Mockingoose v3: TypeScript rewrite, Mongoose 9, Vitest

.claude/skills/github-actions-templates

@@ -0,0 +1 @@
+../../.agents/skills/github-actions-templates

.claude/skills/mongoose-mongodb

@@ -0,0 +1 @@
+../../.agents/skills/mongoose-mongodb

.claude/skills/typescript-advanced-types

@@ -0,0 +1 @@
+../../.agents/skills/typescript-advanced-types

.claude/skills/typescript-docs

@@ -0,0 +1 @@
+../../.agents/skills/typescript-docs

.claude/skills/vitest

@@ -0,0 +1 @@
+../../.agents/skills/vitest

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - '*'
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: bun install
+      - run: bun run typecheck
+      - run: bun run test
+      - run: bun run build
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - run: bun run lint

.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: google-github-actions/release-please-action@v4
+        id: release
+        with:
+          release-type: node
+
+      - uses: actions/checkout@v4
+        if: ${{ steps.release.outputs.release_created }}
+
+      - uses: oven-sh/setup-bun@v2
+        if: ${{ steps.release.outputs.release_created }}
+
+      - uses: actions/setup-node@v4
+        if: ${{ steps.release.outputs.release_created }}
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: bun install
+        if: ${{ steps.release.outputs.release_created }}
+
+      - run: bun run build
+        if: ${{ steps.release.outputs.release_created }}
+
+      - run: bun run test
+        if: ${{ steps.release.outputs.release_created }}
+
+      - run: npm publish
+        if: ${{ steps.release.outputs.release_created }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -58,3 +58,8 @@ typings/
 # dotenv environment variables file
 .env
 
+# Build output
+dist/
+
+# opensrc - source code for packages
+opensrc/

.prettierignore

@@ -0,0 +1,65 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+.idea
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Typescript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+
+# Build output
+dist/
+
+# opensrc - source code for packages
+opensrc/

.prettierrc.json

@@ -1,4 +1,3 @@
-{
-  "singleQuote": true,
-  "trailingComma": "es5"
-}
+{
+  "singleQuote": true
+}

CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+Mockingoose is a utility for mocking Mongoose models in tests (Jest or Vitest). It intercepts Mongoose operations (find, save, aggregate, etc.) via mock functions so tests run without a database connection.
+
+## Commands
+
+- **Test:** `bun run test` (all tests) or `npx vitest run --testPathPattern=<pattern>` (single test)
+- **Build:** `bun run build` (tsdown: `src/` → `dist/` ESM+CJS)
+- **Typecheck:** `bun run typecheck` (tsc --noEmit)
+- **Lint:** `bun run lint` (Prettier check)
+- **Format:** `bunx prettier --write src`
+
+## Architecture
+
+TypeScript library: `src/index.ts` + `src/types.ts` → compiled to `dist/` via tsdown (ESM + CJS dual output with generated `.d.ts`).
+
+### How It Works
+
+1. **Connection mocking** — `mongoose.connect` and `mongoose.createConnection` are replaced with mock function stubs
+2. **Operation mocking** — All query operations (`find`, `findOne`, `save`, etc.) on `mongoose.Query.prototype` are replaced with mocks that call `mockedReturn()`
+3. **`mockedReturn()`** — Core function that looks up mocked data from `mockingoose.__mocks[modelName][op]`, wraps results in Mongoose Model instances (unless the op is a raw-return type like `deleteOne`/`countDocuments`), and supports promise patterns
+4. **Instance methods** — `save`, `$save` are mocked on `mongoose.Model.prototype` with pre/post hook support
+5. **Aggregate** — Separately handled via `mongoose.Aggregate.prototype.exec`
+6. **Proxy API** — `mockingoose` is a Proxy that allows both `mockingoose(Model).toReturn(data, op)` (preferred) and `mockingoose.ModelName.toReturn(data, op)` (deprecated)
+7. **Framework detection** — Runtime detection of `vi` (Vitest) or `jest` globals for mock function creation
+
+### Key Files
+
+- `src/index.ts` — Main library source
+- `src/types.ts` — Exported TypeScript types (Op, MockController, Mockingoose, etc.)
+- `__tests__/index.test.ts` — Test suite (Vitest)
+- `__tests__/User.ts` — Test fixture model
+
+### Style
+
+Prettier with single quotes, trailing commas (es5). See `.prettierrc.json`.
+
+## Skills
+
+Use these Claude Code skills when working in this repo:
+
+- `typescript-docs` — TypeScript documentation generation
+- `typescript-advanced-types` — advanced TypeScript type patterns (generics, conditional types, mapped types, etc.)
+- `vitest` — testing (writing tests, mocking, coverage, fixtures)
+- `mongoose-mongodb` — Mongoose/MongoDB schema design, CRUD, queries
+- `github-actions-templates` — GitHub Actions CI/CD workflows, automated testing/building/deploying
+
+## Package Manager
+
+- Always use `bun` as the package manager.
+- Never add packages manually to package.json — always use `bun add` / `bun add -d`.
+- Always use `bun` to install dependencies.