@simtlix/simfinity-js 2.4.1 → 2.4.4

package/.cursor/rules/simfinity-architecture.mdc

@@ -0,0 +1,71 @@
+---
+description: Simfinity.js project architecture overview -- always loaded for context
+alwaysApply: true
+---
+
+# Simfinity.js Architecture
+
+`@simtlix/simfinity-js` is a GraphQL framework that auto-generates schemas, CRUD queries, mutations, and MongoDB models from `GraphQLObjectType` definitions.
+
+## Tech Stack
+
+- **Language**: JavaScript (ES modules, `"type": "module"`)
+- **Runtime**: Node.js >= 18.18.0
+- **GraphQL**: `graphql` ^16 (peer dependency)
+- **Database**: MongoDB via `mongoose` ^8 (peer dependency)
+- **Testing**: Vitest
+- **Linting**: ESLint 9 (flat config)
+- **Server integration**: GraphQL Yoga with Envelop plugins
+
+## Core Flow
+
+```
+Define GraphQLObjectType
+       |
+       v
+simfinity.connect(null, Type, 'singular', 'plural', controller, onModelCreated, stateMachine)
+  -- or --
+simfinity.addNoEndpointType(Type)   // supporting types without endpoints
+       |
+       v
+simfinity.createSchema()
+       |
+       +-- buildPendingInputTypes()    // resolve deferred input types
+       +-- generateModel()            // create Mongoose schema + model per type
+       +-- autoGenerateResolvers()    // wire relationship resolvers
+       +-- buildRootQuery()           // list, single-entity, aggregate queries
+       +-- buildMutation()            // add, update, delete, state-change mutations
+       |
+       v
+  GraphQLSchema ready for Yoga/Apollo
+```
+
+## Module Map
+
+| File | Responsibility |
+|------|---------------|
+| `src/index.js` | Core engine: type registration, schema/model generation, query/mutation builders, resolvers, middleware, scope |
+| `src/auth/index.js` | Auth plugin (`createAuthPlugin`), permission resolution, deprecated middleware |
+| `src/auth/rules.js` | Rule helpers: `requireAuth`, `requireRole`, `composeRules`, `isOwner`, `allow`, `deny` |
+| `src/auth/expressions.js` | Policy expression DSL evaluator |
+| `src/auth/errors.js` | `UnauthenticatedError`, `ForbiddenError` (extend `SimfinityError`) |
+| `src/validators.js` | Declarative field validators: `stringLength`, `pattern`, `email`, `numberRange`, etc. |
+| `src/scalars.js` | Pre-built scalars (`EmailScalar`, `URLScalar`) and scalar factories |
+| `src/plugins.js` | Plugin exports: `createAuthPlugin`, `apolloCountPlugin`, `envelopCountPlugin` |
+| `src/const/QLOperator.js` | `GraphQLEnumType` for filter operators (EQ, LT, GT, IN, LIKE, etc.) |
+| `src/const/QLValue.js` | `GraphQLScalarType` for filter values |
+| `src/const/QLSort.js` | `GraphQLInputObjectType` for sort expressions |
+| `src/errors/simfinity.error.js` | Base error class with `code` and `status` extensions |
+| `src/errors/internal-server.error.js` | Internal server error (extends `SimfinityError`) |
+
+## Key Global State (in `src/index.js`)
+
+- `typesDict` -- primary registry: `{ types: { [typeName]: { model, gqltype, simpleEntityEndpointName, listEntitiesEndpointName, endpoint, controller, stateMachine, inputType } } }`
+- `typesDictForUpdate` -- parallel registry with update-specific input types
+- `waitingInputType` -- deferred input types awaiting dependency resolution (circular refs)
+- `registeredMutations` -- custom mutations registered via `registerMutation()`
+- `middlewares` -- array of global middleware functions registered via `use()`
+
+## Introspection Extension (Critical)
+
+Simfinity monkey-patches `__Field._fields` to inject `FieldExtensionsType` and `RelationType` into GraphQL introspection globally. This means these types exist outside the schema's type map. Any tool that rebuilds or copies the schema (like `graphql-middleware`'s `applyMiddleware` / `mapSchema`) will cause duplicate type errors. Always use Envelop plugins for schema transformations.

package/.cursor/rules/simfinity-auth-module.mdc

@@ -0,0 +1,100 @@
+---
+description: Documents the authorization subsystem -- Envelop plugin, permission maps, rule helpers, and policy expressions
+globs: src/auth/**
+alwaysApply: false
+---
+
+# Authorization Module (`src/auth/`)
+
+## File Structure
+
+- `index.js` -- `createAuthPlugin` (Envelop), deprecated `createAuthMiddleware`, permission resolution logic
+- `rules.js` -- Rule helper functions: `requireAuth`, `requireRole`, `requirePermission`, `composeRules`, `anyRule`, `isOwner`, `allow`, `deny`, `createRule`
+- `expressions.js` -- Policy expression DSL: `evaluateExpression`, `isPolicyExpression`, `createRuleFromExpression`
+- `errors.js` -- `UnauthenticatedError`, `ForbiddenError` (extend `SimfinityError`)
+
+## `createAuthPlugin(permissions, options)` -- Envelop Plugin
+
+The recommended auth integration. Returns an Envelop plugin with an `onSchemaChange` hook.
+
+```javascript
+const authPlugin = createAuthPlugin(permissions, { defaultPolicy: 'DENY', debug: false });
+// Use with GraphQL Yoga:
+const yoga = createYoga({ schema, plugins: [authPlugin] });
+```
+
+**How it works:**
+1. On `onSchemaChange({ schema })`, iterates all types in `schema.getTypeMap()`
+2. Skips non-`GraphQLObjectType` types and `__`-prefixed introspection types
+3. For each field, looks up rules from the permission map via `getFieldRules()`
+4. Wraps `field.resolve` in-place (mutates the schema, no rebuild)
+5. Uses a `WeakSet` to prevent double-wrapping if `onSchemaChange` fires again
+
+**`defaultPolicy`**: `'DENY'` (default) blocks fields with no rules; `'ALLOW'` permits them.
+
+## Permission Map Structure
+
+```javascript
+const permissions = {
+  Query: {
+    '*': allow(),                    // wildcard: default for all Query fields
+    series: requireAuth(),           // specific field overrides wildcard
+  },
+  Mutation: {
+    addserie: requireRole('admin'),
+    deleteserie: composeRules(requireAuth(), requireRole('admin')),
+  },
+  Serie: {
+    title: allow(),
+    internalNotes: requireRole('admin'),
+  },
+};
+```
+
+- Keys are GraphQL type names (must match `GraphQLObjectType.name` exactly)
+- Field keys are the auto-generated endpoint names (lowercase)
+- Wildcard `'*'` applies to all fields of a type unless overridden by an exact match
+- Values can be: a rule function, an array of rule functions (AND logic), or a policy expression string
+
+## Rule Resolution (`getFieldRules`)
+
+1. Check `permissions[typeName][fieldName]` (exact match)
+2. Fall back to `permissions[typeName]['*']` (wildcard)
+3. If neither exists, return `null` (applies `defaultPolicy`)
+
+Each rule receives `(parent, args, ctx, info)` and must return `true` or throw an error.
+
+## Rule Helpers (from `rules.js`)
+
+| Helper | Description |
+|--------|-------------|
+| `requireAuth(userPath?)` | Checks `ctx[userPath]` exists (default: `'user'`) |
+| `requireRole(role, options?)` | Checks user has role. Options: `{ userPath, rolesPath }` |
+| `requirePermission(perm, options?)` | Checks user has permission string |
+| `composeRules(...rules)` | AND: all rules must pass |
+| `anyRule(...rules)` | OR: at least one rule must pass |
+| `isOwner(ownerField, userIdField?, options?)` | Compares `parent[ownerField]` with user ID |
+| `createRule(predicate, errorMessage?, errorCode?)` | Custom rule from predicate function |
+| `allow()` | Always returns `true` |
+| `deny(message?)` | Always throws `ForbiddenError` |
+
+## Policy Expressions (from `expressions.js`)
+
+String-based alternative to function rules. Evaluated by `evaluateExpression()`.
+
+```javascript
+const permissions = {
+  Mutation: {
+    deleteserie: 'ROLE:admin',
+    updateserie: 'AUTH AND ROLE:editor',
+    addserie: 'ROLE:admin OR ROLE:editor',
+  },
+};
+```
+
+`createRuleFromExpression()` converts an expression string into a standard rule function.
+
+## Deprecated APIs
+
+- `createAuthMiddleware()` -- uses `graphql-middleware`'s `applyMiddleware` which causes duplicate type errors with Simfinity's introspection patch. Use `createAuthPlugin` instead.
+- `createFieldMiddleware()` -- same issue. Use `createAuthPlugin` instead.

package/.cursor/rules/simfinity-coding-standards.mdc

@@ -0,0 +1,62 @@
+---
+description: Coding standards and best practices for writing new Simfinity.js code
+alwaysApply: true
+---
+
+# Coding Standards
+
+## Module System
+
+- Use ES module syntax (`import`/`export`). No CommonJS (`require`/`module.exports`).
+- All imports at the top of the file. No inline or dynamic imports inside functions.
+
+## Style (enforced by ESLint)
+
+- Single quotes, semicolons, trailing commas in multiline constructs.
+- `prefer-const` -- use `const` unless reassignment is needed.
+- No `var`, no `for...in` loops. Use `Object.entries()`, `Object.keys()`, or `for...of`.
+- `no-param-reassign` with `props: false` -- reassigning parameter properties is allowed (common in resolvers and `materializeModel`).
+- `no-underscore-dangle` is off -- `_id` and `_fields` are used throughout for MongoDB and GraphQL internals.
+
+## Error Handling
+
+- Extend `SimfinityError` for all domain errors. Always provide `message`, `code` (string), and `status` (HTTP number):
+
+```javascript
+throw new SimfinityError('Resource not found', 'NOT_FOUND', 404);
+```
+
+- For auth errors, use `UnauthenticatedError` (401) or `ForbiddenError` (403) from `src/auth/errors.js`.
+- Wrap mutation logic in Mongoose transactions. Handle `TransientTransactionError` with retry (see `executeOperation` pattern).
+
+## GraphQL Type Definitions
+
+- Always use `extensions.relation` on fields referencing other `GraphQLObjectType`s. Omitting it causes warnings and broken input types.
+- Use `GraphQLNonNull` wrapper for required fields.
+- Use `extensions.readOnly` for computed/system fields that should not appear in input types.
+- Validated scalars: use `createValidatedScalar(name, description, baseScalarType, validate)` -- the resulting scalar name is `{name}_{baseScalarType.name}`.
+
+## Schema Transformations
+
+- **Never** use `graphql-middleware`'s `applyMiddleware` or `@graphql-tools/utils`'s `mapSchema` on a Simfinity schema. These rebuild the schema, duplicating the globally-injected `FieldExtensionsType`.
+- Use Envelop plugins (`onSchemaChange` hook) to wrap resolvers in-place.
+
+## Export Conventions
+
+- Named exports for public API functions.
+- Default export as an object aggregating all named exports (for convenient destructuring).
+- Re-export submodule defaults from `src/index.js`: `validators`, `scalars`, `plugins`, `auth`.
+
+## Function Naming
+
+- Internal helpers: camelCase, not exported.
+- Public API: camelCase, exported with `export const`.
+- Deprecated functions: mark with `@deprecated` JSDoc tag.
+
+## Keeping Project Artifacts in Sync
+
+When making code changes, update **all** related artifacts:
+
+1. **Tests** (`tests/`): add or update tests for any new or changed behavior. See `simfinity-testing.mdc`.
+2. **Documentation** (`README.md`): update examples, API docs, and Table of Contents for any public API change. See `simfinity-documentation.mdc`.
+3. **Cursor rules** (`.cursor/rules/`): if a change affects architecture, internal functions, the extensions system, the auth module, coding standards, or testing/documentation conventions, update the corresponding `.mdc` rule file so it stays accurate.

package/.cursor/rules/simfinity-core-functions.mdc

@@ -0,0 +1,82 @@
+---
+description: Documents the critical internal functions and pipelines in the Simfinity core engine
+globs: src/index.js
+alwaysApply: false
+---
+
+# Core Functions in src/index.js
+
+## Registration Phase
+
+### `connect(model, gqltype, simpleEntityEndpointName, listEntitiesEndpointName, controller, onModelCreated, stateMachine)`
+
+Registers a GraphQL type for full CRUD endpoint generation. The `model` param is typically `null` (generated later by `createSchema`). Stores metadata in `typesDict` and `typesDictForUpdate`.
+
+### `addNoEndpointType(gqltype)`
+
+Registers a supporting type (no query/mutation endpoints). Auto-detects whether a Mongoose model is needed based on relationship fields. Used for embedded types or types only referenced by other types.
+
+### `registerMutation(name, description, inputModel, outputModel, callback)`
+
+Registers a custom mutation outside the standard CRUD pattern.
+
+## Schema Build Phase (`createSchema()`)
+
+Called after all `connect()`/`addNoEndpointType()` calls. Executes in order:
+
+1. **`generateModel()`** / **`generateModelWithoutCollection()`** -- creates Mongoose schemas via `generateSchemaDefinition()`, auto-indexes all ObjectId fields via `createSchemaWithIndexes()` / `findObjectIdFields()`.
+2. **`buildPendingInputTypes()`** -- recursively resolves deferred input types (handles circular dependencies by retrying until all resolve).
+3. **`autoGenerateResolvers()`** -- for each type's fields with `extensions.relation` and no existing resolver, generates: one-to-one resolvers (`findById`), one-to-many resolvers (aggregation pipeline with filter support).
+4. **`buildRootQuery()`** -- creates the root Query type with: `{singular}(id)` single-entity query, `{plural}(filters, pagination, sort)` list query, `{plural}_aggregate(filters, aggregation)` aggregation query.
+5. **`buildMutation()`** -- creates the Mutation type with: `add{singular}(input)`, `update{singular}(input)`, `delete{singular}(id)`, `{actionName}_{singular}(input)` for state machine transitions.
+
+## Auto-Generated Endpoint Naming
+
+- **Single entity query**: `simpleEntityEndpointName` (e.g., `serie`)
+- **List query**: `listEntitiesEndpointName` (e.g., `series`)
+- **Add mutation**: `add` + `simpleEntityEndpointName` (e.g., `addserie`)
+- **Update mutation**: `update` + `simpleEntityEndpointName` (e.g., `updateserie`)
+- **Delete mutation**: `delete` + `simpleEntityEndpointName` (e.g., `deleteserie`)
+- **State action**: `{actionName}_{simpleEntityEndpointName}` (e.g., `approve_serie`)
+
+All names are lowercase as provided by the consumer in `connect()`.
+
+## Input Type Generation (`buildInputType()`)
+
+Creates two input types per registered type:
+
+- `{Type}Input` -- for `add` mutations (excludes `id`, readOnly fields, state-machine-managed `state`)
+- `{Type}InputForUpdate` -- for `update` mutations (all fields optional except `id` which is required)
+
+Handles: scalars, enums, relation fields (`IdInputType` for refs, nested input for embedded), `GraphQLList` fields (`OneToMany{A|U}{fieldName}` with `added`/`updated`/`deleted` sub-fields), self-referencing collections.
+
+## Query Pipeline
+
+`buildQuery(args, gqltype)` translates GraphQL filter arguments into a MongoDB aggregation pipeline:
+
+- `buildQueryTerms()` -- converts scalar/enum filters to `$match`, object/relation filters to `$lookup` + `$unwind` + `$match`
+- `buildAggregationsForSort()` -- adds `$lookup`/`$unwind` for sort on related fields
+- Pagination: `$skip` + `$limit` from `QLPagination` input
+- Sort: `$sort` from `QLSortExpression` input
+
+`buildAggregationQuery()` extends this with `$group` for aggregation operations (SUM, COUNT, AVG, MIN, MAX).
+
+## Mutation Pipeline
+
+`executeOperation()` wraps all mutations in Mongoose transactions:
+
+1. Starts a session + transaction
+2. Calls the appropriate handler: `onSaveObject`, `onUpdateSubject`, `onDeleteObject`, `onStateChanged`
+3. Commits on success, aborts on error
+4. Auto-retries on `TransientTransactionError`
+
+`materializeModel()` transforms GraphQL input args into Mongoose-compatible documents, running field-level and type-level validators during the process.
+
+## Middleware and Scope
+
+- `use(middleware)` -- pushes to global `middlewares` array. `excecuteMiddleware()` chains them with `next()` pattern.
+- `executeScope()` -- checks `type.gqltype.extensions.scope[operation]` and calls the scope function to apply row-level filtering for `find`, `get_by_id`, and `aggregate` operations.
+
+## Introspection Monkey-Patch
+
+Lines 52-85: `FieldExtensionsType` and `RelationType` are injected into `__Field._fields` globally. This enables introspection clients to discover relation metadata and state machine flags. **Never rebuild the schema** with tools that clone types (e.g., `mapSchema` from `@graphql-tools/utils`) -- it will duplicate these globally-injected types.

package/.cursor/rules/simfinity-documentation.mdc

@@ -0,0 +1,59 @@
+---
+description: Rules for maintaining README.md documentation when code changes
+globs: README.md
+alwaysApply: false
+---
+
+# Documentation Maintenance
+
+## When to Update README.md
+
+- **New public API**: document the function signature, purpose, and a usage example.
+- **Changed behavior**: update relevant sections and code examples to reflect the change.
+- **New feature**: add a new section in the appropriate position (see section order below).
+- **Removed/deprecated feature**: mark as deprecated with migration guidance; do not silently remove.
+
+## Section Order
+
+Maintain this logical flow (define -> operate -> protect -> advanced):
+
+1. Overview / Quick Start
+2. Schema Definition (defining `GraphQLObjectType` with Simfinity)
+3. Relationships (embedded, non-embedded, one-to-many)
+4. Validations (field-level, type-level, declarative validators)
+5. Queries (single entity, list, filtering, pagination, sorting)
+6. Mutations (add, update, delete)
+7. State Machines (states, transitions, actions)
+8. Controllers & Lifecycle Hooks (onSaving, onSaved, onUpdating, onUpdated, onDelete)
+9. Query Scope (row-level security via scope functions)
+10. Authorization (Envelop auth plugin, permission maps, rule helpers)
+11. Middlewares (global middleware via `use()`)
+12. Plugins (count plugins, auth plugin re-export)
+13. Custom Scalars (pre-built and factory functions)
+14. Error Handling
+15. Resources (links to example projects, API docs)
+
+## Table of Contents
+
+Update the Table of Contents whenever sections are added, removed, or reordered. Ensure every `##` and `###` heading has a corresponding ToC entry.
+
+## Naming in Code Examples
+
+Use Simfinity's auto-generated endpoint names consistently:
+
+- **Queries**: `{plural}` for list (e.g., `series`), `{singular}` for single entity (e.g., `serie`)
+- **Mutations**: `add{singular}` (e.g., `addserie`), `update{singular}` (e.g., `updateserie`), `delete{singular}` (e.g., `deleteserie`)
+- **State actions**: `{actionName}_{singular}` (e.g., `approve_serie`)
+- **Aggregation**: `{plural}_aggregate` (e.g., `series_aggregate`)
+
+All names are lowercase as defined in `connect()` calls.
+
+## Reference Project
+
+Always link to the [Series Sample Project](https://github.com/simtlix/series-sample) as a complete working example. Mention it in Quick Start and Resources sections.
+
+## Style Guidelines
+
+- Use fenced code blocks with `javascript` language tag for all code examples.
+- Keep examples realistic -- use types and field names from the series-sample project (Serie, Season, Star, etc.) rather than abstract names.
+- Show both the type definition and the resulting GraphQL operation where appropriate.

package/.cursor/rules/simfinity-extensions.mdc

@@ -0,0 +1,121 @@
+---
+description: Documents the field/type extensions metadata system used in GraphQLObjectType definitions
+globs: src/index.js
+alwaysApply: false
+---
+
+# Extensions Metadata System
+
+Simfinity uses the standard GraphQL `extensions` property on fields and types to carry metadata that drives schema generation, model creation, resolver wiring, and validation.
+
+## Field-Level Extensions
+
+### `extensions.relation`
+
+Defines relationships between types. Required on every field whose type is another `GraphQLObjectType` or `GraphQLList` of one.
+
+```javascript
+fields: () => ({
+  author: {
+    type: AuthorType,
+    extensions: {
+      relation: {
+        embedded: false,          // false = ObjectId reference, true = nested document
+        connectionField: 'author_id',  // MongoDB field storing the ObjectId (defaults to field name)
+        displayField: 'name',     // field shown in introspection UI hints
+      },
+    },
+  },
+  chapters: {
+    type: new GraphQLList(ChapterType),
+    extensions: {
+      relation: {
+        embedded: true,           // stored inline in parent document
+      },
+    },
+  },
+})
+```
+
+- **Non-embedded** (`embedded: false`): stored as ObjectId in MongoDB. Input types use `IdInputType` (`{ id: String! }`). List fields generate `OneToMany` input with `added`/`updated`/`deleted` sub-fields. Auto-generates `$lookup` resolvers.
+- **Embedded** (`embedded: true`): stored inline. Input types use the nested type's full input type. No `$lookup` needed.
+- **`connectionField`**: the actual MongoDB field name for the ObjectId reference. If omitted, defaults to the GraphQL field name.
+
+### `extensions.readOnly`
+
+```javascript
+createdAt: {
+  type: GraphQLString,
+  extensions: { readOnly: true },
+}
+```
+
+Excludes the field from both add and update input types. The field can only be set programmatically (e.g., in a controller hook).
+
+### `extensions.unique`
+
+```javascript
+email: {
+  type: GraphQLString,
+  extensions: { unique: true },
+}
+```
+
+Adds a MongoDB unique index on the field in `generateSchemaDefinition()`.
+
+### `extensions.validations`
+
+```javascript
+name: {
+  type: new GraphQLNonNull(GraphQLString),
+  extensions: {
+    validations: validators.stringLength('Name', 2, 100),
+    // Returns: { CREATE: [validator], UPDATE: [validator] }
+  },
+}
+```
+
+Validators are executed during `materializeModel()` before saving/updating. Each validator has a `.validate(typeName, fieldName, value, session)` method. The `CREATE` array runs on add, `UPDATE` on update.
+
+### `extensions.stateMachine` (auto-set)
+
+Not set manually. When `buildInputType()` detects a `state` field on a type that has a state machine, it sets `extensions.stateMachine = true` on that field and excludes it from input types.
+
+## Type-Level Extensions
+
+### `extensions.validations` (on the type)
+
+```javascript
+const BookType = new GraphQLObjectType({
+  name: 'Book',
+  extensions: {
+    validations: {
+      CREATE: [{ validate: async (typeName, args, modelArgs, session) => { /* cross-field validation */ } }],
+      UPDATE: [{ validate: async (typeName, args, modelArgs, session) => { /* ... */ } }],
+    },
+  },
+  fields: () => ({ /* ... */ }),
+});
+```
+
+Type-level validators run after all field-level validators, receiving the full args and materialized model.
+
+### `extensions.scope`
+
+```javascript
+const BookType = new GraphQLObjectType({
+  name: 'Book',
+  extensions: {
+    scope: {
+      find: async ({ type, args, operation, context }) => {
+        args.owner_id = { operator: 'EQ', value: context.user.id };
+      },
+      get_by_id: async ({ type, args, operation, context }) => { /* ... */ },
+      aggregate: async ({ type, args, operation, context }) => { /* ... */ },
+    },
+  },
+  fields: () => ({ /* ... */ }),
+});
+```
+
+Scope functions modify query args in-place to enforce row-level security. Called by `executeScope()` before building the MongoDB aggregation pipeline.

package/.cursor/rules/simfinity-testing.mdc

@@ -0,0 +1,90 @@
+---
+description: Testing conventions, patterns, and requirements for when tests must be updated
+globs: tests/**
+alwaysApply: false
+---
+
+# Testing Conventions
+
+## Framework and Setup
+
+- **Vitest** with ES module imports: `import { describe, test, expect, beforeAll } from 'vitest';`
+- Run tests: `npm test` (runs `vitest run`), `npm run test:watch`, `npm run test:coverage`
+- Call `simfinity.preventCreatingCollection(true)` in `beforeAll` to prevent MongoDB collection creation during tests.
+
+## Test File Naming
+
+- `tests/{module}.test.js` corresponding to `src/{module}.js`
+- Auth tests: `tests/auth.test.js` covers `src/auth/index.js`, `src/auth/rules.js`, `src/auth/expressions.js`
+- Feature-specific tests: `tests/aggregation.test.js`, `tests/scalar-naming.test.js`, etc.
+
+## Test Structure
+
+```javascript
+describe('Module or Feature Name', () => {
+  beforeAll(() => {
+    simfinity.preventCreatingCollection(true);
+  });
+
+  describe('function or sub-feature', () => {
+    test('should describe expected behavior', () => {
+      // Arrange, Act, Assert
+    });
+  });
+});
+```
+
+- Group by module, then by function/feature.
+- Mirror the export structure: if a module exports `{ foo, bar }`, have `describe('foo', ...)` and `describe('bar', ...)`.
+- Test export existence: verify all expected exports are defined.
+
+## When to Update Tests
+
+**Any change to `src/` must have corresponding test updates:**
+
+- **New export**: add a test verifying the export exists and has the expected type.
+- **New function/feature**: add both positive cases (happy path) and negative cases (error handling, edge cases).
+- **Changed behavior**: update existing tests to reflect the new behavior. Add tests for any new code paths.
+- **Bug fix**: add a regression test that would have caught the bug.
+- **Deprecated function**: keep existing tests but add a note. Do not remove tests for deprecated functions that still exist.
+
+## Common Test Patterns
+
+### Testing GraphQL types without MongoDB
+
+```javascript
+const TestType = new GraphQLObjectType({
+  name: 'TestType',
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: GraphQLString },
+  }),
+});
+
+const schema = new GraphQLSchema({
+  query: new GraphQLObjectType({
+    name: 'Query',
+    fields: { test: { type: TestType, resolve: () => ({ id: '1', name: 'test' }) } },
+  }),
+});
+```
+
+### Testing auth rules
+
+```javascript
+const rule = requireAuth();
+expect(rule(null, {}, { user: { id: '1' } }, null)).toBe(true);
+expect(() => rule(null, {}, {}, null)).toThrow(UnauthenticatedError);
+```
+
+### Testing validators
+
+```javascript
+const validation = validators.stringLength('Name', 2, 100);
+await expect(validation.CREATE[0].validate('Type', 'field', 'ab', null)).resolves.not.toThrow();
+await expect(validation.CREATE[0].validate('Type', 'field', 'a', null)).rejects.toThrow();
+```
+
+## Lint After Testing
+
+Run `npm run lint` after modifying test files to catch unused imports or style violations.