chore(main): release 4.1.0 (#374)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [4.1.0](https://github.com/sern-handler/handler/compare/v4.0.3...v4.1.0) (2025-01-06)
+
+
+### Features
+
+* moduleinfo-in-eventplugins ([#373](https://github.com/sern-handler/handler/issues/373)) ([220a60e](https://github.com/sern-handler/handler/commit/220a60ecf853df8d288de2533c669562a430c3f9))
+
+
+### Bug Fixes
+
+* update github username ([#371](https://github.com/sern-handler/handler/issues/371)) ([55715d5](https://github.com/sern-handler/handler/commit/55715d565990fe686159f3c1eda3754d1262c72c))
+
+## [4.0.3](https://github.com/sern-handler/handler/compare/v4.0.2...v4.0.3) (2024-10-06)
+
+
+### Bug Fixes
+
+* async presence ([#369](https://github.com/sern-handler/handler/issues/369)) ([eabfb81](https://github.com/sern-handler/handler/commit/eabfb81819b53a4656d8eac6e21cfb488b724a42))
+* fix eventModule typing for Discord events ([#368](https://github.com/sern-handler/handler/issues/368)) ([1789ccb](https://github.com/sern-handler/handler/commit/1789ccb2f22f502f87538fecdb07106ff7110434))
+
 ## [4.0.2](https://github.com/sern-handler/handler/compare/v4.0.1...v4.0.2) (2024-08-13)
 
 

README.md

@@ -49,7 +49,7 @@ export default commandModule({
 - [Vinci](https://github.com/SrIzan10/vinci), the bot for Mara Turing.
 - [Bask](https://github.com/baskbotml/bask), Listen your favorite artists on Discord.
 - [Murayama](https://github.com/murayamabot/murayama), :pepega:
-- [Protector (WIP)](https://github.com/needhamgary/Protector), Just a simple bot to help enhance a private minecraft server.
+- [Protector](https://github.com/GlitchApotamus/Protector), Just a simple bot to help enhance a private minecraft server.
 - [SmokinWeed 💨](https://github.com/Peter-MJ-Parker/sern-bud), A fun bot for a small - but growing - server.
 - [Man Nomic](https://github.com/jacoobes/man-nomic), A simple information bot to provide information to the nomic-ai discord community.
 - [Linear-Discord](https://github.com/sern-handler/linear-discord) Display and manage a linear dashboard.

package.json

@@ -1,7 +1,7 @@
 {
     "name": "@sern/handler",
     "packageManager": "yarn@3.5.0",
-    "version": "4.0.2",
+    "version": "4.1.0",
     "description": "A complete, customizable, typesafe, & reactive framework for discord bots.",
     "main": "./dist/index.js",
     "module": "./dist/index.js",

src/core/modules.ts

@@ -10,8 +10,39 @@ import { partitionPlugins } from './functions'
 import type { Awaitable } from '../types/utility';
 
 /**
- * @since 1.0.0 The wrapper function to define command modules for sern
- * @param mod
+ * Creates a command module with standardized structure and plugin support.
+ * 
+ * @since 1.0.0
+ * @param {InputCommand} mod - Command module configuration
+ * @returns {Module} Processed command module ready for registration
+ * 
+ * @example
+ * // Basic slash command
+ * export default commandModule({
+ *   type: CommandType.Slash,
+ *   description: "Ping command",
+ *   execute: async (ctx) => {
+ *     await ctx.reply("Pong! 🏓");
+ *   }
+ * });
+ * 
+ * @example
+ * // Command with component interaction
+ * export default commandModule({
+ *   type: CommandType.Slash,
+ *   description: "Interactive command",
+ *   execute: async (ctx) => {
+ *     const button = new ButtonBuilder({
+ *       customId: "btn/someData",
+ *       label: "Click me",
+ *       style: ButtonStyle.Primary
+ *     });
+ *     await ctx.reply({
+ *       content: "Interactive message",
+ *       components: [new ActionRowBuilder().addComponents(button)]
+ *     });
+ *   }
+ * });
  */
 export function commandModule(mod: InputCommand): Module {
     const [onEvent, plugins] = partitionPlugins(mod.plugins);
@@ -21,12 +52,35 @@ export function commandModule(mod: InputCommand): Module {
              locals: {} } as Module;
 }
 
+
 /**
+ * Creates an event module for handling Discord.js or custom events.
+ * 
  * @since 1.0.0
- * The wrapper function to define event modules for sern
- * @param mod
+ * @template T - Event name from ClientEvents
+ * @param {InputEvent<T>} mod - Event module configuration
+ * @returns {Module} Processed event module ready for registration
+ * @throws {Error} If ControlPlugins are used in event modules
+ * 
+ * @example
+ * // Discord event listener
+ * export default eventModule({
+ *   type: EventType.Discord,
+ *   execute: async (message) => {
+ *     console.log(`${message.author.tag}: ${message.content}`);
+ *   }
+ * });
+ * 
+ * @example
+ * // Custom sern event
+ * export default eventModule({
+ *   type: EventType.Sern,
+ *   execute: async (eventData) => {
+ *     // Handle sern-specific event
+ *   }
+ * });
  */
-export function eventModule(mod: InputEvent): Module {
+export function eventModule<T extends keyof ClientEvents = keyof ClientEvents>(mod: InputEvent<T>): Module {
     const [onEvent, plugins] = partitionPlugins(mod.plugins);
     if(onEvent.length !== 0) throw Error("Event modules cannot have ControlPlugins");
     return { ...mod,
@@ -35,8 +89,9 @@ export function eventModule(mod: InputEvent): Module {
 }
 
 /** Create event modules from discord.js client events,
- * This is an {@link eventModule} for discord events,
- * where typings can be very bad.
+ * This was an {@link eventModule} for discord events,
+ * where typings were bad.
+ * @deprecated Use {@link eventModule} instead
  * @param mod
  */
 export function discordEvent<T extends keyof ClientEvents>(mod: {

src/core/plugin.ts

@@ -1,6 +1,7 @@
 import { CommandType, PluginType } from './structures/enums';
 import type { Plugin, PluginResult, CommandArgs, InitArgs } from '../types/core-plugin';
 import { Err, Ok } from './structures/result';
+import type { Dictionary } from '../types/utility';
 
 export function makePlugin<V extends unknown[]>(
     type: PluginType,
@@ -37,7 +38,7 @@ export function CommandControlPlugin<I extends CommandType>(
  * The object passed into every plugin to control a command's behavior
  */
 export const controller = {
-    next: (val?: Record<string,unknown>) => Ok(val),
+    next: (val?: Dictionary) => Ok(val),
     stop: (val?: string) => Err(val),
 };
 

src/core/presences.ts

@@ -1,11 +1,10 @@
 import type { ActivitiesOptions } from "discord.js";
 import type { IntoDependencies } from "./ioc";
 import type { Emitter } from "./interfaces";
+import { Awaitable } from "../types/utility";
 
 type Status = 'online' | 'idle' | 'invisible' | 'dnd'
-type PresenceReduce = (previous: Presence.Result) => Presence.Result;
-
-
+type PresenceReduce = (previous: Presence.Result) => Awaitable<Presence.Result>;
 
 export const Presence = {
     /**
@@ -50,7 +49,7 @@ export const Presence = {
 export declare namespace Presence {
     export type Config<T extends (keyof Dependencies)[]> = {
         inject?: [...T]
-        execute: (...v: IntoDependencies<T>) => Presence.Result;
+        execute: (...v: IntoDependencies<T>) => Awaitable<Presence.Result>;
 
     }
 
@@ -60,7 +59,7 @@ export declare namespace Presence {
         activities?: ActivitiesOptions[];
         shardId?: number[];
         repeat?: number | [Emitter, string];
-        onRepeat?: (previous: Result) => Result; 
+        onRepeat?: PresenceReduce 
     }
 }
 

src/handlers/event-utils.ts

@@ -241,7 +241,17 @@ export async function callInitPlugins(_module: Module, deps: Dependencies, emit?
 export async function callPlugins({ args, module, deps, params }: ExecutePayload) {
     let state = {};
     for(const plugin of module.onEvent??[]) {
-        const result = await plugin.execute(...args, { state, deps, params, type: module.type });
+        const executionContext  = {
+            state, 
+            deps,
+            params,
+            type: module.type,
+            module: { name: module.name,
+                      description: module.description,
+                      locals: module.locals,
+                      meta: module.meta }
+        };
+        const result = await plugin.execute(...args, executionContext);
         if(!result.ok) {
             return result;
         }
@@ -253,14 +263,26 @@ export async function callPlugins({ args, module, deps, params }: ExecutePayload
 }
 /**
  * Creates an executable task ( execute the command ) if all control plugins are successful
+ * this needs to go
  * @param onStop emits a failure response to the SernEmitter
  */
 export function intoTask(onStop: (m: Module) => unknown) {
-    const onNext = ({ args, module, deps, params }: ExecutePayload, state: Record<string, unknown>) => ({
-        module,
-        args: [...args, { state, deps, params, type: module.type }],
-        deps
-    });
+    const onNext = ({ args, module, deps, params }: ExecutePayload, state: Record<string, unknown>) => {
+        
+        return {
+            module,
+            args: [...args, { state,
+                              deps,
+                              params,
+                              type: module.type,
+                              module: { name: module.name,
+                                        description: module.description,
+                                        locals: module.locals,
+                                        meta: module.meta } }],
+            deps
+        }
+
+    };
     return createResultResolver({ onStop, onNext });
 }
 

src/handlers/presence.ts

@@ -1,4 +1,4 @@
-import { concatMap, from, interval, of, map, scan, startWith, fromEvent, take } from "rxjs"
+import { concatMap, from, interval, of, map, startWith, fromEvent, take, mergeScan } from "rxjs"
 import { Presence  } from "../core/presences";
 import { Services } from "../core/ioc";
 import assert from "node:assert";
@@ -14,7 +14,7 @@ const parseConfig = async (conf: Promise<Presence.Result>) => {
             const src$ = typeof repeat === 'number' 
                 ? interval(repeat)
                 : fromEvent(...repeat);
-                return src$.pipe(scan(onRepeat, s), 
+                return src$.pipe(mergeScan(async (args) => onRepeat(args), s), 
                                  startWith(s));
         }
         return of(s).pipe(take(1));

src/types/core-modules.ts

@@ -19,14 +19,97 @@ import type {
 import type { CommandType, EventType } from '../core/structures/enums';
 import { Context } from '../core/structures/context'
 import { ControlPlugin, InitPlugin, Plugin } from './core-plugin';
-import { Awaitable, SernEventsMapping, UnpackedDependencies } from './utility';
+import { Awaitable, SernEventsMapping, UnpackedDependencies, Dictionary } from './utility';
 
-//state, deps, type (very original)
+/**
+ * SDT (State, Dependencies, Type) interface represents the core data structure
+ * passed through the plugin pipeline to command modules.
+ * 
+ * @interface SDT
+ * @template TState - Type parameter for the state object's structure
+ * @template TDeps - Type parameter for dependencies interface
+ * 
+ * @property {Record<string, unknown>} state - Accumulated state data passed between plugins
+ * @property {TDeps} deps - Instance of application dependencies
+ * @property {CommandType} type - Command type identifier
+ * @property {string} [params] - Optional parameters passed to the command
+ * 
+ * @example
+ * // Example of a plugin using SDT
+ * const loggingPlugin = CommandControlPlugin((ctx, sdt: SDT) => {
+ *     console.log(`User ${ctx.user.id} executed command`);
+ *     return controller.next({ 'logging/timestamp': Date.now() });
+ * });
+ * 
+ * @example
+ * // Example of state accumulation through multiple plugins
+ * const plugin1 = CommandControlPlugin((ctx, sdt: SDT) => {
+ *     return controller.next({ 'plugin1/data': 'value1' });
+ * });
+ * 
+ * const plugin2 = CommandControlPlugin((ctx, sdt: SDT) => {
+ *     // Access previous state
+ *     const prevData = sdt.state['plugin1/data'];
+ *     return controller.next({ 'plugin2/data': 'value2' });
+ * });
+ * 
+ * @remarks
+ * - State is immutable and accumulated through the plugin chain
+ * - Keys in state should be namespaced to avoid collisions
+ * - Dependencies are injected and available throughout the pipeline
+ * - Type information helps plugins make type-safe decisions
+ * 
+ * @see {@link CommandControlPlugin} for plugin implementation
+ * @see {@link CommandType} for available command types
+ * @see {@link Dependencies} for dependency injection interface
+ */
 export type SDT = {
-    state: Record<string,unknown>;
+    /**
+     * Accumulated state passed between plugins in the pipeline.
+     * Each plugin can add to or modify this state using controller.next().
+     * 
+     * @type {Record<string, unknown>}
+     * @example
+     * // Good: Namespaced state key
+     * { 'myPlugin/userData': { id: '123', name: 'User' } }
+     * 
+     * // Avoid: Non-namespaced keys that might collide
+     * { userData: { id: '123' } }
+     */
+    state: Record<string, unknown>;
+
+    /**
+     * Application dependencies available to plugins and command modules.
+     * Typically includes services, configurations, and utilities.
+     * 
+     * @type {Dependencies}
+     */
     deps: Dependencies;
-    type: CommandType,
-    params?: string
+
+    /**
+     * Identifies the type of command being processed.
+     * Used by plugins to apply type-specific logic.
+     * 
+     * @type {CommandType}
+     */
+    type: CommandType;
+
+    /**
+     * Optional parameters passed to the command.
+     * May contain additional configuration or runtime data.
+     * 
+     * @type {string}
+     * @optional
+     */
+    params?: string;
+
+    /**
+     * A copy of the current module that the plugin is running in.
+     */
+    module: { name: string; 
+                  description: string;
+                  meta: Dictionary; 
+                  locals: Dictionary; }
 };
 
 export type Processed<T> = T & { name: string; description: string };
@@ -41,7 +124,75 @@ export interface Module {
         id: string;
         absPath: string;
     }
-    locals: Record<string,unknown>
+
+    /**
+     * Custom data storage object for module-specific information.
+     * Plugins and module code can use this to store and retrieve metadata,
+     * configuration, or any other module-specific information.
+     * 
+     * @type {Dictionary}
+     * @description A key-value store that allows plugins and module code to persist
+     * data at the module level. This is especially useful for InitPlugins that need
+     * to attach metadata or configuration to modules.
+     * 
+     * @example
+     * // In a plugin
+     * module.locals.registrationDate = Date.now();
+     * module.locals.version = "1.0.0";
+     * module.locals.permissions = ["ADMIN", "MODERATE"];
+     * 
+     * @example
+     * // In module execution
+     * console.log(`Command registered on: ${new Date(module.locals.registrationDate)}`);
+     * 
+     * @example
+     * // Storing localization data
+     * module.locals.translations = {
+     *   en: "Hello",
+     *   es: "Hola",
+     *   fr: "Bonjour"
+     * };
+     * 
+     * @example
+     * // Storing command metadata
+     * module.locals.metadata = {
+     *   category: "admin",
+     *   cooldown: 5000,
+     *   requiresPermissions: true
+     * };
+     * 
+     * @remarks
+     * - The locals object is initialized as an empty object ({}) by default
+     * - Keys should be namespaced to avoid collisions between plugins
+     * - Values can be of any type
+     * - Data persists for the lifetime of the module
+     * - Commonly used by InitPlugins during module initialization
+     * 
+     * @best-practices
+     * 1. Namespace your keys to avoid conflicts:
+     *    ```typescript
+     *    module.locals['myPlugin:data'] = value;
+     *    ```
+     * 
+     * 2. Document the data structure you're storing:
+     *    ```typescript
+     *    interface MyPluginData {
+     *      version: string;
+     *      timestamp: number;
+     *    }
+     *    module.locals['myPlugin:data'] = {
+     *      version: '1.0.0',
+     *      timestamp: Date.now()
+     *    } as MyPluginData;
+     *    ```
+     * 
+     * 3. Use type-safe accessors when possible:
+     *    ```typescript
+     *    const getPluginData = (module: Module): MyPluginData => 
+     *      module.locals['myPlugin:data'];
+     *    ```
+     */
+    locals: Dictionary;
     execute(...args: any[]): Awaitable<any>;
 }
 
@@ -167,9 +318,9 @@ export interface CommandModuleDefs {
     [CommandType.Modal]: ModalSubmitCommand;
 }
 
-export interface EventModuleDefs {
+export interface EventModuleDefs<T extends keyof ClientEvents = keyof ClientEvents> {
     [EventType.Sern]: SernEventCommand;
-    [EventType.Discord]: DiscordEventCommand;
+    [EventType.Discord]: DiscordEventCommand<T>;
     [EventType.External]: ExternalEventCommand;
 }
 
@@ -186,12 +337,12 @@ export interface SernAutocompleteData
 type CommandModuleNoPlugins = {
     [T in CommandType]: Omit<CommandModuleDefs[T], 'plugins' | 'onEvent' | 'meta' | 'locals'>;
 };
-type EventModulesNoPlugins = {
-    [T in EventType]: Omit<EventModuleDefs[T], 'plugins' | 'onEvent' | 'meta' | 'locals'> ;
+type EventModulesNoPlugins<K extends keyof ClientEvents = keyof ClientEvents> = {
+    [T in EventType]: Omit<EventModuleDefs<K>[T], 'plugins' | 'onEvent' | 'meta' | 'locals'> ;
 };
 
-export type InputEvent = {
-    [T in EventType]: EventModulesNoPlugins[T] & {
+export type InputEvent<K extends keyof ClientEvents = keyof ClientEvents> = {
+    [T in EventType]: EventModulesNoPlugins<K>[T] & {
         once?: boolean;
         plugins?: InitPlugin[] 
     };

src/types/utility.ts

@@ -3,6 +3,7 @@ import type { Module } from './core-modules';
 import type { Result } from '../core/structures/result';
 
 export type Awaitable<T> = PromiseLike<T> | T;
+export type Dictionary = Record<string, unknown>
 
 export type VoidResult = Result<void, void>;
 export type AnyFunction = (...args: any[]) => unknown;