@hotfusion/modeller 0.0.1 → 0.0.3

package/docs/CORE.md

@@ -0,0 +1,191 @@
+# Core Layer
+
+`Core` is the in-memory data primitive. It holds documents, validates them against a schema, supports indexed lookups, mingo queries, and an optional persistence adapter. Everything in this doc is inherited by `Model`, so you can ignore Core if you only ever use `Model` — but understanding it explains where the behavior comes from.
+
+> [← Back to README](../README.md)
+
+---
+
+## Table of Contents
+
+- [Schema](#schema)
+- [Validator](#validator)
+- [CRUD primitives](#crud-primitives)
+- [Indexes](#indexes)
+- [Adapter](#adapter)
+- [Trash](#trash)
+
+---
+
+## Schema
+
+Schemas are JSON Schema (AJV-compatible) plus a few Modeller-specific keywords:
+
+| Keyword     | Effect                                                                  |
+|-------------|-------------------------------------------------------------------------|
+| `unique`    | Enforces uniqueness across all documents on `insert` / `update`.        |
+| `private`   | Field stripped from read responses unless `{ private: true }` is set.   |
+| `index`     | Builds an in-memory index on the field for fast lookups.                |
+| `protected` | Reserved for transport-layer protection (consumed by `Server`).         |
+| `hidden`    | Hint for client rendering. Not enforced.                                 |
+| `default`   | Standard JSON Schema default.                                            |
+| `model`     | Async FK-style validation against another model by id.                  |
+
+### `$ref` resolution
+
+`$ref` resolves against `$defs` / `definitions` first, then against any `schemes` passed to the constructor (via `$id` match).
+
+A `$ref` may also carry a query string:
+
+```
+"someModel?key=_id&label=name&search=name,email&columns=name,role&min=1&max=5&unique"
+```
+
+This rewrites the property into a model reference with display metadata (`key`, `label`, `search`, `columns`) — used by client tooling to render pickers. For `type: 'array'`, `min` / `max` / `unique` become `minItems` / `maxItems` / `uniqueItemProperties`.
+
+### Inspecting the schema
+
+```ts
+model.getSchema();                   // public — strips `private` fields
+model.getSchema({ private: true });  // full
+```
+
+---
+
+## Validator
+
+AJV with `allErrors`, `strict: false`, `ajv-formats`, and `ajv-errors`. Two custom formats are registered:
+
+- `phone` — `+?[0-9 \-()]{7,10}`
+- `password` — at least 8 chars, mixed case, digit, symbol
+
+And one custom keyword:
+
+- `model` (async) — value must reference an existing document in the named model. Used for FK-style references.
+
+```ts
+properties: {
+    ownerId: { type: 'string', model: 'users.email' }
+}
+```
+
+---
+
+## CRUD primitives
+
+All CRUD methods are async. They throw `{ code, ... }` on failure (see [Errors](./ERRORS.md)).
+
+### `insert(key?, ...patches, opts?)`
+
+Merges `key` and any patch objects into a single document, validates, assigns a BSON `ObjectId`, and stores it.
+
+```ts
+await users.insert({ email: 'a@b.com' }, { name: 'Alex' });
+await users.insert({ email: 'admin@b.com' }, { role: 'admin' }, { private: true });
+```
+
+Returns the inserted document. `private: true` includes `private` fields in the response.
+
+### `update(key, updates, opts?)`
+
+Finds a document by `key` (mingo query), shallow-merges `updates`, re-validates, and saves.
+
+```ts
+await users.update({ _id }, { name: 'Alex H.' });
+```
+
+Returns the merged document, or `null` if no match.
+
+### `delete(key)`
+
+Removes the matching document. If an adapter is configured and `trash` is not disabled, the document is moved to the trash bin.
+
+```ts
+await users.delete({ _id });   // → { _id }  or  null
+```
+
+### `get(key, opts?)`
+
+Returns a single document or `null`.
+
+```ts
+await users.get({ email: 'a@b.com' });
+await users.get({ _id }, { private: true });
+```
+
+### `list(query?, opts?)`
+
+Paginated, **exact-match** mingo query.
+
+```ts
+await users.list({ role: 'admin' }, { start: 0, count: 25, private: false });
+```
+
+Default `count` is 10.
+
+### `find(query?, opts?)`
+
+Like `list`, but **strings match as case-insensitive substrings**. Non-string values match exactly. Returns an array.
+
+```ts
+await users.find({ name: 'al' }, { max: 10 });
+// → [{ name: 'Alex' }, { name: 'Albert' }, ...]
+```
+
+Default `max` is 10.
+
+> **`list` vs `find`** — `list` is for paginated, exact-match queries (admin views, dashboards). `find` is for autocomplete and search. `list` fires hooks; `find` does not.
+
+---
+
+## Indexes
+
+Any property with `index: <number>` in its schema gets a per-field hash index built and maintained automatically. Indexes are used internally to keep large collections fast.
+
+```ts
+properties: {
+    email : { type: 'string', index: 1 }
+}
+```
+
+---
+
+## Adapter
+
+Models are in-memory by default. Provide an `Adapter` subclass to persist on every write and rehydrate on `pull()`.
+
+```ts
+import { Adapter, Model } from '@hotfusion/modeller';
+
+class FileAdapter extends Adapter {
+    async sync(id, doc) { /* called on every write */ }
+    async pull()        { /* return array of docs to load */ return []; }
+}
+
+const users = new Model('users', schema, { adapter: FileAdapter });
+await users.pull();   // hydrate before serving traffic
+```
+
+The Adapter contract:
+
+```ts
+class Adapter {
+    constructor(id: string) {}
+    async sync(id: string, doc: { _id: string, ... }): Promise<void>;
+    async pull(): Promise<any[]>;
+}
+```
+
+Modeller calls `sync` on every `insert`, `update`, and `delete` — including trash moves. `pull()` is called manually when you want to rehydrate.
+
+---
+
+## Trash
+
+When an adapter is configured, deleted documents go to an in-memory trash bin keyed by `_id`. The bin supports `restore`, `has`, `get`, `permanentDelete`, `empty`, `size`, `list({ start, count })`, `find(query)`, `findAll(query)`. Every trash operation also calls `adapter.sync('trash', doc)` so it can be persisted.
+
+Pass `{ trash: false }` in model options to disable.
+
+---
+
+> **Next:** [Model layer →](./MODEL.md)

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)