@asaidimu/utils-database 2.0.0 → 3.1.0

package/README.md

@@ -83,7 +83,7 @@ const db = await DatabaseConnection(
     enableTelemetry: true,
     predicates: {}, // custom validation predicates (optional)
   },
-  createIndexedDbStore
+  createIndexedDbStore,
 );
 ```
 
@@ -171,7 +171,7 @@ await db.migrateCollection(
     },
     description: "Add active flag",
   },
-  100 // batch size (optional)
+  100, // batch size (optional)
 );
 ```
 
@@ -199,7 +199,9 @@ const unsubDoc = doc.subscribe("document:update", (event) => {
 
 // Telemetry (when enableTelemetry: true)
 db.subscribe("telemetry", (event) => {
-  console.log(`${event.method} took ${event.metadata.performance.durationMs}ms`);
+  console.log(
+    `${event.method} took ${event.metadata.performance.durationMs}ms`,
+  );
 });
 ```
 
@@ -291,10 +293,10 @@ For migrations: `migrateCollection` streams documents from the store, passes the
 
 ### Available Scripts
 
-| Command           | Description                                        |
-| ----------------- | -------------------------------------------------- |
-| `npm test`        | Run tests once (Vitest)                           |
-| `npm run test:watch` | Run tests in watch mode                       |
+| Command                | Description                                       |
+| ---------------------- | ------------------------------------------------- |
+| `npm test`             | Run tests once (Vitest)                           |
+| `npm run test:watch`   | Run tests in watch mode                           |
 | `npm run test:browser` | Run tests in a real browser (Vitest browser mode) |
 
 ### Testing
@@ -323,12 +325,12 @@ Use the [GitHub issue tracker](https://github.com/asaidimu/erp-utils/issues) to
 
 ### Troubleshooting
 
-| Error                             | Likely cause & solution                                   |
-| --------------------------------- | --------------------------------------------------------- |
-| `SCHEMA_NOT_FOUND`                | The collection was not created. Call `createCollection` first. |
-| `CONFLICT`                        | Another operation updated the document. Re‑fetch and retry. |
-| `TRANSACTION_FAILED`              | One of the batched writes failed. Check individual operations. |
-| `INVALID_DATA`                    | The document does not match the schema. Review validation errors. |
+| Error                | Likely cause & solution                                           |
+| -------------------- | ----------------------------------------------------------------- |
+| `SCHEMA_NOT_FOUND`   | The collection was not created. Call `createCollection` first.    |
+| `CONFLICT`           | Another operation updated the document. Re‑fetch and retry.       |
+| `TRANSACTION_FAILED` | One of the batched writes failed. Check individual operations.    |
+| `INVALID_DATA`       | The document does not match the schema. Review validation errors. |
 
 ### FAQ
 
@@ -355,6 +357,7 @@ This project is licensed under the **MIT License**. See the [LICENSE](https://gi
 ### Acknowledgments
 
 Built with ❤️ using:
+
 - [`@asaidimu/anansi`](https://github.com/asaidimu/anansi) – schema validation and migrations.
 - [`@standard-schema/spec`](https://github.com/standard-schema/standard-schema) – Standard Schema interoperability.
 - [`uuid`](https://github.com/uuidjs/uuid) – for v7 UUIDs.

package/index.d.mts

@@ -278,6 +278,16 @@ interface Collection<T> {
      * @param tx - Optional transaction to buffer the write into.
      */
     create: (initial: T, tx?: TransactionContext) => Promise<Document<T>>;
+    /**
+     * Updates all documents matching the query with the provided partial data.
+     * Returns the number of documents updated.
+     */
+    update: (query: QueryFilter<T>, data: Partial<T>, tx?: TransactionContext) => Promise<number>;
+    /**
+     * Deletes all documents matching the query.
+     * Returns the number of documents deleted.
+     */
+    delete: (query: QueryFilter<T>, tx?: TransactionContext) => Promise<number>;
     /**
      * Subscribes to collection-level events.
      */
@@ -366,19 +376,22 @@ type DatabaseEvent = {
     schema?: SchemaDefinition | Partial<SchemaDefinition>;
     timestamp: number;
 };
-type Document<T> = {
-    readonly [K in keyof T]: T[K];
-} & {
+type DocumentMetadata = {
     $id?: string;
     $created?: string | Date;
     $updated?: string | Date;
     $version?: number;
+};
+type Document<T> = {
+    readonly [K in keyof T]: T[K];
+} & DocumentMetadata & {
     read: () => Promise<boolean>;
     save: (tx?: TransactionContext) => Promise<boolean>;
     update: (props: Partial<T>, tx?: TransactionContext) => Promise<boolean>;
     delete: (tx?: TransactionContext) => Promise<boolean>;
     subscribe: (event: DocumentEventType | TelemetryEventType, callback: (event: DocumentEvent<T> | TelemetryEvent) => void) => () => void;
     state(): T;
+    $metadata(): DocumentMetadata;
 };
 type DocumentEventType = "document:create" | "document:write" | "document:update" | "document:delete" | "document:read";
 type DocumentEvent<T> = {
@@ -727,6 +740,73 @@ declare const createIndexedDbStore: <T extends Record<string, any>>(config: Stor
 
 declare function DatabaseConnection(config: Omit<DatabaseConfig, "keyPath">, createStore: <T extends Record<string, any>>(config: StoreConfig, indexes: IndexDefinition[]) => Store<T>): Promise<Database>;
 
+interface MutexOptions {
+    /**
+     * Maximum number of pending requests allowed in the queue.
+     * If exceeded, tryLock/lock will fail.
+     * @default Infinity
+     */
+    capacity?: number;
+    /**
+     * Controls how lock handoff is scheduled when a waiter is unblocked.
+     *
+     * - `"macrotask"` (default): Uses setTimeout(fn, 0) to yield to the event
+     *   loop between handoffs. Prevents microtask starvation under heavy
+     *   contention — I/O, rendering, and other macrotasks can run between
+     *   lock acquisitions. Use for Serializer and other coarse-grained
+     *   serializers.
+     *
+     * - `"microtask"`: Uses queueMicrotask(fn) for handoff. Near-zero latency
+     *   between acquisitions — no macrotask delay. Safe when you need
+     *   back-to-back operations to complete as fast as possible and starvation
+     *   is not a concern (e.g. Once, Semaphore where builds are infrequent
+     *   and latency matters more than fairness).
+     */
+    yieldMode?: "macrotask" | "microtask";
+}
+/**
+ * A mutual exclusion lock.
+ * Allows only one execution context to access a resource at a time.
+ *
+ * Yield mode is configurable per instance:
+ * - "macrotask" (default): yields between handoffs, preventing microtask starvation.
+ * - "microtask": zero-delay handoff for latency-sensitive paths.
+ */
+declare class Mutex {
+    private _locked;
+    private _capacity;
+    private _yieldMode;
+    private waiters;
+    constructor(options?: MutexOptions);
+    /**
+     * Acquires the lock. If already held, waits until released or timeout reached.
+     *
+     * @param timeout - Optional maximum wait time in milliseconds.
+     * @throws {TimeoutError} If the lock cannot be acquired within the timeout.
+     * @throws {Error} If the wait queue is full (backpressure).
+     */
+    lock(timeout?: number): Promise<void>;
+    /**
+     * Attempts to acquire the lock without waiting.
+     * @returns `true` if the lock was acquired, `false` otherwise.
+     */
+    tryLock(): boolean;
+    /**
+     * Releases the lock, scheduling the next waiter according to yieldMode.
+     *
+     * When a waiter exists, `_locked` intentionally remains `true` — ownership
+     * transfers directly to the next waiter without ever clearing the flag.
+     * Only when the queue is empty is `_locked` set to false.
+     *
+     * @throws {Error} If the mutex is not currently locked.
+     */
+    unlock(): void;
+    /** Returns true if the mutex is currently locked. */
+    locked(): boolean;
+    /** Returns the number of operations waiting for the lock. */
+    pending(): number;
+}
+
 /**
  * Interface defining the shape of the EventBus.
  * @template TEventMap - A record mapping event names to their respective payload types.
@@ -797,13 +877,6 @@ declare class Pipeline {
     wrap<T extends object>(target: T, baseContext: Partial<MiddlewareContext>): T;
 }
 
-declare class Mutex {
-    private queue;
-    private locked;
-    acquire(): Promise<() => void>;
-    private release;
-}
-
 interface DocumentOptions<T extends Record<string, any>> {
     /**
      * The already-persisted initial state of the document.
@@ -812,6 +885,7 @@ interface DocumentOptions<T extends Record<string, any>> {
      */
     initial: Partial<T>;
     collection: string;
+    schema: SchemaDefinition;
     validator?: StandardSchemaV1;
     store: Store<T>;
     bus: EventBus<Record<DocumentEventType | TelemetryEventType, DocumentEvent<T> | TelemetryEvent>>;
@@ -832,13 +906,14 @@ interface DocumentOptions<T extends Record<string, any>> {
 declare function createDocument<T extends Record<string, any>>(opts: DocumentOptions<T>): Promise<Document<T & {
     $id: string | number;
 }>>;
-declare function openCollection<T extends Record<string, any>>({ collection: schema, validator, bus, store, pipeline, validate, }: {
+declare function openCollection<T extends Record<string, any>>({ collection: schemaName, validator, bus, store, pipeline, validate, schema: schemaDefinition, }: {
     store: Store<T>;
     collection: string;
     validator: StandardSchemaV1;
     bus: EventBus<any>;
     pipeline: Pipeline;
     validate: boolean;
+    schema: SchemaDefinition;
 }): Promise<Collection<T>>;
 
 /**
@@ -879,13 +954,17 @@ declare class DatabaseError extends Error {
      * The schema associated with the error, if applicable.
      */
     schema?: SchemaDefinition;
+    /**
+     * Issues associated with the error
+     */
+    issues?: any[];
     /**
      * Constructs a new DatabaseErrorClass instance.
      * @param type - The type of error that occurred.
      * @param message - A human-readable message describing the error.
      * @param schema - The schema associated with the error, if applicable.
      */
-    constructor(type: DatabaseErrorType, message: string, schema?: SchemaDefinition, cause?: unknown);
+    constructor(type: DatabaseErrorType, message: string, schema?: SchemaDefinition, cause?: unknown, issues?: any);
 }
 
-export { type BufferedOperation, type Collection, type CollectionEvent, type CollectionEventType, type CollectionMigrationOptions, ConnectionManager, type CursorCallback, type CursorCallbackResult, type CursorPaginationOptions, DEFAULT_KEYPATH, type Database, type DatabaseConfig, DatabaseConnection, DatabaseError, DatabaseErrorType, type DatabaseEvent, type DatabaseEventType, type Document, type DocumentEvent, type DocumentEventType, IndexedDBStore, type Store, type StoreConfig, type StoreKeyRange, type TelemetryEvent, type TelemetryEventType, createDocument, createEphemeralStore, createIndexedDbStore, openCollection };
+export { type BufferedOperation, type Collection, type CollectionEvent, type CollectionEventType, type CollectionMigrationOptions, ConnectionManager, type CursorCallback, type CursorCallbackResult, type CursorPaginationOptions, DEFAULT_KEYPATH, type Database, type DatabaseConfig, DatabaseConnection, DatabaseError, DatabaseErrorType, type DatabaseEvent, type DatabaseEventType, type Document, type DocumentEvent, type DocumentEventType, type DocumentMetadata, IndexedDBStore, type Store, type StoreConfig, type StoreKeyRange, type TelemetryEvent, type TelemetryEventType, createDocument, createEphemeralStore, createIndexedDbStore, openCollection };

package/index.d.ts

@@ -278,6 +278,16 @@ interface Collection<T> {
      * @param tx - Optional transaction to buffer the write into.
      */
     create: (initial: T, tx?: TransactionContext) => Promise<Document<T>>;
+    /**
+     * Updates all documents matching the query with the provided partial data.
+     * Returns the number of documents updated.
+     */
+    update: (query: QueryFilter<T>, data: Partial<T>, tx?: TransactionContext) => Promise<number>;
+    /**
+     * Deletes all documents matching the query.
+     * Returns the number of documents deleted.
+     */
+    delete: (query: QueryFilter<T>, tx?: TransactionContext) => Promise<number>;
     /**
      * Subscribes to collection-level events.
      */
@@ -366,19 +376,22 @@ type DatabaseEvent = {
     schema?: SchemaDefinition | Partial<SchemaDefinition>;
     timestamp: number;
 };
-type Document<T> = {
-    readonly [K in keyof T]: T[K];
-} & {
+type DocumentMetadata = {
     $id?: string;
     $created?: string | Date;
     $updated?: string | Date;
     $version?: number;
+};
+type Document<T> = {
+    readonly [K in keyof T]: T[K];
+} & DocumentMetadata & {
     read: () => Promise<boolean>;
     save: (tx?: TransactionContext) => Promise<boolean>;
     update: (props: Partial<T>, tx?: TransactionContext) => Promise<boolean>;
     delete: (tx?: TransactionContext) => Promise<boolean>;
     subscribe: (event: DocumentEventType | TelemetryEventType, callback: (event: DocumentEvent<T> | TelemetryEvent) => void) => () => void;
     state(): T;
+    $metadata(): DocumentMetadata;
 };
 type DocumentEventType = "document:create" | "document:write" | "document:update" | "document:delete" | "document:read";
 type DocumentEvent<T> = {
@@ -727,6 +740,73 @@ declare const createIndexedDbStore: <T extends Record<string, any>>(config: Stor
 
 declare function DatabaseConnection(config: Omit<DatabaseConfig, "keyPath">, createStore: <T extends Record<string, any>>(config: StoreConfig, indexes: IndexDefinition[]) => Store<T>): Promise<Database>;
 
+interface MutexOptions {
+    /**
+     * Maximum number of pending requests allowed in the queue.
+     * If exceeded, tryLock/lock will fail.
+     * @default Infinity
+     */
+    capacity?: number;
+    /**
+     * Controls how lock handoff is scheduled when a waiter is unblocked.
+     *
+     * - `"macrotask"` (default): Uses setTimeout(fn, 0) to yield to the event
+     *   loop between handoffs. Prevents microtask starvation under heavy
+     *   contention — I/O, rendering, and other macrotasks can run between
+     *   lock acquisitions. Use for Serializer and other coarse-grained
+     *   serializers.
+     *
+     * - `"microtask"`: Uses queueMicrotask(fn) for handoff. Near-zero latency
+     *   between acquisitions — no macrotask delay. Safe when you need
+     *   back-to-back operations to complete as fast as possible and starvation
+     *   is not a concern (e.g. Once, Semaphore where builds are infrequent
+     *   and latency matters more than fairness).
+     */
+    yieldMode?: "macrotask" | "microtask";
+}
+/**
+ * A mutual exclusion lock.
+ * Allows only one execution context to access a resource at a time.
+ *
+ * Yield mode is configurable per instance:
+ * - "macrotask" (default): yields between handoffs, preventing microtask starvation.
+ * - "microtask": zero-delay handoff for latency-sensitive paths.
+ */
+declare class Mutex {
+    private _locked;
+    private _capacity;
+    private _yieldMode;
+    private waiters;
+    constructor(options?: MutexOptions);
+    /**
+     * Acquires the lock. If already held, waits until released or timeout reached.
+     *
+     * @param timeout - Optional maximum wait time in milliseconds.
+     * @throws {TimeoutError} If the lock cannot be acquired within the timeout.
+     * @throws {Error} If the wait queue is full (backpressure).
+     */
+    lock(timeout?: number): Promise<void>;
+    /**
+     * Attempts to acquire the lock without waiting.
+     * @returns `true` if the lock was acquired, `false` otherwise.
+     */
+    tryLock(): boolean;
+    /**
+     * Releases the lock, scheduling the next waiter according to yieldMode.
+     *
+     * When a waiter exists, `_locked` intentionally remains `true` — ownership
+     * transfers directly to the next waiter without ever clearing the flag.
+     * Only when the queue is empty is `_locked` set to false.
+     *
+     * @throws {Error} If the mutex is not currently locked.
+     */
+    unlock(): void;
+    /** Returns true if the mutex is currently locked. */
+    locked(): boolean;
+    /** Returns the number of operations waiting for the lock. */
+    pending(): number;
+}
+
 /**
  * Interface defining the shape of the EventBus.
  * @template TEventMap - A record mapping event names to their respective payload types.
@@ -797,13 +877,6 @@ declare class Pipeline {
     wrap<T extends object>(target: T, baseContext: Partial<MiddlewareContext>): T;
 }
 
-declare class Mutex {
-    private queue;
-    private locked;
-    acquire(): Promise<() => void>;
-    private release;
-}
-
 interface DocumentOptions<T extends Record<string, any>> {
     /**
      * The already-persisted initial state of the document.
@@ -812,6 +885,7 @@ interface DocumentOptions<T extends Record<string, any>> {
      */
     initial: Partial<T>;
     collection: string;
+    schema: SchemaDefinition;
     validator?: StandardSchemaV1;
     store: Store<T>;
     bus: EventBus<Record<DocumentEventType | TelemetryEventType, DocumentEvent<T> | TelemetryEvent>>;
@@ -832,13 +906,14 @@ interface DocumentOptions<T extends Record<string, any>> {
 declare function createDocument<T extends Record<string, any>>(opts: DocumentOptions<T>): Promise<Document<T & {
     $id: string | number;
 }>>;
-declare function openCollection<T extends Record<string, any>>({ collection: schema, validator, bus, store, pipeline, validate, }: {
+declare function openCollection<T extends Record<string, any>>({ collection: schemaName, validator, bus, store, pipeline, validate, schema: schemaDefinition, }: {
     store: Store<T>;
     collection: string;
     validator: StandardSchemaV1;
     bus: EventBus<any>;
     pipeline: Pipeline;
     validate: boolean;
+    schema: SchemaDefinition;
 }): Promise<Collection<T>>;
 
 /**
@@ -879,13 +954,17 @@ declare class DatabaseError extends Error {
      * The schema associated with the error, if applicable.
      */
     schema?: SchemaDefinition;
+    /**
+     * Issues associated with the error
+     */
+    issues?: any[];
     /**
      * Constructs a new DatabaseErrorClass instance.
      * @param type - The type of error that occurred.
      * @param message - A human-readable message describing the error.
      * @param schema - The schema associated with the error, if applicable.
      */
-    constructor(type: DatabaseErrorType, message: string, schema?: SchemaDefinition, cause?: unknown);
+    constructor(type: DatabaseErrorType, message: string, schema?: SchemaDefinition, cause?: unknown, issues?: any);
 }
 
-export { type BufferedOperation, type Collection, type CollectionEvent, type CollectionEventType, type CollectionMigrationOptions, ConnectionManager, type CursorCallback, type CursorCallbackResult, type CursorPaginationOptions, DEFAULT_KEYPATH, type Database, type DatabaseConfig, DatabaseConnection, DatabaseError, DatabaseErrorType, type DatabaseEvent, type DatabaseEventType, type Document, type DocumentEvent, type DocumentEventType, IndexedDBStore, type Store, type StoreConfig, type StoreKeyRange, type TelemetryEvent, type TelemetryEventType, createDocument, createEphemeralStore, createIndexedDbStore, openCollection };
+export { type BufferedOperation, type Collection, type CollectionEvent, type CollectionEventType, type CollectionMigrationOptions, ConnectionManager, type CursorCallback, type CursorCallbackResult, type CursorPaginationOptions, DEFAULT_KEYPATH, type Database, type DatabaseConfig, DatabaseConnection, DatabaseError, DatabaseErrorType, type DatabaseEvent, type DatabaseEventType, type Document, type DocumentEvent, type DocumentEventType, type DocumentMetadata, IndexedDBStore, type Store, type StoreConfig, type StoreKeyRange, type TelemetryEvent, type TelemetryEventType, createDocument, createEphemeralStore, createIndexedDbStore, openCollection };