stonyx 0.2.3-alpha.8 → 0.2.3-alpha.80

package/docs/conventions/orm-conventions.md

@@ -1,190 +0,0 @@
-# ORM Conventions
-
-## Models
-
-Models define the data structure with attributes and relationships. One model per file in `models/`.
-
-**Property ordering:** `attr()` → `belongsTo()` / `hasMany()` → computed getters
-
-```js
-import { Model, attr, belongsTo, hasMany } from '@stonyx/orm';
-import { ANIMALS } from '../constants.js';
-
-export default class AnimalModel extends Model {
-  type = attr('animal');
-  age = attr('number');
-  size = attr('string');
-
-  owner = belongsTo('owner');
-  traits = hasMany('trait');
-
-  get tag() {
-    const { owner, size } = this;
-
-    if (!owner) {
-      return `Unowned ${size} ${ANIMALS[this.type]}`;
-    }
-
-    return `${owner.id}'s ${size} ${ANIMALS[this.type]}`;
-  }
-}
-```
-
-### Property Flattening
-
-Every property must resolve to a final data type — no passthrough objects. If an API returns a nested object, create a sub-model with `belongsTo` rather than storing the raw object.
-
-### Nested Models
-
-Use nested directories for `belongsTo` children:
-
-```
-models/
-  character.js
-  character/
-    relationship.js
-```
-
-## Serializers
-
-Serializers map raw external data to the model shape. One serializer per model in `serializers/`.
-
-The serializer has a single `map` property. It is responsible for mapping only, not fetching.
-
-```js
-import { Serializer } from '@stonyx/orm';
-
-const COLOR_TRAIT_MAP = {
-  'black': 2,
-  'white': 3,
-}
-
-export default class AnimalSerializer extends Serializer {
-  map = {
-    age: 'details.age',
-    size: 'details.c',
-    color: 'details.x',
-    owner: 'details.location.owner',
-
-    // Array value: [sourcePath, customHandler]
-    traits: ['details', ({ x:color }) => {
-      const traits = [{ id: 1, type: 'habitat', value: 'farm', category: 'physical' }];
-
-      const id = COLOR_TRAIT_MAP[color];
-      if (id) traits.push({ id, type: 'color', value: color, category: 'appearance' });
-
-      return traits;
-    }]
-  }
-}
-```
-
-### Clients vs Serializers
-
-- **Clients** fetch, decrypt, and provide raw data from external sources
-- **Serializers** map that raw data to the model shape
-
-Clients handle I/O; serializers handle structure. Never mix the two.
-
-## Access Control
-
-Access classes define which models they govern and implement an `access()` method. One access file per logical access boundary in `access/`.
-
-**Structure:** `models` property → `access()` method
-
-```js
-export default class GlobalAccess {
-  models = ['owner', 'animal', 'trait', 'category', 'phone-number'];
-
-  access(request) {
-    const { originalUrl: url } = request;
-
-    // Return false to deny
-    if (url.endsWith('/owners/angela')) return false;
-
-    // Return a filter function for conditional access
-    if (url.endsWith('/owners')) return record => record.id !== 'angela';
-    if (url.endsWith('/animals')) return record => record.owner !== 'angela';
-
-    // Return permission array for full access
-    return ['read', 'create', 'update', 'delete'];
-  }
-}
-```
-
-The `models` property accepts an array of model names, or `'*'` to match all models.
-
-`access()` return values:
-- `false` — deny access
-- `function` — filter function applied to response records
-- `string[]` — allowed operations (e.g., `['read', 'create', 'update', 'delete']`)
-
-## Transforms
-
-Transforms are default-exported functions (not classes) that convert values. One transform per model in `transforms/`.
-
-```js
-import { ANIMALS } from '../constants.js';
-
-const codeEnumMap = {}
-
-for (let i = 0; i < ANIMALS.length; i++) codeEnumMap[ANIMALS[i]] = i;
-
-export default function(value) {
-  return codeEnumMap[value] || 0;
-}
-```
-
-## Hooks
-
-Use `beforeHook` / `afterHook` from `@stonyx/orm/hooks`. Place hook files in `hooks/`.
-
-## DB Schema
-
-The database schema extends `Model` and uses `hasMany` for each collection:
-
-```js
-import { Model, hasMany } from '@stonyx/orm';
-
-export default class DBModel extends Model {
-  owners = hasMany('owner');
-  animals = hasMany('animal');
-  traits = hasMany('trait');
-  categories = hasMany('category');
-  phoneNumbers = hasMany('phone-number');
-}
-```
-
-Located at `config/db-schema.js`, referenced from `config/environment.js`.
-
-## Store
-
-The store is the in-memory data layer. Use it for internal app logic (not REST API consumers).
-
-```js
-import Orm, { store, createRecord, updateRecord } from '@stonyx/orm';
-
-// Read — sync, from memory (requires memory: true on model, which is the default)
-const record = store.get('animal', 1);
-const allAnimals = store.data.get('animals');
-
-// Read — async, queries DB if memory: false
-const record = await store.find('animal', 1);
-const all = await store.findAll('animal');
-
-// Create — adds to store and returns the record
-const animal = createRecord('animal', { type: 'dog', age: 3, owner: 'angela' });
-
-// Update — patches fields on an existing record
-updateRecord(animal, { age: 4 });
-
-// Delete
-store.remove('animal', 1);
-
-// Persist to disk — required when not using REST-triggered autosave
-await Orm.db.save();
-```
-
-**When to use `Orm.db.save()`**: The `autosave: 'onUpdate'` config only triggers on REST POST/PATCH/DELETE. When modifying data directly via `createRecord` / `updateRecord` in app code (not through REST), call `Orm.db.save()` explicitly to persist.
-
-**Store vs REST**: Use `store` for internal app logic (session tracking, state management). Use REST request handlers for external API consumers. Both operate on the same in-memory data.

package/docs/conventions/project-structure.md

@@ -1,105 +0,0 @@
-# Project Structure
-
-## Entry Point
-
-The application entry point is always `app.js` at the project root. This file exports a default class that initializes the application.
-
-```js
-import log from 'stonyx/log';
-
-export default class App {
-  constructor() {
-    if (App.instance) return App.instance;
-    App.instance = this;
-
-    this.ready = this.init();
-  }
-
-  async init() {
-    log.info('Initializing Application');
-    // Application setup here
-    log.info('Application has been initialized');
-  }
-}
-```
-
-## File Layout
-
-Flat file structure at root level — non-directory project files live at the project root.
-
-### Standard Directories
-
-| Directory | Purpose | When to create |
-|-----------|---------|----------------|
-| `config/` | Configuration files | Always |
-| `models/` | ORM model definitions | When using `@stonyx/orm` |
-| `serializers/` | Data serializers | When using `@stonyx/orm` |
-| `access/` | Access control definitions | When using `@stonyx/orm` |
-| `transforms/` | Value transforms | When using `@stonyx/orm` |
-| `hooks/` | Lifecycle hooks | When using `@stonyx/orm` |
-| `requests/` | REST request handlers | When using `@stonyx/rest-server` |
-| `crons/` | Scheduled tasks | When using `@stonyx/cron` |
-| `clients/` | External API clients | When fetching external data |
-| `test/`| Tests | Always |
-| `utils.js` or `utils/` | Project-specific reusable logic | As needed (never duplicate `@stonyx/utils`) |
-
-### Nested Model Directories
-
-Use nested directories under `models/` for `belongsTo` child models:
-
-```
-models/
-  character.js
-  character/
-    relationship.js
-```
-
-## Config Conventions
-
-### `config/environment.js`
-
-Destructure env vars at the top, apply defaults with `??`, export a plain object:
-
-```js
-const {
-  CORS_ORIGIN,
-  DB_FILE,
-  NODE_ENV,
-  REST_PORT,
-} = process.env;
-
-const environment = NODE_ENV ?? 'development';
-
-export default {
-  orm: {
-    db: {
-      file: DB_FILE ?? 'db.json',
-      schema: './config/db-schema.js'
-    }
-  },
-  restServer: {
-    origin: CORS_ORIGIN ?? '*',
-    port: REST_PORT ?? 3000
-  }
-}
-```
-
-**Do NOT re-declare module defaults.** Only include config values that differ from the module's built-in defaults.
-
-### `config/db-schema.js`
-
-Extends `Model` and uses `hasMany` to define each collection:
-
-```js
-import { Model, hasMany } from '@stonyx/orm';
-
-export default class DBModel extends Model {
-  owners = hasMany('owner');
-  animals = hasMany('animal');
-}
-```
-
-## Reference Projects
-
-- `smart-lock-backend/` — full example with REST, ORM, sockets, crons, hooks
-- `nextgoal-backend/` — example with models, transforms, filters, bot commands

package/docs/conventions/rest-conventions.md

@@ -1,96 +0,0 @@
-# REST Conventions
-
-## Request Classes
-
-One request class per file in `requests/`. Each class extends `Request` from `@stonyx/rest-server`.
-
-**Class ordering:** properties → `handlers` object → `auth()` hook → validation/middleware methods
-
-### Public Request (no auth)
-
-```js
-import { Request } from '@stonyx/rest-server';
-
-export default class PublicRequest extends Request {
-  testProp = 'stonyx';
-
-  handlers = {
-    get: {
-      '/': (_request, _state) => {
-        return { data: 'foo' };
-      },
-
-      '/url-params/:x/:y/:z': ({ params }, _state) => {
-        return params;
-      },
-
-      // Middleware chaining: [middlewareFn, handlerFn]
-      '/foo': [this.validationSuccessSample, (_request, state) => {
-        return { data: state };
-      }],
-
-      '/fail': [this.validationFailureSample, (_request, _state) => {
-        return { unreachable: 'response' };
-      }],
-    }
-  }
-
-  validationSuccessSample(_request, state) {
-    state.newProp = 'bar';
-  }
-
-  validationFailureSample() {
-    return 504; // returning a status code rejects the request
-  }
-}
-```
-
-### Private Request (with auth)
-
-```js
-import { Request } from '@stonyx/rest-server';
-
-export default class PrivateRequest extends Request {
-  handlers = {
-    get: {
-      '/success': (_request, _state) => {
-        return { data: 'foo' };
-      },
-
-      '/failure': (_request, _state) => {
-        return { data: 'foo' };
-      }
-    }
-  }
-
-  auth(request, _state) {
-    if (request.path === '/failure') return 505;
-  }
-}
-```
-
-## Key Patterns
-
-### `handlers` Object
-
-Keyed by HTTP method (`get`, `post`, `put`, `delete`), each containing route-to-handler mappings.
-
-Handler signature: `(request, state) => responseData`
-
-### Middleware Chaining
-
-Use `[middlewareFn, handlerFn]` arrays to chain middleware before a handler. The middleware function receives `(request, state)` and can:
-- Mutate `state` to pass data to the handler
-- Return a status code number to reject the request early
-
-### `auth()` Hook
-
-Runs before all handlers in the class. Return an error status code to reject the request. If `auth()` returns nothing (undefined), the request proceeds.
-
-### Route Parameters
-
-Express-style route params (`:param`) are available via `request.params`.
-
-### Binding
-
-Handler functions defined as arrow functions or class methods have access to `this` (the request class instance).

package/docs/conventions/testing-conventions.md

@@ -1,56 +0,0 @@
-# Testing Conventions
-
-## Directory Structure
-
-```
-test/
-  unit/
-  integration/
-  acceptance/
-  config/
-    environment.js    # test config overrides
-  sample/             # fixtures and mocks (alternative: test/mocks/)
-```
-
-## File Naming
-
-All test files use the `*-test.js` suffix: `animal-test.js`, `public-request-test.js`.
-
-## Test Framework
-
-- **QUnit** — test framework
-- **Sinon** — stubs, spies, and mocks
-
-Run tests with `stonyx test` (alias: `stonyx t`), which:
-1. Sets `NODE_ENV=test`
-2. Loads test setup (bootstrap with test config overrides)
-3. Runs QUnit against `test/**/*-test.js`
-
-## Test Config Overrides
-
-Place test-specific config at `test/config/environment.js`. Stonyx auto-merges these overrides when running in test mode.
-
-## Sample / Fixture Files
-
-Each stonyx module's `test/sample/` directory contains reference implementations. Mirror this structure in your project tests:
-
-- `test/sample/models/` — model fixtures
-- `test/sample/serializers/` — serializer fixtures
-- `test/sample/access/` — access control fixtures
-- `test/sample/transforms/` — transform fixtures
-- `test/sample/requests/` — request handler fixtures
-
-The file ordering in tests should mirror the sample files from each module's `test/sample/` directory.
-
-## Running Tests
-
-```bash
-# Run all tests
-stonyx test
-
-# Run specific test file
-stonyx test test/unit/animal-test.js
-
-# Run specific glob
-stonyx test "test/integration/**/*-test.js"
-```

package/docs/developing-modules.md

@@ -1,108 +0,0 @@
-# Developing Modules
-
-Guide for building custom Stonyx modules.
-
-## Package Setup
-
-Your module's `package.json` must include:
-
-```json
-{
-  "name": "@stonyx/my-module",
-  "keywords": ["stonyx-module"],
-  "main": "src/index.js"
-}
-```
-
-Add `stonyx-async` to keywords if your module requires asynchronous initialization.
-
-## Module Class
-
-Export a default class. Optionally define `init()`, `startup()`, and `shutdown()` methods:
-
-```js
-export default class MyModule {
-  // Called during module loading (async modules only)
-  async init() {
-    // Connect to services, load resources, etc.
-  }
-
-  // Called after ALL modules are initialized, before app entry runs
-  async startup() {
-    // Register routes, start listeners, etc.
-  }
-
-  // Called on SIGTERM/SIGINT, in reverse load order
-  async shutdown() {
-    // Close connections, flush data, etc.
-  }
-}
-```
-
-## Default Configuration
-
-Async modules must include `config/environment.js` with sensible defaults:
-
-```js
-export default {
-  logColor: 'cyan',
-  logMethod: 'myModule',
-  logTimestamp: true,
-  // Module-specific defaults...
-};
-```
-
-User project config is merged on top of these defaults.
-
-## Waiting for Other Modules
-
-If your module depends on another async module being ready:
-
-```js
-import { waitForModule } from 'stonyx';
-
-export default class MyModule {
-  async init() {
-    await waitForModule('rest-server');
-    // @stonyx/rest-server is now fully initialized
-  }
-}
-```
-
-Pass the module name without the `@stonyx/` prefix.
-
-## Standalone Development
-
-When running a module standalone (project path contains `stonyx-`), Stonyx auto-transforms the config structure. Your module's config is wrapped under its camelCase name:
-
-```js
-// If your module is @stonyx/rest-server and config is { port: 3000 }
-// Stonyx transforms it to: { restServer: { port: 3000 } }
-```
-
-## Custom CLI Commands
-
-Modules can register CLI commands by adding a `./commands` export:
-
-```json
-{
-  "exports": {
-    "./commands": "./src/commands.js"
-  }
-}
-```
-
-```js
-// src/commands.js
-export default {
-  'my-module:setup': {
-    description: 'Initialize module resources',
-    bootstrap: true,
-    run: async ({ args, cwd }) => {
-      // Command implementation
-    }
-  }
-};
-```
-
-Use namespaced command names (e.g., `my-module:setup`) to avoid conflicts with other modules. See [CLI](cli.md#module-commands) for details.

package/docs/index.md

@@ -1,15 +0,0 @@
-# Stonyx Documentation
-
-## Guides
-
-- [CLI](cli.md) — Commands, usage, and module-contributed commands
-- [Configuration](configuration.md) — Environment config, module config, and test overrides
-- [Modules](modules.md) — Module discovery, sync vs async, and official modules
-- [Lifecycle](lifecycle.md) — Startup/shutdown hooks and signal handling
-- [Logging](logging.md) — Color-coded logging via Chronicle
-- [Testing](testing.md) — Running tests, config overrides, and integration helpers
-- [Developing Modules](developing-modules.md) — Guide for building custom Stonyx modules
-
-## Reference
-
-- [API Reference](api.md) — Public exports and class documentation

package/docs/lifecycle.md

@@ -1,47 +0,0 @@
-# Lifecycle Hooks
-
-Stonyx modules can define `startup()` and `shutdown()` methods that run at specific points in the application lifecycle.
-
-## Startup Hooks
-
-Called sequentially (in module load order) after all modules have been initialized, right before your application entry point runs.
-
-```js
-export default class MyModule {
-  async startup() {
-    // Called after all modules are init'd, before app.js runs
-  }
-}
-```
-
-## Shutdown Hooks
-
-Called sequentially in **reverse** module load order when the process receives `SIGTERM` or `SIGINT`. Errors in one hook do not prevent other hooks from running.
-
-```js
-export default class MyModule {
-  async shutdown() {
-    // Clean up connections, flush buffers, etc.
-  }
-}
-```
-
-## Signal Handling
-
-The `stonyx serve` command registers signal handlers automatically:
-
-- **SIGTERM** — triggers shutdown hooks, then `process.exit(0)`
-- **SIGINT** — triggers shutdown hooks, then `process.exit(0)`
-
-Shutdown is idempotent — calling the handler multiple times only runs hooks once.
-
-## Using Lifecycle Hooks Directly
-
-For advanced use cases, the lifecycle functions are available as a public export:
-
-```js
-import { runStartupHooks, runShutdownHooks } from 'stonyx/lifecycle';
-
-await runStartupHooks(modules);   // Calls startup() on each module in order
-await runShutdownHooks(modules);  // Calls shutdown() on each module in reverse order
-```

package/docs/logging.md

@@ -1,52 +0,0 @@
-# Logging
-
-Stonyx provides centralized, color-coded logging via [Chronicle](https://github.com/abofs/chronicle).
-
-## Overview
-
-Every Stonyx instance creates a Chronicle logger with a default `title` log type (green). Modules and user services can register additional log types with custom colors.
-
-## Module Logs
-
-Modules that specify `logColor` in their configuration automatically get a Chronicle log type:
-
-```js
-// config/environment.js
-export default {
-  restServer: {
-    logColor: 'yellow',
-    logMethod: 'api',        // Optional — defaults to the config key name
-    logTimestamp: true,       // Optional — adds timestamps to log output
-  },
-};
-```
-
-This creates a `chronicle.api()` method that outputs in yellow with timestamps.
-
-## Custom Logs
-
-You can define logs for any class or service in your project — not just Stonyx modules:
-
-```js
-export default {
-  myWorker: {
-    logColor: 'cyan',
-    logMethod: 'worker',
-    logTimestamp: true,
-  },
-};
-```
-
-Any top-level config key with a `logColor` property will have a log type created automatically.
-
-## Accessing the Logger
-
-```js
-import log from 'stonyx/log';
-
-log.title('Application started');
-log.api('Request received');       // If restServer config defines logMethod: 'api'
-log.worker('Processing job');      // If myWorker config defines logMethod: 'worker'
-```
-
-The `stonyx/log` export is a live reference to the Chronicle instance. It will throw if accessed before Stonyx is initialized.