idb-refined 0.0.1 → 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,99 +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`; 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`. |
+| 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. |
 
-## Use cases
+For details, see **[Advanced documentation](docs/advanced.md)**. Run the **[example](example/)** in the browser (see `example/README.md`).
 
-- **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)
+## Example
 
 ```ts
-await putWithEviction(
-  db,
-  "logs",
-  { id: generateId(), message, createdAt: Date.now() },
-  { dateKey: "createdAt", maxCount: 5000 }
-);
-```
+import { createClient } from "idb-refined";
 
-### Manual cleanup when too large
+// 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
-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 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).
+- 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,10 +2,16 @@ 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. */
+    ttlSeconds?: number;
 }
 /**
  * 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 declare function putWithEviction<T = unknown>(db: IDBPDatabase<unknown>, storeName: string, value: T, options: PutWithEvictionOptions): Promise<void>;

package/dist/putWithEviction.js

@@ -1,10 +1,24 @@
 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 } = 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;
+        }
+    }
     await db.put(storeName, value, key);
     const count = await db.count(storeName);
     if (count > maxCount) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idb-refined",
-  "version": "0.0.1",
+  "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",
@@ -16,6 +16,16 @@
   "files": [
     "dist"
   ],
+  "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",
+    "prepare": "husky"
+  },
   "lint-staged": {
     "src/**/*.ts": [
       "eslint --fix",
@@ -46,14 +56,5 @@
     "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"
-  }
-}
+  "license": "MIT"
+}