lumisjs 1.0.0

package/src/datagen/formatters/sql.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const { Readable } = require('stream');
+
+function SqlFormatter(generator, { schema }) {
+  const stream = new Readable({ objectMode: true, read() {} });
+  const table = schema.table || 'data';
+  const columns = Object.keys(schema.properties || {});
+
+  stream._read = function () {
+    const { value, done } = generator.next ? generator.next() : { done: true };
+    if (done) {
+      this.push(null);
+      return;
+    }
+
+    const values = columns
+      .map((col) => {
+        const val = value[col];
+        if (val === null || val === undefined) return 'NULL';
+        if (typeof val === 'number' || typeof val === 'boolean') return val;
+        return `'${String(val).replace(/'/g, "''")}'`;
+      })
+      .join(', ');
+
+    this.push(`INSERT INTO ${table} (${columns.join(', ')}) VALUES (${values});\n`);
+  };
+
+  return stream;
+}
+
+module.exports = { SqlFormatter };

package/src/datagen/index.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const { DataGenerator } = require('./DataGenerator');
+const { loadSchema } = require('./schema/loadSchema');
+const { formatters } = require('./formatters');
+const { PluginManager } = require('./plugin/PluginManager');
+const { mockFromOpenApi } = require('./apis/OpenApiMocker');
+const { mockFromGraphqlSchema } = require('./apis/GraphqlMocker');
+
+module.exports = {
+  DataGenerator,
+  loadSchema,
+  formatters,
+  PluginManager,
+  mockFromOpenApi,
+  mockFromGraphqlSchema,
+};

package/src/datagen/plugin/PluginManager.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+class PluginManager {
+  constructor({ pluginDir, rootDir, locale }) {
+    this.rootDir = rootDir;
+    this.locale = locale;
+    this.plugins = [];
+
+    if (pluginDir) {
+      this.loadFromDirectory(pluginDir);
+    }
+  }
+
+  loadFromDirectory(dir) {
+    const resolved = path.isAbsolute(dir) ? dir : path.join(this.rootDir, dir);
+    if (!fs.existsSync(resolved)) return;
+    const files = fs.readdirSync(resolved);
+    for (const file of files) {
+      if (!file.toLowerCase().endsWith('.js')) continue;
+      try {
+        const plugin = require(path.join(resolved, file));
+        if (plugin && typeof plugin.init === 'function') {
+          plugin.init({ locale: this.locale, register: this.register.bind(this) });
+        }
+      } catch (err) {
+        // ignore
+      }
+    }
+  }
+
+  register(plugin) {
+    this.plugins.push(plugin);
+  }
+
+  getGenerator(name) {
+    return this.plugins.find((p) => p.name === name);
+  }
+}
+
+module.exports = { PluginManager };

package/src/datagen/plugins/example-plugin.js

@@ -0,0 +1,21 @@
+'use strict';
+
+// Example plugin that registers a custom generator
+module.exports = {
+  init({ register }) {
+    register({
+      name: 'randomCountry',
+      generate({ rng, locale }) {
+        const list = [
+          'United States',
+          'Germany',
+          'France',
+          'Türkiye',
+          'Japan',
+          'Brazil',
+        ];
+        return list[rng.integer({ min: 0, max: list.length - 1 })];
+      },
+    });
+  },
+};

package/src/datagen/schema/SchemaGenerator.js

@@ -0,0 +1,172 @@
+'use strict';
+
+const { createSeededRandom } = require('../utils/seed');
+const { faker } = require('@faker-js/faker');
+
+/**
+ * Generate a value for a `string` schema node.
+ */
+const generateString = ({ schema, rng }) => {
+  if (schema.enum && Array.isArray(schema.enum) && schema.enum.length > 0) {
+    return rng.pick(schema.enum);
+  }
+
+  if (schema.format) {
+    switch (schema.format) {
+      case 'uuid':
+        return faker.string.uuid();
+      case 'email':
+        return faker.internet.email();
+      case 'url':
+        return faker.internet.url();
+      case 'date':
+        return faker.date.past().toISOString().split('T')[0];
+      case 'date-time':
+        return faker.date.past().toISOString();
+      case 'uri':
+        return faker.internet.url();
+      case 'hostname':
+        return faker.internet.domainName();
+      case 'ipv4':
+        return faker.internet.ip();
+      case 'ipv6':
+        return faker.internet.ipv6();
+      default:
+        break;
+    }
+  }
+
+  if (schema.pattern) {
+    // Return a placeholder string that matches the pattern description,
+    // since full regex generation requires an extra library.
+    // If a future version adds RandExp, it can slot in here.
+    return schema.pattern;
+  }
+
+  const min = schema.minLength ?? 3;
+  const max = schema.maxLength ?? Math.max(min, 20);
+  const length = rng.integer({ min, max });
+  return faker.string.alpha(length);
+};
+
+/**
+ * Generate a value for a `number` or `integer` schema node.
+ */
+const generateNumber = ({ schema, rng, integer = false }) => {
+  const min = typeof schema.minimum === 'number' ? schema.minimum : 0;
+  const max = typeof schema.maximum === 'number' ? schema.maximum : min + 100;
+  if (integer) return rng.integer({ min: Math.ceil(min), max: Math.floor(max) });
+  return rng.number({ min, max });
+};
+
+const TYPE_GENERATORS = {
+  string: generateString,
+  number: (ctx) => generateNumber({ ...ctx, integer: false }),
+  integer: (ctx) => generateNumber({ ...ctx, integer: true }),
+  boolean: ({ rng }) => rng.boolean(),
+
+  object: ({ schema, rng, locale, pluginManager }) => {
+    const result = {};
+    const props = schema.properties || {};
+    const required = new Set(schema.required || []);
+
+    for (const [key, propSchema] of Object.entries(props)) {
+      // Skip optional fields ~30% of the time unless they're required
+      if (!required.has(key) && rng.number({ min: 0, max: 1 }) < 0.3) continue;
+      result[key] = generateBySchema({ schema: propSchema, rng, locale, pluginManager });
+    }
+    return result;
+  },
+
+  array: ({ schema, rng, locale, pluginManager }) => {
+    const minItems = schema.minItems ?? 1;
+    const maxItems = schema.maxItems ?? Math.max(minItems, 5);
+    const length = rng.integer({ min: minItems, max: maxItems });
+    const items = [];
+    for (let i = 0; i < length; i++) {
+      items.push(generateBySchema({ schema: schema.items || {}, rng, locale, pluginManager }));
+    }
+    return items;
+  },
+
+  null: () => null,
+};
+
+/**
+ * Generate a value from any schema node.
+ * @param {object} ctx
+ * @param {object} ctx.schema
+ * @param {object} ctx.rng
+ * @param {string} ctx.locale
+ * @param {object} [ctx.pluginManager]
+ * @returns {any}
+ */
+function generateBySchema({ schema = {}, rng, locale, pluginManager }) {
+  if (schema === null || schema === undefined) return null;
+  if (schema.const !== undefined) return schema.const;
+
+  // oneOf / anyOf support
+  if (Array.isArray(schema.oneOf) && schema.oneOf.length > 0) {
+    return generateBySchema({ schema: rng.pick(schema.oneOf), rng, locale, pluginManager });
+  }
+  if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) {
+    return generateBySchema({ schema: rng.pick(schema.anyOf), rng, locale, pluginManager });
+  }
+
+  // Plugin generators
+  if (schema.generator && pluginManager) {
+    const plugin = pluginManager.getGenerator?.(schema.generator);
+    if (plugin && typeof plugin.generate === 'function') {
+      return plugin.generate({ schema, rng, locale });
+    }
+  }
+
+  // Nullable support
+  if (schema.nullable && rng.number({ min: 0, max: 1 }) < 0.15) return null;
+
+  // Infer type when not explicitly set
+  const type =
+    schema.type ||
+    (schema.properties ? 'object' : schema.items ? 'array' : 'string');
+
+  // Handle type arrays: e.g. { type: ['string', 'null'] }
+  const resolvedType = Array.isArray(type) ? rng.pick(type) : type;
+
+  const generator = TYPE_GENERATORS[resolvedType];
+  if (!generator) {
+    // Unknown type — return null rather than silently crashing
+    return null;
+  }
+
+  return generator({ schema, rng, locale, pluginManager });
+}
+
+class SchemaGenerator {
+  /**
+   * @param {object} options
+   * @param {object} options.schema - JSON Schema object
+   * @param {string|number} [options.seed] - Seed for reproducible output
+   * @param {string} [options.locale='en']
+   * @param {object} [options.pluginManager]
+   */
+  constructor({ schema, seed, locale = 'en', pluginManager } = {}) {
+    if (!schema || typeof schema !== 'object') {
+      throw new TypeError('schema must be a non-null object');
+    }
+    this.schema = schema;
+    this.locale = locale;
+    this.rng = createSeededRandom(seed, { locale });
+    this.pluginManager = pluginManager;
+  }
+
+  generate() {
+    return generateBySchema({
+      schema: this.schema,
+      rng: this.rng,
+      locale: this.locale,
+      pluginManager: this.pluginManager,
+    });
+  }
+}
+
+module.exports = { SchemaGenerator, generateBySchema };

package/src/datagen/schema/loadSchema.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const fs = require('fs');
+
+function loadSchema(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Unable to parse schema JSON: ${err.message}`);
+  }
+}
+
+module.exports = { loadSchema };

package/src/datagen/utils/seed.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const seedrandom = require('seedrandom');
+
+function createSeededRandom(seed, { locale } = {}) {
+  const rng = seedrandom(String(seed || Date.now()));
+
+  return {
+    number({ min = 0, max = 1 }) {
+      return rng() * (max - min) + min;
+    },
+    integer({ min = 0, max = 100 }) {
+      return Math.floor(rng() * (max - min + 1)) + min;
+    },
+    boolean() {
+      return rng() >= 0.5;
+    },
+    pick(array) {
+      if (!Array.isArray(array) || array.length === 0) return null;
+      const idx = Math.floor(rng() * array.length);
+      return array[idx];
+    },
+  };
+}
+
+module.exports = { createSeededRandom };

package/src/di/ServiceContainer.js

@@ -0,0 +1,229 @@
+'use strict';
+
+/**
+ * Dependency Injection Container.
+ * Register services and inject them into commands/plugins automatically.
+ *
+ * @example
+ * client.services.register('db', new DatabaseService());
+ * client.services.register('api', new ExternalAPI());
+ *
+ * // In a command:
+ * class MyCmd extends Command {
+ *   inject = ['db', 'api'];
+ *   async execute(interaction) {
+ *     await this.db.query(...);
+ *   }
+ * }
+ */
+class ServiceContainer {
+  constructor(client) {
+    this.client = client;
+
+    /** @type {Map<string, { instance: any, singleton: boolean, factory: Function|null, initialized: boolean }>} */
+    this._services = new Map();
+
+    /** @type {Map<string, Function[]>} Lifecycle hooks */
+    this._hooks = new Map();
+  }
+
+  /**
+   * Register a service or factory.
+   * @param {string} name - Unique service identifier
+   * @param {any|Function} instanceOrFactory - Service instance or factory (client) => instance
+   * @param {object} [options]
+   * @param {boolean} [options.singleton=true] - False creates a new instance per get()
+   * @returns {ServiceContainer} this (chainable)
+   */
+  register(name, instanceOrFactory, options = {}) {
+    if (typeof name !== 'string' || !name.trim()) {
+      throw new TypeError('Service name must be a non-empty string.');
+    }
+    if (instanceOrFactory === undefined || instanceOrFactory === null) {
+      throw new TypeError(`Service "${name}" value cannot be null or undefined.`);
+    }
+
+    const singleton = options.singleton !== false;
+    // Heuristic: arrow functions and regular functions with no .prototype.constructor
+    // pairing are treated as factories. Named classes / constructed objects are not.
+    const isFactory =
+      typeof instanceOrFactory === 'function' &&
+      !instanceOrFactory.prototype?.constructor?.name?.length;
+
+    this._services.set(name, {
+      instance: isFactory && singleton ? null : isFactory ? undefined : instanceOrFactory,
+      singleton,
+      factory: isFactory ? instanceOrFactory : null,
+      initialized: !isFactory,
+    });
+
+    this.client.logger?.debug?.(`[ServiceContainer] Registered: ${name}`);
+    this._runHooks('register', name);
+    return this;
+  }
+
+  /**
+   * Register a service that is lazily constructed using a factory.
+   * More explicit alternative to passing a factory to register().
+   * @param {string} name
+   * @param {Function} factory - (client) => instance
+   * @param {object} [options]
+   * @returns {ServiceContainer}
+   */
+  registerFactory(name, factory, options = {}) {
+    if (typeof factory !== 'function') {
+      throw new TypeError(`Factory for "${name}" must be a function.`);
+    }
+    return this.register(name, factory, { ...options, _forceFactory: true });
+  }
+
+  /**
+   * Get a service by name. Lazily initialises singleton factories.
+   * @param {string} name
+   * @returns {any}
+   */
+  get(name) {
+    const entry = this._services.get(name);
+    if (!entry) {
+      throw new Error(
+        `Service "${name}" is not registered. ` +
+          `Available: [${[...this._services.keys()].join(', ')}]`
+      );
+    }
+
+    if (entry.factory) {
+      if (entry.singleton) {
+        if (!entry.initialized) {
+          entry.instance = entry.factory(this.client);
+          entry.initialized = true;
+        }
+        return entry.instance;
+      }
+      // Transient: new instance every call
+      return entry.factory(this.client);
+    }
+
+    return entry.instance;
+  }
+
+  /**
+   * Check if a service is registered.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  has(name) {
+    return this._services.has(name);
+  }
+
+  /**
+   * Unregister and destroy a service.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  unregister(name) {
+    const entry = this._services.get(name);
+    if (!entry) return false;
+
+    if (entry.instance && typeof entry.instance.destroy === 'function') {
+      try {
+        entry.instance.destroy();
+      } catch (err) {
+        this.client.logger?.warn?.(`[ServiceContainer] Error destroying "${name}": ${err.message}`);
+      }
+    }
+
+    this._services.delete(name);
+    this._runHooks('unregister', name);
+    return true;
+  }
+
+  /**
+   * Inject registered services into a target object's `inject` array as lazy getters.
+   * @param {object} target - Object with `inject: string[]` property
+   * @returns {object} target (mutated in-place)
+   */
+  inject(target) {
+    if (!target || !Array.isArray(target.inject)) return target;
+
+    for (const name of target.inject) {
+      if (this.has(name)) {
+        Object.defineProperty(target, name, {
+          get: () => this.get(name),
+          configurable: true,
+          enumerable: false,
+        });
+      } else {
+        this.client.logger?.warn?.(
+          `[ServiceContainer] Cannot inject "${name}": not registered.`
+        );
+      }
+    }
+
+    return target;
+  }
+
+  /**
+   * Subscribe to lifecycle events.
+   * @param {'register'|'unregister'} event
+   * @param {Function} fn - (name: string) => void
+   */
+  on(event, fn) {
+    if (!['register', 'unregister'].includes(event)) {
+      throw new Error(`Unknown ServiceContainer event: "${event}"`);
+    }
+    if (!this._hooks.has(event)) this._hooks.set(event, []);
+    this._hooks.get(event).push(fn);
+  }
+
+  /** @private */
+  _runHooks(event, name) {
+    const hooks = this._hooks.get(event);
+    if (!hooks) return;
+    for (const fn of hooks) {
+      try {
+        fn(name);
+      } catch (err) {
+        this.client.logger?.warn?.(`[ServiceContainer] Hook error on "${event}": ${err.message}`);
+      }
+    }
+  }
+
+  /**
+   * List metadata for all registered services.
+   * @returns {Array<{ name: string, singleton: boolean, initialized: boolean }>}
+   */
+  list() {
+    return [...this._services.entries()].map(([name, entry]) => ({
+      name,
+      singleton: entry.singleton,
+      initialized: entry.initialized,
+      hasFactory: entry.factory !== null,
+    }));
+  }
+
+  /**
+   * Destroy all services and clear the container.
+   */
+  async destroy() {
+    const destroyPromises = [];
+
+    for (const [name, entry] of this._services) {
+      if (entry.instance && typeof entry.instance.destroy === 'function') {
+        const result = entry.instance.destroy();
+        if (result && typeof result.then === 'function') {
+          destroyPromises.push(
+            result.catch((err) =>
+              this.client.logger?.warn?.(`[ServiceContainer] Error destroying "${name}": ${err.message}`)
+            )
+          );
+        }
+      }
+    }
+
+    await Promise.all(destroyPromises);
+    this._services.clear();
+    this._hooks.clear();
+  }
+}
+
+module.exports = ServiceContainer;

package/src/errors/ErrorCodes.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const ErrorCodes = {
+  // Generic
+  UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+  INVALID_TOKEN: 'INVALID_TOKEN',
+  INVALID_OPTION: 'INVALID_OPTION',
+  MISSING_OPTION: 'MISSING_OPTION',
+  INVALID_ARGUMENT: 'INVALID_ARGUMENT',
+
+  // Client
+  CLIENT_NOT_READY: 'CLIENT_NOT_READY',
+  CLIENT_ALREADY_LOGGED_IN: 'CLIENT_ALREADY_LOGGED_IN',
+  CLIENT_DESTROYED: 'CLIENT_DESTROYED',
+
+  // REST / HTTP
+  API_ERROR: 'API_ERROR',
+  HTTP_ERROR: 'HTTP_ERROR',
+  RATE_LIMITED: 'RATE_LIMITED',
+  RATE_LIMIT_EXCEEDED: 'RATE_LIMIT_EXCEEDED',
+
+  // WebSocket
+  WS_CONNECTION_FAILED: 'WS_CONNECTION_FAILED',
+  WS_CLOSE_REQUESTED: 'WS_CLOSE_REQUESTED',
+  WS_NOT_OPEN: 'WS_NOT_OPEN',
+  WS_ALREADY_CONNECTED: 'WS_ALREADY_CONNECTED',
+  WS_AUTHENTICATION_FAILED: 'WS_AUTHENTICATION_FAILED',
+  WS_INVALID_SESSION: 'WS_INVALID_SESSION',
+
+  // Cache
+  CACHE_ADAPTER_ERROR: 'CACHE_ADAPTER_ERROR',
+  CACHE_ADAPTER_NOT_FOUND: 'CACHE_ADAPTER_NOT_FOUND',
+
+  // Plugins
+  PLUGIN_LOAD_ERROR: 'PLUGIN_LOAD_ERROR',
+  PLUGIN_NOT_FOUND: 'PLUGIN_NOT_FOUND',
+  PLUGIN_ALREADY_LOADED: 'PLUGIN_ALREADY_LOADED',
+  PLUGIN_DEPENDENCY_MISSING: 'PLUGIN_DEPENDENCY_MISSING',
+  PLUGIN_INVALID: 'PLUGIN_INVALID',
+
+  // Structures
+  INVALID_STRUCTURE: 'INVALID_STRUCTURE',
+  MISSING_PERMISSIONS: 'MISSING_PERMISSIONS',
+  INVALID_CHANNEL_TYPE: 'INVALID_CHANNEL_TYPE',
+
+  // i18n
+  LOCALE_NOT_FOUND: 'LOCALE_NOT_FOUND',
+  TRANSLATION_KEY_MISSING: 'TRANSLATION_KEY_MISSING',
+
+  // Interactions
+  INTERACTION_ALREADY_REPLIED: 'INTERACTION_ALREADY_REPLIED',
+  INTERACTION_CALLBACK_NOT_FOUND: 'INTERACTION_CALLBACK_NOT_FOUND',
+  INTERACTION_NOT_AUTOCOMPLETE: 'INTERACTION_NOT_AUTOCOMPLETE',
+};
+
+const ErrorMessages = {
+  [ErrorCodes.UNKNOWN_ERROR]: 'An unknown error occurred.',
+  [ErrorCodes.INVALID_TOKEN]: 'An invalid bot token was provided.',
+  [ErrorCodes.INVALID_OPTION]: (option) => `Invalid option: ${option}`,
+  [ErrorCodes.MISSING_OPTION]: (option) => `Missing required option: ${option}`,
+  [ErrorCodes.INVALID_ARGUMENT]: (arg) => `Invalid argument: ${arg}`,
+
+  [ErrorCodes.CLIENT_NOT_READY]: 'The client is not ready yet.',
+  [ErrorCodes.CLIENT_ALREADY_LOGGED_IN]: 'The client is already logged in.',
+  [ErrorCodes.CLIENT_DESTROYED]: 'The client has been destroyed.',
+
+  [ErrorCodes.API_ERROR]: (code, message) => `Discord API error [${code}]: ${message}`,
+  [ErrorCodes.HTTP_ERROR]: (status) => `HTTP error: ${status}`,
+  [ErrorCodes.RATE_LIMITED]: (retryAfter) =>
+    `Rate limited. Retry after ${retryAfter}ms.`,
+  [ErrorCodes.RATE_LIMIT_EXCEEDED]: 'Maximum rate limit retry attempts reached.',
+
+  [ErrorCodes.WS_CONNECTION_FAILED]: 'WebSocket connection failed.',
+  [ErrorCodes.WS_CLOSE_REQUESTED]: 'WebSocket close was requested.',
+  [ErrorCodes.WS_NOT_OPEN]: 'WebSocket connection is not open.',
+  [ErrorCodes.WS_ALREADY_CONNECTED]: 'WebSocket is already connected.',
+  [ErrorCodes.WS_AUTHENTICATION_FAILED]: 'WebSocket authentication failed.',
+  [ErrorCodes.WS_INVALID_SESSION]: 'Invalid WebSocket session.',
+
+  [ErrorCodes.CACHE_ADAPTER_ERROR]: (msg) => `Cache adapter error: ${msg}`,
+  [ErrorCodes.CACHE_ADAPTER_NOT_FOUND]: (name) =>
+    `Cache adapter not found: "${name}". Valid options: memory, redis, sqlite`,
+
+  [ErrorCodes.PLUGIN_LOAD_ERROR]: (name, err) =>
+    `Failed to load plugin "${name}": ${err}`,
+  [ErrorCodes.PLUGIN_NOT_FOUND]: (name) => `Plugin not found: "${name}"`,
+  [ErrorCodes.PLUGIN_ALREADY_LOADED]: (name) =>
+    `Plugin "${name}" is already loaded.`,
+  [ErrorCodes.PLUGIN_DEPENDENCY_MISSING]: (name, dep) =>
+    `Plugin "${name}" is missing dependency: "${dep}"`,
+  [ErrorCodes.PLUGIN_INVALID]: (name) =>
+    `Invalid plugin "${name}". Must export a valid plugin object or class.`,
+
+  [ErrorCodes.INVALID_STRUCTURE]: (name) => `Invalid structure: ${name}`,
+  [ErrorCodes.MISSING_PERMISSIONS]: (perms) => `Missing permissions: ${perms}`,
+  [ErrorCodes.INVALID_CHANNEL_TYPE]: (type) => `Invalid channel type: ${type}`,
+
+  [ErrorCodes.LOCALE_NOT_FOUND]: (locale) => `Locale not found: "${locale}"`,
+  [ErrorCodes.TRANSLATION_KEY_MISSING]: (key) =>
+    `Translation key not found: "${key}"`,
+
+  [ErrorCodes.INTERACTION_ALREADY_REPLIED]:
+    'This interaction has already been replied to.',
+  [ErrorCodes.INTERACTION_CALLBACK_NOT_FOUND]:
+    'Interaction callback not found.',
+  [ErrorCodes.INTERACTION_NOT_AUTOCOMPLETE]:
+    'This interaction is not an autocomplete interaction.',
+};
+
+module.exports = { ErrorCodes, ErrorMessages };