@actdim/utico 1.1.3 → 1.1.6

package/README.md

@@ -2,20 +2,41 @@
 
 A modern foundation toolkit for complex TypeScript apps.
 
+[![npm version](https://img.shields.io/npm/v/@actdim/utico.svg)](https://www.npmjs.com/package/@actdim/utico)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
+[![License: Proprietary](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)
+
 ## Table of Contents
 
 - [Installation](#installation)
 - [Modules](#modules)
     - [typeCore — Expressive Type Composition](#typecore--expressive-type-composition)
     - [typeUtils — Runtime Type Utilities](#typeutils--runtime-type-utilities)
+    - [stringCore — Locale-Aware String Utilities](#stringcore--locale-aware-string-utilities)
+    - [metadata — Property Metadata](#metadata--property-metadata)
+    - [decorators — Property Decorators](#decorators--property-decorators)
+    - [dateTimeDataFormat — Date/Time Serialisation](#datetimedataformat--datetime-serialisation)
     - [StructEvent — Typed DOM Events](#structevent--typed-dom-events)
     - [watchable — Promise & Function Tracking](#watchable--promise--function-tracking)
     - [asyncMutex — Async Mutual Exclusion](#asyncmutex--async-mutual-exclusion)
     - [store — Structured Persistence](#store--structured-persistence)
+    - [cache — Persistent Cache](#cache--persistent-cache)
 - [License](#license)
 
 ---
 
+## Quick Start
+
+Try @actdim/utico instantly in your browser without any installation:
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/~/github.com/actdim/utico)
+
+Once the project loads, run the tests to see it in action:
+
+```bash
+pnpm run test
+```
+
 ## Installation
 
 ```bash
@@ -27,10 +48,10 @@ pnpm add @actdim/utico
 **Peer dependencies** (install only what you use):
 
 ```bash
-pnpm add dexie uuid moment
+pnpm add dexie uuid luxon
 ```
 
-> `dexie` and `uuid` are required for the `store` module. `moment` is required for date/time formatting utilities.
+> `dexie` and `uuid` are required for the `store` module. `luxon` is required for the `dateTimeDataFormat` module.
 
 ---
 
@@ -196,7 +217,7 @@ generic class without repeating its type arguments everywhere.
 (see [StructEvent](#structevent--typed-dom-events)).
 Inside `PersistentCache` you want to work with
 `StructEvent<PersistentCacheEventStruct, PersistentCache>` as if it were its own named type.
-TypeScript offers four ways to achieve this; each has different trade-offs.
+TypeScript offers four ways to achieve this; each has different trade-offs — see the [full comparison](#comparison-4-ways-to-bind-a-generic-constructor) at the end of this section.
 
 ---
 
@@ -248,63 +269,6 @@ const evt = PersistentCacheEvent("evict", { detail: { records }, target: this })
 
 ---
 
-#### Comparison: 4 ways to bind a generic constructor
-
-All four examples produce a bound alias for `StructEvent<PersistentCacheEventStruct, PersistentCache>`.
-
-**1. Subclass**
-
-```ts
-class PersistentCacheEvent
-    extends StructEvent<PersistentCacheEventStruct, PersistentCache> {}
-```
-
-**2. Manual cast**
-
-```ts
-type PersistentCacheEvent = StructEvent<PersistentCacheEventStruct, PersistentCache>;
-const PersistentCacheEvent = StructEvent as new (
-    ...args: ConstructorParameters<typeof StructEvent<PersistentCacheEventStruct, PersistentCache>>
-) => PersistentCacheEvent;
-```
-
-**3. `typed()` + Instantiation Expression** *(recommended)*
-
-```ts
-const PersistentCacheEvent = typed(StructEvent<PersistentCacheEventStruct, PersistentCache>);
-const evt = new PersistentCacheEvent("evict", { detail: { records }, target: this });
-```
-
-**4. `createConstructor()` — callable without `new`**
-
-```ts
-const PersistentCacheEvent = createConstructor(StructEvent<PersistentCacheEventStruct, PersistentCache>);
-const evt = PersistentCacheEvent("evict", { detail: { records }, target: this }); // no new
-```
-
----
-
-**Feature comparison**
-
-| | Subclass | Manual cast | `typed()` | `createConstructor()` |
-|---|:---:|:---:|:---:|:---:|
-| Runtime overhead | new class | none | **none** | wrapper function |
-| `new` required | yes | yes | yes | **no** |
-| `instanceof` | **yes** | no | no | no |
-| Can add methods | **yes** | no | no | no |
-| Verbosity | medium | **high** | **low** | **low** |
-| Requires TS | any | any | **4.7+** | **4.7+** |
-
-**When to choose:**
-
-- **Subclass** — when you need `instanceof` checks, want to add methods, or need a distinct runtime type.
-- **Manual cast** — when TS < 4.7 is required, or you prefer zero dependencies (verbose but explicit).
-- **`typed()`** — the default choice: concise, zero runtime cost. Requires TS 4.7+.
-- **`createConstructor()`** — same as `typed()`, but the constructor must be callable without `new`
-  (e.g. factory patterns, functional-style code).
-
----
-
 #### Object / Key Utilities
 
 | Function | Description |
@@ -313,6 +277,7 @@ const evt = PersistentCacheEvent("evict", { detail: { records }, target: this })
 | `keyOf<T>(key)` | Returns a property name literal narrowed to `keyof T`. No object required — useful for building typed key references |
 | `nameOf<T>(f)` | Extracts a property name from a lambda `x => x.prop` at runtime via `Proxy` |
 | `entry(obj, name, caseInsensitive?)` | Looks up a key (optionally case-insensitive) and returns `[resolvedKey, value]` |
+| `getPrototypes(obj)` | Returns the prototype chain as an array, from the object's direct prototype up to (but not including) `null` |
 
 ```ts
 keysOf({ a: 1, b: 2 })          // => ["a", "b"] typed as ("a" | "b")[]
@@ -370,6 +335,35 @@ combinePropertyPath(["server", "port"])       // => '["server"]["port"]'
 | `toReadOnly<T>(obj, throwOnSet?)` | Deep read-only proxy; silently ignores writes (or throws if `throwOnSet: true`). Toggle with the `[$lock]` symbol |
 | `createDeepProxy<T>(target, handler)` | Deep-change proxy: `handler.set` and `handler.deleteProperty` receive the full `DeepPropertyKey` path |
 
+```ts
+// proxify — lazy proxy that re-evaluates source on every get/set
+let config = { theme: 'dark' };
+const proxy = proxify(() => config);
+proxy.theme;           // => 'dark'
+config = { theme: 'light' };
+proxy.theme;           // => 'light' — picks up the new object
+
+// toReadOnly — deep read-only proxy (writes silently ignored by default)
+const opts = toReadOnly({ server: { port: 3000 } });
+opts.server.port;      // => 3000
+opts.server.port = 80; // silently ignored
+                       // pass true as second arg to throw on write attempts instead
+
+// createDeepProxy — intercept deep mutations with the full property path
+const state = createDeepProxy({ user: { name: 'Alice' } }, {
+    set(target, path, value) {
+        console.log('set', path.map(String).join('.'), '=', value);
+        return true;
+    },
+    deleteProperty(target, path) {
+        console.log('deleted', path.map(String).join('.'));
+        return true;
+    },
+});
+state.user.name = 'Bob';  // logs: "set user.name = Bob"
+delete state.user.name;   // logs: "deleted user.name"
+```
+
 ---
 
 #### JSON Utilities
@@ -405,6 +399,309 @@ getEnumValue(Color, "Purple", Color.Red) // => 0 (default)
 
 ---
 
+#### Comparison: 4 ways to bind a generic constructor
+
+All four examples produce a bound alias for `StructEvent<PersistentCacheEventStruct, PersistentCache>`.
+
+**1. Subclass**
+
+```ts
+class PersistentCacheEvent
+    extends StructEvent<PersistentCacheEventStruct, PersistentCache> {}
+```
+
+**2. Manual cast**
+
+```ts
+type PersistentCacheEvent = StructEvent<PersistentCacheEventStruct, PersistentCache>;
+const PersistentCacheEvent = StructEvent as new (
+    ...args: ConstructorParameters<typeof StructEvent<PersistentCacheEventStruct, PersistentCache>>
+) => PersistentCacheEvent;
+```
+
+**3. `typed()` + Instantiation Expression** *(recommended)*
+
+```ts
+const PersistentCacheEvent = typed(StructEvent<PersistentCacheEventStruct, PersistentCache>);
+const evt = new PersistentCacheEvent("evict", { detail: { records }, target: this });
+```
+
+**4. `createConstructor()` — callable without `new`**
+
+```ts
+const PersistentCacheEvent = createConstructor(StructEvent<PersistentCacheEventStruct, PersistentCache>);
+const evt = PersistentCacheEvent("evict", { detail: { records }, target: this }); // no new
+```
+
+---
+
+**Feature comparison**
+
+| | Subclass | Manual cast | `typed()` | `createConstructor()` |
+|---|:---:|:---:|:---:|:---:|
+| Runtime overhead | new class | none | **none** | wrapper function |
+| `new` required | yes | yes | yes | **no** |
+| `instanceof` | **yes** | no | no | no |
+| Can add methods | **yes** | no | no | no |
+| Verbosity | medium | **high** | **low** | **low** |
+| Requires TS | any | any | **4.7+** | **4.7+** |
+
+**When to choose:**
+
+- **Subclass** — when you need `instanceof` checks, want to add methods, or need a distinct runtime type.
+- **Manual cast** — when TS < 4.7 is required, or you prefer zero dependencies (verbose but explicit).
+- **`typed()`** — the default choice: concise, zero runtime cost. Requires TS 4.7+.
+- **`createConstructor()`** — same as `typed()`, but the constructor must be callable without `new`
+  (e.g. factory patterns, functional-style code).
+
+---
+
+### stringCore — Locale-Aware String Utilities
+
+**Import:** `@actdim/utico/stringCore`
+
+Locale-aware string comparison and search utilities built on `Intl.Collator`. All functions accept an optional `locale` parameter (defaults to `navigator.language`). Non-string inputs fall back to reference equality or a default collator instead of throwing.
+
+#### Functions
+
+| Function | Description |
+|----------|-------------|
+| `equals(strA, strB, ignoreCase?, locale?)` | Returns `true` when strings are equal. Case-sensitive by default. Uses `Intl.Collator` for locale-correct comparison. |
+| `compare(strA, strB, ignoreCase?, locale?)` | Returns a negative, zero, or positive number — same contract as `Array.prototype.sort`. |
+| `ciCompare(strA, strB, locale?)` | Case-insensitive `compare`. Uses `sensitivity: "accent"` when available, falls back to `toLocaleUpperCase`. |
+| `ciStartsWith(str, searchStr, locale?)` | Case-insensitive `String.prototype.startsWith`. Returns `false` for non-string inputs. |
+| `ciEndsWith(str, searchStr, locale?)` | Case-insensitive `String.prototype.endsWith`. Returns `false` for non-string inputs. |
+| `ciIndexOf(str, searchStr, locale?)` | Case-insensitive `String.prototype.indexOf`. Returns `-1` for non-string inputs or no match. |
+| `ciIncludes(str, searchStr, locale?)` | Case-insensitive `String.prototype.includes`. Returns `false` for non-string inputs. |
+
+#### Usage Examples
+
+```typescript
+import { equals, compare, ciCompare, ciStartsWith, ciEndsWith, ciIndexOf, ciIncludes } from '@actdim/utico/stringCore';
+
+// equals
+equals('Hello', 'hello')              // false (case-sensitive)
+equals('Hello', 'hello', true)        // true  (case-insensitive)
+equals('café', 'CAFÉ', true, 'fr')   // true  (locale-aware)
+
+// compare — for sorting
+['banana', 'Apple', 'cherry'].sort((a, b) => compare(a, b, true));
+// => ['Apple', 'banana', 'cherry']
+
+// ciStartsWith / ciEndsWith
+ciStartsWith('Hello World', 'hello') // true
+ciEndsWith('Hello World', 'WORLD')   // true
+
+// ciIndexOf / ciIncludes
+ciIndexOf('Hello World', 'WORLD')    // 6
+ciIncludes('Hello World', 'WORLD')   // true
+ciIncludes('Hello World', 'xyz')     // false
+```
+
+---
+
+### metadata — Property Metadata
+
+**Import:** `@actdim/utico/metadata`
+
+A lightweight property metadata system backed by `WeakMap`. Attach arbitrary named slots of metadata to class properties via the `@metadata` decorator or the imperative API. Metadata is resolved through the prototype chain, so subclasses automatically inherit base-class metadata.
+
+#### Functions
+
+| Function | Description |
+|----------|-------------|
+| `metadata(value, slotName)` | Property decorator factory. Attaches `value` to the `slotName` slot of the decorated property. |
+| `getPropertyMetadata<T>(target, propertyName, slotName?)` | Reads metadata for a property. If `slotName` is omitted, returns all slots for that property. Walks the prototype chain. |
+| `updatePropertyMetadata(target, propertyName, value, slotName)` | Imperative equivalent of `@metadata`. |
+| `getPropertyMetadataItem(metadata, obj)` | Low-level: resolves a `WeakMap` entry for `obj` by walking its prototype chain. |
+
+#### Usage Examples
+
+```typescript
+import { metadata, getPropertyMetadata, updatePropertyMetadata } from '@actdim/utico/metadata';
+
+// --- Decorator API ---
+
+class Article {
+    @metadata('Title of the article', 'label')
+    @metadata(true, 'required')
+    title: string;
+
+    @metadata('Publication date', 'label')
+    publishedAt: number;
+}
+
+const article = new Article();
+
+getPropertyMetadata(article, 'title', 'label')    // => 'Title of the article'
+getPropertyMetadata(article, 'title', 'required') // => true
+getPropertyMetadata(article, 'title')             // => { label: '...', required: true }
+
+// --- Imperative API ---
+
+class Product {
+    price: number;
+}
+
+updatePropertyMetadata(Product.prototype, 'price', 'EUR price in cents', 'label');
+getPropertyMetadata(new Product(), 'price', 'label'); // => 'EUR price in cents'
+
+// --- Prototype chain inheritance ---
+
+class SpecialArticle extends Article {}
+
+// SpecialArticle inherits metadata from Article.prototype
+getPropertyMetadata(new SpecialArticle(), 'title', 'label'); // => 'Title of the article'
+```
+
+---
+
+### decorators — Property Decorators
+
+**Import:** `@actdim/utico/decorators`
+
+| Decorator | Description |
+|-----------|-------------|
+| `@nonEnumerable` | Makes a class property non-enumerable: it is hidden from `Object.keys`, `for...in`, `JSON.stringify`, and spread (`{...obj}`), while remaining fully readable and writable via direct access. |
+
+#### Usage Examples
+
+```typescript
+import { nonEnumerable } from '@actdim/utico/decorators';
+
+class User {
+    name: string;
+
+    @nonEnumerable
+    passwordHash: string;
+}
+
+const user = new User();
+user.name = 'Alice';
+user.passwordHash = 'abc123';
+
+Object.keys(user)       // => ['name']  — passwordHash is hidden
+JSON.stringify(user)    // => '{"name":"Alice"}'
+user.passwordHash       // => 'abc123'  — still directly accessible
+```
+
+> **How it works:** the decorator replaces the property with an accessor on the prototype. On the first assignment, the accessor redefines the property as a non-enumerable own value on the specific instance, so subsequent reads are direct (no getter overhead).
+
+---
+
+### dateTimeDataFormat — Date/Time Serialisation
+
+**Import:** `@actdim/utico/dateTimeDataFormat`
+
+**Peer dependency:** `luxon ^3`
+
+Date/time conversion utilities built on [Luxon](https://moment.github.io/luxon/).  
+The module converts values from string/number/`Date`/`DateTime`, tracks precision, and exports values either as local ISO (without suffix) or UTC ISO (`Z` suffix).
+
+#### Core Types
+
+| Type | Description |
+|------|-------------|
+| `DateTimeNumberFormat` | Numeric input/output format: Unix ms, Unix seconds, OADate |
+| `DateTimePrecision` | `auto \| date \| minute \| second \| millisecond` |
+| `DateTimeKind` | `local \| utc` |
+| `DateTimeStringInterpretation` | `auto \| local \| utc` for parsing strings |
+| `DateTimeExportInterpretation` | `original \| local \| utc \| match` for `exportToString` |
+| `DateTimeExtended` | Luxon `DateTime` with extra fields: `precision`, `exportToString(...)` |
+| `ToDateTimeOptions` | Options for `toDateTime(...)` |
+| `DateTimeTransport` | `{ serialize(...), deserialize(...) }` pair for wire transport |
+
+#### `DateTimeNumberFormat`
+
+| Member | Description |
+|--------|-------------|
+| `UnixTimeMilliseconds` | Default — milliseconds since Unix epoch |
+| `UnixTimeSeconds` | Seconds since Unix epoch |
+| `OADate` | Microsoft OLE Automation date (fractional days since 1899-12-30) |
+
+#### Functions
+
+| Function | Description |
+|----------|-------------|
+| `toDateTime(source, options?)` | Converts `string \| number \| Date \| DateTime` to `DateTimeExtended` |
+| `getDateTimeFromString(value, format?, precision?, interpretAs?)` | Parses string using explicit format or ISO |
+| `getDateTimeFromNumber(value, numberFormat?, interpretAs?, precision?)` | Parses number into `DateTimeExtended` |
+| `getDateTimeNumber(dt, numberFormat?)` | Converts `DateTime`/`DateTimeExtended` to number |
+| `isDateTimeExtended(obj)` | Type guard for `DateTimeExtended` |
+
+#### Ready-to-use transports
+
+| Transport | Serialize | Deserialize |
+|-----------|-----------|-------------|
+| `invariantLocalDateTimeTransport` | local ISO without zone suffix | strings as auto, numbers as local Unix seconds |
+| `utcDateTimeTransport` | UTC ISO with `Z` suffix | strings as auto, numbers as UTC Unix seconds |
+
+#### Usage Examples
+
+```typescript
+import {
+  toDateTime,
+  getDateTimeFromString,
+  getDateTimeFromNumber,
+  getDateTimeNumber,
+  DateTimeKind,
+  DateTimePrecision,
+  DateTimeNumberFormat,
+  DateTimeStringInterpretation,
+  DateTimeExportInterpretation,
+  invariantLocalDateTimeTransport,
+  utcDateTimeTransport
+} from '@actdim/utico/dateTimeDataFormat';
+
+// Parse from string (ISO auto-detect)
+const a = toDateTime("2024-03-15T10:30:45.123");
+
+// Parse from custom string format
+const b = toDateTime("03/15/2024", { stringFormat: "MM/dd/yyyy" });
+
+// Parse from number
+const c = getDateTimeFromNumber(1710496245000, DateTimeNumberFormat.UnixTimeMilliseconds);
+
+// Parse string and force interpretation as UTC
+const d = getDateTimeFromString(
+  "2024-03-15T10:30:45.123",
+  undefined,
+  DateTimePrecision.Auto,
+  DateTimeStringInterpretation.Utc
+);
+
+// Export as ISO local (without zone suffix)
+a.exportToString(DateTimeKind.Local); // "2024-03-15T..."
+
+// Export as ISO UTC (with Z)
+a.exportToString(DateTimeKind.Utc);   // "2024-03-15T...Z"
+
+// Export with explicit interpretation
+a.exportToString(
+  DateTimeKind.Local,
+  DateTimeExportInterpretation.Local
+);
+
+// Precision truncation
+const minute = getDateTimeFromString(
+  "2024-03-15T10:30:45.123",
+  "yyyy-MM-dd'T'HH:mm:ss.SSS",
+  DateTimePrecision.Minute
+);
+minute.second;      // 0
+minute.millisecond; // 0
+
+// Number conversion back
+getDateTimeNumber(a, DateTimeNumberFormat.UnixTimeSeconds);
+
+// Transport helpers
+invariantLocalDateTimeTransport.serialize(a); // local string
+utcDateTimeTransport.serialize(a);            // UTC string with Z
+utcDateTimeTransport.serialize(null);         // null
+```
+
+---
+
 ### StructEvent — Typed DOM Events
 
 **Import:** `@actdim/utico/structEvent`
@@ -502,8 +799,8 @@ const PersistentCacheEvent = typed(StructEvent<PersistentCacheEventStruct, Persi
 const cache = await PersistentCache.open("my-cache");
 
 cache.addEventListener("evict", (e) => {
-    // e.detail  → { records: CacheMetadataRecord[] }   (typed)
-    // e.target  → PersistentCache                       (typed)
+    // e.detail  -> { records: CacheMetadataRecord[] }   (typed)
+    // e.target  -> PersistentCache                       (typed)
     console.log("Evicted records:", e.detail.records);
 });
 ```
@@ -525,9 +822,17 @@ Track the execution state of promises and functions — useful for loading indic
 | Type                      | Description                                                      |
 | ------------------------- | ---------------------------------------------------------------- |
 | `PromiseStatus`           | `"pending" \| "fulfilled" \| "rejected"`                         |
-| `WatchablePromise<T>`     | `PromiseLike<T>` extended with `status`, `settled`, and `result` |
+| `WatchablePromise<T>`     | `PromiseLike<T>` with observable state fields (see below)        |
 | `WatchableFunc<TArgs, T>` | Function extended with an `executing` flag                       |
 
+`WatchablePromise<T>` adds three read-only fields to the underlying promise:
+
+| Field      | Type            | Description                                                                 |
+| ---------- | --------------- | --------------------------------------------------------------------------- |
+| `status`   | `PromiseStatus` | `"pending"` immediately; becomes `"fulfilled"` or `"rejected"` when settled |
+| `settled`  | `boolean`       | Computed getter — `true` once `status` is no longer `"pending"`             |
+| `result`   | `T \| undefined`| The resolved value after fulfillment; `undefined` after rejection           |
+
 #### Functions
 
 | Function      | Signature                                         | Description                                   |
@@ -714,6 +1019,8 @@ The main entry point for structured persistence. Key features:
 | `getOrSet<TValue>(metadata, factory)` | Get existing or create via factory |
 | `bulkGet<TValue>(keys)` | Get multiple items |
 | `bulkSet<TValue>(metadataRecords, dataRecords)` | Insert multiple items |
+| `update<TValue>(key, metadataChanges, valueChanges?)` | Patch fields of a single item by key; returns count of records modified (0 if key not found) |
+| `bulkUpdate(metadataChangeSets, dataChangeSets?)` | Patch fields of multiple items; each change set is `{ key, changes: KeyPathValueMap<T> }` |
 | `delete(key)` | Delete an item |
 | `bulkDelete(keys)` | Delete multiple items |
 | `clear()` | Delete all items |
@@ -788,6 +1095,15 @@ const items = await store.bulkGet<{ x: number }>(['item:1', 'item:2']);
 await store.delete('user:42');
 await store.bulkDelete(['item:1', 'item:2']);
 await store.clear();
+
+// Patch individual fields without rewriting the whole record
+await store.update('user:42', { tags: ['admin', 'verified'] });
+
+// Patch multiple records in one transaction
+await store.bulkUpdate([
+  { key: 'item:1', changes: { tags: ['sale'] } },
+  { key: 'item:2', changes: { tags: ['new'] } },
+]);
 ```
 
 ```typescript
@@ -833,6 +1149,129 @@ const page = await store
 
 ---
 
+### cache — Persistent Cache
+
+**Imports:**
+
+- `@actdim/utico/cache/persistentCache` — `PersistentCache`, `CacheOptions`, `PersistentCacheOptions`
+- `@actdim/utico/cache/cacheContracts` — `CacheMetadataRecord`
+
+Built on top of the `store` module. Adds expiration semantics (TTL, absolute expiration, sliding expiration) and a background cleanup job that evicts expired entries automatically.
+
+#### Types
+
+| Type | Description |
+|------|-------------|
+| `CacheMetadataRecord` | Extends `MetadataRecord` with `slidingExpiration`, `absoluteExpiration`, and `expiresAt` |
+| `CacheOptions` | Per-entry expiration options (see below) |
+| `PersistentCacheOptions` | Cache-level options: `cleanupTimeout` (ms between background cleanup runs) |
+| `CacheEvictionEvent` | `{ records: CacheMetadataRecord[] }` — payload of the `"evict"` event |
+
+#### `CacheOptions`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `slidingExpiration` | `number` (ms) | Extends `expiresAt` by this duration on every `get()`. Recommended: combined with `absoluteExpiration` as a cap. |
+| `absoluteExpiration` | `Date \| number` | Hard deadline — `expiresAt` is never pushed past this value. |
+| `ttl` | `number \| { seconds?, minutes?, hours? }` | Sets `absoluteExpiration` relative to the creation time. |
+
+#### Static Methods
+
+| Method | Description |
+|--------|-------------|
+| `PersistentCache.open(name, options?)` | Open or create a named cache. Returns a `PersistentCache` instance. |
+| `PersistentCache.exists(name)` | Check if a named cache database exists. |
+| `PersistentCache.delete(name)` | Delete a named cache database. |
+
+#### Instance Methods
+
+| Method | Description |
+|--------|-------------|
+| `get<TValue>(key)` | Get an item and update `accessedAt` (and `expiresAt` if `slidingExpiration` is set). |
+| `set(metadata, value, options)` | Create or overwrite an item with expiration options. Auto-generates a UUID key if `metadata.key` is absent. |
+| `getOrSet(metadata, factory, options)` | Return the existing item or create it via `factory`. `metadata.key` is required. |
+| `bulkGet<TValue>(keys)` | Get multiple items by key. |
+| `bulkSet(metadataRecords, dataRecords, optionsProvider)` | Insert multiple items. `optionsProvider` is called per-record to produce `CacheOptions`. |
+| `contains(key)` | Check if a key exists. |
+| `getKeys()` | Return all stored keys. |
+| `delete(key)` | Delete a single item. |
+| `bulkDelete(keys)` | Delete multiple items. |
+| `clear()` | Delete all items. |
+| `deleteExpired(ts?)` | Evict entries whose `expiresAt < ts` (defaults to `Date.now()`). Fires the `"evict"` event if anything was removed. |
+| `[Symbol.dispose]()` | Cancel the background cleanup timer and close the database. |
+
+#### Events
+
+`PersistentCache` extends `StructEventTarget`. Subscribe with `addEventListener`.
+
+| Event | Detail type | Description |
+|-------|-------------|-------------|
+| `"evict"` | `{ records: CacheMetadataRecord[] }` | Fired after `deleteExpired` removes at least one entry. |
+
+#### Usage Examples
+
+```typescript
+import { PersistentCache } from '@actdim/utico/cache/persistentCache';
+
+// --- Open a cache ---
+
+const cache = await PersistentCache.open('my-cache');
+
+// --- set / get ---
+
+await cache.set({ key: 'user:42' }, { name: 'Alice' }, {});
+
+const item = await cache.get<{ name: string }>('user:42');
+item.metadata.key        // 'user:42'
+item.metadata.createdAt  // timestamp set automatically
+item.data.value.name     // 'Alice'
+
+// --- Auto-generated key ---
+
+const meta = {};                         // no key provided
+await cache.set(meta, { x: 1 }, {});
+meta.key;                                // UUID filled in by set()
+
+// --- getOrSet ---
+
+const item2 = await cache.getOrSet(
+    { key: 'session:abc' },
+    () => ({ token: crypto.randomUUID() }),
+    {}
+);
+
+// --- Sliding expiration (renewed on every get) ---
+
+await cache.set({ key: 'live' }, 'data', { slidingExpiration: 30_000 });
+// expiresAt = now + 30 s; reset to now + 30 s on each get()
+
+// --- Sliding expiration with absolute cap ---
+
+await cache.set({ key: 'bounded' }, 'data', {
+    slidingExpiration: 5 * 60_000,          // renew up to 5 min on each get
+    absoluteExpiration: Date.now() + 3_600_000, // but never past 1 hour from now
+});
+
+// --- Manual eviction ---
+
+await cache.deleteExpired();   // uses Date.now()
+await cache.deleteExpired(Date.now() + 60_000); // treat everything expiring in the next minute as expired
+
+// --- Eviction event ---
+
+cache.addEventListener('evict', (e) => {
+    console.log('Evicted:', e.detail.records.map(r => r.key));
+});
+
+// --- Cleanup ---
+
+cache[Symbol.dispose]();   // stops background timer, closes DB
+// or:
+using c = await PersistentCache.open('temp');   // auto-disposed at block exit (TS 5.2+)
+```
+
+---
+
 ## License
 
 Proprietary — © Pavel Borodaev