refactor: require in-page channel function maps

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 shape as `defineRpcFunction` (`name`, `type`, Standard-Schema `args`/`returns`, `jsonSerializable`, `handler`), narrowed to the browser. Each inline definition is contextually typed from its `name` and the corresponding function in the protocol. `defineChannelFunction` provides the same shape when defining a function outside an endpoint's options. 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 `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.
 
 ```ts
 import type { MyChannelProtocol } from '../shared/protocol'
@@ -64,21 +64,19 @@ import { MY_CHANNEL } from '../shared/protocol'
 
 const channel = createPageScriptChannel<MyChannelProtocol>({
   name: MY_CHANNEL,
-  functions: [
-    {
-      name: 'highlight',
+  functions: {
+    highlight: {
       type: 'event', // fire-and-forget
       jsonSerializable: true,
       handler: selector => drawRing(document.querySelector(selector)),
     },
-    {
-      name: 'measure', // request/response (the default `query` type)
+    measure: { // request/response (the default `query` type)
       handler: (selector) => {
         const rect = document.querySelector(selector)!.getBoundingClientRect()
         return { width: rect.width, height: rect.height }
       },
     },
-  ],
+  },
 })
 
 channel.callEvent('flash', 'scanning…') // fans out to every connected panel

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

@@ -1,6 +1,5 @@
 import type { ConnectPanelChannelOptions, CreatePageScriptChannelOptions, InPageChannelProtocol, PageScriptChannel, PanelChannel } from './types'
 import { describe, expect, it, vi } from 'vitest'
-import { defineChannelFunction } from './index'
 import { InPageChannelError } from './internal'
 import { createPageScriptChannel } from './page-script'
 import { connectPanelChannel } from './panel'
@@ -39,6 +38,19 @@ function until(predicate: () => boolean, timeoutMs = 2000): Promise<void> {
 
 const noHandshake = { window: false as const, heartbeat: false as const }
 
+const defaultPageScriptFunctions: NonNullable<CreatePageScriptChannelOptions<TestProtocol>['functions']> = {
+  echo: { handler: value => value },
+  sum: { handler: (a, b) => a + b },
+  boom: { handler: () => {} },
+  strict: { handler: payload => payload },
+  note: { type: 'event', handler: () => {} },
+}
+
+const defaultPanelFunctions: NonNullable<ConnectPanelChannelOptions<TestProtocol>['functions']> = {
+  'ping-panel': { handler: value => `pong:${value}` },
+  'notify': { type: 'event', handler: () => {} },
+}
+
 function createLinkedPair(options?: {
   pageScript?: Partial<CreatePageScriptChannelOptions<TestProtocol>>
   panel?: Partial<ConnectPanelChannelOptions<TestProtocol>>
@@ -47,14 +59,13 @@ function createLinkedPair(options?: {
   const pageScript = createPageScriptChannel<TestProtocol>({
     name: 'devframes:test',
     ...noHandshake,
-    functions: [
-      defineChannelFunction({ name: 'echo', handler: (value: string) => value }),
-      defineChannelFunction({ name: 'sum', type: 'query', handler: (a: number, b: number) => a + b }),
-      defineChannelFunction({ name: 'boom', handler: () => {
+    functions: {
+      ...defaultPageScriptFunctions,
+      boom: { handler: () => {
         throw new Error('exploded')
-      } }),
-      defineChannelFunction({ name: 'strict', jsonSerializable: true, handler: (payload: unknown) => payload }),
-    ],
+      } },
+      strict: { jsonSerializable: true, handler: payload => payload },
+    },
     ...options?.pageScript,
   })
   pageScript.addPanelPort(port1)
@@ -142,14 +153,14 @@ describe('in-page channel over bring-your-own ports', () => {
     const pageScript = createPageScriptChannel<TestProtocol>({
       name: 'devframes:test',
       ...noHandshake,
-      functions: [
-        defineChannelFunction({
-          name: 'note',
+      functions: {
+        ...defaultPageScriptFunctions,
+        note: {
           args: [s.string()] as const,
           returns: s.void(),
           handler: () => {},
-        }),
-      ],
+        },
+      },
     })
     pageScript.addPanelPort(port1)
     const panel = connectPanelChannel<TestProtocol>({
@@ -182,11 +193,12 @@ describe('in-page channel over bring-your-own ports', () => {
       name: 'devframes:test',
       ...noHandshake,
       transport: a.port2,
-      functions: [
-        defineChannelFunction({ name: 'notify', type: 'event', handler: (value: string) => {
+      functions: {
+        ...defaultPanelFunctions,
+        notify: { type: 'event', handler: (value) => {
           received.push(`a:${value}`)
-        } }),
-      ],
+        } },
+      },
     })
     // Panel B deliberately implements nothing.
     const panelB = connectPanelChannel<TestProtocol>({
@@ -218,9 +230,7 @@ describe('in-page channel over bring-your-own ports', () => {
       name: 'devframes:test',
       ...noHandshake,
       transport: port2,
-      functions: [
-        defineChannelFunction({ name: 'ping-panel', handler: (value: string) => `pong:${value}` }),
-      ],
+      functions: defaultPanelFunctions,
     })
     try {
       const peer = pageScript.panels[0]!
@@ -237,9 +247,7 @@ describe('in-page channel over bring-your-own ports', () => {
     const pageScript = createPageScriptChannel<TestProtocol>({
       name: 'devframes:test',
       ...noHandshake,
-      functions: [
-        defineChannelFunction({ name: 'echo', handler: (value: any) => value }),
-      ],
+      functions: defaultPageScriptFunctions,
     })
     pageScript.addPanelPort(port1)
     const panel = connectPanelChannel<TestProtocol>({
@@ -443,7 +451,7 @@ describe('in-page channel handshake', () => {
       name: 'devframes:test',
       window: hostWin as unknown as Window,
       heartbeat: false,
-      functions: [defineChannelFunction({ name: 'echo', handler: (value: string) => value })],
+      functions: defaultPageScriptFunctions,
     })
     const panel = connectPanelChannel<TestProtocol>({
       name: 'devframes:test',
@@ -465,7 +473,10 @@ describe('in-page channel handshake', () => {
         name: 'devframes:test',
         window: hostWin as unknown as Window,
         heartbeat: false,
-        functions: [defineChannelFunction({ name: 'echo', handler: (value: string) => `revived:${value}` })],
+        functions: {
+          ...defaultPageScriptFunctions,
+          echo: { handler: value => `revived:${value}` },
+        },
       })
       try {
         await panel.whenConnected(2000)
@@ -497,12 +508,12 @@ describe('in-page channel handshake', () => {
       name: 'devframes:test',
       window: hostWin as unknown as Window,
       heartbeat: false,
-      functions: [
-        defineChannelFunction({ name: 'echo', handler: (value: string) => value }),
-        defineChannelFunction({ name: 'note', type: 'event', handler: (value: string) => {
+      functions: {
+        ...defaultPageScriptFunctions,
+        note: { type: 'event', handler: (value) => {
           noted.push(value)
-        } }),
-      ],
+        } },
+      },
     })
     try {
       await expect(early).resolves.toBe('early')

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

@@ -63,8 +63,8 @@ export function createPageScriptChannel<P extends InPageChannelProtocol>(
   let heartbeatTimer: ReturnType<typeof setInterval> | undefined
 
   const registry = createLocalFunctionRegistry(codec)
-  for (const definition of options.functions ?? [])
-    registry.register(definition)
+  for (const [fnName, definition] of Object.entries(options.functions ?? {}))
+    registry.register({ ...definition, name: fnName })
 
   const stateHost = createPageScriptStateHost<P>(function* () {
     for (const peer of peers.values()) {

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

@@ -62,8 +62,8 @@ export function connectPanelChannel<P extends InPageChannelProtocol>(
 
   const events = createEventEmitter<PanelChannelEvents>()
   const registry = createLocalFunctionRegistry(codec)
-  for (const definition of options.functions ?? [])
-    registry.register(definition)
+  for (const [fnName, definition] of Object.entries(options.functions ?? {}))
+    registry.register({ ...definition, name: fnName })
 
   let status: InPageChannelStatus = 'connecting'
   let attached: AttachedChannelPort | undefined

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

@@ -18,20 +18,17 @@ describe('in-page channel function definitions', () => {
   it('infers page-script handlers from the protocol name', () => {
     createPageScriptChannel<TestProtocol>({
       name: 'devframes:test',
-      functions: [
-        {
-          name: 'echo',
+      functions: {
+        echo: {
           handler: value => value.toUpperCase(),
         },
-        {
-          name: 'sum',
+        sum: {
           handler: (a, b) => a + b,
         },
-        {
-          name: 'save',
+        save: {
           handler: () => {},
         },
-      ],
+      },
     })
   })
 
@@ -41,39 +38,51 @@ describe('in-page channel function definitions', () => {
       name: 'devframes:test',
       window: false,
       transport: port1,
-      functions: [{
-        name: 'notify',
-        handler: (message) => {
-          void message
+      functions: {
+        notify: {
+          handler: (message) => {
+            void message
+          },
         },
-      }],
+      },
     })
     channel.close()
   })
 
-  it('rejects names from the remote side', () => {
+  it('requires every function from the local protocol side', () => {
     createPageScriptChannel<TestProtocol>({
       name: 'devframes:test',
-      functions: [
-        {
-          // @ts-expect-error `notify` is implemented by panels.
-          name: 'notify',
-          handler: (message: string) => void message,
-        },
-      ],
+      // @ts-expect-error `sum` and `save` are required.
+      functions: {
+        echo: { handler: value => value },
+      },
+    })
+  })
+
+  it('rejects keys from the remote side', () => {
+    createPageScriptChannel<TestProtocol>({
+      name: 'devframes:test',
+      functions: {
+        echo: { handler: value => value },
+        sum: { handler: (a, b) => a + b },
+        save: { handler: () => {} },
+        // @ts-expect-error `notify` is implemented by panels.
+        notify: { handler: (message: string) => void message },
+      },
     })
   })
 
   it('rejects handlers incompatible with the named protocol function', () => {
     createPageScriptChannel<TestProtocol>({
       name: 'devframes:test',
-      functions: [
-        // @ts-expect-error `echo` accepts and returns a string.
-        {
-          name: 'echo',
+      functions: {
+        echo: {
+          // @ts-expect-error `echo` accepts and returns a string.
           handler: (value: number) => value,
         },
-      ],
+        sum: { handler: (a, b) => a + b },
+        save: { handler: () => {} },
+      },
     })
   })
 })

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

@@ -108,12 +108,17 @@ export type InPageFunctionDefinitionFor<
   }
 }[keyof ProtocolSideFunctions<P, SIDE> & string]
 
-type InPageFunctionOption<
+type InPageFunctionOptions<
   P extends InPageChannelProtocol,
   SIDE extends ProtocolSide,
 > = InPageChannelProtocol extends P
-  ? InPageFunctionDefinitionAny
-  : InPageFunctionDefinitionFor<P, SIDE>
+  ? Record<string, Omit<InPageFunctionDefinitionAny, 'name'>>
+  : {
+      [NAME in keyof ProtocolSideFunctions<P, SIDE> & string]: Omit<
+        Extract<InPageFunctionDefinitionFor<P, SIDE>, { name: NAME }>,
+        'name'
+      >
+    }
 
 /**
  * Connection lifecycle of a panel endpoint: `connecting` (handshake retry
@@ -160,7 +165,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?: readonly InPageFunctionOption<Protocol, 'pageScript'>[]
+  functions?: InPageFunctionOptions<Protocol, 'pageScript'>
   /**
    * Window whose `message` events carry panel hellos. Defaults to the
    * global `window`; pass `false` to skip the handshake listener entirely
@@ -172,7 +177,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?: readonly InPageFunctionOption<Protocol, 'panel'>[]
+  functions?: InPageFunctionOptions<Protocol, 'panel'>
   /**
    * The panel's own window (listens for the handshake grant). Defaults to
    * the global `window`; pass `false` with `transport` to skip the handshake.