@kedem/okdb 1.0.0

package/docs/plugins.md

@@ -0,0 +1,144 @@
+# Plugins
+
+Plugins are first-class addons that extend OKDB before it opens. They integrate into the lifecycle cleanly: registered before `open()`, started after `open()`, stopped before `close()`.
+
+---
+
+## Registering a plugin
+
+```javascript
+const okdb = new OKDB('./db');
+
+okdb.plugins.register(MyPlugin, {
+    /* options */
+});
+
+await okdb.open();
+```
+
+Plugins must be registered **before** `okdb.open()`. Attempting to register after open throws `INVALID_STATE`.
+
+---
+
+## Writing a plugin
+
+A plugin module is a plain object with a `name`, an optional `requires` list, and a `register` function that returns an instance.
+
+```javascript
+// my-plugin.js
+module.exports = {
+    name: 'my-plugin',
+
+    // Other plugin names that must be registered first
+    requires: [],
+
+    // Called synchronously during okdb.plugins.register().
+    // Must NOT do IO. Returns the plugin instance.
+    register(okdb, options) {
+        // Attach routes, listen to events, etc.
+        okdb.http.get('/api/my-plugin/ping', async (req, res) => {
+            res.json({ ok: true });
+        });
+
+        // The returned object becomes the instance
+        return {
+            async start(okdb) {
+                // Called after okdb.open() — IO is allowed here
+                console.log('my-plugin started');
+            },
+            async stop(okdb) {
+                // Called before okdb.close() — clean up everything
+                console.log('my-plugin stopped');
+            },
+        };
+    },
+};
+```
+
+```javascript
+const MyPlugin = require('./my-plugin');
+okdb.plugins.register(MyPlugin, {
+    /* options passed to register() */
+});
+await okdb.open();
+```
+
+After registration, `okdb.my-plugin` is set to the instance object — so the plugin becomes a property on `okdb`:
+
+```javascript
+okdb['my-plugin']; // → the instance returned by register()
+```
+
+:::note
+Plugin name must not conflict with existing OKDB properties (`env`, `put`, `get`, `http`, etc.). Registration throws `PLUGIN_NAME_CONFLICT` if there's a clash.
+:::
+
+---
+
+## Lifecycle contract
+
+| Phase                     | Hook  | IO allowed | Purpose                                       |
+| ------------------------- | ----- | ---------- | --------------------------------------------- |
+| `register(okdb, options)` | sync  | **no**     | Attach routes, event listeners, declare types |
+| `instance.start(okdb)`    | async | **yes**    | Start servers, timers, workers                |
+| `instance.stop(okdb)`     | async | **yes**    | Stop everything started in `start()`          |
+
+If any plugin's `start()` throws, all already-started plugins are stopped in reverse order before the error propagates.
+
+---
+
+## Plugin dependencies
+
+Use `requires` to declare that another plugin must be registered first:
+
+```javascript
+module.exports = {
+    name: 'payments',
+    requires: ['auth'],   // 'auth' plugin must be registered before 'payments'
+    register(okdb, options) { ... },
+};
+```
+
+OKDB checks this at registration time and throws `PLUGIN_DEPENDENCY_MISSING` if the dependency isn't registered yet.
+
+---
+
+## Example: type initializer plugin
+
+A common pattern is a plugin that ensures types and indexes exist at startup:
+
+```javascript
+module.exports = {
+    name: 'schema',
+    register(okdb, options) {
+        return {
+            async start(okdb) {
+                await okdb.ensureType('users', {
+                    indexes: [['email'], ['role', 'createdAt']],
+                });
+                await okdb.ensureType('sessions', {
+                    indexes: [['userId'], ['expiresAt']],
+                });
+                console.log('[schema] types ready');
+            },
+            async stop() {},
+        };
+    },
+};
+```
+
+---
+
+## Listing registered plugins
+
+```javascript
+const names = okdb.plugins._plugins.map((p) => p.module.name);
+// e.g. ['schema', 'auth', 'payments']
+```
+
+The `okdb.info` response also includes the plugin list:
+
+```javascript
+const info = await fetch('/api/info').then((r) => r.json());
+info.plugins; // → ['schema', 'auth', 'payments']
+```

package/docs/querying.md

@@ -0,0 +1,204 @@
+# Querying
+
+OKDB provides a layered query model: fast synchronous reads by key, ordered range scans, index-narrowed scans, and MongoDB-style in-process filtering.
+
+---
+
+## Single record reads
+
+```javascript
+// Returns value or undefined
+const user = okdb.get('users', 'alice');
+
+// Returns { value, version } or undefined
+const entry = okdb.getEntry('users', 'alice');
+
+// Multiple keys at once — returns an array in the same order (undefined for missing)
+const [alice, bob] = okdb.getMany('users', ['alice', 'bob']);
+```
+
+All reads are **synchronous**. LMDB maps the database file directly into process memory; there's no async I/O, no network call, no serialisation beyond a single decode.
+
+---
+
+## Range scans
+
+Range scans return **lazy LMDB iterables**. They are cursor-backed and produce `{ key, value, version }` entries.
+
+```javascript
+// All records in default order (key-lexicographic)
+for (const { key, value } of okdb.getRange('users')) {
+    console.log(key, value.name);
+}
+
+// Bounded range
+for (const { key, value } of okdb.getRange('users', {
+    start: 'a',   // inclusive lower bound
+    end:   'b',   // inclusive upper bound
+    limit: 100,
+    reverse: false,
+})) { ... }
+```
+
+Convenience iterables for when you only need one dimension:
+
+```javascript
+// Keys only
+for (const key of okdb.getKeys('users')) { ... }
+
+// Values only
+for (const value of okdb.getValues('users')) { ... }
+
+// Lexicographic prefix
+for (const { key, value } of okdb.getByPrefix('users', 'team:')) { ... }
+
+// Record count (no scan — read from index metadata)
+const total = okdb.getCount('users');
+```
+
+:::warning Cursor invalidation
+Lazy iterables are invalidated the moment a write transaction opens on the same environment. If you `await` anything between iterating and finishing the cursor, materialise first:
+
+```javascript
+const all = Array.from(okdb.getValues('users'));
+await doSomethingAsync();
+// safe to use `all` here
+```
+
+:::
+
+---
+
+## MongoDB-style query
+
+`query()` applies a [sift](https://github.com/crcn/sift.js) filter over a range scan. Sift supports the full MongoDB query operator syntax.
+
+```javascript
+// Basic equality
+const admins = okdb.query('users', { role: 'admin' });
+
+// Comparison operators
+const seniors = okdb.query('users', { age: { $gte: 65 } });
+
+// $in / $nin
+const staff = okdb.query('users', { role: { $in: ['admin', 'moderator'] } });
+
+// Nested fields
+const verified = okdb.query('users', { 'profile.verified': true });
+
+// Logical operators
+const results = okdb.query('users', {
+    $and: [{ role: 'member' }, { createdAt: { $gt: Date.now() - 7 * 86400_000 } }],
+});
+```
+
+### Narrowing with an index
+
+Without an index hint, `query()` scans every record. With one, it uses the index to iterate only matching entries:
+
+```javascript
+// Only scans records where role === 'admin'
+const admins = okdb.query(
+    'users',
+    { role: 'admin', age: { $gte: 30 } },
+    {
+        index: ['role'],
+        prefix: ['admin'],
+    },
+);
+
+// With composite index: role + createdAt
+const recent = okdb.query(
+    'users',
+    { active: true },
+    {
+        index: ['role', 'createdAt'],
+        prefix: ['admin'],
+        reverse: true,
+        limit: 20,
+    },
+);
+```
+
+:::tip
+There is no query planner. If you pass `index`, OKDB uses it without cost analysis. Pick the most selective index for your query by hand.
+:::
+
+---
+
+## Index scans
+
+`byIndex` iterates entries in index order, returning `{ key, value, version, indexKey }`.
+
+```javascript
+// All records in order of the 'score' field
+for (const { key, value, indexKey } of okdb.byIndex('leaderboard', ['score'], { reverse: true, limit: 10 })) {
+    console.log(key, value.name, indexKey[0]);
+}
+
+// Exact prefix match: all articles by author 'alice'
+for (const { key, value } of okdb.byIndex('articles', ['author'], {
+    prefix: ['alice'],
+})) { ... }
+
+// Range on composite index: articles by 'alice' published in the last week
+const since = Date.now() - 7 * 86400_000;
+for (const { key, value } of okdb.byIndex('articles', ['author', 'publishedAt'], {
+    start:  ['alice', since],
+    end:    ['alice', Infinity],
+})) { ... }
+```
+
+### Options
+
+| Option              | Type    | Description                                       |
+| ------------------- | ------- | ------------------------------------------------- |
+| `prefix`            | `any[]` | Index entries must start with these values        |
+| `start`             | `any[]` | Inclusive lower bound (full index key)            |
+| `end`               | `any[]` | Inclusive upper bound                             |
+| `reverse`           | boolean | Scan in descending order                          |
+| `limit`             | number  | Maximum entries to return                         |
+| `offset`            | number  | Skip this many entries                            |
+| `includeViolations` | boolean | For unique indexes: include all violating entries |
+
+---
+
+## Geo query
+
+OKDB has a built-in geospatial index based on geohash. Register a geo index on a field that stores `{ lat, lon }` (or an `[lat, lon]` array):
+
+```javascript
+await okdb.registerIndex('places', ['location'], { type: 'geo', precision: 7 });
+
+// Store records with lat/lon
+await okdb.put('places', 'eiffel', { name: 'Eiffel Tower', location: { lat: 48.8584, lon: 2.2945 } });
+
+// Radius query — returns records within N metres of a point
+const nearby = okdb.geoQuery('places', 'location', {
+    lat: 48.8566,
+    lon: 2.3522,
+    radius: 5000, // metres
+});
+for (const { key, value, distance } of nearby) {
+    console.log(value.name, Math.round(distance), 'm');
+}
+```
+
+Internally, geohash prefix expansion covers the radius at the registered precision. Precision 7 gives ~76m cell size — good for city-level queries. For sub-10m accuracy, use precision 9.
+
+---
+
+## Range options reference
+
+Most scan methods accept the same range options bag:
+
+```typescript
+{
+    start?:   any;       // inclusive start key / index key
+    end?:     any;       // inclusive end key / index key
+    limit?:   number;    // max entries returned
+    offset?:  number;    // entries to skip
+    reverse?: boolean;   // descending order
+    prefix?:  any[];     // index prefix (byIndex / query only)
+}
+```