stonyx 0.2.3-alpha.17 → 0.2.3-alpha.19

package/dist/main.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2025 Stone Costa
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import Chronicle from '@stonyx/logs';
+import loadModules from './modules.js';
+import { kebabCaseToCamelCase } from '@stonyx/utils/string';
+import { mergeObject } from '@stonyx/utils/object';
+export default class Stonyx {
+    static initialized = false;
+    static modulePromises = {};
+    static instance;
+    static ready;
+    config;
+    chronicle;
+    modules;
+    constructor(config, rootPath) {
+        if (Stonyx.instance)
+            return Stonyx.instance;
+        Stonyx.instance = this;
+        Stonyx.ready = this.start(config, rootPath);
+    }
+    async start(config, rootPath) {
+        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' } });
+        Stonyx.initialized = true;
+        // Auto-merge test environment overrides (after initialized flag, before modules load)
+        // Uses in-place mutation to preserve existing references (e.g. stonyx/config export cache)
+        if (process.env.NODE_ENV === 'test') {
+            try {
+                const { default: testOverrides } = await import(`${rootPath}/test/config/environment.js`);
+                const merged = mergeObject(config, testOverrides);
+                Object.assign(config, merged);
+            }
+            catch { /* no test overrides found */ }
+        }
+        this.modules = await loadModules(config, rootPath, this.chronicle);
+        this.configureUserLogs();
+    }
+    /**
+     * Allows users to define their own log for any extra class via environment config
+     */
+    configureUserLogs() {
+        const { chronicle } = this;
+        for (const [className, config] of Object.entries(this.config)) {
+            if (!config || typeof config !== 'object')
+                continue;
+            if (chronicle[className])
+                continue;
+            const { logColor, logMethod, logTimestamp } = config;
+            if (!logColor)
+                continue;
+            chronicle.defineType(logMethod || className, logColor, { logTimestamp: !!logTimestamp });
+        }
+    }
+    static get log() {
+        if (!Stonyx.initialized)
+            throw new Error('Stonyx has not been initialized yet');
+        return Stonyx.instance.chronicle;
+    }
+    static get config() {
+        if (!Stonyx.initialized)
+            throw new Error('Stonyx has not been initialized yet');
+        return Stonyx.instance.config;
+    }
+}
+export { waitForModule } from './modules.js';

package/dist/modules.d.ts

@@ -0,0 +1,5 @@
+import type { StoynxModule } from './lifecycle.js';
+import type Chronicle from '@stonyx/logs';
+export type StoynxConfig = Record<string, Record<string, unknown> | unknown>;
+export default function loadModules(config: StoynxConfig, rootPath: string, chronicle: Chronicle): Promise<StoynxModule[]>;
+export declare function waitForModule(moduleName: string): Promise<void>;

package/dist/modules.js

@@ -0,0 +1,92 @@
+/**
+ * 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);
+    if (!moduleInstance.init)
+        return;
+    initPromises.push((async () => {
+        await moduleInstance.init();
+        modulePromises[moduleName]?.resolve();
+    })());
+}
+export default async function loadModules(config, rootPath, chronicle) {
+    const modules = [];
+    const initPromises = [];
+    const rootPackage = await readFile(`${rootPath}/package.json`, { json: true });
+    const dependencies = rootPackage.devDependencies;
+    const projectName = rootPackage.name;
+    // Expose rootPath to public configuration
+    config.rootPath = rootPath;
+    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 entryPoint = rootPackage.main;
+        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: (_filePath) => {
+                console.warn(`Warning: Could not locate stonyx module: "${moduleName}". Module was not loaded`);
+                return '';
+            } });
+        if (!modulePackage)
+            continue;
+        const keywords = modulePackage.keywords;
+        if (!keywords.includes('stonyx-module')) {
+            console.warn(`Warning: Stonyx modules must contain the "stonyx-module" keyword. Module was not loaded`);
+            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 = kebabCaseToCamelCase(moduleName.split('/').pop());
+            const userConfig = config[module] || {};
+            const finalConfig = mergeObject(moduleConfig, userConfig);
+            config[module] = finalConfig;
+            // Configure module-specific logging
+            configureLog(chronicle, module, finalConfig);
+            const entryPoint = modulePackage.main;
+            const { default: moduleClass } = await import(`${rootPath}/node_modules/${moduleName}/${entryPoint}`);
+            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. Module "${moduleName}" failed to load.`);
+        }
+    }
+    // Wait until all modules are initialized
+    await Promise.all(initPromises);
+    return modules;
+}
+export async function waitForModule(moduleName) {
+    const fullName = `@stonyx/${moduleName}`;
+    const modulePromise = modulePromises[fullName];
+    if (!modulePromise)
+        throw new Error(`Could wait for module: ${fullName}. Module was not registered in project dependencies`);
+    await modulePromises[fullName].ready;
+}

package/package.json

@@ -1,25 +1,41 @@
 {
   "name": "stonyx",
-  "version": "0.2.3-alpha.17",
+  "version": "0.2.3-alpha.19",
   "description": "Base stonyx framework module",
-  "main": "main.js",
+  "main": "dist/main.js",
+  "types": "dist/main.d.ts",
   "type": "module",
   "bin": {
-    "stonyx": "./src/cli.js"
+    "stonyx": "./dist/cli.js"
   },
   "exports": {
-    ".": "./src/main.js",
-    "./config": "./src/exports/config.js",
-    "./log": "./src/exports/log.js",
-    "./test-helpers": "./src/exports/test-helpers.js",
-    "./lifecycle": "./src/lifecycle.js"
+    ".": {
+      "types": "./dist/main.d.ts",
+      "default": "./dist/main.js"
+    },
+    "./config": {
+      "types": "./dist/exports/config.d.ts",
+      "default": "./dist/exports/config.js"
+    },
+    "./log": {
+      "types": "./dist/exports/log.d.ts",
+      "default": "./dist/exports/log.js"
+    },
+    "./test-helpers": {
+      "types": "./dist/exports/test-helpers.d.ts",
+      "default": "./dist/exports/test-helpers.js"
+    },
+    "./lifecycle": {
+      "types": "./dist/lifecycle.d.ts",
+      "default": "./dist/lifecycle.js"
+    }
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/abofs/stonyx.git"
   },
   "files": [
-    "src",
+    "dist",
     "config",
     "README.md"
   ],
@@ -35,16 +51,22 @@
     "url": "https://github.com/abofs/stonyx/issues"
   },
   "dependencies": {
-    "@stonyx/utils": "0.2.3-beta.11",
-    "@stonyx/logs": "1.0.1-beta.6"
+    "@stonyx/utils": "0.2.3-beta.18",
+    "@stonyx/logs": "1.0.1-beta.11"
   },
   "devDependencies": {
+    "@types/node": "^25.5.2",
+    "@types/qunit": "^2.19.13",
+    "@types/sinon": "^21.0.1",
     "qunit": "^2.24.1",
-    "sinon": "^21.0.0"
+    "sinon": "^21.0.0",
+    "typescript": "^5.8.3"
   },
   "scripts": {
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
     "start": "node .",
-    "test": "qunit",
+    "test": "pnpm build && pnpm build:test && qunit 'dist-test/test/**/*-test.js'",
     "error": "echo \"Error: no error handling\" && exit 1",
     "postinstall": "node scripts/postinstall.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('');
-}

package/src/cli/load-commands.js

@@ -1,56 +0,0 @@
-import { readFile } from 'fs/promises';
-import path from 'path';
-
-export default async function loadModuleCommands() {
-  const cwd = process.cwd();
-  const commands = {};
-
-  let projectPackage;
-
-  try {
-    const raw = await readFile(path.join(cwd, 'package.json'), 'utf8');
-    projectPackage = JSON.parse(raw);
-  } catch {
-    return commands;
-  }
-
-  const allDeps = {
-    ...projectPackage.dependencies,
-    ...projectPackage.devDependencies
-  };
-
-  const stonyxModules = Object.keys(allDeps).filter(name => name.startsWith('@stonyx/'));
-
-  for (const moduleName of stonyxModules) {
-    let modulePackage;
-
-    try {
-      const raw = await readFile(path.join(cwd, 'node_modules', moduleName, 'package.json'), 'utf8');
-      modulePackage = JSON.parse(raw);
-    } catch {
-      continue;
-    }
-
-    const { exports: moduleExports } = modulePackage;
-
-    if (!moduleExports || !moduleExports['./commands']) continue;
-
-    try {
-      const commandsModule = await import(path.join(cwd, 'node_modules', moduleName, moduleExports['./commands']));
-      const moduleCommands = commandsModule.default;
-
-      for (const [name, command] of Object.entries(moduleCommands)) {
-        if (commands[name]) {
-          console.warn(`Warning: Command "${name}" from ${moduleName} conflicts with existing command. Skipping.`);
-          continue;
-        }
-
-        commands[name] = { ...command, module: moduleName };
-      }
-    } catch {
-      continue;
-    }
-  }
-
-  return commands;
-}

package/src/cli/new.js

@@ -1,237 +0,0 @@
-import { confirm, prompt } from '@stonyx/utils/prompt';
-import { createFile, createDirectory, copyFile, fileExists } from '@stonyx/utils/file';
-import { spawn } from 'child_process';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const MODULE_OPTIONS = [
-  {
-    question: 'Will this project need a REST server?',
-    package: '@stonyx/rest-server',
-    dirs: ['requests']
-  },
-  {
-    question: 'Will this project need WebSockets?',
-    package: '@stonyx/sockets',
-    dirs: ['socket-handlers']
-  },
-  {
-    question: 'Will this project need data management?',
-    package: '@stonyx/orm',
-    dirs: ['models', 'serializers', 'access', 'transforms', 'hooks'],
-    files: { 'config/db-schema.js': generateDbSchema }
-  },
-  {
-    question: 'Will this project need scheduled tasks (cron)?',
-    package: '@stonyx/cron',
-    dirs: ['crons']
-  },
-  {
-    question: 'Will this project need OAuth?',
-    package: '@stonyx/oauth'
-  },
-  {
-    question: 'Will this project need pub/sub events?',
-    package: '@stonyx/events'
-  },
-  {
-    question: 'Will this project need a Discord bot?',
-    package: '@stonyx/discord',
-    dirs: ['discord-commands', 'discord-events']
-  }
-];
-
-function generateDbSchema() {
-  return `import { Model, hasMany } from '@stonyx/orm';
-
-export default class DBModel extends Model {
-  // Define your collections here
-  // examples = hasMany('example');
-}
-`;
-}
-
-function generatePackageJson(name, selectedModules) {
-  const devDependencies = { stonyx: 'latest' };
-
-  for (const mod of selectedModules) {
-    devDependencies[mod.package] = 'latest';
-  }
-
-  // Sort dependencies alphabetically
-  const sorted = Object.fromEntries(
-    Object.entries(devDependencies).sort(([a], [b]) => a.localeCompare(b))
-  );
-
-  return JSON.stringify({
-    name,
-    version: '0.1.0',
-    type: 'module',
-    private: true,
-    scripts: {
-      start: 'stonyx serve',
-      test: 'stonyx test'
-    },
-    devDependencies: sorted
-  }, null, 2) + '\n';
-}
-
-function generateAppJs() {
-  return `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');
-  }
-}
-`;
-}
-
-function generateEnvironmentJs() {
-  return `export default {
-}
-`;
-}
-
-function generateEnvironmentExampleJs() {
-  return `// Copy this file to environment.js and fill in your values
-// All values should use environment variables with ?? fallback defaults
-
-const {
-  NODE_ENV,
-} = process.env;
-
-const environment = NODE_ENV ?? 'development';
-
-export default {
-}
-`;
-}
-
-function generateGitignore() {
-  return `node_modules/
-.env
-db.json
-*.log
-`;
-}
-
-function runPnpmInstall(projectDir) {
-  return new Promise((resolve, reject) => {
-    const child = spawn('pnpm', ['install'], {
-      cwd: projectDir,
-      stdio: 'inherit'
-    });
-
-    child.on('close', code => {
-      if (code === 0) resolve();
-      else reject(new Error(`pnpm install exited with code ${code}`));
-    });
-
-    child.on('error', reject);
-  });
-}
-
-export default async function newCommand({ args }) {
-  let appName = args[0];
-
-  if (!appName) {
-    appName = await prompt('Project name:');
-  }
-
-  if (!appName) {
-    console.error('Project name is required.');
-    process.exit(1);
-  }
-
-  const projectDir = path.resolve(process.cwd(), appName);
-
-  if (await fileExists(projectDir)) {
-    console.error(`Directory "${appName}" already exists.`);
-    process.exit(1);
-  }
-
-  console.log(`\nScaffolding new Stonyx project: ${appName}\n`);
-
-  // Prompt for module selection
-  const selectedModules = [];
-
-  for (const mod of MODULE_OPTIONS) {
-    if (await confirm(mod.question)) {
-      selectedModules.push(mod);
-    }
-  }
-
-  console.log('\nCreating project structure...\n');
-
-  // Create project directory
-  await createDirectory(projectDir);
-
-  // Copy .nvmrc from monorepo root
-  const monorepoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
-  const nvmrcSource = path.join(monorepoRoot, '.nvmrc');
-
-  if (await fileExists(nvmrcSource)) {
-    await copyFile(nvmrcSource, path.join(projectDir, '.nvmrc'));
-  }
-
-  // Generate core files
-  await createFile(path.join(projectDir, 'package.json'), generatePackageJson(appName, selectedModules));
-  await createFile(path.join(projectDir, 'app.js'), generateAppJs());
-  await createFile(path.join(projectDir, '.gitignore'), generateGitignore());
-
-  // Create config directory and files
-  await createFile(path.join(projectDir, 'config', 'environment.js'), generateEnvironmentJs());
-  await createFile(path.join(projectDir, 'config', 'environment.example.js'), generateEnvironmentExampleJs());
-
-  // Create module-specific directories and files
-  for (const mod of selectedModules) {
-    if (mod.dirs) {
-      for (const dir of mod.dirs) {
-        await createDirectory(path.join(projectDir, dir));
-        // Create .gitkeep so empty dirs are tracked
-        await createFile(path.join(projectDir, dir, '.gitkeep'), '');
-      }
-    }
-
-    if (mod.files) {
-      for (const [filePath, generator] of Object.entries(mod.files)) {
-        await createFile(path.join(projectDir, filePath), generator());
-      }
-    }
-  }
-
-  // Create test structure
-  await createDirectory(path.join(projectDir, 'test', 'unit'));
-  await createFile(path.join(projectDir, 'test', 'unit', '.gitkeep'), '');
-  await createDirectory(path.join(projectDir, 'test', 'integration'));
-  await createFile(path.join(projectDir, 'test', 'integration', '.gitkeep'), '');
-  await createDirectory(path.join(projectDir, 'test', 'acceptance'));
-  await createFile(path.join(projectDir, 'test', 'acceptance', '.gitkeep'), '');
-
-  // Create test config
-  await createFile(path.join(projectDir, 'test', 'config', 'environment.js'), `export default {\n  // Test-specific config overrides\n}\n`);
-
-  console.log('Installing dependencies...\n');
-
-  try {
-    await runPnpmInstall(projectDir);
-  } catch (error) {
-    console.error('Failed to install dependencies. Run `pnpm install` manually in the project directory.');
-  }
-
-  console.log(`\n✓ Project "${appName}" created successfully!`);
-  console.log(`\n  cd ${appName}`);
-  console.log(`  stonyx serve\n`);
-}

package/src/cli/serve.js

@@ -1,38 +0,0 @@
-import { runStartupHooks, runShutdownHooks } from '../lifecycle.js';
-
-export function createShutdownHandler(modules) {
-  let shuttingDown = false;
-  return async () => {
-    if (shuttingDown) return;
-    shuttingDown = true;
-
-    await runShutdownHooks(modules);
-    process.exit(0);
-  };
-}
-
-export default async function serve({ args }) {
-  const cwd = process.cwd();
-  const entryFlag = args.indexOf('--entry');
-  const entryPoint = entryFlag !== -1 ? args[entryFlag + 1] : 'app.js';
-
-  const { default: config } = await import(`${cwd}/config/environment.js`);
-  const { default: Stonyx } = await import('../main.js');
-
-  new Stonyx(config, cwd);
-  await Stonyx.ready;
-
-  const { modules } = Stonyx.instance;
-  await runStartupHooks(modules);
-
-  const shutdown = createShutdownHandler(modules);
-
-  process.on('SIGTERM', shutdown);
-  process.on('SIGINT', shutdown);
-
-  const entryModule = await import(`${cwd}/${entryPoint}`);
-
-  if (entryModule.default) {
-    new entryModule.default();
-  }
-}

package/src/cli/test.js

@@ -1,27 +0,0 @@
-import { spawn } from 'child_process';
-import { fileURLToPath, pathToFileURL } from 'url';
-import path from 'path';
-
-export default async function test({ args }) {
-  const cwd = process.cwd();
-  const setupFile = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'test-setup.js');
-  const setupFileUrl = pathToFileURL(setupFile).href;
-  const qunitBin = path.resolve(cwd, 'node_modules/qunit/bin/qunit.js');
-
-  // Default to conventional test glob if no args provided
-  const testArgs = args.length > 0 ? args : ['test/**/*-test.js'];
-
-  const child = spawn(process.execPath, [
-    '--import', setupFileUrl,
-    qunitBin,
-    ...testArgs
-  ], {
-    cwd,
-    stdio: 'inherit',
-    env: { ...process.env, NODE_ENV: 'test' }
-  });
-
-  child.on('close', (code) => {
-    process.exit(code);
-  });
-}