refactor: require in-page channel functions

Author: posva

docs/content/1.guide/12.in-page-channel.md

@@ -54,7 +54,7 @@ Channel names are namespaced with the devframe id, like RPC ids. Function names
 
 ## The page script endpoint
 
-Functions use the same authoring metadata as `defineRpcFunction` (`type`, Standard-Schema `args`/`returns`, `jsonSerializable`, `handler`), narrowed to the browser. The `functions` object's keys are the function names, and every function on that endpoint's protocol side is required when the object is provided. Each handler is contextually typed from its key and the corresponding function in the protocol. `defineChannelFunction` retains the named definition shape for lower-level authoring. Define each side's functions in that side's source files; the shared protocol file carries only types.
+Functions use the same authoring metadata as `defineRpcFunction` (`type`, Standard-Schema `args`/`returns`, `jsonSerializable`, `handler`), narrowed to the browser. The required `functions` object's keys are the function names, and it implements every function on that endpoint's protocol side. Each handler is contextually typed from its key and the corresponding function in the protocol. `defineChannelFunction` retains the named definition shape for lower-level authoring. Define each side's functions in that side's source files; the shared protocol file carries only types.
 
 ```ts
 import type { MyChannelProtocol } from '../shared/protocol'
@@ -94,7 +94,14 @@ import type { MyChannelProtocol } from '../shared/protocol'
 import { connectPanelChannel } from 'devframe/in-page-channel'
 import { MY_CHANNEL } from '../shared/protocol'
 
-const channel = connectPanelChannel<MyChannelProtocol>({ name: MY_CHANNEL })
+const channel = connectPanelChannel<MyChannelProtocol>({
+  name: MY_CHANNEL,
+  functions: {
+    flash: {
+      handler: message => showFlash(message),
+    },
+  },
+})
 
 channel.callEvent('highlight', '.hero') // buffered until connected
 const size = await channel.call('measure', '.hero')

packages/devframe/src/in-page-channel/in-page-channel.test.ts

@@ -73,6 +73,7 @@ function createLinkedPair(options?: {
     name: 'devframes:test',
     ...noHandshake,
     transport: port2,
+    functions: defaultPanelFunctions,
     ...options?.panel,
   })
   return {
@@ -167,6 +168,7 @@ describe('in-page channel over bring-your-own ports', () => {
       name: 'devframes:test',
       ...noHandshake,
       transport: port2,
+      functions: defaultPanelFunctions,
     })
     try {
       await expect(panel.call('note', 'fine')).resolves.toBeUndefined()
@@ -185,6 +187,7 @@ describe('in-page channel over bring-your-own ports', () => {
     const pageScript = createPageScriptChannel<TestProtocol>({
       name: 'devframes:test',
       ...noHandshake,
+      functions: defaultPageScriptFunctions,
     })
     pageScript.addPanelPort(a.port1)
     pageScript.addPanelPort(b.port1)
@@ -200,11 +203,12 @@ describe('in-page channel over bring-your-own ports', () => {
         } },
       },
     })
-    // Panel B deliberately implements nothing.
-    const panelB = connectPanelChannel<TestProtocol>({
+    // Panel B deliberately has no local functions in its protocol.
+    const panelB = connectPanelChannel<InPageChannelProtocol>({
       name: 'devframes:test',
       ...noHandshake,
       transport: b.port2,
+      functions: {},
     })
     try {
       expect(pageScript.panels).toHaveLength(2)
@@ -224,6 +228,7 @@ describe('in-page channel over bring-your-own ports', () => {
     const pageScript = createPageScriptChannel<TestProtocol>({
       name: 'devframes:test',
       ...noHandshake,
+      functions: defaultPageScriptFunctions,
     })
     pageScript.addPanelPort(port1)
     const panel = connectPanelChannel<TestProtocol>({
@@ -254,6 +259,7 @@ describe('in-page channel over bring-your-own ports', () => {
       name: 'devframes:test',
       ...noHandshake,
       transport: port2,
+      functions: defaultPanelFunctions,
       // Unwrap a fake reactivity wrapper on the way out, tag on the way in.
       serialize: value => (value && typeof value === 'object' && '__wrapped' in (value as any))
         ? (value as any).__wrapped
@@ -274,6 +280,7 @@ describe('in-page channel over bring-your-own ports', () => {
     const pageScript = createPageScriptChannel<TestProtocol>({
       name: 'devframes:test',
       ...noHandshake,
+      functions: defaultPageScriptFunctions,
     })
     const connected: string[] = []
     const disconnected: string[] = []
@@ -284,6 +291,7 @@ describe('in-page channel over bring-your-own ports', () => {
       name: 'devframes:test',
       ...noHandshake,
       transport: port2,
+      functions: defaultPanelFunctions,
     })
     try {
       expect(connected).toHaveLength(1)
@@ -324,11 +332,12 @@ describe('in-page channel shared state', () => {
     const pageScript = createPageScriptChannel<TestProtocol>({
       name: 'devframes:test',
       ...noHandshake,
+      functions: defaultPageScriptFunctions,
     })
     pageScript.addPanelPort(a.port1)
     pageScript.addPanelPort(b.port1)
-    const panelA = connectPanelChannel<TestProtocol>({ name: 'devframes:test', ...noHandshake, transport: a.port2 })
-    const panelB = connectPanelChannel<TestProtocol>({ name: 'devframes:test', ...noHandshake, transport: b.port2 })
+    const panelA = connectPanelChannel<TestProtocol>({ name: 'devframes:test', ...noHandshake, transport: a.port2, functions: defaultPanelFunctions })
+    const panelB = connectPanelChannel<TestProtocol>({ name: 'devframes:test', ...noHandshake, transport: b.port2, functions: defaultPanelFunctions })
     try {
       const authority = await pageScript.sharedState.get('doc', { initialValue: { count: 0 } })
       const mirrorA = await panelA.sharedState.get('doc')
@@ -349,7 +358,7 @@ describe('in-page channel shared state', () => {
 
   it('seeds a late-joining panel with the current value', async () => {
     const { port1, port2 } = new MessageChannel()
-    const pageScript = createPageScriptChannel<TestProtocol>({ name: 'devframes:test', ...noHandshake })
+    const pageScript = createPageScriptChannel<TestProtocol>({ name: 'devframes:test', ...noHandshake, functions: defaultPageScriptFunctions })
     const authority = await pageScript.sharedState.get('doc', { initialValue: { count: 0 } })
     authority.mutate((draft) => {
       draft.count = 41
@@ -359,7 +368,7 @@ describe('in-page channel shared state', () => {
     })
 
     pageScript.addPanelPort(port1)
-    const panel = connectPanelChannel<TestProtocol>({ name: 'devframes:test', ...noHandshake, transport: port2 })
+    const panel = connectPanelChannel<TestProtocol>({ name: 'devframes:test', ...noHandshake, transport: port2, functions: defaultPanelFunctions })
     try {
       const mirror = await panel.sharedState.get('doc')
       expect(mirror.value()).toEqual({ count: 42 })
@@ -458,6 +467,7 @@ describe('in-page channel handshake', () => {
       window: panelWin as unknown as Window,
       targets: [hostWin as unknown as Window],
       ...fastHello,
+      functions: defaultPanelFunctions,
     })
     try {
       await panel.whenConnected(2000)
@@ -500,6 +510,7 @@ describe('in-page channel handshake', () => {
       window: panelWin as unknown as Window,
       targets: [hostWin as unknown as Window],
       ...fastHello,
+      functions: defaultPanelFunctions,
     })
     const early = panel.call('echo', 'early')
     panel.callEvent('note', 'buffered')
@@ -533,6 +544,7 @@ describe('in-page channel handshake', () => {
       name: 'devframes:test-origin',
       window: hostWin as unknown as Window,
       heartbeat: false,
+      functions: defaultPageScriptFunctions,
     })
     try {
       hostWin.__dispatch({
@@ -563,6 +575,7 @@ describe('in-page channel handshake', () => {
       name: 'devframes:test-version',
       window: hostWin as unknown as Window,
       heartbeat: false,
+      functions: defaultPageScriptFunctions,
     })
     try {
       hostWin.__dispatch({
@@ -592,13 +605,15 @@ describe('in-page channel handshake', () => {
       name: 'devframes:test',
       window: hostWin as unknown as Window,
       heartbeat: false,
+      functions: defaultPageScriptFunctions,
     })
     const pinnedElsewhere = connectPanelChannel<TestProtocol>({
       name: 'devframes:test',
       window: panelWin as unknown as Window,
       targets: [hostWin as unknown as Window],
       instanceId: 'some-other-tab',
       ...fastHello,
+      functions: defaultPanelFunctions,
     })
     try {
       await expect(pinnedElsewhere.whenConnected(100)).rejects.toMatchObject({ code: 'timeout' })
@@ -609,6 +624,7 @@ describe('in-page channel handshake', () => {
         targets: [hostWin as unknown as Window],
         instanceId: pageScript.instanceId,
         ...fastHello,
+        functions: defaultPanelFunctions,
       })
       try {
         await pinnedHere.whenConnected(2000)
@@ -629,6 +645,7 @@ describe('in-page channel handshake', () => {
       name: `devframes:test-lonely-${Math.random()}`,
       window: false,
       heartbeat: false,
+      functions: defaultPanelFunctions,
     })
     try {
       expect(lonely.status).toBe('connecting')
@@ -647,6 +664,7 @@ describe('in-page channel handshake', () => {
       window: false,
       heartbeat: false,
       callTimeoutMs: 50,
+      functions: defaultPanelFunctions,
     })
     try {
       const rejection = await lonely.call('echo', 'nobody').catch(error => error)
@@ -664,6 +682,7 @@ describe('in-page channel handshake', () => {
       name: `devframes:test-lonely-${Math.random()}`,
       window: false,
       heartbeat: false,
+      functions: defaultPanelFunctions,
     })
     const pending = lonely.call('echo', 'never')
     const waiting = lonely.whenConnected()

packages/devframe/src/in-page-channel/types.test-d.ts

@@ -59,6 +59,11 @@ describe('in-page channel function definitions', () => {
   })
 
   it('requires every function from the local protocol side', () => {
+    // @ts-expect-error `functions` is required.
+    createPageScriptChannel<TestProtocol>({ name: 'devframes:test' })
+    // @ts-expect-error `functions` is required.
+    connectPanelChannel<TestProtocol>({ name: 'devframes:test' })
+
     createPageScriptChannel<TestProtocol>({
       name: 'devframes:test',
       // @ts-expect-error `sum` and `save` are required.
@@ -97,9 +102,16 @@ describe('in-page channel function definitions', () => {
 })
 
 describe('page-script channel types', () => {
-  it('types calls to panel functions', () => {
-    const channel = createPageScriptChannel<TestProtocol>({ name: 'devframes:test' })
+  const channel = createPageScriptChannel<TestProtocol>({
+    name: 'devframes:test',
+    functions: {
+      echo: { handler: value => value },
+      sum: { handler: (a, b) => a + b },
+      save: { handler: () => {} },
+    },
+  })
 
+  it('types calls to panel functions', () => {
     expectTypeOf(channel.callEvent('notify', 'ready')).toEqualTypeOf<void>()
 
     // @ts-expect-error Page-script functions cannot be called on panels.
@@ -113,7 +125,6 @@ describe('page-script channel types', () => {
   })
 
   it('types connected panel peers and their calls', () => {
-    const channel = createPageScriptChannel<TestProtocol>({ name: 'devframes:test' })
     const unsubscribe = channel.events.on('panel:connected', (panel) => {
       expectTypeOf(panel.id).toEqualTypeOf<string>()
       expectTypeOf(panel.call('notify', 'ready')).toEqualTypeOf<Promise<void>>()
@@ -129,7 +140,6 @@ describe('page-script channel types', () => {
   })
 
   it('types disconnected panel peers and one-time listeners', () => {
-    const channel = createPageScriptChannel<TestProtocol>({ name: 'devframes:test' })
     const unsubscribe = channel.events.once('panel:disconnected', (panel) => {
       expectTypeOf(panel.id).toEqualTypeOf<string>()
       expectTypeOf(panel.call('notify', 'bye')).toEqualTypeOf<Promise<void>>()
@@ -143,9 +153,14 @@ describe('page-script channel types', () => {
 })
 
 describe('panel channel types', () => {
-  it('types calls and their resolved results', () => {
-    const channel = connectPanelChannel<TestProtocol>({ name: 'devframes:test' })
+  const channel = connectPanelChannel<TestProtocol>({
+    name: 'devframes:test',
+    functions: {
+      notify: { handler: () => {} },
+    },
+  })
 
+  it('types calls and their resolved results', () => {
     expectTypeOf(channel.call('echo', 'hello')).toEqualTypeOf<Promise<string>>()
     expectTypeOf(channel.call('sum', 1, 2)).toEqualTypeOf<Promise<number>>()
     expectTypeOf(channel.call('save', 'draft')).toEqualTypeOf<Promise<void>>()
@@ -161,8 +176,6 @@ describe('panel channel types', () => {
   })
 
   it('types fire-and-forget calls to page-script functions', () => {
-    const channel = connectPanelChannel<TestProtocol>({ name: 'devframes:test' })
-
     expectTypeOf(channel.callEvent('echo', 'hello')).toEqualTypeOf<void>()
     expectTypeOf(channel.callEvent('sum', 1, 2)).toEqualTypeOf<void>()
     expectTypeOf(channel.callEvent('save', 'draft')).toEqualTypeOf<void>()
@@ -176,7 +189,6 @@ describe('panel channel types', () => {
   })
 
   it('types status listeners and channel state', () => {
-    const channel = connectPanelChannel<TestProtocol>({ name: 'devframes:test' })
     const unsubscribe = channel.events.on('status:updated', (status) => {
       expectTypeOf(status).toEqualTypeOf<'connecting' | 'connected' | 'closed'>()
     })

packages/devframe/src/in-page-channel/types.ts

@@ -174,7 +174,7 @@ interface InPageChannelCommonOptions {
 /** Options for {@link createPageScriptChannel}. */
 export interface CreatePageScriptChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
   /** Implementations of the protocol's page-script functions. */
-  functions?: CreatePageScriptChannelOptionsFunctions<Protocol>
+  functions: CreatePageScriptChannelOptionsFunctions<Protocol>
   /**
    * Window whose `message` events carry panel hellos. Defaults to the
    * global `window`; pass `false` to skip the handshake listener entirely
@@ -186,7 +186,7 @@ export interface CreatePageScriptChannelOptions<Protocol extends InPageChannelPr
 /** Options for {@link connectPanelChannel}. */
 export interface ConnectPanelChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
   /** Implementations of the protocol's panel functions. */
-  functions?: ConnectPanelChannelOptionsFunctions<Protocol>
+  functions: ConnectPanelChannelOptionsFunctions<Protocol>
   /**
    * The panel's own window (listens for the handshake grant). Defaults to
    * the global `window`; pass `false` with `transport` to skip the handshake.

plugins/a11y/src/spa/lib/channel.ts

@@ -49,7 +49,10 @@ export function createA11yChannel(): A11yChannel {
   // authoritative flag inside `A11yState` takes over on the next update.
   const [localScanning, setLocalScanning] = createSignal(false)
 
-  const channel = connectPanelChannel<A11yChannelProtocol>({ name: A11Y_CHANNEL })
+  const channel = connectPanelChannel<A11yChannelProtocol>({
+    name: A11Y_CHANNEL,
+    functions: {},
+  })
   channel.events.on('status:updated', status => setPageScriptReady(status === 'connected'))
 
   void channel.sharedState.get('state').then((shared) => {