@fitzzero/quickdraw-core 5.1.2 → 5.1.3

package/dist/client/core.d.ts

@@ -0,0 +1,387 @@
+export { BreadcrumbItem, JWTPayload, NavItem, QueryClientLike, ServerCallOptions, ServerCaller, ServerCallerHeaders, ServerCallerOptions, ServerMethod, ServerMutation, ServerQuery, buildBreadcrumbs, createServerCaller, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, parseJWTPayload, routeRequiresAuth, truncate } from '../utils/index.js';
+export { C as CollectionQueryKey, E as EntityQueryKey, K as KEY_ROOT, b as MethodKeyPrefix, M as MethodQueryKey, S as ServiceKeyPrefix, c as collectionKey, e as entityKey, m as methodKey, a as methodKeyPrefix, s as serviceKeyPrefix } from '../keys-CqKkljVN.js';
+import { Q as QuickdrawConnection } from '../connection-2EeQ_Et0.js';
+export { B as BackoffKind, g as BackoffWindows, C as ConnectionAuth, c as ConnectionRefusal, e as ConnectionState, b as ConnectionStatus, D as DEFAULT_BACKOFF_MS, h as DEFAULT_SUBSCRIPTION_LANE, J as JoinWait, L as LaneCallback, a as QuickdrawConnectionOptions, f as QuickdrawSocket, S as SocketClientOptions, i as SubscriptionEvent, j as SubscriptionLane, T as TopicWatch, d as createQuickdrawConnection } from '../connection-2EeQ_Et0.js';
+import { k as MethodKind, J as AnyContract, aD as HostStreamName, ay as StreamItemOf, aE as HostChannelName, ab as ChannelPayloadOf } from '../infer-Br62cnyW.js';
+import { aA as Version, D as CallSuccess, z as CallNotModified, q as ProtocolMismatch } from '../envelope-BMBaxppV.js';
+export { ab as PeerLabel } from '../envelope-BMBaxppV.js';
+import { a as PeerLink } from '../types-tMagHbjy.js';
+export { b as PeerClock, c as PeerCloseReason, d as PeerLinkEvents, e as PeerLinkLag, f as PeerLinkLagOptions, g as PeerLinkState, h as PeerLinkStats, P as PeerPath } from '../types-tMagHbjy.js';
+import 'socket.io-client';
+import '../errors-S-bxEIBC.js';
+
+/**
+ * Get the stored auth token: from `localStorage`, or from memory where it
+ * cannot be used; `null` without a `window`.
+ */
+declare function getAuthToken(): string | null;
+/**
+ * Store the auth token (in `localStorage`, else in memory) and dispatch a
+ * change event. Does nothing without a `window`.
+ */
+declare function setAuthToken(token: string): void;
+/**
+ * Remove the auth token and dispatch a change event. Does nothing without a
+ * `window`.
+ */
+declare function clearAuthToken(): void;
+/** Where the auth routes are, for the browser helpers. */
+interface AuthRoutesTarget {
+    /**
+     * The API's URL, where `createAuthRoutes` is mounted:
+     * `"https://api.example.com"`. Default: `NEXT_PUBLIC_API_URL` where it can
+     * be read, else `http://localhost:4000`.
+     */
+    readonly apiUrl?: string;
+    /** The routes' `basePath`, as `createAuthRoutes` was given it. Default `/auth`. */
+    readonly basePath?: string;
+}
+/** Options of {@link signInUrl}. */
+interface SignInUrlOptions extends AuthRoutesTarget {
+    /**
+     * The page to come back to: an origin or a URL on one, of which the
+     * routes keep the origin when `allowedOrigins` lists it, and land on
+     * `{origin}{successPath}`. Default: the current page's origin where there
+     * is a page; elsewhere the routes take their first allowed origin.
+     */
+    readonly returnTo?: string;
+}
+/**
+ * The URL that starts a sign-in with `provider`: the auth routes' `GET
+ * {basePath}/{provider}/start?returnTo=`, which redirects to the provider
+ * and, once the user consents, back to `returnTo`'s origin with the session
+ * cookie set (or to the routes' `errorPath` with `?error=`). Navigate to it:
+ * a link, or `location.assign`. Throws a `TypeError` for a provider id the
+ * routes cannot have (lowercase letters, digits and hyphens).
+ *
+ * @example
+ * <a href={signInUrl("google", { apiUrl: API_URL })}>Sign in with Google</a>
+ */
+declare function signInUrl(provider: string, options?: SignInUrlOptions): string;
+/**
+ * Signs out: `POST {basePath}/logout`, which revokes the request's session
+ * and clears its cookie, sent with the session cookie and, when one is
+ * stored, the bearer token; the stored token is forgotten either way.
+ * Rejects with a `QuickdrawError` when the server cannot be reached or
+ * refuses (`RATE_LIMITED`, say), so the app knows the session may still be
+ * live. The connection keeps the user it signed in as until it connects
+ * again: with cookie sessions, reconnect it (`connection.close()`, then
+ * `open()`), or load the next page; a provider whose `auth` was the stored
+ * token reconnects when the app clears it.
+ *
+ * @example
+ * await signOut({ apiUrl: API_URL });
+ */
+declare function signOut(options?: AuthRoutesTarget): Promise<void>;
+/** A sign-in the API's auth routes serve, as `GET {basePath}/providers` lists it ({@link authProviders}). */
+interface AuthProviderInfo {
+    /** Its id: `signInUrl(id)` starts it; a guest's is `POST {basePath}/guest`. */
+    readonly id: string;
+    /** A name for its button: `"Google"`, `"Discord"`, `"Mock"`, `"Guest"`, or an OAuth provider's own. */
+    readonly name: string;
+    /** `"oauth"` (a redirecting provider), `"mock"` (the development picker) or `"guest"`. */
+    readonly kind: "oauth" | "mock" | "guest";
+}
+/**
+ * The sign-ins the API serves, in the order its routes list them: `GET
+ * {basePath}/providers` (finding F9.1 of the owner's QA of the template), so
+ * a login page renders a button only for a provider that is there, whatever
+ * the web app was built with: a provider whose credentials the server lacks
+ * is not listed, nor the mock where it is off. Rejects with a
+ * `QuickdrawError` when the server cannot be reached or refuses.
+ *
+ * @example
+ * const { data: providers = [] } = useQuery({
+ *   queryKey: ["auth", "providers"],
+ *   queryFn: () => authProviders({ apiUrl: API_URL }),
+ * });
+ */
+declare function authProviders(options?: AuthRoutesTarget): Promise<readonly AuthProviderInfo[]>;
+/**
+ * Signs the user out everywhere: `POST {basePath}/logout-all`, which
+ * revokes every session of the user (the app's `onRevoke` can disconnect
+ * their sockets) and clears this browser's cookie; the stored token is
+ * forgotten either way. Rejects with `UNAUTHENTICATED` when the request
+ * carries no live session, and with a `QuickdrawError` when the server
+ * cannot be reached or refuses.
+ */
+declare function signOutEverywhere(options?: AuthRoutesTarget): Promise<void>;
+
+/** One call, as {@link call} takes it. */
+interface CallRequest {
+    /** The service's name on the wire: the contract's `name`. */
+    readonly service: string;
+    readonly method: string;
+    /** The input; left out of the envelope when `undefined`. */
+    readonly input?: unknown;
+    /** The method's kind, which picks the backoff a `RATE_LIMITED` answer starts. Default `"query"`. */
+    readonly kind?: MethodKind;
+    /** Aborting it cancels the call. */
+    readonly signal?: AbortSignal;
+    /** How long to wait for the answer. Default: the connection's `timeoutMs`. */
+    readonly timeoutMs?: number;
+    /** The version of the result the caller holds; the server answers "not modified" while it is current. */
+    readonly v?: Version;
+    /**
+     * Called with the result the moment the reply arrives, before any frame
+     * the server sent after it is handled; the returned promise settles only
+     * after more microtasks, and a client on Node can handle several frames in
+     * between. What must follow reply order goes here: an optimistic layer
+     * ends at the first newer frame after its call's reply.
+     */
+    readonly onReply?: (result: CallResult) => void;
+}
+/** What a call resolves with: the data, or "not modified" when the `v` it sent is current. */
+type CallResult<Output = unknown> = CallSuccess<Output> | CallNotModified;
+/** True when the server answered that the caller's version is current. */
+declare function isNotModified(result: CallResult): result is CallNotModified;
+/**
+ * True when `error` leaves a call's outcome unknown: a `TIMEOUT` (the
+ * server may still be running it, or ran it and the answer was lost), or the
+ * `INTERNAL` of a call whose connection dropped after it was sent. The write
+ * may have been made: before sending it again, make sure the call is
+ * idempotent (a create that carries an id the client made, which the server
+ * keeps, fails `CONFLICT` the second time instead of writing a second row).
+ * False for a refusal, and for a call that was never sent.
+ *
+ * @example
+ * onError: (error) => setStatus(isUnknownOutcome(error) ? "checking" : "failed")
+ */
+declare function isUnknownOutcome(error: unknown): boolean;
+/**
+ * Calls `request.method` of `request.service` over `connection`. Resolves
+ * with `{ ok: true, d, v? }`, or `{ ok: true, nm: true, v }` when the `v` it
+ * sent is current; rejects with a `QuickdrawError` (see the top of this file
+ * for which code when).
+ *
+ * @example
+ * const reply = await call(connection, { service: "taskService", method: "get", input: { id } });
+ * const task = isNotModified(reply) ? cached : reply.d;
+ */
+declare function call<Output = unknown>(connection: QuickdrawConnection, request: CallRequest): Promise<CallResult<Output>>;
+/**
+ * Calls a method and resolves with its data. For a caller that sends no
+ * version, which is never answered "not modified".
+ */
+declare function callData<Output = unknown>(connection: QuickdrawConnection, request: Omit<CallRequest, "v">): Promise<Output>;
+/**
+ * The default `retry` of query hooks: one more attempt after an `INTERNAL`
+ * error, which includes a dropped connection, or an error that is not a
+ * `QuickdrawError`; none for any other code. A `TIMEOUT` is not retried,
+ * because the server may still be running the call, and `RATE_LIMITED`
+ * waits for the backoff instead.
+ */
+declare function shouldRetry(failureCount: number, error: unknown): boolean;
+
+/** The default `onProtocolMismatch`: reloads the page once per session and server protocol. */
+declare function reloadOncePerSession(mismatch: ProtocolMismatch): void;
+
+/**
+ * A new id for a row the client creates and the server keeps: a version 4
+ * UUID, from `crypto.randomUUID()`, or from `crypto.getRandomValues()` where
+ * that is missing (a page over plain http, which browsers do not give
+ * `randomUUID`). Give it to an item an optimistic update adds and to the
+ * create's input, so the scope's next load can find the item after a lost
+ * answer and `retry()` cannot write twice. Throws a `TypeError` in a runtime
+ * without Web Crypto.
+ *
+ * @example
+ * create.mutate({ id: newId(), chatId, content });
+ */
+declare function newId(): string;
+
+/** A STUN or TURN server, as `RTCIceServer` takes it. */
+interface PeerIceServer {
+    urls: string | string[];
+    username?: string;
+    credential?: string;
+}
+/** What a link makes its `RTCPeerConnection` with. */
+interface PeerConnectionConfig {
+    iceServers: PeerIceServer[];
+}
+
+/**
+ * When a link uses the server's relay: `auto` when the direct path cannot
+ * form or fails, `always` instead of it (no WebRTC at all), `never` (a link
+ * whose direct path fails closes).
+ */
+type RelayMode = "auto" | "always" | "never";
+/** Options of {@link createPeerLink}. */
+interface PeerLinkOptions {
+    /** The app room both sockets are in; the link belongs to it, and ends when this socket leaves it. */
+    readonly room: string;
+    /** The peer's socket id. */
+    readonly to: string;
+    /**
+     * Whether this side makes the offer. One side of a link does; when both
+     * do, the side whose socket id sorts after the other's answers instead.
+     */
+    readonly offerer: boolean;
+    /**
+     * STUN and TURN servers. Default Google's and Cloudflare's public STUN
+     * servers, and no TURN: a pair that cannot reach each other uses the
+     * relay, which is expected, not an error.
+     */
+    readonly iceServers?: readonly PeerIceServer[];
+    /** When the link may use the server's relay. Default `"auto"`. */
+    readonly relay?: RelayMode;
+    /**
+     * Makes the link's `RTCPeerConnection`. Default the platform's
+     * `RTCPeerConnection` when it has one; React Native passes
+     * react-native-webrtc's, Node a WebRTC package's. A link without one uses
+     * the relay.
+     */
+    readonly peerConnection?: (configuration: PeerConnectionConfig) => unknown;
+}
+/** The STUN servers a link asks by default. */
+declare const DEFAULT_ICE_SERVERS: readonly PeerIceServer[];
+/**
+ * Opens a link to socket `options.to` in app room `options.room`, over
+ * WebRTC data channels when it can and the server's relay when it cannot.
+ * The server must serve peer links (`createServer({ peers: true })`), and
+ * both sockets must be in the room. Throws a `TypeError` for bad options,
+ * or when the connection has a link to that peer in that room already.
+ *
+ * @example
+ * const link = createPeerLink(connection, { room: "match:7", to: rivalSocketId, offerer: true });
+ * link.on("message", (data, label) => applyRemote(data));
+ * link.on("open", () => link.send("rel", { hello: "rival" }));
+ */
+declare function createPeerLink(connection: QuickdrawConnection, options: PeerLinkOptions): PeerLink;
+/** A socket of the room signalled this one with no link to it: a link it asks for. */
+interface PeerRequest {
+    readonly room: string;
+    /** The peer's socket id. */
+    readonly from: string;
+    /** The peer's user, as the server named it. */
+    readonly userId: string;
+    /** Answers with a link: `createPeerLink(connection, { room, to: from, offerer: false, ...options })`. */
+    accept(options?: Omit<PeerLinkOptions, "room" | "to" | "offerer">): PeerLink;
+    /** Refuses: the peer's link closes, with `bye`. */
+    reject(): void;
+}
+/**
+ * Calls `listener` when a socket of an app room this connection's socket is
+ * in signals it with no link to it yet: answer with `request.accept()` (or
+ * `createPeerLink` with `offerer: false`) within 15 seconds, or
+ * `request.reject()`. Returns its removal.
+ */
+declare function onPeerRequest(connection: QuickdrawConnection, listener: (request: PeerRequest) => void): () => void;
+
+/** A peer of a host: its socket and its user, as the server named them, and its link. */
+interface HostPeer {
+    readonly socketId: string;
+    readonly userId: string;
+    /**
+     * The host's end of the peer's link: its `clock` (the peer's round trip,
+     * `rtt`) and `setLag`, which lags the peer's messages both ways. The
+     * host's own client has one too, in process.
+     */
+    readonly link: PeerLink;
+}
+/** What a host-served channel's handler receives beside the payload. */
+interface HostChannelContext {
+    /** Who sent it: the user the server named for the peer's socket, and the peer's link. */
+    readonly peer: HostPeer;
+    /** The host's room. */
+    readonly room: string;
+}
+
+/** A host-served channel's handler: it runs once per message, with the payload its schema parsed. */
+type HostChannelHandler<Payload> = (payload: Payload, ctx: HostChannelContext) => void;
+/** One host-served stream's options. */
+interface HostStreamOptions<Item> {
+    /**
+     * Computes a subscriber's seed when it subscribes, at once: the current
+     * state, where the items that follow are deltas. Each item is checked
+     * against the stream's schema. Without it the seed is the latest items
+     * pushed to the scope, as many as the contract's `seed` (default none).
+     */
+    readonly seed?: (scope: string) => readonly Item[];
+}
+/**
+ * `defineHost`'s second argument: one handler per host-served channel of
+ * the contract, and options per host-served stream.
+ */
+type HostImplementation<C extends AnyContract> = {
+    readonly streams?: {
+        readonly [K in HostStreamName<C>]?: HostStreamOptions<StreamItemOf<C, K>>;
+    };
+} & ([HostChannelName<C>] extends [never] ? {
+    readonly channels?: Readonly<Record<string, never>>;
+} : {
+    readonly channels: {
+        readonly [K in HostChannelName<C>]: HostChannelHandler<ChannelPayloadOf<C, K>>;
+    };
+});
+/** A host-served stream, as its host pushes to it. */
+interface HostStream<Item> {
+    /**
+     * Sends `item` to the subscribers of the feed of `scope`, after checking
+     * it against the stream's schema (a `TypeError` when it fails), and keeps
+     * it for the seed. A `RangeError` for an item over the message limit
+     * (`limits.peers.maxMessageBytes` with its message).
+     */
+    push(scope: string, item: Item): void;
+}
+/** A room served by its host's client. */
+interface Host<C extends AnyContract> {
+    readonly room: string;
+    /**
+     * The peers linked to the host now, each with the host's end of its link
+     * (this client too, in process, while its own channels or feeds use the
+     * room).
+     */
+    readonly peers: readonly HostPeer[];
+    /** A host-served stream of the contract. */
+    stream<K extends HostStreamName<C>>(name: K): HostStream<StreamItemOf<C, K>>;
+    /** Stops serving the room: closes every peer's link, and answers no request of it. */
+    close(): void;
+}
+/** What `defineHost` returns: the contract, and how to serve one of its rooms. */
+interface HostDefinition<C extends AnyContract> {
+    readonly contract: C;
+    /**
+     * Serves app room `room` on `connection`, whose socket a method made the
+     * room's host (`ctx.rooms.setHost`). Call it once per room, and `close()`
+     * when the socket is no longer the host (`onHostChange`, a reconnect).
+     */
+    serve(connection: QuickdrawConnection, options: {
+        readonly room: string;
+    }): Host<C>;
+}
+/**
+ * Declares how a client serves a contract's host-served channels and
+ * streams (`serve: "host"`) as the host of an app room: one handler per
+ * channel, and options per stream. Throws a `TypeError` for a handler a
+ * host-served channel lacks, or for a member the room's host does not
+ * serve.
+ *
+ * @example
+ * const worldHost = defineHost(game, {
+ *   channels: { move: (move, { peer }) => world.input(peer.userId, move) },
+ *   streams: { world: { seed: () => [world.snapshot()] } },
+ * });
+ * const host = worldHost.serve(connection, { room: `world:${worldId}` });
+ * host.stream("world").push(worldId, world.snapshot());
+ */
+declare function defineHost<const C extends AnyContract>(contract: C, implementation: HostImplementation<C>): HostDefinition<C>;
+
+/** Hears a room's host change: its socket id, or `null` when the room has none now. */
+type HostListener = (room: string, host: string | null) => void;
+/**
+ * The host of app room `room` (host mode): the socket id the server named
+ * in `qd:host`, or `null` when the room has none or this connection's
+ * socket is not in it. Without React, call it (or `onHostChange`) before
+ * the joining call, so the connection hears the room's host as it joins.
+ */
+declare function hostOf(connection: QuickdrawConnection, room: string): string | null;
+/**
+ * Calls `listener(room, host)` whenever the host of a room this
+ * connection's socket is in changes (`null`: none now, or the socket left
+ * the room or disconnected); returns its removal.
+ */
+declare function onHostChange(connection: QuickdrawConnection, listener: HostListener): () => void;
+
+export { type AuthProviderInfo, type AuthRoutesTarget, type CallRequest, type CallResult, DEFAULT_ICE_SERVERS, type Host, type HostChannelContext, type HostChannelHandler, type HostDefinition, type HostImplementation, type HostListener, type HostPeer, type HostStream, type HostStreamOptions, type PeerConnectionConfig, type PeerIceServer, PeerLink, type PeerLinkOptions, type PeerRequest, QuickdrawConnection, type RelayMode, type SignInUrlOptions, authProviders, call, callData, clearAuthToken, createPeerLink, defineHost, getAuthToken, hostOf, isNotModified, isUnknownOutcome, newId, onHostChange, onPeerRequest, reloadOncePerSession, setAuthToken, shouldRetry, signInUrl, signOut, signOutEverywhere };

package/dist/client/core.js

@@ -0,0 +1,109 @@
+import {
+  authProviders,
+  clearAuthToken,
+  defineHost,
+  getAuthToken,
+  newId,
+  setAuthToken,
+  signInUrl,
+  signOut,
+  signOutEverywhere
+} from "../chunk-Z7I6SONO.js";
+import {
+  DEFAULT_ICE_SERVERS,
+  createPeerLink,
+  onPeerRequest
+} from "../chunk-DNP65TD5.js";
+import {
+  buildBreadcrumbs,
+  createServerCaller,
+  findNavItemByHref,
+  findParentNavItem,
+  formatCurrency,
+  formatDate,
+  formatDateTime,
+  formatNumber,
+  formatPercent,
+  parseJWTPayload,
+  routeRequiresAuth,
+  truncate
+} from "../chunk-CYE4UBOB.js";
+import "../chunk-ASAMUGHG.js";
+import {
+  call,
+  callData,
+  isNotModified,
+  isUnknownOutcome,
+  shouldRetry
+} from "../chunk-NX2V6SIL.js";
+import {
+  DEFAULT_BACKOFF_MS,
+  DEFAULT_SUBSCRIPTION_LANE,
+  createQuickdrawConnection,
+  hostOf,
+  onHostChange,
+  reloadOncePerSession
+} from "../chunk-STH5DLQP.js";
+import {
+  KEY_ROOT,
+  collectionKey,
+  entityKey,
+  methodKey,
+  methodKeyPrefix,
+  serviceKeyPrefix
+} from "../chunk-IIQ3WMJK.js";
+import "../chunk-7473HK24.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 {
+  DEFAULT_BACKOFF_MS,
+  DEFAULT_ICE_SERVERS,
+  DEFAULT_SUBSCRIPTION_LANE,
+  KEY_ROOT,
+  authProviders,
+  buildBreadcrumbs,
+  call,
+  callData,
+  clearAuthToken,
+  collectionKey,
+  createPeerLink,
+  createQuickdrawConnection,
+  createServerCaller,
+  defineHost,
+  entityKey,
+  findNavItemByHref,
+  findParentNavItem,
+  formatCurrency,
+  formatDate,
+  formatDateTime,
+  formatNumber,
+  formatPercent,
+  getAuthToken,
+  hostOf,
+  isNotModified,
+  isUnknownOutcome,
+  methodKey,
+  methodKeyPrefix,
+  newId,
+  onHostChange,
+  onPeerRequest,
+  parseJWTPayload,
+  reloadOncePerSession,
+  routeRequiresAuth,
+  serviceKeyPrefix,
+  setAuthToken,
+  shouldRetry,
+  signInUrl,
+  signOut,
+  signOutEverywhere,
+  truncate
+};
+//# sourceMappingURL=core.js.map

package/dist/client/core.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}