@spooky-sync/core 0.0.1-canary.38 → 0.0.1-canary.381

package/dist/otel/index.d.ts

@@ -1,4 +1,4 @@
-import { c as PinoTransmit } from "../types.js";
+import { h as PinoTransmit } from "../types.js";
 import { Level } from "pino";
 
 //#region src/otel/index.d.ts

package/dist/pure.d.ts

@@ -0,0 +1,401 @@
+import { a as bucketIdForUser, i as RefMode, n as ANON_USER_ID, o as listRefTableFor, r as DEFAULT_REF_MODE, s as sanitizeUserId, t as ANON_LIST_REF_TABLE } from "./worker-ref-tables.js";
+import { a as PushNotificationAction, c as PushPayloadKind, d as base64UrlToBytes, f as bytesToBase64Url, i as PushNotification, l as PushUrgency, m as sameBytes, n as BridgeTokenMessage, o as PushOp, p as isPushPayload, r as PUSH_PAYLOAD_VERSION, s as PushPayload, t as BridgeSignOutMessage, u as WebPushClientMessage } from "./worker-types.js";
+import { Duration, RecordId } from "surrealdb";
+import { ColumnSchema, RecordId as RecordId$1, SchemaStructure } from "@spooky-sync/query-builder";
+import "pino";
+
+//#region src/query/hash.d.ts
+/**
+ * Hash inputs for the two query keys. Kept byte-identical to the previous
+ * implementation (`DataModule.calculateHash` / `calculateMembershipKey`):
+ * the salted key names the remote `_00_query` row, the unsalted one names the
+ * durable `_00_view` row, and both are `sha256(JSON.stringify(input))`.
+ */
+interface QueryKeyInput {
+  surql: string;
+  params: Record<string, unknown>;
+}
+/** Session-salted: two tabs of one user must not share a remote view. */
+declare const queryHashInput: (input: QueryKeyInput, sessionId: string | null) => string;
+/** Session-independent: survives reload and bucket switch. */
+declare const viewKeyInput: (input: QueryKeyInput) => string;
+//#endregion
+//#region src/modules/auth/impersonation.d.ts
+/**
+ * Admin impersonation, client side.
+ *
+ * The server does the enforcing (see `impersonation_remote.surql` in the CLI):
+ * an admin calls `fn::_00_impersonate::start`, receives a token for the
+ * `_00_impersonate` access method, and authenticates with it, so `$auth.id` is
+ * the target user. Everything here is state and timers around that:
+ *
+ * - the admin's own token is kept under {@link ORIGIN_TOKEN_KEY} so Stop (and a
+ *   reload in between) can return to it;
+ * - the impersonation state is derived from the token's claims, never stored
+ *   separately, so it cannot disagree with the session actually in use;
+ * - the token is re-signed before it expires, and the session is polled so a
+ *   stop or revocation made elsewhere reaches an open WebSocket quickly.
+ */
+/** Access method impersonation tokens are issued for. */
+declare const IMPERSONATION_ACCESS = "_00_impersonate";
+/** Persistence key holding the admin's own token while impersonating. */
+
+interface TokenClaims {
+  access: string | null;
+  userId: string | null;
+  exp: number | null;
+  impersonation: {
+    session: string;
+    admin: string;
+  } | null;
+}
+/**
+ * Read the claims of a SurrealDB record-access JWT WITHOUT verifying it. The
+ * server still enforces the token on every request; this is only so the client
+ * can act on what it already holds before a round trip completes.
+ *
+ * Returns nulls on any malformed input.
+ */
+declare function decodeTokenClaims(token: string): TokenClaims;
+/** The impersonation a token represents, or null for a regular session. */
+//#endregion
+//#region src/utils/surql.d.ts
+interface TxQuery {
+  readonly __brand: 'TxQuery';
+  readonly sql: string;
+  readonly statementCount: number;
+}
+interface SealOptions {
+  /** 0-based index of the inner statement to extract. Default: last statement. */
+  resultIndex?: number;
+}
+interface SealedQuery<T = void> {
+  readonly sql: string;
+  readonly extract: (results: unknown[]) => T;
+}
+interface SurqlHelper {
+  seal(query: string): string;
+  seal<T = void>(query: TxQuery, options?: SealOptions): SealedQuery<T>;
+  tx(queries: string[]): TxQuery;
+  selectById(idVar: string, returnValues: string[]): string;
+  selectByFieldsAnd(table: string, whereVar: ({
+    field: string;
+    variable: string;
+  } | string)[], returnValues: ({
+    field: string;
+    alias: string;
+  } | string)[]): string;
+  create(idVar: string, dataVar: string): string;
+  createSet(idVar: string, keyDataVars: ({
+    key: string;
+    variable: string;
+  } | {
+    statement: string;
+  } | string)[]): string;
+  upsert(idVar: string, dataVar: string): string;
+  upsertMerge(idVar: string, dataVar: string): string;
+  updateMerge(idVar: string, dataVar: string): string;
+  updateSet(idVar: string, keyDataVar: ({
+    key: string;
+    variable: string;
+  } | {
+    statement: string;
+  } | string)[]): string;
+  delete(idVar: string): string;
+  let(name: string, query: string): string;
+  createMutation(t: MutationEventType, mutationIdVar: string, recordIdVar: string, dataVar?: string, beforeRecordVar?: string): string;
+  returnObject(entries: {
+    key: string;
+    variable: string;
+  }[]): string;
+}
+declare const surql: SurqlHelper;
+//#endregion
+//#region src/types.d.ts
+
+/**
+ * Supported Time-To-Live (TTL) values for cached queries.
+ * Format: number + unit (m=minutes, h=hours, d=days).
+ */
+type QueryTimeToLive = '1m' | '5m' | '10m' | '15m' | '20m' | '25m' | '30m' | '1h' | '2h' | '3h' | '4h' | '5h' | '6h' | '7h' | '8h' | '9h' | '10h' | '11h' | '12h' | '1d';
+/**
+ * Refresh behavior for `preload` when the data is already cached locally (warm).
+ * The FIRST load (cold) always fetches + blocks regardless.
+ * - `onUse` (default): do nothing when warm — the data freshens on use, when the
+ *   real `useQuery` mounts and registers its live view. No network on load.
+ * - `background`: return instantly, but kick a one-time silent refetch.
+ * - `stale`: like `background`, but only if the cached copy is older than
+ *   `staleTime`.
+ */
+
+/**
+ * One changed row delivered inline on a LIVE notification, when the
+ * subscription was opened with the body joined on (see
+ * {@link Sp00kyConfig.liveInlineBodies}). `version` is the edge's `version`,
+ * i.e. the same number the membership read would have reported for this row.
+ */
+interface InlineRow {
+  id: string;
+  version: number;
+  record: Record<string, unknown>;
+}
+/**
+ * A row that joined a query's view, or moved to a newer version, as one LIVE
+ * notification on `_00_list_ref` reports it: the edge's `out` and `version`.
+ * The client commits it to the query's membership straight away instead of
+ * re-reading the edges (see `sync/live.saga.ts`).
+ */
+
+type RecordVersionArray = Array<[string, number]>;
+/**
+ * Represents the difference between two record version sets.
+ * Used for synchronizing local and remote states.
+ */
+
+/**
+ * What the server's `_00_query` row says about a view, read alongside its
+ * `_00_list_ref` edges (registration, the poll, a targeted re-read).
+ *
+ * - `present: false`: the row is not there (or not readable). The SSP no
+ *   longer has this view: a TTL sweep, an SSP reset, a scheduler wipe. An
+ *   empty edge set read at the same time is NOT "no rows", it is "no view".
+ * - `state: 'materializing'`: the SSP has (re)computed the set and its edges
+ *   are in flight; an empty read is "not landed yet".
+ * - `state: 'ready'`: the edges are committed (flipped in the same
+ *   transaction), so `rowCount === 0` with no edges is a real empty result.
+ * - `state: null`: a server that predates the marker; only `rowCount` can be
+ *   used, with its `> 0` = flush window / `0` = empty ambiguity.
+ */
+interface ServerViewMeta {
+  present: boolean;
+  /** `_00_query.rowCount`; `null` when unreadable. */
+  rowCount: number | null;
+  state: 'materializing' | 'ready' | null;
+}
+/** Outcome of handing a server id-set to `DataModule.updateQueryRemoteArray`. */
+
+type MutationEventType = 'create' | 'update' | 'delete';
+/**
+ * Represents a mutation event (create, update, delete) to be synchronized.
+ */
+//#endregion
+//#region src/kernel/effects.d.ts
+type Vars = Record<string, unknown>;
+/** What the in-browser SSP needs to build a local view. */
+//#endregion
+//#region src/query/sql.d.ts
+/** Every SurrealQL statement the query side sends, as pure builders. */
+declare const VIEW_TABLE = "_00_view";
+declare const LEGACY_VIEW_TABLE = "_00_window";
+declare const viewRecordId: (viewKey: string) => RecordId<string>;
+/**
+ * The durable `_00_view` row: the confirmed membership plus the subquery
+ * children, which the GC must keep and a cold scan may paint as much as the
+ * members.
+ */
+declare const viewRow: (ids: RecordVersionArray, children: RecordVersionArray, confirmed: boolean, now: number) => Record<string, unknown>;
+/** Every `_00_view` row: the durable view index and the GC read it. */
+declare const readViewRows: () => string;
+/** Copy every legacy `_00_window` row into `_00_view` once. */
+declare const readLegacyViewRows: () => string;
+declare const countViewRows: () => string;
+declare const listRefSelect: (table: string) => string;
+declare const subqueryListRefSelect: (table: string) => string;
+declare const queryRowCountSelect: () => string;
+declare const listRefBatchSelect: (table: string) => string;
+declare const queryRowCountBatchSelect: () => string;
+/** The single-query read: edges, meta, subquery children in one request. */
+declare const singleSnapshotSelect: (table: string) => string;
+/** The many-query read: all edges + all metas in one request. */
+declare const batchSnapshotSelect: (table: string) => string;
+/**
+ * The session's one LIVE subscription on its `_00_list_ref` table.
+ *
+ * `inlineBodies` adds `FETCH out`, which resolves the edge's target into the
+ * notification so the body arrives with the doorbell.
+ *
+ * On the anon table it is filtered to this client's own edges. Every
+ * signed-out session shares that table, so unfiltered each one received (and
+ * the server fetched a body for) every anonymous edge change of every other
+ * session, and the client then dropped all but its own. An edge carries the
+ * `session::id()` of whichever socket last registered its view, which is a
+ * socket of this client but not necessarily the current one: a view stays
+ * registered across a reconnect, and a reload keeps its salt and its views,
+ * so their older edges still name an earlier socket. `sessionIds` are those
+ * earlier sockets. The current one is matched by `session::id()` itself,
+ * which SurrealDB evaluates in the subscriber's own session, so the filter
+ * holds before the client has learned its new id.
+ *
+ * The cast is load-bearing: `session::id()` is a uuid, `clientId` a string,
+ * and without it nothing matches. Per-user tables need no filter.
+ */
+declare function listRefLive(table: string, opts: {
+  inlineBodies: boolean;
+  sessionIds: ReadonlyArray<string>;
+}): {
+  sql: string;
+  vars?: Vars;
+};
+interface RegisterPayload {
+  id: RecordId<string>;
+  surql: string;
+  params: Record<string, unknown>;
+  ttl: string;
+  /**
+   * The registering page's secret. `fn::query::register` forwards only its
+   * hash, and the SSP lets a registration onto an existing anonymous view
+   * only with the hash that view was registered with: every signed-out
+   * visitor is `anon`, and anyone can read an anonymous view's id. Kept out
+   * of `params`, which name the computation the SSP shares between views.
+   */
+  owner?: string;
+}
+/** Register + read back edges/meta/children in ONE request. */
+declare const registerSelect: (table: string) => string;
+declare const registerVars: (payload: RegisterPayload) => Vars;
+/** One heartbeat statement per view id; result index i answers id i. */
+declare function heartbeatBatch(ids: ReadonlyArray<RecordId<string>>): {
+  sql: string;
+  vars: Vars;
+};
+/**
+ * Hand back view ids this page no longer answers to. Per id,
+ * `fn::query::unsubscribe` drops this socket's entry and deletes the row when
+ * nobody else watches it; `fn::query::leave` then drops the entries of this
+ * page's earlier sockets (a reconnect re-registered under a new session id)
+ * and pulls the expiry in when none remain. Result index 2i answers the
+ * unsubscribe of id i, 2i + 1 its leave.
+ */
+declare function releaseBatch(ids: ReadonlyArray<RecordId<string>>, sessionIds: ReadonlyArray<string>): {
+  sql: string;
+  vars: Vars;
+};
+/** A heartbeat answer whose statement matched no row: the view was reclaimed. */
+declare const heartbeatRowGone: (result: unknown) => boolean;
+/**
+ * The pagehide release: one bare statement for `beaconSql`, which has no params
+ * channel, so ids are inlined. Only shapes the client minted itself get in, a
+ * `_00_query:<sha256>` id and a UUID session id, so nothing else is ever
+ * interpolated. `null` when there is nothing the server could act on: with no
+ * session ids it could not tell this page's entries from anyone else's.
+ */
+declare function leaveViewsBeacon(ids: ReadonlyArray<unknown>, sessionIds: ReadonlyArray<string>): string | null;
+declare const bodySelect: () => string;
+/** Local transaction that MERGEs many fetched bodies. */
+declare function upsertBodiesTx(records: ReadonlyArray<{
+  id: unknown;
+  content: Record<string, unknown>;
+}>): {
+  query: SealedQuery<unknown>;
+  vars: Vars;
+};
+//#endregion
+//#region src/query/membership.d.ts
+/** The `{ rowCount, state }` object the row-count selects return per row. */
+interface QueryMetaRow {
+  id?: RecordId<string>;
+  rowCount?: number | null;
+  state?: string | null;
+}
+declare function metaFromRow(row: QueryMetaRow | null | undefined): ServerViewMeta;
+/** Collapse duplicate `(id, version)` pairs to one per id, keeping the highest version. */
+declare function dedupeRecordVersions(pairs: RecordVersionArray): RecordVersionArray;
+/**
+ * A statement that did not answer (an ERR, or no result at all). Kept apart
+ * from a `null` result, which is the server saying "no such row": reading a
+ * failed statement as a missing row turned every timeout under load into a
+ * lost view and re-registered it, over and over (whitepawn, 2026-09-16).
+ */
+declare const FAILED: unique symbol;
+type Answer<T> = T | null | typeof FAILED;
+interface ListRefSnapshot {
+  primary: RecordVersionArray;
+  subquery: RecordVersionArray;
+  meta: ServerViewMeta;
+}
+/**
+ * Fold the single-query statement batch (edges, meta, children) into a
+ * snapshot. `null` when any of the three did not answer: half an answer is
+ * not one, and a missing meta would read as a lost view.
+ */
+declare function snapshotFromSingle(items: Answer<Array<{
+  out: RecordId<string>;
+  version: number;
+}>>, metaRow: Answer<QueryMetaRow>, children: Answer<Array<{
+  out: RecordId<string>;
+  version: number;
+}>>): ListRefSnapshot | null;
+/**
+ * Fold the many-query statement batch into one snapshot per hash. Every hash
+ * in `hashById` gets a snapshot; a query whose row did not come back reads
+ * `present: false`. Empty when either statement did not answer.
+ */
+//#endregion
+//#region src/utils/edges.d.ts
+/**
+ * Reading `_00_list_ref` edges as a LIVE notification delivers them. Pure, so
+ * both the full client and the wasm-free live feed (`@spooky-sync/core/live`)
+ * decode the same wire shape the same way.
+ */
+/** The hash a `_00_list_ref` edge belongs to: the id part of its `in` (`_00_query:<hash>`). */
+declare function hashOfEdge(value: unknown): string | null;
+/**
+ * The row an edge notification carries, when the subscription joined it on.
+ *
+ * Without `FETCH out` the edge's `out` is a record id and there is nothing to
+ * land, so this returns null and the caller falls back to fetching the body.
+ * It also returns null for a row the session may not read (the join yields
+ * `out: null`) and for an edge whose target has been deleted.
+ */
+declare function rowOfEdge(value: unknown): InlineRow | null;
+/**
+ * The membership change a `CREATE` or `UPDATE` notification reports: the
+ * edge's target joined the view (or its version moved). Null for anything a
+ * re-read must settle instead: a `DELETE` (a row leaving, or every edge of a
+ * view being rewritten), a subquery child (`parent` set), or an edge missing
+ * its target or version. With `FETCH out` the target is the joined row, whose
+ * `id` is the record id.
+ */
+
+//#endregion
+//#region src/utils/parser.d.ts
+/**
+ * Parse a QUERY's params. Unlike a record's fields, a param name is not always a
+ * column: an `_or` branch binds under a synthetic `white__or0` (see
+ * `orParamName` in @spooky-sync/query-builder), and the surql that references it
+ * is already written. So resolve the column through the synthetic name, and keep
+ * a param we cannot type rather than dropping it.
+ *
+ * Dropping was the bug: `parseParams` kept only column-named params, so every
+ * `_or` query registered with `$or0`/`$or1` unbound and matched no rows at all,
+ * silently (rowCount 0, errorCount 0).
+ */
+declare function parseQueryParams(tableSchema: Record<string, ColumnSchema>, params: Record<string, any>): Record<string, any>;
+//#endregion
+//#region src/utils/index.d.ts
+declare const encodeRecordId: (recordId: RecordId<string>) => string;
+declare const parseRecordIdString: (id: string) => RecordId<string>;
+/**
+ * Parse duration string or Duration object to milliseconds
+ */
+declare function parseDuration(duration: QueryTimeToLive | Duration): number;
+//#endregion
+//#region src/utils/sha256.d.ts
+/**
+ * Lowercase hex SHA-256 of a UTF-8 string, through WebCrypto.
+ *
+ * Pure and dependency free so it can live in `@spooky-sync/core/pure` and run
+ * in a service worker, a dedicated worker or Node (`globalThis.crypto` is
+ * there on Node 19+). Query keys are `sha256Hex(JSON.stringify(..))`, see
+ * `query/hash.ts`.
+ */
+declare function sha256Hex(input: string): Promise<string>;
+//#endregion
+//#region src/pure.d.ts
+/**
+ * The remote `_00_query` key of a query for one session salt: what the full
+ * client names its view (`_00_query:<key>`).
+ */
+declare function queryKey(input: QueryKeyInput, sessionId: string | null): Promise<string>;
+//#endregion
+export { ANON_LIST_REF_TABLE, ANON_USER_ID, type Answer, BridgeSignOutMessage, BridgeTokenMessage, DEFAULT_REF_MODE, FAILED, IMPERSONATION_ACCESS, LEGACY_VIEW_TABLE, type ListRefSnapshot, PUSH_PAYLOAD_VERSION, PushNotification, PushNotificationAction, PushOp, PushPayload, PushPayloadKind, PushUrgency, type QueryKeyInput, type QueryMetaRow, type RefMode, RegisterPayload, type SealOptions, type SealedQuery, type SurqlHelper, type TokenClaims, type TxQuery, VIEW_TABLE, WebPushClientMessage, base64UrlToBytes, batchSnapshotSelect, bodySelect, bucketIdForUser, bytesToBase64Url, countViewRows, decodeTokenClaims, dedupeRecordVersions, encodeRecordId, hashOfEdge, heartbeatBatch, heartbeatRowGone, isPushPayload, leaveViewsBeacon, listRefBatchSelect, listRefLive, listRefSelect, listRefTableFor, metaFromRow, parseDuration, parseQueryParams, parseRecordIdString, queryHashInput, queryKey, queryRowCountBatchSelect, queryRowCountSelect, readLegacyViewRows, readViewRows, registerSelect, registerVars, releaseBatch, rowOfEdge, sameBytes, sanitizeUserId, sha256Hex, singleSnapshotSelect, snapshotFromSingle, subqueryListRefSelect, surql, upsertBodiesTx, viewKeyInput, viewRecordId, viewRow };

package/dist/pure.js

@@ -0,0 +1,24 @@
+import { A as releaseBatch, B as listRefTableFor, C as listRefSelect, D as readViewRows, E as readLegacyViewRows, F as viewRow, G as viewKeyInput, H as surql, I as ANON_LIST_REF_TABLE, L as ANON_USER_ID, M as subqueryListRefSelect, N as upsertBodiesTx, O as registerSelect, P as viewRecordId, R as DEFAULT_REF_MODE, S as listRefLive, T as queryRowCountSelect, U as sha256Hex, V as sanitizeUserId, W as queryHashInput, _ as countViewRows, a as metaFromRow, b as leaveViewsBeacon, f as parseQueryParams, g as bodySelect, h as batchSnapshotSelect, i as dedupeRecordVersions, j as singleSnapshotSelect, k as registerVars, l as parseDuration, m as VIEW_TABLE, n as rowOfEdge, o as snapshotFromSingle, p as LEGACY_VIEW_TABLE, r as FAILED, s as encodeRecordId, t as hashOfEdge, u as parseRecordIdString, v as heartbeatBatch, w as queryRowCountBatchSelect, x as listRefBatchSelect, y as heartbeatRowGone, z as bucketIdForUser } from "./worker-edges.js";
+import { n as decodeTokenClaims, t as IMPERSONATION_ACCESS } from "./worker-impersonation.js";
+import { a as sameBytes, i as isPushPayload, n as base64UrlToBytes, r as bytesToBase64Url, t as PUSH_PAYLOAD_VERSION } from "./worker-types.js";
+
+//#region src/pure.ts
+/**
+* `@spooky-sync/core/pure`: the side-effect-free builders of the sync protocol.
+*
+* Everything here is plain functions and constants over `surrealdb` value
+* types: no wasm, no logger, no `window`/`document`/`localStorage`. Safe to
+* import from a service worker, a dedicated worker or Node. The full client
+* imports the same modules, so what this entry builds is byte for byte what
+* `Sp00kyClient` sends.
+*/
+/**
+* The remote `_00_query` key of a query for one session salt: what the full
+* client names its view (`_00_query:<key>`).
+*/
+function queryKey(input, sessionId) {
+	return sha256Hex(queryHashInput(input, sessionId));
+}
+
+//#endregion
+export { ANON_LIST_REF_TABLE, ANON_USER_ID, DEFAULT_REF_MODE, FAILED, IMPERSONATION_ACCESS, LEGACY_VIEW_TABLE, PUSH_PAYLOAD_VERSION, VIEW_TABLE, base64UrlToBytes, batchSnapshotSelect, bodySelect, bucketIdForUser, bytesToBase64Url, countViewRows, decodeTokenClaims, dedupeRecordVersions, encodeRecordId, hashOfEdge, heartbeatBatch, heartbeatRowGone, isPushPayload, leaveViewsBeacon, listRefBatchSelect, listRefLive, listRefSelect, listRefTableFor, metaFromRow, parseDuration, parseQueryParams, parseRecordIdString, queryHashInput, queryKey, queryRowCountBatchSelect, queryRowCountSelect, readLegacyViewRows, readViewRows, registerSelect, registerVars, releaseBatch, rowOfEdge, sameBytes, sanitizeUserId, sha256Hex, singleSnapshotSelect, snapshotFromSingle, subqueryListRefSelect, surql, upsertBodiesTx, viewKeyInput, viewRecordId, viewRow };