tiny-idb-store 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# tiny-idb-store
+
+IndexedDB object-store wrapper with promise-based CRUD, bulk, cursor, range, and update helpers.
+
+## Install
+
+```sh
+npm install tiny-idb-store
+```
+
+## Scripts
+
+- npm run test - run the Vitest suite with fake IndexedDB.
+- npm run build - emit ESM JavaScript and TypeScript declarations to dist.
+- npm run check - run tests and build.
+
+## Usage
+
+```ts
+import { BaseStore } from 'tiny-idb-store'
+
+interface Note {
+  id?: number
+  title: string
+}
+
+class NotesStore extends BaseStore {
+  constructor(db: IDBDatabase) {
+    super(db, 'notes')
+  }
+}
+
+class StorageService {
+  private static instance: StorageService | null = null
+
+  private db: IDBDatabase | null = null
+  private notesStore: NotesStore | null = null
+  private readonly name = 'notes-db'
+  private readonly version = 1
+
+  private constructor() {}
+
+  get notes(): NotesStore {
+    if (!this.notesStore) {
+      throw new Error('StorageService is not initialized.')
+    }
+
+    return this.notesStore
+  }
+
+  static async create(): Promise<StorageService> {
+    if (StorageService.instance) {
+      return StorageService.instance
+    }
+
+    const instance = new StorageService()
+    await instance.initialize()
+    StorageService.instance = instance
+
+    return instance
+  }
+
+  private async initialize(): Promise<void> {
+    this.db = await this.openConnection()
+    this.notesStore = new NotesStore(this.db)
+  }
+
+  private openConnection(): Promise<IDBDatabase> {
+    return new Promise<IDBDatabase>((resolve, reject) => {
+      const connection = indexedDB.open(this.name, this.version)
+
+      connection.onupgradeneeded = (event: IDBVersionChangeEvent) => {
+        const request = event.target as IDBOpenDBRequest
+        const db = request.result
+        const transaction = request.transaction
+
+        if (!transaction) {
+          reject(new Error('Missing upgrade transaction.'))
+          return
+        }
+
+        switch (event.oldVersion) {
+          case 0:
+            db.createObjectStore('notes', { keyPath: 'id', autoIncrement: true })
+            break
+          default:
+            break
+        }
+      }
+
+      connection.onsuccess = function () {
+        const db = connection.result
+        resolve(db)
+
+        db.onclose = function () {
+          alert('Database connection closed. Please reload the page.')
+        }
+        db.onversionchange = function () {
+          db.close()
+          alert('Database is outdated. Please reload the page.')
+        }
+      }
+
+      connection.onerror = function () {
+        reject(connection.error)
+      }
+      connection.onblocked = function () {
+        alert(
+          "Database is outdated. The newer version can't be loaded until you close other tabs. Please reload the page.",
+        )
+      }
+    })
+  }
+}
+
+const storage = await StorageService.create()
+const noteId = await storage.notes.add<Note>({ title: 'My first note' })
+const note = await storage.notes.get<Note>(noteId)
+console.log(note)
+```

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+type TransactionOperation<T> = (store: IDBObjectStore) => Promise<T>;
+export declare class BaseStore {
+    protected readonly db: IDBDatabase;
+    protected readonly storeName: string;
+    constructor(db: IDBDatabase, storeName: string);
+    protected createReadStore(): IDBObjectStore;
+    protected cursorValues<T>(): AsyncGenerator<T>;
+    protected createWriteTransaction(): IDBTransaction;
+    protected request<T>(request: IDBRequest<T>): Promise<T>;
+    protected write<T>(operation: TransactionOperation<T>): Promise<T>;
+    add<T>(record: T): Promise<IDBValidKey>;
+    bulkAdd<T>(records: T[]): Promise<IDBValidKey[]>;
+    put<T>(record: T): Promise<IDBValidKey>;
+    bulkPut<T>(records: T[]): Promise<IDBValidKey[]>;
+    get<T>(key: IDBValidKey): Promise<T | undefined>;
+    count(): Promise<number>;
+    getAll<T>(): Promise<T[]>;
+    getAllFromTo<T>(fromKey: IDBValidKey, toKey: IDBValidKey): Promise<T[]>;
+    getAllFrom<T>(fromKey: IDBValidKey): Promise<T[]>;
+    getAllKeysFrom(fromKey: IDBValidKey): Promise<IDBValidKey[]>;
+    getAllTo<T>(toKey: IDBValidKey): Promise<T[]>;
+    getAllKeysTo(toKey: IDBValidKey): Promise<IDBValidKey[]>;
+    mapAll<T, R>(mappers: Array<(value: T) => R>): AsyncGenerator<R>;
+    findAllBy<T>(predicate: (value: T) => boolean): AsyncGenerator<T>;
+    takeByLimit<T>(limit: number): AsyncGenerator<T>;
+    reduce<T, R>(predicate: (value: T) => boolean, mappers: Array<(value: T) => R>): AsyncGenerator<R>;
+    sliceBy<T>(start: number, stop: number, step?: number): AsyncGenerator<T>;
+    clear(): Promise<void>;
+    delete(key: IDBValidKey): Promise<void>;
+    bulkDelete(keys: IDBValidKey[]): Promise<unknown[]>;
+    update<T extends Record<string, unknown>>(key: IDBValidKey, patch: Partial<T>): Promise<boolean>;
+    updateByPath(key: IDBValidKey, path: string, value: unknown): Promise<boolean>;
+    updateAll<T extends Record<string, unknown>>(patch: Partial<T>): Promise<number>;
+    updateAllByPath(path: string, value: unknown): Promise<number>;
+    private updateAllRecords;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,190 @@
+import { setByPath } from "./utils";
+export class BaseStore {
+    constructor(db, storeName) {
+        this.db = db;
+        this.storeName = storeName;
+    }
+    createReadStore() {
+        return this.db
+            .transaction(this.storeName, "readonly")
+            .objectStore(this.storeName);
+    }
+    async *cursorValues() {
+        const request = this.createReadStore().openCursor();
+        while (true) {
+            const cursor = await this.request(request);
+            if (!cursor) {
+                return;
+            }
+            yield cursor.value;
+            cursor.continue();
+        }
+    }
+    createWriteTransaction() {
+        return this.db.transaction(this.storeName, "readwrite");
+    }
+    request(request) {
+        return new Promise((resolve, reject) => {
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async write(operation) {
+        const transaction = this.createWriteTransaction();
+        const store = transaction.objectStore(this.storeName);
+        try {
+            const result = await operation(store);
+            await new Promise((resolve, reject) => {
+                transaction.oncomplete = () => resolve();
+                transaction.onerror = () => reject(transaction.error);
+                transaction.onabort = () => reject(transaction.error);
+            });
+            return result;
+        }
+        catch (error) {
+            if (transaction.error === null) {
+                transaction.abort();
+            }
+            throw error;
+        }
+    }
+    async add(record) {
+        return this.write((store) => this.request(store.add(record)));
+    }
+    async bulkAdd(records) {
+        return this.write((store) => Promise.all(records.map((record) => this.request(store.add(record)))));
+    }
+    async put(record) {
+        return this.write((store) => this.request(store.put(record)));
+    }
+    async bulkPut(records) {
+        return this.write((store) => Promise.all(records.map((record) => this.request(store.put(record)))));
+    }
+    async get(key) {
+        return this.request(this.createReadStore().get(key));
+    }
+    async count() {
+        return this.request(this.createReadStore().count());
+    }
+    async getAll() {
+        return this.request(this.createReadStore().getAll());
+    }
+    async getAllFromTo(fromKey, toKey) {
+        return this.request(this.createReadStore().getAll(IDBKeyRange.bound(fromKey, toKey)));
+    }
+    async getAllFrom(fromKey) {
+        return this.request(this.createReadStore().getAll(IDBKeyRange.lowerBound(fromKey, true)));
+    }
+    async getAllKeysFrom(fromKey) {
+        return this.request(this.createReadStore().getAllKeys(IDBKeyRange.lowerBound(fromKey, true)));
+    }
+    async getAllTo(toKey) {
+        return this.request(this.createReadStore().getAll(IDBKeyRange.upperBound(toKey, true)));
+    }
+    async getAllKeysTo(toKey) {
+        return this.request(this.createReadStore().getAllKeys(IDBKeyRange.upperBound(toKey, true)));
+    }
+    async *mapAll(mappers) {
+        for await (const value of this.cursorValues()) {
+            for (const mapper of mappers) {
+                yield mapper(value);
+            }
+        }
+    }
+    async *findAllBy(predicate) {
+        for await (const value of this.cursorValues()) {
+            if (predicate(value)) {
+                yield value;
+            }
+        }
+    }
+    async *takeByLimit(limit) {
+        let count = 0;
+        for await (const value of this.cursorValues()) {
+            if (count >= limit) {
+                return;
+            }
+            yield value;
+            count += 1;
+        }
+    }
+    async *reduce(predicate, mappers) {
+        for await (const value of this.cursorValues()) {
+            if (predicate(value)) {
+                for (const mapper of mappers) {
+                    yield mapper(value);
+                }
+            }
+        }
+    }
+    async *sliceBy(start, stop, step = 1) {
+        let index = 0;
+        for await (const value of this.cursorValues()) {
+            if (index >= stop) {
+                return;
+            }
+            if (index >= start && (index - start) % step === 0) {
+                yield value;
+            }
+            index += 1;
+        }
+    }
+    async clear() {
+        await this.write((store) => this.request(store.clear()));
+    }
+    async delete(key) {
+        await this.write((store) => this.request(store.delete(key)));
+    }
+    async bulkDelete(keys) {
+        return this.write((store) => Promise.all(keys.map((key) => this.request(store.delete(key)))));
+    }
+    async update(key, patch) {
+        const current = await this.get(key);
+        if (!current) {
+            return false;
+        }
+        await this.put({ ...current, ...patch });
+        return true;
+    }
+    async updateByPath(key, path, value) {
+        const current = await this.get(key);
+        if (!current) {
+            return false;
+        }
+        setByPath(current, path, value);
+        await this.put(current);
+        return true;
+    }
+    async updateAll(patch) {
+        return this.updateAllRecords((record) => {
+            Object.assign(record, patch);
+        });
+    }
+    async updateAllByPath(path, value) {
+        return this.updateAllRecords((record) => {
+            setByPath(record, path, value);
+        });
+    }
+    async updateAllRecords(updateRecord) {
+        return this.write((store) => new Promise((resolve, reject) => {
+            const request = store.openCursor();
+            let updatedCount = 0;
+            request.onsuccess = () => {
+                const cursor = request.result;
+                if (!cursor) {
+                    resolve(updatedCount);
+                    return;
+                }
+                const record = cursor.value;
+                updateRecord(record);
+                const updateRequest = cursor.update(record);
+                updateRequest.onsuccess = () => {
+                    updatedCount += 1;
+                    cursor.continue();
+                };
+                updateRequest.onerror = () => reject(updateRequest.error);
+            };
+            request.onerror = () => reject(request.error);
+        }));
+    }
+}

package/dist/utils.d.ts

@@ -0,0 +1 @@
+export declare const setByPath: (record: Record<string, unknown>, path: string, value: unknown) => void;

package/dist/utils.js

@@ -0,0 +1,14 @@
+export const setByPath = (record, path, value) => {
+    let current = record;
+    const parts = path.split(".");
+    for (const [index, part] of parts.entries()) {
+        if (index === parts.length - 1) {
+            current[part] = value;
+            return;
+        }
+        if (typeof current[part] !== "object" || current[part] === null) {
+            current[part] = {};
+        }
+        current = current[part];
+    }
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "tiny-idb-store",
+	"version": "0.1.0",
+	"private": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"test": "vitest run",
+		"check": "vitest run && tsc -p tsconfig.json"
+	},
+	"devDependencies": {
+		"fake-indexeddb": "^6.0.0",
+		"typescript": "~5.7.2",
+		"vitest": "^3.2.0"
+	},
+	"description": "Typed IndexedDB object-store wrapper with promise-based CRUD, bulk, cursor, range, and update helpers.",
+	"license": "MIT",
+	"files": [
+		"dist"
+	]
+}