tetherdb 0.1.0

package/dist/client/storage.d.ts

@@ -0,0 +1,183 @@
+import { type ChangeRecord, OperationType, type SnapshotRecord, type StoredRecord } from '../shared/types.js';
+import { EventRegistry } from './shared/event.js';
+import { Table } from './table.js';
+/**
+ * Represents a pending mutation queue item within the internal IndexedDB outbox.
+ */
+export interface OutboxEntry {
+    /** Auto-incrementing primary key in the outbox object store. */
+    localId?: number;
+    /** Transient batch correlation identifier. */
+    batchId?: string;
+    /** The mutation change record to be synced to the server. */
+    change: ChangeRecord;
+    /** Epoch timestamp when the entry was queued locally. */
+    createdAt: number;
+}
+/**
+ * Mutation item payload passed to `Storage.applyLocalChanges`.
+ */
+export interface LocalMutationItem<T = unknown> {
+    /** Target record identifier. */
+    id: string;
+    /** Mutation operation type. */
+    op: OperationType;
+    /** Record data payload (defined on put). */
+    data?: T;
+    /** Correlated changelog entry to queue in outbox. */
+    change: ChangeRecord<T>;
+}
+/**
+ * Atomic transaction and local persistence manager wrapping IndexedDB.
+ * Coordinates user table stores, pending outbox changelogs, and sync metadata.
+ */
+export declare class Storage {
+    /** Name of the local IndexedDB database. */
+    readonly name: string;
+    /** Unique client instance identifier used for monotonic logical clock tie-breaking. */
+    readonly clientId: string;
+    /** Reactive event registry triggered when mutations are committed to the local database. */
+    readonly onLocalChange: EventRegistry<void>;
+    private databasePromise;
+    private schemaMutex;
+    private tables;
+    /**
+     * Creates a new Storage instance.
+     *
+     * @param name - Name of the IndexedDB database.
+     */
+    constructor(name: string);
+    /**
+     * Obtains a typed table reference for reading, mutating, and subscribing to records.
+     * Tables are created dynamically on-demand if not already declared.
+     *
+     * @typeParam T - Data payload model type for records in this table.
+     * @param name - The table name.
+     * @returns A typed `Table<T>` instance.
+     */
+    table<T = unknown>(name: string): Table<T>;
+    /**
+     * Opens or returns the active IndexedDB connection, executing schema upgrades when needed.
+     *
+     * @returns A promise resolving to the open IDBDatabase instance.
+     */
+    getDatabase(): Promise<IDBDatabase>;
+    /**
+     * Dynamically ensures that multiple application tables exist in IndexedDB.
+     *
+     * @param tableNames - Array of table names to ensure.
+     */
+    ensureTables(tableNames: string[]): Promise<void>;
+    /**
+     * Ensures a single application table exists in IndexedDB.
+     *
+     * @param tableName - Name of the table to ensure.
+     */
+    ensureTable(tableName: string): Promise<void>;
+    /**
+     * Retrieves a metadata value from the internal metadata store.
+     *
+     * @typeParam T - Expected value type.
+     * @param key - The metadata key identifier.
+     * @returns The stored metadata value, or `undefined` if not set.
+     */
+    getMeta<T = unknown>(key: string): Promise<T | undefined>;
+    /**
+     * Sets a metadata value in the internal metadata store.
+     *
+     * @param key - The metadata key identifier.
+     * @param value - The value to store.
+     */
+    setMeta(key: string, value: unknown): Promise<void>;
+    /**
+     * Deletes a metadata entry from the internal metadata store.
+     *
+     * @param key - The metadata key identifier.
+     */
+    deleteMeta(key: string): Promise<void>;
+    /**
+     * Retrieves a single stored record by table and identifier.
+     *
+     * @typeParam T - Expected payload type.
+     * @param tableName - Table name.
+     * @param id - Record identifier.
+     * @returns Stored record or `undefined` if not found.
+     */
+    getRecord<T = unknown>(tableName: string, id: string): Promise<StoredRecord<T> | undefined>;
+    /**
+     * Retrieves multiple stored records by their identifiers in a single readonly transaction.
+     *
+     * @typeParam T - Expected payload type.
+     * @param tableName - Table name.
+     * @param ids - Array of record identifiers.
+     * @returns Map of found stored records keyed by id.
+     */
+    getRecords<T = unknown>(tableName: string, ids: string[]): Promise<Map<string, StoredRecord<T>>>;
+    /**
+     * Retrieves stored records from a specified table.
+     *
+     * @typeParam T - Data payload type.
+     * @param tableName - Table name.
+     * @returns Array of stored records with metadata.
+     */
+    getAllRecords<T = unknown>(tableName: string): Promise<StoredRecord<T>[]>;
+    /**
+     * Atomically persists a batch of local mutations alongside outbox changelog entries
+     * within a single IndexedDB transaction.
+     *
+     * @typeParam T - Data payload type.
+     * @param tableName - Target table name.
+     * @param mutations - List of mutations to apply and queue into outbox.
+     * @returns Array of newly stored records with updated metadata.
+     */
+    applyLocalChanges<T = unknown>(tableName: string, mutations: LocalMutationItem<T>[]): Promise<StoredRecord<T>[]>;
+    /**
+     * Retrieves all currently queued outbox entries awaiting sync.
+     *
+     * @param limit - Optional maximum number of entries to retrieve.
+     * @returns Array of pending outbox queue items.
+     */
+    getPendingOutbox(limit?: number): Promise<OutboxEntry[]>;
+    /**
+     * Clears acknowledged changes from the outbox by their local database IDs.
+     *
+     * @param localIds - Array of auto-incremented local outbox IDs to remove.
+     */
+    removeOutboxEntries(localIds: number[]): Promise<void>;
+    /**
+     * Applies an entire snapshot batch across tables atomically in a single transaction.
+     *
+     * @param snapshot - Array of record items to persist.
+     * @param seq - Global sequence number corresponding to this snapshot.
+     */
+    applySnapshotBatch(snapshot: SnapshotRecord[], seq: number): Promise<void>;
+    /**
+     * Applies a batch of incoming remote delta mutations atomically across tables
+     * in a single IndexedDB transaction without generating local outbox echo entries.
+     *
+     * @param changes - Array of change records received from the server.
+     * @param seq - New sequence number to record upon transaction commit.
+     */
+    applyRemoteChangesBatch(changes: ChangeRecord[], seq: number): Promise<void>;
+    /**
+     * Clears only user table stores, leaving internal metadata and outbox intact if desired.
+     *
+     * @param clearOutbox - Whether to clear the pending outbox queue as well (defaults to `true`).
+     */
+    clearTables(clearOutbox?: boolean): Promise<void>;
+    /**
+     * Clears all local table stores, outbox changelog entries, and metadata.
+     */
+    clearAllData(): Promise<void>;
+    /**
+     * Closes the active IndexedDB connection.
+     */
+    close(): Promise<void>;
+    private withDatabase;
+    private applyBatchRecords;
+    private clearStores;
+    private openDatabase;
+    private upgradeDatabase;
+    private createInternalStores;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/client/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/client/storage.ts"],"names":[],"mappings":"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"}

package/dist/client/sync.d.cts

@@ -0,0 +1,126 @@
+import { TetherClientError } from './errors.cjs';
+import { EventRegistry } from './shared/event.cjs';
+import type { Storage } from './storage.cjs';
+/**
+ * Operational state of the synchronization coordinator.
+ */
+export declare enum SyncStatus {
+    /** Disconnected from the remote synchronization server. */
+    Disconnected = 0,
+    /** Currently establishing a WebSocket connection. */
+    Connecting = 1,
+    /** Authenticated and actively synchronizing in real time. */
+    Connected = 2,
+    /** Synchronization halted due to an unrecoverable error (e.g. invalid auth token). */
+    Error = 3
+}
+/**
+ * Constructor signature for WebSocket implementations (native browser WebSocket or 'ws' package).
+ */
+export type WebSocketConstructor = new (url: string | URL, protocols?: string | string[] | WebSocketInit) => WebSocket;
+/**
+ * Configuration options for Sync.
+ */
+export interface SyncOptions {
+    /** WebSocket URL of the sync endpoint (e.g. 'ws://localhost:8080/sync'). */
+    url?: string;
+    /** Signed authentication session token. */
+    token?: string;
+    /** Application namespace identifier. */
+    appId: string;
+    /** Unique client instance identifier. */
+    clientId: string;
+    /** Initial reconnection backoff delay in milliseconds (defaults to 1000). */
+    reconnectIntervalMs?: number;
+    /** Maximum reconnection backoff delay in milliseconds (defaults to 30000). */
+    maxReconnectIntervalMs?: number;
+    /** Periodic keepalive ping interval in milliseconds (defaults to 30000). Set to 0 to disable. */
+    pingIntervalMs?: number;
+    /** Debounce delay in milliseconds before pushing queued local outbox changes (defaults to 10). */
+    pushDebounceMs?: number;
+    /** Custom WebSocket constructor for Node.js environments. */
+    webSocketClass?: WebSocketConstructor;
+    /** Callback invoked when the server provides a refreshed session token. */
+    onTokenRefresh?: (token: string) => void;
+    /** Callback invoked when the server rejects authentication. */
+    onAuthError?: (message: string) => void;
+}
+/**
+ * Two-way WebSocket sync coordinator managing initial snapshot / diff downloads,
+ * batched outbox queue flushing, acknowledgments, and auto-reconnect backoff.
+ */
+export declare class Sync {
+    /** Remote WebSocket endpoint URL. */
+    url?: string;
+    /** Application namespace identifier for partitioning synchronization channels. */
+    readonly appId: string;
+    /** Client identifier used for conflict resolution tie-breaking. */
+    readonly clientId: string;
+    /** Reactive event registry triggered whenever synchronization status transitions. */
+    readonly onStatusChange: EventRegistry<SyncStatus>;
+    /** Reactive event registry triggered whenever background sync or network errors occur. */
+    readonly onError: EventRegistry<TetherClientError>;
+    private token?;
+    private storage;
+    private options;
+    private webSocket;
+    private currentStatus;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private pingTimer;
+    private pushTimer;
+    private isPushing;
+    private isDestroyed;
+    private pendingBatches;
+    private messageQueue;
+    /**
+     * Creates a new Sync instance.
+     *
+     * @param storage - Local storage coordinator.
+     * @param options - Configuration options for sync and connection.
+     */
+    constructor(storage: Storage, options: SyncOptions);
+    /**
+     * Current operational status of the sync coordinator.
+     */
+    get status(): SyncStatus;
+    /**
+     * Initiates a WebSocket connection to the sync endpoint and sends authentication.
+     *
+     * @param token - Optional session token to connect with.
+     * @param url - Optional WebSocket URL override.
+     */
+    connect(token?: string, url?: string): void;
+    /**
+     * Disconnects the active WebSocket connection.
+     */
+    disconnect(): void;
+    /**
+     * Permanently tears down the sync coordinator and cancels reconnection timers.
+     */
+    destroy(): void;
+    /**
+     * Schedules a debounced push of pending outbox mutations.
+     *
+     * @param delayMs - Optional override for debounce delay in milliseconds.
+     */
+    schedulePush(delayMs?: number): void;
+    /**
+     * Immediately extracts queued outbox changes and transmits them to the server.
+     */
+    pushOutbox(): Promise<void>;
+    private setStatus;
+    private startPing;
+    private stopPing;
+    private isOnline;
+    private handleOnline;
+    private handleOffline;
+    private scheduleReconnect;
+    private send;
+    private sendAuth;
+    private handleServerMessage;
+    private handleSnapshot;
+    private handleDiff;
+    private notifyTableRemoteEvents;
+}
+//# sourceMappingURL=sync.d.ts.map

package/dist/client/sync.d.ts

@@ -0,0 +1,126 @@
+import { TetherClientError } from './errors.js';
+import { EventRegistry } from './shared/event.js';
+import type { Storage } from './storage.js';
+/**
+ * Operational state of the synchronization coordinator.
+ */
+export declare enum SyncStatus {
+    /** Disconnected from the remote synchronization server. */
+    Disconnected = 0,
+    /** Currently establishing a WebSocket connection. */
+    Connecting = 1,
+    /** Authenticated and actively synchronizing in real time. */
+    Connected = 2,
+    /** Synchronization halted due to an unrecoverable error (e.g. invalid auth token). */
+    Error = 3
+}
+/**
+ * Constructor signature for WebSocket implementations (native browser WebSocket or 'ws' package).
+ */
+export type WebSocketConstructor = new (url: string | URL, protocols?: string | string[] | WebSocketInit) => WebSocket;
+/**
+ * Configuration options for Sync.
+ */
+export interface SyncOptions {
+    /** WebSocket URL of the sync endpoint (e.g. 'ws://localhost:8080/sync'). */
+    url?: string;
+    /** Signed authentication session token. */
+    token?: string;
+    /** Application namespace identifier. */
+    appId: string;
+    /** Unique client instance identifier. */
+    clientId: string;
+    /** Initial reconnection backoff delay in milliseconds (defaults to 1000). */
+    reconnectIntervalMs?: number;
+    /** Maximum reconnection backoff delay in milliseconds (defaults to 30000). */
+    maxReconnectIntervalMs?: number;
+    /** Periodic keepalive ping interval in milliseconds (defaults to 30000). Set to 0 to disable. */
+    pingIntervalMs?: number;
+    /** Debounce delay in milliseconds before pushing queued local outbox changes (defaults to 10). */
+    pushDebounceMs?: number;
+    /** Custom WebSocket constructor for Node.js environments. */
+    webSocketClass?: WebSocketConstructor;
+    /** Callback invoked when the server provides a refreshed session token. */
+    onTokenRefresh?: (token: string) => void;
+    /** Callback invoked when the server rejects authentication. */
+    onAuthError?: (message: string) => void;
+}
+/**
+ * Two-way WebSocket sync coordinator managing initial snapshot / diff downloads,
+ * batched outbox queue flushing, acknowledgments, and auto-reconnect backoff.
+ */
+export declare class Sync {
+    /** Remote WebSocket endpoint URL. */
+    url?: string;
+    /** Application namespace identifier for partitioning synchronization channels. */
+    readonly appId: string;
+    /** Client identifier used for conflict resolution tie-breaking. */
+    readonly clientId: string;
+    /** Reactive event registry triggered whenever synchronization status transitions. */
+    readonly onStatusChange: EventRegistry<SyncStatus>;
+    /** Reactive event registry triggered whenever background sync or network errors occur. */
+    readonly onError: EventRegistry<TetherClientError>;
+    private token?;
+    private storage;
+    private options;
+    private webSocket;
+    private currentStatus;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private pingTimer;
+    private pushTimer;
+    private isPushing;
+    private isDestroyed;
+    private pendingBatches;
+    private messageQueue;
+    /**
+     * Creates a new Sync instance.
+     *
+     * @param storage - Local storage coordinator.
+     * @param options - Configuration options for sync and connection.
+     */
+    constructor(storage: Storage, options: SyncOptions);
+    /**
+     * Current operational status of the sync coordinator.
+     */
+    get status(): SyncStatus;
+    /**
+     * Initiates a WebSocket connection to the sync endpoint and sends authentication.
+     *
+     * @param token - Optional session token to connect with.
+     * @param url - Optional WebSocket URL override.
+     */
+    connect(token?: string, url?: string): void;
+    /**
+     * Disconnects the active WebSocket connection.
+     */
+    disconnect(): void;
+    /**
+     * Permanently tears down the sync coordinator and cancels reconnection timers.
+     */
+    destroy(): void;
+    /**
+     * Schedules a debounced push of pending outbox mutations.
+     *
+     * @param delayMs - Optional override for debounce delay in milliseconds.
+     */
+    schedulePush(delayMs?: number): void;
+    /**
+     * Immediately extracts queued outbox changes and transmits them to the server.
+     */
+    pushOutbox(): Promise<void>;
+    private setStatus;
+    private startPing;
+    private stopPing;
+    private isOnline;
+    private handleOnline;
+    private handleOffline;
+    private scheduleReconnect;
+    private send;
+    private sendAuth;
+    private handleServerMessage;
+    private handleSnapshot;
+    private handleDiff;
+    private notifyTableRemoteEvents;
+}
+//# sourceMappingURL=sync.d.ts.map

package/dist/client/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/client/sync.ts"],"names":[],"mappings":"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"}

package/dist/client/table.d.cts

@@ -0,0 +1,146 @@
+import { OperationType, type StoredRecord } from '../shared/types.cjs';
+import { EventRegistry } from './shared/event.cjs';
+import type { Storage } from './storage.cjs';
+/**
+ * Event describing a mutation (insert, update, delete) on a table record.
+ *
+ * @typeParam T - Data payload type.
+ */
+export interface TableChangeEvent<T = unknown> {
+    /** The mutation operation type. */
+    op: OperationType;
+    /** The affected record identifier. */
+    id: string;
+    /** The new record data (defined on 'put' operations). */
+    data?: T;
+    /** `true` if the change originated from remote synchronization; `false` if triggered locally. */
+    isRemote?: boolean;
+}
+/**
+ * Entry item for bulk insertion/update via `Table.putAll`.
+ *
+ * @typeParam T - Data payload type.
+ */
+export interface TablePutEntry<T = unknown> {
+    /** Target record identifier. */
+    id: string;
+    /** Record data payload. */
+    data: T;
+}
+/**
+ * Event notification callback fired when records are inserted, updated, or deleted.
+ * Always receives a list of change events.
+ *
+ * @typeParam T - Data payload type.
+ * @param events - List of change events that occurred.
+ */
+export type TableChangeListener<T = unknown> = (events: TableChangeEvent<T>[]) => void;
+/**
+ * Typed table wrapper providing local-first CRUD operations and reactive event subscriptions
+ * against an underlying IndexedDB table.
+ * Operations are batched by default for maximum performance.
+ *
+ * @typeParam T - The data type of records stored in this table.
+ */
+export declare class Table<T = unknown> {
+    /** Reactive event registry triggered when records in this table are created, updated, or deleted. */
+    readonly onChange: EventRegistry<TableChangeEvent<T>[]>;
+    private tableName;
+    private storage;
+    /**
+     * Creates a new Table instance.
+     *
+     * @param tableName - Name of the table.
+     * @param storage - Local storage coordinator.
+     */
+    constructor(tableName: string, storage: Storage);
+    /**
+     * The name of the table.
+     */
+    get name(): string;
+    /**
+     * The client identifier for local mutations.
+     */
+    get clientId(): string;
+    /**
+     * Retrieves a single record by its identifier.
+     *
+     * @param id - The unique record identifier.
+     * @returns A promise resolving to the record data, or `undefined` if not found.
+     */
+    get(id: string): Promise<T | undefined>;
+    /**
+     * Retrieves records stored in this table, optionally filtered by a list of IDs.
+     *
+     * @param ids - Optional list of record identifiers to fetch. If omitted, retrieves all records.
+     * @returns A promise resolving to an array of record data objects.
+     */
+    getAll(ids?: string[]): Promise<T[]>;
+    /**
+     * Deletes all records in this table and queues tombstones for synchronization.
+     *
+     * @returns A promise resolving to the number of deleted records.
+     */
+    clear(): Promise<number>;
+    /**
+     * Retrieves a single stored record including metadata (version, timestamp).
+     *
+     * @param id - The unique record identifier.
+     * @returns A promise resolving to the stored record with metadata, or `undefined` if not found.
+     */
+    getWithMetadata(id: string): Promise<StoredRecord<T> | undefined>;
+    /**
+     * Retrieves all records with storage metadata (version, timestamp).
+     *
+     * @returns A promise resolving to an array of stored records with metadata.
+     */
+    getAllWithMetadata(): Promise<StoredRecord<T>[]>;
+    /**
+     * Stores or updates a record locally and triggers synchronization.
+     *
+     * @param id - The unique record identifier.
+     * @param data - The data payload to save.
+     * @returns A promise resolving to the saved data.
+     */
+    put(id: string, data: T): Promise<T>;
+    /**
+     * Atomically stores or updates multiple records locally in a single batch,
+     * queues outbox mutations, notifies subscribers with an event list, and triggers synchronization.
+     *
+     * @param entries - Array of record entries to save.
+     * @returns A promise resolving to the array of saved data objects.
+     */
+    putAll(entries: TablePutEntry<T>[]): Promise<T[]>;
+    /**
+     * Deletes a record locally by creating a tombstone and triggers synchronization.
+     *
+     * @param id - The unique record identifier to delete.
+     * @returns A promise resolving to `true` if the record existed and was deleted; otherwise `false`.
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Atomically deletes multiple records locally in a single batch,
+     * creates tombstones, notifies subscribers with an event list, and triggers synchronization.
+     *
+     * @param ids - Array of record identifiers to delete.
+     * @returns A promise resolving to the count of records that existed and were deleted.
+     */
+    deleteAll(ids: string[]): Promise<number>;
+    /**
+     * Subscribes to the complete list of records in this table.
+     * Immediately invokes the listener with the current records, and re-invokes it
+     * whenever any local or remote mutations occur on this table.
+     *
+     * @param listener - Callback receiving the latest array of records.
+     * @returns An unsubscribe function.
+     */
+    subscribeAll(listener: (items: T[]) => void): () => void;
+    /**
+     * Notifies registered subscribers of remote change events.
+     *
+     * @param events - The list of remote change events.
+     */
+    notifyRemoteChanges(events: TableChangeEvent<unknown>[]): void;
+    private createMutationItem;
+}
+//# sourceMappingURL=table.d.ts.map