Simfinity.js

Generate GraphQL APIs from object types, with PostgreSQL and MongoDB adapters, application hooks and optional MCP tools.

Comment

Simfinity.js: GraphQL, PostgreSQL, MongoDB and optional MCP

The project

I contribute to Simfinity.js, an Apache-2.0 Node.js project from Simtlix that generates a GraphQL API from GraphQLObjectType definitions. Register object types and relationships, and the library builds queries, CRUD mutations, filters, pagination and relationship handling around them.

The aim is to make the repeated parts of an API easier to maintain while keeping application logic close to the schema. Hooks, authorization rules and query scopes provide places to add that logic. Applications remain responsible for authentication and for passing a trusted user context.

How it fits together

Version 3.2 separates the shared runtime from database-specific behavior:

  • @simtlix/simfinity-core contains the driver-free runtime.
  • @simtlix/simfinity-js connects it to MongoDB through Mongoose.
  • @simtlix/simfinity-postgres connects it to PostgreSQL 15+ through the pg driver, without a MongoDB or Mongoose dependency.
  • @simtlix/simfinity-mcp optionally exposes selected GraphQL operations as MCP tools over stdio or Streamable HTTP.

That separation lets an application install the database adapter it needs. The adapters have documented differences, including PostgreSQL UUID identifiers and database-specific native model/session APIs. The compatibility guide describes those boundaries.

My recent contributions

My recent work has focused on the correctness of generated operations and their contracts:

  • Query filters and pagination: preserve every conjunctive filter term, including repeated conditions on one field; cast identifiers using the storage schema; resolve sort paths consistently; and reject invalid filter or pagination inputs. Merged change and regression coverage.
  • MCP execution and JSON Schema: preserve GraphQL defaults and nullability, apply result limits to error payloads, and handle cancellation and remote transport failures consistently. Merged change and regression coverage.

These changes belong to the wider Simfinity.js project, built by Simtlix and its contributors. The linked pull requests document my part, the reproduced cases and the checks performed.

What this work reinforced

Generated APIs need to preserve meaning across each boundary. A nullable GraphQL value needs a compatible tool input schema. Two conditions on the same database field still need to remain two conditions. Checking the generated shape is useful; exercising the resulting operation against the expected data is what exposes many of the difficult bugs.

Try it

The documentation includes runnable PostgreSQL and MongoDB starters, relationship examples, hooks and authorization guides. Start with the PostgreSQL quick start or the MongoDB quick start.

For MCP, there is also a runnable example with an operation allowlist and stdio transport. Source code and issues are in simtlix/simfinity.js.

Built With

Share this project:

Updates