@asaidimu/utils-database 1.0.0

package/index.d.mts

@@ -0,0 +1,527 @@
+import { QueryFilter, PaginationOptions } from '@asaidimu/query';
+import { SchemaDefinition, SchemaChange, DataTransform, PredicateMap } from '@asaidimu/anansi';
+
+declare const DEFAULT_KEYPATH = "$id";
+interface CursorPaginationOptions {
+    limit: number;
+    cursor?: any;
+    direction?: "forward" | "backward";
+}
+interface CursorCallbackResult<T> {
+    value: T | null;
+    done: boolean;
+    offset?: number;
+}
+/**
+ * Callback function for cursor iteration over store records.
+ *
+ * @template T - The type of records stored.
+ * @param value - The current record value (cloned, not a live reference).
+ * @param key - The key (ID) of the current record.
+ * @param cursor - The underlying cursor object (implementation‑specific; may be `null` in memory adapters).
+ * @returns A promise that resolves to an object indicating whether iteration should stop, and an optional offset to advance.
+ */
+type CursorCallback<T> = (value: T, key: string | number, cursor: any) => Promise<CursorCallbackResult<T>>;
+/**
+ * A generic representation of a key range, replacing the browser-specific IDBKeyRange.
+ */
+interface StoreKeyRange {
+    lower?: any;
+    upper?: any;
+    lowerOpen?: boolean;
+    upperOpen?: boolean;
+}
+/**
+ * Storage adapter interface for a single object store (collection).
+ *
+ * This interface abstracts all low‑level persistence operations, allowing
+ * different backends (IndexedDB, memory, remote, etc.) to be used interchangeably.
+ * All methods return promises and operate on clones of data to prevent
+ * unintended mutations.
+ *
+ * @template T - The type of objects stored in this store. Must include the key path property.
+ */
+interface Store<T = any> {
+    /**
+     * Adds one or more records to the store.
+     *
+     * If a record does not have a value for the store's key path, an automatic
+     * key (e.g., auto‑incremented number) may be assigned. The store's key path
+     * property is then updated on the added record(s).
+     *
+     * @param data - A single record or an array of records to add.
+     * @returns A promise that resolves to:
+     *   - the key(s) of the added record(s) – a single key if `data` was a single record,
+     *     or an array of keys if `data` was an array.
+     * @throws {Error} If any record lacks the key path property and auto‑keying is not supported,
+     *                 or if a record with the same key already exists.
+     */
+    add(data: T | T[]): Promise<string | number | (string | number)[]>;
+    /**
+     * Removes all records from the store.
+     *
+     * @returns A promise that resolves when the store is cleared.
+     * @throws {Error} If the operation fails (e.g., store is closed).
+     */
+    clear(): Promise<void>;
+    /**
+     * Returns the total number of records in the store.
+     *
+     * @returns A promise that resolves to the record count.
+     * @throws {Error} If the operation fails.
+     */
+    count(): Promise<number>;
+    /**
+     * Deletes one or more records by their keys.
+     *
+     * @param id - A single key or an array of keys to delete.
+     * @returns A promise that resolves when the records are deleted.
+     * @throws {Error} If any key is `undefined` or the operation fails.
+     */
+    delete(id: string | number | (string | number)[]): Promise<void>;
+    /**
+     * Retrieves a single record by its primary key.
+     *
+     * @param id - The key of the record to retrieve.
+     * @returns A promise that resolves to the record (cloned) if found, otherwise `undefined`.
+     * @throws {Error} If the key is `undefined` or the operation fails.
+     */
+    getById(id: string | number): Promise<T | undefined>;
+    /**
+     * Retrieves a single record by an index and index key.
+     *
+     * @param index - The name of the index to query.
+     * @param key - The exact key value to look up in the index.
+     * @returns A promise that resolves to the first matching record (cloned), or `undefined` if none.
+     * @throws {Error} If the index does not exist, the key is `undefined`, or the operation fails.
+     */
+    getByIndex(index: string, key: any): Promise<T | undefined>;
+    /**
+     * Retrieves multiple records from an index, optionally within a key range.
+     *
+     * @param index - The name of the index to query.
+     * @param keyRange - Optional `StoreKeyRange` to filter results. If omitted, all records are returned.
+     * @returns A promise that resolves to an array of matching records (each cloned).
+     * @throws {Error} If the index does not exist or the operation fails.
+     */
+    getByKeyRange(index: string, keyRange?: StoreKeyRange): Promise<T[]>;
+    /**
+     * Retrieves all records from the store.
+     *
+     * @returns A promise that resolves to an array of all records (each cloned).
+     * @throws {Error} If the operation fails.
+     */
+    getAll(): Promise<T[]>;
+    /**
+     * Inserts or replaces a record.
+     *
+     * If a record with the same key already exists, it is replaced.
+     * The record must contain the store's key path property.
+     *
+     * @param data - The record to store.
+     * @returns A promise that resolves to the key of the stored record.
+     * @throws {Error} If the record lacks the key path property or the operation fails.
+     */
+    put(data: T): Promise<string | number>;
+    /**
+     * Iterates over records using a cursor, allowing early termination and skipping.
+     *
+     * The callback is invoked for each record in iteration order. The callback
+     * can control the iteration by returning `{ done: true }` to stop, or
+     * `{ offset: n }` to skip ahead `n` records.
+     *
+     * @param callback - Function called for each record.
+     * @param direction - Iteration direction: `"forward"` (ascending keys) or `"backward"` (descending keys).
+     * @param keyRange - An optional StoreKeyRange to start from specific points.
+     * @returns A promise that resolves to the last record processed (or `null` if none).
+     * @throws {Error} If the callback throws or the operation fails.
+     */
+    cursor(callback: CursorCallback<T>, direction?: "forward" | "backward", keyRange?: StoreKeyRange): Promise<T | null>;
+    /**
+     * Executes a batch of write operations atomically.
+     *
+     * All operations in the batch succeed or fail together. This is useful for
+     * maintaining consistency when multiple writes are required.
+     *
+     * @param operations - An array of operations. Each operation can be:
+     *   - `{ type: "add" | "put", data: T | T[] }`
+     *   - `{ type: "delete", data: string | number | (string | number)[] }`
+     * @returns A promise that resolves when the batch is committed.
+     * @throws {Error} If any operation fails or the batch cannot be completed.
+     */
+    batch(operations: Array<{
+        type: "add" | "put";
+        data: T | T[];
+    } | {
+        type: "delete";
+        data: string | number | (string | number)[];
+    }>): Promise<void>;
+    open(): Promise<void>;
+}
+interface Collection<T> {
+    /**
+     * Finds a single document matching the query.
+     * @param query - The query to execute.
+     * @returns A promise resolving to the matching document or `null` if not found.
+     */
+    find: (query: QueryFilter<T>) => Promise<Document<T> | null>;
+    /**
+     * Lists documents based on the provided query.
+     * @param query - The query to list documents (supports pagination and sorting).
+     * @returns A promise resolving to an array of documents.
+     */
+    list: (query: PaginationOptions) => Promise<AsyncIterator<Document<T>[]>>;
+    /**
+     * Filters documents based on the provided query.
+     * @param query - The query to filter documents.
+     * @returns A promise resolving to an array of matching documents.
+     */
+    filter: (query: QueryFilter<T>) => Promise<Document<T>[]>;
+    /**
+     * Creates a new document in the schema.
+     * @param initial - The initial data for the document.
+     * @returns A promise resolving to the created document.
+     */
+    create: (initial: T) => Promise<Document<T>>;
+    /**
+     * Subscribes to schema-level events (e.g., "create", "update", "delete", "access").
+     * @param event - The event type to subscribe to.
+     * @param callback - The function to call when the event occurs.
+     * @returns A promise resolving to an unsubscribe function.
+     */
+    subscribe: (event: CollectionEventType | TelemetryEventType, callback: (event: CollectionEvent<T> | TelemetryEvent) => void) => Promise<() => void>;
+    /**
+     * Validate data
+     * @param data - The data to validate
+     * @returns An object containing validation results
+     */
+    validate(data: Record<string, any>): Promise<{
+        value?: any;
+        issues: Array<{
+            message: string;
+            path: Array<string>;
+        }>;
+    }>;
+}
+/**
+ * Event payload for DocumentCursor events.
+ */
+type CollectionEventType = "document:create" | "collection:read" | "migration:start" | "migration:end";
+type CollectionEvent<T> = {
+    type: CollectionEventType;
+    document?: T;
+    model?: string;
+    method?: keyof Collection<T>;
+    metadata?: Record<string, unknown>;
+    timestamp: number;
+};
+interface Database {
+    /**
+     * Accesses a schema model by name.
+     * @param schemaName - The name of the schema to access.
+     * @returns A promise resolving to the schema's DocumentCursor.
+     * @throws DatabaseError
+     */
+    collection: <T>(schemaName: string) => Promise<Collection<T>>;
+    /**
+     * Creates a new schema model.
+     * @param schema - The schema definition.
+     * @returns A promise resolving to the created schema's DocumentCursor.
+     * @throws DatabaseError
+     */
+    createCollection: <T>(schema: SchemaDefinition) => Promise<Collection<T>>;
+    /**
+     * Deletes a schema by name.
+     * @param schemaName - The name of the schema to delete.
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     * @throws DatabaseError
+     */
+    deleteCollection: (schemaName: string) => Promise<boolean>;
+    /**
+     * Updates an existing schema.
+     * @param schema - The updated schema definition.
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     * @throws DatabaseError
+     */
+    updateCollection: (schema: SchemaDefinition) => Promise<boolean>;
+    /**
+     * Migrates an existing collection's data and updates its schema definition metadata.
+     * This function processes data in a streaming fashion to prevent loading
+     * the entire collection into memory.
+     *
+     * It will:
+     * 1. Verify the target collection exists.
+     * 2. Retrieve the collection's current schema definition from a metadata store ($index).
+     * 3. Initialize a `MigrationEngine` with this schema.
+     * 4. Allow a callback to define specific data transformations using the `MigrationEngine`.
+     * 5. **Crucially, it uses `migrationEngine.dryRun()` to get the `newSchema` that results**
+     * **from the transformations defined in the callback.**
+     * 6. Execute these transformations by streaming data from the collection,
+     * through the `MigrationEngine`, and back into the same collection.
+     * 7. Finally, update the schema definition for the collection in the `$index` metadata store
+     * to reflect this `newSchema`.
+     * All these steps for data and metadata updates happen within a single atomic IndexedDB transaction.
+     *
+     * Note: This function focuses solely on *data transformation* and *metadata updates*.
+     * It does NOT handle structural IndexedDB changes like adding/removing physical indexes or object stores,
+     * which still require an `onupgradeneeded` event (i.e., a database version upgrade).
+     *
+     * @param name - The name of the collection (IndexedDB object store) to migrate.
+     * @param {Object} opts - Options for the new migration
+     * @param {SchemaChange<any>[]} opts.changes - Array of schema changes
+     * @param {string} opts.description - Description of the migration
+     * @param {SchemaChange<any>[]} [opts.rollback] - Optional rollback changes
+     * @param {DataTransform<any, any>} [opts.transform] - Optional data transform
+     * @returns A Promise resolving to `true` if the migration completes successfully,
+     * @throws {DatabaseError} If the collection does not exist, its schema metadata is missing,
+     * or any IndexedDB operation/streaming fails critically.
+     */
+    migrateCollection: (name: string, opts: CollectionMigrationOptions, batchSize?: number) => Promise<boolean>;
+    /**
+     * Subscribes to database-level events (e.g., "schemaAdded", "schemaDeleted", "schemaAccessed", "migrate").
+     * @param event - The event type to subscribe to.
+     * @param callback - The function to call when the event occurs.
+     * @returns A promise resolving to an unsubscribe function.
+     */
+    subscribe: (event: DatabaseEventType | "telemetry", callback: (event: DatabaseEvent | TelemetryEvent) => void) => Promise<() => void>;
+    /**
+     * Closes the connection to the database
+     */
+    close: () => void;
+}
+type CollectionMigrationOptions = {
+    changes: SchemaChange<any>[];
+    description: string;
+    rollback?: SchemaChange<any>[];
+    transform?: string | DataTransform<any, any>;
+};
+/**
+ * Event payload for Database events.
+ */
+type DatabaseEventType = "collection:create" | "collection:delete" | "collection:update" | "collection:read" | "migrate";
+type DatabaseEvent = {
+    type: DatabaseEventType;
+    schema?: SchemaDefinition | Partial<SchemaDefinition>;
+    timestamp: number;
+};
+type Document<T> = {
+    readonly [K in keyof T]: T[K];
+} & {
+    /**
+     * A unique identifier for the document
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     */
+    $id?: string;
+    /**
+     * A timestamp indicating when the document was created
+     */
+    $created?: string | Date;
+    /**
+     * A timestamp indicating when the document was last updated
+     */
+    $updated?: string | Date;
+    /**
+     * A number representing how many times the document has changed
+     */
+    $version?: number;
+    /**
+     * Fetches the latest data from the database
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     */
+    read: () => Promise<boolean>;
+    /**
+     * Updates the document with the provided properties.
+     * @param props - Partial object containing the fields to update.
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     */
+    update: (props: Partial<T>) => Promise<boolean>;
+    /**
+     * Deletes the document from the database.
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     */
+    delete: () => Promise<boolean>;
+    /**
+     * Subscribes to document events (e.g., "update", "delete", "access").
+     * @param event - The event type to subscribe to.
+     * @param callback - The function to call when the event occurs.
+     * @returns A promise resolving to an unsubscribe function.
+     */
+    subscribe: (event: DocumentEventType | TelemetryEventType, callback: (event: DocumentEvent<T> | TelemetryEvent) => void) => () => void;
+    state(): T;
+};
+/**
+ * Event payload for DocumentModel events.
+ */
+type DocumentEventType = "document:create" | "document:write" | "document:update" | "document:delete" | "document:read";
+type DocumentEvent<T> = {
+    type: DocumentEventType;
+    data?: Partial<T>;
+    timestamp: number;
+};
+type TelemetryEventType = "telemetry";
+type TelemetryEvent = {
+    type: TelemetryEventType;
+    method: string;
+    timestamp: number;
+    source: any;
+    metadata: {
+        args: any[];
+        performance: {
+            durationMs: number;
+        };
+        source: {
+            level: "database" | "collection" | "document";
+            collection?: string;
+            document?: string;
+        };
+        result?: {
+            type: 'array' | string;
+            size?: number;
+        };
+        error: {
+            message: string;
+            name: string;
+            stack?: string;
+        } | null;
+    };
+};
+interface DatabaseConfig {
+    name: string;
+    keyPath?: string;
+    schemasStoreName?: string;
+    enableTelemetry?: boolean;
+    predicates?: PredicateMap;
+    validate?: boolean;
+}
+
+declare class MemoryStore<T extends Record<string, any>> implements Store<T> {
+    private readonly keyPath;
+    private data;
+    private nextId;
+    constructor(keyPath?: string);
+    open(): Promise<void>;
+    private getKey;
+    private clone;
+    add(data: T | T[]): Promise<string | number | (string | number)[]>;
+    put(data: T): Promise<string | number>;
+    batch(operations: Array<{
+        type: "add" | "put";
+        data: T | T[];
+    } | {
+        type: "delete";
+        data: string | number | (string | number)[];
+    }>): Promise<void>;
+    getById(id: string | number): Promise<T | undefined>;
+    delete(id: string | number | (string | number)[]): Promise<void>;
+    clear(): Promise<void>;
+    count(): Promise<number>;
+    getByIndex(index: string, key: any): Promise<T | undefined>;
+    getByKeyRange(indexName: string, keyRange?: StoreKeyRange): Promise<T[]>;
+    private isInKeyRange;
+    getAll(): Promise<T[]>;
+    cursor(callback: CursorCallback<T>, direction?: "forward" | "backward", keyRange?: StoreKeyRange): Promise<T | null>;
+}
+
+declare function createEphemeralStore<T extends Record<string, any>>(config: DatabaseConfig): MemoryStore<T>;
+
+/**
+ * Manages the lifecycle and state of an IndexedDB connection, ensuring
+ * schema stores and collections are created and upgraded safely.
+ */
+declare class ConnectionManager {
+    private readonly config;
+    private connectionInitializer;
+    private readonly schemasStoreName;
+    /**
+     * Initializes a new ConnectionManager.
+     *
+     * @param config - The database configuration options.
+     */
+    constructor(config: DatabaseConfig);
+    /**
+     * Opens the database and ensures the base schemas store exists.
+     *
+     * @returns A promise that resolves to the opened IDBDatabase instance.
+     * @throws {Error} If the database fails to open.
+     */
+    private openDatabase;
+    /**
+     * Upgrades the database version and executes the provided upgrade logic.
+     *
+     * @param currentConnection - The existing active IndexedDB connection to be closed.
+     * @param upgradeCallback - A callback function containing the structural changes to apply during the upgrade.
+     * @returns A promise that resolves to the newly upgraded IDBDatabase instance.
+     * @throws {Error} If the database upgrade fails.
+     */
+    private upgradeDatabase;
+    /**
+     * Ensures a collection object store exists within the database.
+     * Triggers an upgrade if the specified store is missing.
+     *
+     * @param collectionName - The name of the collection store to ensure.
+     * @param keyPath - The primary key path for the collection (defaults to "$id").
+     * @returns A promise that resolves when the store is confirmed to exist.
+     */
+    ensureStore(collectionName: string, keyPath?: string): Promise<void>;
+    /**
+     * Retrieves or opens the active database connection.
+     * Handles connection loss and version changes automatically.
+     *
+     * @returns A promise resolving to the active IDBDatabase connection.
+     * @throws {DatabaseError} If the connection initialization fails.
+     */
+    getConnection: () => Promise<IDBDatabase>;
+    /**
+     * Performs a version upgrade using custom structural logic.
+     * Resets the internal initialization state so subsequent callers wait for the new version.
+     *
+     * @param upgradeLogic - A callback executed during the IndexedDB upgradeneeded event.
+     * @returns A promise resolving to the upgraded IDBDatabase connection.
+     * @throws {DatabaseError} If the internal upgrade procedure fails.
+     */
+    upgrade(upgradeLogic: (db: IDBDatabase) => void): Promise<IDBDatabase>;
+    /**
+     * Closes the active database connection and resets the internal initialization state.
+     */
+    close(): void;
+}
+
+declare class IndexedDBStore<T extends Record<string, any>> implements Store<T> {
+    private readonly getConnection;
+    private readonly storeName;
+    private readonly keyPath;
+    private readonly onOpen;
+    constructor(getConnection: () => Promise<IDBDatabase>, storeName: string, keyPath: string | undefined, onOpen: () => Promise<void>);
+    open(): Promise<void>;
+    /**
+     * Map native DOMExceptions to internal DatabaseErrors.
+     */
+    private mapError;
+    /**
+     * Core wrapper for transaction safety. It converts IDB request callbacks
+     * into a single Promise while preserving transaction activity.
+     */
+    private withTx;
+    private requestToPromise;
+    put(data: T): Promise<string | number>;
+    add(data: T | T[]): Promise<string | number | (string | number)[]>;
+    batch(operations: Array<{
+        type: "add" | "put";
+        data: T | T[];
+    } | {
+        type: "delete";
+        data: string | number | (string | number)[];
+    }>): Promise<void>;
+    getById(id: string | number): Promise<T | undefined>;
+    delete(id: string | number | (string | number)[]): Promise<void>;
+    clear(): Promise<void>;
+    count(): Promise<number>;
+    getByIndex(indexName: string, key: any): Promise<T | undefined>;
+    getByKeyRange(indexName: string, keyRange?: StoreKeyRange): Promise<T[]>;
+    getAll(): Promise<T[]>;
+    cursor(callback: CursorCallback<T>, direction?: "forward" | "backward", keyRange?: StoreKeyRange): Promise<T | null>;
+}
+
+declare const createIndexedDbStore: <T extends Record<string, any>>(config: DatabaseConfig) => Store<T>;
+
+export { type Collection, type CollectionEvent, type CollectionEventType, type CollectionMigrationOptions, ConnectionManager, type CursorCallback, type CursorCallbackResult, type CursorPaginationOptions, DEFAULT_KEYPATH, type Database, type DatabaseConfig, type DatabaseEvent, type DatabaseEventType, type Document, type DocumentEvent, type DocumentEventType, IndexedDBStore, type Store, type StoreKeyRange, type TelemetryEvent, type TelemetryEventType, createEphemeralStore, createIndexedDbStore };