@spooky-sync/core 0.0.1-canary.6 → 0.0.1-canary.60

package/dist/index.d.ts

@@ -1,132 +1,10 @@
+import { C as Logger$1, S as UpdateOptions, T as EventSystem, _ as RunOptions, a as MutationEvent, b as Sp00kyQueryResultPromise, c as PinoTransmit, d as QueryHash, f as QueryState, g as RecordVersionDiff, h as RecordVersionArray, i as MutationCallback, l as QueryConfig, m as QueryUpdateCallback, n as EventSubscriptionOptions, o as MutationEventType, p as QueryTimeToLive, r as Level, s as PersistenceClient, t as DebounceOptions, u as QueryConfigRecord, v as Sp00kyConfig, w as EventDefinition, x as StoreType, y as Sp00kyQueryResult } from "./types.js";
 import * as surrealdb0 from "surrealdb";
-import { Duration, RecordId, Surreal, SurrealTransaction } from "surrealdb";
-import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, GetTable, QueryBuilder, QueryOptions, RecordId as RecordId$1, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
-import { Level, Level as Level$1, Logger } from "pino";
+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";
+import { Logger } from "pino";
+import { LoroDoc } from "loro-crdt";
 
-//#region src/events/index.d.ts
-/**
- * Utility type to define the payload structure of an event.
- * If the payload type P is never, it defines payload as undefined.
- */
-type EventPayloadDefinition<P> = [P] extends [never] ? {
-  payload: undefined;
-} : {
-  payload: P;
-};
-/**
- * Defines the structure of an event with a specific type and payload.
- * @template T The string literal type of the event.
- * @template P The type of the event payload.
- */
-type EventDefinition<T extends string, P> = {
-  type: T;
-} & EventPayloadDefinition<P>;
-/**
- * A map of event types to their definitions.
- * Keys are event names, values are EventDefinitions.
- */
-type EventTypeMap = Record<string, EventDefinition<any, unknown> | EventDefinition<any, never>>;
-/**
- * Options for pushing/emitting events.
- */
-interface PushEventOptions {
-  /** Configuration for debouncing the event. */
-  debounced?: {
-    key: string;
-    delay: number;
-  };
-}
-/**
- * Extracts the full Event object type from the map for a given key.
- */
-type Event<E extends EventTypeMap, T extends EventType<E>> = E[T];
-/**
- * Extracts the payload type from the map for a given key.
- */
-type EventPayload<E extends EventTypeMap, T extends EventType<E>> = E[T]['payload'];
-/**
- * Array of available event type keys.
- */
-type EventTypes<E extends EventTypeMap> = (keyof E)[];
-/**
- * Represents a valid key (event name) from the EventTypeMap.
- */
-type EventType<E extends EventTypeMap> = keyof E;
-/**
- * Function signature for an event handler.
- */
-type EventHandler<E extends EventTypeMap, T extends EventType<E>> = (event: Event<E, T>) => void;
-/**
- * Options when subscribing to an event.
- */
-type EventSubscriptionOptions$1 = {
-  /** If true, the handler will be called immediately with the last emitted event of this type (if any). */
-  immediately?: boolean;
-  /** If true, the subscription will be automatically removed after the first event is handled. */
-  once?: boolean;
-};
-/**
- * A type-safe event system that handles subscription, emission (including debouncing), and buffering of events.
- * @template E The EventTypeMap defining all supported events.
- */
-declare class EventSystem<E extends EventTypeMap> {
-  private _eventTypes;
-  private subscriberId;
-  private isProcessing;
-  private buffer;
-  private subscribers;
-  private subscribersTypeMap;
-  private lastEvents;
-  private debouncedEvents;
-  constructor(_eventTypes: EventTypes<E>);
-  get eventTypes(): EventTypes<E>;
-  /**
-   * Subscribes a handler to a specific event type.
-   * @param type The event type to subscribe to.
-   * @param handler The function to call when the event occurs.
-   * @param options Subscription options (once, immediately).
-   * @returns A subscription ID that can be used to unsubscribe.
-   */
-  subscribe<T extends EventType<E>>(type: T, handler: EventHandler<E, T>, options?: EventSubscriptionOptions$1): number;
-  /**
-   * Subscribes a handler to multiple event types.
-   * @param types An array of event types to subscribe to.
-   * @param handler The function to call when any of the events occur.
-   * @param options Subscription options.
-   * @returns An array of subscription IDs.
-   */
-  subscribeMany<T extends EventType<E>>(types: T[], handler: EventHandler<E, T>, options?: EventSubscriptionOptions$1): number[];
-  /**
-   * Unsubscribes a specific subscription by ID.
-   * @param id The subscription ID returned by subscribe().
-   * @returns True if the subscription was found and removed, false otherwise.
-   */
-  unsubscribe(id: number): boolean;
-  /**
-   * Emits an event with the given type and payload.
-   * @param type The type of event to emit.
-   * @param payload The data associated with the event.
-   */
-  emit<T extends EventType<E>, P extends EventPayload<E, T>>(type: T, payload: P): void;
-  /**
-   * Adds a fully constructed event object to the system.
-   * Similar to emit, but takes the full event object directly.
-   * Supports debouncing if options are provided.
-   * @param event The event object.
-   * @param options Options for the event push (e.g., debouncing).
-   */
-  addEvent<T extends EventType<E>>(event: Event<E, T>, options?: PushEventOptions): void;
-  private handleDebouncedEvent;
-  private scheduleProcessing;
-  private processEvents;
-  private dequeue;
-  private setLastEvent;
-  private broadcastEvent;
-}
-//#endregion
-//#region src/services/logger/index.d.ts
-type Logger$1 = Logger;
-//#endregion
 //#region src/services/database/events/index.d.ts
 declare const DatabaseEventTypes: {
   readonly LocalQuery: "DATABASE_LOCAL_QUERY";
@@ -154,13 +32,13 @@ interface SealedQuery<T = void> {
 //#endregion
 //#region src/services/database/database.d.ts
 declare abstract class AbstractDatabaseService {
-  protected client: Surreal;
+  protected client: Surreal$1;
   protected logger: Logger$1;
   protected events: DatabaseEventSystem;
   protected abstract eventType: typeof DatabaseEventTypes.LocalQuery | typeof DatabaseEventTypes.RemoteQuery;
-  constructor(client: Surreal, logger: Logger$1, events: DatabaseEventSystem);
+  constructor(client: Surreal$1, logger: Logger$1, events: DatabaseEventSystem);
   abstract connect(): Promise<void>;
-  getClient(): Surreal;
+  getClient(): Surreal$1;
   getEvents(): DatabaseEventSystem;
   tx(): Promise<SurrealTransaction>;
   private queryQueue;
@@ -176,8 +54,8 @@ declare abstract class AbstractDatabaseService {
 declare class LocalDatabaseService extends AbstractDatabaseService {
   private config;
   protected eventType: "DATABASE_LOCAL_QUERY";
-  constructor(config: SpookyConfig<any>['database'], logger: Logger$1);
-  getConfig(): SpookyConfig<any>['database'];
+  constructor(config: Sp00kyConfig<any>['database'], logger: Logger$1);
+  getConfig(): Sp00kyConfig<any>['database'];
   connect(): Promise<void>;
 }
 //#endregion
@@ -185,8 +63,8 @@ declare class LocalDatabaseService extends AbstractDatabaseService {
 declare class RemoteDatabaseService extends AbstractDatabaseService {
   private config;
   protected eventType: "DATABASE_REMOTE_QUERY";
-  constructor(config: SpookyConfig<any>['database'], logger: Logger$1);
-  getConfig(): SpookyConfig<any>['database'];
+  constructor(config: Sp00kyConfig<any>['database'], logger: Logger$1);
+  getConfig(): Sp00kyConfig<any>['database'];
   connect(): Promise<void>;
   signin(params: any): Promise<any>;
   signup(params: any): Promise<any>;
@@ -194,33 +72,6 @@ declare class RemoteDatabaseService extends AbstractDatabaseService {
   invalidate(): Promise<void>;
 }
 //#endregion
-//#region src/modules/sync/queue/queue-up.d.ts
-type CreateEvent = {
-  type: 'create';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  data: Record<string, unknown>;
-  record?: Record<string, unknown>;
-  tableName?: string;
-  options?: PushEventOptions;
-};
-type UpdateEvent = {
-  type: 'update';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  data: Record<string, unknown>;
-  record?: Record<string, unknown>;
-  beforeRecord?: Record<string, unknown>;
-  options?: PushEventOptions;
-};
-type DeleteEvent = {
-  type: 'delete';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  options?: PushEventOptions;
-};
-type UpEvent = CreateEvent | UpdateEvent | DeleteEvent;
-//#endregion
 //#region src/services/stream-processor/wasm-types.d.ts
 interface WasmStreamUpdate {
   query_id: string;
@@ -297,205 +148,6 @@ declare class StreamProcessorService {
   private normalizeValue;
 }
 //#endregion
-//#region src/types.d.ts
-/**
- * The type of storage backend to use for the local database.
- * - 'memory': In-memory storage (transient).
- * - 'indexeddb': IndexedDB storage (persistent).
- */
-type StoreType = 'memory' | 'indexeddb';
-/**
- * Interface for a custom persistence client.
- * Allows providing a custom storage mechanism for the local database.
- */
-interface PersistenceClient {
-  /**
-   * Sets a value in the storage.
-   * @param key The key to set.
-   * @param value The value to store.
-   */
-  set<T>(key: string, value: T): Promise<void>;
-  /**
-   * Gets a value from the storage.
-   * @param key The key to retrieve.
-   * @returns The stored value or null if not found.
-   */
-  get<T>(key: string): Promise<T | null>;
-  /**
-   * Removes a value from the storage.
-   * @param key The key to remove.
-   */
-  remove(key: string): Promise<void>;
-}
-/**
- * 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';
-/**
- * Result object returned when a query is registered or executed.
- */
-interface SpookyQueryResult {
-  /** The unique hash identifier for the query. */
-  hash: string;
-}
-type SpookyQueryResultPromise = Promise<SpookyQueryResult>;
-interface EventSubscriptionOptions {
-  priority?: number;
-}
-/**
- * Configuration options for the Spooky client.
- * @template S The schema structure type.
- */
-interface SpookyConfig<S extends SchemaStructure> {
-  /** Database connection configuration. */
-  database: {
-    /** The SurrealDB endpoint URL. */
-    endpoint?: string;
-    /** The namespace to use. */
-    namespace: string;
-    /** The database name. */
-    database: string;
-    /** The local store type implementation. */
-    store?: StoreType;
-    /** Authentication token. */
-    token?: string;
-  };
-  /** Unique client identifier. If not provided, one will be generated. */
-  clientId?: string;
-  /** The schema definition. */
-  schema: S;
-  /** The compiled SURQL schema string. */
-  schemaSurql: string;
-  /** Logging level. */
-  logLevel: Level$1;
-  /**
-   * Persistence client to use.
-   * Can be a custom implementation, 'surrealdb' (default), or 'localstorage'.
-   */
-  persistenceClient?: PersistenceClient | 'surrealdb' | 'localstorage';
-  /** OpenTelemetry collector endpoint for telemetry data. */
-  otelEndpoint?: string;
-  /**
-   * Debounce time in milliseconds for stream updates.
-   * Defaults to 100ms.
-   */
-  streamDebounceTime?: number;
-}
-type QueryHash = string;
-type RecordVersionArray = Array<[string, number]>;
-/**
- * Represents the difference between two record version sets.
- * Used for synchronizing local and remote states.
- */
-interface RecordVersionDiff {
-  /** List of records added. */
-  added: Array<{
-    id: RecordId$1<string>;
-    version: number;
-  }>;
-  /** List of records updated. */
-  updated: Array<{
-    id: RecordId$1<string>;
-    version: number;
-  }>;
-  /** List of record IDs removed. */
-  removed: RecordId$1<string>[];
-}
-/**
- * Configuration for a specific query instance.
- * Stores metadata about the query's state, parameters, and versioning.
- */
-interface QueryConfig {
-  /** The unique ID of the query config record. */
-  id: RecordId$1<string>;
-  /** The SURQL query string. */
-  surql: string;
-  /** Parameters used in the query. */
-  params: Record<string, any>;
-  /** The version array representing the local state of results. */
-  localArray: RecordVersionArray;
-  /** The version array representing the remote (server) state of results. */
-  remoteArray: RecordVersionArray;
-  /** Time-To-Live for this query. */
-  ttl: QueryTimeToLive;
-  /** Timestamp when the query was last accessed/active. */
-  lastActiveAt: Date;
-  /** The name of the table this query targets (if applicable). */
-  tableName: string;
-}
-type QueryConfigRecord = QueryConfig & {
-  id: string;
-};
-/**
- * Internal state of a live query.
- */
-interface QueryState {
-  /** The configuration for this query. */
-  config: QueryConfig;
-  /** The current cached records for this query. */
-  records: Record<string, any>[];
-  /** Timer for TTL expiration. */
-  ttlTimer: NodeJS.Timeout | null;
-  /** TTL duration in milliseconds. */
-  ttlDurationMs: number;
-  /** Number of times the query has been updated. */
-  updateCount: number;
-}
-type QueryUpdateCallback = (records: Record<string, any>[]) => void;
-type MutationCallback = (mutations: UpEvent[]) => void;
-type MutationEventType = 'create' | 'update' | 'delete';
-/**
- * Represents a mutation event (create, update, delete) to be synchronized.
- */
-interface MutationEvent {
-  /** Example: 'create', 'update', or 'delete'. */
-  type: MutationEventType;
-  /** unique id of the mutation */
-  mutation_id: RecordId$1<string>;
-  /** The ID of the record being mutated. */
-  record_id: RecordId$1<string>;
-  /** The data payload for create/update operations. */
-  data?: any;
-  /** The full record data (optional context). */
-  record?: any;
-  /** Options for the mutation event (e.g., debounce settings). */
-  options?: PushEventOptions;
-  /** Timestamp when the event was created. */
-  createdAt: Date;
-}
-/**
- * Options for run operations.
- */
-interface RunOptions {
-  assignedTo?: string;
-  max_retries?: number;
-  retry_strategy?: 'linear' | 'exponential';
-}
-/**
- * Options for update operations.
- */
-interface UpdateOptions {
-  /**
-   * Debounce configuration for the update.
-   * If boolean, enables default debounce behavior.
-   */
-  debounced?: boolean | DebounceOptions;
-}
-/**
- * Configuration options for debouncing updates.
- */
-interface DebounceOptions {
-  /**
-   * The key to use for debouncing.
-   * - 'recordId': Debounce based on the specific record ID. WARNING: IT WILL ONLY ACCEPT THE LATEST CHANGE AND DOES *NOT* MERGE THE PREVIOUS ONCES. IF YOU ARE UNSURE JUST USE 'recordId_x_fields'.
-   * - 'recordId_x_fields': Debounce based on record ID and specific fields.
-   */
-  key?: 'recordId' | 'recordId_x_fields';
-  /** The debounce delay in milliseconds. */
-  delay?: number;
-}
-//#endregion
 //#region src/modules/auth/events/index.d.ts
 declare const AuthEventTypes: {
   readonly AuthStateChanged: "AUTH_STATE_CHANGED";
@@ -543,7 +195,75 @@ declare class AuthService<S extends SchemaStructure> {
   signIn<Name extends keyof S['access'] & string>(accessName: Name, params: ExtractAccessParams<S, Name, 'signIn'>): Promise<void>;
 }
 //#endregion
-//#region src/spooky.d.ts
+//#region src/modules/crdt/crdt-field.d.ts
+declare const CURSOR_COLORS: string[];
+declare function cursorColorFromName(name: string): string;
+declare class CrdtField {
+  private fieldName;
+  private doc;
+  private pushTimer;
+  private remote;
+  private recordId;
+  private unsubscribe;
+  private lastPushTime;
+  private lastCursorPushTime;
+  private loadedFromCrdt;
+  private pushRetryCount;
+  private logger;
+  private _onCursorUpdate;
+  private pendingCursorUpdate;
+  /** Callback set by the editor to receive remote cursor updates.
+   *  Any cursor data that arrived before this callback was set will be replayed. */
+  set onCursorUpdate(cb: ((data: Uint8Array) => void) | null);
+  get onCursorUpdate(): ((data: Uint8Array) => void) | null;
+  constructor(fieldName: string, initialState?: string, logger?: Logger$1 | null);
+  getDoc(): LoroDoc;
+  /** Whether the LoroDoc was loaded from saved CRDT state */
+  hasContent(): boolean;
+  startSync(remote: RemoteDatabaseService, recordId: string): void;
+  stopSync(): void;
+  importRemote(base64State: string): void;
+  exportSnapshot(): string;
+  /** Push cursor ephemeral state to _00_crdt as a "_cursor_<fieldName>" entry */
+  pushCursorState(encoded: Uint8Array): Promise<void>;
+  /** Import remote cursor state (called by CrdtManager from LIVE SELECT) */
+  importRemoteCursor(base64State: string): void;
+  private schedulePush;
+  private pushToRemote;
+}
+//#endregion
+//#region src/modules/crdt/index.d.ts
+/**
+ * CrdtManager manages active CrdtField instances and their sync channels.
+ *
+ * Each open record gets a LIVE SELECT on _00_crdt that delivers remote
+ * changes in real time.
+ */
+declare class CrdtManager {
+  private schema;
+  private remote;
+  private fields;
+  private liveQueries;
+  private logger;
+  constructor(schema: SchemaStructure, remote: RemoteDatabaseService, logger: Logger$1);
+  /**
+   * Open a CRDT field for collaborative editing.
+   *
+   * @param table - Table name
+   * @param recordId - Full record ID (e.g., "thread:abc")
+   * @param field - Field name (e.g., "title", "content")
+   * @param fallbackText - Current plain text from the record, used to seed the
+   *                       LoroDoc if no CRDT state exists yet (migration path)
+   */
+  open(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField>;
+  close(table: string, recordId: string, field: string): void;
+  closeAll(): void;
+  private ensureLiveSelect;
+  private killLiveSelect;
+  private makeKey;
+}
+//#endregion
+//#region src/sp00ky.d.ts
 declare class BucketHandle {
   private bucketName;
   private remote;
@@ -557,7 +277,7 @@ declare class BucketHandle {
   rename(sourcePath: string, targetPath: string): Promise<void>;
   list(prefix?: string): Promise<string[]>;
 }
-declare class SpookyClient<S extends SchemaStructure> {
+declare class Sp00kyClient<S extends SchemaStructure> {
   private config;
   private local;
   private remote;
@@ -567,14 +287,15 @@ declare class SpookyClient<S extends SchemaStructure> {
   private dataModule;
   private sync;
   private devTools;
+  private crdtManager;
   private logger;
   auth: AuthService<S>;
   streamProcessor: StreamProcessorService;
-  get remoteClient(): Surreal;
-  get localClient(): Surreal;
+  get remoteClient(): surrealdb0.Surreal;
+  get localClient(): surrealdb0.Surreal;
   get pendingMutationCount(): number;
   subscribeToPendingMutations(cb: (count: number) => void): () => void;
-  constructor(config: SpookyConfig<S>);
+  constructor(config: Sp00kyConfig<S>);
   /**
    * Setup direct callbacks instead of event subscriptions
    */
@@ -582,8 +303,18 @@ declare class SpookyClient<S extends SchemaStructure> {
   init(): Promise<void>;
   close(): Promise<void>;
   authenticate(token: string): Promise<surrealdb0.Tokens>;
+  /**
+   * Open a CRDT field for collaborative editing.
+   * Returns a CrdtField with a LoroDoc that can be bound to any editor.
+   * Also starts a LIVE SELECT on _00_crdt for real-time sync.
+   */
+  openCrdtField(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField>;
+  /**
+   * Close a CRDT field when editing is done.
+   */
+  closeCrdtField(table: string, recordId: string, field: string): void;
   deauthenticate(): Promise<void>;
-  query<Table extends TableNames<S>>(table: Table, options: QueryOptions<TableModel<GetTable<S, Table>>, false>, ttl?: QueryTimeToLive): QueryBuilder<S, Table, SpookyQueryResultPromise>;
+  query<Table extends TableNames<S>>(table: Table, options: QueryOptions<TableModel<GetTable<S, Table>>, false>, ttl?: QueryTimeToLive): QueryBuilder<S, Table, Sp00kyQueryResultPromise>;
   private initQuery;
   queryRaw(sql: string, params: Record<string, any>, ttl: QueryTimeToLive): Promise<string>;
   subscribe(queryHash: string, callback: (records: Record<string, any>[]) => void, options?: {
@@ -603,9 +334,14 @@ declare class SpookyClient<S extends SchemaStructure> {
 //#endregion
 //#region src/utils/index.d.ts
 declare function fileToUint8Array(file: File | Blob): Promise<Uint8Array>;
+/**
+ * Convert plain text to simple HTML paragraphs.
+ * Useful for seeding a rich-text editor (e.g. TipTap/ProseMirror) with fallback content.
+ */
+declare function textToHtml(text: string): string;
 /**
  * Helper for retrying DB operations with exponential backoff
  */
 
 //#endregion
-export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, DebounceOptions, EventSubscriptionOptions, type Level, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryTimeToLive, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RunOptions, SpookyClient, SpookyConfig, SpookyQueryResult, SpookyQueryResultPromise, StoreType, UpdateOptions, createAuthEventSystem, fileToUint8Array };
+export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, Level, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PinoTransmit, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryTimeToLive, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };