@daloyjs/core 1.0.0-beta.6 → 1.0.0-beta.7

package/dist/websocket.d.ts

@@ -76,10 +76,15 @@ export interface WebSocketConnection<TData = unknown> {
  * been read.
  */
 export interface WebSocketContext<P extends string = string, S = AppState> {
+    /** The original RFC 6455 upgrade `Request`. */
     request: Request;
+    /** Path parameters extracted from the matched route pattern. */
     params: PathParams<P>;
+    /** Query-string parameters from the upgrade URL. */
     query: Record<string, string>;
+    /** Upgrade request headers, lower-cased keys. */
     headers: Record<string, string>;
+    /** Per-app state produced by the route's state factory. */
     state: S;
     /** Subprotocols offered by the client (parsed from `Sec-WebSocket-Protocol`). */
     protocols: string[];
@@ -208,25 +213,45 @@ export interface WebSocketHandler<P extends string = string, S = AppState, TData
      * @since 0.33.0
      */
     acknowledgeCrossOriginUpgrade?: boolean;
+    /**
+     * Auth/decision hook run before the 101 response is sent (after the
+     * {@link WebSocketHandler.allowedOrigins} check). Return a `Response` to
+     * reject, a string to select that subprotocol, or `undefined` to accept.
+     */
     beforeUpgrade?(request: Request, ctx: WebSocketContext<P, S>): Response | string | undefined | Promise<Response | string | undefined>;
+    /** Called once after the upgrade completes and the connection is open. */
     open?(conn: WebSocketConnection<TData>, ctx: WebSocketContext<P, S>): void | Promise<void>;
+    /** Called for each complete inbound message; `data` is a string for text frames, bytes for binary (`isBinary: true`). */
     message?(conn: WebSocketConnection<TData>, data: string | Uint8Array | ArrayBuffer, isBinary: boolean): void | Promise<void>;
+    /** Called when the connection closes, with the RFC 6455 close code and reason. */
     close?(conn: WebSocketConnection<TData>, code: number, reason: string): void | Promise<void>;
+    /** Called when a socket or handler error occurs on the connection. */
     error?(conn: WebSocketConnection<TData>, err: unknown): void | Promise<void>;
+    /** Called when the socket's send buffer drains after backpressure. */
     drain?(conn: WebSocketConnection<TData>): void | Promise<void>;
 }
 /** Result of {@link normalizeWebSocketOptions}: fully resolved limits applied by the adapter. */
 export interface NormalizedWebSocketOptions {
+    /** Close the connection when queued outbound bytes exceed `backpressureLimit`. Defaults to `true`. */
     closeOnBackpressureLimit: boolean;
+    /** Maximum queued outbound bytes before backpressure handling triggers. Defaults to 1 MiB. */
     backpressureLimit: number;
+    /** Per-message compression flag. Defaults to `false`; refused in production under secureDefaults. */
     perMessageDeflate: boolean;
+    /** Idle timeout in seconds. Defaults to `120`. */
     idleTimeout: number;
+    /** Maximum inbound message payload length in bytes. Defaults to 1 MiB. */
     maxPayloadLength: number;
 }
 /**
  * Resolve a user-supplied {@link WebSocketHandler} into the strict
  * {@link NormalizedWebSocketOptions} the adapter consumes. Applies defaults,
  * runs production safety checks, and throws on invalid values.
+ *
+ * @param handler The user-supplied handler whose option fields are validated.
+ * @param context Environment flags: `production` and `secureDefaults` gate the perMessageDeflate refusal.
+ * @returns The fully resolved options applied by the runtime adapter.
+ * @throws Error when a limit is not a positive integer, `allowedOrigins` is malformed, `perMessageDeflate` is enabled in production under secureDefaults, or `maxPayloadLength` exceeds the body schema maximum.
  */
 export declare function normalizeWebSocketOptions(handler: WebSocketHandler<any, any, any>, context: {
     production: boolean;
@@ -239,16 +264,27 @@ export type WebSocketBeforeUpgrade<P extends string = string, S = AppState> = No
  * a `beforeUpgrade` handler to spend from the same shared buckets as HTTP
  * routes (for example, login and WebSocket session-establishment endpoints).
  *
+ * @param options The same {@link RateLimitOptions} accepted by the HTTP `rateLimit` middleware.
+ * @returns A `beforeUpgrade` hook that returns the 429 (or error) `Response` when the limit is exceeded, or `undefined` to allow the upgrade. Rate-limit headers are copied onto rejection responses.
  * @since 0.23.0
  */
 export declare function wsRateLimit<P extends string = string, S = AppState>(options: RateLimitOptions): WebSocketBeforeUpgrade<P, S>;
-/** Helper for declaring a handler with full type-inference. */
+/**
+ * Helper for declaring a handler with full type-inference.
+ *
+ * @param handler The {@link WebSocketHandler} to type-check; returned as-is.
+ * @returns The same handler object, with `P`/`S`/`TData` inferred.
+ */
 export declare function defineWebSocket<P extends string, S = AppState, TData = unknown>(handler: WebSocketHandler<P, S, TData>): WebSocketHandler<P, S, TData>;
 /** Entry stored inside {@link WebSocketRegistry} for a single WS route. */
 export interface WebSocketRouteEntry {
+    /** Route path pattern the entry was registered under (may contain `:param` segments). */
     path: PathString;
+    /** The user-supplied lifecycle handler for this route. */
     handler: WebSocketHandler<any, any, any>;
+    /** Factory producing the per-upgrade `state` object handed to the context. */
     createState: WebSocketStateFactory;
+    /** Resolved limits from {@link normalizeWebSocketOptions} applied by the adapter. */
     options: NormalizedWebSocketOptions;
 }
 type WebSocketStateFactory = () => Record<string, unknown>;
@@ -263,7 +299,21 @@ export declare class WebSocketRegistry {
     private router;
     private _size;
     private entries;
+    /**
+     * Register a WebSocket route.
+     *
+     * @param path Route path pattern (supports `:param` segments).
+     * @param handler Lifecycle handler for connections on this route.
+     * @param createState Per-upgrade state factory. Defaults to `() => ({})`.
+     * @param options Resolved limits; defaults to normalizing `handler` with dev-mode secure defaults.
+     */
     add(path: PathString, handler: WebSocketHandler<any, any, any>, createState?: WebSocketStateFactory, options?: NormalizedWebSocketOptions): void;
+    /**
+     * Match a request pathname against the registered WS routes.
+     *
+     * @param pathname URL pathname of the upgrade request.
+     * @returns The matched entry plus extracted params, or `undefined` when no route matches.
+     */
     find(pathname: string): RouteMatch<WebSocketRouteEntry> | undefined;
     /**
      * List every registered WebSocket route entry in registration order.
@@ -276,7 +326,17 @@ export declare class WebSocketRegistry {
      * @since 0.37.0
      */
     list(): WebSocketRouteEntry[];
+    /** Number of registered WebSocket routes. */
     get size(): number;
+    /**
+     * Aggregate the per-route options into a single set for runtimes (Bun) that
+     * take one server-wide WebSocket config: `closeOnBackpressureLimit` only when
+     * every route enables it, largest `backpressureLimit`/`maxPayloadLength`,
+     * smallest `idleTimeout`, and `perMessageDeflate` if any route enables it.
+     * Returns the secure defaults when no routes are registered.
+     *
+     * @returns The merged {@link NormalizedWebSocketOptions} for the whole app.
+     */
     runtimeOptions(): NormalizedWebSocketOptions;
 }
 /**
@@ -284,17 +344,30 @@ export declare class WebSocketRegistry {
  * `Sec-WebSocket-Key` per RFC 6455 §4.2.2:
  *
  * `base64(SHA1(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"))`
+ *
+ * @param key - The client's `Sec-WebSocket-Key` header value.
+ * @returns The base64-encoded accept token for the 101 response.
+ * @throws Error when Web Crypto (`crypto.subtle`) is unavailable.
  */
 export declare function computeAcceptKey(key: string): Promise<string>;
 /**
  * Parse the offered subprotocols from a `Sec-WebSocket-Protocol` header.
  * Returns trimmed, non-empty tokens in client preference order.
+ *
+ * @param header - Raw header value; `null`/`undefined` yields an empty list.
+ * @returns The offered subprotocol tokens, most-preferred first.
  */
 export declare function parseSubprotocols(header: string | null | undefined): string[];
 /**
  * Validate a server-selected subprotocol before it is written to the 101
  * response. RFC 6455 requires the value to be one of the client-offered
  * tokens; enforcing it also prevents accidental response-header injection.
+ *
+ * @param protocol - The subprotocol the server wants to select.
+ * @param offered - Tokens the client offered (from {@link parseSubprotocols}).
+ * @returns The validated `protocol`, unchanged.
+ * @throws WebSocketProtocolError when `protocol` is not a valid HTTP token
+ *   or was not offered by the client.
  */
 export declare function validateSelectedSubprotocol(protocol: string, offered: readonly string[]): string;
 /**
@@ -315,6 +388,12 @@ export type HandshakeResult = {
  * Validate the upgrade request headers and compute the accept key when
  * valid. This helper does **not** touch the wire — it only decides whether
  * the handshake should succeed and what the response key should be.
+ *
+ * @param headers - Header accessor for the upgrade request (any object with
+ *   a `Headers`-style `get`).
+ * @returns `{ ok: true, acceptKey, protocols }` when the RFC 6455 handshake
+ *   headers are valid, or `{ ok: false, status, reason }` describing the
+ *   error response the adapter should send.
  */
 export declare function validateUpgrade(headers: {
     get(name: string): string | null;
@@ -329,6 +408,10 @@ export declare function validateUpgrade(headers: {
  * `{ ok: false, reason }` with a short human-readable reason suitable for
  * the upgrade-error body.
  *
+ * @param request - The upgrade request whose `Origin` header is checked.
+ * @param policy - The route's `allowedOrigins` value: `undefined` (allow
+ *   all), `"same-origin"`, a string allowlist, or a predicate function.
+ * @returns `{ ok: true }` when permitted, otherwise `{ ok: false, reason }`.
  * @since 0.33.0
  */
 export declare function checkWebSocketOrigin(request: Request, policy: WebSocketHandler<any, any, any>["allowedOrigins"]): {
@@ -339,8 +422,11 @@ export declare function checkWebSocketOrigin(request: Request, policy: WebSocket
 };
 /** A single decoded RFC 6455 frame, as returned by {@link parseFrame}. */
 export interface ParsedFrame {
+    /** FIN bit — `true` when this frame ends a message. */
     fin: boolean;
+    /** Frame opcode (see `WS_OPCODE`): continuation, text, binary, close, ping, or pong. */
     opcode: number;
+    /** Unmasked payload bytes — a subarray view over the input buffer, not a copy. */
     payload: Uint8Array;
     /** Number of bytes consumed from the input buffer (header + payload). */
     consumed: number;
@@ -355,6 +441,15 @@ export declare const FRAME_INCOMPLETE: unique symbol;
  * The parser unmasks payloads in-place when needed. The returned `payload`
  * is a subarray view over `buf`; copy it if you intend to retain it past
  * the next call.
+ *
+ * @param buf - Buffered socket bytes beginning at a frame boundary.
+ * @param opts - `requireMask: true` enforces the RFC 6455 rule that
+ *   client-to-server frames are masked. Defaults to `{}` (not enforced).
+ * @returns The decoded {@link ParsedFrame}, or {@link FRAME_INCOMPLETE}
+ *   when more bytes are needed.
+ * @throws WebSocketProtocolError on RSV bits, unknown opcodes, fragmented
+ *   or oversized control frames, unmasked client frames, or payload lengths
+ *   above `Number.MAX_SAFE_INTEGER`.
  */
 export declare function parseFrame(buf: Uint8Array, opts?: {
     requireMask?: boolean;
@@ -363,6 +458,12 @@ export declare function parseFrame(buf: Uint8Array, opts?: {
  * Encode a single frame. By default the frame is emitted unmasked (server
  * → client). Pass `mask: true` to generate a client-style masked frame (used
  * mainly for testing).
+ *
+ * @param opts - Frame parts: `opcode` (required), `payload` (default empty),
+ *   `fin` (default `true`), and `mask` (default `false`).
+ * @returns The wire-ready frame bytes (header + payload).
+ * @throws WebSocketProtocolError when a control-frame payload exceeds 125
+ *   bytes; Error when masking is requested without Web Crypto.
  */
 export declare function encodeFrame(opts: {
     fin?: boolean;
@@ -370,9 +471,23 @@ export declare function encodeFrame(opts: {
     payload?: Uint8Array;
     mask?: boolean;
 }): Uint8Array;
-/** Encode a CLOSE frame payload (`uint16 code` + optional UTF-8 reason). */
+/**
+ * Encode a CLOSE frame payload (`uint16 code` + optional UTF-8 reason).
+ *
+ * @param code - RFC 6455 close status code, written big-endian.
+ * @param reason - Optional human-readable reason. Defaults to `""`.
+ * @returns The 2+N byte close payload.
+ * @throws WebSocketProtocolError when the encoded reason exceeds 123 bytes.
+ */
 export declare function encodeClosePayload(code: number, reason?: string): Uint8Array;
-/** Decode a CLOSE frame payload. Returns `{ code: 1005, reason: "" }` when empty. */
+/**
+ * Decode a CLOSE frame payload. Returns `{ code: 1005, reason: "" }` when empty.
+ *
+ * @param payload - Unmasked close-frame payload bytes.
+ * @returns The close `code` and decoded UTF-8 `reason`.
+ * @throws WebSocketProtocolError when the payload is exactly 1 byte or the
+ *   reason is not valid UTF-8.
+ */
 export declare function decodeClosePayload(payload: Uint8Array): {
     code: number;
     reason: string;
@@ -400,10 +515,15 @@ export interface MessageEvent {
 }
 /** Callbacks supplied to a {@link FrameSink} by an adapter to receive decoded frames and protocol events. */
 export interface FrameSinkEvents {
+    /** A complete (possibly reassembled) text or binary message arrived. */
     onMessage(ev: MessageEvent): void;
+    /** A PING control frame arrived; `payload` is a copied buffer. */
     onPing(payload: Uint8Array): void;
+    /** A PONG control frame arrived; `payload` is a copied buffer. */
     onPong(payload: Uint8Array): void;
+    /** A CLOSE frame arrived; the sink stops processing further input. */
     onClose(code: number, reason: string): void;
+    /** An RFC 6455 violation was detected; the adapter should CLOSE(1002). */
     onProtocolError(err: WebSocketProtocolError): void;
 }
 /**
@@ -422,11 +542,24 @@ export declare class FrameSink {
         requireMask?: boolean;
         maxPayloadLength?: number;
     });
+    /**
+     * Feed raw socket bytes into the assembler. Complete frames trigger the
+     * configured callbacks; partial frames are buffered until more bytes
+     * arrive. No-op after a CLOSE frame or protocol error.
+     *
+     * @param chunk - The next bytes read from the socket.
+     */
     push(chunk: Uint8Array): void;
     private handle;
     private assertMessageSize;
 }
-/** Coerce arbitrary `send()` payloads to a `Uint8Array` + opcode pair. */
+/**
+ * Coerce arbitrary `send()` payloads to a `Uint8Array` + opcode pair.
+ *
+ * @param data - A string (sent as TEXT) or any `ArrayBuffer`/view (sent as
+ *   BINARY without copying when possible).
+ * @returns The `WS_OPCODE` to use and the payload bytes to frame.
+ */
 export declare function encodeSendPayload(data: string | ArrayBufferLike | ArrayBufferView): {
     opcode: number;
     payload: Uint8Array;

package/dist/websocket.js

@@ -124,6 +124,11 @@ function declaredSchemaMaxBytes(schema) {
  * Resolve a user-supplied {@link WebSocketHandler} into the strict
  * {@link NormalizedWebSocketOptions} the adapter consumes. Applies defaults,
  * runs production safety checks, and throws on invalid values.
+ *
+ * @param handler The user-supplied handler whose option fields are validated.
+ * @param context Environment flags: `production` and `secureDefaults` gate the perMessageDeflate refusal.
+ * @returns The fully resolved options applied by the runtime adapter.
+ * @throws Error when a limit is not a positive integer, `allowedOrigins` is malformed, `perMessageDeflate` is enabled in production under secureDefaults, or `maxPayloadLength` exceeds the body schema maximum.
  */
 export function normalizeWebSocketOptions(handler, context) {
     const closeOnBackpressureLimit = handler.closeOnBackpressureLimit ?? true;
@@ -162,6 +167,8 @@ export function normalizeWebSocketOptions(handler, context) {
  * a `beforeUpgrade` handler to spend from the same shared buckets as HTTP
  * routes (for example, login and WebSocket session-establishment endpoints).
  *
+ * @param options The same {@link RateLimitOptions} accepted by the HTTP `rateLimit` middleware.
+ * @returns A `beforeUpgrade` hook that returns the 429 (or error) `Response` when the limit is exceeded, or `undefined` to allow the upgrade. Rate-limit headers are copied onto rejection responses.
  * @since 0.23.0
  */
 export function wsRateLimit(options) {
@@ -200,7 +207,12 @@ function copyWsRateLimitHeaders(headers, response) {
             response.headers.set(key, value);
     });
 }
-/** Helper for declaring a handler with full type-inference. */
+/**
+ * Helper for declaring a handler with full type-inference.
+ *
+ * @param handler The {@link WebSocketHandler} to type-check; returned as-is.
+ * @returns The same handler object, with `P`/`S`/`TData` inferred.
+ */
 export function defineWebSocket(handler) {
     return handler;
 }
@@ -215,6 +227,14 @@ export class WebSocketRegistry {
     router = new Router();
     _size = 0;
     entries = [];
+    /**
+     * Register a WebSocket route.
+     *
+     * @param path Route path pattern (supports `:param` segments).
+     * @param handler Lifecycle handler for connections on this route.
+     * @param createState Per-upgrade state factory. Defaults to `() => ({})`.
+     * @param options Resolved limits; defaults to normalizing `handler` with dev-mode secure defaults.
+     */
     add(path, handler, createState = () => ({}), options = normalizeWebSocketOptions(handler, {
         production: false,
         secureDefaults: true,
@@ -224,6 +244,12 @@ export class WebSocketRegistry {
         this.entries.push(entry);
         this._size += 1;
     }
+    /**
+     * Match a request pathname against the registered WS routes.
+     *
+     * @param pathname URL pathname of the upgrade request.
+     * @returns The matched entry plus extracted params, or `undefined` when no route matches.
+     */
     find(pathname) {
         return this.router.find("GET", pathname);
     }
@@ -240,9 +266,19 @@ export class WebSocketRegistry {
     list() {
         return [...this.entries];
     }
+    /** Number of registered WebSocket routes. */
     get size() {
         return this._size;
     }
+    /**
+     * Aggregate the per-route options into a single set for runtimes (Bun) that
+     * take one server-wide WebSocket config: `closeOnBackpressureLimit` only when
+     * every route enables it, largest `backpressureLimit`/`maxPayloadLength`,
+     * smallest `idleTimeout`, and `perMessageDeflate` if any route enables it.
+     * Returns the secure defaults when no routes are registered.
+     *
+     * @returns The merged {@link NormalizedWebSocketOptions} for the whole app.
+     */
     runtimeOptions() {
         if (this.entries.length === 0) {
             return {
@@ -282,6 +318,10 @@ function getSubtle() {
  * `Sec-WebSocket-Key` per RFC 6455 §4.2.2:
  *
  * `base64(SHA1(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"))`
+ *
+ * @param key - The client's `Sec-WebSocket-Key` header value.
+ * @returns The base64-encoded accept token for the 101 response.
+ * @throws Error when Web Crypto (`crypto.subtle`) is unavailable.
  */
 export async function computeAcceptKey(key) {
     const digest = await getSubtle().digest("SHA-1", enc.encode(key + WS_GUID));
@@ -290,6 +330,9 @@ export async function computeAcceptKey(key) {
 /**
  * Parse the offered subprotocols from a `Sec-WebSocket-Protocol` header.
  * Returns trimmed, non-empty tokens in client preference order.
+ *
+ * @param header - Raw header value; `null`/`undefined` yields an empty list.
+ * @returns The offered subprotocol tokens, most-preferred first.
  */
 export function parseSubprotocols(header) {
     if (!header)
@@ -304,6 +347,12 @@ const WS_TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
  * Validate a server-selected subprotocol before it is written to the 101
  * response. RFC 6455 requires the value to be one of the client-offered
  * tokens; enforcing it also prevents accidental response-header injection.
+ *
+ * @param protocol - The subprotocol the server wants to select.
+ * @param offered - Tokens the client offered (from {@link parseSubprotocols}).
+ * @returns The validated `protocol`, unchanged.
+ * @throws WebSocketProtocolError when `protocol` is not a valid HTTP token
+ *   or was not offered by the client.
  */
 export function validateSelectedSubprotocol(protocol, offered) {
     if (!WS_TOKEN_RE.test(protocol)) {
@@ -318,6 +367,12 @@ export function validateSelectedSubprotocol(protocol, offered) {
  * Validate the upgrade request headers and compute the accept key when
  * valid. This helper does **not** touch the wire — it only decides whether
  * the handshake should succeed and what the response key should be.
+ *
+ * @param headers - Header accessor for the upgrade request (any object with
+ *   a `Headers`-style `get`).
+ * @returns `{ ok: true, acceptKey, protocols }` when the RFC 6455 handshake
+ *   headers are valid, or `{ ok: false, status, reason }` describing the
+ *   error response the adapter should send.
  */
 export async function validateUpgrade(headers) {
     const upgrade = headers.get("upgrade");
@@ -378,6 +433,10 @@ function isValidWebSocketKey(key) {
  * `{ ok: false, reason }` with a short human-readable reason suitable for
  * the upgrade-error body.
  *
+ * @param request - The upgrade request whose `Origin` header is checked.
+ * @param policy - The route's `allowedOrigins` value: `undefined` (allow
+ *   all), `"same-origin"`, a string allowlist, or a predicate function.
+ * @returns `{ ok: true }` when permitted, otherwise `{ ok: false, reason }`.
  * @since 0.33.0
  */
 export function checkWebSocketOrigin(request, policy) {
@@ -438,6 +497,15 @@ export const FRAME_INCOMPLETE = Symbol("daloy.ws.frameIncomplete");
  * The parser unmasks payloads in-place when needed. The returned `payload`
  * is a subarray view over `buf`; copy it if you intend to retain it past
  * the next call.
+ *
+ * @param buf - Buffered socket bytes beginning at a frame boundary.
+ * @param opts - `requireMask: true` enforces the RFC 6455 rule that
+ *   client-to-server frames are masked. Defaults to `{}` (not enforced).
+ * @returns The decoded {@link ParsedFrame}, or {@link FRAME_INCOMPLETE}
+ *   when more bytes are needed.
+ * @throws WebSocketProtocolError on RSV bits, unknown opcodes, fragmented
+ *   or oversized control frames, unmasked client frames, or payload lengths
+ *   above `Number.MAX_SAFE_INTEGER`.
  */
 export function parseFrame(buf, opts = {}) {
     if (buf.length < 2)
@@ -514,6 +582,12 @@ export function parseFrame(buf, opts = {}) {
  * Encode a single frame. By default the frame is emitted unmasked (server
  * → client). Pass `mask: true` to generate a client-style masked frame (used
  * mainly for testing).
+ *
+ * @param opts - Frame parts: `opcode` (required), `payload` (default empty),
+ *   `fin` (default `true`), and `mask` (default `false`).
+ * @returns The wire-ready frame bytes (header + payload).
+ * @throws WebSocketProtocolError when a control-frame payload exceeds 125
+ *   bytes; Error when masking is requested without Web Crypto.
  */
 export function encodeFrame(opts) {
     const fin = opts.fin !== false;
@@ -579,7 +653,14 @@ export function encodeFrame(opts) {
     }
     return out;
 }
-/** Encode a CLOSE frame payload (`uint16 code` + optional UTF-8 reason). */
+/**
+ * Encode a CLOSE frame payload (`uint16 code` + optional UTF-8 reason).
+ *
+ * @param code - RFC 6455 close status code, written big-endian.
+ * @param reason - Optional human-readable reason. Defaults to `""`.
+ * @returns The 2+N byte close payload.
+ * @throws WebSocketProtocolError when the encoded reason exceeds 123 bytes.
+ */
 export function encodeClosePayload(code, reason = "") {
     const reasonBytes = enc.encode(reason);
     if (reasonBytes.length > WS_MAX_CONTROL_PAYLOAD - 2) {
@@ -591,7 +672,14 @@ export function encodeClosePayload(code, reason = "") {
     out.set(reasonBytes, 2);
     return out;
 }
-/** Decode a CLOSE frame payload. Returns `{ code: 1005, reason: "" }` when empty. */
+/**
+ * Decode a CLOSE frame payload. Returns `{ code: 1005, reason: "" }` when empty.
+ *
+ * @param payload - Unmasked close-frame payload bytes.
+ * @returns The close `code` and decoded UTF-8 `reason`.
+ * @throws WebSocketProtocolError when the payload is exactly 1 byte or the
+ *   reason is not valid UTF-8.
+ */
 export function decodeClosePayload(payload) {
     if (payload.length === 0)
         return { code: WS_CLOSE_CODE.NO_STATUS_RECEIVED, reason: "" };
@@ -634,6 +722,13 @@ export class FrameSink {
     constructor(opts) {
         this.opts = opts;
     }
+    /**
+     * Feed raw socket bytes into the assembler. Complete frames trigger the
+     * configured callbacks; partial frames are buffered until more bytes
+     * arrive. No-op after a CLOSE frame or protocol error.
+     *
+     * @param chunk - The next bytes read from the socket.
+     */
     push(chunk) {
         if (this.closed)
             return;
@@ -738,7 +833,13 @@ export class FrameSink {
     }
 }
 // ---------- Helpers shared by adapters ----------
-/** Coerce arbitrary `send()` payloads to a `Uint8Array` + opcode pair. */
+/**
+ * Coerce arbitrary `send()` payloads to a `Uint8Array` + opcode pair.
+ *
+ * @param data - A string (sent as TEXT) or any `ArrayBuffer`/view (sent as
+ *   BINARY without copying when possible).
+ * @returns The `WS_OPCODE` to use and the payload bytes to frame.
+ */
 export function encodeSendPayload(data) {
     if (typeof data === "string") {
         return { opcode: WS_OPCODE.TEXT, payload: enc.encode(data) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daloyjs/core",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.7",
   "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops — distributed via pnpm.",
   "type": "module",
   "publishConfig": {