Simfinity.js

A Node.js framework that turns GraphQL object types into generated queries, mutations, relationships, and database storage. Use the established MongoDB/Mongoose facade or the PostgreSQL 15+ facade with real tables and foreign keys.

Read the documentation website: start with the quick start, explore the guides, or consult the API reference. The website source is in docs/.

For a complete application, run the Barber examples: independent MongoDB and PostgreSQL backends with one shared Next.js frontend, synthetic demo data, Docker setup, and a dedicated CI workflow. Both backends consume released Simfinity 3.5.9 packages from npm. Their shared HTTP matrix verifies filters, aggregates, scopes and nested mutations; see the API test commands and reference-integrity boundary.

Run the documentation website locally with Node.js 22+:

npm run docs:install
npm run docs:dev

For builds and hosting, see the website maintainer guide. The website documents the current source; some older examples later in this README retain historical conventions.

Documentation for both databases: The public website now covers MongoDB and PostgreSQL, including shared APIs, relationships, generated FKs, scopes, and MCP. Both adapters are available on npm and released together. Follow the quick starts for installation, or download the runnable starters and verified release archives.

📑 Table of Contents

• Features
• Installation
• PostgreSQL support
• Quick Start
• Core Concepts
  • Connecting Models
  • Creating Schemas
  • MongoDB Reference Integrity
  • Global Configuration
• Basic Usage
  • Automatic Query Generation
  • Automatic Mutation Generation
  • Filtering and Querying
  • Collection Field Filtering
• Relationships
  • Defining Relationships
  • Auto-Generated Resolve Methods
  • Adding Types Without Endpoints
  • Embedded vs Referenced Relationships
  • Querying Relationships
• Validations
  • Field-Level Validations
  • Type-Level Validations
  • Custom Validated Scalar Types
  • Custom Error Classes
• State Machines
• Controllers & Lifecycle Hooks
  • Hook Parameters
• Query Scope
  • Overview
  • Defining Scope
  • Scope for Find Operations
  • Scope for Aggregate Operations
  • Scope for Get By ID Operations
  • Scope Function Parameters
• Authorization
  • Quick Start
  • Permission Schema
  • Rule Helpers
  • Policy Expressions (JSON AST)
  • Integration with GraphQL Yoga / Envelop
  • Legacy: Integration with graphql-middleware
• Middlewares
  • Adding Middlewares
  • Middleware Parameters
  • Common Use Cases
• Advanced Features
  • Field Extensions
  • Custom Mutations
  • Working with Existing Mongoose Models
  • Programmatic Data Access
• MCP Generation
  • Generating tool definitions
  • Standalone MCP server (stdio)
  • HTTP MCP endpoint (alongside GraphQL)
  • Options
  • Selecting and naming tools
  • Customizing tools
  • Limits
  • Tool middleware
  • Remote execution
  • Tool results and errors
  • Authentication
• Aggregation Queries
• Complete Example
• Resources
• License
• Contributing

✨ Features

• Automatic Schema Generation: Define your object model, and Simfinity.js generates all queries and mutations
• MongoDB or PostgreSQL: Choose the database facade once during application startup
• Powerful Querying: Typed filters, nested paths, pagination, sorting, and aggregations across the supported contract
• Aggregation Queries: Built-in support for GROUP BY queries with aggregation operations (SUM, COUNT, AVG, MIN, MAX)
• Auto-Generated Resolvers: Automatically generates resolve methods for relationship fields
• Automatic Index Creation: Generates MongoDB indexes for ObjectId fields and single references, including leaves inside embedded objects and embedded arrays; see the index reference
• Business Logic: Implement business logic and domain validations declaratively
• State Machines: Built-in support for declarative state machine workflows
• Lifecycle Hooks: Controller methods for granular control over operations
• Custom Validation: Field-level and type-level custom validations
• Relationship Management: Support for embedded and referenced relationships
• Authorization: Production-grade GraphQL authorization with RBAC/ABAC, function-based rules, declarative policy expressions, and native Envelop/Yoga plugin support

📦 Installation

npm install mongoose@^8.24.2 graphql@^16.11.0 @simtlix/simfinity-js@3.5.9

Prerequisites: Simfinity.js requires mongoose and graphql as peer dependencies. Keep them within the ranges above so your application and Simfinity share a single Mongoose and GraphQL instance; npm reports an out-of-range version as a peer conflict. The MCP transports need the optional peer @modelcontextprotocol/sdk@^1.31.0, which is not installed automatically, and graphql-middleware is not a Simfinity dependency.

PostgreSQL support

Simfinity releases @simtlix/simfinity-core, @simtlix/simfinity-sql, @simtlix/simfinity-mcp, @simtlix/simfinity-postgres, and the MongoDB facade in lockstep. Install the selected adapter from npm; shared dependencies resolve automatically. PostgreSQL runs the shared GraphQL query/mutation engine, including scopes, controllers, validators, state transitions and nested writes. It generates and validates tables, indexes, and real foreign keys, including inverse relations, explicit many-to-many linking entities, and references inside embedded objects. PostgreSQL installation does not pull Mongoose, MongoDB, or MCP dependencies.

Version 3.3.0 separates the driver-free relational runtime into @simtlix/simfinity-sql. PostgreSQL supplies the first SQL plugin; it owns physical SQL, types, schema initialization and pg. Existing createPostgres and namespace imports remain compatible, with unchanged generated PostgreSQL storage and FKs. Use the explicit composition API when you want to select a plugin:

import { createSQL } from '@simtlix/simfinity-sql';
import { postgresPlugin } from '@simtlix/simfinity-postgres';

const simfinity = createSQL({ plugin: postgresPlugin({ pool, schema: 'app' }) });

Install both packages directly when importing both. Only PostgreSQL is supported initially; see the SQL plugin guide for the contract, capabilities, dependency boundaries and extension requirements.

All publishable libraries live under packages/:

| Directory | npm package | | --- | --- | | packages/core | @simtlix/simfinity-core | | packages/sql | @simtlix/simfinity-sql | | packages/mongodb | @simtlix/simfinity-js | | packages/postgres | @simtlix/simfinity-postgres | | packages/mcp | @simtlix/simfinity-mcp |

The repository root is a private npm workspace for shared tests, documentation and release tooling. MongoDB retains its existing package name, public API and deep imports such as @simtlix/simfinity-js/src/auth/rules.js. Its legacy src/ modules that re-export public API (src/index.js, src/auth/index.js, src/auth/errors.js, src/auth/expressions.js, src/auth/rules.js, src/plugins.js, src/scalars.js, src/validators.js, src/mcp.js, src/const/*.js, src/errors/*.js, and their extensionless aliases) ship TypeScript declarations with the types of the package root and the matching @simtlix/simfinity-core subpaths; src/mongo/* is internal and undeclared. New code should still import auth, plugins, scalars and validators from the package root. The typed @simtlix/simfinity-core subpaths, such as @simtlix/simfinity-core/auth, need @simtlix/simfinity-core as a direct dependency pinned to the facade's exact version. Run development commands from the root; pack MongoDB with npm pack --workspace @simtlix/simfinity-js or use the release scripts to pack all five libraries. Pushing a release tag (vX.Y.Z) or publishing a GitHub release automatically publishes all five packages with GitHub Actions, attaches verified archives to the release, and deploys the stable documentation. Version changes and merges to master do not publish; the tag must match the aligned package versions and point to source already merged into master. See the release and OIDC setup guide.

The shared development and publication contract applies to contributors and coding agents: when a task includes publication, completion requires the GitHub tag and published release, verified packages in both registries, and the applicable documentation deployment. This rule is tracked in AGENTS.md and the always-applied Cursor workflow rule.

Enum filters resolve member names first, then declared internal values by strict equality, on both backends. For example, with ONE: { value: 'TWO' } and TWO: { value: 'two' }, filter "TWO" selects member TWO. Numeric internal values require numbers, not numeric strings. This applies to scalar lists, embedded/reference leaves and state filters across EQ, NE, LT, LTE, GT, GTE, BTW, IN and NIN. LIKE accepts string fields only. PostgreSQL writes and state guards continue to use internal enum values. Generated MongoDB models store numeric and boolean enum values as numbers and booleans, so MongoDB range filters, sorts and aggregate groupId values follow that type while PostgreSQL uses their text form ("10" before "2"); convert documents written by earlier versions as described in the schema guide.

The shared runtime preserves the v3.1 contract: generated relationships run target mi