tiny-essentials 1.28.19 → 1.29.1

package/docs/v1/libs/storage/TinySetMapDatabase.md

@@ -0,0 +1,478 @@
+# 🗃️ TinySetMapDatabase
+
+> Persistent `Set` and `Map` collections backed by **IndexedDB** — with a tiny, promise-based API.
+
+`TinySetMapDatabase` gives you two familiar data structures (`Set` and `Map`) that survive page reloads, service-worker restarts, and browser sessions. You get the ergonomics of the standard collections, plus a migration system that keeps your schema under control.
+
+---
+
+## 📖 Table of Contents
+
+1. [✨ Why TinySetMapDatabase?](#-why-tinysetmapdatabase)
+2. [📦 Requirements](#-requirements)
+3. [🚀 Quick Start](#-quick-start)
+4. [🧠 Core Concepts](#-core-concepts)
+5. [🏗️ API Reference](#️-api-reference)
+   - [`TinySetMapDatabase`](#tinysetmapdatabase)
+   - [`TinySetDb`](#tinysetdb)
+   - [`TinyMapDb](#tinymapdb)
+   - [`TinyTableDb` (base class)](#tinytabledb-base-class)
+6. [🧩 Migrations](#-migrations)
+7. [✅ Validators](#-validators)
+8. [🍳 Recipes](#-recipes)
+9. [🛠️ Service Worker Notes](#️-service-worker-notes)
+10. [🐛 Error Reference](#-error-reference)
+11. [❓ FAQ](#-faq)
+
+---
+
+## ✨ Why TinySetMapDatabase?
+
+- 🔒 **Persistent** — Data lives in IndexedDB, so it survives reloads and restarts.
+- 🧩 **Familiar API** — `add`, `get`, `set`, `delete`, `has`, `forEach`, `for await...of`.
+- ⚡ **Synchronous reads, async writes** — An in-memory cache makes reads instant.
+- 🧱 **Schema migrations built in** — Version your database with a plain array.
+- 🧵 **Serialized writes** — Every write goes through a queue, so you never corrupt your store.
+
+---
+
+## 📦 Requirements
+
+- A runtime with **IndexedDB** (browsers, Web Workers, Service Workers).
+- **ES2022+** (private class fields, `??=`, async generators).
+
+---
+
+## 🚀 Quick Start
+
+```js
+import { TinySetMapDatabase } from 'tiny-essentials/libs/storage/TinySetMapDatabase';
+
+// 1. Describe your schema as a list of migrations.
+const migrations = [
+  {
+    create: [
+      'visited-pages', // shorthand: a Set of strings
+      { name: 'settings', type: 'map' }, // a Map of string -> any
+    ],
+  },
+];
+
+// 2. Open the database.
+const db = new TinySetMapDatabase('my-app', migrations);
+
+// 3. Wait until every table is hydrated.
+await db.ready;
+
+// 4. Use your tables.
+const pages = db.tableSet('visited-pages');
+await pages.add('/home');
+await pages.add('/about');
+
+const settings = db.tableMap('settings');
+await settings.set('theme', 'dark');
+
+console.log(await pages.toArray()); // ['/home', '/about']
+console.log(await settings.get('theme')); // 'dark'
+```
+
+---
+
+## 🧠 Core Concepts
+
+| Concept | What it means |
+| --- | --- |
+| **Table** | A single IndexedDB object store. It is either a `Set` or a `Map`. |
+| **Migration** | One entry in the migrations array. Its position defines its version (1-based). |
+| **Hydration** | The one-time process of loading every persisted record into memory. |
+| **Cache** | An in-memory `Set` or `Map` that mirrors the store for fast reads. |
+| **Write queue** | A `TinyPromiseQueue` that serializes all writes to the object store. |
+| **Action queue** | A `TinyPromiseQueue` that serializes all cache mutations. |
+
+> 💡 **Rule of thumb:** reads hit the cache, writes go through the queue and reach IndexedDB.
+
+---
+
+## 🏗️ API Reference
+
+### `TinySetMapDatabase`
+
+The entry point. It owns the IndexedDB connection and every table.
+
+#### `new TinySetMapDatabase(name, migrations)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Name of the IndexedDB database. |
+| `migrations` | `TinyDatabaseMigration[]` | Ordered schema history. Length = database version. |
+
+**Throws**
+
+- `TypeError` — if `name` is not a non-empty string.
+- `TypeError` — if `migrations` is not a non-empty array.
+- `TypeError` — if a migration is invalid.
+- `Error` — if a table is created twice without being dropped in between.
+
+---
+
+#### `db.name` → `string`
+
+The database name.
+
+#### `db.version` → `number`
+
+The current schema version (equal to `migrations.length`).
+
+#### `db.tableNames` → `string[]`
+
+Every table name declared by the migrations.
+
+#### `db.ready` → `Promise<void>`
+
+Resolves once the connection is open **and** every table is hydrated.
+
+```js
+await db.ready;
+```
+
+#### `db.tableSet(name)` → `TinySetDb`
+
+Returns a `Set`-like table.
+
+- **Throws** `TypeError` if `name` is not a non-empty string.
+- **Throws** `RangeError` if the table was not declared.
+- **Throws** `Error` if the table is not a Set.
+
+#### `db.tableMap(name)` → `TinyMapDb`
+
+Returns a `Map`-like table.
+
+- **Throws** `TypeError` if `name` is not a non-empty string.
+- **Throws** `RangeError` if the table was not declared.
+- **Throws** `Error` if the table is not a Map.
+
+#### `db.has(name)` → `boolean`
+
+Returns `true` when the table exists.
+
+#### `await db.close()`
+
+Closes the underlying IndexedDB connection.
+
+---
+
+### `TinySetDb`
+
+A persistent `Set<Value>`. Every value must be a non-empty string (an `IDBValidKey`).
+
+#### `new TinySetDb({ storeName, openDatabase, validate? })`
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `storeName` | `string` | Name of the object store. |
+| `openDatabase` | `() => Promise<IDBDatabase>` | Resolves with the shared connection. |
+| `validate` | `(value) => boolean \| null` | Optional predicate. Return `false` to reject. |
+
+#### `set.size` → `number`
+
+Number of values in the in-memory cache.
+
+#### `await set.has(value)` → `boolean`
+
+Checks whether `value` is stored.
+
+#### `await set.add(value)` → `boolean`
+
+Adds a value. Returns `true` when it was added, `false` when it already existed.
+
+#### `await set.delete(value)` → `boolean`
+
+Removes a value. Returns `true` when it existed.
+
+#### `await set.clear()` → `void`
+
+Removes every value from both the cache and the store.
+
+#### `await set.toArray()` → `Value[]`
+
+Returns a snapshot array.
+
+#### `await set.toJSON()` → `Value[]`
+
+Serialization hook used by `JSON.stringify`.
+
+#### `set.values()` / `set.keys()` → `AsyncGenerator<Value>`
+
+Iterates over every value.
+
+#### `set.entries()` → `AsyncGenerator<[Value, Value]>`
+
+Iterates over `[value, value]` pairs (mirrors `Set.prototype.entries`).
+
+#### `set[Symbol.asyncIterator]()`
+
+Alias for `values()`, so you can use `for await...of`.
+
+#### `await set.forEach(callbackFn, thisArg?)`
+
+Runs `callbackFn(value, value, set)` for every value.
+
+#### Set algebra
+
+All of these return a **new native `Set`** and accept a `TinySetDb`, a native `Set`, or an array.
+
+| Method | Description |
+| --- | --- |
+| `union(...sources)` | Values in this set **or** in any source. |
+| `intersection(other)` | Values in both. |
+| `difference(other)` | Values in this set but not in `other`. |
+| `symmetricDifference(other)` | Values in exactly one of the two. |
+| `isSubsetOf(other)` | `true` when every value here exists in `other`. |
+| `isSupersetOf(other)` | `true` when every value of `other` exists here. |
+| `isDisjointFrom(other)` | `true` when they share no values. |
+
+```js
+const a = new Set(['apple', 'banana']);
+const b = new Set(['banana', 'cherry']);
+
+await set.union(a, b);              // Set { 'apple', 'banana', 'cherry' }
+await set.intersection(a);          // Set { 'banana' }
+await set.difference(a);            // Set { 'cherry' }
+await set.symmetricDifference(a);   // Set { 'apple', 'cherry' }
+await set.isSubsetOf(a);            // false
+await set.isDisjointFrom(a);        // false
+```
+
+---
+
+### `TinyMapDb`
+
+A persistent `Map<Key, Value>`. Keys must be non-empty strings.
+
+#### `new TinyMapDb({ storeName, openDatabase, validate? })`
+
+Same options as `TinySetDb`, but `validate` receives `(key, value)`.
+
+#### `map.size` → `number`
+
+Number of entries in the in-memory cache.
+
+#### `await map.has(key)` → `boolean`
+
+#### `await map.get(key)` → `Value | undefined`
+
+#### `await map.set(key, value)` → `this`
+
+Binds a value to a key. Returns the map, so you can chain.
+
+#### `await map.delete(key)` → `boolean`
+
+#### `await map.clear()` → `void`
+
+#### `await map.toArray()` → `Array<[Key, Value]>`
+
+#### `await map.toJSON()` → `Array<[Key, Value]>`
+
+#### `map.keys()` / `map.values()` / `map.entries()`
+
+Async generators.
+
+#### `map[Symbol.asyncIterator]()`
+
+Alias for `entries()`.
+
+#### `await map.forEach(callbackFn, thisArg?)`
+
+Runs `callbackFn(value, key, map)` for every entry.
+
+---
+
+### `TinyTableDb` (base class)
+
+You normally do **not** instantiate this class directly. It is the shared plumbing for `TinySetDb` and `TinyMapDb`.
+
+If you want to build your own table type, extend it and implement `_load(records)`.
+
+| Member | Description |
+| --- | --- |
+| `get storeName()` | Name of the object store. |
+| `get isReady()` | `true` after hydration. |
+| `hydrate()` | Loads the cache once. Safe to call many times. |
+| `_action(operation)` | Runs an operation with exclusive access to the cache. |
+| `_write(operation)` | Runs an operation with exclusive access to the store. |
+| `_persist(record)` | Persists a single record. |
+| `_remove(key)` | Deletes a single record. |
+| `_clear()` | Deletes every record. |
+| `_load(records)` | **Abstract.** Must be implemented by subclasses. |
+
+---
+
+## 🧩 Migrations
+
+A migration is a plain object:
+
+```ts
+type TinyDatabaseMigration = {
+  create?: (string | {
+    name: string;
+    type: 'set' | 'map';
+    validate?: (key: any, value?: any) => boolean;
+  })[];
+  delete?: string[];
+};
+```
+
+- The **version** of a migration is its **1-based index** in the array.
+- The **database version** is `migrations.length`.
+- To change a table's key path, `delete` it and `create` it again in the same migration.
+
+### Example: adding a table in v2
+
+```js
+const migrations = [
+  // v1
+  { create: ['visited-pages'] },
+
+  // v2 — add a settings map
+  {
+    create: [{ name: 'settings', type: 'map' }],
+  },
+
+  // v3 — drop a table and recreate it as a map
+  {
+    delete: ['visited-pages'],
+    create: [{ name: 'visited-pages', type: 'map' }],
+  },
+];
+```
+
+> ⚠️ **Never reorder or remove migrations.** Their position *is* the version number. Appending is the only safe operation.
+
+---
+
+## ✅ Validators
+
+A validator is a predicate that runs **before** a write reaches the store. Return a falsy value to reject the write with a `TypeError`.
+
+```js
+const migrations = [
+  {
+    create: [
+      {
+        name: 'emails',
+        type: 'set',
+        validate: (value) => value.includes('@'),
+      },
+      {
+        name: 'users',
+        type: 'map',
+        validate: (key, value) => typeof value === 'object' && value !== null,
+      },
+    ],
+  },
+];
+
+const db = new TinySetMapDatabase('app', migrations);
+const emails = db.tableSet('emails');
+
+await emails.add('not-an-email'); // ❌ TypeError
+await emails.add('me@example.com'); // ✅
+```
+
+> 💡 The validator that wins is the one from the **latest migration that creates the table**.
+
+---
+
+## 🍳 Recipes
+
+### 🔁 Iterate over a set
+
+```js
+for await (const page of db.tableSet('visited-pages')) {
+  console.log(page);
+}
+```
+
+### 📦 Serialize a table
+
+```js
+const json = JSON.stringify(await db.tableMap('settings'));
+```
+
+### 🧹 Wipe a table
+
+```js
+await db.tableSet('visited-pages').clear();
+```
+
+### 🔍 Check before writing
+
+```js
+const pages = db.tableSet('visited-pages');
+if (!(await pages.has('/home'))) {
+  await pages.add('/home');
+}
+```
+
+### 🧮 Set algebra across tables
+
+```js
+const a = db.tableSet('a');
+const b = db.tableSet('b');
+
+const common = await a.intersection(b);
+console.log(`Shared values: ${[...common].join(', ')}`);
+```
+
+---
+
+## 🛠️ Service Worker Notes
+
+`TinySetMapDatabase` is designed to be created **once** per service worker lifetime:
+
+```js
+let database;
+
+self.addEventListener('install', () => {
+  database = new TinySetMapDatabase('my-app', migrations);
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(database.ready);
+});
+```
+
+- The connection is opened lazily and reused.
+- `onversionchange` closes the connection automatically, so a new tab can upgrade the schema.
+- Every write is queued, so concurrent `add`/`set` calls are safe.
+
+---
+
+## 🐛 Error Reference
+
+| Error | When it happens |
+| --- | --- |
+| `TypeError` | A string argument is empty, a validator rejects a value, or an option has the wrong type. |
+| `RangeError` | You asked for a table that was never declared. |
+| `ReferenceError` | `indexedDB` is not available in the current environment. |
+| `Error` | A table is created twice, or a table has the wrong type. |
+
+---
+
+## ❓ FAQ
+
+**Does it work outside the browser?**
+Only where `indexedDB` exists. In Node.js, provide a shim such as `fake-indexeddb`.
+
+**Are reads async?**
+Yes, all public methods return a `Promise`. The cache makes them fast, not synchronous.
+
+**Can I use non-string keys?**
+No. Keys must be non-empty strings, because they are used as the object store key path.
+
+**What happens if I forget to `await db.ready`?**
+Every method calls `hydrate()` internally, so it is safe — but awaiting `db.ready` once at startup avoids a small delay on the first call.
+
+**Can I have two databases with the same name?**
+Yes, but they will share the same IndexedDB database. Use different names for isolation.
+