idb-refined 0.0.2 → 0.0.3

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+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.
 
 ## Install
 
@@ -12,71 +12,45 @@ 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`; or use manual `version` and `upgrade`. Returns idb’s `IDBPDatabase`. |
-| **cleanOldEntries(db, storeName, options)** | Delete entries where `dateKey` < `before` (timestamp ms). Requires an index on `dateKey`. |
-| **cleanWhenTooLarge(db, storeName, options)** | Evict oldest entries (by `dateKey`) until count ≤ `maxCount`. Returns count deleted. Requires an index on `dateKey`. `maxCount` is optional. |
-| **putWithEviction(db, storeName, value, options)** | Put value, then if store count > `maxCount` evict oldest by `dateKey`. Options may include `expiresAt` (ms), `ttlSeconds` (seconds), and optional `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`. |
+| 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. |
+| **get(key)** | Get a value by key. Returns `undefined` if not found. |
+| **update(key, value)** | Update an existing entry by key. |
+| **delete(key)** | Delete an entry by key. |
+| **deleteDb()** | Close the DB and delete it from disk. |
 
-For parameter details, behavior, and use-case explanations, see **[Advanced documentation](docs/advanced.md)**.
+For details, see **[Advanced documentation](docs/advanced.md)**. Run the **[example](example/)** in the browser (see `example/README.md`).
 
-## Examples
-
-### Cache with TTL and max size
+## Example
 
 ```ts
-import { initDb, putWithEviction, cleanOldEntries, deleteByKey } from "idb-refined";
-
-const db = await initDb("my-cache", {
-  schema: {
-    stores: {
-      cache: { keyPath: "id", indexes: ["expiresAt"] },
-    },
-  },
-});
-
-await putWithEviction(db, "cache", { id: "k1", data: "v1" }, {
-  dateKey: "expiresAt",
-  maxCount: 1000,
-  ttlSeconds: 3600,
-});
-
-await cleanOldEntries(db, "cache", { dateKey: "expiresAt", before: Date.now() });
-await deleteByKey(db, "cache", "k1");
-```
+import { createClient } from "idb-refined";
 
-### Log buffer
+// 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" });
 
-```ts
-await putWithEviction(db, "logs", { id: generateId(), message }, {
-  dateKey: "createdAt",
-  maxCount: 5000,
-});
-```
-
-### Manual eviction
-
-```ts
-const deleted = await cleanWhenTooLarge(db, "cache", { dateKey: "expiresAt", maxCount: 500 });
-console.log(`Evicted ${deleted} entries`);
+await set({ id: "1", name: "Alice" });
+const value = await get("1"); // User | undefined
+await update("1", { name: "Alice Updated" });
+await del("1");
+await deleteDb();
 ```
 
 ## Requirements
 
-- Stores used with `cleanOldEntries`, `cleanWhenTooLarge`, or `putWithEviction` must have an **index** on the date field (e.g. `expiresAt`, `createdAt`). Define it in your schema.
-- Eviction is **count-based** only (no byte-size or quota check).
+- 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.
 
 ## 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`.
+3. Pushing a tag matching `v*` triggers the [Publish to npm](.github/workflows/publish.yml) workflow.
 
-**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.
+**Required:** Add an `NPM_TOKEN` secret in the repo (Settings → Secrets and variables → Actions).
 
 ## License
 

package/dist/cleanWhenTooLarge.d.ts

@@ -1,7 +1,8 @@
 import type { IDBPDatabase } from "idb";
 export interface CleanWhenTooLargeOptions {
     dateKey: string;
-    maxCount: number;
+    /** Target max entries after eviction. */
+    maxCount?: number;
 }
 /**
  * Evict oldest entries (by dateKey) until store count <= maxCount.

package/dist/cleanWhenTooLarge.js

@@ -1,9 +1,11 @@
+const DEFAULT_MAX_COUNT = 1000;
 /**
  * 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 { dateKey } = options;
+    const maxCount = options.maxCount ?? DEFAULT_MAX_COUNT;
     const count = await db.count(storeName);
     if (count <= maxCount)
         return 0;

package/dist/client.d.ts

@@ -0,0 +1,21 @@
+export interface CreateClientOptions {
+    dbName: string;
+    storeName?: string;
+}
+/** 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>;
+    get: (key: IDBValidKey) => Promise<T | undefined>;
+    update: (key: IDBValidKey, value: Partial<T>) => Promise<void>;
+    delete: (key: IDBValidKey) => Promise<void>;
+    removeDb: () => Promise<void>;
+}
+/**
+ * Create a client that exposes add, get, update, delete, removeDb.
+ * Init, schema, cleanup and eviction run automatically.
+ * @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>;

package/dist/client.js

@@ -0,0 +1,84 @@
+import { deleteDB } from "idb";
+import { initDb } from "./initDb.js";
+import { cleanOldEntries } from "./cleanOldEntries.js";
+import { cleanWhenTooLarge } from "./cleanWhenTooLarge.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) {
+    return {
+        stores: {
+            [storeName]: {
+                keyPath: DEFAULT_KEY_PATH,
+                indexes: DATE_INDEXES,
+            },
+        },
+    };
+}
+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.
+ * @template T - Stored value shape (must include `id`). Omit for a generic client.
+ */
+export function createClient(options) {
+    const { dbName } = options;
+    const storeName = options.storeName ?? DEFAULT_STORE_NAME;
+    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 get(key) {
+            const db = await getDb(dbName, storeName);
+            return (await db.get(storeName, key));
+        },
+        async update(key, value) {
+            const db = await getDb(dbName, storeName);
+            const withKey = { ...value, [DEFAULT_KEY_PATH]: key };
+            await db.put(storeName, withKey);
+        },
+        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);
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,13 +1,2 @@
-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";
+export { createClient } from "./client.js";
+export type { CreateClientOptions, IdbRefinedClient, StoredValue, } from "./client.js";

package/dist/index.js

@@ -1,7 +1 @@
-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";
+export { createClient } from "./client.js";

package/dist/putWithEviction.d.ts

@@ -2,7 +2,8 @@ import type { IDBPDatabase } from "idb";
 export interface PutWithEvictionOptions {
     key?: IDBValidKey;
     dateKey: string;
-    maxCount: number;
+    /** Evict oldest when store count exceeds this. */
+    maxCount?: number;
     /** Absolute expiry timestamp (ms). If set, used for the dateKey field on the value. */
     expiresAt?: number;
     /** Relative expiry in seconds. Used when expiresAt is not set; then dateKey = now + ttlSeconds * 1000. */

package/dist/putWithEviction.js

@@ -1,19 +1,22 @@
 import { cleanWhenTooLarge } from "./cleanWhenTooLarge.js";
 const DEFAULT_TTL_SECONDS = 3600;
+const DEFAULT_MAX_COUNT = 1000;
 /**
  * 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).
  * Value must include the keyPath field, or pass options.key.
  */
 export async function putWithEviction(db, storeName, value, options) {
-    const { key, dateKey, maxCount, expiresAt, ttlSeconds } = options;
+    const { key, dateKey, expiresAt, ttlSeconds } = options;
+    const maxCount = options.maxCount ?? DEFAULT_MAX_COUNT;
     if (typeof value === "object" && value !== null) {
         const valueRecord = value;
         if (expiresAt !== undefined) {
             valueRecord[dateKey] = expiresAt;
         }
         else {
-            valueRecord[dateKey] = Date.now() + (ttlSeconds ?? DEFAULT_TTL_SECONDS) * 1000;
+            valueRecord[dateKey] =
+                Date.now() + (ttlSeconds ?? DEFAULT_TTL_SECONDS) * 1000;
         }
     }
     await db.put(storeName, value, key);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idb-refined",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Thin TypeScript IndexedDB helper: initDb (auto-version), clean by date/size, add with eviction, delete helpers",
   "type": "module",
   "main": "./dist/index.js",