idb-refined 0.0.1 → 0.0.2

package/README.md

@@ -14,21 +14,15 @@ npm install idb-refined
 
 | 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 }`. |
+| **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`. |
 
-## 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.
+For parameter details, behavior, and use-case explanations, see **[Advanced documentation](docs/advanced.md)**.
 
 ## Examples
 
@@ -45,57 +39,35 @@ const db = await initDb("my-cache", {
   },
 });
 
-// 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", {
+await putWithEviction(db, "cache", { id: "k1", data: "v1" }, {
   dateKey: "expiresAt",
-  before: Date.now(),
+  maxCount: 1000,
+  ttlSeconds: 3600,
 });
 
-// Delete one
+await cleanOldEntries(db, "cache", { dateKey: "expiresAt", before: Date.now() });
 await deleteByKey(db, "cache", "k1");
 ```
 
-### Log buffer (cap size)
+### Log buffer
 
 ```ts
-await putWithEviction(
-  db,
-  "logs",
-  { id: generateId(), message, createdAt: Date.now() },
-  { dateKey: "createdAt", maxCount: 5000 }
-);
+await putWithEviction(db, "logs", { id: generateId(), message }, {
+  dateKey: "createdAt",
+  maxCount: 5000,
+});
 ```
 
-### Manual cleanup when too large
+### Manual eviction
 
 ```ts
-const deleted = await cleanWhenTooLarge(db, "cache", {
-  dateKey: "expiresAt",
-  maxCount: 500,
-});
+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"] },
-    },
-  }
-  ```
-
+- 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).
 
 ## Releasing

package/dist/putWithEviction.d.ts

@@ -3,9 +3,14 @@ export interface PutWithEvictionOptions {
     key?: IDBValidKey;
     dateKey: string;
     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,21 @@
 import { cleanWhenTooLarge } from "./cleanWhenTooLarge.js";
+const DEFAULT_TTL_SECONDS = 3600;
 /**
  * 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, maxCount, expiresAt, ttlSeconds } = options;
+    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.2",
   "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"
+}