@spooky-sync/core 0.0.1-canary.69 → 0.0.1-canary.70

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { C as UpdateOptions, E as EventSystem, S as StoreType, T as EventDefinition, _ as RecordVersionDiff, a as MutationCallback, b as Sp00kyQueryResult, c as PersistenceClient, d as QueryConfigRecord, f as QueryHash, g as RecordVersionArray, h as QueryUpdateCallback, i as MATERIALIZATION_SAMPLE_WINDOW, l as PinoTransmit, m as QueryTimeToLive, n as EventSubscriptionOptions, o as MutationEvent, p as QueryState, r as Level, s as MutationEventType, t as DebounceOptions, u as QueryConfig, v as RunOptions, w as Logger$1, x as Sp00kyQueryResultPromise, y as Sp00kyConfig } from "./types.js";
+import { A as Logger$1, C as RunOptions, D as StoreType, E as Sp00kyQueryResultPromise, M as EventSystem, O as TimingPhase, S as RegistrationTimings, T as Sp00kyQueryResult, _ as QueryTimeToLive, a as MutationCallback, b as RecordVersionArray, c as PersistenceClient, d as QueryConfig, f as QueryConfigRecord, g as QueryStatusCallback, h as QueryStatus, i as MATERIALIZATION_SAMPLE_WINDOW, j as EventDefinition, k as UpdateOptions, l as PhaseStat, m as QueryState, n as EventSubscriptionOptions, o as MutationEvent, p as QueryHash, r as Level, s as MutationEventType, t as DebounceOptions, u as PinoTransmit, v as QueryTimings, w as Sp00kyConfig, x as RecordVersionDiff, y as QueryUpdateCallback } from "./types.js";
 import * as surrealdb0 from "surrealdb";
 import { Duration, RecordId, Surreal as Surreal$1, SurrealTransaction } from "surrealdb";
 import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, GetTable, QueryBuilder, QueryOptions, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
@@ -57,7 +57,23 @@ declare class LocalDatabaseService extends AbstractDatabaseService {
   constructor(config: Sp00kyConfig<any>['database'], logger: Logger$1);
   getConfig(): Sp00kyConfig<any>['database'];
   connect(): Promise<void>;
+  private unloadCloseRegistered;
+  /**
+   * Close the local DB on page unload so the SurrealDB-WASM worker releases its
+   * IndexedDB connection cleanly. Without this, the previous page's connection
+   * lingers; the next load's `client.connect` opens the store but the first
+   * write transaction in `client.use` hits an "IndexedDB error" — which then
+   * (mis)triggered the corrupt-store recovery and WIPED the cache on every
+   * reload, making warm loads as slow as cold ones. `pagehide` is the reliable
+   * unload signal (fires on bfcache + normal navigation); `close()` is async but
+   * the WASM worker initiates the IndexedDB connection teardown synchronously.
+   */
+  private registerUnloadClose;
+  private openStore;
 }
+/** True for the SurrealDB-WASM error raised when its IndexedDB-backed key-value
+ *  store can't be opened (corrupt / version-incompatible / blocked). Exported
+ *  for unit testing the error-message match. */
 //#endregion
 //#region src/services/database/remote.d.ts
 declare class RemoteDatabaseService extends AbstractDatabaseService {
@@ -77,6 +93,12 @@ interface WasmStreamUpdate {
   query_id: string;
   result_hash: string;
   result_data: RecordVersionArray;
+  timing_store_apply_ms?: number;
+  timing_circuit_step_ms?: number;
+  timing_transform_ms?: number;
+  timing_parse_ms?: number;
+  timing_plan_ms?: number;
+  timing_snapshot_ms?: number;
 }
 //#endregion
 //#region src/services/stream-processor/index.d.ts
@@ -103,6 +125,19 @@ interface StreamUpdate {
    * for the initial register_view snapshot.
    */
   materializationTimeMs?: number;
+  /** SSP internal sub-phase timings (ms) for this ingest, from the WASM binding. */
+  storeApplyMs?: number;
+  circuitStepMs?: number;
+  transformMs?: number;
+  /**
+   * One-shot registration timings (ms). Only set on the StreamUpdate returned
+   * by `registerQueryPlan` (the register_view snapshot), not on ingest updates.
+   */
+  registration?: {
+    parseMs: number;
+    planMs: number;
+    snapshotMs: number;
+  };
 }
 type StreamProcessorEvents = {
   stream_update: EventDefinition<'stream_update', StreamUpdate[]>;
@@ -122,6 +157,8 @@ declare class StreamProcessorService {
   private processor;
   private isInitialized;
   private receivers;
+  private batching;
+  private batchBuffer;
   constructor(events: EventSystem<StreamProcessorEvents>, db: LocalDatabaseService, persistenceClient: PersistenceClient, logger: Logger);
   /**
    * Add a receiver for stream updates.
@@ -129,12 +166,53 @@ declare class StreamProcessorService {
    */
   addReceiver(receiver: StreamUpdateReceiver): void;
   private notifyUpdates;
+  private dispatchUpdates;
+  /**
+   * Ingest a batch of record changes as a single bulk operation, firing only
+   * one coalesced `StreamUpdate` per affected query once every record has been
+   * ingested (instead of one update per record). Use this whenever multiple
+   * records land at once — e.g. sync fetching N missing rows — so a list query
+   * re-runs and the UI re-renders once for the whole batch rather than
+   * row-by-row.
+   *
+   * Internally opens a coalescing window, ingests each record, then flushes;
+   * processor state is persisted once for the whole batch. No-op for an empty
+   * batch.
+   */
+  ingestMany(records: Array<{
+    table: string;
+    op: 'CREATE' | 'UPDATE' | 'DELETE';
+    id: string;
+    record: any;
+  }>): void;
+  /**
+   * Open a coalescing window. While open, the per-record stream updates
+   * emitted by `ingest` are buffered (one entry per queryHash) instead of
+   * dispatched. Always paired with `flushCoalescing()` in a try/finally by
+   * `ingestMany` so the window always closes — otherwise the processor stays
+   * stuck buffering forever.
+   *
+   * No-op if a window is already open (nested batches aren't expected here).
+   */
+  private beginCoalescing;
+  /**
+   * Close the coalescing window and flush: dispatch one coalesced
+   * `StreamUpdate` per buffered queryHash, then persist processor state once
+   * for the whole batch (instead of once per ingest).
+   */
+  private flushCoalescing;
   /**
    * Initialize the WASM module and processor.
    * This must be called before using other methods.
    */
   init(): Promise<void>;
   loadState(): Promise<void>;
+  /**
+   * Seed per-table `select` permission predicates ({ [table]: whereText }).
+   * Must run after the processor exists and before any `register_view`, else
+   * non-`_00_` tables are default-denied and registration fails.
+   */
+  setPermissions(permissions: Record<string, string>): void;
   saveState(): Promise<void>;
   /**
    * Ingest a record change into the processor.
@@ -409,6 +487,28 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   subscribe(queryHash: string, callback: (records: Record<string, any>[]) => void, options?: {
     immediate?: boolean;
   }): Promise<() => void>;
+  /**
+   * Opt-in eager teardown for a query whose last subscriber has gone away
+   * (e.g. a viewport-windowed list cancelling an off-screen window). No-op
+   * while any subscriber remains. Tears down the remote `_00_query` view +
+   * local WASM view instead of waiting for the TTL sweep. Default behavior
+   * (no call here) keeps the view resident for cheap re-subscription.
+   */
+  deregisterQuery(queryHash: string): void;
+  /**
+   * Subscribe to a query's fetch-status changes (idle/fetching). With
+   * `{ immediate: true }` the callback fires synchronously with the current
+   * status. Powers the `useQuery` hook's `isFetching()` accessor.
+   */
+  subscribeQueryStatus(queryHash: string, callback: QueryStatusCallback, options?: {
+    immediate?: boolean;
+  }): () => void;
+  /**
+   * Report the frontend processing time (ms) a client framework spent applying
+   * an update for a query (e.g. `useQuery`'s `reconcile()`), so DevTools/MCP can
+   * surface the "frontend" phase of the per-query timing breakdown.
+   */
+  reportFrontendTiming(queryHash: string, ms: number): void;
   run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(backend: B, path: R, payload: RoutePayload<S, B, R>, options?: RunOptions): Promise<void>;
   bucket<B extends BucketNames<S>>(name: B): BucketHandle;
   create(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
@@ -438,4 +538,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PinoTransmit, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryTimeToLive, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };
+export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };