idb-refined 0.0.1

package/README.md

@@ -0,0 +1,111 @@
+# idb-refined
+
+Thin TypeScript IndexedDB helper on top of [idb](https://www.npmjs.com/package/idb): init DB with auto-version, clean by date or size, add with eviction, and delete helpers.
+
+## Install
+
+```bash
+pnpm add idb-refined
+# or
+npm install idb-refined
+```
+
+## API
+
+| Function | Purpose |
+|----------|---------|
+| **initDb(name, options?)** | Open or create a DB. Version is auto-detected when you pass a declarative `schema`; optional manual `version` + `upgrade`. Returns idb’s `IDBPDatabase`. |
+| **cleanOldEntries(db, storeName, options)** | Delete entries where `dateKey` < `before` (timestamp ms). Options: `{ dateKey, before }`. Requires an index on `dateKey`. |
+| **cleanWhenTooLarge(db, storeName, options)** | Evict oldest entries (by `dateKey`) until count ≤ `maxCount`. Options: `{ dateKey, maxCount }`. Returns count deleted. |
+| **putWithEviction(db, storeName, value, options)** | Put value, then if store count > `maxCount` evict oldest by `dateKey`. Options: `{ key?, dateKey, maxCount }`. |
+| **deleteByKey(db, storeName, key)** | Delete a single entry by key. |
+| **clearStore(db, storeName)** | Delete all entries in a store. |
+| **deleteDB(name)** | Re-export of idb’s `deleteDB`. |
+
+## Use cases
+
+- **Cache with TTL:** initDb, put items with `expiresAt`, call `cleanOldEntries` on startup or interval.
+- **Cache with max size:** Use `putWithEviction` or call `cleanWhenTooLarge` after adding.
+- **Cache with TTL + max size:** `putWithEviction` + periodic `cleanOldEntries` for expired.
+- **Log / event buffer:** `putWithEviction` with `dateKey: 'createdAt'` and `maxCount`.
+- **Simple key-value:** initDb, `db.get` / `db.put` / `deleteByKey`; optional cleanup when too large.
+
+## Examples
+
+### Cache with TTL and max size
+
+```ts
+import { initDb, putWithEviction, cleanOldEntries, deleteByKey } from "idb-refined";
+
+const db = await initDb("my-cache", {
+  schema: {
+    stores: {
+      cache: { keyPath: "id", indexes: ["expiresAt"] },
+    },
+  },
+});
+
+// Add item; if store has more than 1000 entries, evict oldest
+await putWithEviction(
+  db,
+  "cache",
+  { id: "k1", data: "v1", expiresAt: Date.now() + 3600 },
+  { dateKey: "expiresAt", maxCount: 1000 }
+);
+
+// Periodic: remove expired
+await cleanOldEntries(db, "cache", {
+  dateKey: "expiresAt",
+  before: Date.now(),
+});
+
+// Delete one
+await deleteByKey(db, "cache", "k1");
+```
+
+### Log buffer (cap size)
+
+```ts
+await putWithEviction(
+  db,
+  "logs",
+  { id: generateId(), message, createdAt: Date.now() },
+  { dateKey: "createdAt", maxCount: 5000 }
+);
+```
+
+### Manual cleanup when too large
+
+```ts
+const deleted = await cleanWhenTooLarge(db, "cache", {
+  dateKey: "expiresAt",
+  maxCount: 500,
+});
+console.log(`Evicted ${deleted} entries`);
+```
+
+## Requirements
+
+- Stores that use `cleanOldEntries`, `cleanWhenTooLarge`, or `putWithEviction` must have an **index** on the date field (e.g. `expiresAt`, `createdAt`). Define it in your schema:
+
+  ```ts
+  schema: {
+    stores: {
+      cache: { keyPath: "id", indexes: ["expiresAt"] },
+    },
+  }
+  ```
+
+- Eviction is **count-based** only (no byte-size or quota check).
+
+## Releasing
+
+1. Bump version: `pnpm version patch` (or `minor` / `major`).
+2. Commit and push: `git push && git push --tags`.
+3. Pushing a tag matching `v*` (e.g. `v0.0.2`) triggers the [Publish to npm](.github/workflows/publish.yml) workflow, which runs build and `pnpm publish`.
+
+**Required:** Add an `NPM_TOKEN` secret in the repo (Settings → Secrets and variables → Actions). Use an npm [access token](https://www.npmjs.com/settings/~/tokens) or granular token with publish permission.
+
+## License
+
+MIT

package/dist/cleanOldEntries.d.ts

@@ -0,0 +1,10 @@
+import type { IDBPDatabase } from "idb";
+export interface CleanOldEntriesOptions {
+    dateKey: string;
+    before: number;
+}
+/**
+ * Delete entries in a store where the date/timestamp field is before the threshold.
+ * Requires an index on `dateKey`. Uses timestamp in ms (e.g. Date.now()).
+ */
+export declare function cleanOldEntries(db: IDBPDatabase<unknown>, storeName: string, options: CleanOldEntriesOptions): Promise<void>;

package/dist/cleanOldEntries.js

@@ -0,0 +1,16 @@
+/**
+ * Delete entries in a store where the date/timestamp field is before the threshold.
+ * Requires an index on `dateKey`. Uses timestamp in ms (e.g. Date.now()).
+ */
+export async function cleanOldEntries(db, storeName, options) {
+    const { dateKey, before } = options;
+    const tx = db.transaction(storeName, "readwrite");
+    const store = tx.objectStore(storeName);
+    const index = store.index(dateKey);
+    const range = IDBKeyRange.upperBound(before, true);
+    const keysToDelete = await index.getAllKeys(range);
+    for (const key of keysToDelete) {
+        store.delete(key);
+    }
+    await tx.done;
+}

package/dist/cleanWhenTooLarge.d.ts

@@ -0,0 +1,10 @@
+import type { IDBPDatabase } from "idb";
+export interface CleanWhenTooLargeOptions {
+    dateKey: string;
+    maxCount: number;
+}
+/**
+ * Evict oldest entries (by dateKey) until store count <= maxCount.
+ * Requires an index on dateKey. Returns the number of entries deleted.
+ */
+export declare function cleanWhenTooLarge(db: IDBPDatabase<unknown>, storeName: string, options: CleanWhenTooLargeOptions): Promise<number>;

package/dist/cleanWhenTooLarge.js

@@ -0,0 +1,25 @@
+/**
+ * Evict oldest entries (by dateKey) until store count <= maxCount.
+ * Requires an index on dateKey. Returns the number of entries deleted.
+ */
+export async function cleanWhenTooLarge(db, storeName, options) {
+    const { dateKey, maxCount } = options;
+    const count = await db.count(storeName);
+    if (count <= maxCount)
+        return 0;
+    const toDelete = count - maxCount;
+    const tx = db.transaction(storeName, "readwrite");
+    const store = tx.objectStore(storeName);
+    const index = store.index(dateKey);
+    const keysToDelete = [];
+    let cursor = await index.openKeyCursor(null, "next");
+    while (cursor != null && keysToDelete.length < toDelete) {
+        keysToDelete.push(cursor.primaryKey);
+        cursor = await cursor.continue();
+    }
+    for (const key of keysToDelete) {
+        store.delete(key);
+    }
+    await tx.done;
+    return keysToDelete.length;
+}

package/dist/delete.d.ts

@@ -0,0 +1,9 @@
+import type { IDBPDatabase } from "idb";
+/**
+ * Delete a single entry by key.
+ */
+export declare function deleteByKey(db: IDBPDatabase<unknown>, storeName: string, key: IDBValidKey): Promise<void>;
+/**
+ * Delete all entries in a store.
+ */
+export declare function clearStore(db: IDBPDatabase<unknown>, storeName: string): Promise<void>;

package/dist/delete.js

@@ -0,0 +1,12 @@
+/**
+ * Delete a single entry by key.
+ */
+export async function deleteByKey(db, storeName, key) {
+    await db.delete(storeName, key);
+}
+/**
+ * Delete all entries in a store.
+ */
+export async function clearStore(db, storeName) {
+    await db.clear(storeName);
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { initDb } from "./initDb.js";
+export type { InitDbOptions } from "./initDb.js";
+export { cleanOldEntries } from "./cleanOldEntries.js";
+export type { CleanOldEntriesOptions } from "./cleanOldEntries.js";
+export { cleanWhenTooLarge } from "./cleanWhenTooLarge.js";
+export type { CleanWhenTooLargeOptions } from "./cleanWhenTooLarge.js";
+export { putWithEviction } from "./putWithEviction.js";
+export type { PutWithEvictionOptions } from "./putWithEviction.js";
+export { deleteByKey, clearStore } from "./delete.js";
+export { deleteDB } from "idb";
+export type { IDBPDatabase, DBSchema } from "idb";
+export type { SchemaDef, StoreDef } from "./schema.js";
+export { fingerprint, applySchema } from "./schema.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { initDb } from "./initDb.js";
+export { cleanOldEntries } from "./cleanOldEntries.js";
+export { cleanWhenTooLarge } from "./cleanWhenTooLarge.js";
+export { putWithEviction } from "./putWithEviction.js";
+export { deleteByKey, clearStore } from "./delete.js";
+export { deleteDB } from "idb";
+export { fingerprint, applySchema } from "./schema.js";

package/dist/initDb.d.ts

@@ -0,0 +1,12 @@
+import type { IDBPDatabase } from "idb";
+import type { SchemaDef } from "./schema.js";
+export interface InitDbOptions {
+    schema?: SchemaDef;
+    version?: number;
+    upgrade?: (db: IDBPDatabase<unknown>) => void;
+}
+/**
+ * Open or create a database. When `schema` is provided, version is auto-detected
+ * from a fingerprint; when `version` and/or `upgrade` are provided, use them directly.
+ */
+export declare function initDb(name: string, options?: InitDbOptions): Promise<IDBPDatabase<unknown>>;

package/dist/initDb.js

@@ -0,0 +1,60 @@
+import { openDB } from "idb";
+import { fingerprint, applySchema } from "./schema.js";
+const META_DB_NAME = "idb-refined-meta";
+const META_STORE = "meta";
+/**
+ * Open or create a database. When `schema` is provided, version is auto-detected
+ * from a fingerprint; when `version` and/or `upgrade` are provided, use them directly.
+ */
+export async function initDb(name, options) {
+    if (options?.schema != null) {
+        return initDbWithSchema(name, options.schema, options.upgrade);
+    }
+    const version = options?.version ?? 1;
+    return openDB(name, version, {
+        upgrade: options?.upgrade,
+    });
+}
+async function initDbWithSchema(name, schema, customUpgrade) {
+    const fp = fingerprint(schema);
+    const metaDb = await openDB(META_DB_NAME, 1, {
+        upgrade(db) {
+            if (!db.objectStoreNames.contains(META_STORE)) {
+                db.createObjectStore(META_STORE, { keyPath: "dbName" });
+            }
+        },
+    });
+    const stored = (await metaDb.get(META_STORE, name));
+    metaDb.close();
+    let currentVersion = 0;
+    try {
+        const probe = await openDB(name);
+        currentVersion = probe.version;
+        probe.close();
+    }
+    catch {
+        // DB does not exist yet
+    }
+    const needUpgrade = stored == null || stored.schemaFingerprint !== fp;
+    const newVersion = needUpgrade
+        ? Math.max((stored?.version ?? 0) + 1, currentVersion + 1)
+        : stored.version;
+    const db = (await openDB(name, newVersion, {
+        upgrade(db, _oldVersion, _newVersion, transaction) {
+            if (needUpgrade) {
+                applySchema(db, schema, transaction);
+            }
+            customUpgrade?.(db);
+        },
+    }));
+    if (needUpgrade) {
+        const metaDb2 = await openDB(META_DB_NAME, 1);
+        await metaDb2.put(META_STORE, {
+            dbName: name,
+            schemaFingerprint: fp,
+            version: newVersion,
+        });
+        metaDb2.close();
+    }
+    return db;
+}

package/dist/putWithEviction.d.ts

@@ -0,0 +1,11 @@
+import type { IDBPDatabase } from "idb";
+export interface PutWithEvictionOptions {
+    key?: IDBValidKey;
+    dateKey: string;
+    maxCount: number;
+}
+/**
+ * Put a value in the store, then if count > maxCount evict oldest entries (by dateKey).
+ * Value must include the keyPath field, or pass options.key.
+ */
+export declare function putWithEviction<T = unknown>(db: IDBPDatabase<unknown>, storeName: string, value: T, options: PutWithEvictionOptions): Promise<void>;

package/dist/putWithEviction.js

@@ -0,0 +1,13 @@
+import { cleanWhenTooLarge } from "./cleanWhenTooLarge.js";
+/**
+ * Put a value in the store, then if count > maxCount evict oldest entries (by dateKey).
+ * Value must include the keyPath field, or pass options.key.
+ */
+export async function putWithEviction(db, storeName, value, options) {
+    const { key, dateKey, maxCount } = options;
+    await db.put(storeName, value, key);
+    const count = await db.count(storeName);
+    if (count > maxCount) {
+        await cleanWhenTooLarge(db, storeName, { dateKey, maxCount });
+    }
+}

package/dist/schema.d.ts

@@ -0,0 +1,27 @@
+import type { IDBPDatabase, IDBPTransaction } from "idb";
+/**
+ * Definition for a single object store.
+ * - keyPath: optional key path (e.g. 'id')
+ * - autoIncrement: optional
+ * - indexes: array of index names (keyPath = name) or record indexName -> keyPath | keyPath[]
+ */
+export interface StoreDef {
+    keyPath?: string;
+    autoIncrement?: boolean;
+    indexes?: string[] | Record<string, string | string[]>;
+}
+/**
+ * Declarative schema: store names -> store definitions.
+ */
+export interface SchemaDef {
+    stores: Record<string, StoreDef>;
+}
+/**
+ * Stable fingerprint for schema (sorted keys) so any schema change produces a different string.
+ */
+export declare function fingerprint(schema: SchemaDef): string;
+/**
+ * Create object stores and indexes from schema. Call this from within an upgrade callback.
+ * Pass the upgrade transaction so existing stores can get new indexes. Skips stores/indexes that already exist.
+ */
+export declare function applySchema(db: IDBPDatabase<unknown>, schema: SchemaDef, transaction: IDBPTransaction<unknown, string[], "versionchange">): void;

package/dist/schema.js

@@ -0,0 +1,49 @@
+/**
+ * Stable fingerprint for schema (sorted keys) so any schema change produces a different string.
+ */
+export function fingerprint(schema) {
+    const normalized = {};
+    for (const name of Object.keys(schema.stores).sort()) {
+        const def = schema.stores[name];
+        const indexes = def.indexes == null
+            ? undefined
+            : Array.isArray(def.indexes)
+                ? [...def.indexes].sort()
+                : Object.fromEntries(Object.keys(def.indexes)
+                    .sort()
+                    .map((k) => [
+                    k,
+                    def.indexes[k],
+                ]));
+        normalized[name] = {
+            keyPath: def.keyPath,
+            autoIncrement: def.autoIncrement,
+            indexes,
+        };
+    }
+    return JSON.stringify(normalized);
+}
+/**
+ * Create object stores and indexes from schema. Call this from within an upgrade callback.
+ * Pass the upgrade transaction so existing stores can get new indexes. Skips stores/indexes that already exist.
+ */
+export function applySchema(db, schema, transaction) {
+    for (const [storeName, def] of Object.entries(schema.stores)) {
+        const store = !db.objectStoreNames.contains(storeName)
+            ? db.createObjectStore(storeName, {
+                keyPath: def.keyPath,
+                autoIncrement: def.autoIncrement ?? false,
+            })
+            : transaction.objectStore(storeName);
+        if (def.indexes) {
+            const indexEntries = Array.isArray(def.indexes)
+                ? def.indexes.map((name) => [name, name])
+                : Object.entries(def.indexes);
+            for (const [indexName, keyPath] of indexEntries) {
+                if (!store.indexNames.contains(indexName)) {
+                    store.createIndex(indexName, keyPath);
+                }
+            }
+        }
+    }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "idb-refined",
+  "version": "0.0.1",
+  "description": "Thin TypeScript IndexedDB helper: initDb (auto-version), clean by date/size, add with eviction, delete helpers",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "lint-staged": {
+    "src/**/*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  },
+  "dependencies": {
+    "idb": "^8.0.3"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.8.1",
+    "@commitlint/config-conventional": "^19.8.1",
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^9.1.2",
+    "fake-indexeddb": "^6.2.5",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.5.2",
+    "prettier": "^3.8.1",
+    "typescript": "^5.6.3",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^2.1.9"
+  },
+  "keywords": [
+    "indexeddb",
+    "idb",
+    "cache",
+    "browser",
+    "storage"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}