tetherdb 0.1.0

package/dist/client/table.d.ts

@@ -0,0 +1,146 @@
+import { OperationType, type StoredRecord } from '../shared/types.js';
+import { EventRegistry } from './shared/event.js';
+import type { Storage } from './storage.js';
+/**
+ * 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

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

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/client/table.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,aAAa,EACb,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAqB,OAAO,EAAE,MAAM,cAAc,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC3C,mCAAmC;IACnC,EAAE,EAAE,aAAa,CAAC;IAClB,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,iGAAiG;IACjG,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,GAAG,OAAO,IAAI,CAC7C,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,KAC1B,IAAI,CAAC;AAEV;;;;;;GAMG;AACH,qBAAa,KAAK,CAAC,CAAC,GAAG,OAAO;IAC5B,qGAAqG;IACrG,QAAQ,CAAC,QAAQ,uCAA8C;IAC/D,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAU;IAEzB;;;;;OAKG;IACH,YAAY,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAG9C;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;;OAKG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAG5C;IAED;;;;;OAKG;IACG,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAezC;IAED;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAI7B;IAED;;;;;OAKG;IACG,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAEtE;IAED;;;;OAIG;IACG,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAErD;IAED;;;;;;OAMG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAGzC;IAED;;;;;;OAMG;IACG,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CA2BtD;IAED;;;;;OAKG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGzC;IAED;;;;;;OAMG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B9C;IAED;;;;;;;OAOG;IACH,YAAY,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAyBvD;IAED;;;;OAIG;IACH,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,CAG7D;IAID,OAAO,CAAC,kBAAkB;CAuB3B"}