feat: type in-page channel functions from protocol

Author: posva

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

@@ -54,30 +54,30 @@ Channel names are namespaced with the devframe id, like RPC ids. Function names
 
 ## The page script endpoint
 
-Functions are defined with `defineChannelFunction` — the same authoring shape as `defineRpcFunction` (`name`, `type`, Standard-Schema `args`/`returns`, `jsonSerializable`, `handler`), narrowed to the browser. Define each side's functions in that side's source files; the shared protocol file carries only types.
+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.
 
 ```ts
 import type { MyChannelProtocol } from '../shared/protocol'
 // inject/index.ts — runs in the user app's page
-import { createPageScriptChannel, defineChannelFunction } from 'devframe/in-page-channel'
+import { createPageScriptChannel } from 'devframe/in-page-channel'
 import { MY_CHANNEL } from '../shared/protocol'
 
 const channel = createPageScriptChannel<MyChannelProtocol>({
   name: MY_CHANNEL,
   functions: [
-    defineChannelFunction({
+    {
       name: 'highlight',
       type: 'event', // fire-and-forget
       jsonSerializable: true,
-      handler: (selector: string) => drawRing(document.querySelector(selector)),
-    }),
-    defineChannelFunction({
+      handler: selector => drawRing(document.querySelector(selector)),
+    },
+    {
       name: 'measure', // request/response (the default `query` type)
-      handler: (selector: string) => {
+      handler: (selector) => {
         const rect = document.querySelector(selector)!.getBoundingClientRect()
         return { width: rect.width, height: rect.height }
       },
-    }),
+    },
   ],
 })
 

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

@@ -1,4 +1,4 @@
-import type { InPageChannelProtocol, PageScriptChannel, PanelChannel } from './types'
+import type { ConnectPanelChannelOptions, CreatePageScriptChannelOptions, InPageChannelProtocol, PageScriptChannel, PanelChannel } from './types'
 import { describe, expect, it, vi } from 'vitest'
 import { defineChannelFunction } from './index'
 import { InPageChannelError } from './internal'
@@ -40,8 +40,8 @@ function until(predicate: () => boolean, timeoutMs = 2000): Promise<void> {
 const noHandshake = { window: false as const, heartbeat: false as const }
 
 function createLinkedPair(options?: {
-  pageScript?: Partial<Parameters<typeof createPageScriptChannel>[0]>
-  panel?: Partial<Parameters<typeof connectPanelChannel>[0]>
+  pageScript?: Partial<CreatePageScriptChannelOptions<TestProtocol>>
+  panel?: Partial<ConnectPanelChannelOptions<TestProtocol>>
 }): { pageScript: PageScriptChannel<TestProtocol>, panel: PanelChannel<TestProtocol>, dispose: () => void } {
   const { port1, port2 } = new MessageChannel()
   const pageScript = createPageScriptChannel<TestProtocol>({

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

@@ -17,6 +17,7 @@ export type {
   InPageChannelProtocol,
   InPageChannelStatus,
   InPageFunctionDefinition,
+  InPageFunctionDefinitionFor,
   PageScriptChannel,
   PanelChannel,
   PanelPeer,
@@ -31,14 +32,37 @@ export type {
  * constant.
  */
 export function defineChannelFunction<
-  NAME extends string,
-  TYPE extends InPageFunctionType,
+  const NAME extends string,
   ARGS extends any[],
   RETURN = void,
-  const AS extends RpcArgsSchema | undefined = undefined,
-  const RS extends RpcReturnSchema | undefined = undefined,
+  TYPE extends InPageFunctionType = 'query',
 >(
-  definition: InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>,
-): InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS> {
+  definition: {
+    name: NAME
+    type?: TYPE
+    args?: undefined
+    returns?: undefined
+    jsonSerializable?: boolean
+    handler: (...args: ARGS) => RETURN
+  },
+): InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN>
+export function defineChannelFunction<
+  const NAME extends string,
+  const AS extends RpcArgsSchema,
+  const RS extends RpcReturnSchema,
+  TYPE extends InPageFunctionType = 'query',
+>(
+  definition: {
+    name: NAME
+    type?: TYPE
+    args: AS
+    returns: RS
+    jsonSerializable?: boolean
+    handler: InPageFunctionDefinition<NAME, TYPE, never, never, AS, RS>['handler']
+  },
+): InPageFunctionDefinition<NAME, TYPE, never, never, AS, RS>
+export function defineChannelFunction(
+  definition: InPageFunctionDefinition<string, InPageFunctionType, any[], any, any, any>,
+): InPageFunctionDefinition<string, InPageFunctionType, any[], any, any, any> {
   return definition
 }

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

@@ -45,7 +45,7 @@ interface PeerInternal<P extends InPageChannelProtocol> {
  * handshake. No server is involved at any point.
  */
 export function createPageScriptChannel<P extends InPageChannelProtocol>(
-  options: CreatePageScriptChannelOptions,
+  options: CreatePageScriptChannelOptions<P>,
 ): PageScriptChannel<P> {
   const { name } = options
   const callTimeoutMs = options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS

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

@@ -45,7 +45,7 @@ const DEFAULT_EVENT_BUFFER_LIMIT = 64
  * the UI can key a fallback state off `status` / `whenConnected()`.
  */
 export function connectPanelChannel<P extends InPageChannelProtocol>(
-  options: ConnectPanelChannelOptions,
+  options: ConnectPanelChannelOptions<P>,
 ): PanelChannel<P> {
   const { name } = options
   const callTimeoutMs = options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS

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

@@ -0,0 +1,79 @@
+import type { InPageChannelProtocol } from './types'
+import { describe, it } from 'vitest'
+import { createPageScriptChannel } from './page-script'
+import { connectPanelChannel } from './panel'
+
+interface TestProtocol extends InPageChannelProtocol {
+  pageScript: {
+    echo: (value: string) => string
+    sum: (a: number, b: number) => number
+    save: (value: string) => Promise<void>
+  }
+  panel: {
+    notify: (message: string) => void
+  }
+}
+
+describe('in-page channel function definitions', () => {
+  it('infers page-script handlers from the protocol name', () => {
+    createPageScriptChannel<TestProtocol>({
+      name: 'devframes:test',
+      functions: [
+        {
+          name: 'echo',
+          handler: value => value.toUpperCase(),
+        },
+        {
+          name: 'sum',
+          handler: (a, b) => a + b,
+        },
+        {
+          name: 'save',
+          handler: () => {},
+        },
+      ],
+    })
+  })
+
+  it('infers panel handlers from the protocol name', () => {
+    const { port1 } = new MessageChannel()
+    const channel = connectPanelChannel<TestProtocol>({
+      name: 'devframes:test',
+      window: false,
+      transport: port1,
+      functions: [{
+        name: 'notify',
+        handler: (message) => {
+          void message
+        },
+      }],
+    })
+    channel.close()
+  })
+
+  it('rejects names from the remote side', () => {
+    createPageScriptChannel<TestProtocol>({
+      name: 'devframes:test',
+      functions: [
+        {
+          // @ts-expect-error `notify` is implemented by panels.
+          name: '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',
+          handler: (value: number) => value,
+        },
+      ],
+    })
+  })
+})

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

@@ -30,6 +30,9 @@ type SharedStates<P extends InPageChannelProtocol>
 
 type FnArgs<F> = F extends (...args: infer A) => any ? A : never
 type FnReturn<F> = F extends (...args: any[]) => infer R ? Awaited<R> : never
+type ProtocolHandler<F> = F extends (...args: any[]) => any
+  ? (...args: FnArgs<F>) => Thenable<FnReturn<F>>
+  : never
 
 /**
  * Types of an in-page channel function — `RpcFunctionType` minus the
@@ -78,6 +81,40 @@ export type InPageFunctionDefinition<
 /** Loosely-typed definition — the registration unit both endpoints accept. */
 export type InPageFunctionDefinitionAny = InPageFunctionDefinition<string, any, any, any, any, any>
 
+type ProtocolSide = 'pageScript' | 'panel'
+type ProtocolSideFunctions<
+  P extends InPageChannelProtocol,
+  SIDE extends ProtocolSide,
+> = SideFunctions<NonNullable<P[SIDE]>>
+
+/**
+ * A function definition constrained by one side of an in-page channel
+ * protocol. The `name` discriminant selects the matching protocol function,
+ * which contextually types the handler's arguments and return value.
+ */
+export type InPageFunctionDefinitionFor<
+  P extends InPageChannelProtocol,
+  SIDE extends ProtocolSide,
+> = {
+  [NAME in keyof ProtocolSideFunctions<P, SIDE> & string]: {
+    name: NAME
+    type?: InPageFunctionType
+    /** Optional Standard Schema array validating the arguments. */
+    args?: RpcArgsSchema
+    /** Optional Standard Schema validating the resolved return value. */
+    returns?: RpcReturnSchema
+    jsonSerializable?: boolean
+    handler: ProtocolHandler<ProtocolSideFunctions<P, SIDE>[NAME]>
+  }
+}[keyof ProtocolSideFunctions<P, SIDE> & string]
+
+type InPageFunctionOption<
+  P extends InPageChannelProtocol,
+  SIDE extends ProtocolSide,
+> = InPageChannelProtocol extends P
+  ? InPageFunctionDefinitionAny
+  : InPageFunctionDefinitionFor<P, SIDE>
+
 /**
  * Connection lifecycle of a panel endpoint: `connecting` (handshake retry
  * loop running, outgoing traffic buffered) → `connected` → back to
@@ -91,8 +128,6 @@ interface InPageChannelCommonOptions {
    * (e.g. `devframes:plugin:a11y`). Both endpoints must use the same name.
    */
   name: string
-  /** Implementations of this endpoint's side of the protocol. */
-  functions?: readonly InPageFunctionDefinitionAny[]
   /**
    * Origins accepted during the handshake (and used as `targetOrigin` when
    * posting handshake messages). The in-page channel is same-origin by
@@ -123,7 +158,9 @@ interface InPageChannelCommonOptions {
 }
 
 /** Options for {@link createPageScriptChannel}. */
-export interface CreatePageScriptChannelOptions extends InPageChannelCommonOptions {
+export interface CreatePageScriptChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
+  /** Implementations of the protocol's page-script functions. */
+  functions?: readonly InPageFunctionOption<Protocol, 'pageScript'>[]
   /**
    * Window whose `message` events carry panel hellos. Defaults to the
    * global `window`; pass `false` to skip the handshake listener entirely
@@ -133,7 +170,9 @@ export interface CreatePageScriptChannelOptions extends InPageChannelCommonOptio
 }
 
 /** Options for {@link connectPanelChannel}. */
-export interface ConnectPanelChannelOptions extends InPageChannelCommonOptions {
+export interface ConnectPanelChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
+  /** Implementations of the protocol's panel functions. */
+  functions?: readonly InPageFunctionOption<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.

packages/devframe/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config'
+import { alias } from '../../alias'
+
+export default defineConfig({
+  resolve: { alias },
+  test: {
+    name: 'devframe',
+    testTimeout: 10_000,
+    typecheck: {
+      enabled: true,
+      tsconfig: './tsconfig.json',
+    },
+  },
+})