meocord 3.0.0 → 3.2.0

package/dist/esm/bin/app-template/README.md.template

@@ -0,0 +1,61 @@
+# {{displayName}}
+
+A Discord bot built with [MeoCord](https://github.com/l7aromeo/meocord).
+
+## Setup
+
+Copy the example environment file and add your bot token:
+
+```shell
+cp .env.example .env
+```
+
+`.env` is gitignored. Never commit a real token — if one is pushed, reset it in the
+[Discord developer portal](https://discord.com/developers/applications) rather than
+rewriting history.
+
+## Running
+
+```shell
+{{packageManager}} run start:dev    # watch mode, rebuilds and restarts on change
+{{packageManager}} run start:prod   # production
+```
+
+The bot runs on whichever runtime you launch it with — launch with bun and it is a bun
+process, launch with node and it is a node process.
+
+## Building
+
+```shell
+{{packageManager}} run build:dev
+{{packageManager}} run build:prod
+```
+
+## Generating components
+
+```shell
+npx meocord g co slash "profile"     # a slash controller, its spec and its builder
+npx meocord g s "profile"            # a service
+npx meocord g gu "rate-limit"        # a guard
+npx meocord g --help                 # every generator
+```
+
+Register whatever you generate in the `controllers` array in `src/app.ts` — controllers
+are wired up by that list, not by where they sit on disk.
+
+## Testing
+
+```shell
+{{packageManager}} run test
+{{packageManager}} run test:coverage
+```
+
+`meocord/testing` provides `MeoCordTestingModule` for building a controller with its
+dependencies, plus `createMockInteraction` and friends for driving it without a Discord
+connection.
+
+## Linting
+
+```shell
+{{packageManager}} run lint
+```

package/dist/esm/bin/app-template/_env.example.template

@@ -0,0 +1,2 @@
+# Copy to .env and fill in. Never commit the real token.
+DISCORD_TOKEN=

package/dist/esm/bin/app-template/_gitignore.template

@@ -0,0 +1,22 @@
+dist
+coverage
+
+/node_modules
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+.idea
+.vscode/*
+
+.env*
+!.env.example
+.DS_Store

package/dist/esm/bin/app-template/_prettierrc.mjs.template

@@ -0,0 +1,10 @@
+export default {
+  bracketSpacing: true,
+  bracketSameLine: true,
+  singleQuote: true,
+  trailingComma: 'all',
+  arrowParens: 'avoid',
+  semi: false,
+  endOfLine: 'lf',
+  printWidth: 120,
+}

package/dist/esm/bin/app-template/eslint.config.ts.template

@@ -0,0 +1,25 @@
+import unusedImports from 'eslint-plugin-unused-imports'
+import meocordESLint, { typescriptConfig } from 'meocord/eslint'
+
+const customConfig = {
+  ...typescriptConfig,
+  plugins: {
+    ...typescriptConfig.plugins,
+    'unused-imports': unusedImports,
+  },
+  rules: {
+    ...typescriptConfig.rules,
+    'unused-imports/no-unused-imports': 'error',
+    'unused-imports/no-unused-vars': [
+      'error',
+      {
+        vars: 'all',
+        varsIgnorePattern: '^_',
+        args: 'after-used',
+        argsIgnorePattern: '^_',
+      },
+    ],
+  },
+}
+
+export default [...meocordESLint, customConfig]

package/dist/esm/bin/app-template/meocord.config.ts.template

@@ -0,0 +1,25 @@
+import 'dotenv/config'
+import { type MeoCordConfig } from 'meocord/interface'
+
+export default {
+  appName: '{{displayName}}',
+  // Read from the environment rather than written here: this file is committed, and a
+  // token pasted into it is a token pushed to the remote. Copy .env.example to .env.
+  discordToken: process.env.DISCORD_TOKEN!,
+  webpack: config => {
+    config.module.rules?.push({
+      test: /\.(md|html)$/i,
+      type: 'asset/source',
+    })
+    config.module.rules?.push({
+      test: /\.(gif|jpg|jpeg|png|svg|woff|woff2|eot|ttf|otf)$/i,
+      type: 'asset/resource',
+      exclude: /node_modules/,
+      generator: {
+        filename: 'assets/[name][ext]',
+      },
+    })
+
+    return config
+  },
+} satisfies MeoCordConfig

package/dist/esm/bin/app-template/package.json.template

@@ -0,0 +1,38 @@
+{
+  "name": "{{appName}}",
+  "version": "0.1.0",
+  "description": "",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build:dev": "{{runtimePrefix}}meocord build --dev",
+    "build:prod": "{{runtimePrefix}}meocord build --prod",
+    "start:dev": "{{runtimePrefix}}meocord start --dev",
+    "start:prod": "{{runtimePrefix}}meocord start --prod",
+    "lint": "eslint --fix && tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "discord.js": "^14.27.0",
+    "dotenv": "^17.2.4",
+    "meocord": "^{{version}}"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@typescript-eslint/parser": "^8.58.1",
+    "@vitest/coverage-istanbul": "^4.1.10",
+    "eslint": "^10.2.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import-x": "^4.16.2",
+    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-unused-imports": "^4.4.1",
+    "globals": "^17.5.0",
+    "prettier": "^3.8.2",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.1",
+    "unplugin-swc": "^1.5.7",
+    "vitest": "^4.1.10"
+  }
+}

package/dist/esm/bin/app-template/src/app.ts.template

@@ -0,0 +1,44 @@
+import { GatewayIntentBits, Partials, ActivityType } from 'discord.js'
+import { MeoCord } from 'meocord/decorator'
+import { SampleSlashController } from '@src/controllers/slash/sample.slash.controller'
+import { SampleSelectMenuController } from '@src/controllers/select-menu/sample.select-menu.controller'
+import { SampleButtonController } from '@src/controllers/button/sample.button.controller'
+import { SampleMessageController } from '@src/controllers/message/sample.message.controller'
+import { SampleReactionController } from '@src/controllers/reaction/sample.reaction.controller'
+import { SampleContextMenuController } from '@src/controllers/context-menu/sample.context-menu.controller'
+import { SampleModalSubmitController } from '@src/controllers/modal-submit/sample.modal-submit.controller'
+
+@MeoCord({
+  controllers: [
+    // Slash Commands
+    SampleSlashController,
+    // Select Menu
+    SampleSelectMenuController,
+    // Buttons
+    SampleButtonController,
+    // Message
+    SampleMessageController,
+    // Reactions
+    SampleReactionController,
+    // Context Menu
+    SampleContextMenuController,
+    // Modal Submit
+    SampleModalSubmitController,
+  ],
+  clientOptions: {
+    intents: [
+      GatewayIntentBits.Guilds,
+      GatewayIntentBits.GuildMessages,
+      GatewayIntentBits.GuildMessageReactions,
+      GatewayIntentBits.MessageContent,
+    ],
+    partials: [Partials.Message, Partials.Reaction],
+  },
+  activities: [
+    {
+      name: ``,
+      type: ActivityType.Custom,
+    },
+  ],
+})
+export default class App {}

package/dist/esm/bin/app-template/src/controllers/button/sample.button.controller.spec.ts.template

@@ -0,0 +1,17 @@
+import { MeoCordTestingModule } from 'meocord/testing'
+import { SampleButtonController } from '@src/controllers/button/sample.button.controller.js'
+
+describe('SampleButtonController', () => {
+  let controller: SampleButtonController
+
+  beforeEach(() => {
+    const module = MeoCordTestingModule.create({
+      controllers: [SampleButtonController],
+    }).compile()
+    controller = module.get(SampleButtonController)
+  })
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined()
+  })
+})

package/dist/esm/bin/app-template/src/controllers/button/sample.button.controller.ts.template

@@ -0,0 +1,19 @@
+import { ButtonInteraction } from 'discord.js'
+import { Controller, Command, UseGuard } from 'meocord/decorator'
+import { CommandType } from 'meocord/enum'
+import { RateLimitGuard } from '@src/guards/rate-limit.guard'
+
+@Controller()
+export class SampleButtonController {
+  @Command('button-click', CommandType.BUTTON)
+  @UseGuard(RateLimitGuard)
+  async handleButton(interaction: ButtonInteraction) {
+    await interaction.reply('Button clicked!')
+  }
+
+  @Command('button-with/{id}', CommandType.BUTTON)
+  @UseGuard({ provide: RateLimitGuard, params: { limit: 2, windowInSeconds: 60 } })
+  async handleButtonWithId(interaction: ButtonInteraction, { id }: { id: string }) {
+    await interaction.reply(`Button with id: ${id} clicked!`)
+  }
+}

package/dist/esm/bin/app-template/src/controllers/context-menu/builders/sample.builder.ts.template

@@ -0,0 +1,10 @@
+import { ContextMenuCommandBuilder, ApplicationCommandType } from 'discord.js'
+import { CommandBuilder } from 'meocord/decorator'
+import { CommandType } from 'meocord/enum'
+
+@CommandBuilder(CommandType.CONTEXT_MENU)
+export class SampleCommandBuilder {
+  build() {
+    return new ContextMenuCommandBuilder().setName('sample-context-menu').setType(ApplicationCommandType.User)
+  }
+}

package/dist/esm/bin/app-template/src/controllers/context-menu/sample.context-menu.controller.spec.ts.template

@@ -0,0 +1,17 @@
+import { MeoCordTestingModule } from 'meocord/testing'
+import { SampleContextMenuController } from '@src/controllers/context-menu/sample.context-menu.controller.js'
+
+describe('SampleContextMenuController', () => {
+  let controller: SampleContextMenuController
+
+  beforeEach(() => {
+    const module = MeoCordTestingModule.create({
+      controllers: [SampleContextMenuController],
+    }).compile()
+    controller = module.get(SampleContextMenuController)
+  })
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined()
+  })
+})

package/dist/esm/bin/app-template/src/controllers/context-menu/sample.context-menu.controller.ts.template

@@ -0,0 +1,13 @@
+import { UserContextMenuCommandInteraction, MessageContextMenuCommandInteraction } from 'discord.js'
+import { Controller, Command, UseGuard } from 'meocord/decorator'
+import { SampleCommandBuilder } from '@src/controllers/context-menu/builders/sample.builder'
+import { RateLimitGuard } from '@src/guards/rate-limit.guard'
+
+@Controller()
+export class SampleContextMenuController {
+  @Command('sample-context-menu', SampleCommandBuilder)
+  @UseGuard(RateLimitGuard)
+  async handleContextMenu(interaction: UserContextMenuCommandInteraction | MessageContextMenuCommandInteraction) {
+    await interaction.reply('This is sample reply of context menu command.')
+  }
+}

package/dist/esm/bin/app-template/src/controllers/message/sample.message.controller.spec.ts.template

@@ -0,0 +1,17 @@
+import { MeoCordTestingModule } from 'meocord/testing'
+import { SampleMessageController } from '@src/controllers/message/sample.message.controller.js'
+
+describe('SampleMessageController', () => {
+  let controller: SampleMessageController
+
+  beforeEach(() => {
+    const module = MeoCordTestingModule.create({
+      controllers: [SampleMessageController],
+    }).compile()
+    controller = module.get(SampleMessageController)
+  })
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined()
+  })
+})

package/dist/esm/bin/app-template/src/controllers/message/sample.message.controller.ts.template

@@ -0,0 +1,28 @@
+import { MessageHandler, Controller } from 'meocord/decorator'
+import { Message } from 'discord.js'
+import { Logger } from 'meocord/common'
+
+@Controller()
+export class SampleMessageController {
+  private readonly logger = new Logger(SampleMessageController.name)
+
+  @MessageHandler('baka')
+  @MessageHandler('Baka')
+  async baka(message: Message): Promise<void> {
+    try {
+      await message.reply(`You Baka!`)
+    } catch (error) {
+      this.logger.error('Error replying to command', error)
+    }
+  }
+
+  @MessageHandler()
+  async handleGeneralMessage(message: Message): Promise<void> {
+    try {
+      this.logger.info(`Received message: ${message.content}`)
+      // TODO: Implements your message handler logic here
+    } catch (error) {
+      this.logger.error('Error handling the message', error)
+    }
+  }
+}

package/dist/esm/bin/app-template/src/controllers/modal-submit/sample.modal-submit.controller.spec.ts.template

@@ -0,0 +1,17 @@
+import { MeoCordTestingModule } from 'meocord/testing'
+import { SampleModalSubmitController } from '@src/controllers/modal-submit/sample.modal-submit.controller.js'
+
+describe('SampleModalSubmitController', () => {
+  let controller: SampleModalSubmitController
+
+  beforeEach(() => {
+    const module = MeoCordTestingModule.create({
+      controllers: [SampleModalSubmitController],
+    }).compile()
+    controller = module.get(SampleModalSubmitController)
+  })
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined()
+  })
+})

package/dist/esm/bin/app-template/src/controllers/modal-submit/sample.modal-submit.controller.ts.template

@@ -0,0 +1,13 @@
+import { ModalSubmitInteraction } from 'discord.js'
+import { Controller, Command, UseGuard } from 'meocord/decorator'
+import { CommandType } from 'meocord/enum'
+import { RateLimitGuard } from '@src/guards/rate-limit.guard'
+
+@Controller()
+export class SampleModalSubmitController {
+  @Command('submit-modal', CommandType.MODAL_SUBMIT)
+  @UseGuard(RateLimitGuard)
+  async handleModal(interaction: ModalSubmitInteraction) {
+    await interaction.reply('Modal submitted!')
+  }
+}

package/dist/esm/bin/app-template/src/controllers/reaction/sample.reaction.controller.spec.ts.template

@@ -0,0 +1,17 @@
+import { MeoCordTestingModule } from 'meocord/testing'
+import { SampleReactionController } from '@src/controllers/reaction/sample.reaction.controller.js'
+
+describe('SampleReactionController', () => {
+  let controller: SampleReactionController
+
+  beforeEach(() => {
+    const module = MeoCordTestingModule.create({
+      controllers: [SampleReactionController],
+    }).compile()
+    controller = module.get(SampleReactionController)
+  })
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined()
+  })
+})

package/dist/esm/bin/app-template/src/controllers/reaction/sample.reaction.controller.ts.template

@@ -0,0 +1,29 @@
+import { MessageReaction } from 'discord.js'
+import { Controller, ReactionHandler } from 'meocord/decorator'
+import { Logger } from 'meocord/common'
+import { ReactionHandlerAction } from 'meocord/enum'
+import { type ReactionHandlerOptions } from 'meocord/interface'
+
+@Controller()
+export class SampleReactionController {
+  private readonly logger = new Logger(SampleReactionController.name)
+
+  @ReactionHandler('😋')
+  async handleReaction(reaction: MessageReaction, { user, action }: ReactionHandlerOptions) {
+    this.logger.log(`Reaction 😋 ${action === ReactionHandlerAction.ADD ? 'added' : 'removed'}.`)
+
+    if (!reaction.message) return
+
+    if (action === ReactionHandlerAction.ADD) {
+      await reaction.message.reply(`${user.username} reacted with 😋!`)
+    }
+  }
+
+  @ReactionHandler()
+  async handleAnyReaction(reaction: MessageReaction, { user, action }: ReactionHandlerOptions) {
+    this.logger.log('Reaction detected!')
+    if (reaction.message && action === ReactionHandlerAction.ADD) {
+      await reaction.message.reply(`${user.username} reacted with ${reaction.emoji.name}!`)
+    }
+  }
+}

package/dist/esm/bin/app-template/src/controllers/select-menu/sample.select-menu.controller.spec.ts.template

@@ -0,0 +1,17 @@
+import { MeoCordTestingModule } from 'meocord/testing'
+import { SampleSelectMenuController } from '@src/controllers/select-menu/sample.select-menu.controller.js'
+
+describe('SampleSelectMenuController', () => {
+  let controller: SampleSelectMenuController
+
+  beforeEach(() => {
+    const module = MeoCordTestingModule.create({
+      controllers: [SampleSelectMenuController],
+    }).compile()
+    controller = module.get(SampleSelectMenuController)
+  })
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined()
+  })
+})

package/dist/esm/bin/app-template/src/controllers/select-menu/sample.select-menu.controller.ts.template

@@ -0,0 +1,11 @@
+import { StringSelectMenuInteraction } from 'discord.js'
+import { Controller, Command } from 'meocord/decorator'
+import { CommandType } from 'meocord/enum'
+
+@Controller()
+export class SampleSelectMenuController {
+  @Command('select-menu', CommandType.SELECT_MENU)
+  async handleSelectMenu(interaction: StringSelectMenuInteraction) {
+    await interaction.reply('Select menu used!')
+  }
+}

package/dist/esm/bin/app-template/src/controllers/slash/builders/sample.builder.ts.template

@@ -0,0 +1,10 @@
+import { SlashCommandBuilder } from 'discord.js'
+import { CommandBuilder } from 'meocord/decorator'
+import { CommandType } from 'meocord/enum'
+
+@CommandBuilder(CommandType.SLASH)
+export class SampleCommandBuilder {
+  build(commandName: string) {
+    return new SlashCommandBuilder().setName(commandName).setDescription('This is a sample slash command')
+  }
+}

package/dist/esm/bin/app-template/src/controllers/slash/sample.slash.controller.spec.ts.template

@@ -0,0 +1,17 @@
+import { MeoCordTestingModule } from 'meocord/testing'
+import { SampleSlashController } from '@src/controllers/slash/sample.slash.controller.js'
+
+describe('SampleSlashController', () => {
+  let controller: SampleSlashController
+
+  beforeEach(() => {
+    const module = MeoCordTestingModule.create({
+      controllers: [SampleSlashController],
+    }).compile()
+    controller = module.get(SampleSlashController)
+  })
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined()
+  })
+})

package/dist/esm/bin/app-template/src/controllers/slash/sample.slash.controller.ts.template

@@ -0,0 +1,19 @@
+import { ChatInputCommandInteraction } from 'discord.js'
+import { Controller, Command, UseGuard } from 'meocord/decorator'
+import { SampleCommandBuilder } from '@src/controllers/slash/builders/sample.builder'
+import { RateLimitGuard } from '@src/guards/rate-limit.guard'
+
+@Controller()
+export class SampleSlashController {
+  @Command('sample-slash', SampleCommandBuilder)
+  @UseGuard(RateLimitGuard)
+  async handleSampleSlash(interaction: ChatInputCommandInteraction) {
+    await interaction.reply('This is sample reply of slash command.')
+  }
+
+  @Command('sample-slash-2', SampleCommandBuilder)
+  @UseGuard({ provide: RateLimitGuard, params: { limit: 2, windowInSeconds: 60 } })
+  async handleSampleSlashTwo(interaction: ChatInputCommandInteraction) {
+    await interaction.reply('This is sample reply of slash command.')
+  }
+}

package/dist/esm/bin/app-template/src/guards/rate-limit.guard.spec.ts.template

@@ -0,0 +1,13 @@
+import { RateLimitGuard } from '@src/guards/rate-limit.guard.js'
+
+describe('RateLimitGuard', () => {
+  let guard: RateLimitGuard
+
+  beforeEach(() => {
+    guard = new RateLimitGuard({ limit: 3, windowInSeconds: 60 })
+  })
+
+  it('should be defined', () => {
+    expect(guard).toBeDefined()
+  })
+})

package/dist/esm/bin/app-template/src/guards/rate-limit.guard.ts.template

@@ -0,0 +1,52 @@
+import { Guard } from 'meocord/decorator'
+import { type GuardInterface } from 'meocord/interface'
+import { BaseInteraction } from 'discord.js'
+import { Logger } from 'meocord/common'
+
+class RateLimiterGuardOptions {
+  limit?: number
+  windowInSeconds?: number
+}
+
+@Guard()
+export class RateLimitGuard implements GuardInterface {
+  // ==============================
+  // NOTE: Consider using Redis or another distributed store for rate limits in production
+  // ==============================
+  private logger = new Logger(RateLimitGuard.name)
+
+  private rateLimits = new Map<string, number[]>()
+  private readonly limit: number
+  private readonly windowInSeconds: number
+
+  constructor(options: RateLimiterGuardOptions = {}) {
+    this.limit = options.limit || 5
+    this.windowInSeconds = options.windowInSeconds || 60
+  }
+
+  async canActivate(interaction: BaseInteraction): Promise<boolean> {
+    const userId = interaction.user.id
+
+    let key: string
+    if (interaction.isChatInputCommand()) {
+      const commandId = interaction.commandName
+      const subCommand = interaction.options.getSubcommand(false) || ''
+      key = subCommand ? `${commandId}:${subCommand}:${userId}` : `${commandId}:${userId}`
+    } else if (interaction.isMessageComponent()) {
+      key = `${interaction.customId}:${userId}`
+    } else {
+      key = userId
+    }
+
+    const currentTime = Math.floor(Date.now() / 1000)
+    const timestamps = this.rateLimits.get(key) || []
+
+    const filteredTimestamps = timestamps.filter(time => currentTime - time < this.windowInSeconds)
+    filteredTimestamps.push(currentTime)
+    this.rateLimits.set(key, filteredTimestamps)
+
+    this.logger.debug(key, filteredTimestamps.length, this.limit, this.windowInSeconds)
+
+    return filteredTimestamps.length <= this.limit
+  }
+}

package/dist/esm/bin/app-template/src/main.ts.template

@@ -0,0 +1,14 @@
+import App from '@src/app'
+import { Logger } from 'meocord/common'
+import { MeoCordFactory } from 'meocord/core'
+
+const logger = new Logger()
+const app = MeoCordFactory.create(App)
+
+async function bootstrap() {
+  logger.log('Starting application')
+  await app.start()
+  logger.log('Application started')
+}
+
+bootstrap().catch(error => logger.error('Error during startup:', error))

package/dist/esm/bin/app-template/src/services/sample.service.spec.ts.template

@@ -0,0 +1,17 @@
+import { MeoCordTestingModule } from 'meocord/testing'
+import { SampleService } from '@src/services/sample.service.js'
+
+describe('SampleService', () => {
+  let service: SampleService
+
+  beforeEach(() => {
+    const module = MeoCordTestingModule.create({
+      providers: [{ provide: SampleService, useClass: SampleService }],
+    }).compile()
+    service = module.get(SampleService)
+  })
+
+  it('should be defined', () => {
+    expect(service).toBeDefined()
+  })
+})

package/dist/esm/bin/app-template/src/services/sample.service.ts.template

@@ -0,0 +1,9 @@
+import { Service } from 'meocord/decorator'
+
+@Service()
+export class SampleService {
+  async handleInteraction() {
+    // TODO: Implement service logic
+    return 'SampleService is working!'
+  }
+}

package/dist/esm/bin/app-template/tsconfig.eslint.json.template

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["meocord.eslint.ts", "meocord.config.ts", "vitest.config.ts", "eslint.config.ts"],
+  "exclude": ["node_modules"]
+}