@scalar/mock-server 0.11.1 → 0.12.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @scalar/mock-server
 
+## 0.12.1
+
+## 0.12.0
+
+### Minor Changes
+
+- [#9572](https://github.com/scalar/scalar/pull/9572): Add `createAsyncApiMockServer` to mock event-driven APIs from an AsyncAPI 3.1 document. Channels are served over WebSocket and SSE, with messages generated from each message's payload schema (the same generator the REST mocker uses). Additional protocols (e.g. SignalR) can be added through the `transports` extension point. The Docker mock server now auto-detects AsyncAPI documents.
+- [#9486](https://github.com/scalar/scalar/pull/9486): Extend request validation to cover all parameter locations and serialization styles. Header (`in: header`) and cookie (`in: cookie`) parameters are now validated against their schema, with case-insensitive header matching and the `Accept`/`Content-Type`/`Authorization` headers ignored per the OpenAPI specification. Array and object parameters are deserialized by their `style`/`explode` before validation — `form`, `simple`, `spaceDelimited`, `pipeDelimited`, `deepObject`, `label`, and `matrix` — so values like `?ids=1&ids=2`, `?filter[min]=1`, or `/;point=x,1,y,2` validate against their schema instead of being rejected as a raw string. Violations are reported with a `header`, `cookie`, `path`, or `query` location.
+
 ## 0.11.1
 
 ### Patch Changes

package/dist/create-asyncapi-mock-server.d.ts

@@ -0,0 +1,51 @@
+import { createNodeWebSocket } from '@hono/node-ws';
+import { Hono } from 'hono';
+import type { MessageDirection, MockTransport } from './transports/types.js';
+/** Options for {@link createAsyncApiMockServer}. */
+export type AsyncApiMockServerOptions = {
+    /**
+     * The AsyncAPI 3.1 document to mock. Can be a string (URL or file path), a raw JSON/YAML
+     * string, or an already-parsed object.
+     */
+    document?: string | Record<string, any>;
+    /**
+     * Additional transports appended after the built-in WebSocket and SSE transports. Use this to
+     * support extra protocols (for example SignalR) without changing the core. The first transport
+     * whose `supports()` returns `true` for a channel owns it.
+     */
+    transports?: MockTransport[];
+    /** Called for every message flowing in or out of the mock, for logging or inspection. */
+    onMessage?: (event: {
+        channel: string;
+        direction: MessageDirection;
+        payload: unknown;
+    }) => void;
+    /** Optional sink for transport lifecycle log lines. Defaults to no-op. */
+    logger?: (line: string) => void;
+};
+/** The result of {@link createAsyncApiMockServer}. */
+export type AsyncApiMockServer = {
+    /** The Hono app serving SSE channels and WebSocket upgrade routes. */
+    app: Hono;
+    /**
+     * Attaches WebSocket handling to the running Node HTTP server returned by `@hono/node-server`'s
+     * `serve()`. Must be called for WebSocket channels to accept connections.
+     */
+    injectWebSocket: ReturnType<typeof createNodeWebSocket>['injectWebSocket'];
+};
+/**
+ * Create a mock server for an AsyncAPI 3.1 document — the event-driven counterpart of
+ * {@link createMockServer}. Each channel is registered on a transport (WebSocket or SSE by
+ * default) that emits realistic mock messages generated from the channel's message payload
+ * schemas, the same way the REST mocker generates HTTP response bodies.
+ *
+ * WebSocket support requires attaching to the HTTP server after `serve()`:
+ *
+ * ```ts
+ * const { app, injectWebSocket } = await createAsyncApiMockServer({ document })
+ * const server = serve({ fetch: app.fetch, port: 3000 })
+ * injectWebSocket(server)
+ * ```
+ */
+export declare function createAsyncApiMockServer(options: AsyncApiMockServerOptions): Promise<AsyncApiMockServer>;
+//# sourceMappingURL=create-asyncapi-mock-server.d.ts.map

package/dist/create-asyncapi-mock-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-asyncapi-mock-server.d.ts","sourceRoot":"","sources":["../src/create-asyncapi-mock-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAI3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAoB,MAAM,oBAAoB,CAAA;AAK3F,oDAAoD;AACpD,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEvC;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,EAAE,CAAA;IAE5B,yFAAyF;IACzF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IAE/F,0EAA0E;IAC1E,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAChC,CAAA;AAED,sDAAsD;AACtD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,sEAAsE;IACtE,GAAG,EAAE,IAAI,CAAA;IACT;;;OAGG;IACH,eAAe,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,iBAAiB,CAAC,CAAA;CAC3E,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsC9G"}

package/dist/create-asyncapi-mock-server.js

@@ -0,0 +1,51 @@
+import { createNodeWebSocket } from '@hono/node-ws';
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { defaultTransports } from './transports/index.js';
+import { generateMessage } from './utils/generate-message.js';
+import { processAsyncApiDocument } from './utils/process-asyncapi-document.js';
+import { resolveChannels } from './utils/resolve-channels.js';
+/**
+ * Create a mock server for an AsyncAPI 3.1 document — the event-driven counterpart of
+ * {@link createMockServer}. Each channel is registered on a transport (WebSocket or SSE by
+ * default) that emits realistic mock messages generated from the channel's message payload
+ * schemas, the same way the REST mocker generates HTTP response bodies.
+ *
+ * WebSocket support requires attaching to the HTTP server after `serve()`:
+ *
+ * ```ts
+ * const { app, injectWebSocket } = await createAsyncApiMockServer({ document })
+ * const server = serve({ fetch: app.fetch, port: 3000 })
+ * injectWebSocket(server)
+ * ```
+ */
+export async function createAsyncApiMockServer(options) {
+    const app = new Hono();
+    // The Node WebSocket adapter must be created against the app before routes are registered so the
+    // `upgradeWebSocket` helper shares this app's lifecycle. `injectWebSocket` is wired to the
+    // HTTP server by the caller after `serve()`.
+    const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app });
+    const document = await processAsyncApiDocument(options.document);
+    const channels = resolveChannels(document);
+    const transports = [...defaultTransports, ...(options.transports ?? [])];
+    const log = options.logger ?? (() => undefined);
+    // CORS for the SSE/HTTP routes (WebSocket upgrades are not subject to CORS).
+    app.use(cors());
+    const context = {
+        app,
+        upgradeWebSocket,
+        generateMessage,
+        onMessage: options.onMessage,
+        log,
+    };
+    for (const channel of channels) {
+        const transport = transports.find((candidate) => candidate.supports(channel));
+        if (!transport) {
+            log(`[asyncapi] no transport for channel "${channel.id}" (protocols: ${channel.protocols.join(', ') || 'none'})`);
+            continue;
+        }
+        transport.register(channel, context);
+        log(`[asyncapi] ${transport.name} -> ${channel.route} (channel "${channel.id}")`);
+    }
+    return { app, injectWebSocket };
+}

package/dist/index.d.ts

@@ -1,2 +1,6 @@
+export { type AsyncApiMockServer, type AsyncApiMockServerOptions, createAsyncApiMockServer, } from './create-asyncapi-mock-server.js';
 export { createMockServer } from './create-mock-server.js';
+export { defaultTransports, sseTransport, websocketTransport } from './transports/index.js';
+export type { MessageDirection, MockMessage, MockTransport, ResolvedChannel, ResolvedMessage, ResolvedOperation, TransportContext, } from './transports/types.js';
+export { isAsyncApiDocument } from './utils/process-asyncapi-document.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,wBAAwB,GACzB,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAClF,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAA"}

package/dist/index.js

@@ -1 +1,4 @@
+export { createAsyncApiMockServer, } from './create-asyncapi-mock-server.js';
 export { createMockServer } from './create-mock-server.js';
+export { defaultTransports, sseTransport, websocketTransport } from './transports/index.js';
+export { isAsyncApiDocument } from './utils/process-asyncapi-document.js';

package/dist/transports/index.d.ts

@@ -0,0 +1,9 @@
+import type { MockTransport } from '../transports/types.js';
+/**
+ * Built-in transports, in match priority order. WebSocket is checked before SSE so a `ws`
+ * channel is never claimed by the SSE fallback. Consumer transports are appended after these.
+ */
+export declare const defaultTransports: MockTransport[];
+export { sseTransport } from './sse.js';
+export { websocketTransport } from './websocket.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/transports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transports/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAKvD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,aAAa,EAAuC,CAAA;AAEpF,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AACpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}

package/dist/transports/index.js

@@ -0,0 +1,9 @@
+import { sseTransport } from './sse.js';
+import { websocketTransport } from './websocket.js';
+/**
+ * Built-in transports, in match priority order. WebSocket is checked before SSE so a `ws`
+ * channel is never claimed by the SSE fallback. Consumer transports are appended after these.
+ */
+export const defaultTransports = [websocketTransport, sseTransport];
+export { sseTransport } from './sse.js';
+export { websocketTransport } from './websocket.js';

package/dist/transports/sse.d.ts

@@ -0,0 +1,11 @@
+import type { MockTransport } from '../transports/types.js';
+/**
+ * Built-in Server-Sent Events transport. Serves one-way, server-push channels over HTTP: a `GET`
+ * on the channel route opens an SSE stream and emits a generated message per `receive` operation.
+ *
+ * Claims channels whose servers speak `sse`, or plain `http`/`https` channels that have at least
+ * one `receive` operation (a server-push channel). WebSocket takes precedence for `ws` channels
+ * because it is registered first in the default transport list.
+ */
+export declare const sseTransport: MockTransport;
+//# sourceMappingURL=sse.d.ts.map

package/dist/transports/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/transports/sse.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,oBAAoB,CAAA;AAE1E;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,aAmC1B,CAAA"}

package/dist/transports/sse.js

@@ -0,0 +1,37 @@
+import { streamSSE } from 'hono/streaming';
+/**
+ * Built-in Server-Sent Events transport. Serves one-way, server-push channels over HTTP: a `GET`
+ * on the channel route opens an SSE stream and emits a generated message per `receive` operation.
+ *
+ * Claims channels whose servers speak `sse`, or plain `http`/`https` channels that have at least
+ * one `receive` operation (a server-push channel). WebSocket takes precedence for `ws` channels
+ * because it is registered first in the default transport list.
+ */
+export const sseTransport = {
+    name: 'sse',
+    supports: (channel) => {
+        if (channel.protocols.includes('sse')) {
+            return true;
+        }
+        const isHttp = channel.protocols.includes('http') || channel.protocols.includes('https');
+        const hasServerPush = channel.operations.some((operation) => operation.action === 'receive');
+        return isHttp && hasServerPush;
+    },
+    register: (channel, context) => {
+        const { app, generateMessage, onMessage, log } = context;
+        const receiveOperations = channel.operations.filter((operation) => operation.action === 'receive');
+        // Fall back to all channel messages when the channel has no explicit receive operation.
+        const operations = receiveOperations.length > 0 ? receiveOperations : [{ messages: channel.messages }];
+        app.get(channel.route, (c) => streamSSE(c, async (stream) => {
+            log(`[sse] open ${channel.route}`);
+            for (const operation of operations) {
+                const message = generateMessage(channel, operation.messages[0]?.id);
+                if (message) {
+                    await stream.writeSSE({ data: message.data, event: message.event });
+                    onMessage?.({ channel: channel.id, direction: 'out', payload: message.data });
+                }
+            }
+            log(`[sse] close ${channel.route}`);
+        }));
+    },
+};

package/dist/transports/types.d.ts

@@ -0,0 +1,94 @@
+import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { Hono } from 'hono';
+import type { UpgradeWebSocket } from 'hono/ws';
+/**
+ * A message resolved from an AsyncAPI channel/operation, with `$ref`s already resolved.
+ * The `payload` is a plain JSON Schema ready to feed to `getExampleFromSchema`.
+ */
+export type ResolvedMessage = {
+    /** The message id (its key in `channel.messages`), used as the default event name. */
+    id: string;
+    /** The JSON Schema for the message payload, or `undefined` when the message has no payload. */
+    payload?: OpenAPIV3_1.SchemaObject;
+    /** Named/inline examples defined on the message, preferred over generated payloads. */
+    examples: unknown[];
+    /** Content type used to encode the payload (defaults to the document's `defaultContentType`). */
+    contentType?: string;
+};
+/** A single AsyncAPI operation (`send`/`receive`) bound to its channel. */
+export type ResolvedOperation = {
+    /** The operation id (its key in the document's `operations` map). */
+    id: string;
+    /**
+     * `send`: the application sends to the channel, so the mock *receives* a client message
+     * and echoes a reply. `receive`: the application receives from the channel, so the mock
+     * *pushes* a message to the client.
+     */
+    action: 'send' | 'receive';
+    /** Messages this operation may carry (a subset of the channel's messages, or all of them). */
+    messages: ResolvedMessage[];
+};
+/** A normalized, dereferenced view of an AsyncAPI channel that a transport can serve. */
+export type ResolvedChannel = {
+    /** The channel id (its key in the document's `channels` map). */
+    id: string;
+    /** The raw channel address, e.g. `user/signedup` or `rooms/{roomId}`. */
+    address: string;
+    /** Hono-style route derived from the address (`rooms/{roomId}` -> `/rooms/:roomId`). */
+    route: string;
+    /** Connection protocols advertised by the channel's servers, e.g. `['ws']`, `['sse']`. */
+    protocols: string[];
+    /** Operations targeting this channel. */
+    operations: ResolvedOperation[];
+    /** All messages declared on the channel. */
+    messages: ResolvedMessage[];
+};
+/** An encoded frame ready to write to a transport, plus the optional event name. */
+export type MockMessage = {
+    /** The wire payload (already encoded per the message `contentType`). */
+    data: string;
+    /** Event name (the message id), surfaced by transports that support named events (SSE). */
+    event?: string;
+};
+/** Direction of a message relative to the mock server. */
+export type MessageDirection = 'in' | 'out';
+/**
+ * Everything a transport needs to register a channel on the running server. The core builds
+ * this once and passes it to every transport's {@link MockTransport.register}.
+ */
+export type TransportContext = {
+    /** The Hono app. HTTP-based transports (SSE, SignalR negotiate) register routes here. */
+    app: Hono;
+    /**
+     * Hono's WebSocket upgrade helper, bound to the Node adapter. Upgrade-based transports
+     * (WebSocket, SignalR) register sockets via `app.get(route, upgradeWebSocket(...))`.
+     */
+    upgradeWebSocket: UpgradeWebSocket;
+    /**
+     * Generate an encoded mock message for a channel. When `messageId` is omitted the first
+     * available message is used. Returns `null` when the channel declares no messages.
+     */
+    generateMessage: (channel: ResolvedChannel, messageId?: string) => MockMessage | null;
+    /** Notifies the caller about every message flowing in or out, for logging/inspection. */
+    onMessage?: (event: {
+        channel: string;
+        direction: MessageDirection;
+        payload: unknown;
+    }) => void;
+    /** Structured logger for transport lifecycle lines. */
+    log: (line: string) => void;
+};
+/**
+ * A pluggable transport that knows how to serve a class of AsyncAPI channels (by protocol).
+ * Built-in transports cover WebSocket and SSE; consumers can append their own (e.g. SignalR)
+ * via {@link AsyncApiMockServerOptions.transports} without changing the core.
+ */
+export type MockTransport = {
+    /** Unique transport id, e.g. `websocket`, `sse`. */
+    name: string;
+    /** Whether this transport should own the given channel. The first match wins. */
+    supports: (channel: ResolvedChannel) => boolean;
+    /** Register the channel on the server. Called once per matching channel at startup. */
+    register: (channel: ResolvedChannel, context: TransportContext) => void;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/transports/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/transports/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAChC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,sFAAsF;IACtF,EAAE,EAAE,MAAM,CAAA;IACV,+FAA+F;IAC/F,OAAO,CAAC,EAAE,WAAW,CAAC,YAAY,CAAA;IAClC,uFAAuF;IACvF,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,iGAAiG;IACjG,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,2EAA2E;AAC3E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,8FAA8F;IAC9F,QAAQ,EAAE,eAAe,EAAE,CAAA;CAC5B,CAAA;AAED,yFAAyF;AACzF,MAAM,MAAM,eAAe,GAAG;IAC5B,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAA;IACV,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAA;IACf,wFAAwF;IACxF,KAAK,EAAE,MAAM,CAAA;IACb,0FAA0F;IAC1F,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,yCAAyC;IACzC,UAAU,EAAE,iBAAiB,EAAE,CAAA;IAC/B,4CAA4C;IAC5C,QAAQ,EAAE,eAAe,EAAE,CAAA;CAC5B,CAAA;AAED,oFAAoF;AACpF,MAAM,MAAM,WAAW,GAAG;IACxB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAA;IACZ,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,KAAK,CAAA;AAE3C;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,yFAAyF;IACzF,GAAG,EAAE,IAAI,CAAA;IACT;;;OAGG;IACH,gBAAgB,EAAE,gBAAgB,CAAA;IAClC;;;OAGG;IACH,eAAe,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,WAAW,GAAG,IAAI,CAAA;IACrF,yFAAyF;IACzF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IAC/F,uDAAuD;IACvD,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,iFAAiF;IACjF,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAA;IAC/C,uFAAuF;IACvF,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAA;CACxE,CAAA"}

package/dist/transports/types.js

@@ -0,0 +1 @@
+export {};

package/dist/transports/websocket.d.ts

@@ -0,0 +1,10 @@
+import type { MockTransport } from '../transports/types.js';
+/**
+ * Built-in WebSocket transport. Serves channels whose servers speak `ws`/`wss` by upgrading the
+ * channel route to a WebSocket connection.
+ *
+ * - `receive` operations (server push): one message is emitted per operation when a client connects.
+ * - `send` operations (client -> server): each inbound frame is logged and echoed with a generated reply.
+ */
+export declare const websocketTransport: MockTransport;
+//# sourceMappingURL=websocket.d.ts.map

package/dist/transports/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../src/transports/websocket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,aA6ChC,CAAA"}

package/dist/transports/websocket.js

@@ -0,0 +1,45 @@
+/**
+ * Built-in WebSocket transport. Serves channels whose servers speak `ws`/`wss` by upgrading the
+ * channel route to a WebSocket connection.
+ *
+ * - `receive` operations (server push): one message is emitted per operation when a client connects.
+ * - `send` operations (client -> server): each inbound frame is logged and echoed with a generated reply.
+ */
+export const websocketTransport = {
+    name: 'websocket',
+    supports: (channel) => channel.protocols.includes('ws') || channel.protocols.includes('wss'),
+    register: (channel, context) => {
+        const { app, upgradeWebSocket, generateMessage, onMessage, log } = context;
+        const receiveOperations = channel.operations.filter((operation) => operation.action === 'receive');
+        const sendOperation = channel.operations.find((operation) => operation.action === 'send');
+        app.get(channel.route, upgradeWebSocket(() => ({
+            onOpen: (_event, ws) => {
+                log(`[ws] open ${channel.route}`);
+                // Push a single message per receive operation on connect (quiet, deterministic default).
+                for (const operation of receiveOperations) {
+                    const message = generateMessage(channel, operation.messages[0]?.id);
+                    if (message) {
+                        ws.send(message.data);
+                        onMessage?.({ channel: channel.id, direction: 'out', payload: message.data });
+                    }
+                }
+            },
+            onMessage: (event, ws) => {
+                const incoming = typeof event.data === 'string' ? event.data : '[binary]';
+                log(`[ws] recv ${channel.route}: ${incoming}`);
+                onMessage?.({ channel: channel.id, direction: 'in', payload: incoming });
+                // Only echo a reply when the channel declares a `send` operation. Receive-only channels
+                // (server push) stay quiet on inbound frames instead of fabricating an unsolicited reply.
+                if (!sendOperation) {
+                    return;
+                }
+                const reply = generateMessage(channel, sendOperation.messages[0]?.id);
+                if (reply) {
+                    ws.send(reply.data);
+                    onMessage?.({ channel: channel.id, direction: 'out', payload: reply.data });
+                }
+            },
+            onClose: () => log(`[ws] close ${channel.route}`),
+        })));
+    },
+};

package/dist/utils/deserialize-parameter.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Helpers for turning string-encoded request parameters back into the structured values that JSON
+ * Schema validation expects, following the OpenAPI `style`/`explode` serialization rules.
+ *
+ * @see https://spec.openapis.org/oas/v3.1.1.html#style-values
+ */
+/** OpenAPI parameter location, which determines the default serialization style. */
+export type ParameterLocation = 'path' | 'query' | 'header' | 'cookie';
+/**
+ * Resolve the effective `style` and `explode` for a parameter, applying the OpenAPI defaults.
+ *
+ * `explode` defaults to `true` only for the `form` style and `false` for every other style, so the
+ * default depends on the resolved style rather than the location alone.
+ */
+export declare const resolveSerialization: (location: ParameterLocation, style?: string, explode?: boolean) => {
+    style: string;
+    explode: boolean;
+};
+/** Whether a resolved schema describes an array, including the OpenAPI 3.1 `type: ['array', 'null']` form. */
+export declare const isArraySchema: (schema: Record<string, unknown> | undefined) => boolean;
+/** Whether a resolved schema describes an object, including the OpenAPI 3.1 `type: ['object', 'null']` form. */
+export declare const isObjectSchema: (schema: Record<string, unknown> | undefined) => boolean;
+/**
+ * Collect the declared property names of an object schema, looking through `anyOf`/`oneOf`/`allOf`.
+ *
+ * `isObjectSchema` unwraps composed schemas (for example an optional object written as
+ * `anyOf: [{ type: 'object', properties: {…} }, { type: 'null' }]`), so property extraction has to do the
+ * same. Otherwise the names live on a subschema, the top level looks empty, and exploded `form` objects
+ * fall back to free-form gathering — claiming unrelated keys and failing `additionalProperties: false`.
+ */
+export declare const getObjectPropertyNames: (schema: Record<string, unknown> | undefined) => string[];
+/**
+ * Deserialize a string-encoded array parameter into its elements.
+ *
+ * Returns `undefined` when the parameter is absent so the caller can enforce `required` separately.
+ * Object parameters (`deepObject`, simple/form objects) are not handled yet and are validated as-is.
+ */
+export declare const deserializeArrayParameter: ({ style, explode, single, multi, }: {
+    style: string;
+    explode: boolean;
+    /** The single, joined value (for example `1,2,3`) as read from path, query, header, or cookie */
+    single: string | undefined;
+    /** Every repeated value (query only, for example `?id=1&id=2` becomes `['1', '2']`) */
+    multi?: string[] | undefined;
+}) => string[] | undefined;
+/**
+ * Deserialize a string-encoded object parameter into its properties, following the OpenAPI
+ * `style`/`explode` rules. Property values stay as strings so the caller can coerce them against the
+ * object's property schemas.
+ *
+ * Returns `undefined` when the parameter is absent so the caller can enforce `required` separately.
+ * Property values are strings, except for repeated query keys (an array-valued property such as
+ * `filter[tags]=a&filter[tags]=b`), which stay as a string array.
+ */
+export declare const deserializeObjectParameter: ({ style, explode, single, map, name, propertyNames, reservedKeys, }: {
+    style: string;
+    explode: boolean;
+    /** The single value (for example `R,100,G,200`) as read from path, query, header, or cookie */
+    single: string | undefined;
+    /**
+     * The full key/value map for the location, needed for `deepObject` (query only) and exploded `form`
+     * objects (query top-level keys, or one cookie per property). A key with repeated query values carries
+     * a string array so array-valued object properties survive deserialization.
+     */
+    map?: Record<string, string | string[]> | undefined;
+    name: string;
+    /** Declared object property names, used to gather exploded `form` objects from the location map */
+    propertyNames?: string[] | undefined;
+    /**
+     * Names of the other parameters declared in the same location. A free-form exploded object (no declared
+     * properties) claims the remaining keys, so these are excluded to avoid swallowing a sibling parameter's
+     * value (for example a required free-form `meta` must not be satisfied by a `limit` query key).
+     */
+    reservedKeys?: Set<string> | undefined;
+}) => Record<string, string | string[]> | undefined;
+//# sourceMappingURL=deserialize-parameter.d.ts.map

package/dist/utils/deserialize-parameter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deserialize-parameter.d.ts","sourceRoot":"","sources":["../../src/utils/deserialize-parameter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oFAAoF;AACpF,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAUtE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,UAAU,iBAAiB,EAC3B,QAAQ,MAAM,EACd,UAAU,OAAO,KAChB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAGnC,CAAA;AA2BD,8GAA8G;AAC9G,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAG,OAU3E,CAAA;AAED,gHAAgH;AAChH,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAG,OAU5E,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAG,MAAM,EA4B1F,CAAA;AAgGD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,oCAKvC;IACD,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,iGAAiG;IACjG,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;CAC7B,KAAG,MAAM,EAAE,GAAG,SAoBd,CAAA;AAgCD;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,GAAI,qEAQxC;IACD,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,+FAA+F;IAC/F,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,SAAS,CAAA;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,mGAAmG;IACnG,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;CACvC,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,SAoEvC,CAAA"}