stonyx 0.2.3-beta.9 → 0.2.3-beta.90

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.

package/docs/modules.md

@@ -1,78 +0,0 @@
-# Module System
-
-Stonyx uses a plug-and-play module architecture. Modules are automatically detected, loaded, and initialized at startup.
-
-## How Modules Are Discovered
-
-Stonyx scans your project's `devDependencies` for packages prefixed with `@stonyx/`. Each matching package must include the `stonyx-module` keyword in its `package.json` to be loaded.
-
-```json
-{
-  "name": "@stonyx/my-module",
-  "keywords": ["stonyx-module"],
-  "main": "src/index.js"
-}
-```
-
-## Sync vs Async Modules
-
-### Sync Modules
-
-Modules with only the `stonyx-module` keyword are treated as synchronous. They are instantiated but their promise resolves immediately — no init phase is awaited.
-
-### Async Modules
-
-Modules that also include the `stonyx-async` keyword require initialization before they're ready:
-
-```json
-{
-  "keywords": ["stonyx-module", "stonyx-async"]
-}
-```
-
-Async modules **must** include a `config/environment.js` with default configuration. This is merged with the user's project config before initialization.
-
-Async modules can define an `init()` method that Stonyx awaits:
-
-```js
-export default class MyModule {
-  async init() {
-    // Connect to database, start server, etc.
-  }
-}
-```
-
-All module `init()` calls run concurrently via `Promise.all`.
-
-## Module Lifecycle
-
-1. **Discovery** — scan `devDependencies` for `@stonyx/*` packages
-2. **Validation** — verify `stonyx-module` keyword exists
-3. **Config merge** — async module defaults merged with user config
-4. **Log setup** — module-specific Chronicle log created if `logColor` is set
-5. **Instantiation** — module class is `new`'d
-6. **Initialization** — `init()` called (async modules only)
-7. **Startup hooks** — `startup()` called after all modules init (see [Lifecycle](lifecycle.md))
-8. **Shutdown hooks** — `shutdown()` called on process exit (see [Lifecycle](lifecycle.md))
-
-## waitForModule
-
-For submodule developers who need to ensure another async module is ready:
-
-```js
-import { waitForModule } from 'stonyx';
-
-await waitForModule('rest-server'); // Waits for @stonyx/rest-server
-```
-
-> **Note:** `waitForModule` is only needed during submodule development or testing. End-user applications don't need it — the CLI ensures all modules are initialized before running your app.
-
-## Official Modules
-
-| Module | Description |
-|--------|-------------|
-| [@stonyx/cron](https://github.com/abofs/stonyx-cron) | Lightweight async job scheduling with min-heap |
-| [@stonyx/rest-server](https://github.com/abofs/stonyx-rest-server) | Dynamic REST server with auto-route registration |
-| [@stonyx/orm](https://github.com/abofs/stonyx-orm) | ORM with models, relationships, serializers, and optional REST integration |
-
-See each module's repository for its specific documentation.

package/docs/testing.md

@@ -1,64 +0,0 @@
-# Testing
-
-Stonyx includes built-in test infrastructure using [QUnit](https://qunitjs.com/).
-
-## Running Tests
-
-```bash
-stonyx test                     # Runs test/**/*-test.js by default
-stonyx test "test/unit/**/*.js" # Custom glob pattern
-```
-
-The test command:
-1. Sets `NODE_ENV=test`
-2. Bootstraps Stonyx via a `--require` setup file
-3. Applies [test config overrides](configuration.md#test-environment-overrides)
-4. Runs QUnit with the specified glob
-
-## Test Config Overrides
-
-Create `test/config/environment.js` to override configuration during tests:
-
-```js
-export default {
-  debug: false,
-  restServer: { port: 0 },
-};
-```
-
-These are deep-merged into the main config. See [Configuration](configuration.md#test-environment-overrides).
-
-## Integration Test Helper
-
-For tests that need Stonyx fully initialized (e.g., testing modules with database connections):
-
-```js
-import { setupIntegrationTests } from 'stonyx/test-helpers';
-
-const { module, test } = QUnit;
-
-module('My Integration Test', function(hooks) {
-  setupIntegrationTests(hooks);
-
-  test('can access modules', function(assert) {
-    // Stonyx is fully initialized here
-    assert.ok(true);
-  });
-});
-```
-
-`setupIntegrationTests` adds a `before` hook that waits for `Stonyx.ready` to resolve.
-
-## Test File Convention
-
-Place tests under `test/` with the `-test.js` suffix:
-
-```
-test/
-  unit/
-    my-feature-test.js
-    cli/
-      serve-test.js
-  integration/
-    api-test.js
-```

package/src/cli/help.js

@@ -1,48 +0,0 @@
-export default async function help({ args, builtInCommands, loadModuleCommands } = {}) {
-  console.log('\nUsage: stonyx <command> [...args]\n');
-  console.log('Commands:\n');
-
-  if (builtInCommands) {
-    for (const [name, { description }] of Object.entries(builtInCommands)) {
-      console.log(`  ${name.padEnd(20)} ${description}`);
-    }
-  }
-
-  if (loadModuleCommands) {
-    try {
-      const moduleCommands = await loadModuleCommands();
-      const entries = Object.entries(moduleCommands);
-
-      if (entries.length) {
-        console.log('\nModule commands:\n');
-
-        for (const [name, { description }] of entries) {
-          console.log(`  ${name.padEnd(20)} ${description}`);
-        }
-      }
-    } catch {
-      // Module commands not available (e.g., no project context)
-    }
-  }
-
-  console.log('\nAliases: s=serve, t=test, n=new, h=help\n');
-
-  console.log('Project conventions:\n');
-  console.log('  Entry point:       app.js');
-  console.log('  Config:            config/environment.js');
-  console.log('  DB schema:         config/db-schema.js');
-  console.log('  Models:            models/');
-  console.log('  Serializers:       serializers/');
-  console.log('  Access control:    access/');
-  console.log('  Transforms:        transforms/');
-  console.log('  Hooks:             hooks/');
-  console.log('  REST requests:     requests/');
-  console.log('  Cron jobs:         crons/');
-  console.log('  Tests:             test/{unit,integration,acceptance}/');
-  console.log('');
-  console.log('  Logging:           import log from \'stonyx/log\' (never console.log)');
-  console.log('  Utilities:         import from \'@stonyx/utils/*\' (never raw fs)');
-  console.log('  Lint config:       import from \'@abofs/code-conventions\'');
-  console.log('  Package manager:   pnpm');
-  console.log('');
-}