@spooky-sync/core 0.0.1-canary.32 → 0.0.1-canary.320

package/dist/live.d.ts

@@ -0,0 +1,141 @@
+import { r as RefMode } from "./worker-ref-tables.js";
+import { SchemaStructure } from "@spooky-sync/query-builder";
+
+//#region src/live/index.d.ts
+type LiveToken = string | null | undefined;
+/** A token, or a function returning one (called on every connect). */
+type LiveTokenSource = string | (() => LiveToken | Promise<LiveToken>);
+/** The subset of the `surrealdb` SDK's `Surreal` the feed drives. */
+interface LiveSurreal {
+  connect(url: string, options?: Record<string, unknown>): Promise<unknown>;
+  use(what: {
+    namespace: string;
+    database: string;
+  }): Promise<unknown>;
+  authenticate(token: string): Promise<unknown>;
+  query(sql: string, vars?: Record<string, unknown>): PromiseLike<unknown>;
+  liveOf(id: never): PromiseLike<LiveStreamLike>;
+  close(): Promise<unknown>;
+  subscribe?(event: string, listener: (...args: unknown[]) => void): () => void;
+}
+interface LiveStreamLike {
+  subscribe(handler: (message: LiveMessageLike) => void): () => void;
+  kill?(): Promise<void>;
+}
+interface LiveMessageLike {
+  action: string;
+  value: unknown;
+}
+interface LiveFeedOptions {
+  /** SurrealDB endpoint, `wss://host/rpc` (http(s) is rewritten to ws(s)). */
+  endpoint: string;
+  namespace: string;
+  database: string;
+  /**
+   * The session token (`db.auth.token` on the page, `getBridgedToken()` in the
+   * service worker). None: the anonymous `_00_list_ref_anon` table, which
+   * needs `anonymousLiveQueries` on the server.
+   */
+  token?: LiveTokenSource;
+  /** `_00_list_ref` layout. Default `dedicated` (one table per user), as the SSP. */
+  refMode?: RefMode;
+  /** View ttl sent with every registration. Default `10m`, the full client's. */
+  ttl?: string;
+  /** Salt of the `_00_query` keys. Default: a fresh random id per feed. */
+  sessionId?: string;
+  /**
+   * The generated schema. Used to type query params (record ids, datetimes)
+   * exactly like the full client does before registering. Taken from a query
+   * builder's own schema when omitted.
+   */
+  schema?: SchemaStructure;
+  /** The server refused the token. Called once, before the connect rejects. */
+  onUnauthorized?: (error: unknown) => void | Promise<void>;
+  /** Background failures (LIVE, heartbeat, re-reads). Never thrown. */
+  onError?: (error: unknown) => void;
+  /** Deadline for every statement, ms. Default 15000. */
+  timeoutMs?: number;
+  /** Bring your own SDK client (tests, a custom WebSocket implementation). */
+  surreal?: LiveSurreal | (() => LiveSurreal);
+}
+/** `{ surql, params }`, or anything the query builder builds (`FinalQuery`, `InnerQuery`). */
+type LiveQuery = {
+  surql: string;
+  params?: Record<string, unknown>;
+  table?: string;
+} | BuiltQueryLike;
+interface SelectInfoLike {
+  query: string;
+  vars?: Record<string, unknown>;
+}
+interface InnerQueryLike {
+  selectQuery: SelectInfoLike;
+  tableName: string;
+}
+/** A `FinalQuery` (via its `innerQuery`) or an `InnerQuery`. */
+type BuiltQueryLike = {
+  innerQuery: InnerQueryLike;
+} | InnerQueryLike;
+interface LiveChange<T> {
+  added: T[];
+  updated: T[];
+  /** The last known body of each row that left the set. */
+  removed: T[];
+}
+interface LiveHandlers<T> {
+  /** The whole current set: once when it first loads, then after every change. */
+  onSet(rows: T[]): void;
+  /** What changed, after the first set. */
+  onChange?(change: LiveChange<T>): void;
+  /** The registration or a later re-read failed. */
+  onError?(error: unknown): void;
+}
+interface LiveFeedSubscription<T> {
+  /** The first full set; rejects when the registration failed. */
+  readonly ready: Promise<T[]>;
+  /** The current rows, unordered. Empty until `ready`. */
+  rows(): T[];
+  /** The view's `_00_query` key, once computed. */
+  readonly key: string | null;
+  /** Stop listening; releases the server view when nobody else on this feed watches it. */
+  unsubscribe(): Promise<void>;
+}
+interface LiveIdleOptions {
+  /** Give up after this long and resolve `false`. Default 10000. */
+  timeoutMs?: number;
+  /** How long nothing must have arrived. Default 300. */
+  quietMs?: number;
+}
+interface LiveFeed {
+  subscribe<T = Record<string, unknown>>(query: LiveQuery, handlers: LiveHandlers<T>): LiveFeedSubscription<T>;
+  /** Run statements on the feed's connection (small writes, `fn::push::*`). The SDK's result array. */
+  query<T extends unknown[] = unknown[]>(surql: string, vars?: Record<string, unknown>): Promise<T>;
+  /** `true` once every subscription has its first set and nothing arrived for `quietMs`. */
+  idle(options?: LiveIdleOptions): Promise<boolean>;
+  /** Connect now (subscribe/query do it lazily). */
+  connect(): Promise<void>;
+  /** Release every view, kill LIVE, close the socket. Idempotent. */
+  close(): Promise<void>;
+  /** `$auth.id` from the token (`user:abc`), null when anonymous. Known after connect. */
+  readonly userId: string | null;
+  /** The `_00_list_ref` table LIVE watches. Known after connect. */
+  readonly listRefTable: string | null;
+  readonly closed: boolean;
+}
+type LiveFeedErrorCode = 'closed' | 'unauthorized' | 'connect' | 'register' | 'query';
+declare class LiveFeedError extends Error {
+  readonly code: LiveFeedErrorCode;
+  readonly cause?: unknown | undefined;
+  constructor(code: LiveFeedErrorCode, message: string, cause?: unknown | undefined);
+}
+declare function createLiveFeed(options: LiveFeedOptions): LiveFeed;
+/** The register input the full client derives from the same query. */
+declare function liveQueryInput(query: LiveQuery, schema?: SchemaStructure): {
+  table: string;
+  surql: string;
+  params: Record<string, unknown>;
+};
+/** `http(s)://` becomes `ws(s)://`; a bare host gets `/rpc`. */
+declare function liveEndpoint(endpoint: string): string;
+//#endregion
+export { LiveChange, LiveFeed, LiveFeedError, LiveFeedErrorCode, LiveFeedOptions, LiveFeedSubscription, LiveHandlers, LiveIdleOptions, LiveMessageLike, LiveQuery, LiveStreamLike, LiveSurreal, LiveToken, LiveTokenSource, createLiveFeed, liveEndpoint, liveQueryInput };