@fitzzero/quickdraw-core 5.1.2 → 5.1.3

package/dist/testing/mock.d.ts

@@ -1,12 +1,12 @@
-import { A as AccessLevel, ae as ContractMap, J as AnyContract, ap as MethodName, al as InputOf, ar as OutputOf, af as EntityOf, ac as CollectionName, aw as ScopeOf, an as ItemOf, az as StreamName, am as IsScopedStream, ay as StreamItemOf, aa as ChannelName, a9 as ChannelInputOf, ag as EventName, ah as EventPayloadOf } from '../infer-BmoZsL9a.js';
+import { A as AccessLevel, ae as ContractMap, J as AnyContract, ap as MethodName, al as InputOf, ar as OutputOf, af as EntityOf, ac as CollectionName, aw as ScopeOf, an as ItemOf, az as StreamName, am as IsScopedStream, ay as StreamItemOf, aa as ChannelName, a9 as ChannelInputOf, ag as EventName, ah as EventPayloadOf } from '../infer-Br62cnyW.js';
 import { QueryClient } from '@tanstack/react-query';
 import { ReactNode, ReactElement } from 'react';
-import { i as MethodMember, E as EntityMembers, C as CollectionMember, y as StreamMember, u as ChannelMember, v as EventMember, n as QuickdrawInvalidate } from '../clientTypes-hWcPUVS9.js';
-import { H as AdminMethodsOf } from '../admin-DWWrT1h6.js';
+import { i as MethodMember, E as EntityMembers, C as CollectionMember, y as StreamMember, u as ChannelMember, v as EventMember, n as QuickdrawInvalidate } from '../clientTypes-CUUNJwWs.js';
+import { H as AdminMethodsOf } from '../admin-CS7JB_UH.js';
 import { Q as QuickdrawError } from '../errors-S-bxEIBC.js';
 import '../keys-CqKkljVN.js';
-import '../adminSchemas-D4bFKsrb.js';
-import '../envelope-DzWyIXjj.js';
+import '../adminSchemas-29cGgrg5.js';
+import '../envelope-BMBaxppV.js';
 
 /**
  * How a mocked method answers. Until one of the `mock*` setters runs, every

package/dist/testing/mock.js

@@ -1,17 +1,23 @@
 import {
   createMockClient
-} from "../chunk-AONAFOYU.js";
-import "../chunk-GSIPUNJL.js";
-import "../chunk-GKH3LJ7N.js";
-import "../chunk-753VJIUP.js";
-import "../chunk-5CGO426C.js";
+} from "../chunk-I3JCFS7H.js";
+import "../chunk-64I6MYBC.js";
+import "../chunk-XD7SRDUY.js";
 import "../chunk-4D2DOGAW.js";
 import "../chunk-AK23XSWD.js";
-import "../chunk-47AEXVDM.js";
-import "../chunk-Z2LZ7IZ7.js";
 import "../chunk-DKE6QO26.js";
-import "../chunk-X5CWPX7H.js";
-import "../chunk-4YO5H5ON.js";
+import "../chunk-STH5DLQP.js";
+import "../chunk-IIQ3WMJK.js";
+import "../chunk-2FDSKLBO.js";
+import "../chunk-MPQAT55F.js";
+import "../chunk-A2RBQD66.js";
+import "../chunk-X4ZU4QH5.js";
+import "../chunk-GYLWEJHW.js";
+import "../chunk-47AEXVDM.js";
+import "../chunk-SN3OZVEQ.js";
+import "../chunk-7Y5ROPXL.js";
+import "../chunk-Q4OGQM5I.js";
+import "../chunk-QSU47XEX.js";
 export {
   createMockClient
 };

package/dist/tracked-BR5b2O-U.d.ts

@@ -0,0 +1,43 @@
+declare const TRACKED: unique symbol;
+/** What marks a client as tracked: a type only, with no property at run time. */
+interface TrackedMark {
+    readonly [TRACKED]: true;
+}
+/** The client an interactive `$transaction` of `C` passes its callback, or `C` itself when it has none. */
+type TransactionClientOf<C> = C extends {
+    $transaction(fn: (tx: infer Tx) => unknown, options?: unknown): unknown;
+} ? Tx : C;
+/** The interactive `$transaction` of a tracked `C`: its callback gets the tracked transaction client. */
+interface TrackedInteractiveTransaction<C, Options> {
+    $transaction<R>(fn: (tx: TrackedTransaction<C>) => Promise<R>, options?: Options): Promise<R>;
+}
+/** `$transaction` declared again, with Prisma's options, for a `C` that has an interactive one; nothing for one that has none. */
+type TrackedTransactions<C> = C extends {
+    $transaction(fn: (tx: infer _Tx) => unknown, options?: infer Options): unknown;
+} ? TrackedInteractiveTransaction<C, Options> : unknown;
+/**
+ * A database client whose writes the framework sees: what `trackPrisma`
+ * returns. It is still a `C` everywhere a `C` is asked for, but a plain `C`
+ * is not a `Tracked<C>`, so a helper that writes takes `db: Tracked<Db>`
+ * and the untracked client passed to it is a type error. Its interactive
+ * `$transaction` passes a {@link TrackedTransaction}; the array form is
+ * Prisma's own.
+ *
+ * @example
+ * export const db = trackPrisma(new PrismaClient({ adapter })); // Tracked<PrismaClient>
+ * export async function archive(client: Tracked<PrismaClient>, id: string): Promise<void> {
+ *   await client.project.update({ where: { id }, data: { archived: true } });
+ * }
+ * await qd.run(() => archive(db, projectId)); // archive(prisma, projectId) is a type error
+ */
+type Tracked<C> = TrackedMark & TrackedTransactions<C> & C;
+/**
+ * The client an interactive `db.$transaction(async (tx) => ...)` of a
+ * tracked `db` passes as `tx`, tracked too: Prisma's transaction client of
+ * `C`. `C` is the client, tracked or not; a transaction client stays itself.
+ * A helper that writes inside or outside a transaction takes
+ * `TrackedTransaction<Db>`, which both `db` and `tx` are.
+ */
+type TrackedTransaction<C> = Tracked<TransactionClientOf<C>>;
+
+export type { Tracked as T, TrackedTransaction as a };

package/dist/{types-CYliTP65.d.ts → types-CLRCQGnO.d.ts}

@@ -1,4 +1,4 @@
-import { A as AccessLevel, ae as ContractMap } from './infer-BmoZsL9a.js';
+import { A as AccessLevel, ae as ContractMap } from './infer-Br62cnyW.js';
 
 /**
  * Who is calling. A transport authenticates the connection or request and
@@ -28,7 +28,8 @@ interface Principal {
  * - `context`: the fields `initQuickdraw({ context })` adds to every handler's `ctx`.
  * - `contracts`: the app's contracts (`{ task, project }`), which type `qd.caller`.
  * - `mcp`: the fields the MCP bridge's `context` option gives calls that
- *   arrive over MCP, which handlers read as `ctx.mcp` (token scopes, for example).
+ *   arrive over MCP, and the calls they make through `ctx.services`, which
+ *   handlers read as `ctx.mcp` (token scopes, for example).
  *
  * @example
  * export const qd = initQuickdraw<{ db: AppPrisma; principal: AppPrincipal }>();
@@ -69,4 +70,4 @@ type Transport = "socket" | "http" | "mcp" | "internal" | "legacy";
 /** A value, or a promise of it. */
 type MaybePromise<T> = T | PromiseLike<T>;
 
-export type { ContextExtensionOf as C, DbOf as D, MaybePromise as M, Principal as P, QuickdrawTypes as Q, Transport as T, McpContext as a, McpContextOf as b, PrincipalOf as c, PrincipalKindOf as d };
+export type { ContextExtensionOf as C, DbOf as D, MaybePromise as M, Principal as P, QuickdrawTypes as Q, Transport as T, McpContext as a, PrincipalOf as b, McpContextOf as c, PrincipalKindOf as d };

package/dist/types-tMagHbjy.d.ts

@@ -0,0 +1,151 @@
+import { ab as PeerLabel } from './envelope-BMBaxppV.js';
+
+/** A peer's clock, as a link estimates it. */
+interface PeerClock {
+    /** The peer's clock now, in milliseconds: this side's `performance.now()` plus `offset`. */
+    now(): number;
+    /** The peer's clock minus this side's, in milliseconds; 0 before the first pong. */
+    readonly offset: number;
+    /** The round trip, smoothed, in milliseconds; 0 before the first pong. */
+    readonly rtt: number;
+    /** How much round trips vary, smoothed, in milliseconds. */
+    readonly jitter: number;
+    /** True once enough pongs arrived for `offset` to hold: about half a second after the link opens. */
+    readonly synced: boolean;
+}
+
+/**
+ * Where a link is: `connecting` until a path carries it, `open` while one
+ * does (`path` says which), `closed` for good (`closeReason` says why).
+ */
+type PeerLinkState = "connecting" | "open" | "closed";
+/** What carries an open link: WebRTC data channels between the two clients, or the server's relay. */
+type PeerPath = "direct" | "relay";
+/**
+ * Why a link closed:
+ *
+ * - `closed`: this side's `close()`;
+ * - `bye`: the peer closed it, left the room or disconnected (the server
+ *   says so for a peer that left);
+ * - `left`: this socket left the link's room, or was taken out of it;
+ * - `disconnected`: this side's socket disconnected (a link lives as long
+ *   as the socket it started on), or the connection was closed;
+ * - `timeout`: no path opened within 15 seconds;
+ * - `lost`: nothing was heard from the peer for 8 seconds, or the direct
+ *   path of a link that may not use the relay (`relay: "never"`) dropped
+ *   after it opened;
+ * - `failed`: the direct path failed and the link may not use the relay
+ *   (`relay: "never"`);
+ * - `refused`: the server refused a signal (the peer is not in the room,
+ *   this socket signals too many peers, ...);
+ * - `unsupported`: the server serves no peer links (its hello lists no
+ *   `"peer"`), or the link may use neither WebRTC (absent here) nor the
+ *   relay.
+ */
+type PeerCloseReason = "closed" | "bye" | "left" | "disconnected" | "timeout" | "lost" | "failed" | "refused" | "unsupported";
+/** What a link counted. */
+interface PeerLinkStats {
+    /** App messages a path took: under a lag (`setLag`), each as it goes. */
+    readonly sent: number;
+    /** App messages received. */
+    readonly received: number;
+    /**
+     * App messages `send` dropped: sent while the link was not open, a `fast`
+     * message while the data channel was backed up, or one over the relay's
+     * limits. Under a lag, also a held `fast` message its path refused as it
+     * came due, and a `rel` one sent while a held `rel` message waits for its
+     * path.
+     */
+    readonly dropped: number;
+    /**
+     * App messages the lag lost (`setLag`'s `loss`), sent or received: `fast`
+     * ones alone, and never counted in `dropped`.
+     */
+    readonly simulatedLoss: number;
+}
+/** A link's simulated network, as `setLag` set it. */
+interface PeerLinkLag {
+    /** How long each message waits, each way, in milliseconds. */
+    readonly ms: number;
+    /** Up to this many milliseconds more, at random, per message. */
+    readonly jitter: number;
+    /** The share of `fast` messages lost, each way, from 0 to 1. */
+    readonly loss: number;
+}
+/** What `setLag` takes: each part defaults to 0. */
+interface PeerLinkLagOptions {
+    /** How long each message waits, each way, in milliseconds. */
+    readonly ms?: number;
+    /** Up to this many milliseconds more, at random, per message. */
+    readonly jitter?: number;
+    /** The share of `fast` messages lost, each way, from 0 to 1. `rel` ones never are. */
+    readonly loss?: number;
+    /** Random numbers from 0 to 1, for jitter and loss. Default `Math.random`; pass a seeded one to repeat a run. */
+    readonly random?: () => number;
+}
+/** A link's events and their listeners' arguments. */
+interface PeerLinkEvents {
+    /** An app message from the peer, on `label`. */
+    message: (data: unknown, label: PeerLabel) => void;
+    /** The link opened, on `path`: once. */
+    open: (path: PeerPath) => void;
+    /** The link's state or path changed. */
+    state: (state: PeerLinkState, path: PeerPath | undefined) => void;
+    /** The link closed, for good: once. */
+    close: (reason: PeerCloseReason) => void;
+}
+/**
+ * A link to another socket of an app room: two channels, `rel` (ordered,
+ * reliable) and `fast` (unordered, never retransmitted), over WebRTC data
+ * channels or, when those cannot form, the server's relay, with the same
+ * behaviour either way. Messages are JSON values.
+ */
+interface PeerLink {
+    /** The app room the link belongs to. */
+    readonly room: string;
+    /** The peer's socket id. */
+    readonly peer: string;
+    /** The peer's user, as the server named it in the peer's first signal; `undefined` until then. */
+    readonly userId: string | undefined;
+    readonly state: PeerLinkState;
+    /** What carries the link while it is open. */
+    readonly path: PeerPath | undefined;
+    /** Why the link closed, once it has. */
+    readonly closeReason: PeerCloseReason | undefined;
+    /**
+     * Sends `data` (any JSON value) on `label`. Returns false when it was
+     * dropped: the link is not open, `fast` is backed up, or the relay's rate
+     * is spent (`stats.dropped` counts it). `rel` delivers in order while the
+     * path holds; a path change (the direct path failed, the relay took over)
+     * may lose `rel` messages in flight, and emits `state`. Under a lag
+     * (`setLag`) it returns true for a message it holds. Throws a
+     * `RangeError` for a message over `limits.peers.maxMessageBytes`.
+     */
+    send(label: PeerLabel, data: unknown): boolean;
+    /** Calls `listener` on `event`; returns its removal. */
+    on<E extends keyof PeerLinkEvents>(event: E, listener: PeerLinkEvents[E]): () => void;
+    /** The peer's clock, read from pings the link sends on `fast`. */
+    readonly clock: PeerClock;
+    /** What the link counted. */
+    readonly stats: PeerLinkStats;
+    /**
+     * Simulates a bad network on this link, both ways and on either path, for
+     * a test, a bench or a host that gives itself its peers' lag: each
+     * message waits `ms` plus up to `jitter` milliseconds, and a `fast` one
+     * is lost with probability `loss` (`stats.simulatedLoss` counts the
+     * app's). `rel` messages are never lost and keep their order; one its
+     * path refuses as it comes due goes again a little later. The clock's
+     * pings wait too, so `clock.rtt` reads the lagged round trip. A new lag
+     * leaves what is held on its time; `null` (or all zeros) ends it, and
+     * what is held goes on the next task, in order. A link that closes drops
+     * what it holds. Throws a `TypeError` for a part out of range. Does
+     * nothing once the link is closed.
+     */
+    setLag(lag: PeerLinkLagOptions | null): void;
+    /** The lag `setLag` set; `null` for none. */
+    readonly lag: PeerLinkLag | null;
+    /** Closes the link and tells the peer. Does nothing once it is closed. */
+    close(): void;
+}
+
+export type { PeerPath as P, PeerLink as a, PeerClock as b, PeerCloseReason as c, PeerLinkEvents as d, PeerLinkLag as e, PeerLinkLagOptions as f, PeerLinkState as g, PeerLinkStats as h };

package/dist/utils/index.d.ts

@@ -1,7 +1,6 @@
 import { M as MethodQueryKey } from '../keys-CqKkljVN.js';
 export { C as CollectionQueryKey, E as EntityQueryKey, K as KEY_ROOT, b as MethodKeyPrefix, S as ServiceKeyPrefix, c as collectionKey, e as entityKey, m as methodKey, a as methodKeyPrefix, s as serviceKeyPrefix } from '../keys-CqKkljVN.js';
-import { QueryClient } from '@tanstack/react-query';
-import { ae as ContractMap, ap as MethodName, J as AnyContract, ao as KindOf, al as InputOf, ar as OutputOf } from '../infer-BmoZsL9a.js';
+import { ae as ContractMap, ap as MethodName, J as AnyContract, ao as KindOf, al as InputOf, ar as OutputOf } from '../infer-Br62cnyW.js';
 
 /**
  * Format a currency value for display.
@@ -91,6 +90,19 @@ interface ServerCallerOptions {
     /** The `fetch` to call with. Default: the global one. */
     readonly fetch?: typeof fetch;
 }
+/**
+ * The part of a TanStack `QueryClient` that `prefetch` calls, which any
+ * `QueryClient` is: `prefetchQuery` with the method's key and a function
+ * that calls it.
+ */
+interface QueryClientLike {
+    prefetchQuery(options: {
+        readonly queryKey: MethodQueryKey;
+        readonly queryFn: (context: {
+            readonly signal: AbortSignal;
+        }) => Promise<unknown>;
+    }): Promise<void>;
+}
 /** Options of one HTTP call. */
 interface ServerCallOptions {
     /** Aborting it cancels the request; the call rejects with `CANCELLED`. */
@@ -104,7 +116,7 @@ interface ServerQuery<C extends AnyContract, M extends MethodName<C>> {
     /** The key the query's result is cached under, the one the client's hooks read. */
     key(...args: InputArgs<C, M, []>): MethodQueryKey<InputOf<C, M>>;
     /** Calls the query into `queryClient`, as `queryClient.prefetchQuery` does: it never rejects. */
-    prefetch(queryClient: QueryClient, ...args: InputArgs<C, M, []>): Promise<void>;
+    prefetch(queryClient: QueryClientLike, ...args: InputArgs<C, M, []>): Promise<void>;
 }
 /** A mutation of the server caller. */
 interface ServerMutation<C extends AnyContract, M extends MethodName<C>> {
@@ -137,4 +149,4 @@ type ServerCaller<Contracts extends ContractMap> = {
  */
 declare function createServerCaller<const Contracts extends ContractMap>(contracts: Contracts, options: ServerCallerOptions): ServerCaller<Contracts>;
 
-export { type BreadcrumbItem, type JWTPayload, MethodQueryKey, type NavItem, type ServerCallOptions, type ServerCaller, type ServerCallerHeaders, type ServerCallerOptions, type ServerMethod, type ServerMutation, type ServerQuery, buildBreadcrumbs, createServerCaller, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, parseJWTPayload, routeRequiresAuth, truncate };
+export { type BreadcrumbItem, type JWTPayload, MethodQueryKey, type NavItem, type QueryClientLike, type ServerCallOptions, type ServerCaller, type ServerCallerHeaders, type ServerCallerOptions, type ServerMethod, type ServerMutation, type ServerQuery, buildBreadcrumbs, createServerCaller, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, parseJWTPayload, routeRequiresAuth, truncate };

package/dist/utils/index.js

@@ -11,7 +11,7 @@ import {
   parseJWTPayload,
   routeRequiresAuth,
   truncate
-} from "../chunk-B2P7AZ25.js";
+} from "../chunk-CYE4UBOB.js";
 import {
   KEY_ROOT,
   collectionKey,
@@ -19,8 +19,11 @@ import {
   methodKey,
   methodKeyPrefix,
   serviceKeyPrefix
-} from "../chunk-X5CWPX7H.js";
-import "../chunk-4YO5H5ON.js";
+} from "../chunk-IIQ3WMJK.js";
+import "../chunk-MPQAT55F.js";
+import "../chunk-47AEXVDM.js";
+import "../chunk-Q4OGQM5I.js";
+import "../chunk-QSU47XEX.js";
 export {
   KEY_ROOT,
   buildBreadcrumbs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitzzero/quickdraw-core",
-  "version": "5.1.2",
+  "version": "5.1.3",
   "description": "Fast fullstack patterns for real-time applications with Socket.io and TanStack Query",
   "keywords": [
     "fullstack",
@@ -53,6 +53,10 @@
       "types": "./dist/client/index.d.ts",
       "import": "./dist/client/index.js"
     },
+    "./client/core": {
+      "types": "./dist/client/core.d.ts",
+      "import": "./dist/client/core.js"
+    },
     "./utils": {
       "types": "./dist/utils/index.d.ts",
       "import": "./dist/utils/index.js"

package/dist/chunk-4YO5H5ON.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/protocol/guards.ts","../src/protocol/errors.ts"],"sourcesContent":["// Shape checks shared by the protocol's hand-written guards. Internal: the\n// package root exports the guards built on these, not these.\n\n/** An object that is not an array or `null`: what a JSON object decodes to. */\nexport type UnknownRecord = { readonly [key: string]: unknown };\n\n/** True when `value` is an object that is not an array or `null`. */\nexport function isRecord(value: unknown): value is UnknownRecord {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** True when `value` is a non-empty string, as service and method names are. */\nexport function isName(value: unknown): value is string {\n  return typeof value === \"string\" && value.length > 0;\n}\n","// Error codes and the error every failed call carries (RFC 0003 section 3).\n// In 4.1 a failed call answered `{ success: false, error, code? }`\n// (4.1 `src/shared/types.ts:88-90`), every thrown error became code 500\n// with its own message (4.1 `src/server/ServiceRegistry.ts:398-402`), and\n// the client rethrew it as `ServiceCallError` with that number\n// (4.1 `src/client/serviceError.ts:6`). In 5.0 a handler picks the code by\n// throwing `QuickdrawError`; the same code reaches the caller on every\n// transport, and the HTTP transport maps it to a status with `httpStatus`.\n\nimport { isRecord } from \"./guards\";\n\n/** Every code a call can fail with, in the order of RFC 0003 section 3. */\nexport const ERROR_CODES = Object.freeze([\n  \"UNAUTHENTICATED\",\n  \"FORBIDDEN\",\n  \"NOT_FOUND\",\n  \"CONFLICT\",\n  \"VALIDATION\",\n  \"RATE_LIMITED\",\n  \"CANCELLED\",\n  \"TIMEOUT\",\n  \"INTERNAL\",\n] as const);\n\n/**\n * Why a call failed:\n *\n * - `UNAUTHENTICATED` (401): there is no principal.\n * - `FORBIDDEN` (403): access was denied.\n * - `NOT_FOUND` (404): an unknown service, method or row.\n * - `CONFLICT` (409): a unique or state conflict.\n * - `VALIDATION` (422): the input failed its schema; see {@link ValidationErrorData}.\n * - `RATE_LIMITED` (429): a limiter or a full queue; see {@link RateLimitedErrorData}.\n * - `CANCELLED` (499): the caller cancelled.\n * - `TIMEOUT` (504): the handler ran past its time limit.\n * - `INTERNAL` (500): anything else.\n */\nexport type ErrorCode = (typeof ERROR_CODES)[number];\n\nconst HTTP_STATUS: Readonly<Record<ErrorCode, number>> = Object.freeze({\n  UNAUTHENTICATED: 401,\n  FORBIDDEN: 403,\n  NOT_FOUND: 404,\n  CONFLICT: 409,\n  VALIDATION: 422,\n  RATE_LIMITED: 429,\n  CANCELLED: 499,\n  TIMEOUT: 504,\n  INTERNAL: 500,\n});\n\n/** The message every `INTERNAL` error carries on the wire, whatever was thrown. */\nexport const INTERNAL_MESSAGE = \"Internal error\";\n\n/** True when `value` is one of the error codes. */\nexport function isErrorCode(value: unknown): value is ErrorCode {\n  return typeof value === \"string\" && Object.hasOwn(HTTP_STATUS, value);\n}\n\n/** The HTTP status for an error code, as the table in RFC 0003 section 3 gives it. */\nexport function httpStatus(code: ErrorCode): number {\n  return HTTP_STATUS[code];\n}\n\n/** One problem with a call's input, in a `VALIDATION` error's `data.issues`. */\nexport interface WireIssue {\n  /** Where the problem is, as object keys and array indexes; empty for the input itself. */\n  readonly path: readonly (string | number)[];\n  readonly message: string;\n}\n\n/** The `data` of a `VALIDATION` error. */\nexport interface ValidationErrorData {\n  readonly issues: readonly WireIssue[];\n}\n\n/** The `data` of a `RATE_LIMITED` error. */\nexport interface RateLimitedErrorData {\n  /** How long to wait before trying again, in milliseconds. */\n  readonly retryAfterMs: number;\n}\n\n/**\n * The error a failed call carries. A handler throws it to choose the code the\n * caller sees; the client rejects with it. Anything else a handler throws\n * reaches the caller as `INTERNAL` with a generic message (see {@link toWire}).\n */\nexport class QuickdrawError extends Error {\n  /** Why the call failed. */\n  readonly code: ErrorCode;\n  /**\n   * Details for the caller, sent as JSON: `issues` for `VALIDATION`,\n   * `retryAfterMs` for `RATE_LIMITED`. `INTERNAL` errors never send it.\n   */\n  readonly data: unknown;\n\n  constructor(code: ErrorCode, message: string, data?: unknown) {\n    super(message);\n    this.name = \"QuickdrawError\";\n    this.code = code;\n    this.data = data;\n  }\n}\n\n/** An error as it travels: the `e` of a failed acknowledgement. */\nexport interface WireError {\n  readonly code: ErrorCode;\n  readonly message: string;\n  readonly data?: unknown;\n}\n\n/**\n * The wire form of whatever a call failed with. A `QuickdrawError` keeps its\n * code, message and data. Anything else, and every `INTERNAL` error, becomes\n * `{ code: \"INTERNAL\", message: \"Internal error\" }`: no stack, message or data\n * of an internal failure ever reaches the caller, so log the original first.\n */\nexport function toWire(error: unknown): WireError {\n  if (!(error instanceof QuickdrawError) || error.code === \"INTERNAL\" || !isErrorCode(error.code)) {\n    return { code: \"INTERNAL\", message: INTERNAL_MESSAGE };\n  }\n  return error.data === undefined\n    ? { code: error.code, message: error.message }\n    : { code: error.code, message: error.message, data: error.data };\n}\n\n/**\n * The `QuickdrawError` a wire error describes. A code this version does not\n * know becomes `INTERNAL`, keeping the message and data. A payload that is not\n * a wire error (not an object, or no string `message`) becomes a generic\n * `INTERNAL`. Either way the caller can branch on `code`.\n */\nexport function fromWire(payload: unknown): QuickdrawError {\n  if (!isRecord(payload) || typeof payload.message !== \"string\") {\n    return new QuickdrawError(\"INTERNAL\", INTERNAL_MESSAGE);\n  }\n  const code = isErrorCode(payload.code) ? payload.code : \"INTERNAL\";\n  return new QuickdrawError(code, payload.message, payload.data);\n}\n"],"mappings":";AAOO,SAAS,SAAS,OAAwC;AAC/D,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAGO,SAAS,OAAO,OAAiC;AACtD,SAAO,OAAO,UAAU,YAAY,MAAM,SAAS;AACrD;;;ACFO,IAAM,cAAc,OAAO,OAAO;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAU;AAiBV,IAAM,cAAmD,OAAO,OAAO;AAAA,EACrE,iBAAiB;AAAA,EACjB,WAAW;AAAA,EACX,WAAW;AAAA,EACX,UAAU;AAAA,EACV,YAAY;AAAA,EACZ,cAAc;AAAA,EACd,WAAW;AAAA,EACX,SAAS;AAAA,EACT,UAAU;AACZ,CAAC;AAGM,IAAM,mBAAmB;AAGzB,SAAS,YAAY,OAAoC;AAC9D,SAAO,OAAO,UAAU,YAAY,OAAO,OAAO,aAAa,KAAK;AACtE;AAGO,SAAS,WAAW,MAAyB;AAClD,SAAO,YAAY,IAAI;AACzB;AAyBO,IAAM,iBAAN,cAA6B,MAAM;AAAA;AAAA,EAE/B;AAAA;AAAA;AAAA;AAAA;AAAA,EAKA;AAAA,EAET,YAAY,MAAiB,SAAiB,MAAgB;AAC5D,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd;AACF;AAeO,SAAS,OAAO,OAA2B;AAChD,MAAI,EAAE,iBAAiB,mBAAmB,MAAM,SAAS,cAAc,CAAC,YAAY,MAAM,IAAI,GAAG;AAC/F,WAAO,EAAE,MAAM,YAAY,SAAS,iBAAiB;AAAA,EACvD;AACA,SAAO,MAAM,SAAS,SAClB,EAAE,MAAM,MAAM,MAAM,SAAS,MAAM,QAAQ,IAC3C,EAAE,MAAM,MAAM,MAAM,SAAS,MAAM,SAAS,MAAM,MAAM,KAAK;AACnE;AAQO,SAAS,SAAS,SAAkC;AACzD,MAAI,CAAC,SAAS,OAAO,KAAK,OAAO,QAAQ,YAAY,UAAU;AAC7D,WAAO,IAAI,eAAe,YAAY,gBAAgB;AAAA,EACxD;AACA,QAAM,OAAO,YAAY,QAAQ,IAAI,IAAI,QAAQ,OAAO;AACxD,SAAO,IAAI,eAAe,MAAM,QAAQ,SAAS,QAAQ,IAAI;AAC/D;","names":[]}

package/dist/chunk-5CGO426C.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/contract/realtime.ts"],"sourcesContent":["// Streams, channels and typed room events in a contract (RFC 0003 section\n// 12.5). A stream is server-to-client append-only data a subscriber receives\n// with a seed of recent items; a channel is fire-and-forget client-to-server\n// input (cursors, typing) behind a per-socket token bucket; an event is a\n// typed custom frame a handler sends to a room. 4.1 declared channels on the\n// service class (4.1 `src/server/BaseService.ts:915-942`) and typed room\n// events through the augmentable `QuickdrawEventMap`; here all three live in\n// the contract, so the client is typed from it.\n//\n// Methods, collections, streams, channels and events share one namespace:\n// the client exposes each as `qd.<service>.<name>`.\n\nimport type { AccessLevel } from \"./access\";\nimport type { AnyContract } from \"./defineContract\";\nimport type { StandardSchemaV1 } from \"./standardSchema\";\n\n/** The `scope` of a stream with one feed for the whole service: the default. */\nexport const GLOBAL_STREAM = \"global\";\n\n/** The most items a stream may keep per scope as the seed for new subscribers. */\nexport const STREAM_MAX_SEED = 1000;\n\n/** A channel's sustained rate when it declares none: messages per second per socket. */\nexport const CHANNEL_DEFAULT_RATE = 30;\n\n/**\n * The app room a stream's subscriber must be in (`access: { room }`): for a\n * global stream the room's name, or `{ prefix }` for any room whose name\n * starts with it; for a scoped stream a function of the scope\n * (`(worldId) => \\`world:${worldId}\\``), since a name or a prefix would let\n * a socket in that room read every scope (`defineContract` refuses them\n * there).\n */\nexport type StreamRoom = string | RoomPrefix | ((scope: string) => string | null | undefined);\n\n/**\n * Who may subscribe to a stream (RFC 0003 section 4.1's forms, as data). A\n * scoped stream's scope value is the row an `entry` or `scope` form is about:\n * `{ entry: L }` needs level `L` on the row of this service whose id is the\n * scope, `{ scope: L, of }` level `L` on that row of `of`'s service.\n * `{ room }` opens it to the sockets in an app room a method joined them to\n * (signed in or not), as a channel's `requires: { room }` does its messages:\n * a socket that leaves the room, or is taken out of it, leaves the feed too.\n * A scoped stream computes that room from its scope; a name or `{ prefix }`\n * serves a global stream only. A stream that declares none is closed: no\n * client may subscribe.\n */\nexport type StreamAccess =\n  | \"public\"\n  | \"authenticated\"\n  | {\n      readonly service: AccessLevel;\n      readonly entry?: undefined;\n      readonly scope?: undefined;\n      readonly of?: undefined;\n      readonly room?: undefined;\n    }\n  | {\n      readonly entry: AccessLevel;\n      readonly service?: AccessLevel;\n      readonly scope?: undefined;\n      readonly of?: undefined;\n      readonly room?: undefined;\n    }\n  | {\n      readonly scope: AccessLevel;\n      readonly of: AnyContract;\n      readonly service?: undefined;\n      readonly entry?: undefined;\n      readonly room?: undefined;\n    }\n  | {\n      readonly room: StreamRoom;\n      readonly service?: undefined;\n      readonly entry?: undefined;\n      readonly scope?: undefined;\n      readonly of?: undefined;\n    };\n\n/** A server-to-client stream of append-only items (RFC 0003 section 12.5). */\nexport interface StreamDef<Item extends StandardSchemaV1 = StandardSchemaV1> {\n  /** One item's schema. Pushed items are checked against it before they are sent. */\n  readonly item: Item;\n  /**\n   * What a scope value is (`\"taskId\"`): the stream has one feed per scope.\n   * `\"global\"`, the default, makes one feed for the whole service.\n   */\n  readonly scope?: string;\n  /**\n   * How many of the latest items the server keeps per scope, in memory on\n   * each process, and sends a new subscriber first. Default 0; at most 1,000.\n   */\n  readonly seed?: number;\n  /** Send items volatile: dropped for a client whose connection is backed up. Default `false`. */\n  readonly volatile?: boolean;\n  /** Who may subscribe. Without it the stream is closed. */\n  readonly access?: StreamAccess;\n  /** What the stream carries, in a sentence or two, for the generated docs. */\n  readonly describe?: string;\n}\n\n/**\n * Where a channel requirement finds its row id or scope value in the parsed\n * payload: the name of a key holding a string, or a function of the payload.\n */\nexport type PayloadSelector = string | ((payload: never) => string | null | undefined);\n\n/**\n * Any app room whose name starts with `prefix` (`{ prefix: \"world:\" }`, a\n * game of many worlds): the sending socket passes when it is in one, and\n * the channel's handler gets the one it matched as `ctx.room`, so the\n * payload need not repeat which room it is for.\n */\nexport interface RoomPrefix {\n  readonly prefix: string;\n}\n\n/**\n * The app room a channel requirement names: the room itself (`\"world\"`, a\n * game's one world), a function of the parsed payload that returns it\n * (`(payload) => \\`lobby:${payload.lobbyId}\\``), or `{ prefix }`, any room\n * whose name starts with it (`{ prefix: \"world:\" }`). Unlike a\n * {@link PayloadSelector}, a string here is the room's name, not a payload\n * key. A name starting with `qd:` or `user:`, or one with the shape of a\n * Socket.IO socket id (20 letters, digits, `_` or `-`), is never an app\n * room: a literal one (or such a prefix) is refused when the contract is\n * defined, and a computed one drops the message.\n */\nexport type RoomSelector = string | ((payload: never) => string | null | undefined) | RoomPrefix;\n\n/**\n * What a channel message requires of the socket that sends it: a live\n * subscription (`qd:sub`) to the row of this service `entity` names, or\n * (`qd:col:sub`) to the scope of `collection` that `scope` names; or that\n * the socket is in the app room `room` names (or, for `{ prefix }`, in any\n * app room whose name starts with it), which a method called over that\n * same socket joined with `ctx.rooms.join` (a room another socket of the\n * user joined does not count, and a reconnected socket is in none until it\n * joins again). The handler gets the room that matched as `ctx.room`. Each\n * is checked in memory against the sending socket's own records, on the\n * node it is connected to. A message whose payload names none is dropped.\n */\nexport type ChannelRequires =\n  | {\n      readonly entity: PayloadSelector;\n      readonly collection?: undefined;\n      readonly scope?: undefined;\n      readonly room?: undefined;\n    }\n  | {\n      readonly collection: string;\n      readonly scope: PayloadSelector;\n      readonly entity?: undefined;\n      readonly room?: undefined;\n    }\n  | {\n      readonly room: RoomSelector;\n      readonly entity?: undefined;\n      readonly collection?: undefined;\n      readonly scope?: undefined;\n    };\n\n/** A client-to-server fire-and-forget channel (RFC 0003 section 12.5). */\nexport interface ChannelDef<Payload extends StandardSchemaV1 = StandardSchemaV1> {\n  /** One message's schema. A message that fails it is dropped. */\n  readonly payload: Payload;\n  /** Messages one socket may send per second, sustained. Default 30. */\n  readonly ratePerSecond?: number;\n  /** How many messages one socket may send at once. Default twice `ratePerSecond`. */\n  readonly burst?: number;\n  /**\n   * What the sender must already be subscribed to, or the app room it must\n   * be in. Without it every signed-in user may send the channel, about any\n   * row or room its payload names, and the server warns\n   * `channel-without-requires` unless the service declares the channel's\n   * `access` (`\"authenticated\"` when any signed-in user may send it).\n   */\n  readonly requires?: ChannelRequires;\n  /** What a message says, in a sentence or two, for the generated docs. */\n  readonly describe?: string;\n}\n\n/** A typed custom room event, delivered as `qd:event` (RFC 0003 section 8.3). */\nexport interface EventDef<Payload extends StandardSchemaV1 = StandardSchemaV1> {\n  readonly payload: Payload;\n  /** What the event announces, in a sentence or two, for the generated docs. */\n  readonly describe?: string;\n}\n\n/** True when a stream has one feed per scope value; false for a global stream. */\nexport function isScopedStream(def: Pick<StreamDef, \"scope\">): boolean {\n  return def.scope !== undefined && def.scope !== GLOBAL_STREAM;\n}\n"],"mappings":";AAiBO,IAAM,gBAAgB;AAGtB,IAAM,kBAAkB;AAGxB,IAAM,uBAAuB;AAuK7B,SAAS,eAAe,KAAwC;AACrE,SAAO,IAAI,UAAU,UAAa,IAAI,UAAU;AAClD;","names":[]}