fix: preserve required in-page function declarations

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
 
-Request/response functions use the same authoring metadata as `defineRpcFunction` (`type`, Standard-Schema `args`/`returns`, `jsonSerializable`, `handler`), narrowed to the browser. The optional `functions` object registers initial handlers, while `channel.on()` subscribes event listeners at runtime. 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.
+The required `functions` object declares every function on that endpoint's protocol side, preserving a compile-time completeness check. Request/response declarations require a `handler`; an event declaration uses `type: 'event'` and may receive events through either its optional `handler` or runtime `channel.on()` listeners. Functions use the same Standard-Schema `args`/`returns` and `jsonSerializable` metadata as `defineRpcFunction`, narrowed to the browser. Each handler is contextually typed from its key and the corresponding protocol function. `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'
@@ -96,6 +96,9 @@ import { MY_CHANNEL } from '../shared/protocol'
 
 const channel = connectPanelChannel<MyChannelProtocol>({
   name: MY_CHANNEL,
+  functions: {
+    flash: { type: 'event' },
+  },
 })
 
 const offFlash = channel.on('flash', message => showFlash(message))

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

@@ -43,12 +43,12 @@ const defaultPageScriptFunctions: NonNullable<CreatePageScriptChannelOptions<Tes
   sum: { handler: (a, b) => a + b },
   boom: { handler: () => {} },
   strict: { handler: payload => payload },
-  note: { type: 'event', handler: () => {} },
+  note: { type: 'event' },
 }
 
 const defaultPanelFunctions: NonNullable<ConnectPanelChannelOptions<TestProtocol>['functions']> = {
   'ping-panel': { handler: value => `pong:${value}` },
-  'notify': { type: 'event', handler: () => {} },
+  'notify': { type: 'event' },
 }
 
 function createLinkedPair(options?: {
@@ -196,9 +196,7 @@ describe('in-page channel over bring-your-own ports', () => {
       name: 'devframes:test',
       ...noHandshake,
       transport: a.port2,
-      functions: {
-        'ping-panel': defaultPanelFunctions['ping-panel'],
-      },
+      functions: defaultPanelFunctions,
     })
     pageScript.emit('notify', 'before-listener')
     await new Promise(resolve => setTimeout(resolve, 20))
@@ -209,6 +207,7 @@ describe('in-page channel over bring-your-own ports', () => {
       name: 'devframes:test',
       ...noHandshake,
       transport: b.port2,
+      functions: {},
     })
     try {
       expect(pageScript.panels).toHaveLength(2)

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

@@ -33,7 +33,7 @@ export type {
 export function defineChannelFunction<
   NAME extends string,
   TYPE extends InPageFunctionType,
-  ARGS extends any[],
+  ARGS extends any[] = [],
   RETURN = void,
   const AS extends RpcArgsSchema | undefined = undefined,
   const RS extends RpcReturnSchema | undefined = undefined,

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

@@ -199,7 +199,7 @@ export function createLocalFunctionRegistry(codec: InPageChannelSerialization):
           assertJsonSerializable(args, 'its arguments', definition.name)
         if (definition?.args?.length)
           await validateArgs(definition.name, definition.args, args)
-        const result = await definition?.handler(...args)
+        const result = await definition?.handler?.(...args)
         for (const listener of [...(listeners.get(name) ?? [])])
           listener(...args)
         if (definition?.jsonSerializable)

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

@@ -63,10 +63,8 @@ export function createPageScriptChannel<P extends InPageChannelProtocol>(
   let heartbeatTimer: ReturnType<typeof setInterval> | undefined
 
   const registry = createLocalFunctionRegistry(codec)
-  for (const [fnName, definition] of Object.entries(options.functions ?? {})) {
-    if (definition)
-      registry.register({ ...definition, name: fnName })
-  }
+  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,10 +62,8 @@ export function connectPanelChannel<P extends InPageChannelProtocol>(
 
   const events = createEventEmitter<PanelChannelEvents>()
   const registry = createLocalFunctionRegistry(codec)
-  for (const [fnName, definition] of Object.entries(options.functions ?? {})) {
-    if (definition)
-      registry.register({ ...definition, name: fnName })
-  }
+  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

@@ -1,4 +1,5 @@
 import { describe, expectTypeOf, it } from 'vitest'
+import { defineChannelFunction } from './index'
 import { createPageScriptChannel } from './page-script'
 import { connectPanelChannel } from './panel'
 
@@ -20,6 +21,19 @@ interface PageScriptOnlyProtocol {
   panel: Record<string, never>
 }
 
+describe('Channel function definitions', () => {
+  it('allows events without handlers', () => {
+    defineChannelFunction({ name: 'notify', type: 'event' })
+  })
+
+  it('requires handlers for request/response functions', () => {
+    // @ts-expect-error Query functions require a handler.
+    defineChannelFunction({ name: 'load', type: 'query' })
+    // @ts-expect-error Action functions require a handler.
+    defineChannelFunction({ name: 'save', type: 'action' })
+  })
+})
+
 describe('In-page script channel', () => {
   const channel = createPageScriptChannel<TestProtocol>({
     name: 'devframes:test',
@@ -57,17 +71,40 @@ describe('In-page script channel', () => {
       })
     })
 
-    it('accepts runtime-only and partial function implementations', () => {
+    it('requires every page-script function declaration', () => {
+      // @ts-expect-error `functions` is required.
       createPageScriptChannel<TestProtocol>({ name: 'devframes:test' })
 
       createPageScriptChannel<TestProtocol>({
         name: 'devframes:test',
+        // @ts-expect-error `sum` and `save` must be declared.
         functions: {
           echo: { handler: value => value },
         },
       })
     })
 
+    it('allows event declarations to omit their handler', () => {
+      createPageScriptChannel<TestProtocol>({
+        name: 'devframes:test',
+        functions: {
+          echo: { handler: value => value },
+          sum: { handler: (a, b) => a + b },
+          save: { type: 'event' },
+        },
+      })
+
+      createPageScriptChannel<TestProtocol>({
+        name: 'devframes:test',
+        functions: {
+          // @ts-expect-error Request/response functions require a handler.
+          echo: { type: 'query' },
+          sum: { handler: (a, b) => a + b },
+          save: { type: 'event' },
+        },
+      })
+    })
+
     it('rejects panel functions', () => {
       createPageScriptChannel<TestProtocol>({
         name: 'devframes:test',
@@ -195,15 +232,34 @@ describe('Panel channel', () => {
       inferredChannel.close()
     })
 
-    it('accepts runtime-only and partial function implementations', () => {
+    it('requires every panel function declaration', () => {
+      // @ts-expect-error `functions` is required.
       connectPanelChannel<TestProtocol>({ name: 'devframes:test' })
 
       connectPanelChannel<TestProtocol>({
         name: 'devframes:test',
+        // @ts-expect-error `notify` must be declared.
         functions: {},
       })
     })
 
+    it('allows event declarations to omit their handler', () => {
+      connectPanelChannel<TestProtocol>({
+        name: 'devframes:test',
+        functions: {
+          notify: { type: 'event' },
+        },
+      })
+
+      connectPanelChannel<TestProtocol>({
+        name: 'devframes:test',
+        functions: {
+          // @ts-expect-error Request/response functions require a handler.
+          notify: { type: 'action' },
+        },
+      })
+    })
+
     it('rejects in-page script functions', () => {
       connectPanelChannel<TestProtocol>({
         name: 'devframes:test',

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

@@ -54,7 +54,8 @@ export type InPageFunctionType = 'action' | 'event' | 'query'
  * `dump`/`snapshot`/`cacheable`/`agent`. When `jsonSerializable` is `true`,
  * payloads are strictly validated at the receiving endpoint and misshapen
  * values reject the call with a descriptive `InPageChannelError` instead of
- * a cryptic `DataCloneError` in the port.
+ * a cryptic `DataCloneError` in the port. Event definitions may omit their
+ * handler when runtime listeners subscribe through `channel.on()`.
  */
 export type InPageFunctionDefinition<
   NAME extends string,
@@ -65,24 +66,26 @@ export type InPageFunctionDefinition<
   RS extends RpcReturnSchema | undefined = undefined,
 >
   = [AS, RS] extends [undefined, undefined]
-    ? {
+    ? ({
         name: NAME
         type?: TYPE
         args?: AS
         returns?: RS
         jsonSerializable?: boolean
-        handler: (...args: ARGS) => RETURN
-      }
-    : {
+      } & (TYPE extends 'event'
+        ? { handler?: (...args: ARGS) => RETURN }
+        : { handler: (...args: ARGS) => RETURN }))
+    : ({
         name: NAME
         type?: TYPE
         /** Standard Schema array validating (and typing) the arguments. */
         args: AS
         /** Standard Schema typing the resolved return value. */
         returns: RS
         jsonSerializable?: boolean
-        handler: (...args: InferArgsType<AS>) => Thenable<InferReturnType<RS>>
-      }
+      } & (TYPE extends 'event'
+        ? { handler?: (...args: InferArgsType<AS>) => Thenable<InferReturnType<RS>> }
+        : { handler: (...args: InferArgsType<AS>) => Thenable<InferReturnType<RS>> }))
 
 /**
  * Loosely-typed definition used by the internal function registry.
@@ -96,33 +99,41 @@ export type InPageFunctionDefinitionAny = InPageFunctionDefinition<string, any,
  *
  * @internal
  */
-interface InPageFunctionOption<F> {
-  type?: InPageFunctionType
+interface InPageFunctionOptionBase {
   /** Optional Standard Schema array validating the arguments. */
   args?: RpcArgsSchema
   /** Optional Standard Schema validating the resolved return value. */
   returns?: RpcReturnSchema
   jsonSerializable?: boolean
-  handler: ProtocolHandler<F>
 }
 
+type InPageFunctionOption<F>
+  = | (InPageFunctionOptionBase & {
+    type: 'event'
+    handler?: ProtocolHandler<F>
+  })
+  | (InPageFunctionOptionBase & {
+    type?: Exclude<InPageFunctionType, 'event'>
+    handler: ProtocolHandler<F>
+  })
+
 /**
  * Functions implemented by {@link createPageScriptChannel}.
  *
  * @internal
  */
-type CreatePageScriptChannelOptionsFunctions<P extends InPageChannelProtocol> = Partial<{
+type CreatePageScriptChannelOptionsFunctions<P extends InPageChannelProtocol> = {
   [NAME in keyof PageScriptFunctions<P> & string]: InPageFunctionOption<PageScriptFunctions<P>[NAME]>
-}>
+}
 
 /**
  * Functions implemented by {@link connectPanelChannel}.
  *
  * @internal
  */
-type ConnectPanelChannelOptionsFunctions<P extends InPageChannelProtocol> = Partial<{
+type ConnectPanelChannelOptionsFunctions<P extends InPageChannelProtocol> = {
   [NAME in keyof PanelFunctions<P> & string]: InPageFunctionOption<PanelFunctions<P>[NAME]>
-}>
+}
 
 /**
  * Connection lifecycle of a panel endpoint: `connecting` (handshake retry
@@ -173,8 +184,8 @@ interface InPageChannelCommonOptions {
 
 /** Options for {@link createPageScriptChannel}. */
 export interface CreatePageScriptChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
-  /** Initial page-script handlers. Event listeners may also use `channel.on()`. */
-  functions?: CreatePageScriptChannelOptionsFunctions<Protocol>
+  /** Every page-script function declaration; event handlers may use `channel.on()`. */
+  functions: CreatePageScriptChannelOptionsFunctions<Protocol>
   /**
    * Window whose `message` events carry panel hellos. Defaults to the
    * global `window`; pass `false` to skip the handshake listener entirely
@@ -185,8 +196,8 @@ export interface CreatePageScriptChannelOptions<Protocol extends InPageChannelPr
 
 /** Options for {@link connectPanelChannel}. */
 export interface ConnectPanelChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
-  /** Initial panel handlers. Event listeners may also use `channel.on()`. */
-  functions?: ConnectPanelChannelOptionsFunctions<Protocol>
+  /** Every panel function declaration; event handlers may use `channel.on()`. */
+  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.

tests/__snapshots__/tsnapi/devframe/in-page-channel.snapshot.d.ts

@@ -3,7 +3,7 @@
  */
 // #region Interfaces
 export interface ConnectPanelChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
-  functions?: ConnectPanelChannelOptionsFunctions<Protocol>;
+  functions: ConnectPanelChannelOptionsFunctions<Protocol>;
   window?: Window | false;
   targets?: Window[];
   transport?: MessagePort;
@@ -12,7 +12,7 @@ export interface ConnectPanelChannelOptions<Protocol extends InPageChannelProtoc
   eventBufferLimit?: number;
 }
 export interface CreatePageScriptChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
-  functions?: CreatePageScriptChannelOptionsFunctions<Protocol>;
+  functions: CreatePageScriptChannelOptionsFunctions<Protocol>;
   window?: Window | false;
 }
 export interface InPageChannelProtocol {
@@ -62,21 +62,27 @@ export type InPageChannelErrorCode = 'timeout' |
 'invalid-args' |
 'state-uninitialized';
 export type InPageChannelStatus = 'connecting' | 'connected' | 'closed';
-export type InPageFunctionDefinition<NAME extends string, TYPE extends InPageFunctionType = 'query', ARGS extends any[] = [], RETURN = void, AS extends RpcArgsSchema | undefined = undefined, RS extends RpcReturnSchema | undefined = undefined> = [AS, RS] extends [undefined, undefined] ? {
+export type InPageFunctionDefinition<NAME extends string, TYPE extends InPageFunctionType = 'query', ARGS extends any[] = [], RETURN = void, AS extends RpcArgsSchema | undefined = undefined, RS extends RpcReturnSchema | undefined = undefined> = [AS, RS] extends [undefined, undefined] ? ({
   name: NAME;
   type?: TYPE;
   args?: AS;
   returns?: RS;
   jsonSerializable?: boolean;
-  handler: (...args: ARGS) => RETURN;
+} & (TYPE extends 'event' ? {
+  handler?: (...args: ARGS) => RETURN;
 } : {
+  handler: (...args: ARGS) => RETURN;
+})) : ({
   name: NAME;
   type?: TYPE;
   args: AS;
   returns: RS;
   jsonSerializable?: boolean;
+} & (TYPE extends 'event' ? {
+  handler?: (...args: InferArgsType<AS>) => Thenable<InferReturnType<RS>>;
+} : {
   handler: (...args: InferArgsType<AS>) => Thenable<InferReturnType<RS>>;
-};
+}));
 // #endregion
 
 // #region Classes
@@ -92,12 +98,12 @@ export declare class InPageChannelError extends Error {
 // #region Functions
 export declare function connectPanelChannel<P extends InPageChannelProtocol>(_: ConnectPanelChannelOptions<P>): PanelChannel<P>;
 export declare function createPageScriptChannel<P extends InPageChannelProtocol>(_: CreatePageScriptChannelOptions<P>): PageScriptChannel<P>;
-export declare function defineChannelFunction<NAME extends string, TYPE extends InPageFunctionType, ARGS extends any[], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(_: InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>): InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>;
+export declare function defineChannelFunction<NAME extends string, TYPE extends InPageFunctionType, ARGS extends any[] = [], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(_: InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>): InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>;
 // #endregion
 
 // #region Referenced (internal)
-type ConnectPanelChannelOptionsFunctions<P extends InPageChannelProtocol> = Partial<{ [NAME in keyof PanelFunctions<P> & string]: InPageFunctionOption<PanelFunctions<P>[NAME]>; }>;
-type CreatePageScriptChannelOptionsFunctions<P extends InPageChannelProtocol> = Partial<{ [NAME in keyof PageScriptFunctions<P> & string]: InPageFunctionOption<PageScriptFunctions<P>[NAME]>; }>;
+type ConnectPanelChannelOptionsFunctions<P extends InPageChannelProtocol> = { [NAME in keyof PanelFunctions<P> & string]: InPageFunctionOption<PanelFunctions<P>[NAME]>; };
+type CreatePageScriptChannelOptionsFunctions<P extends InPageChannelProtocol> = { [NAME in keyof PageScriptFunctions<P> & string]: InPageFunctionOption<PageScriptFunctions<P>[NAME]>; };
 type FnArgs<F> = F extends ((...args: infer A) => any) ? A : never;
 type FnReturn<F> = F extends ((...args: any[]) => infer R) ? Awaited<R> : never;
 interface InPageChannelCommonOptions {