stonyx 0.0.7 → 0.2.0

package/.github/workflows/ci.yml

@@ -18,14 +18,19 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v3
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
       - name: Set up Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 18
-          cache: 'npm'
+          node-version: 22.18.0
+          cache: 'pnpm'
 
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       - name: Run tests
-        run: npm test
+        run: pnpm test

package/README.md

@@ -1,52 +1,179 @@
-# stonyx-backend-application
-Main base vanilla application / host module
-The intention is that this application can be used as a "base" for the Stonyx framework
+# Stonyx
 
-## Running the application
+**Stonyx** is a lightweight, modular framework for building modern Node.js applications. It provides a **plug-and-play architecture**, centralized color-coded logging, and seamless integration of asynchronous modules, making development faster, cleaner, and more maintainable.
+
+### Highlights
+
+* ✅ 100% JavaScript
+* ✅ Drop-in file system for most modules
+* ✅ Don’t even hit the ground — just fly
+* ✅ High performance
+
+Stonyx acts as a **base application host**, allowing you to add official modules (`@stonyx/*`) or your own custom modules without boilerplate initialization.
+
+---
+
+## Quick Start
+
+### ESM Usage (Application Startup)
+
+For standard applications, the **bootstrap file** ensures that the Stonyx framework and all submodules are fully loaded before your application code runs:
+
+```js
+// index.js - your project's entry point
+import Stonyx from './stonyx-bootstrap.cjs';
+await Stonyx.ready; // wait until all modules are initialized
+
+const { default: App } = await import('./app.js'); // your application
+new App();
 ```
-node . 
+
+### CommonJS Bootstrap Helper
+Auto-generated and added to your project post installation
+
+```js
+// stonyx-bootstrap.cjs
+const Stonyx = require('stonyx').default;
+const config = require('./config/environment.js').default;
+
+new Stonyx(config, __dirname);
 ```
 
-## Color Coded Logging via Chronicle
+---
+
+## Core Features
+
+### 1. **Modular Architecture**
+
+* Automatically detects modules in `devDependencies` prefixed with `@stonyx/`.
+* Supports async initialization with `stonyx-async` modules.
+* Safe module sequencing for submodule development with `waitForModule()`.
+
+### 2. **Color-Coded Logging**
+
+* Centralized logging via [Chronicle](https://github.com/abofs/chronicle).
+* Module-specific logs configurable in `environment.js`:
 
 ```js
-import log from 'stonyx/log';
+restServer: { logColor: 'yellow', logMethod: 'api', logTimestamp: true }
 ```
 
-Stonyx utilizes our own chronicle library for logging: https://github.com/abofs/chronicle.
-For all Stonyx modules, color coding can be dynamically configured by providing a `logColor` setting in the `environent.js` file.
+* Create custom logs for any class with minimal configuration.
+
+### 3. **Singleton Design**
+
+* Only one instance of Stonyx exists per project.
+* Ensures consistent access to modules, logs, and configuration.
+
+### 4. **Plug-and-Play Module Loading**
+
+* Modules with `stonyx-module` keyword in `package.json` are auto-initialized.
+* Modules with `stonyx-async` keyword are awaited automatically before usage.
+
+---
 
-### Example:
+## Official Modules
+
+### **[@stonyx/cron](https://github.com/abofs/stonyx-cron)**
+
+Lightweight asynchronous job scheduling utility.
 
 ```js
-// environment.js
-//...
-db: {
-  logColor: 'white',
-  //...
-}
+import Cron from '@stonyx/cron';
+
+const cron = new Cron();
+cron.register('exampleJob', async () => console.log('Job executed!'), 5, true);
+```
+
+* Efficient scheduling using a min-heap.
+* Optional logging via `config.cron`.
+
+---
+
+### **[@stonyx/rest-server](https://github.com/abofs/stonyx-rest-server)**
+
+Dynamic REST server module with auto-route registration.
+
+```js
+import Stonyx from 'stonyx';
+import config from './config/environment.js';
+
+new Stonyx(config);
 ```
-The above setting will expose the `log.db()` method, which will output in white.
-Alternatively you can provide a `logMethod` setting if you would rather use a different alias that
-does not match the class name, and `logTimestamp` as a true if you wish your log to include timestamp.
-`stonyx/log` fully exposes the `chronicle` object. See Chronicle documentation for more information.
+
+* Zero configuration for routes: drop request classes into the `requests` directory.
+* Automatic path generation, JSON parsing, and CORS handling.
+* Supports per-route authentication hooks.
+
+---
+
+### **[@stonyx/orm](https://github.com/abofs/stonyx-orm)**
+
+Lightweight ORM with model definitions, relationships, serializers, and optional REST integration.
 
 ```js
-// environment.js
-//...
-restServer: {
-  logColor: 'yellow',
-  logMethod: 'api'
-  //...
+import Stonyx from 'stonyx';
+import config from './config/environment.js';
+
+new Stonyx(config);
+
+// Define models
+import { Model, attr, hasMany, belongsTo } from '@stonyx/orm';
+
+class Owner extends Model {
+  id = attr('string');
+  pets = hasMany('animal');
 }
 ```
 
-The above example will expose `log.api()`, which will output in yellow.
+* Auto-loads models, serializers, transforms, and access classes.
+* Optional JSON file persistence with auto-save intervals.
+* Integrates with `@stonyx/rest-server` for automatic route setup.
+
+---
+
+## Configuration
+
+All modules are configurable via `config/environment.js`:
+
+```js
+export default {
+  restServer: { logColor: 'yellow', port: 3000 },
+  orm: { logColor: 'white', db: { file: './db.json', autosave: true } },
+  cron: { log: true }
+};
+```
+
+---
+
+## Running the Application
+
+```bash
+node .        # Start the main app
+npm start     # Run using npm script
+```
+
+---
+
+## Developing Submodules
+
+For developers building new Stonyx modules or experimenting with async modules:
+
+```js
+import Stonyx, { waitForModule } from 'stonyx';
+import config from './config/environment.js';
+
+const app = new Stonyx(config, __dirname);
+
+// Wait for specific async module readiness
+await waitForModule('restServer');
+```
+
+* Use `waitForModule()` **only for submodule development**, testing, or when you need to ensure a specific module is fully initialized before continuing.
+* Official modules automatically initialize during normal application startup, so end-users do **not** need to call `waitForModule()`.
 
-## Module Development
+---
 
-`modules.js` is responsible for dynamically loading any async stonyx modules.
-Conventionally, all official Stonyx modules must be prefixed with `@stonyx/`, and
-contain the `stonyx-module` keyword in its respective `package.json` file.
+## License
 
-Async modules require the `stonyx-async` keyword in order to be automatically loaded.
+Apache 2.0 — do what you want, just keep attribution.

package/config/environment.js

@@ -0,0 +1,13 @@
+// project configuration, override-able by listed environment variables
+const {
+  DEBUG,
+  NODE_ENV,
+} = process.env;
+
+const isTest = typeof QUnit !== 'undefined';
+const environment = isTest ? 'test' : (NODE_ENV ?? 'development');
+
+export default {
+  environment,
+  debug: DEBUG ?? environment === 'development',
+}

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "stonyx",
-  "version": "0.0.7",
+  "version": "0.2.0",
   "description": "Base stonyx framework module",
   "main": "main.js",
   "type": "module",
   "exports": {
     ".": "./src/main.js",
     "./config": "./src/exports/config.js",
-    "./log": "./src/exports/log.js"
+    "./log": "./src/exports/log.js",
+    "./test-helpers": "./src/exports/test-helpers.js"
   },
   "scripts": {
     "start": "node .",
     "test": "qunit",
     "error": "echo \"Error: no error handling\" && exit 1",
-    "postinstall": "echo \"TODO: Postinstall\""
+    "postinstall": "node scripts/postinstall.js"
   },
   "repository": {
     "type": "git",
@@ -31,6 +32,8 @@
     "node-chronicle": "^0.2.0"
   },
   "devDependencies": {
-    "@stonyx/utils": "^0.0.4"
+    "@stonyx/utils": "^0.2.0",
+    "qunit": "^2.24.1",
+    "sinon": "^21.0.0"
   }
 }

package/scripts/postinstall.js

@@ -0,0 +1,16 @@
+import { copyFile, createDirectory } from '@stonyx/utils/file';
+
+const projectDir = process.env.INIT_CWD;
+const configDir = `${projectDir}/config`;
+const bootstrapFile = 'stonyx-bootstrap.cjs';
+const envFile = 'environment.js';
+
+createDirectory(configDir);
+
+copyFile(`./config/environment copy.js`, `${configDir}/${envFile}`).then(result => {
+  if (result) console.log(`Stonyx: ${envFile} has been successfully created. Please see README.md for more information.`);
+});
+
+copyFile(`./src/bootstrap.cjs`, `${projectDir}/${bootstrapFile}`).then(result => {
+  if (result) console.log(`Stonyx: ${bootstrapFile} has been successfully created. Please see README.md for more information.`);
+});

package/src/bootstrap.cjs

@@ -0,0 +1,9 @@
+/**
+ * commonJS Bootstrap loading - Stonyx must be loaded first, prior to the rest of the application
+ */
+const { default:Stonyx } = require('stonyx');
+const { default:config } = require('./config/environment.js');
+
+new Stonyx(config, __dirname);
+
+module.exports = Stonyx;

package/src/exports/test-helpers.js

@@ -0,0 +1,8 @@
+import Stonyx from 'stonyx';
+
+export function setupIntegrationTests(hooks) {
+  hooks.before(async function() {
+    await Stonyx.ready;
+    console.log('Stonyx ready');
+  });
+}

package/src/main.js

@@ -16,9 +16,11 @@
 
 import Chronicle from 'node-chronicle';
 import loadModules from './modules.js';
+import { kebabCaseToCamelCase } from '@stonyx/utils/string';
 
 export default class Stonyx {
   static initialized = false
+  static modulePromises = {};
 
   constructor(config, rootPath) {
     if (Stonyx.instance) return Stonyx.instance;
@@ -31,6 +33,13 @@ export default class Stonyx {
     if (!config) throw new Error('Stonyx requires full environment configuration on startup');
     if (!rootPath) throw new Error('Stonyx requires root project\'s path on startup');
 
+    // Transform config from stonyx-modules running as a standalone
+    if (rootPath.includes('stonyx-')) {
+      const moduleName = kebabCaseToCamelCase(rootPath.split('/').pop().replace('stonyx-', ''));
+      config = { [moduleName]: config, ...(config.modules || {}) };
+      delete config.modules;  
+    }
+
     this.config = config;
     this.chronicle = new Chronicle({ additionalLogs: { title: 'green' }});
 
@@ -77,3 +86,5 @@ export default class Stonyx {
     return Stonyx.instance.config;
   }
 }
+
+export { waitForModule } from './modules.js';

package/src/modules.js

@@ -1,19 +1,62 @@
 /**
  * Validates and initializes stonyx modules
+ * TODO: Refactor into a ModuleLoader class (good coding exercise) 
  */
-
 import { readFile } from '@stonyx/utils/file';
+import { kebabCaseToCamelCase } from '@stonyx/utils/string';
+import { mergeObject } from '@stonyx/utils/object';
+
+const modulePromises = {};
+
+// Configure module-specific logging
+function configureLog(chronicle, module, config) {
+  const { logColor, logMethod, logTimestamp } = config;
+  if (!logColor) return;
+  
+  chronicle.defineType(logMethod || module, logColor, { logTimestamp: !!logTimestamp });
+}
+
+function initializeModule(moduleName, moduleClass, modules, initPromises) {
+  const moduleInstance = new moduleClass();
+  
+  modules.push(moduleInstance);
 
-export default async (config, rootPath, chronicle) => {
+  if (!moduleInstance.init) return;
+    
+  initPromises.push((async () => {
+    await moduleInstance.init();
+    modulePromises[moduleName]?.resolve();
+  })());
+}
+
+export default async function(config, rootPath, chronicle) {
   const modules = [];
   const initPromises = [];
   const rootPackage = await readFile(`${rootPath}/package.json`, { json: true });
-  const { devDependencies:dependencies } = rootPackage;
+  const { devDependencies:dependencies, name:projectName } = rootPackage;
+
+  // Expose rootPath to public configuration
   config.rootPath = rootPath;
 
-  for (const moduleName of Object.keys(dependencies)) {
-    if (!moduleName.startsWith('@stonyx/')) continue; // All official stonyx modules should be start with "@stonyx/"
-     
+  const moduleDependencies = Object.keys(dependencies).filter(moduleName => moduleName.startsWith('@stonyx/'));
+
+  // Setup module promises prior to initialization
+  for (const moduleName of moduleDependencies) {
+    const promise = {};
+    modulePromises[moduleName] = promise;
+    promise.ready = new Promise(resolve => promise.resolve = resolve);
+  }
+
+  // Standalone module configuration
+  if (rootPackage.keywords?.includes('stonyx-module')) {
+    configureLog(chronicle, projectName, config);
+
+    const { main: entryPoint } = rootPackage; 
+    const { default: moduleClass } = await import(`${rootPath}/${entryPoint}`);
+    initializeModule(rootPackage.name, moduleClass, modules, initPromises);
+  }
+
+  for (const moduleName of moduleDependencies) {
     const modulePackage = await readFile(`${rootPath}/node_modules/${moduleName}/package.json`, { json: true, missingFileCallback: () => {
       console.warn(`Warning: Could not locate stonyx module: "${moduleName}". Module was not loaded`);
     }});
@@ -26,36 +69,44 @@ export default async (config, rootPath, chronicle) => {
       console.warn(`Warning: Stonyx modules must contain the "stonyx-module" keyword. Module was not loaded`);
       continue;
     }
-
-    if (!keywords.includes('stonyx-async')) continue;
+    
+    if (!keywords.includes('stonyx-async')) {
+      modulePromises[moduleName].resolve();
+      continue;
+    }
 
     try {
-
       // Load & Configure Async Modules
       const { default: moduleConfig } = await import(`${rootPath}/node_modules/${moduleName}/config/environment.js`);
 
-      const module = moduleName.split('/').pop();
+      const module = kebabCaseToCamelCase(moduleName.split('/').pop());
       const userConfig = config[module] || {};
-      const finalConfig = { ...moduleConfig, ...userConfig };
+      const finalConfig = mergeObject(moduleConfig, userConfig);
       config[module] = finalConfig;
 
       // Configure module-specific logging
-      const { logColor, logMethod, logTimestamp } = finalConfig;
-      if (logColor) chronicle.defineType(logMethod || module, logColor, { logTimestamp: !!logTimestamp });
-  
+      configureLog(chronicle, module, finalConfig);
+
       const { main: entryPoint } = modulePackage; 
       const { default: moduleClass } = await import(`${rootPath}/node_modules/${moduleName}/${entryPoint}`);
-      const moduleInstance = new moduleClass();
-      
-      modules.push(moduleInstance);
-      if (moduleInstance.init) initPromises.push(moduleInstance.init());
-
+      initializeModule(moduleName, moduleClass, modules, initPromises);
     } catch (error) {
       console.error(error);
-      throw new Error(`Stonyx modules with async loading must have a config/environment.js file with default configurations.`);
+      throw new Error(`Stonyx modules with async loading must have a config/environment.js file with default configurations. Module "${moduleName}" failed to load.`);
     }
   }
 
   // Wait until all modules are initialized
   await Promise.all(initPromises);
+
+  return modules;
+}
+
+export async function waitForModule(module) {
+  module = `@stonyx/${module}`;
+  const modulePromise = modulePromises[module];
+
+  if (!modulePromise) throw new Error(`Could wait for module: ${module}. Module was not registered in project dependencies`);
+
+  await modulePromises[module].ready;
 }

package/stonyx-bootstrap.cjs

@@ -0,0 +1,9 @@
+/**
+ * commonJS Bootstrap loading - Stonyx must be loaded first, prior to the rest of the application
+ */
+const { default:Stonyx } = require('stonyx');
+const { default:config } = require('./config/environment.js');
+
+new Stonyx(config, __dirname);
+
+module.exports = Stonyx;

package/.nvmrc

@@ -1 +0,0 @@
-v22.18.0