@hotfusion/modeller 0.0.2 → 0.0.3

package/docs/ERRORS.md

@@ -0,0 +1,90 @@
+# Errors
+
+All errors thrown by Modeller are plain objects with a `code` field. They aren't `Error` instances — catch them as plain objects and branch on `code`.
+
+> [← Back to README](../README.md)
+
+---
+
+## Error codes
+
+| Code                | Source                                          | Extra fields            |
+|---------------------|-------------------------------------------------|-------------------------|
+| `VALIDATION_ERROR`  | AJV failed on `insert` / `update` / event args. | `errors` (AJV errors[]) |
+| `UNIQUE_VIOLATION`  | A `unique` field collided.                      | `field`                 |
+| `METHOD_NOT_FOUND`  | `call('id', ...)` with unregistered id.         | `id`                    |
+| `UPLOAD_NOT_FOUND`  | `callUpload('id', ...)` with unregistered id.   | `id`                    |
+| `STREAM_NOT_FOUND`  | `callStream('id', ...)` with unregistered id.   | `id`                    |
+| `EVENT_NOT_FOUND`   | `subscription.dispatch('id', ...)` mismatch.    | `id`                    |
+
+---
+
+## Catching
+
+```ts
+try {
+    await users.insert({ email: 'bad' });
+} catch (err) {
+    switch (err.code) {
+        case 'VALIDATION_ERROR':
+            console.log('AJV errors:', err.errors);
+            break;
+        case 'UNIQUE_VIOLATION':
+            console.log('duplicate field:', err.field);
+            break;
+        default:
+            throw err;
+    }
+}
+```
+
+---
+
+## Validation error shape
+
+`VALIDATION_ERROR` carries the raw AJV error array on `errors`. Each entry has `instancePath`, `keyword`, `message`, `params`, and `schemaPath`.
+
+```ts
+{
+    code: 'VALIDATION_ERROR',
+    errors: [
+        {
+            instancePath : '/email',
+            keyword      : 'format',
+            message      : 'must match format "email"',
+            params       : { format: 'email' },
+            schemaPath   : '#/properties/email/format'
+        }
+    ]
+}
+```
+
+`ajv-errors` is enabled, so per-field custom messages declared via `errorMessage` in the schema show up in `message`.
+
+---
+
+## Hooks and errors
+
+A non-scheduled hook that throws aborts the operation. The thrown value is logged at `error` level via the [logger](./MODEL.md#logging) and re-thrown to the caller. Throw a plain object with a `code` to keep error handling consistent:
+
+```ts
+users.hook({
+    id: 'check-quota',
+    on: 'before:insert',
+    callback: async ({ data }) => {
+        if (await overQuota(data)) throw { code: 'QUOTA_EXCEEDED' };
+    }
+});
+```
+
+Scheduled hooks (those with `schedule: <ms>`) are fire-and-forget. Errors from them are logged but not propagated.
+
+---
+
+## Workers and errors
+
+Worker handler errors are caught and logged at `error` level. They never crash the interval — the worker keeps ticking. If you want a worker to stop on failure, call `model.stop('worker-id')` from inside the handler's catch block.
+
+---
+
+> **Related:** [Core →](./CORE.md) · [Model →](./MODEL.md)

package/docs/MODEL.md

@@ -0,0 +1,296 @@
+# Model Layer
+
+`Model extends Core`. Everything from the [Core layer](./CORE.md) is available on a `Model` instance — `insert`, `update`, `delete`, `get`, `list`, `find`, `getSchema`, `pull`. On top of that, `Model` adds the behavior surface: hooks, workers, methods, uploads, streams, events, subscriptions, logging, and extensions.
+
+> [← Back to README](../README.md)
+
+---
+
+## Table of Contents
+
+- [Hooks](#hooks)
+- [Workers](#workers)
+- [Methods](#methods)
+- [Uploads](#uploads)
+- [Streams](#streams)
+- [Events & Subscriptions](#events--subscriptions)
+- [Internal Event Emitter](#internal-event-emitter)
+- [Extensions](#extensions)
+- [Logging](#logging)
+
+---
+
+## Hooks
+
+Hooks run before or after a CRUD operation. They can short-circuit by throwing, mutate the payload, or perform side effects. Both sync and async callbacks are supported.
+
+```ts
+users.hook({
+    id       : 'normalize-email',
+    on       : 'before:insert',
+    callback : async ({ data }) => {
+        if (data?.email) data.email = data.email.toLowerCase();
+    }
+});
+
+users.hook({
+    id       : 'audit',
+    on       : ['after:insert', 'after:update', 'after:delete'],
+    callback : ({ operation, key, data }) => audit.log(operation, key, data)
+});
+
+users.unhook('normalize-email');
+```
+
+### Hook events
+
+| Event             | Payload fields                                |
+|-------------------|-----------------------------------------------|
+| `before:insert`   | `operation`, `timing`, `data`                 |
+| `after:insert`    | `operation`, `timing`, `data`, `key: { _id }` |
+| `before:update`   | `operation`, `timing`, `key`, `data`          |
+| `after:update`    | `operation`, `timing`, `key`, `data`          |
+| `before:delete`   | `operation`, `timing`, `key`                  |
+| `after:delete`    | `operation`, `timing`, `key`, `data`          |
+| `before:list`     | `operation`, `timing`, `data` (= query)       |
+| `after:list`      | `operation`, `timing`, `data` (= query)       |
+
+`get` and `find` do **not** fire hooks.
+
+### Scheduled hooks
+
+`schedule: <ms>` defers execution via `setTimeout`. Scheduled hooks are fire-and-forget — they don't block the operation and their errors aren't propagated.
+
+```ts
+users.hook({
+    id       : 'welcome-email',
+    on       : 'after:insert',
+    schedule : 5_000,
+    callback : ({ data }) => mailer.send(data.email, 'welcome')
+});
+```
+
+### Throwing from a hook
+
+A non-scheduled hook that throws aborts the operation. The error is logged at `error` level and re-thrown to the caller.
+
+---
+
+## Workers
+
+Workers are interval-based background tasks bound to the model. They can be **named** (managed individually) or **unsigned** (managed in bulk).
+
+```ts
+users.worker({
+    id        : 'sync',
+    interval  : 30_000,
+    immediate : true,         // run once on start, default true
+    handler   : async (model) => { await model.pull(); }
+});
+
+users.worker({ interval: 60_000, handler: () => cleanup() });   // unsigned
+```
+
+### Lifecycle
+
+```ts
+users.start();           // start all (named + unsigned)
+users.start('sync');     // start a specific named worker
+users.stop();            // stop all
+users.stop('sync');      // stop a specific named worker
+users.isRunning('sync'); // → boolean
+```
+
+Errors thrown inside a worker handler are caught and logged — they never crash the interval.
+
+---
+
+## Methods
+
+Methods are named, schemaless RPC-style operations. Use them for anything that doesn't fit the CRUD shape.
+
+```ts
+users.method({
+    id      : 'resetPassword',
+    handler : async ({ email, newPassword }, model, ctx) => {
+        const u = await model.get({ email });
+        if (!u) throw { code: 'NOT_FOUND' };
+        return model.update({ _id: u._id }, { password: newPassword });
+    }
+});
+
+await users.call('resetPassword', { email, newPassword }, ctx);
+users.getMethods();   // → ['resetPassword']
+```
+
+`call` throws `{ code: 'METHOD_NOT_FOUND', id }` if the method isn't registered.
+
+---
+
+## Uploads
+
+Uploads receive a `Buffer` plus a `fields` map (typically multipart form fields).
+
+```ts
+users.upload({
+    id      : 'avatar',
+    handler : async (file, fields, model) => {
+        const path = await storage.put(file, fields.filename);
+        return model.update({ _id: fields.userId }, { avatar: path });
+    }
+});
+
+await users.callUpload('avatar', buffer, { userId, filename: 'me.png' });
+users.getUploads();   // → ['avatar']
+```
+
+---
+
+## Streams
+
+Streams are similar to uploads but expect chunked `Buffer` data with arbitrary `meta`.
+
+```ts
+users.stream({
+    id      : 'import',
+    handler : async (chunk, meta, model) => {
+        for (const row of parseCsv(chunk)) await model.insert(row);
+    }
+});
+
+await users.callStream('import', chunk, { source: 'crm' });
+users.getStreams();   // → ['import']
+```
+
+---
+
+## Events & Subscriptions
+
+Events are named, schema-validated handlers that clients **subscribe to**. Where `method` is one-shot RPC, events are designed for fan-out to multiple subscribers, scoped by query.
+
+### Defining an event
+
+```ts
+users.event({
+    id     : 'roleChanged',
+    schema : {
+        type     : 'object',
+        required : ['_id', 'role'],
+        properties: {
+            _id  : { type: 'string' },
+            role : { type: 'string', enum: ['user', 'admin'] }
+        }
+    },
+    handler: async ({ _id, role }, model, ctx) => {
+        return model.update({ _id }, { role });
+    }
+});
+```
+
+If `schema` is set, args are validated before the handler runs. Validation errors throw `{ code: 'VALIDATION_ERROR', errors }`.
+
+### Subscribing
+
+A subscription is keyed by a normalized query — same query keys/values produce the same subscription instance.
+
+```ts
+const { subscription, subId } = users.subscribe({ role: 'admin' });
+
+subscription.on('publish', payload => {
+    console.log('admin update:', payload);
+});
+
+// shorthand — returns just the subscription
+const sub = users.subscription({ role: 'admin' });
+```
+
+### Dispatching an event
+
+`dispatch` validates args (if a schema is set) and runs the matching event handler.
+
+```ts
+await sub.dispatch('roleChanged', { _id, role: 'admin' }, ctx);
+```
+
+Throws `{ code: 'EVENT_NOT_FOUND', id }` if the event isn't registered.
+
+### Publishing to subscribers
+
+`publish` is your fan-out hook — it emits to every listener attached via `on('publish', ...)` for that subscription. The transport layer ([Server](./SERVER.md)) wires this into a Socket.IO room so browser clients receive it automatically.
+
+```ts
+sub.publish({ type: 'role-changed', _id, role: 'admin' });
+```
+
+A common pattern is calling `publish` from inside an `after:update` hook to notify everyone watching that slice of the model. See [Patterns](./PATTERNS.md).
+
+### Inspection / cleanup
+
+```ts
+sub.getEvents();                 // → ['roleChanged']
+users.unsubscribe({ role: 'admin' });
+```
+
+---
+
+## Internal Event Emitter
+
+Separate from the subscription system, every model is also an `EventEmitter`. CRUD operations emit on this emitter directly — useful for in-process listeners that don't need query scoping.
+
+```ts
+users.on('insert', doc => log('inserted', doc));
+users.on('update', ({ key, data }) => log('updated', key, data));
+users.on('delete', result => log('deleted', result));
+users.on('log',    entry => sink.write(entry));
+```
+
+`on`, `off`, `once`, `emit` are all available. Built-in events: `insert`, `update`, `delete`, `log`.
+
+---
+
+## Extensions
+
+Pass `extensions: [...]` in the constructor options to mount sub-models as named properties on the parent. The mount key is `extension.id`.
+
+```ts
+const ssh   = new Model('ssh',   sshSchema);
+const users = new Model('users', userSchema, { extensions: [ssh] });
+
+users.ssh.insert({ host: '...', port: 22, username: 'root' });
+users.getExtensions();   // → [Model('ssh')]
+```
+
+This is how Modeller composes namespaces — a `system` model with `system.ssh`, `system.docker`, `system.firewall` extensions, all addressable as `system.ssh.insert(...)`.
+
+---
+
+## Logging
+
+A built-in logger surfaces hook, worker, method, event, and CRUD activity.
+
+```ts
+const users = new Model('users', schema, {
+    level     : 'debug',     // 'debug' | 'info' | 'warn' | 'error' | 'silent'
+    timestamp : true,
+    features  : { hook: true, worker: true, method: true, event: false, crud: true },
+    onEntry   : entry => myLogger.log(entry)
+});
+```
+
+Or supply a custom adapter:
+
+```ts
+{ logAdapter: { log: entry => myStore.append(entry) } }
+```
+
+Listen on the model itself:
+
+```ts
+users.on('log', entry => sink.write(entry));
+```
+
+Each entry includes `level`, `feature`, `modelId`, `message`, `callSite`, `timestamp`, and optional `data`. `initial` is `true` for one-shot registration messages (e.g. "Hook registered"), `false` for runtime activity.
+
+---
+
+> **Next:** [Server layer →](./SERVER.md)

package/docs/PATTERNS.md

@@ -0,0 +1,182 @@
+# Common Patterns
+
+Recipes that show the [Core → Model → Server](../README.md) chain in action. Each pattern is small, self-contained, and reflects how the framework is meant to be composed.
+
+> [← Back to README](../README.md)
+
+---
+
+## Publish on update
+
+Notify every client subscribed to a slice of a model whenever a document in that slice changes. The `after:update` hook is the natural seam.
+
+```ts
+users.hook({
+    id: 'broadcast',
+    on: 'after:update',
+    callback: ({ key, data }) => {
+        users.subscription({ _id: key._id }).publish({ type: 'updated', data });
+    }
+});
+```
+
+The [Server layer](./SERVER.md) wires the subscription into a Socket.IO room, so every browser client subscribed to `{ _id }` receives the payload automatically.
+
+---
+
+## FK validation across models
+
+Use the async `model` keyword to require that a field references an existing document in another model.
+
+```ts
+const orders = new Model('orders', {
+    type: 'object',
+    properties: {
+        userId: { type: 'string', model: 'users.email' }
+    }
+}, { schemes: [users.getSchema()] });
+```
+
+`Validator` rejects an `insert` whose `userId` doesn't exist in the `users` model. See [Validator](./CORE.md#validator).
+
+---
+
+## Composing a system root via extensions
+
+`extensions` mounts sub-models as named properties on the parent — addressable as `parent.childId.method(...)`.
+
+```ts
+const ssh      = new Model('ssh',      sshSchema);
+const docker   = new Model('docker',   dockerSchema);
+const firewall = new Model('firewall', firewallSchema);
+
+const system = new Model('system', systemSchema, {
+    extensions: [ssh, docker, firewall]
+});
+
+await system.ssh.insert({ host: '...', port: 22, username: 'root' });
+await system.firewall.list();
+```
+
+This pattern is how Modeller composes namespaces. Each extension keeps its own hooks, workers, methods, events, and schema — they aren't merged, just mounted.
+
+See [Extensions](./MODEL.md#extensions).
+
+---
+
+## Background sync worker
+
+Reconcile in-memory state with an external source on an interval.
+
+```ts
+firewall.worker({
+    id       : 'sync-rules',
+    interval : 30_000,
+    handler  : async (model) => {
+        const live = await readLiveUFW();
+        for (const rule of live) {
+            const existing = await model.get({ id: rule.id });
+            if (!existing) await model.insert(rule);
+        }
+    }
+});
+
+firewall.start('sync-rules');
+```
+
+Errors inside the handler are logged but never crash the interval. See [Workers](./MODEL.md#workers).
+
+---
+
+## Quota / authorization in `before:insert`
+
+Throw from a `before:` hook to abort an operation.
+
+```ts
+users.hook({
+    id: 'check-quota',
+    on: 'before:insert',
+    callback: async ({ data }) => {
+        if (await overQuota(data.tenantId)) {
+            throw { code: 'QUOTA_EXCEEDED' };
+        }
+    }
+});
+```
+
+The thrown object propagates back to the caller of `insert()`. See [Errors](./ERRORS.md).
+
+---
+
+## Schedule a side effect after insert
+
+Send a welcome email five seconds after a user is created — without blocking the insert.
+
+```ts
+users.hook({
+    id       : 'welcome-email',
+    on       : 'after:insert',
+    schedule : 5_000,
+    callback : ({ data }) => mailer.send(data.email, 'welcome')
+});
+```
+
+`schedule` makes the hook fire-and-forget via `setTimeout`. Errors from scheduled hooks are logged but don't propagate.
+
+---
+
+## Persist with an adapter, hydrate on boot
+
+Wire an `Adapter` so writes are durable, then `pull()` once at startup.
+
+```ts
+class FileAdapter extends Adapter {
+    async sync(id, doc) { await fs.writeFile(`./data/${id}.json`, JSON.stringify(doc)); }
+    async pull()        { return JSON.parse(await fs.readFile('./data/users.json', 'utf8')); }
+}
+
+const users = new Model('users', schema, { adapter: FileAdapter });
+await users.pull();   // hydrate before serving traffic
+```
+
+See [Adapter](./CORE.md#adapter).
+
+---
+
+## Method as RPC, event as fan-out
+
+Two different shapes for "do something":
+
+- **Method** — one caller, one return value. Use for actions like `resetPassword`, `regenerateApiKey`.
+- **Event** — one or many callers via a subscription, validated args, multi-subscriber fan-out. Use when the action should also notify watchers.
+
+```ts
+// method — RPC
+users.method({ id: 'resetPassword', handler: async (...) => { /* ... */ } });
+
+// event — broadcasts via subscription
+users.event({ id: 'roleChanged', schema, handler: async (...) => { /* ... */ } });
+```
+
+If in doubt, start with a method. Promote to an event only when more than one consumer needs to know it happened.
+
+---
+
+## Listening in-process vs over the wire
+
+Two emitters live on every model. Use the right one for the job:
+
+- **`model.on('insert' | 'update' | 'delete' | 'log', ...)`** — in-process, no query scoping. Use for audit logs, metrics, internal indexers.
+- **`model.subscription(query).on('publish', ...)`** — query-scoped fan-out, designed to be bridged to clients via the [Server layer](./SERVER.md).
+
+```ts
+// in-process: every write
+users.on('update', ({ key, data }) => metrics.increment('users.updated'));
+
+// per-query: clients listening for admin changes
+users.subscription({ role: 'admin' }).on('publish', payload => doSomething(payload));
+```
+
+---
+
+> **Related:** [Model →](./MODEL.md) · [Errors →](./ERRORS.md)

package/docs/SERVER.md

@@ -0,0 +1,88 @@
+# Server Layer
+
+`Server` is a thin transport that exposes models over HTTP and WebSocket. The package abstracts the underlying Koa + Socket.IO + OIDC + busboy machinery — you don't interact with it directly.
+
+> [← Back to README](../README.md)
+
+---
+
+## The mental model
+
+- **Models in, HTTP + WS out.** Methods, uploads, streams, and events become endpoints.
+- **Subscriptions become rooms.** `subscription.publish(payload)` reaches every connected client subscribed to that query.
+- **A `/@metadata` endpoint** advertises every model, scope, operation, and event so clients can build typed proxies at runtime.
+- **Auth is OIDC + JWT.** Routes can opt in with `protected: true`.
+
+---
+
+## Quick example
+
+```ts
+import { Server, Model } from '@hotfusion/modeller';
+
+const server = new Server(3030, { domain: 'api', secret: process.env.SECRET });
+
+server.route({
+    method   : 'post',
+    path     : '/system/ping',
+    callback : async (ctx) => ({ ok: true, ts: Date.now() })
+});
+
+server.start();
+```
+
+---
+
+## Public methods
+
+| Method                                          | Purpose                                               |
+|-------------------------------------------------|-------------------------------------------------------|
+| `route({ method, path, callback, protected? })` | Register a custom HTTP route.                         |
+| `upload(path, handler)`                         | Multipart form-data endpoint, parsed into a Buffer.   |
+| `stream(handler)`                               | Single global handler for chunked socket uploads with resume. |
+| `setOIDCProviders(path, providers)`             | Wire OIDC providers under a base path.                |
+| `start()`                                       | Bind to the port, mount routes, start Socket.IO.      |
+
+The full HTTP/WS surface is generated from your models — you don't need to wire each operation manually.
+
+---
+
+## Server events
+
+```ts
+server.on('mounted',       (s)                 => console.log('listening'));
+server.on('connection',    ({ socket })        => /* socket.io connection */);
+server.on('request',       ({ ctx, flags })    => /* every HTTP request */);
+server.on('authenticated', ({ profile, provider, ctx, middleware }) => /* OIDC success */);
+server.on('provider',      ({ token, sid, session }) => /* token issued */);
+server.on('uploaded',      ({ file, buffer, resolve }) => resolve({ /* meta */ }));
+```
+
+| Event           | When it fires                                              |
+|-----------------|------------------------------------------------------------|
+| `mounted`       | After `start()` has bound the port and mounted routes.     |
+| `connection`    | A new Socket.IO client connects.                           |
+| `request`       | Every incoming HTTP request, with `protected` flag.        |
+| `authenticated` | OIDC profile successfully verified.                        |
+| `provider`      | A provider has issued a token; session is established.     |
+| `uploaded`      | A streamed upload finished assembling. Resolve with meta.  |
+
+---
+
+## Auth
+
+`{ protected: true }` on a route requires a valid `Authorization: Bearer <jwt>` header. The token is verified against the secret passed to the constructor (or auto-generated via `KeyGen.getSystemSecret()` if omitted).
+
+`setOIDCProviders` wires multiple OIDC providers under a base path. The server handles the redirect, callback, token exchange, and session creation. Listen to `authenticated` and `provider` to react to login.
+
+---
+
+## Scope
+
+This package is meant to be used as an abstraction. The Server layer intentionally keeps a narrow surface so consumers don't need to know Koa, Socket.IO, OIDC client config, or busboy internals.
+
+If you need to dig deeper — custom middleware, custom socket rooms, OIDC introspection — read `src/server.ts` directly. The public API documented here is the contract.
+
+---
+
+> **Related:** [Utilities →](./UTILITIES.md) · [Errors →](./ERRORS.md)