@hotfusion/modeller 0.0.13 → 0.0.16

package/docs/MODEL.md

@@ -1,296 +0,0 @@
-# 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

@@ -1,182 +0,0 @@
-# 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

@@ -1,88 +0,0 @@
-# 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)

package/docs/UTILITIES.md

@@ -1,111 +0,0 @@
-# Utilities
-
-Helpers exported from `@hotfusion/modeller` and from `src/utils`.
-
-> [← Back to README](../README.md)
-
----
-
-## Public exports
-
-| Export    | Purpose                                                                |
-|-----------|------------------------------------------------------------------------|
-| `Bundler` | Rollup-based bundler for shipping client code (TS, JSON, LESS, terser).|
-| `KeyGen`  | System-wide secret generator.                                          |
-| `Adapter` | Base class for persistence — extend to plug in a backing store.        |
-
----
-
-## `Bundler`
-
-A Rollup wrapper preconfigured for the Modeller stack. Bundles TypeScript, inlines JSON, compiles LESS via `rollup-plugin-postcss`, supports `@rollup/plugin-replace` for build-time substitutions, and minifies with terser.
-
-```ts
-import { Bundler } from '@hotfusion/modeller';
-
-const result = await Bundler.bundle({
-    entry  : 'src/client/index.ts',
-    output : 'dist/client.js'
-});
-```
-
-Use it for shipping client bundles served by the [Server layer](./SERVER.md), or for any pre-built artifact you want to expose at runtime.
-
----
-
-## `KeyGen`
-
-```ts
-import { KeyGen } from '@hotfusion/modeller';
-
-const secret = KeyGen.getSystemSecret();              // → hex string
-const bytes  = KeyGen.getSystemSecret('uint8Array');  // → Uint8Array
-```
-
-`getSystemSecret()` returns a stable 32-byte secret. On first call it generates one and caches it to disk (`_secret.key`); subsequent calls return the same value. Use it as the JWT signing key, the session secret, or wherever a stable per-installation secret is needed.
-
-`KeyGen.generateSecret(false)` returns a fresh random secret each time — use this for one-off keys (per-document encryption, single-use tokens).
-
----
-
-## `Adapter`
-
-Base class for persistence. See the full contract in the [Core layer doc](./CORE.md#adapter).
-
-```ts
-import { Adapter } from '@hotfusion/modeller';
-
-class MyAdapter extends Adapter {
-    async sync(id, doc) { /* persist */ }
-    async pull()        { /* return docs */ return []; }
-}
-```
-
----
-
-## Internal utilities
-
-These live in `src/utils` and aren't re-exported from the package root, but are stable and safe to import directly.
-
-### `encrypt` / `decrypt`
-
-AES-256-GCM wrappers using a `Uint8Array` secret.
-
-```ts
-import { encrypt, decrypt } from '@hotfusion/modeller/dist/utils/encryption';
-
-const hash  = await encrypt('plaintext', secretBytes);
-const plain = await decrypt(hash,        secretBytes);
-```
-
-Pair with `KeyGen.getSystemSecret('uint8Array')` for the secret.
-
-### `signJWT` / `decodeJWT`
-
-`jose`-backed JWT helpers.
-
-```ts
-import { signJWT }   from '@hotfusion/modeller/dist/utils/sign-jwt';
-import { decodeJWT } from '@hotfusion/modeller/dist/utils/decode-jwt';
-
-const token  = await signJWT(payload, secret, { exp: '1h' });
-const claims = decodeJWT(token);
-```
-
-### `request`
-
-Minimal `fetch` wrapper used internally by the connector. Returns the parsed body, throws on non-2xx.
-
-```ts
-import { request } from '@hotfusion/modeller/dist/utils/request';
-
-const data = await request('https://api.example.com/x', { method: 'GET' });
-```
-
-### `ObjectCollection`
-
-A typed `Map`-with-extras used internally for keyed collections. Useful when you need a `Map` plus filtering / iteration helpers.
-
----
-
-> **Related:** [Core →](./CORE.md) · [Errors →](./ERRORS.md)