meocord 1.4.0 → 1.5.0-beta.1

package/README.md

@@ -18,6 +18,7 @@ While still growing, MeoCord provides a solid foundation for developers to creat
 - [Configuration](#configuration)
 - [CLI Usage](#cli-usage)
 - [Development Guide](#development-guide)
+- [Custom Decorators](#custom-decorators)
 - [Deployment Guide](#deployment-guide)
 - [Contributing](#contributing)
 - [License](#license)
@@ -484,6 +485,104 @@ Once built, you can deploy or run the application efficiently.
 
 ---
 
+## Custom Decorators
+
+MeoCord exports two helpers from `meocord/common` for building your own decorators: `applyDecorators` and `SetMetadata`.
+
+### `applyDecorators` — compose decorators into one
+
+Combine multiple existing decorators into a single reusable one. Useful for bundling a common guard pattern so you don't repeat it on every command.
+
+```typescript
+import { applyDecorators } from 'meocord/common'
+import { UseGuard } from 'meocord/decorator'
+import { DefaultGuard, GlobalRateLimiterGuard, RateLimiterGuard } from '@src/guards'
+
+// Reusable decorator that applies a standard guard stack
+export const Protected = () =>
+  applyDecorators(
+    UseGuard(DefaultGuard, GlobalRateLimiterGuard),
+  )
+
+// With configurable rate limit
+export const RateLimited = (limit: number) =>
+  applyDecorators(
+    UseGuard(DefaultGuard, { provide: RateLimiterGuard, params: { limit } }),
+  )
+```
+
+Usage on a controller:
+
+```typescript
+import { Controller } from 'meocord/decorator'
+import { Protected, RateLimited } from '@src/common/decorators'
+
+@Controller()
+export class ProfileController {
+  @Command('profile', CommandType.SLASH)
+  @Protected()
+  async profile(interaction: ChatInputCommandInteraction) { ... }
+
+  @Command('wish', CommandType.SLASH)
+  @RateLimited(3)
+  async wish(interaction: ChatInputCommandInteraction) { ... }
+}
+```
+
+### `SetMetadata` + custom guard — attach and read custom metadata
+
+Use `SetMetadata` to tag commands with arbitrary data, then read it inside a guard.
+
+**1. Define the metadata decorator:**
+
+```typescript
+import { SetMetadata } from 'meocord/common'
+
+export const Roles = (...roles: string[]) => SetMetadata('roles', roles)
+```
+
+**2. Read it in a guard:**
+
+```typescript
+import { Guard } from 'meocord/decorator'
+import { type GuardInterface } from 'meocord/interface'
+import type { ChatInputCommandInteraction } from 'discord.js'
+
+@Guard()
+export class RolesGuard implements GuardInterface {
+  async canActivate(interaction: ChatInputCommandInteraction): Promise<boolean> {
+    const required: string[] = Reflect.getMetadata('roles', interaction.constructor) ?? []
+    if (!required.length) return true
+
+    const memberRoles = interaction.member?.roles
+    // ... check member has at least one required role
+    return true
+  }
+}
+```
+
+**3. Apply both on a command:**
+
+```typescript
+import { applyDecorators } from 'meocord/common'
+import { UseGuard } from 'meocord/decorator'
+
+export const RequireRoles = (...roles: string[]) =>
+  applyDecorators(
+    Roles(...roles),
+    UseGuard(RolesGuard),
+  )
+
+@Controller()
+export class AdminController {
+  @Command('ban', CommandType.SLASH)
+  @RequireRoles('admin', 'moderator')
+  async ban(interaction: ChatInputCommandInteraction) { ... }
+}
+```
+
+---
+
 ## Deployment Guide
 
 Install all necessary dependencies, including development dependencies, before building:
@@ -571,6 +670,12 @@ Thank you for helping make **MeoCord** better!
 
 ---
 
+## Release Notes
+
+Full release history is available on the [GitHub Releases](https://github.com/l7aromeo/meocord/releases) page.
+
+---
+
 ## License
 
 **MeoCord Framework** is licensed under the [MIT License](./LICENSE).

package/dist/cjs/_shared/controller.decorator-CnSCBkOa.cjs

@@ -0,0 +1,215 @@
+'use strict';
+
+require('reflect-metadata');
+var inversify = require('inversify');
+var discord_js = require('discord.js');
+var enum_index = require('../enum/index.cjs');
+
+const COMMAND_METADATA_KEY = Symbol('commands');
+const MESSAGE_HANDLER_METADATA_KEY = Symbol('message_handlers');
+const REACTION_HANDLER_METADATA_KEY = Symbol('reaction_handlers');
+/**
+ * Decorator to register message handlers in the controller.
+ *
+ * @param keyword - An optional keyword to filter messages this handler should respond to.
+ *
+ * @example
+ * ```typescript
+ * @MessageHandler('hello')
+ * async handleHelloMessage(message: Message) {
+ *   await message.reply('Hello! How can I help you?');
+ * }
+ *
+ * @MessageHandler()
+ * async handleAnyMessage(message: Message) {
+ *   console.log(`Received a message: ${message.content}`);
+ * }
+ * ```
+ */ function MessageHandler(keyword) {
+    return function(target, propertyKey, _descriptor) {
+        const handlers = Reflect.getMetadata(MESSAGE_HANDLER_METADATA_KEY, target) || [];
+        handlers.push({
+            keyword,
+            method: propertyKey.toString()
+        });
+        Reflect.defineMetadata(MESSAGE_HANDLER_METADATA_KEY, handlers, target);
+    };
+}
+/**
+ * Decorator to register reaction handlers in the controller.
+ *
+ * @param emoji - Optional emoji name to filter reactions this handler should respond to.
+ *
+ * @example
+ * ```typescript
+ * @ReactionHandler('👍')
+ * async handleThumbsUpReaction(reaction: MessageReaction, { user }: ReactionHandlerOptions) {
+ *   console.log(`User ${user.username} reacted with 👍`);
+ * }
+ *
+ * @ReactionHandler()
+ * async handleAnyReaction(reaction: MessageReaction, { user }: ReactionHandlerOptions) {
+ *   console.log(`User ${user.username} reacted with ${reaction.emoji.name}`);
+ * }
+ * ```
+ */ function ReactionHandler(emoji) {
+    return function(target, propertyKey, _descriptor) {
+        const handlers = Reflect.getMetadata(REACTION_HANDLER_METADATA_KEY, target) || [];
+        handlers.push({
+            emoji,
+            method: propertyKey.toString()
+        });
+        Reflect.defineMetadata(REACTION_HANDLER_METADATA_KEY, handlers, target);
+    };
+}
+/**
+ * Retrieves reaction handlers metadata from a given controller.
+ *
+ * @param controller - The controller class instance.
+ * @returns An array of reaction handler metadata objects.
+ */ function getReactionHandlers(controller) {
+    return Reflect.getMetadata(REACTION_HANDLER_METADATA_KEY, controller) || [];
+}
+/**
+ * Retrieves message handlers metadata from a given controller.
+ *
+ * @param controller - The controller class instance.
+ * @returns An array of message handler method names.
+ */ function getMessageHandlers(controller) {
+    return Reflect.getMetadata(MESSAGE_HANDLER_METADATA_KEY, controller) || [];
+}
+/**
+ * Helper function to create regex and parameter mappings from a pattern string.
+ *
+ * @param pattern - The pattern string to parse.
+ * @returns An object containing the generated regex and parameter names.
+ */ function createRegexFromPattern(pattern) {
+    const params = [];
+    // Escape special characters except for {} and -
+    const escapedPattern = pattern.replace(/[/\\^$*+?.()|[\]]/g, '\\$&') // Removed hyphen `-` from this list
+    ;
+    // Replace placeholders with named capturing groups
+    const regexPattern = escapedPattern.replace(/\{(\w+)}/g, (_, param)=>{
+        if (!/^\w+$/.test(param)) {
+            throw new Error(`Invalid parameter name: ${param}. Parameter names must be alphanumeric.`);
+        }
+        params.push(param);
+        return `(?<${param}>[a-zA-Z0-9]+)`;
+    });
+    // Construct the final regex
+    const regex = new RegExp(`^${regexPattern}$`);
+    return {
+        regex,
+        params
+    };
+}
+/**
+ * Decorator to register command methods in a controller.
+ *
+ * @param commandName - The name or pattern of the command.
+ * @param builderOrType - A command builder class or a command type from `CommandType`.
+ *
+ * @example
+ * ```typescript
+ * @Command('help', CommandType.SLASH)
+ * public async handleHelp(interaction: ChatInputCommandInteraction) {
+ *   await interaction.reply('This is the help command!')
+ * }
+ *
+ * @Command('stats-{id}', CommandType.BUTTON)
+ * public async handleStats(message: ButtonInteraction, { id }) {
+ *   await message.reply(`Fetching stats for ID: ${id}`);
+ * }
+ * ```
+ */ function Command(commandName, builderOrType) {
+    return function(target, propertyKey, _descriptor) {
+        const originalMethod = _descriptor.value;
+        if (!originalMethod) {
+            throw new Error(`Missing implementation for method ${propertyKey}`);
+        }
+        // Wrap original method for interaction type validation
+        _descriptor.value = function(interaction, params) {
+            const expectedInteraction = commandType === enum_index.CommandType.BUTTON && interaction instanceof discord_js.ButtonInteraction || commandType === enum_index.CommandType.SELECT_MENU && interaction instanceof discord_js.StringSelectMenuInteraction || commandType === enum_index.CommandType.SLASH && interaction instanceof discord_js.ChatInputCommandInteraction || commandType === enum_index.CommandType.CONTEXT_MENU && interaction instanceof discord_js.ContextMenuCommandInteraction || commandType === enum_index.CommandType.MODAL_SUBMIT && interaction instanceof discord_js.ModalSubmitInteraction;
+            if (!expectedInteraction) {
+                throw new Error(`Invalid interaction type passed to @Command for method: ${propertyKey}`);
+            }
+            return originalMethod.apply(this, [
+                interaction,
+                params
+            ]);
+        };
+        // Retrieve existing metadata or initialize it
+        const commands = Reflect.getMetadata(COMMAND_METADATA_KEY, target) || {};
+        let builderInstance;
+        let commandType;
+        let regex;
+        let dynamicParams = [];
+        // Determine command type and builder
+        if (typeof builderOrType === 'function') {
+            const builderObj = new builderOrType();
+            builderInstance = builderObj.build(commandName);
+            commandType = Reflect.getMetadata(enum_index.MetadataKey.CommandType, builderOrType);
+            if (!(commandType in enum_index.CommandType)) {
+                throw new Error(`Metadata for 'commandType' is missing on builder ${builderOrType.name}`);
+            }
+        } else {
+            commandType = builderOrType;
+        }
+        if (commandType !== enum_index.CommandType.SLASH && commandType !== enum_index.CommandType.CONTEXT_MENU) {
+            const { regex: generatedRegex, params } = createRegexFromPattern(commandName);
+            regex = generatedRegex;
+            dynamicParams = params;
+        }
+        // Ensure commandName supports multiple entries
+        if (!commands[commandName]) {
+            commands[commandName] = [];
+        }
+        commands[commandName].push({
+            methodName: propertyKey,
+            builder: builderInstance,
+            type: commandType,
+            regex,
+            dynamicParams
+        });
+        Reflect.defineMetadata(COMMAND_METADATA_KEY, commands, target);
+    };
+}
+/**
+ * Retrieves the command map for a given controller.
+ *
+ * @param controller - The controller class instance.
+ * @returns A record containing command metadata indexed by command names.
+ */ function getCommandMap(controller) {
+    return Reflect.getMetadata(COMMAND_METADATA_KEY, controller);
+}
+/**
+ * Decorator to mark a class as a controller that can later be registered to the App class `(app.ts)` using the `@MeoCord` decorator.
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class PingSlashController {
+ *   constructor(private pingService: PingService) {}
+ *
+ *   @Command('ping', PingCommandBuilder)
+ *   async ping(interaction: ChatInputCommandInteraction) {
+ *     const response = await this.pingService.handlePing()
+ *     await interaction.reply(response)
+ *   }
+ * }
+ * ```
+ */ function Controller() {
+    return function(target) {
+        if (!Reflect.hasMetadata(enum_index.MetadataKey.Injectable, target)) {
+            inversify.injectable()(target);
+        }
+    };
+}
+
+exports.Command = Command;
+exports.Controller = Controller;
+exports.MessageHandler = MessageHandler;
+exports.ReactionHandler = ReactionHandler;
+exports.getCommandMap = getCommandMap;
+exports.getMessageHandlers = getMessageHandlers;
+exports.getReactionHandlers = getReactionHandlers;

package/dist/cjs/common/index.cjs

@@ -10,7 +10,57 @@ require('fs');
 require('jiti');
 require('chalk');
 
-
+/**
+ * MeoCord Framework
+ * Copyright (c) 2025 Ukasyah Rahmatullah Zada
+ * SPDX-License-Identifier: MIT
+ */ /**
+ * Composes multiple class or method decorators into a single decorator.
+ *
+ * @example
+ * ```typescript
+ * export const Protected = () => applyDecorators(
+ *   UseGuard(DefaultGuard, GlobalRateLimiterGuard),
+ * )
+ *
+ * @Controller()
+ * @Protected()
+ * export class PingController {}
+ * ```
+ */ function applyDecorators(...decorators) {
+    return function(target, propertyKey, descriptor) {
+        for (const decorator of decorators){
+            if (propertyKey !== undefined && descriptor !== undefined) {
+                decorator(target, propertyKey, descriptor);
+            } else {
+                decorator(target);
+            }
+        }
+        return descriptor;
+    };
+}
+/**
+ * Attaches arbitrary metadata to a class or method. Use alongside `Reflect.getMetadata` to read it back.
+ *
+ * @example
+ * ```typescript
+ * export const Roles = (...roles: string[]) => SetMetadata('roles', roles)
+ *
+ * @Command('admin', CommandType.SLASH)
+ * @Roles('admin', 'moderator')
+ * async adminCommand(interaction: ChatInputCommandInteraction) {}
+ * ```
+ */ function SetMetadata(metadataKey, metadataValue) {
+    return function(target, propertyKey) {
+        if (propertyKey !== undefined) {
+            Reflect.defineMetadata(metadataKey, metadataValue, target, propertyKey);
+        } else {
+            Reflect.defineMetadata(metadataKey, metadataValue, target);
+        }
+    };
+}
 
 exports.Logger = theme.Logger;
 exports.Theme = theme.Theme;
+exports.SetMetadata = SetMetadata;
+exports.applyDecorators = applyDecorators;