idb-refined 0.0.3 → 0.0.5

package/README.md

@@ -1,6 +1,6 @@
 # idb-refined
 
-Minimal IndexedDB client on top of [idb](https://www.npmjs.com/package/idb). Exposes **add**, **update**, **delete**, and **removeDb**. Init, schema, cleanup and eviction run automatically.
+Minimal IndexedDB client on top of [idb](https://www.npmjs.com/package/idb). Exposes **set**, **get**, **update**, **delete**, and **deleteDb**. Init, schema, cleanup and eviction run automatically. See [CHANGELOG.md](CHANGELOG.md) for version history.
 
 ## Install
 
@@ -10,27 +10,37 @@ pnpm add idb-refined
 npm install idb-refined
 ```
 
+## When to use
+
+Good for: key-value cache with TTL and eviction, offline storage, simple app storage by id. Not for: complex multi-index queries or raw IDB transactions—use [idb](https://www.npmjs.com/package/idb) or native IndexedDB instead.
+
 ## API
 
 | Export | Purpose |
 |--------|---------|
-| **createClient(options)** | Returns `{ set, get, update, delete, deleteDb }`. Options: `dbName` (required), `storeName` (optional). |
-| **set(value)** | Store a value. Value must have an `id` property. Expiry and eviction run automatically. |
+| **createIdb(options, workerUrl?)** | Returns a Promise of `{ set, get, getAll, keys, getMany, update, delete, deleteDb }`. Uses a Web Worker by default (browser); worker URL is auto-generated. Options: `dbName` (required), `storeName` (optional), `ttlMs` (optional, default 3600000), `maxCount` (optional, default 1000). Pass `workerUrl` only when bundling requires it. |
+| **set(value)** | Store a value. Value must have an `id` property. The object is not mutated; expiry and eviction run automatically. |
 | **get(key)** | Get a value by key. Returns `undefined` if not found. |
-| **update(key, value)** | Update an existing entry by key. |
+| **getAll()** | Get all values in the store. |
+| **keys()** | Get all keys in the store. |
+| **getMany(keys)** | Get values for multiple keys; returns array aligned with input (undefined where missing). |
+| **update(key, value)** | Merge partial fields into the existing entry by key (other fields preserved). |
 | **delete(key)** | Delete an entry by key. |
 | **deleteDb()** | Close the DB and delete it from disk. |
 
-For details, see **[Advanced documentation](docs/advanced.md)**. Run the **[example](example/)** in the browser (see `example/README.md`).
+For details, see **[Advanced documentation](docs/advanced.md)**. Run the **[example](example/)** in the browser (see `example/README.md`). The `idb-refined/worker` export is a script entry for the Worker constructor only (no types).
 
 ## Example
 
 ```ts
-import { createClient } from "idb-refined";
+import { createIdb } from "idb-refined";
 
 // Optional: type the stored value for set/get/update
 type User = { id: string; name: string; createdAt?: number; expiresAt?: number };
-const { set, get, update, delete: del, deleteDb } = createClient<User>({ dbName: "my-app" });
+const { set, get, update, delete: del, deleteDb } = await createIdb<User>({
+  dbName: "my-app",
+  ttlMs: 3600_000, // optional: 1 hour default TTL
+});
 
 await set({ id: "1", name: "Alice" });
 const value = await get("1"); // User | undefined
@@ -39,10 +49,33 @@ await del("1");
 await deleteDb();
 ```
 
+## Bundling
+
+With Vite or Webpack the worker URL may not resolve; pass `workerUrl` explicitly:
+
+**Vite:**
+
+```ts
+const client = await createIdb(
+  { dbName: "my-app" },
+  new URL("idb-refined/worker", import.meta.url)
+);
+```
+
+**Webpack 5:** Use a path that resolves to the worker script (e.g. `new URL("./node_modules/idb-refined/dist/worker.js", import.meta.url)` or configure your bundler to expose it). See [Bundling](docs/advanced.md#bundling) in the advanced docs.
+
 ## Requirements
 
 - Values must include an `id` property (used as the store key).
 - The library uses a single store (default name `"store"`) with indexes on `expiresAt` and `createdAt`. Cleanup and eviction run on set.
+- **Environment:** Requires IndexedDB (and Web Workers in the browser for worker mode). Works in modern browsers; tests use fake-indexeddb in Node.
+
+## Under the hood
+
+- **Schema & versioning** — A single store (and indexes on `expiresAt`, `createdAt`) is created or upgraded automatically; version bumps are derived from a schema fingerprint so you don’t manage versions by hand.
+- **Cleanup** — Expired entries (`expiresAt` in the past) are removed before and after each `set`, so TTL “just works” and there’s room to add.
+- **Eviction** — If the store is at or over `maxCount` (default 1000), the oldest entries by `createdAt` are evicted *before* the add, then again after if needed, so the store stays under the cap and adds don’t run out of space.
+- **Web Worker** — `createIdb` runs all of the above (schema, cleanup, eviction, put/get/update/delete) inside a Web Worker by default. The worker URL is auto-generated; the main thread only sends messages and receives results, so heavy I/O and bookkeeping stay off the UI thread.
 
 ## Releasing
 

package/dist/cleanWhenTooLarge.js

@@ -1,4 +1,4 @@
-const DEFAULT_MAX_COUNT = 1000;
+import { DEFAULT_MAX_COUNT } from "./constants.js";
 /**
  * Evict oldest entries (by dateKey) until store count <= maxCount.
  * Requires an index on dateKey. Returns the number of entries deleted.

package/dist/client.d.ts

@@ -1,21 +1,30 @@
-export interface CreateClientOptions {
+export interface IdbRefinedOptions {
     dbName: string;
     storeName?: string;
+    /** Default TTL in ms for values without `expiresAt`. Default: 3600000 (1 hour). */
+    ttlMs?: number;
+    /** Max entries before eviction. Default: 1000. */
+    maxCount?: number;
 }
 /** Stored value must have `id`. `createdAt` and `expiresAt` are set by the client if missing. */
 export type StoredValue = Record<string, unknown> & {
     id: IDBValidKey;
 };
 export interface IdbRefinedClient<T extends StoredValue = StoredValue> {
-    add: (value: T) => Promise<void>;
+    set: (value: T) => Promise<void>;
     get: (key: IDBValidKey) => Promise<T | undefined>;
+    getAll: () => Promise<T[]>;
+    keys: () => Promise<IDBValidKey[]>;
+    getMany: (keys: IDBValidKey[]) => Promise<(T | undefined)[]>;
     update: (key: IDBValidKey, value: Partial<T>) => Promise<void>;
     delete: (key: IDBValidKey) => Promise<void>;
-    removeDb: () => Promise<void>;
+    deleteDb: () => Promise<void>;
 }
+import type { WorkerMessage, WorkerResponse } from "./workerProtocol.js";
+export type { WorkerMessage, WorkerResponse };
 /**
- * Create a client that exposes add, get, update, delete, removeDb.
- * Init, schema, cleanup and eviction run automatically.
+ * Create an idb-refined client. Uses a Web Worker by default (browser); falls back to main thread when Worker is unavailable (e.g. Node/tests).
+ * Worker URL is auto-generated from the same directory as the library; pass `workerUrl` only when bundling requires it (e.g. `new URL('idb-refined/worker', import.meta.url)`).
  * @template T - Stored value shape (must include `id`). Omit for a generic client.
  */
-export declare function createClient<T extends StoredValue = StoredValue>(options: CreateClientOptions): IdbRefinedClient<T>;
+export declare function createIdb<T extends StoredValue = StoredValue>(options: IdbRefinedOptions, workerUrl?: string | URL): Promise<IdbRefinedClient<T>>;

package/dist/client.js

@@ -1,84 +1,110 @@
-import { deleteDB } from "idb";
-import { initDb } from "./initDb.js";
-import { cleanOldEntries } from "./cleanOldEntries.js";
-import { cleanWhenTooLarge } from "./cleanWhenTooLarge.js";
+import { executeDelete as execDelete, executeDeleteDb as execDeleteDb, executeGet as execGet, executeGetAll as execGetAll, executeGetMany as execGetMany, executeKeys as execKeys, executeSet as execSet, executeUpdate as execUpdate, } from "./clientCore.js";
 const DEFAULT_STORE_NAME = "store";
-const DEFAULT_KEY_PATH = "id";
-const DATE_INDEXES = ["expiresAt", "createdAt"];
-const DEFAULT_TTL_MS = 3600 * 1000;
-const DEFAULT_MAX_COUNT = 1000;
-const dbCache = new Map();
-function getDefaultSchema(storeName) {
+function mainThreadClient(dbName, storeName, ttlMs, maxCount) {
     return {
-        stores: {
-            [storeName]: {
-                keyPath: DEFAULT_KEY_PATH,
-                indexes: DATE_INDEXES,
-            },
+        async set(value) {
+            await execSet(dbName, storeName, value, {
+                ttlMs,
+                maxCount,
+            });
+        },
+        async get(key) {
+            return execGet(dbName, storeName, key);
+        },
+        async getAll() {
+            return execGetAll(dbName, storeName);
+        },
+        async keys() {
+            return execKeys(dbName, storeName);
+        },
+        async getMany(keys) {
+            return execGetMany(dbName, storeName, keys);
+        },
+        async update(key, value) {
+            await execUpdate(dbName, storeName, key, value);
+        },
+        async delete(key) {
+            await execDelete(dbName, storeName, key);
+        },
+        async deleteDb() {
+            await execDeleteDb(dbName);
         },
     };
 }
-async function getDb(dbName, storeName) {
-    let db = dbCache.get(dbName);
-    if (db != null)
-        return db;
-    const schema = getDefaultSchema(storeName);
-    db = await initDb(dbName, { schema });
-    dbCache.set(dbName, db);
-    return db;
-}
-function setExpiryFields(value) {
-    const now = Date.now();
-    if (value.createdAt === undefined)
-        value.createdAt = now;
-    if (value.expiresAt === undefined)
-        value.expiresAt = now + DEFAULT_TTL_MS;
-}
 /**
- * Create a client that exposes add, get, update, delete, removeDb.
- * Init, schema, cleanup and eviction run automatically.
+ * Create an idb-refined client. Uses a Web Worker by default (browser); falls back to main thread when Worker is unavailable (e.g. Node/tests).
+ * Worker URL is auto-generated from the same directory as the library; pass `workerUrl` only when bundling requires it (e.g. `new URL('idb-refined/worker', import.meta.url)`).
  * @template T - Stored value shape (must include `id`). Omit for a generic client.
  */
-export function createClient(options) {
-    const { dbName } = options;
+export async function createIdb(options, workerUrl) {
+    const { dbName, ttlMs, maxCount } = options;
     const storeName = options.storeName ?? DEFAULT_STORE_NAME;
+    if (typeof Worker === "undefined") {
+        return mainThreadClient(dbName, storeName, ttlMs, maxCount);
+    }
+    const url = workerUrl ??
+        (typeof import.meta !== "undefined" && import.meta.url
+            ? new URL("./worker.js", import.meta.url).href
+            : undefined);
+    if (url == null) {
+        throw new Error("createIdb: worker URL could not be resolved. Pass workerUrl (e.g. new URL('idb-refined/worker', import.meta.url)) when bundling.");
+    }
+    const worker = new Worker(url, { type: "module" });
+    const pending = new Map();
+    let nextId = 0;
+    const workerUnavailableError = new Error("Worker unavailable; create a new client with createIdb().");
+    let workerDead = false;
+    worker.onmessage = (e) => {
+        const data = e.data;
+        const p = pending.get(data.id);
+        if (p) {
+            pending.delete(data.id);
+            if ("error" in data && data.error)
+                p.reject(new Error(data.error));
+            else
+                p.resolve(("result" in data ? data.result : undefined));
+        }
+    };
+    worker.onerror = (ev) => {
+        workerDead = true;
+        for (const [, p] of pending)
+            p.reject(ev.error ?? new Error("Worker error"));
+        pending.clear();
+    };
+    const send = (type, payload) => new Promise((resolve, reject) => {
+        if (workerDead) {
+            reject(workerUnavailableError);
+            return;
+        }
+        const id = nextId++;
+        pending.set(id, { resolve: resolve, reject });
+        worker.postMessage({ type, id, payload });
+    });
+    await send("init", { dbName, storeName, ttlMs, maxCount });
     return {
-        async add(value) {
-            const db = await getDb(dbName, storeName);
-            setExpiryFields(value);
-            await db.put(storeName, value);
-            const count = await db.count(storeName);
-            if (count > DEFAULT_MAX_COUNT) {
-                await cleanWhenTooLarge(db, storeName, {
-                    dateKey: "createdAt",
-                    maxCount: DEFAULT_MAX_COUNT,
-                });
-            }
-            await cleanOldEntries(db, storeName, {
-                dateKey: "expiresAt",
-                before: Date.now(),
-            });
+        async set(value) {
+            await send("set", value);
         },
         async get(key) {
-            const db = await getDb(dbName, storeName);
-            return (await db.get(storeName, key));
+            return send("get", key);
+        },
+        async getAll() {
+            return send("getAll");
+        },
+        async keys() {
+            return send("keys");
+        },
+        async getMany(keys) {
+            return send("getMany", keys);
         },
         async update(key, value) {
-            const db = await getDb(dbName, storeName);
-            const withKey = { ...value, [DEFAULT_KEY_PATH]: key };
-            await db.put(storeName, withKey);
+            await send("update", { key, value });
         },
         async delete(key) {
-            const db = await getDb(dbName, storeName);
-            await db.delete(storeName, key);
-        },
-        async removeDb() {
-            const db = dbCache.get(dbName);
-            if (db != null) {
-                db.close();
-                dbCache.delete(dbName);
-            }
-            await deleteDB(dbName);
+            await send("delete", key);
+        },
+        async deleteDb() {
+            await send("deleteDb");
         },
     };
 }

package/dist/clientCore.d.ts

@@ -0,0 +1,17 @@
+import type { IDBPDatabase } from "idb";
+export { DEFAULT_TTL_MS } from "./constants.js";
+export declare function getDb(dbName: string, storeName: string): Promise<IDBPDatabase<unknown>>;
+export declare function setExpiryFields(value: Record<string, unknown>, ttlMs?: number): void;
+export interface ExecuteSetOptions {
+    ttlMs?: number;
+    /** Max entries before eviction. Default: 1000. */
+    maxCount?: number;
+}
+export declare function executeSet(dbName: string, storeName: string, value: Record<string, unknown>, options?: ExecuteSetOptions): Promise<void>;
+export declare function executeGet<T>(dbName: string, storeName: string, key: IDBValidKey): Promise<T | undefined>;
+export declare function executeGetAll<T>(dbName: string, storeName: string): Promise<T[]>;
+export declare function executeKeys(dbName: string, storeName: string): Promise<IDBValidKey[]>;
+export declare function executeGetMany<T>(dbName: string, storeName: string, keys: IDBValidKey[]): Promise<(T | undefined)[]>;
+export declare function executeUpdate(dbName: string, storeName: string, key: IDBValidKey, value: Record<string, unknown>): Promise<void>;
+export declare function executeDelete(dbName: string, storeName: string, key: IDBValidKey): Promise<void>;
+export declare function executeDeleteDb(dbName: string): Promise<void>;

package/dist/clientCore.js

@@ -0,0 +1,112 @@
+import { deleteDB } from "idb";
+import { clearMetaForDb, initDb } from "./initDb.js";
+import { cleanOldEntries } from "./cleanOldEntries.js";
+import { cleanWhenTooLarge } from "./cleanWhenTooLarge.js";
+import { DEFAULT_MAX_COUNT, DEFAULT_TTL_MS } from "./constants.js";
+export { DEFAULT_TTL_MS } from "./constants.js";
+const DEFAULT_KEY_PATH = "id";
+const DATE_INDEXES = ["expiresAt", "createdAt"];
+const dbCache = new Map();
+function getDefaultSchema(storeNames) {
+    const stores = {};
+    for (const name of storeNames) {
+        stores[name] = {
+            keyPath: DEFAULT_KEY_PATH,
+            indexes: DATE_INDEXES,
+        };
+    }
+    return { stores };
+}
+export async function getDb(dbName, storeName) {
+    const entry = dbCache.get(dbName);
+    if (entry != null && entry.storeNames.has(storeName)) {
+        return entry.db;
+    }
+    const existingStores = entry != null ? [...entry.storeNames] : [];
+    if (entry != null) {
+        entry.db.close();
+        dbCache.delete(dbName);
+    }
+    const allStores = existingStores.includes(storeName)
+        ? existingStores
+        : [...existingStores, storeName];
+    const schema = getDefaultSchema(allStores);
+    const db = await initDb(dbName, { schema });
+    dbCache.set(dbName, {
+        db,
+        storeNames: new Set(allStores),
+    });
+    return db;
+}
+export function setExpiryFields(value, ttlMs = DEFAULT_TTL_MS) {
+    const now = Date.now();
+    if (value.createdAt === undefined)
+        value.createdAt = now;
+    if (value.expiresAt === undefined)
+        value.expiresAt = now + ttlMs;
+}
+export async function executeSet(dbName, storeName, value, options) {
+    const db = await getDb(dbName, storeName);
+    const toStore = { ...value };
+    setExpiryFields(toStore, options?.ttlMs ?? DEFAULT_TTL_MS);
+    await cleanOldEntries(db, storeName, {
+        dateKey: "expiresAt",
+        before: Date.now(),
+    });
+    const maxCount = options?.maxCount ?? DEFAULT_MAX_COUNT;
+    const count = await db.count(storeName);
+    if (count >= maxCount) {
+        await cleanWhenTooLarge(db, storeName, {
+            dateKey: "createdAt",
+            maxCount,
+        });
+    }
+    await db.put(storeName, toStore);
+    const countAfter = await db.count(storeName);
+    if (countAfter > maxCount) {
+        await cleanWhenTooLarge(db, storeName, {
+            dateKey: "createdAt",
+            maxCount,
+        });
+    }
+}
+export async function executeGet(dbName, storeName, key) {
+    const db = await getDb(dbName, storeName);
+    return (await db.get(storeName, key));
+}
+export async function executeGetAll(dbName, storeName) {
+    const db = await getDb(dbName, storeName);
+    return (await db.getAll(storeName));
+}
+export async function executeKeys(dbName, storeName) {
+    const db = await getDb(dbName, storeName);
+    return db.getAllKeys(storeName);
+}
+export async function executeGetMany(dbName, storeName, keys) {
+    const db = await getDb(dbName, storeName);
+    const results = await Promise.all(keys.map((key) => db.get(storeName, key)));
+    return results;
+}
+export async function executeUpdate(dbName, storeName, key, value) {
+    const db = await getDb(dbName, storeName);
+    const existing = (await db.get(storeName, key));
+    const merged = {
+        ...(existing ?? {}),
+        ...value,
+        [DEFAULT_KEY_PATH]: key,
+    };
+    await db.put(storeName, merged);
+}
+export async function executeDelete(dbName, storeName, key) {
+    const db = await getDb(dbName, storeName);
+    await db.delete(storeName, key);
+}
+export async function executeDeleteDb(dbName) {
+    const entry = dbCache.get(dbName);
+    if (entry != null) {
+        entry.db.close();
+        dbCache.delete(dbName);
+    }
+    await deleteDB(dbName);
+    await clearMetaForDb(dbName);
+}

package/dist/constants.d.ts

@@ -0,0 +1,6 @@
+/** Default TTL in ms (1 hour). Used for values without `expiresAt`. */
+export declare const DEFAULT_TTL_MS: number;
+/** Default max entries before eviction. */
+export declare const DEFAULT_MAX_COUNT = 1000;
+/** Default TTL in seconds (1 hour). Used by putWithEviction when expiresAt is not set. */
+export declare const DEFAULT_TTL_SECONDS = 3600;

package/dist/constants.js

@@ -0,0 +1,6 @@
+/** Default TTL in ms (1 hour). Used for values without `expiresAt`. */
+export const DEFAULT_TTL_MS = 3600 * 1000;
+/** Default max entries before eviction. */
+export const DEFAULT_MAX_COUNT = 1000;
+/** Default TTL in seconds (1 hour). Used by putWithEviction when expiresAt is not set. */
+export const DEFAULT_TTL_SECONDS = 3600;

package/dist/index.d.ts

@@ -1,2 +1,6 @@
-export { createClient } from "./client.js";
-export type { CreateClientOptions, IdbRefinedClient, StoredValue, } from "./client.js";
+export { createIdb } from "./client.js";
+export type { IdbRefinedClient, IdbRefinedOptions, StoredValue, WorkerMessage, WorkerResponse, } from "./client.js";
+/** Advanced: low-level helpers when you have a raw IDBPDatabase (e.g. from initDb). */
+export { clearStore, deleteByKey, } from "./delete.js";
+export { putWithEviction } from "./putWithEviction.js";
+export type { PutWithEvictionOptions } from "./putWithEviction.js";

package/dist/index.js

@@ -1 +1,4 @@
-export { createClient } from "./client.js";
+export { createIdb } from "./client.js";
+/** Advanced: low-level helpers when you have a raw IDBPDatabase (e.g. from initDb). */
+export { clearStore, deleteByKey, } from "./delete.js";
+export { putWithEviction } from "./putWithEviction.js";

package/dist/initDb.d.ts

@@ -10,3 +10,7 @@ export interface InitDbOptions {
  * from a fingerprint; when `version` and/or `upgrade` are provided, use them directly.
  */
 export declare function initDb(name: string, options?: InitDbOptions): Promise<IDBPDatabase<unknown>>;
+/**
+ * Remove the meta row for a database (e.g. after deleteDB). Keeps the meta DB from growing.
+ */
+export declare function clearMetaForDb(dbName: string): Promise<void>;

package/dist/initDb.js

@@ -25,7 +25,6 @@ async function initDbWithSchema(name, schema, customUpgrade) {
         },
     });
     const stored = (await metaDb.get(META_STORE, name));
-    metaDb.close();
     let currentVersion = 0;
     try {
         const probe = await openDB(name);
@@ -48,13 +47,26 @@ async function initDbWithSchema(name, schema, customUpgrade) {
         },
     }));
     if (needUpgrade) {
-        const metaDb2 = await openDB(META_DB_NAME, 1);
-        await metaDb2.put(META_STORE, {
+        await metaDb.put(META_STORE, {
             dbName: name,
             schemaFingerprint: fp,
             version: newVersion,
         });
-        metaDb2.close();
     }
+    metaDb.close();
     return db;
 }
+/**
+ * Remove the meta row for a database (e.g. after deleteDB). Keeps the meta DB from growing.
+ */
+export async function clearMetaForDb(dbName) {
+    const metaDb = await openDB(META_DB_NAME, 1, {
+        upgrade(db) {
+            if (!db.objectStoreNames.contains(META_STORE)) {
+                db.createObjectStore(META_STORE, { keyPath: "dbName" });
+            }
+        },
+    });
+    await metaDb.delete(META_STORE, dbName);
+    metaDb.close();
+}

package/dist/putWithEviction.js

@@ -1,6 +1,5 @@
 import { cleanWhenTooLarge } from "./cleanWhenTooLarge.js";
-const DEFAULT_TTL_SECONDS = 3600;
-const DEFAULT_MAX_COUNT = 1000;
+import { DEFAULT_MAX_COUNT, DEFAULT_TTL_SECONDS } from "./constants.js";
 /**
  * Put a value in the store, then if count > maxCount evict oldest entries (by dateKey).
  * Optionally set the dateKey field from expiresAt (absolute ms) or ttlSeconds (relative seconds).

package/dist/worker.js

@@ -0,0 +1,579 @@
+// node_modules/.pnpm/idb@8.0.3/node_modules/idb/build/index.js
+var instanceOfAny = (object, constructors) => constructors.some((c) => object instanceof c);
+var idbProxyableTypes;
+var cursorAdvanceMethods;
+function getIdbProxyableTypes() {
+  return idbProxyableTypes || (idbProxyableTypes = [
+    IDBDatabase,
+    IDBObjectStore,
+    IDBIndex,
+    IDBCursor,
+    IDBTransaction
+  ]);
+}
+function getCursorAdvanceMethods() {
+  return cursorAdvanceMethods || (cursorAdvanceMethods = [
+    IDBCursor.prototype.advance,
+    IDBCursor.prototype.continue,
+    IDBCursor.prototype.continuePrimaryKey
+  ]);
+}
+var transactionDoneMap = /* @__PURE__ */ new WeakMap();
+var transformCache = /* @__PURE__ */ new WeakMap();
+var reverseTransformCache = /* @__PURE__ */ new WeakMap();
+function promisifyRequest(request) {
+  const promise = new Promise((resolve, reject) => {
+    const unlisten = () => {
+      request.removeEventListener("success", success);
+      request.removeEventListener("error", error);
+    };
+    const success = () => {
+      resolve(wrap(request.result));
+      unlisten();
+    };
+    const error = () => {
+      reject(request.error);
+      unlisten();
+    };
+    request.addEventListener("success", success);
+    request.addEventListener("error", error);
+  });
+  reverseTransformCache.set(promise, request);
+  return promise;
+}
+function cacheDonePromiseForTransaction(tx) {
+  if (transactionDoneMap.has(tx))
+    return;
+  const done = new Promise((resolve, reject) => {
+    const unlisten = () => {
+      tx.removeEventListener("complete", complete);
+      tx.removeEventListener("error", error);
+      tx.removeEventListener("abort", error);
+    };
+    const complete = () => {
+      resolve();
+      unlisten();
+    };
+    const error = () => {
+      reject(tx.error || new DOMException("AbortError", "AbortError"));
+      unlisten();
+    };
+    tx.addEventListener("complete", complete);
+    tx.addEventListener("error", error);
+    tx.addEventListener("abort", error);
+  });
+  transactionDoneMap.set(tx, done);
+}
+var idbProxyTraps = {
+  get(target, prop, receiver) {
+    if (target instanceof IDBTransaction) {
+      if (prop === "done")
+        return transactionDoneMap.get(target);
+      if (prop === "store") {
+        return receiver.objectStoreNames[1] ? void 0 : receiver.objectStore(receiver.objectStoreNames[0]);
+      }
+    }
+    return wrap(target[prop]);
+  },
+  set(target, prop, value) {
+    target[prop] = value;
+    return true;
+  },
+  has(target, prop) {
+    if (target instanceof IDBTransaction && (prop === "done" || prop === "store")) {
+      return true;
+    }
+    return prop in target;
+  }
+};
+function replaceTraps(callback) {
+  idbProxyTraps = callback(idbProxyTraps);
+}
+function wrapFunction(func) {
+  if (getCursorAdvanceMethods().includes(func)) {
+    return function(...args) {
+      func.apply(unwrap(this), args);
+      return wrap(this.request);
+    };
+  }
+  return function(...args) {
+    return wrap(func.apply(unwrap(this), args));
+  };
+}
+function transformCachableValue(value) {
+  if (typeof value === "function")
+    return wrapFunction(value);
+  if (value instanceof IDBTransaction)
+    cacheDonePromiseForTransaction(value);
+  if (instanceOfAny(value, getIdbProxyableTypes()))
+    return new Proxy(value, idbProxyTraps);
+  return value;
+}
+function wrap(value) {
+  if (value instanceof IDBRequest)
+    return promisifyRequest(value);
+  if (transformCache.has(value))
+    return transformCache.get(value);
+  const newValue = transformCachableValue(value);
+  if (newValue !== value) {
+    transformCache.set(value, newValue);
+    reverseTransformCache.set(newValue, value);
+  }
+  return newValue;
+}
+var unwrap = (value) => reverseTransformCache.get(value);
+function openDB(name, version, { blocked, upgrade, blocking, terminated } = {}) {
+  const request = indexedDB.open(name, version);
+  const openPromise = wrap(request);
+  if (upgrade) {
+    request.addEventListener("upgradeneeded", (event) => {
+      upgrade(wrap(request.result), event.oldVersion, event.newVersion, wrap(request.transaction), event);
+    });
+  }
+  if (blocked) {
+    request.addEventListener("blocked", (event) => blocked(
+      // Casting due to https://github.com/microsoft/TypeScript-DOM-lib-generator/pull/1405
+      event.oldVersion,
+      event.newVersion,
+      event
+    ));
+  }
+  openPromise.then((db) => {
+    if (terminated)
+      db.addEventListener("close", () => terminated());
+    if (blocking) {
+      db.addEventListener("versionchange", (event) => blocking(event.oldVersion, event.newVersion, event));
+    }
+  }).catch(() => {
+  });
+  return openPromise;
+}
+function deleteDB(name, { blocked } = {}) {
+  const request = indexedDB.deleteDatabase(name);
+  if (blocked) {
+    request.addEventListener("blocked", (event) => blocked(
+      // Casting due to https://github.com/microsoft/TypeScript-DOM-lib-generator/pull/1405
+      event.oldVersion,
+      event
+    ));
+  }
+  return wrap(request).then(() => void 0);
+}
+var readMethods = ["get", "getKey", "getAll", "getAllKeys", "count"];
+var writeMethods = ["put", "add", "delete", "clear"];
+var cachedMethods = /* @__PURE__ */ new Map();
+function getMethod(target, prop) {
+  if (!(target instanceof IDBDatabase && !(prop in target) && typeof prop === "string")) {
+    return;
+  }
+  if (cachedMethods.get(prop))
+    return cachedMethods.get(prop);
+  const targetFuncName = prop.replace(/FromIndex$/, "");
+  const useIndex = prop !== targetFuncName;
+  const isWrite = writeMethods.includes(targetFuncName);
+  if (
+    // Bail if the target doesn't exist on the target. Eg, getAll isn't in Edge.
+    !(targetFuncName in (useIndex ? IDBIndex : IDBObjectStore).prototype) || !(isWrite || readMethods.includes(targetFuncName))
+  ) {
+    return;
+  }
+  const method = async function(storeName2, ...args) {
+    const tx = this.transaction(storeName2, isWrite ? "readwrite" : "readonly");
+    let target2 = tx.store;
+    if (useIndex)
+      target2 = target2.index(args.shift());
+    return (await Promise.all([
+      target2[targetFuncName](...args),
+      isWrite && tx.done
+    ]))[0];
+  };
+  cachedMethods.set(prop, method);
+  return method;
+}
+replaceTraps((oldTraps) => ({
+  ...oldTraps,
+  get: (target, prop, receiver) => getMethod(target, prop) || oldTraps.get(target, prop, receiver),
+  has: (target, prop) => !!getMethod(target, prop) || oldTraps.has(target, prop)
+}));
+var advanceMethodProps = ["continue", "continuePrimaryKey", "advance"];
+var methodMap = {};
+var advanceResults = /* @__PURE__ */ new WeakMap();
+var ittrProxiedCursorToOriginalProxy = /* @__PURE__ */ new WeakMap();
+var cursorIteratorTraps = {
+  get(target, prop) {
+    if (!advanceMethodProps.includes(prop))
+      return target[prop];
+    let cachedFunc = methodMap[prop];
+    if (!cachedFunc) {
+      cachedFunc = methodMap[prop] = function(...args) {
+        advanceResults.set(this, ittrProxiedCursorToOriginalProxy.get(this)[prop](...args));
+      };
+    }
+    return cachedFunc;
+  }
+};
+async function* iterate(...args) {
+  let cursor = this;
+  if (!(cursor instanceof IDBCursor)) {
+    cursor = await cursor.openCursor(...args);
+  }
+  if (!cursor)
+    return;
+  cursor = cursor;
+  const proxiedCursor = new Proxy(cursor, cursorIteratorTraps);
+  ittrProxiedCursorToOriginalProxy.set(proxiedCursor, cursor);
+  reverseTransformCache.set(proxiedCursor, unwrap(cursor));
+  while (cursor) {
+    yield proxiedCursor;
+    cursor = await (advanceResults.get(proxiedCursor) || cursor.continue());
+    advanceResults.delete(proxiedCursor);
+  }
+}
+function isIteratorProp(target, prop) {
+  return prop === Symbol.asyncIterator && instanceOfAny(target, [IDBIndex, IDBObjectStore, IDBCursor]) || prop === "iterate" && instanceOfAny(target, [IDBIndex, IDBObjectStore]);
+}
+replaceTraps((oldTraps) => ({
+  ...oldTraps,
+  get(target, prop, receiver) {
+    if (isIteratorProp(target, prop))
+      return iterate;
+    return oldTraps.get(target, prop, receiver);
+  },
+  has(target, prop) {
+    return isIteratorProp(target, prop) || oldTraps.has(target, prop);
+  }
+}));
+
+// src/schema.ts
+function fingerprint(schema) {
+  const normalized = {};
+  for (const name of Object.keys(schema.stores).sort()) {
+    const def = schema.stores[name];
+    const indexes = def.indexes == null ? void 0 : 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);
+}
+function applySchema(db, schema, transaction) {
+  for (const [storeName2, def] of Object.entries(schema.stores)) {
+    const store = !db.objectStoreNames.contains(storeName2) ? db.createObjectStore(storeName2, {
+      keyPath: def.keyPath,
+      autoIncrement: def.autoIncrement ?? false
+    }) : transaction.objectStore(storeName2);
+    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);
+        }
+      }
+    }
+  }
+}
+
+// src/initDb.ts
+var META_DB_NAME = "idb-refined-meta";
+var META_STORE = "meta";
+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(db2) {
+      if (!db2.objectStoreNames.contains(META_STORE)) {
+        db2.createObjectStore(META_STORE, { keyPath: "dbName" });
+      }
+    }
+  });
+  const stored = await metaDb.get(META_STORE, name);
+  let currentVersion = 0;
+  try {
+    const probe = await openDB(name);
+    currentVersion = probe.version;
+    probe.close();
+  } catch {
+  }
+  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(db2, _oldVersion, _newVersion, transaction) {
+      if (needUpgrade) {
+        applySchema(db2, schema, transaction);
+      }
+      customUpgrade?.(db2);
+    }
+  });
+  if (needUpgrade) {
+    await metaDb.put(META_STORE, {
+      dbName: name,
+      schemaFingerprint: fp,
+      version: newVersion
+    });
+  }
+  metaDb.close();
+  return db;
+}
+async function clearMetaForDb(dbName2) {
+  const metaDb = await openDB(META_DB_NAME, 1, {
+    upgrade(db) {
+      if (!db.objectStoreNames.contains(META_STORE)) {
+        db.createObjectStore(META_STORE, { keyPath: "dbName" });
+      }
+    }
+  });
+  await metaDb.delete(META_STORE, dbName2);
+  metaDb.close();
+}
+
+// src/cleanOldEntries.ts
+async function cleanOldEntries(db, storeName2, options) {
+  const { dateKey, before } = options;
+  const tx = db.transaction(storeName2, "readwrite");
+  const store = tx.objectStore(storeName2);
+  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;
+}
+
+// src/constants.ts
+var DEFAULT_TTL_MS = 3600 * 1e3;
+var DEFAULT_MAX_COUNT = 1e3;
+
+// src/cleanWhenTooLarge.ts
+async function cleanWhenTooLarge(db, storeName2, options) {
+  const { dateKey } = options;
+  const maxCount2 = options.maxCount ?? DEFAULT_MAX_COUNT;
+  const count = await db.count(storeName2);
+  if (count <= maxCount2) return 0;
+  const toDelete = count - maxCount2;
+  const tx = db.transaction(storeName2, "readwrite");
+  const store = tx.objectStore(storeName2);
+  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;
+}
+
+// src/clientCore.ts
+var DEFAULT_KEY_PATH = "id";
+var DATE_INDEXES = ["expiresAt", "createdAt"];
+var dbCache = /* @__PURE__ */ new Map();
+function getDefaultSchema(storeNames) {
+  const stores = {};
+  for (const name of storeNames) {
+    stores[name] = {
+      keyPath: DEFAULT_KEY_PATH,
+      indexes: DATE_INDEXES
+    };
+  }
+  return { stores };
+}
+async function getDb(dbName2, storeName2) {
+  const entry = dbCache.get(dbName2);
+  if (entry != null && entry.storeNames.has(storeName2)) {
+    return entry.db;
+  }
+  const existingStores = entry != null ? [...entry.storeNames] : [];
+  if (entry != null) {
+    entry.db.close();
+    dbCache.delete(dbName2);
+  }
+  const allStores = existingStores.includes(storeName2) ? existingStores : [...existingStores, storeName2];
+  const schema = getDefaultSchema(allStores);
+  const db = await initDb(dbName2, { schema });
+  dbCache.set(dbName2, {
+    db,
+    storeNames: new Set(allStores)
+  });
+  return db;
+}
+function setExpiryFields(value, ttlMs2 = DEFAULT_TTL_MS) {
+  const now = Date.now();
+  if (value.createdAt === void 0) value.createdAt = now;
+  if (value.expiresAt === void 0) value.expiresAt = now + ttlMs2;
+}
+async function executeSet(dbName2, storeName2, value, options) {
+  const db = await getDb(dbName2, storeName2);
+  const toStore = { ...value };
+  setExpiryFields(toStore, options?.ttlMs ?? DEFAULT_TTL_MS);
+  await cleanOldEntries(db, storeName2, {
+    dateKey: "expiresAt",
+    before: Date.now()
+  });
+  const maxCount2 = options?.maxCount ?? DEFAULT_MAX_COUNT;
+  const count = await db.count(storeName2);
+  if (count >= maxCount2) {
+    await cleanWhenTooLarge(db, storeName2, {
+      dateKey: "createdAt",
+      maxCount: maxCount2
+    });
+  }
+  await db.put(storeName2, toStore);
+  const countAfter = await db.count(storeName2);
+  if (countAfter > maxCount2) {
+    await cleanWhenTooLarge(db, storeName2, {
+      dateKey: "createdAt",
+      maxCount: maxCount2
+    });
+  }
+}
+async function executeGet(dbName2, storeName2, key) {
+  const db = await getDb(dbName2, storeName2);
+  return await db.get(storeName2, key);
+}
+async function executeGetAll(dbName2, storeName2) {
+  const db = await getDb(dbName2, storeName2);
+  return await db.getAll(storeName2);
+}
+async function executeKeys(dbName2, storeName2) {
+  const db = await getDb(dbName2, storeName2);
+  return db.getAllKeys(storeName2);
+}
+async function executeGetMany(dbName2, storeName2, keys) {
+  const db = await getDb(dbName2, storeName2);
+  const results = await Promise.all(
+    keys.map((key) => db.get(storeName2, key))
+  );
+  return results;
+}
+async function executeUpdate(dbName2, storeName2, key, value) {
+  const db = await getDb(dbName2, storeName2);
+  const existing = await db.get(storeName2, key);
+  const merged = {
+    ...existing ?? {},
+    ...value,
+    [DEFAULT_KEY_PATH]: key
+  };
+  await db.put(storeName2, merged);
+}
+async function executeDelete(dbName2, storeName2, key) {
+  const db = await getDb(dbName2, storeName2);
+  await db.delete(storeName2, key);
+}
+async function executeDeleteDb(dbName2) {
+  const entry = dbCache.get(dbName2);
+  if (entry != null) {
+    entry.db.close();
+    dbCache.delete(dbName2);
+  }
+  await deleteDB(dbName2);
+  await clearMetaForDb(dbName2);
+}
+
+// src/worker.ts
+var dbName;
+var storeName;
+var ttlMs;
+var maxCount;
+function respond(id, result, error) {
+  const msg = error != null ? { id, error } : { id, result };
+  self.postMessage(msg);
+}
+self.onmessage = async (e) => {
+  const { type, id, payload } = e.data;
+  try {
+    switch (type) {
+      case "init": {
+        const {
+          dbName: dn,
+          storeName: sn,
+          ttlMs: ttl,
+          maxCount: max
+        } = payload;
+        dbName = dn;
+        storeName = sn;
+        ttlMs = ttl;
+        maxCount = max;
+        await getDb(dbName, storeName);
+        respond(id);
+        break;
+      }
+      case "set":
+        await executeSet(
+          dbName,
+          storeName,
+          payload,
+          {
+            ttlMs,
+            maxCount
+          }
+        );
+        respond(id);
+        break;
+      case "get": {
+        const value = await executeGet(
+          dbName,
+          storeName,
+          payload
+        );
+        respond(id, value);
+        break;
+      }
+      case "getAll": {
+        const values = await executeGetAll(dbName, storeName);
+        respond(id, values);
+        break;
+      }
+      case "keys": {
+        const keysResult = await executeKeys(dbName, storeName);
+        respond(id, keysResult);
+        break;
+      }
+      case "getMany": {
+        const values = await executeGetMany(
+          dbName,
+          storeName,
+          payload
+        );
+        respond(id, values);
+        break;
+      }
+      case "update": {
+        const { key, value } = payload;
+        await executeUpdate(dbName, storeName, key, value);
+        respond(id);
+        break;
+      }
+      case "delete":
+        await executeDelete(dbName, storeName, payload);
+        respond(id);
+        break;
+      case "deleteDb":
+        await executeDeleteDb(dbName);
+        respond(id);
+        break;
+      default:
+        respond(id, void 0, `Unknown message type: ${type}`);
+    }
+  } catch (err) {
+    respond(id, void 0, err instanceof Error ? err.message : String(err));
+  }
+};

package/dist/workerProtocol.d.ts

@@ -0,0 +1,52 @@
+export type WorkerMessage = {
+    type: "init";
+    id: number;
+    payload: {
+        dbName: string;
+        storeName: string;
+        ttlMs?: number;
+        maxCount?: number;
+    };
+} | {
+    type: "set";
+    id: number;
+    payload: unknown;
+} | {
+    type: "get";
+    id: number;
+    payload: IDBValidKey;
+} | {
+    type: "getAll";
+    id: number;
+    payload?: undefined;
+} | {
+    type: "keys";
+    id: number;
+    payload?: undefined;
+} | {
+    type: "getMany";
+    id: number;
+    payload: IDBValidKey[];
+} | {
+    type: "update";
+    id: number;
+    payload: {
+        key: IDBValidKey;
+        value: unknown;
+    };
+} | {
+    type: "delete";
+    id: number;
+    payload: IDBValidKey;
+} | {
+    type: "deleteDb";
+    id: number;
+    payload?: undefined;
+};
+export type WorkerResponse = {
+    id: number;
+    result: unknown;
+} | {
+    id: number;
+    error: string;
+};

package/dist/workerProtocol.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "idb-refined",
-  "version": "0.0.3",
-  "description": "Thin TypeScript IndexedDB helper: initDb (auto-version), clean by date/size, add with eviction, delete helpers",
+  "version": "0.0.5",
+  "description": "Minimal IndexedDB client with TTL, eviction, and Web Worker support—no manual schema versions.",
   "type": "module",
+  "repository": "github:thiennp/idb-refined",
+  "homepage": "https://github.com/thiennp/idb-refined#readme",
+  "bugs": {
+    "url": "https://github.com/thiennp/idb-refined/issues"
+  },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,13 +16,18 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./worker": {
+      "import": "./dist/worker.js",
+      "default": "./dist/worker.js"
     }
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && esbuild src/worker.ts --bundle --format=esm --outfile=dist/worker.js --platform=browser",
+    "example": "pnpm build && vite --config example/vite.config.ts",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
     "format": "prettier --write \"src/**/*.ts\"",
@@ -39,6 +49,7 @@
     "@commitlint/cli": "^19.8.1",
     "@commitlint/config-conventional": "^19.8.1",
     "@eslint/js": "^9.39.2",
+    "esbuild": "^0.24.2",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^9.1.2",
     "fake-indexeddb": "^6.2.5",
@@ -47,6 +58,7 @@
     "prettier": "^3.8.1",
     "typescript": "^5.6.3",
     "typescript-eslint": "^8.54.0",
+    "vite": "^6.0.3",
     "vitest": "^2.1.9"
   },
   "keywords": [