@abimongo/core

A production-ready, TypeScript-first ORM/ODM for MongoDB built on the official MongoDB Node.js driver. @abimongo/core focuses on developer ergonomics, multi-tenant support, caching, and first-class GraphQL integration while keeping the API small and extensible.

Key capabilities

• Schema validation and type-safe models

• Middleware (pre/post hooks) for lifecycle events

• Multi-tenancy with tenant context and lazy connection management

• Redis-backed caching utilities for query results

• Transaction helpers for multi-step operations

• Aggregation pipeline helpers and convenience utilities

• Change streams / real-time change listeners

• Optional GraphQL schema generation and resolver wiring

• CLI scaffolding and project bootstrap utilities

  ---

  Installation

  Install from npm or using yarn:

  npm install @abimongo/core
  # or
  yarn add @abimongo/core

  Local development note

  If you're developing or testing @abimongo/core locally, avoid installing a runtime copy of graphql inside the @abimongo/core repository itself. graphql is a peer dependency and should be provided by the consuming app. Installing graphql in both the library repo and the consumer app can cause Node to load multiple physical copies of the graphql runtime which leads to runtime errors such as "GraphQLSchema from another module or realm".

  Recommended approaches when developing locally:

  • Use a pnpm workspace or pnpm add ../path/to/abimongo/packages/core from the consumer app so the consumer's node_modules provides graphql.

  • If you need to run pnpm install in the abimongo repo for dev work, avoid leaving graphql installed there while testing the consumer app; you can reinstall dev dependencies after testing.

  • Treat graphql as a peer dependency (it already is) and ensure the consumer app has an explicit graphql dependency or overrides configured.

    If you are using TypeScript, make sure tsconfig.json is configured to include node types and target a supported ECMAScript version.

    ---

    Quick start

    This example demonstrates model creation and basic CRUD operations using the high-level API.

    import { AbimongoClient } from '@abimongo/core';
    
    const clientDB = new AbimongoClient('mongodb://localhost:27017');
    
    await clientDB.connnect();
    console.log('MongoDB connection successful.')

    import { AbimongoSchema, AbimongoModel } from '@abimongo/core';
    
    const userSchema = new AbimongoSchema({
      name: { type: String, required: true },
      email: { type: String, required: true, unique: true },
      age: { type: Number },
    });
    
    const UserModel = new AbimongoModel({
      collectionName: 'users',
      schema: userSchema,
    });
    
    async function example() {
      const created = await UserModel.create({ name: 'Jane', email: '[email protected]', age: 28 });
      const found = await UserModel.find({ age: { $gte: 18 } });
      await UserModel.updateOne({ email: '[email protected]' }, { $set: { age: 29 } });
      await UserModel.deleteOne({ email: '[email protected]' });
    }
    
    example().catch(console.error);

    ---

    Multi-tenancy

    @abimongo/core includes helpers for multi-tenant applications. You can register tenants with connection URIs and use a tenant-aware model resolver.

    Example (Express middleware + lazy tenant connections):

    import express from 'express';
    import { applyMultiTenancy, getTenantModel } from '@abimongo/core';
    
    const app = express();
    
    const tenants = {
      tenant1: 'mongodb://localhost:27017/tenant1',
      tenant2: 'mongodb://localhost:27017/tenant2',
    };
    
    applyMultiTenancy(app, tenants, { headerKey: 'x-tenant-id', initOptions: { lazy: true } });
    
    app.get('/users', async (req, res) => {
      const tenantId = req.headers['x-tenant-id'] as string;
      const UserModel = await getTenantModel({ modelName: 'User', tenantId });
      const users = await UserModel.find();
      res.json(users);
    });
    
    app.listen(3000);

    Notes

  • Tenant connections are managed by MultiTenantManager. Use registerTenant at runtime to add tenants dynamically.

  • TenantContext provides a way to run code bound to a tenant without threading tenant ids through every function call.

    ---

    Schema validation & middleware

    Define schemas with validation rules (types, required, min/max, unique) and attach middleware hooks for lifecycle events.

    const productSchema = new AbimongoSchema({
      name: { type: String, required: true },
      price: { type: Number, required: true, min: 0 },
      category: { type: String },
    });
    
    productSchema.pre('save', async (doc) => { /* ... */ });
    productSchema.post('save', async (doc) => { /* ... */ });

    ---

    Transactions

    Helpers are provided to make transactional updates simpler. These utilities use MongoDB sessions under the hood.

    await UserModel.updateWithTransaction({ email: '[email protected]' }, { $set: { age: 30 } });

    ---

    Caching

    Use built-in Redis-backed caching helpers for expensive aggregation queries or frequently requested results.

    const cached = await UserModel.aggregateWithCache([
      { $match: { active: true } },
    ], 'active_users_cache', 300);

    ---

    Change streams

    Listen for real-time changes on collections with a simple watcher API.

    UserModel.watchChanges((change) => {
      console.log('change:', change);
    });

    ---

    GraphQL integration

    Optional GraphQL helpers can generate type definitions and resolvers from your models. The feature supports queries, mutations and subscriptions and includes RBAC hooks.

    API (examples):

  • AbimongoGraphQL.generateSchema({ models?, options? }) – generate an executable GraphQL schema.

  • schema.customResolvers(...) and schema.customTypeDefs(...) – extend generated schema with custom definitions.

    Example (Apollo Server):

    import { AbimongoGraphQL } from '@abimongo/core';
    import { ApolloServer } from '@apollo/server';
    
    const schema = AbimongoGraphQL.generateSchema({ models: [/* models */], options: { enableSubscriptions: true } });
    const server = new ApolloServer({ schema });
    // start the server with your preferred method

    Note: GraphQL generation is powerful but may be considered experimental for very complex schemas—review generated types before using them in production.

    ---

    CLI scaffolding

    The accompanying CLI accelerates project setup and scaffolding of models, schemas and GraphQL components.

    # Run the CLI without installing globally (recommended):
    npx abimongo init my-app-name
    
    # Example: scaffold with GraphQL, multi-tenant and logger support (no installs by default):
    npx abimongo init my-app-name --with-graphql --multi-tenant --logger
    
    # If you want the scaffold to auto-install dependencies into the generated project, pass `--install`:
    npx abimongo init my-app-name --with-graphql --multi-tenant --logger --install
    
    # Notes:
    # - By default the scaffold does NOT run `npm`/`pnpm` installs. This keeps scaffolding fast and CI-friendly.
    # - Use `--install` to opt into installing `@abimongo/core` and `@abimongo/logger` into the generated project.
    # - The `abimongo` binary is provided by `@abimongo/core` and is safe to run via `npx` or after installing the package locally.

    Flags will toggle features in the generated abimongo.config.json. If you omit a flag you can still enable features later by editing the config.

    See the docs-site for a full CLI guide: docs-site/docs/guides/CLI-Scaffolding.md

    ---

    RBAC

    Built-in role-based access control utilities make it straightforward to protect resolvers or REST handlers.

  • enforceRBAC(resolver, action) — wrap resolvers with permission checks

  • getRBACAction(resolver) — inspect mapped action

    The RBAC layer integrates with caching for efficient permission evaluation.

    ---

    Plugin system

    Extend the platform using plugins that can add behavior at the model, schema or manager layer.

    ---

    Bootstrapping

    AbimongoBootstrap helps initialize new projects, creating a recommended folder layout and a starter abimongo.config.json.

    ---

    API reference (short)

    Abbreviated list of commonly used APIs. See the generated docs in the repo for full signatures and options.

  • AbimongoModel

    • create(doc)
    • find(filter)
    • updateOne(filter, update)
    • deleteOne(filter)
    • aggregate(pipeline)

  • TenantContext

    • run(tenantId, callback)
    • getTenantId()

  • MultiTenantManager

    • registerTenant(tenantId, uri)
    • getClient(tenantId)

  • AbimongoGraphQL

    • generateSchema({ models, options })

  • RBAC utilities

    • enforceRBAC(resolver, action)

    ---

    Contributing

    Contributions are welcome. Please check CONTRIBUTING.md in the repository root for guidelines on code style, tests and committing.

    ---

    License

    This package is published under the MIT license. See the project LICENSE for details.

    ---

    Support

    If you find a bug or need help, open an issue in the repository.

    ---

    Acknowledgements

    Thanks to the MongoDB Node.js Driver team and the community contributors.