refactor: make events optional

Author: posva

docs/content/6.errors/DF0077.md

@@ -83,7 +83,6 @@ Emitted by `devframe`: the framework-neutral host, RPC, streaming, assets, servi
 | [DF0074](/errors/DF0074) | error | JSON-Render Schema Is Asynchronous |
 | [DF0075](/errors/DF0075) | warn | No RPC Transport On This Runtime |
 | [DF0076](/errors/DF0076) | error | WebSocket Upgrade Unsupported On This Runtime |
-| [DF0077](/errors/DF0077) | error | In-Page Channel Event Not Registered |
 
 ## Hub: context & lifecycle (DF80xx)
 

docs/content/6.errors/index.md

@@ -1,4 +1,4 @@
-import type { ConnectPanelChannelOptions, CreatePageScriptChannelOptions, PageScriptChannel, PanelChannel } from './types'
+import type { PageScriptChannel, PanelChannel } from './types'
 import { expectTypeOf, it } from 'vitest'
 
 interface Protocol {
@@ -47,45 +47,9 @@ it('distinguishes void actions from declared events in both directions', () => {
   panel.on('reset', () => {})
 })
 
-it('requires function handlers and separate event declarations', () => {
-  const options: CreatePageScriptChannelOptions<Protocol> = {
-    name: 'test',
-    functions: {
-      save: { type: 'action', handler: (value) => {
-        expectTypeOf(value).toEqualTypeOf<string>()
-      } },
-      reset: { type: 'action', handler: async () => {} },
-    },
-    events: { note: {} },
-  }
-  // @ts-expect-error Actions require handlers even when returning void.
-  options.functions.save = { type: 'action' }
-  // @ts-expect-error Functions cannot be declared as events.
-  options.functions.reset = { type: 'event' }
-  // @ts-expect-error Events belong in the events option.
-  options.functions.note = { handler: () => {} }
-  // @ts-expect-error Event declarations must be complete.
-  options.events = {}
-  // @ts-expect-error Functions belong in the functions option.
-  options.events.save = {}
-  options.events.note = { handler: (value, count) => {
-    expectTypeOf(value).toEqualTypeOf<string>()
-    expectTypeOf(count).toEqualTypeOf<number | undefined>()
-  } }
-  // @ts-expect-error Event handlers must match the declared arguments.
-  options.events.note = { handler: (value: number) => void value }
-  // @ts-expect-error Event declarations cannot be actions.
-  options.events.note = { type: 'action', handler: () => {} }
-})
-
 it('supports omitted protocol sections without widening their keys', () => {
   interface FunctionsOnly { functions: { pageScript: { run: () => void } } }
   interface EventsOnly { events: { panel: { ready: () => void } } }
-  const options: ConnectPanelChannelOptions<FunctionsOnly> = { name: 'test', functions: {}, events: {} }
-  // @ts-expect-error This direction declares no events.
-  options.events.ready = {}
-  // @ts-expect-error This direction declares no functions.
-  options.functions.run = { handler: () => {} }
   expectTypeOf<Parameters<PanelChannel<FunctionsOnly>['emit']>[0]>().toEqualTypeOf<never>()
   expectTypeOf<Parameters<PanelChannel<EventsOnly>['call']>[0]>().toEqualTypeOf<never>()
   expectTypeOf<Parameters<PageScriptChannel<EventsOnly>['on']>[0]>().toEqualTypeOf<never>()

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

@@ -59,7 +59,6 @@ function createLinkedPair(options?: {
 }): { pageScript: PageScriptChannel<TestProtocol>, panel: PanelChannel<TestProtocol>, dispose: () => void } {
   const { port1, port2 } = new MessageChannel()
   const pageScript = createPageScriptChannel<TestProtocol>({
-    events: { note: {} },
     name: 'devframes:test',
     ...noHandshake,
     functions: {
@@ -73,7 +72,6 @@ function createLinkedPair(options?: {
   })
   pageScript.addPanelPort(port1)
   const panel = connectPanelChannel<TestProtocol>({
-    events: { notify: {} },
     name: 'devframes:test',
     ...noHandshake,
     transport: port2,
@@ -118,7 +116,6 @@ describe('in-page channel over bring-your-own ports', () => {
     const pageScript = createPageScriptChannel<Protocol>({
       name: 'test',
       ...noHandshake,
-      events: {},
       functions: {
         save: { type: 'action', jsonSerializable: true, handler: () => {} },
         reset: { type: 'action', handler: async () => {
@@ -135,7 +132,6 @@ describe('in-page channel over bring-your-own ports', () => {
       name: 'test',
       ...noHandshake,
       functions: {},
-      events: {},
       transport: port2,
       callTimeoutMs: 100,
     })
@@ -204,14 +200,10 @@ describe('in-page channel over bring-your-own ports', () => {
     expect(panelAction).toHaveBeenCalledOnce()
   })
 
-  it('rejects subscriptions to functions even when they return void', ({ onTestFinished }) => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  it('keeps untyped runtime subscriptions isolated from functions', ({ onTestFinished }) => {
     const { pageScript, dispose } = createLinkedPair()
-    onTestFinished(() => {
-      dispose()
-      warn.mockRestore()
-    })
-    expect(() => pageScript.on('boom' as any, () => {})).toThrowError(expect.objectContaining({ name: 'DF0077' }))
+    onTestFinished(dispose)
+    expect(() => pageScript.on('boom' as any, () => {})).not.toThrow()
   })
 
   it('round-trips calls, arguments, and results', async () => {
@@ -247,19 +239,10 @@ describe('in-page channel over bring-your-own ports', () => {
     }
   })
 
-  it('reports and rejects listeners for undeclared events', ({ onTestFinished }) => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  it('accepts listeners without runtime event declarations', ({ onTestFinished }) => {
     const { panel, dispose } = createLinkedPair()
-    onTestFinished(() => {
-      dispose()
-      warn.mockRestore()
-    })
-
-    expect(() => {
-      panel.on('missing' as any, () => {})
-    }).toThrowError(expect.objectContaining({ name: 'DF0077' }))
-    expect(warn).toHaveBeenCalledOnce()
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('[DF0077]'))
+    onTestFinished(dispose)
+    expect(() => panel.on('missing' as any, () => {})).not.toThrow()
   })
 
   it('enforces jsonSerializable payloads with a coded error', async () => {
@@ -350,7 +333,6 @@ describe('in-page channel over bring-your-own ports', () => {
     const offNotify = panelA.on('notify', value => received.push(`a:${value}`))
     // Panel B deliberately has no listener for this event.
     const panelB = connectPanelChannel<InPageChannelProtocol>({
-      events: {},
       name: 'devframes:test',
       ...noHandshake,
       transport: b.port2,

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

@@ -4,7 +4,6 @@ import type { RpcArgsSchema } from '../rpc/types'
 import type { InPageChannelControlFrame } from './protocol'
 import type { InPageFunctionDefinitionAny } from './types'
 import { createBirpc } from 'birpc'
-import { diagnostics } from './diagnostics'
 import { isControlFrame } from './protocol'
 
 /**
@@ -182,8 +181,6 @@ export function createLocalFunctionRegistry(codec: InPageChannelSerialization):
     },
     on(name, listener) {
       const key = channelMethod('event', name)
-      if (!definitions.has(key))
-        throw diagnostics.DF0077({ name })
       let registered = listeners.get(key)
       if (!registered) {
         registered = new Set()

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

@@ -66,7 +66,7 @@ export function createPageScriptChannel<P extends InPageChannelProtocol>(
   const registry = createLocalFunctionRegistry(codec)
   for (const [fnName, definition] of Object.entries(options.functions))
     registry.register({ ...definition, name: fnName })
-  for (const [eventName, definition] of Object.entries(options.events))
+  for (const [eventName, definition] of Object.entries(options.events ?? {}))
     registry.register({ ...definition, name: eventName, type: 'event' })
 
   const stateHost = createPageScriptStateHost<P>(function* () {

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

@@ -65,7 +65,7 @@ export function connectPanelChannel<P extends InPageChannelProtocol>(
   const registry = createLocalFunctionRegistry(codec)
   for (const [fnName, definition] of Object.entries(options.functions))
     registry.register({ ...definition, name: fnName })
-  for (const [eventName, definition] of Object.entries(options.events))
+  for (const [eventName, definition] of Object.entries(options.events ?? {}))
     registry.register({ ...definition, name: eventName, type: 'event' })
 
   let status: InPageChannelStatus = 'connecting'

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

@@ -178,7 +178,6 @@ describe('In-page script channel', () => {
 
     it('rejects fire-and-forget calls to panel queries', () => {
       const mixedChannel = createPageScriptChannel<MixedPanelProtocol>({
-        events: {},
         name: 'devframes:mixed-panel',
         functions: {},
       })
@@ -204,7 +203,6 @@ describe('In-page script channel', () => {
 
     it('rejects calls when the protocol declares no panel functions', () => {
       const pageScriptOnlyChannel = createPageScriptChannel<PageScriptOnlyProtocol>({
-        events: {},
         name: 'devframes:page-script-only',
         functions: {
           echo: { handler: value => value },
@@ -338,13 +336,11 @@ describe('Panel channel', () => {
 
     it('accepts an explicitly empty panel function map', () => {
       connectPanelChannel<PageScriptOnlyProtocol>({
-        events: {},
         name: 'devframes:page-script-only',
         functions: {},
       })
 
       connectPanelChannel<PageScriptOnlyProtocol>({
-        events: {},
         name: 'devframes:page-script-only',
         functions: {
           // @ts-expect-error The protocol has no panel functions.

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

@@ -253,8 +253,8 @@ interface InPageChannelCommonOptions {
 export interface CreatePageScriptChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
   /** Every page-script function declaration, with a required handler. */
   functions: CreatePageScriptChannelOptionsFunctions<Protocol>
-  /** Every incoming event declaration; handlers may subscribe through `channel.on()`. */
-  events: { [NAME in keyof PageScriptProtocolEvents<Protocol> & string]: InPageEventOption<PageScriptProtocolEvents<Protocol>[NAME]> }
+  /** Optional metadata or handlers for incoming events. Listeners may instead subscribe through `channel.on()`. */
+  events?: { [NAME in keyof PageScriptProtocolEvents<Protocol> & string]?: InPageEventOption<PageScriptProtocolEvents<Protocol>[NAME]> }
   /**
    * Window whose `message` events carry panel hellos. Defaults to the
    * global `window`; pass `false` to skip the handshake listener entirely
@@ -267,8 +267,8 @@ export interface CreatePageScriptChannelOptions<Protocol extends InPageChannelPr
 export interface ConnectPanelChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
   /** Every panel function declaration, with a required handler. */
   functions: ConnectPanelChannelOptionsFunctions<Protocol>
-  /** Every incoming event declaration; handlers may subscribe through `channel.on()`. */
-  events: { [NAME in keyof PanelProtocolEvents<Protocol> & string]: InPageEventOption<PanelProtocolEvents<Protocol>[NAME]> }
+  /** Optional metadata or handlers for incoming events. Listeners may instead subscribe through `channel.on()`. */
+  events?: { [NAME in keyof PanelProtocolEvents<Protocol> & string]?: InPageEventOption<PanelProtocolEvents<Protocol>[NAME]> }
   /**
    * The panel's own window (listens for the handshake grant). Defaults to
    * the global `window`; pass `false` with `transport` to skip the handshake.