meocord 1.8.4-beta.1 → 1.8.4

package/README.md

@@ -337,7 +337,21 @@ async ban(interaction: ChatInputCommandInteraction) { ... }
 
 ## Testing
 
-MeoCord ships a `meocord/testing` entry point with utilities for testing controllers in isolation — no real Discord connection required.
+MeoCord ships a `meocord/testing` entry point with utilities for testing controllers in isolation — no real Discord connection required. The framework repo runs tests with [Vitest](https://vitest.dev/); the mocks themselves are **framework-agnostic** and work with Vitest or Jest assertions (see below).
+
+### Running tests
+
+From the MeoCord repo root:
+
+```shell
+bun run test              # run once
+bun run test:watch        # watch mode
+bun run test:coverage     # coverage report
+bun run test:typecheck    # tsc -p tsconfig.test.json
+bun run lint              # eslint --fix + tsc
+```
+
+In your own bot project, add Vitest (or keep Jest) plus a `vitest.config.ts` with SWC if you use decorator metadata — see this repo's config for reference. Generated apps include `*.spec.ts` stubs but not a test runner config yet.
 
 ### `MeoCordTestingModule`
 
@@ -364,7 +378,7 @@ Creates a smart mock instance of any discord.js class. The full prototype chain
 
 **Reply state machine** — for repliable interactions, `replied` and `deferred` start as `false`. Calling `reply()` or `deferReply()` twice throws, just like a real interaction. `followUp()`, `editReply()`, and `deleteReply()` throw if called before any reply. The ephemeral flag is tracked on `interaction.ephemeral`. All reply methods are still mock functions so call assertions work normally.
 
-> **Framework-agnostic** — the mocks returned here are plain mock functions that stamp `_isMockFunction` and expose `.mock.calls`, the exact contract both `jest` and `vitest` check. Use them with either framework's `expect(...).toHaveBeenCalledWith(...)` / `toHaveBeenCalledTimes(...)` — no jest or vitest import is required to produce them.
+> **Framework-agnostic** — the mocks returned here are plain mock functions that stamp `_isMockFunction` and expose `.mock.calls`, the exact contract both `jest` and `vitest` check. Use them with either framework's `expect(...).toHaveBeenCalledWith(...)` / `toHaveBeenCalledTimes(...)` — no jest or vitest import is required to produce them. For typed stubs in your own code, import `MockedFunction`, `createMockFn`, and `DeepMocked` from `meocord/testing`.
 
 ```typescript
 import { createMockInteraction } from 'meocord/testing'
@@ -429,8 +443,13 @@ All methods are mock functions — override any per test with `.mockReturnValue(
 Convenience wrappers for common discord.js classes. All methods are auto-stubbed as mock functions. Nested managers (`client.users`, `guild.members`, etc.) are independent nested stubs.
 
 ```typescript
-import { vi } from 'vitest'
-import { createMockUser, createMockClient, createMockGuild, createMockChannel } from 'meocord/testing'
+import {
+  createMockFn,
+  createMockUser,
+  createMockClient,
+  createMockGuild,
+  createMockChannel,
+} from 'meocord/testing'
 import { TextChannel } from 'discord.js'
 
 const user    = createMockUser()
@@ -438,8 +457,8 @@ const client  = createMockClient()
 const guild   = createMockGuild()
 const channel = createMockChannel(TextChannel)
 
-// override nested manager methods per test
-;(client.users as any).fetch = vi.fn(() => Promise.resolve(user))
+// override nested manager methods per test (createMockFn works with vitest and jest matchers)
+;(client.users as any).fetch = createMockFn(() => Promise.resolve(user))
 await (client.users as any).fetch('user-123')
 expect((client.users as any).fetch).toHaveBeenCalledWith('user-123')
 ```
@@ -486,8 +505,13 @@ const module = MeoCordTestingModule.create({
 ### Full example
 
 ```typescript
-import { vi, type MockedFunction } from 'vitest'
-import { MeoCordTestingModule, createMockInteraction, createChatInputOptions } from 'meocord/testing'
+import {
+  MeoCordTestingModule,
+  createMockFn,
+  createMockInteraction,
+  createChatInputOptions,
+  type MockedFunction,
+} from 'meocord/testing'
 import { ChatInputCommandInteraction } from 'discord.js'
 import { GreetingSlashController } from '@src/controllers/slash/greeting.slash.controller.js'
 import { GreetingService } from '@src/services/greeting.service.js'
@@ -498,7 +522,7 @@ describe('GreetingSlashController', () => {
   let greetingService: { buildGreeting: MockedFunction<GreetingService['buildGreeting']> }
 
   beforeEach(() => {
-    greetingService = { buildGreeting: vi.fn() }
+    greetingService = { buildGreeting: createMockFn() }
 
     const module = MeoCordTestingModule.create({
       controllers: [GreetingSlashController],
@@ -566,9 +590,10 @@ npx meocord start --prod
 1. Fork the repository
 2. Create a feature branch: `git checkout -b feat/your-feature`
 3. Commit with conventional commits: `git commit -m "feat: add X"`
-4. Push and open a pull request against `main`
+4. Run `bun run lint` and `bun run test` before pushing
+5. Push and open a pull request against `main`
 
-Include a description of what changed and why, and add tests for any new behaviour.
+Include a description of what changed and why, and add tests for any new behaviour. Use `fix:` / `feat:` / `docs:` prefixes so [semantic-release](https://semantic-release.gitbook.io/) can version correctly — `test:` commits do not trigger a release.
 
 ---
 

package/dist/cjs/testing/index.cjs

@@ -97,10 +97,12 @@ function isValueProvider(p) {
  *
  * @example
  * ```typescript
+ * import { MeoCordTestingModule, createMockFn } from 'meocord/testing'
+ *
  * const module = MeoCordTestingModule.create({
  *   controllers: [PingController],
  *   providers: [
- *     { provide: PingService, useValue: { handlePing: vi.fn().mockResolvedValue('pong') } },
+ *     { provide: PingService, useValue: { handlePing: createMockFn().mockResolvedValue('pong') } },
  *   ],
  * }).compile()
  *
@@ -126,6 +128,12 @@ function isValueProvider(p) {
 // `fn.mock.calls` — so a mock produced here is recognized by assertions in
 // either framework.
 // ---------------------------------------------------------------------------
+/**
+ * Type guard that recognises mocks produced by `createMockFn` as well as
+ * native `jest.fn()` / `vi.fn()` mocks — all stamp `_isMockFunction = true`.
+ */ function isMockFunction(fn) {
+    return typeof fn === 'function' && '_isMockFunction' in fn && fn._isMockFunction === true;
+}
 /**
  * Creates a framework-agnostic mock function. Callable; records calls on
  * `.mock.calls`; supports the mock-return/resolved/rejected/implementation
@@ -752,7 +760,9 @@ exports.TestingModuleBuilder = TestingModuleBuilder;
 exports.createChatInputOptions = createChatInputOptions;
 exports.createMockChannel = createMockChannel;
 exports.createMockClient = createMockClient;
+exports.createMockFn = createMockFn;
 exports.createMockGuild = createMockGuild;
 exports.createMockInteraction = createMockInteraction;
 exports.createMockMessage = createMockMessage;
 exports.createMockUser = createMockUser;
+exports.isMockFunction = isMockFunction;

package/dist/esm/testing/index.js

@@ -1,2 +1,3 @@
 export { MeoCordTestingModule, TestingModule, TestingModuleBuilder } from './meocord-testing-module.js';
 export { createChatInputOptions, createMockChannel, createMockClient, createMockGuild, createMockInteraction, createMockMessage, createMockUser } from './mock-interaction.js';
+export { createMockFn, isMockFunction } from './mock-fn.js';

package/dist/esm/testing/meocord-testing-module.js

@@ -94,10 +94,12 @@ function isValueProvider(p) {
  *
  * @example
  * ```typescript
+ * import { MeoCordTestingModule, createMockFn } from 'meocord/testing'
+ *
  * const module = MeoCordTestingModule.create({
  *   controllers: [PingController],
  *   providers: [
- *     { provide: PingService, useValue: { handlePing: vi.fn().mockResolvedValue('pong') } },
+ *     { provide: PingService, useValue: { handlePing: createMockFn().mockResolvedValue('pong') } },
  *   ],
  * }).compile()
  *

package/dist/esm/testing/mock-fn.js

@@ -12,6 +12,12 @@
 // `fn.mock.calls` — so a mock produced here is recognized by assertions in
 // either framework.
 // ---------------------------------------------------------------------------
+/**
+ * Type guard that recognises mocks produced by `createMockFn` as well as
+ * native `jest.fn()` / `vi.fn()` mocks — all stamp `_isMockFunction = true`.
+ */ function isMockFunction(fn) {
+    return typeof fn === 'function' && '_isMockFunction' in fn && fn._isMockFunction === true;
+}
 /**
  * Creates a framework-agnostic mock function. Callable; records calls on
  * `.mock.calls`; supports the mock-return/resolved/rejected/implementation
@@ -187,4 +193,4 @@
     return mockFn;
 }
 
-export { createMockFn };
+export { createMockFn, isMockFunction };

package/dist/types/testing/index.d.ts

@@ -53,10 +53,12 @@ declare class TestingModuleBuilder {
  *
  * @example
  * ```typescript
+ * import { MeoCordTestingModule, createMockFn } from 'meocord/testing'
+ *
  * const module = MeoCordTestingModule.create({
  *   controllers: [PingController],
  *   providers: [
- *     { provide: PingService, useValue: { handlePing: vi.fn().mockResolvedValue('pong') } },
+ *     { provide: PingService, useValue: { handlePing: createMockFn().mockResolvedValue('pong') } },
  *   ],
  * }).compile()
  *
@@ -110,6 +112,26 @@ interface MockInstance<T extends (...args: any[]) => any = (...args: any[]) => a
  * Drop-in replacement for `jest.MockedFunction<T>` / vitest `MockedFunction<T>`.
  */
 type MockedFunction<T extends (...args: any[]) => any> = ((...args: Parameters<T>) => ReturnType<T>) & MockInstance<T>;
+/** Alias kept for parity with `jest.Mock` / vitest `Mock`. */
+type Mock<T extends (...args: any[]) => any = (...args: any[]) => any> = MockedFunction<T>;
+/**
+ * Type guard that recognises mocks produced by `createMockFn` as well as
+ * native `jest.fn()` / `vi.fn()` mocks — all stamp `_isMockFunction = true`.
+ */
+declare function isMockFunction(fn: unknown): fn is MockInstance;
+/**
+ * Creates a framework-agnostic mock function. Callable; records calls on
+ * `.mock.calls`; supports the mock-return/resolved/rejected/implementation
+ * API used by the testing utilities and by user assertions.
+ *
+ * @example
+ * const fn = createMockFn<(x: number) => number>((x) => x + 1)
+ * fn(2)                    // → 3
+ * fn.mockReturnValue(99)
+ * fn(2)                    // → 99
+ * fn.mock.calls             // → [[2], [2]]
+ */
+declare function createMockFn<T extends (...args: any[]) => any = (...args: any[]) => any>(impl?: T): MockedFunction<T>;
 
 /**
  * MeoCord Framework
@@ -220,5 +242,5 @@ interface ChatInputOptions {
  */
 declare function createChatInputOptions(opts?: ChatInputOptions): DeepMocked<CommandInteractionOptionResolver>;
 
-export { MeoCordTestingModule, TestingModule, TestingModuleBuilder, createChatInputOptions, createMockChannel, createMockClient, createMockGuild, createMockInteraction, createMockMessage, createMockUser };
-export type { ChatInputOptions, ClassProvider, DeepMocked, Provider, TestingModuleOptions, ValueProvider };
+export { MeoCordTestingModule, TestingModule, TestingModuleBuilder, createChatInputOptions, createMockChannel, createMockClient, createMockFn, createMockGuild, createMockInteraction, createMockMessage, createMockUser, isMockFunction };
+export type { ChatInputOptions, ClassProvider, DeepMocked, Mock, MockInstance, MockResult, MockState, MockedFunction, Provider, TestingModuleOptions, ValueProvider };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "meocord",
   "description": "Decorator-based Discord bot framework built on discord.js. Brings NestJS-style controllers, dependency injection, guards, and testing utilities to bot development — with a full CLI and TypeScript-first design.",
-  "version": "1.8.4-beta.1",
+  "version": "1.8.4",
   "type": "module",
   "scripts": {
     "lint": "eslint --fix . && tsc --noEmit && tsc --noEmit --project tsconfig.test.json",