@slimr/dbsync 0.0.3

package/README.md

@@ -0,0 +1,183 @@
+# 🪶 @slimr/dbsync [![npm package](https://img.shields.io/npm/v/@slimr/dbsync.svg?style=flat-square)](https://npmjs.org/package/@slimr/dbsync)
+
+A powerfully slim, offline-first IndexedDB ORM and sync engine.
+
+`@slimr/dbsync` provides a simple, Promise-based NoSQL API for browser data while automatically turning your app into a robust offline-first experience. It quietly queues changes made offline and perfectly synchronizes a local IndexedDB with a remote `@slimr/swift-crud` backed SQL database via background polling and Web Locks.
+
+## Context
+
+`@slimr` is a set of slim React (hence '@slimr') libs. Check them all out on [github](https://github.com/bdombro/slimr)!
+
+## Why use `dbsync`?
+
+- 🚀 **Zero-Config Schemas:** Define your tables and indexes in JS. `dbsync` automatically calculates schema signatures and handles IndexedDB `onupgradeneeded` version bumping and cross-device schema sync seamlessly.
+- ⚡️ **Offline-First Resilience:** Read and write instantly, network or no network. Mutations are automatically written to a background queue and flushed to the backend as soon as connectivity is restored.
+- 🔄 **Cross-Tab Reactivity:** Utilizing an internal Pub/Sub system and `BroadcastChannel`, any data changes (either local or synced from the server) instantly trigger subscribers, ensuring UI hooks eagerly re-render across all open tabs.
+- 🔐 **First-Class Identity:** Deeply integrated with backend authentication, managing `isAuth` state, logins, and securely wiping local databases on logout.
+- 🌱 **Zero Dependencies:** Built entirely on standard Web APIs (IndexedDB, BroadcastChannel, Web Locks, `fetch`). Fits the `@slimr` ethos perfectly.
+
+## Installation
+
+```bash
+npm install @slimr/dbsync
+```
+
+## Quick Start
+You instantiate `dbsync` by supplying your backend [adapter](./src/adapters/Adapters.md) and your table/index definitions. Afterwards, you must call `.init()` to safely generate the database.
+
+```typescript
+import { DbSync } from '@slimr/dbsync';
+import { RestAdapter } from '@slimr/dbsync/adapters';
+
+const dbAdapter = new RestAdapter({ url: 'https://api.myapp.com' });
+
+const db = new DbSync({
+    adapter: dbAdapter,
+    tables: {
+        posts: { indexes: ['userId', 'updatedAt'] },
+        users: { indexes: ['email'] }
+    }
+});
+
+// Await init before usage
+await db.init();
+```
+
+## Schema Versioning
+
+`@slimr/dbsync` automatically manages your IndexedDB database versioning to prevent schema mismatches and corruption across tabs and devices.
+
+By default, you don't even need to provide a `version`. The library calculates a **deterministic schema signature** based on the tables and indexes you define in `tables`. If you modify your schema, the signature changes, the local IndexedDB version is automatically incremented, and this schema change is announced to the backend. Other tabs and devices syncing from the server will detect the new signature and safely reload to adapt to the new schema without mutating data out-of-bounds.
+
+If you prefer explicit control, you can provide an exact `version: number` in the config. `@slimr/dbsync` will strictly enforce that exact version across the network instead.
+
+## The ORM API
+Once initialized, `dbsync` acts as a fast NoSQL document store. To support offline-first behavior, you should generate IDs locally using `db.uuid()`.
+
+### Basic CRUD
+```typescript
+// Create
+const newPost = await db.put('posts', { 
+    id: db.genUuid(), 
+    content: 'Hello World!', 
+    userId: 'user_123' 
+});
+
+// Read
+const myPost = await db.get('posts', newPost.id);
+const allPosts = await db.findAll('posts');
+
+// Delete
+await db.delete('posts', newPost.id);
+```
+
+
+### Typed Repositories (`DbRepository`)
+For a cleaner developer experience, you can wrap a table in a `DbRepository`. This automatically binds the table name and TypeScript generic to the CRUD methods so you don't have to repeat them everywhere.
+
+```typescript
+import { DbRepository } from '@slimr/dbsync';
+
+interface Post { id: string; content: string; }
+const postsRepo = new DbRepository<Post>(db, 'posts');
+
+// Types act natively without passing the table name again
+await postsRepo.put({ id: '1', content: 'Cleaner code!' });
+const post = await postsRepo.findById('1');
+```
+
+### Atomic Transactions
+Need to update multiple records or cross-table data safely? Buffer them in memory and commit them all at once. In contrast to the transaction API of IndexedDB, `DbSync` transactions are purely in-memory and only hit the database when you call `commit()`. This means you can batch as many operations as you want without worrying about transaction timeouts, locks,
+or the indexeddb quirk where it automatically commits after a certain number of operations.
+
+```typescript
+const tx = db.getTransaction();
+
+tx.put('posts', { id: '1', content: 'Atomic write 1' });
+tx.put('posts', { id: '2', content: 'Atomic write 2' });
+tx.delete('users', 'bad_user');
+
+// Writes hit the database together
+await tx.commit();
+```
+
+Alternatively, you can create a `DbTxRepository`, similar to `DbRepository`, to encapsulate the raw table name semantics and enforce typescript hinting across your consumer app via a singleton:
+
+```typescript
+import { DbTxRepository } from '@slimr/dbsync';
+
+class Tx {
+    private tx = db.getTransaction();
+
+    // Wrap your tables for strict typings & intellisense
+    posts = new DbTxRepository<Post>(this.tx, 'posts');
+    users = new DbTxRepository<User>(this.tx, 'users');
+
+    commit = () => this.tx.commit();
+}
+
+const tx = new Tx();
+tx.posts.put({ id: '1', content: 'Atomic write 1' });
+tx.posts.put({ id: '2', content: 'Atomic write 2' });
+tx.users.delete('bad_user');
+
+// Writes hit the database together
+await tx.commit();
+```
+
+### UI Reactivity (Pub/Sub)
+Whenever a table is modified—whether by you manually, or by a background Sync Engine pull—`dbsync` announces the change.
+
+```typescript
+const sub = db.subscribe((updatedStores) => {
+    if (updatedStores.includes('posts')) {
+        console.log('The posts table was just updated!');
+        // Trigger your React state re-render here
+    }
+});
+
+// Clean up on component unmount
+sub.close();
+```
+
+### React Hook (`useDbQuery`)
+For React users, `@slimr/dbsync` exports a built-in `useDbQuery` hook that makes binding components to your data effortless. It executes your query natively and instantly re-renders the component whenever the underlying table changes locally or remotely!
+
+```tsx
+import { useDbQuery } from '@slimr/dbsync/react';
+
+function PostList({ db }) {
+    // Re-renders automatically whenever the 'posts' table changes!
+    const posts = useDbQuery(db, 'posts', () => db.findAll('posts'));
+
+    if (!posts) return <Spinner />;
+    return <ul>{posts.map(p => <li key={p.id}>{p.content}</li>)}</ul>;
+}
+```
+
+## The Offline Sync Engine
+By routing your `put` and `delete` operations exclusively through the `DbSync` class, updates are silently logged into highly scalable native `dirtyQueue` and `deletedQueue` tables under-the-hood.
+
+To boot up the network synchronizer to clear those queues and fetch server updates:
+
+```typescript
+// Start polling the swift-crud backend every 5 seconds
+db.enable();
+
+// Stop polling
+db.disable();
+```
+
+Only one tab on a user's device will act as the "Leader" and poll the network at any time using **Web Locks**. All other tabs remain completely idle and rely on `BroadcastChannel` messages from the Leader tab to reactively update their UI when fresh data drops.
+
+
+## Session Management
+Because offline data is fundamentally tied to an authenticated session, `DbSync` wraps the core identity commands to ensure background syncing strictly follows network permissions.
+
+```typescript
+// Authenticate and unlock syncing
+await db.login('user@email.com', '123456');
+
+// Wipe the IndexedDB totally clean + log out immediately
+await db.reset();
+```

package/cjs/DbRepository.d.ts

@@ -0,0 +1,59 @@
+import type { DbSync } from "./DbSync.js";
+/**
+ * A typed repository wrapper for a single `DbSync` object store.
+ * Provides a localized CRUD interface to minimize boilerplate and
+ * enforce consistent data types for a specific table.
+ */
+export declare class DbRepository<T> {
+    protected db: DbSync;
+    readonly storeName: string;
+    /**
+     * Initializes a new repository tied to a specific object store.
+     *
+     * @param db The centralized `DbSync` instance.
+     * @param storeName The name of the object store this repository will manage.
+     */
+    constructor(db: DbSync, storeName: string);
+    /**
+     * Retrieves a single record by its primary key.
+     *
+     * @param id The primary key of the record to retrieve.
+     * @returns A promise resolving to the typed record, or `undefined` if not found.
+     */
+    findById(id: string | number): Promise<T | undefined>;
+    /**
+     * Retrieves all records currently held in the object store.
+     *
+     * @returns A promise resolving to an array of all typed records.
+     */
+    findAll(): Promise<T[]>;
+    /**
+     * Inserts a new record into the object store.
+     *
+     * @param value The object payload to insert.
+     * @param key An optional explicit primary key.
+     * @returns A promise resolving to the newly inserted record.
+     */
+    add(value: Partial<T>, key?: string | number): Promise<T>;
+    /**
+     * Inserts or updates an existing record in the object store.
+     *
+     * @param value The complete object to upsert.
+     * @param key An optional explicit primary key.
+     * @returns A promise resolving to the upserted record.
+     */
+    put(value: T, key?: string | number): Promise<T>;
+    /**
+     * Removes a record from the object store by its primary key.
+     *
+     * @param key The primary key of the record to delete.
+     * @returns A promise resolving when the deletion is complete.
+     */
+    delete(key: string | number): Promise<void>;
+    /**
+     * Discards all records present in the object store.
+     *
+     * @returns A promise resolving when the store has been completely cleared.
+     */
+    clear(): Promise<void>;
+}

package/cjs/DbRepository.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbRepository = void 0;
+/**
+ * A typed repository wrapper for a single `DbSync` object store.
+ * Provides a localized CRUD interface to minimize boilerplate and
+ * enforce consistent data types for a specific table.
+ */
+class DbRepository {
+    db;
+    storeName;
+    /**
+     * Initializes a new repository tied to a specific object store.
+     *
+     * @param db The centralized `DbSync` instance.
+     * @param storeName The name of the object store this repository will manage.
+     */
+    constructor(db, storeName) {
+        this.db = db;
+        this.storeName = storeName;
+    }
+    /**
+     * Retrieves a single record by its primary key.
+     *
+     * @param id The primary key of the record to retrieve.
+     * @returns A promise resolving to the typed record, or `undefined` if not found.
+     */
+    async findById(id) {
+        return this.db.get(this.storeName, id);
+    }
+    /**
+     * Retrieves all records currently held in the object store.
+     *
+     * @returns A promise resolving to an array of all typed records.
+     */
+    async findAll() {
+        return this.db.findAll(this.storeName);
+    }
+    /**
+     * Inserts a new record into the object store.
+     *
+     * @param value The object payload to insert.
+     * @param key An optional explicit primary key.
+     * @returns A promise resolving to the newly inserted record.
+     */
+    async add(value, key) {
+        return this.db.add(this.storeName, value, key);
+    }
+    /**
+     * Inserts or updates an existing record in the object store.
+     *
+     * @param value The complete object to upsert.
+     * @param key An optional explicit primary key.
+     * @returns A promise resolving to the upserted record.
+     */
+    async put(value, key) {
+        return this.db.put(this.storeName, value, key);
+    }
+    /**
+     * Removes a record from the object store by its primary key.
+     *
+     * @param key The primary key of the record to delete.
+     * @returns A promise resolving when the deletion is complete.
+     */
+    async delete(key) {
+        return this.db.delete(this.storeName, key);
+    }
+    /**
+     * Discards all records present in the object store.
+     *
+     * @returns A promise resolving when the store has been completely cleared.
+     */
+    async clear() {
+        return this.db.clear(this.storeName);
+    }
+}
+exports.DbRepository = DbRepository;
+//# sourceMappingURL=DbRepository.js.map

package/cjs/DbRepository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DbRepository.js","sourceRoot":"","sources":["../src/DbRepository.ts"],"names":[],"mappings":";;;AAEA;;;;GAIG;AACH,MAAa,YAAY;IAQb;IACM;IARjB;;;;;OAKG;IACH,YACW,EAAU,EACJ,SAAiB;QADvB,OAAE,GAAF,EAAE,CAAQ;QACJ,cAAS,GAAT,SAAS,CAAQ;IAC/B,CAAC;IAEJ;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAmB;QACjC,OAAO,IAAI,CAAC,EAAE,CAAC,GAAG,CAAI,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAA;IAC1C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO;QACZ,OAAO,IAAI,CAAC,EAAE,CAAC,OAAO,CAAI,IAAI,CAAC,SAAS,CAAC,CAAA;IAC1C,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,CAAC,KAAiB,EAAE,GAAqB;QACjD,OAAO,IAAI,CAAC,EAAE,CAAC,GAAG,CAAI,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,CAAC,CAAA;IAClD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,CAAC,KAAQ,EAAE,GAAqB;QACxC,OAAO,IAAI,CAAC,EAAE,CAAC,GAAG,CAAI,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,CAAC,CAAA;IAClD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,GAAoB;QAChC,OAAO,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAA;IAC3C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK;QACV,OAAO,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IACrC,CAAC;CACD;AAvED,oCAuEC"}

package/cjs/DbSync.d.ts

@@ -0,0 +1,51 @@
+import type { BackendAdapter } from "./adapters/types.js";
+import { type SyncState } from "./internal/EventBus.js";
+import { StorageManager } from "./internal/StorageManager.js";
+export interface DbSyncConfig {
+    adapter: BackendAdapter;
+    version?: number;
+    tables: Record<string, {
+        indexes?: string[];
+    }>;
+}
+export type { SyncState };
+export declare class DbSync {
+    syncInterval: number;
+    config: DbSyncConfig;
+    private events;
+    storage: StorageManager;
+    private syncEngine;
+    private authManager;
+    constructor(config: DbSyncConfig);
+    genUuid(): `${string}-${string}-${string}-${string}-${string}`;
+    get initted(): boolean;
+    init(): Promise<void>;
+    getTransaction(): import("./internal/DbTransaction.js").DbTransaction;
+    get<T>(storeName: string, id: string | number): Promise<T | undefined>;
+    findAll<T>(storeName: string): Promise<T[]>;
+    add<T>(storeName: string, value: any, key?: string | number): Promise<T>;
+    put<T>(storeName: string, value: any, key?: string | number): Promise<T>;
+    delete(storeName: string, key: string | number): Promise<void>;
+    clear(storeName: string): Promise<void>;
+    subscribe(callback: (stores: string[]) => void): {
+        close: () => boolean;
+    };
+    onSyncStateChange(callback: (state: SyncState) => void): {
+        close: () => boolean;
+    };
+    get isAuth(): boolean;
+    checkAuth(): Promise<boolean>;
+    login(email: string, code: string): Promise<void>;
+    logout(): Promise<void>;
+    reset(): Promise<void>;
+    get isEnabled(): boolean;
+    get isLive(): boolean;
+    enable(): void;
+    disable(): void;
+    waitForLive(): Promise<void>;
+    triggerSync(): Promise<void>;
+    startSyncInterval(): void;
+    stopSyncInterval(): void;
+    protected onSchemaChangeDetected(): void;
+    dispose(): void;
+}

package/cjs/DbSync.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbSync = void 0;
+const AuthManager_js_1 = require("./internal/AuthManager.js");
+const EventBus_js_1 = require("./internal/EventBus.js");
+const StorageManager_js_1 = require("./internal/StorageManager.js");
+const SyncEngine_js_1 = require("./internal/SyncEngine.js");
+const utils_js_1 = require("./internal/utils.js");
+class DbSync {
+    syncInterval = 5000;
+    config;
+    // Internal managers
+    events;
+    storage; // Public for tests currently (we can wrap it later)
+    syncEngine;
+    authManager;
+    constructor(config) {
+        this.config = config;
+        this.events = new EventBus_js_1.EventBus();
+        const adapter = config.adapter;
+        const onSchemaChange = () => this.onSchemaChangeDetected();
+        this.storage = new StorageManager_js_1.StorageManager(config, this.events, onSchemaChange);
+        this.authManager = new AuthManager_js_1.AuthManager(adapter, this.storage, () => this.disable());
+        this.syncEngine = new SyncEngine_js_1.SyncEngine(config, this.syncInterval, this.events, this.storage, this.authManager, adapter, onSchemaChange);
+    }
+    // Facade to Utils
+    genUuid() {
+        return (0, utils_js_1.genUuid)();
+    }
+    // Facade to StorageManager
+    get initted() {
+        return this.storage.initted;
+    }
+    async init() {
+        return this.storage.init();
+    }
+    getTransaction() {
+        return this.storage.getTransaction();
+    } // Exported temporarily for tests
+    async get(storeName, id) {
+        return this.storage.get(storeName, id);
+    }
+    async findAll(storeName) {
+        return this.storage.findAll(storeName);
+    }
+    async add(storeName, value, key) {
+        await this.storage.executeTransaction([{ type: "add", storeName, value, key }]);
+        return value;
+    }
+    async put(storeName, value, key) {
+        await this.storage.executeTransaction([{ type: "put", storeName, value, key }]);
+        return value;
+    }
+    async delete(storeName, key) {
+        await this.storage.executeTransaction([{ type: "delete", storeName, key }]);
+    }
+    async clear(storeName) {
+        await this.storage.executeTransaction([{ type: "clear", storeName }]);
+    }
+    // Facade to EventBus
+    subscribe(callback) {
+        return this.events.subscribe(callback);
+    }
+    onSyncStateChange(callback) {
+        return this.events.onSyncStateChange(callback);
+    }
+    // Facade to AuthManager
+    get isAuth() {
+        return this.authManager.isAuth;
+    }
+    async checkAuth() {
+        return this.authManager.checkAuth();
+    }
+    async login(email, code) {
+        return this.authManager.login(email, code);
+    }
+    async logout() {
+        return this.authManager.logout();
+    }
+    async reset() {
+        return this.authManager.reset();
+    }
+    // Facade to SyncEngine
+    get isEnabled() {
+        return this.syncEngine.isEnabled;
+    }
+    get isLive() {
+        return this.syncEngine.isLive;
+    }
+    enable() {
+        this.syncEngine.enable();
+    }
+    disable() {
+        this.syncEngine.disable();
+    }
+    async waitForLive() {
+        return this.syncEngine.waitForLive();
+    }
+    async triggerSync() {
+        return this.syncEngine.triggerSync();
+    }
+    // Legacy aliases
+    startSyncInterval() {
+        this.enable();
+    }
+    stopSyncInterval() {
+        this.disable();
+    }
+    onSchemaChangeDetected() {
+        this.storage.dispose();
+        this.disable();
+        if (typeof window !== "undefined") {
+            window.location.reload();
+        }
+    }
+    dispose() {
+        this.disable();
+        this.events.dispose();
+        this.storage.dispose();
+    }
+}
+exports.DbSync = DbSync;
+//# sourceMappingURL=DbSync.js.map

package/cjs/DbSync.js.map

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

package/cjs/DbTransaction.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Represents an atomic sequence of write operations.
+ * Operations are queued in memory and only executed against the target
+ * database when `commit()` is called.
+ */
+export declare class DbTransaction {
+    private executor;
+    /**
+     * Stores the pending CRUD operations.
+     * @internal Evaluated and executed by the executor function upon `commit()`.
+     */
+    private operations;
+    /**
+     * Initializes the transaction with an execution engine.
+     * Should be instantiated via `DbSync.getTransaction()` rather than directly.
+     *
+     * @internal
+     * @param executor Provides the context needed to process the queued operations.
+     */
+    constructor(executor: (ops: any[]) => Promise<void>);
+    /**
+     * Queues an insertion operation.
+     *
+     * @param storeName The name of the target object store.
+     * @param value The object payload to insert.
+     * @param key An optional explicit primary key.
+     */
+    add(storeName: string, value: any, key?: string | number): void;
+    /**
+     * Queues an upsert (insert or update) operation.
+     *
+     * @param storeName The name of the target object store.
+     * @param value The object payload to write.
+     * @param key An optional explicit primary key.
+     */
+    put(storeName: string, value: any, key?: string | number): void;
+    /**
+     * Queues a deletion operation.
+     *
+     * @param storeName The name of the target object store.
+     * @param key The primary key of the record to remove.
+     */
+    delete(storeName: string, key: string | number): void;
+    /**
+     * Queues an operation to remove all records from an object store.
+     *
+     * @param storeName The name of the object store to clear.
+     */
+    clear(storeName: string): void;
+    /**
+     * Executes all queued operations atomically within a single database transaction.
+     *
+     * @returns A promise that resolves when the transaction successfully completes.
+     */
+    commit(): Promise<void>;
+    /**
+     * Discards all pending operations without modifying the database.
+     */
+    cancel(): void;
+}

package/cjs/DbTransaction.js

@@ -0,0 +1,82 @@
+"use strict";
+// DbTransaction does not depend on DbSync now
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbTransaction = void 0;
+/**
+ * Represents an atomic sequence of write operations.
+ * Operations are queued in memory and only executed against the target
+ * database when `commit()` is called.
+ */
+class DbTransaction {
+    executor;
+    /**
+     * Stores the pending CRUD operations.
+     * @internal Evaluated and executed by the executor function upon `commit()`.
+     */
+    operations = [];
+    /**
+     * Initializes the transaction with an execution engine.
+     * Should be instantiated via `DbSync.getTransaction()` rather than directly.
+     *
+     * @internal
+     * @param executor Provides the context needed to process the queued operations.
+     */
+    constructor(executor) {
+        this.executor = executor;
+    }
+    /**
+     * Queues an insertion operation.
+     *
+     * @param storeName The name of the target object store.
+     * @param value The object payload to insert.
+     * @param key An optional explicit primary key.
+     */
+    add(storeName, value, key) {
+        this.operations.push({ type: "add", storeName, value, key });
+    }
+    /**
+     * Queues an upsert (insert or update) operation.
+     *
+     * @param storeName The name of the target object store.
+     * @param value The object payload to write.
+     * @param key An optional explicit primary key.
+     */
+    put(storeName, value, key) {
+        this.operations.push({ type: "put", storeName, value, key });
+    }
+    /**
+     * Queues a deletion operation.
+     *
+     * @param storeName The name of the target object store.
+     * @param key The primary key of the record to remove.
+     */
+    delete(storeName, key) {
+        this.operations.push({ type: "delete", storeName, key });
+    }
+    /**
+     * Queues an operation to remove all records from an object store.
+     *
+     * @param storeName The name of the object store to clear.
+     */
+    clear(storeName) {
+        this.operations.push({ type: "clear", storeName });
+    }
+    /**
+     * Executes all queued operations atomically within a single database transaction.
+     *
+     * @returns A promise that resolves when the transaction successfully completes.
+     */
+    async commit() {
+        if (this.operations.length === 0)
+            return;
+        return this.executor(this.operations);
+    }
+    /**
+     * Discards all pending operations without modifying the database.
+     */
+    cancel() {
+        this.operations = [];
+    }
+}
+exports.DbTransaction = DbTransaction;
+//# sourceMappingURL=DbTransaction.js.map

package/cjs/DbTransaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DbTransaction.js","sourceRoot":"","sources":["../src/DbTransaction.ts"],"names":[],"mappings":";AAAA,8CAA8C;;;AAE9C;;;;GAIG;AACH,MAAa,aAAa;IAmBL;IAlBpB;;;OAGG;IACK,UAAU,GAKZ,EAAE,CAAA;IAER;;;;;;OAMG;IACH,YAAoB,QAAuC;QAAvC,aAAQ,GAAR,QAAQ,CAA+B;IAAG,CAAC;IAE/D;;;;;;OAMG;IACH,GAAG,CAAC,SAAiB,EAAE,KAAU,EAAE,GAAqB;QACvD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAA;IAC7D,CAAC;IAED;;;;;;OAMG;IACH,GAAG,CAAC,SAAiB,EAAE,KAAU,EAAE,GAAqB;QACvD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAA;IAC7D,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,SAAiB,EAAE,GAAoB;QAC7C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAA;IACzD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,SAAiB;QACtB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;IACnD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM;QACX,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,OAAM;QACxC,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IACtC,CAAC;IAED;;OAEG;IACH,MAAM;QACL,IAAI,CAAC,UAAU,GAAG,EAAE,CAAA;IACrB,CAAC;CACD;AA9ED,sCA8EC"}