zumito-framework 1.23.2 → 1.24.0

package/dist/ZumitoFramework.js

@@ -1,5 +1,6 @@
 import * as fs from 'fs';
 import * as url from 'url';
+import { createRequire } from 'module';
 import { Client, Events, } from 'discord.js';
 import { ApiResponse } from './definitions/api/ApiResponse.js';
 import { EventEmitter } from "tseep";
@@ -317,12 +318,37 @@ export class ZumitoFramework {
         }
         const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
         const moduleEntries = [];
+        const require = createRequire(import.meta.url);
+        // New format: modules as array of package names or ModuleEntry objects
+        if (this.settings.modules) {
+            for (const entry of this.settings.modules) {
+                if (typeof entry === 'string') {
+                    const resolvedPath = require.resolve(entry, { paths: [process.cwd()] });
+                    moduleEntries.push({ rootPath: resolvedPath + '/..', name: entry });
+                }
+                else {
+                    const resolvedPath = entry.path ?? require.resolve(entry.name, { paths: [process.cwd()] });
+                    moduleEntries.push({
+                        rootPath: resolvedPath + '/..',
+                        options: entry.config,
+                        name: entry.name,
+                    });
+                }
+            }
+        }
+        // Backwards compat: old bundles format
         if (this.settings.bundles && this.settings.bundles.length > 0) {
             for (const bundle of this.settings.bundles) {
-                moduleEntries.push({
-                    rootPath: bundle.path,
-                    options: bundle.options,
-                });
+                if (typeof bundle === 'string') {
+                    const resolvedPath = require.resolve(bundle, { paths: [process.cwd()] });
+                    moduleEntries.push({ rootPath: resolvedPath + '/..', name: bundle });
+                }
+                else {
+                    moduleEntries.push({
+                        rootPath: bundle.path,
+                        options: bundle.options,
+                    });
+                }
             }
         }
         moduleEntries.push({

package/dist/definitions/FrameworkSettings.d.ts

@@ -1,4 +1,4 @@
 /**
  * @deprecated
  */
-export { FrameworkSettings } from "./settings/FrameworkSettings";
+export { FrameworkSettings, ModuleEntry } from "./settings/FrameworkSettings";

package/dist/definitions/Module.d.ts

@@ -19,6 +19,7 @@ export type ModuleDeclaration = {
 export declare abstract class Module {
     protected path: string;
     protected parameters: ModuleParameters;
+    protected moduleConfig: Record<string, any>;
     protected framework: ZumitoFramework;
     protected events: Map<string, FrameworkEvent>;
     static moduleName?: string;

package/dist/definitions/Module.js

@@ -9,6 +9,7 @@ import { getModelMetadata } from 'zumito-db';
 export class Module {
     path;
     parameters;
+    moduleConfig;
     framework;
     events = new Map();
     static moduleName;
@@ -21,6 +22,7 @@ export class Module {
         this.parameters = parameters;
         this.framework = ServiceContainer.getService(ZumitoFramework);
         this.errorHandler = ServiceContainer.getService(ErrorHandler);
+        this.moduleConfig = parameters ?? {};
     }
     async initialize() {
         await this.registerCommands();

package/dist/definitions/config/defineConfig.d.ts

@@ -0,0 +1,9 @@
+import type { LauncherConfig } from './LauncherConfig.js';
+/**
+ * Type-safe helper for writing `zumito.config.ts`.
+ * Provides autocompletion for all framework settings and module-specific
+ * configs contributed via declaration merging on `ModuleConfigs`.
+ *
+ * Does not modify the config object — it's a pure identity function.
+ */
+export declare function defineConfig(config: LauncherConfig): LauncherConfig;

package/dist/definitions/config/defineConfig.js

@@ -0,0 +1,10 @@
+/**
+ * Type-safe helper for writing `zumito.config.ts`.
+ * Provides autocompletion for all framework settings and module-specific
+ * configs contributed via declaration merging on `ModuleConfigs`.
+ *
+ * Does not modify the config object — it's a pure identity function.
+ */
+export function defineConfig(config) {
+    return config;
+}

package/dist/definitions/config/moduleHelpers.d.ts

@@ -0,0 +1,32 @@
+import { ZumitoFramework } from '../../ZumitoFramework.js';
+import type { ModuleEntry } from '../settings/FrameworkSettings.js';
+/**
+ * Creates a type-safe factory function that returns a `ModuleEntry`.
+ * Reads the module name from the nearest `package.json` by walking up
+ * from the caller's location.
+ *
+ * @example
+ * ```ts
+ * // admin/index.ts
+ * export const adminModule = createModuleEntry<AdminConfig>(import.meta.url);
+ *
+ * // Consumer's zumito.config.ts
+ * adminModule({ colors: { primary: '#ff0000' } })
+ * ```
+ */
+export declare function createModuleEntry<T = Record<string, any>>(metaUrl: string): (config?: T) => ModuleEntry;
+/**
+ * Retrieves the module-specific configuration from the framework settings
+ * by matching the module's package name against the `modules` array.
+ *
+ * Modules that are registered as plain strings in the `modules` array
+ * (without config) will return an empty object.
+ *
+ * @example
+ * ```ts
+ * import { getModuleConfig } from 'zumito-framework';
+ *
+ * const config = getModuleConfig<MyConfig>(framework, import.meta.url);
+ * ```
+ */
+export declare function getModuleConfig<T = Record<string, any>>(framework: ZumitoFramework | undefined, metaUrl: string): T;

package/dist/definitions/config/moduleHelpers.js

@@ -0,0 +1,71 @@
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { existsSync } from 'fs';
+function findPackageJson(startPath) {
+    let dir = startPath;
+    for (let i = 0; i < 10; i++) {
+        const candidate = resolve(dir, 'package.json');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+function readModuleName(metaUrl) {
+    const filePath = fileURLToPath(metaUrl);
+    const callerDir = dirname(filePath);
+    const pkgPath = findPackageJson(callerDir);
+    if (!pkgPath)
+        return null;
+    const require = createRequire(pkgPath);
+    return require(pkgPath)?.name ?? null;
+}
+/**
+ * Creates a type-safe factory function that returns a `ModuleEntry`.
+ * Reads the module name from the nearest `package.json` by walking up
+ * from the caller's location.
+ *
+ * @example
+ * ```ts
+ * // admin/index.ts
+ * export const adminModule = createModuleEntry<AdminConfig>(import.meta.url);
+ *
+ * // Consumer's zumito.config.ts
+ * adminModule({ colors: { primary: '#ff0000' } })
+ * ```
+ */
+export function createModuleEntry(metaUrl) {
+    const name = readModuleName(metaUrl);
+    if (!name) {
+        throw new Error(`createModuleEntry: could not read 'name' from package.json near ${metaUrl}`);
+    }
+    return (config) => ({ name, config });
+}
+/**
+ * Retrieves the module-specific configuration from the framework settings
+ * by matching the module's package name against the `modules` array.
+ *
+ * Modules that are registered as plain strings in the `modules` array
+ * (without config) will return an empty object.
+ *
+ * @example
+ * ```ts
+ * import { getModuleConfig } from 'zumito-framework';
+ *
+ * const config = getModuleConfig<MyConfig>(framework, import.meta.url);
+ * ```
+ */
+export function getModuleConfig(framework, metaUrl) {
+    if (!framework)
+        return {};
+    const name = readModuleName(metaUrl);
+    if (!name)
+        return {};
+    const modules = framework.settings?.modules ?? [];
+    const entry = modules.find((m) => typeof m !== 'string' && m.name === name);
+    return (entry?.config ?? {});
+}

package/dist/definitions/parameters/ModuleParameters.d.ts

@@ -1,7 +1,11 @@
+/**
+ * Module parameters passed to the Module constructor.
+ * Includes base framework fields plus any module-specific config.
+ */
 export type ModuleParameters = {
+    path?: string;
     commandWhitelist?: string[];
     commandBlacklist?: string[];
-    commandRenames?: {
-        [key: string]: string;
-    };
+    commandRenames?: Record<string, string>;
+    [key: string]: any;
 };

package/dist/definitions/settings/FrameworkSettings.d.ts

@@ -1,6 +1,17 @@
-import { ModuleParameters } from "../parameters/ModuleParameters";
 import { StatusManagerOptions } from "../StatusManagerOptions";
 import type { DatabaseConfig } from 'zumito-db';
+/**
+ * A module entry returned by a module factory function like `adminModule()`.
+ * Provides typed configuration and optional path override.
+ */
+export interface ModuleEntry {
+    /** Package name or module identifier (e.g., '@zumito-team/admin-module'). */
+    name: string;
+    /** Module-specific configuration. Typed by the factory function. */
+    config?: Record<string, any>;
+    /** Optional filesystem path override. Defaults to `require.resolve(name)`. */
+    path?: string;
+}
 export interface FrameworkSettings {
     mongoQueryString?: string;
     logLevel?: number;
@@ -18,10 +29,31 @@ export interface FrameworkSettings {
      * @experimental
      */
     srcMode?: 'multiBundle' | 'monoBundle' | undefined;
-    bundles?: {
+    /**
+     * @deprecated Use `modules` instead.
+     */
+    bundles?: (string | {
         path: string;
-        options?: ModuleParameters;
-    }[];
+        options?: Record<string, any>;
+    })[];
+    /**
+     * Modules to load. Each entry is either a package name string or a
+     * `ModuleEntry` object returned by a module factory function (e.g., `adminModule({...})`).
+     *
+     * Strings are resolved via `require.resolve()`.
+     * Factory functions provide type-safe autocompletion for module-specific config.
+     *
+     * @example
+     * ```ts
+     * import { adminModule } from '@zumito-team/admin-module';
+     *
+     * modules: [
+     *     adminModule({ colors: { primary: '#ff0000' } }),
+     *     '@zumito-team/canvas-module',
+     * ]
+     * ```
+     */
+    modules?: (string | ModuleEntry)[];
     webServer?: {
         port?: number;
         disableNotFoundHandler?: boolean;

package/dist/index.d.ts

@@ -41,5 +41,8 @@ export { ModalSubmitParameters } from './definitions/parameters/ModalSubmitParam
 export { CommandBinds } from './definitions/commands/CommandBinds.js';
 export { Injectable } from './definitions/decorators/Injectable.decorator.js';
 export { LauncherConfig } from './definitions/config/LauncherConfig.js';
+export { defineConfig } from './definitions/config/defineConfig.js';
+export { createModuleEntry, getModuleConfig } from './definitions/config/moduleHelpers.js';
+export type { ModuleEntry } from './definitions/settings/FrameworkSettings.js';
 export { ModuleParameters } from './definitions/parameters/ModuleParameters.js';
 export { ZumitoFramework, FrameworkSettings, Command, Module, ModuleDeclaration, ModuleRequeriments, CommandParameters, CommandArguments, FrameworkEvent, Translation, TranslationManager, ApiResponse, SelectMenuParameters, CommandType, CommandArgDefinition, CommandChoiceDefinition, ButtonPressed, ButtonPressedParams, TextFormatter, EmojiFallback, DatabaseConfigLoader, PresenceDataRule, RuledPresenceData, StatusManagerOptions, discord, EventParameters, ServiceContainer, GuildDataGetter, SlashCommandRefresher, CommandParser, ErrorHandler, ErrorType, Route, RouteMethod, InteractionHandler, CommandManager, InviteUrlGenerator, PrefixResolver, CommandExecutionChecker, DatabaseManager, };

package/dist/index.js

@@ -28,6 +28,8 @@ import { CommandExecutionChecker } from './services/CommandExecutionChecker.js';
 import { DatabaseManager } from 'zumito-db';
 export { Collection, Field, HasMany, BelongsTo, HasOne, Migration, Repository, QueryBuilder } from 'zumito-db';
 export { Injectable } from './definitions/decorators/Injectable.decorator.js';
+export { defineConfig } from './definitions/config/defineConfig.js';
+export { createModuleEntry, getModuleConfig } from './definitions/config/moduleHelpers.js';
 ServiceContainer.addService(TextFormatter, []);
 ServiceContainer.addService(EmojiFallback, [discord.Client.name, TranslationManager.name]);
 ServiceContainer.addService(GuildDataGetter, [ZumitoFramework.name]);

package/dist/launcher.js

@@ -29,7 +29,12 @@ if (!fs.existsSync(configFilePath)) {
     process.exit(1);
 }
 import(pathToFileURL(configFilePath).href)
-    .then(({ config: userConfig }) => {
+    .then((mod) => {
+    const userConfig = mod.config ?? mod.default;
+    if (!userConfig) {
+        console.error(`Config file at ${configFilePath} must export 'config' (named) or 'default' (default export).`);
+        process.exit(1);
+    }
     const config = RecursiveObjectMerger.merge(defaultConfig, userConfig);
     new ZumitoFramework(config, (bot) => {
         BotReadyLogger.log(bot);

package/dist/services/managers/CommandManager.js

@@ -42,6 +42,8 @@ export class CommandManager {
         if (!filePath.endsWith('.js') && !filePath.endsWith('.ts')) {
             return;
         }
+        if (filePath.endsWith('.d.ts'))
+            return;
         const counter = (this.importCounters.get(filePath) || 0) + 1;
         this.importCounters.set(filePath, counter);
         const baseName = path.basename(filePath).split('.').slice(0, -1).join('.');
@@ -62,6 +64,7 @@ export class CommandManager {
             return command;
         }
         catch (error) {
+            console.error('[🆕🔴 ] Error instanciating command ' + chalk.blue(baseName) + ' from ' + filePath);
             this.errorHandler.handleError(error, {
                 type: ErrorType.CommandInstance,
                 command: command,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zumito-framework",
-  "version": "1.23.2",
+  "version": "1.24.0",
   "description": "Discord.js bot framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -42,7 +42,7 @@
     "source-fragment": "^1.1.0",
     "tingodb": "^0.6.1",
     "tseep": "^1.2.2",
-    "zumito-db": "^2.0.3"
+    "zumito-db": "^2.0.4"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",