@spooky-sync/core 0.0.1-canary.17 → 0.0.1-canary.18

package/dist/index.d.ts

@@ -1,132 +1,9 @@
+import { C as Logger$1, S as UpdateOptions, T as EventSystem, _ as RunOptions, a as MutationEvent, b as SpookyQueryResultPromise, 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 SpookyConfig, w as EventDefinition, x as StoreType, y as SpookyQueryResult } 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 { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, GetTable, QueryBuilder, QueryOptions, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
+import { Logger } from "pino";
 
-//#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";
@@ -194,33 +71,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 +147,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";
@@ -608,4 +259,4 @@ declare function fileToUint8Array(file: File | Blob): Promise<Uint8Array>;
  */
 
 //#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, DebounceOptions, EventSubscriptionOptions, Level, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PinoTransmit, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryTimeToLive, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RunOptions, SpookyClient, SpookyConfig, SpookyQueryResult, SpookyQueryResultPromise, StoreType, UpdateOptions, createAuthEventSystem, fileToUint8Array };

package/dist/index.js

@@ -1110,82 +1110,14 @@ var RemoteDatabaseService = class extends AbstractDatabaseService {
 
 //#endregion
 //#region src/services/logger/index.ts
-function mapLevelToSeverityNumber(level) {
-	switch (level) {
-		case "trace": return 1;
-		case "debug": return 5;
-		case "info": return 9;
-		case "warn": return 13;
-		case "error": return 17;
-		case "fatal": return 21;
-		default: return 9;
-	}
-}
-async function loadOtelModules(otelEndpoint) {
-	const [{ LoggerProvider, BatchLogRecordProcessor }, { OTLPLogExporter }, { resourceFromAttributes }, { ATTR_SERVICE_NAME }] = await Promise.all([
-		import("@opentelemetry/sdk-logs"),
-		import("@opentelemetry/exporter-logs-otlp-proto"),
-		import("@opentelemetry/resources"),
-		import("@opentelemetry/semantic-conventions")
-	]);
-	const loggerProvider = new LoggerProvider({
-		resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: "spooky-client" }),
-		processors: [new BatchLogRecordProcessor(new OTLPLogExporter({ url: otelEndpoint }))]
-	});
-	const otelLoggerCache = {};
-	return (category) => {
-		if (!otelLoggerCache[category]) otelLoggerCache[category] = loggerProvider.getLogger(category);
-		return otelLoggerCache[category];
-	};
-}
-function createLogger(level = "info", otelEndpoint) {
+function createLogger(level = "info", transmit) {
 	const browserConfig = {
 		asObject: true,
 		write: (o) => {
 			console.log(JSON.stringify(o));
 		}
 	};
-	if (otelEndpoint) {
-		const otelReady = loadOtelModules(otelEndpoint);
-		browserConfig.transmit = {
-			level,
-			send: (levelLabel, logEvent) => {
-				otelReady.then((getOtelLogger) => {
-					try {
-						const messages = [...logEvent.messages];
-						const severityNumber = mapLevelToSeverityNumber(levelLabel);
-						let body = "";
-						const msg = messages.pop();
-						if (typeof msg === "string") body = msg;
-						else if (msg) body = JSON.stringify(msg);
-						let category = "spooky-client::unknown";
-						const attributes = {};
-						for (const msg of messages) if (typeof msg === "object") {
-							if (msg.Category) {
-								category = msg.Category;
-								delete msg.Category;
-							}
-							Object.assign(attributes, msg);
-						}
-						getOtelLogger(category).emit({
-							severityNumber,
-							severityText: levelLabel.toUpperCase(),
-							body,
-							attributes: {
-								...logEvent.bindings[0],
-								...attributes
-							},
-							timestamp: new Date(logEvent.ts)
-						});
-					} catch (e) {
-						console.warn("Failed to transmit log to OTEL endpoint", e);
-					}
-				}).catch((e) => {
-					console.warn("Failed to load OpenTelemetry modules", e);
-				});
-			}
-		};
-	}
+	if (transmit) browserConfig.transmit = transmit;
 	return pino({
 		level,
 		browser: browserConfig
@@ -3069,7 +3001,7 @@ var SpookyClient = class {
 	}
 	constructor(config) {
 		this.config = config;
-		const logger = createLogger(config.logLevel ?? "info", config.otelEndpoint);
+		const logger = createLogger(config.logLevel ?? "info", config.otelTransmit);
 		this.logger = logger.child({ service: "SpookyClient" });
 		this.logger.info({
 			config: {

package/dist/otel/index.d.ts

@@ -0,0 +1,21 @@
+import { c as PinoTransmit } from "../types.js";
+import { Level } from "pino";
+
+//#region src/otel/index.d.ts
+
+/**
+ * Creates a pino browser transmit object that forwards logs to an OpenTelemetry collector.
+ *
+ * @example
+ * ```ts
+ * import { createOtelTransmit } from '@spooky-sync/core/otel';
+ *
+ * new SpookyClient({
+ *   // ...
+ *   otelTransmit: createOtelTransmit('http://localhost:4318/v1/logs'),
+ * });
+ * ```
+ */
+declare function createOtelTransmit(endpoint: string, level?: Level): PinoTransmit;
+//#endregion
+export { createOtelTransmit };

package/dist/otel/index.js

@@ -0,0 +1,86 @@
+//#region src/otel/index.ts
+function mapLevelToSeverityNumber(level) {
+	switch (level) {
+		case "trace": return 1;
+		case "debug": return 5;
+		case "info": return 9;
+		case "warn": return 13;
+		case "error": return 17;
+		case "fatal": return 21;
+		default: return 9;
+	}
+}
+async function loadOtelModules(otelEndpoint) {
+	const [{ LoggerProvider, BatchLogRecordProcessor }, { OTLPLogExporter }, { resourceFromAttributes }, { ATTR_SERVICE_NAME }] = await Promise.all([
+		import("@opentelemetry/sdk-logs"),
+		import("@opentelemetry/exporter-logs-otlp-proto"),
+		import("@opentelemetry/resources"),
+		import("@opentelemetry/semantic-conventions")
+	]);
+	const loggerProvider = new LoggerProvider({
+		resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: "spooky-client" }),
+		processors: [new BatchLogRecordProcessor(new OTLPLogExporter({ url: otelEndpoint }))]
+	});
+	const otelLoggerCache = {};
+	return (category) => {
+		if (!otelLoggerCache[category]) otelLoggerCache[category] = loggerProvider.getLogger(category);
+		return otelLoggerCache[category];
+	};
+}
+/**
+* Creates a pino browser transmit object that forwards logs to an OpenTelemetry collector.
+*
+* @example
+* ```ts
+* import { createOtelTransmit } from '@spooky-sync/core/otel';
+*
+* new SpookyClient({
+*   // ...
+*   otelTransmit: createOtelTransmit('http://localhost:4318/v1/logs'),
+* });
+* ```
+*/
+function createOtelTransmit(endpoint, level = "info") {
+	const otelReady = loadOtelModules(endpoint);
+	return {
+		level,
+		send: (levelLabel, logEvent) => {
+			otelReady.then((getOtelLogger) => {
+				try {
+					const messages = [...logEvent.messages];
+					const severityNumber = mapLevelToSeverityNumber(levelLabel);
+					let body = "";
+					const msg = messages.pop();
+					if (typeof msg === "string") body = msg;
+					else if (msg) body = JSON.stringify(msg);
+					let category = "spooky-client::unknown";
+					const attributes = {};
+					for (const msg of messages) if (typeof msg === "object") {
+						if (msg.Category) {
+							category = msg.Category;
+							delete msg.Category;
+						}
+						Object.assign(attributes, msg);
+					}
+					getOtelLogger(category).emit({
+						severityNumber,
+						severityText: levelLabel.toUpperCase(),
+						body,
+						attributes: {
+							...logEvent.bindings[0],
+							...attributes
+						},
+						timestamp: new Date(logEvent.ts)
+					});
+				} catch (e) {
+					console.warn("Failed to transmit log to OTEL endpoint", e);
+				}
+			}).catch((e) => {
+				console.warn("Failed to load OpenTelemetry modules", e);
+			});
+		}
+	};
+}
+
+//#endregion
+export { createOtelTransmit };

package/dist/types.d.ts

@@ -0,0 +1,359 @@
+import { RecordId } from "surrealdb";
+import { RecordId as RecordId$1, SchemaStructure } from "@spooky-sync/query-builder";
+import { Level, Level as Level$1, Logger, LoggerOptions } from "pino";
+
+//#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/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/types.d.ts
+/**
+ * A pino browser transmit object for forwarding logs to an external sink (e.g. OpenTelemetry).
+ */
+type PinoTransmit = NonNullable<NonNullable<LoggerOptions['browser']>['transmit']>;
+/**
+ * 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;
+  /**
+   * Persistence client to use.
+   * Can be a custom implementation, 'surrealdb' (default), or 'localstorage'.
+   */
+  persistenceClient?: PersistenceClient | 'surrealdb' | 'localstorage';
+  /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel). */
+  otelTransmit?: PinoTransmit;
+  /**
+   * 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
+export { Logger$1 as C, UpdateOptions as S, EventSystem as T, RunOptions as _, MutationEvent as a, SpookyQueryResultPromise as b, PinoTransmit as c, QueryHash as d, QueryState as f, RecordVersionDiff as g, RecordVersionArray as h, MutationCallback as i, QueryConfig as l, QueryUpdateCallback as m, EventSubscriptionOptions as n, MutationEventType as o, QueryTimeToLive as p, Level$1 as r, PersistenceClient as s, DebounceOptions as t, QueryConfigRecord as u, SpookyConfig as v, EventDefinition as w, StoreType as x, SpookyQueryResult as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.17",
+  "version": "0.0.1-canary.18",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -8,6 +8,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./otel": {
+      "types": "./dist/otel/index.d.ts",
+      "import": "./dist/otel/index.js"
     }
   },
   "scripts": {

package/skills/spooky-core/references/config.md

@@ -29,8 +29,8 @@ interface SpookyConfig<S extends SchemaStructure> {
    * - Custom: Provide an object implementing PersistenceClient
    */
   persistenceClient?: PersistenceClient | 'surrealdb' | 'localstorage';
-  /** OpenTelemetry collector endpoint */
-  otelEndpoint?: string;
+  /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel) */
+  otelTransmit?: PinoTransmit;
   /** Debounce time in ms for stream updates (default: 100) */
   streamDebounceTime?: number;
 }

package/src/otel/index.ts

@@ -0,0 +1,124 @@
+import { Level } from 'pino';
+import { PinoTransmit } from '../types';
+
+// Map pino levels to OTEL severity numbers
+// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#severity-fields
+function mapLevelToSeverityNumber(level: string): number {
+  switch (level) {
+    case 'trace':
+      return 1;
+    case 'debug':
+      return 5;
+    case 'info':
+      return 9;
+    case 'warn':
+      return 13;
+    case 'error':
+      return 17;
+    case 'fatal':
+      return 21;
+    default:
+      return 9;
+  }
+}
+
+async function loadOtelModules(otelEndpoint: string) {
+  const [{ LoggerProvider, BatchLogRecordProcessor }, { OTLPLogExporter }, { resourceFromAttributes }, { ATTR_SERVICE_NAME }] =
+    await Promise.all([
+      import('@opentelemetry/sdk-logs'),
+      import('@opentelemetry/exporter-logs-otlp-proto'),
+      import('@opentelemetry/resources'),
+      import('@opentelemetry/semantic-conventions'),
+    ]);
+
+  const resource = resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: 'spooky-client',
+  });
+
+  const exporter = new OTLPLogExporter({
+    url: otelEndpoint,
+  });
+
+  const loggerProvider = new LoggerProvider({
+    resource,
+    processors: [new BatchLogRecordProcessor(exporter)],
+  });
+
+  const otelLoggerCache: Record<string, ReturnType<typeof loggerProvider.getLogger>> = {};
+
+  return (category: string) => {
+    if (!otelLoggerCache[category]) {
+      otelLoggerCache[category] = loggerProvider.getLogger(category);
+    }
+    return otelLoggerCache[category];
+  };
+}
+
+/**
+ * Creates a pino browser transmit object that forwards logs to an OpenTelemetry collector.
+ *
+ * @example
+ * ```ts
+ * import { createOtelTransmit } from '@spooky-sync/core/otel';
+ *
+ * new SpookyClient({
+ *   // ...
+ *   otelTransmit: createOtelTransmit('http://localhost:4318/v1/logs'),
+ * });
+ * ```
+ */
+export function createOtelTransmit(endpoint: string, level: Level = 'info'): PinoTransmit {
+  // Start loading OTel modules eagerly (don't await — we're synchronous)
+  const otelReady = loadOtelModules(endpoint);
+
+  return {
+    level: level,
+    send: (levelLabel: string, logEvent: any) => {
+      otelReady.then((getOtelLogger) => {
+        try {
+          const messages = [...logEvent.messages];
+          const severityNumber = mapLevelToSeverityNumber(levelLabel);
+
+          // Construct the message body
+          let body = '';
+          const msg = messages.pop();
+
+          if (typeof msg === 'string') {
+            body = msg;
+          } else if (msg) {
+            body = JSON.stringify(msg);
+          }
+
+          let category = 'spooky-client::unknown';
+
+          const attributes = {};
+          for (const msg of messages) {
+            if (typeof msg === 'object') {
+              if (msg.Category) {
+                category = msg.Category;
+                delete msg.Category;
+              }
+              Object.assign(attributes, msg);
+            }
+          }
+
+          // Emit to OTEL SDK
+          getOtelLogger(category).emit({
+            severityNumber: severityNumber,
+            severityText: levelLabel.toUpperCase(),
+            body: body,
+            attributes: {
+              ...logEvent.bindings[0],
+              ...attributes,
+            },
+            timestamp: new Date(logEvent.ts),
+          });
+        } catch (e) {
+          console.warn('Failed to transmit log to OTEL endpoint', e);
+        }
+      }).catch((e) => {
+        console.warn('Failed to load OpenTelemetry modules', e);
+      });
+    },
+  };
+}

package/src/services/logger/index.ts

@@ -1,61 +1,9 @@
 import pino, { Level, type Logger as PinoLogger, type LoggerOptions } from 'pino';
+import { PinoTransmit } from '../../types';
 
 export type Logger = PinoLogger;
 
-// Map pino levels to OTEL severity numbers
-// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#severity-fields
-function mapLevelToSeverityNumber(level: string): number {
-  switch (level) {
-    case 'trace':
-      return 1;
-    case 'debug':
-      return 5;
-    case 'info':
-      return 9;
-    case 'warn':
-      return 13;
-    case 'error':
-      return 17;
-    case 'fatal':
-      return 21;
-    default:
-      return 9;
-  }
-}
-
-async function loadOtelModules(otelEndpoint: string) {
-  const [{ LoggerProvider, BatchLogRecordProcessor }, { OTLPLogExporter }, { resourceFromAttributes }, { ATTR_SERVICE_NAME }] =
-    await Promise.all([
-      import('@opentelemetry/sdk-logs'),
-      import('@opentelemetry/exporter-logs-otlp-proto'),
-      import('@opentelemetry/resources'),
-      import('@opentelemetry/semantic-conventions'),
-    ]);
-
-  const resource = resourceFromAttributes({
-    [ATTR_SERVICE_NAME]: 'spooky-client',
-  });
-
-  const exporter = new OTLPLogExporter({
-    url: otelEndpoint,
-  });
-
-  const loggerProvider = new LoggerProvider({
-    resource,
-    processors: [new BatchLogRecordProcessor(exporter)],
-  });
-
-  const otelLoggerCache: Record<string, ReturnType<typeof loggerProvider.getLogger>> = {};
-
-  return (category: string) => {
-    if (!otelLoggerCache[category]) {
-      otelLoggerCache[category] = loggerProvider.getLogger(category);
-    }
-    return otelLoggerCache[category];
-  };
-}
-
-export function createLogger(level: Level = 'info', otelEndpoint?: string): Logger {
+export function createLogger(level: Level = 'info', transmit?: PinoTransmit): Logger {
   const browserConfig: LoggerOptions['browser'] = {
     asObject: true,
     write: (o: any) => {
@@ -63,60 +11,8 @@ export function createLogger(level: Level = 'info', otelEndpoint?: string): Logg
     },
   };
 
-  if (otelEndpoint) {
-    // Start loading OTel modules eagerly (don't await — we're synchronous)
-    const otelReady = loadOtelModules(otelEndpoint);
-
-    browserConfig.transmit = {
-      level: level,
-      send: (levelLabel: string, logEvent: any) => {
-        otelReady.then((getOtelLogger) => {
-          try {
-            const messages = [...logEvent.messages];
-            const severityNumber = mapLevelToSeverityNumber(levelLabel);
-
-            // Construct the message body
-            let body = '';
-            const msg = messages.pop();
-
-            if (typeof msg === 'string') {
-              body = msg;
-            } else if (msg) {
-              body = JSON.stringify(msg);
-            }
-
-            let category = 'spooky-client::unknown';
-
-            const attributes = {};
-            for (const msg of messages) {
-              if (typeof msg === 'object') {
-                if (msg.Category) {
-                  category = msg.Category;
-                  delete msg.Category;
-                }
-                Object.assign(attributes, msg);
-              }
-            }
-
-            // Emit to OTEL SDK
-            getOtelLogger(category).emit({
-              severityNumber: severityNumber,
-              severityText: levelLabel.toUpperCase(),
-              body: body,
-              attributes: {
-                ...logEvent.bindings[0],
-                ...attributes,
-              },
-              timestamp: new Date(logEvent.ts),
-            });
-          } catch (e) {
-            console.warn('Failed to transmit log to OTEL endpoint', e);
-          }
-        }).catch((e) => {
-          console.warn('Failed to load OpenTelemetry modules', e);
-        });
-      },
-    };
+  if (transmit) {
+    browserConfig.transmit = transmit;
   }
 
   return pino({

package/src/spooky.ts

@@ -113,7 +113,7 @@ export class SpookyClient<S extends SchemaStructure> {
   }
 
   constructor(private config: SpookyConfig<S>) {
-    const logger = createLogger(config.logLevel ?? 'info', config.otelEndpoint);
+    const logger = createLogger(config.logLevel ?? 'info', config.otelTransmit);
     this.logger = logger.child({ service: 'SpookyClient' });
 
     this.logger.info(

package/src/types.ts

@@ -1,10 +1,15 @@
 import { RecordId, SchemaStructure } from '@spooky-sync/query-builder';
-import { Level } from 'pino';
+import { Level, type LoggerOptions } from 'pino';
 import { PushEventOptions } from './events/index';
 import { UpEvent } from './modules/sync/index';
 
 export type { Level } from 'pino';
 
+/**
+ * A pino browser transmit object for forwarding logs to an external sink (e.g. OpenTelemetry).
+ */
+export type PinoTransmit = NonNullable<NonNullable<LoggerOptions['browser']>['transmit']>;
+
 /**
  * The type of storage backend to use for the local database.
  * - 'memory': In-memory storage (transient).
@@ -107,8 +112,8 @@ export interface SpookyConfig<S extends SchemaStructure> {
    * Can be a custom implementation, 'surrealdb' (default), or 'localstorage'.
    */
   persistenceClient?: PersistenceClient | 'surrealdb' | 'localstorage';
-  /** OpenTelemetry collector endpoint for telemetry data. */
-  otelEndpoint?: string;
+  /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel). */
+  otelTransmit?: PinoTransmit;
   /**
    * Debounce time in milliseconds for stream updates.
    * Defaults to 100ms.

package/tsdown.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from 'tsdown';
 
 export default defineConfig({
-  entry: ['src/index.ts'],
+  entry: ['src/index.ts', 'src/otel/index.ts'],
   format: ['esm'],
   dts: true,
   clean: true,