\n\n---\n\n \n \n\n 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.\n\n## Key capabilities\n\n- Schema validation and type-safe models\n- Middleware (pre/post hooks) for lifecycle events\n- Multi-tenancy with tenant context and lazy connection management\n- Redis-backed caching utilities for query results\n- Transaction helpers for multi-step operations\n- Aggregation pipeline helpers and convenience utilities\n- Change streams / real-time change listeners\n- Optional GraphQL schema generation and resolver wiring\n- CLI scaffolding and project bootstrap utilities\n\n---\n\n## Installation\n\nInstall from npm or using yarn:\n\n```bash\nnpm install @abimongo/core\n# or\nyarn add @abimongo/core\n```\n\nIf you are using TypeScript, make sure `tsconfig.json` is configured to include node types and target a supported ECMAScript version.\n\n---\n\n## Quick start\n\nThis example demonstrates model creation and basic CRUD operations using the high-level API.\n\n```ts\nimport { AbimongoClient } from '@abimongo/core';\n\nconst clientDB = new AbimongoClient('mongodb://localhost:27017');\n\nawait clientDB.connnect();\nconsole.log('MongoDB connection successful.')\n```\n\n```ts\nimport { AbimongoSchema, AbimongoModel } from '@abimongo/core';\n\nconst userSchema = new AbimongoSchema({\n name: { type: String, required: true },\n email: { type: String, required: true, unique: true },\n age: { type: Number },\n});\n\nconst UserModel = new AbimongoModel({\n collectionName: 'users',\n schema: userSchema,\n});\n\nasync function example() {\n const created = await UserModel.create({ name: 'Jane', email: 'jane@example.com', age: 28 });\n const found = await UserModel.find({ age: { $gte: 18 } });\n await UserModel.updateOne({ email: 'jane@example.com' }, { $set: { age: 29 } });\n await UserModel.deleteOne({ email: 'jane@example.com' });\n}\n\nexample().catch(console.error);\n```\n\n---\n\n## Multi-tenancy\n\n@abimongo/core includes helpers for multi-tenant applications. You can register tenants with connection URIs and use a tenant-aware model resolver.\n\nExample (Express middleware + lazy tenant connections):\n\n```ts\nimport express from 'express';\nimport { applyMultiTenancy, getTenantModel } from '@abimongo/core';\n\nconst app = express();\n\nconst tenants = {\n tenant1: 'mongodb://localhost:27017/tenant1',\n tenant2: 'mongodb://localhost:27017/tenant2',\n};\n\napplyMultiTenancy(app, tenants, { headerKey: 'x-tenant-id', initOptions: { lazy: true } });\n\napp.get('/users', async (req, res) => {\n const tenantId = req.headers['x-tenant-id'] as string;\n const UserModel = await getTenantModel({ modelName: 'User', tenantId });\n const users = await UserModel.find();\n res.json(users);\n});\n\napp.listen(3000);\n```\n\nNotes\n\n- Tenant connections are managed by `MultiTenantManager`. Use `registerTenant` at runtime to add tenants dynamically.\n- `TenantContext` provides a way to run code bound to a tenant without threading tenant ids through every function call.\n\n---\n\n## Schema validation & middleware\n\nDefine schemas with validation rules (types, required, min/max, unique) and attach middleware hooks for lifecycle events.\n\n```ts\nconst productSchema = new AbimongoSchema({\n name: { type: String, required: true },\n price: { type: Number, required: true, min: 0 },\n category: { type: String },\n});\n\nproductSchema.pre('save', async (doc) => { /* ... */ });\nproductSchema.post('save', async (doc) => { /* ... */ });\n```\n\n---\n\n## Transactions\n\nHelpers are provided to make transactional updates simpler. These utilities use MongoDB sessions under the hood.\n\n```ts\nawait UserModel.updateWithTransaction({ email: 'jane@example.com' }, { $set: { age: 30 } });\n```\n\n---\n\n## Caching\n\nUse built-in Redis-backed caching helpers for expensive aggregation queries or frequently requested results.\n\n```ts\nconst cached = await UserModel.aggregateWithCache([\n { $match: { active: true } },\n], 'active_users_cache', 300);\n```\n\n---\n\n## Change streams\n\nListen for real-time changes on collections with a simple watcher API.\n\n```ts\nUserModel.watchChanges((change) => {\n console.log('change:', change);\n});\n```\n\n---\n\n## GraphQL integration\n\nOptional GraphQL helpers can generate type definitions and resolvers from your models. The feature supports queries, mutations and subscriptions and includes RBAC hooks.\n\nAPI (examples):\n\n- `AbimongoGraphQL.generateSchema({ models?, options? })` – generate an executable GraphQL schema.\n- `schema.customResolvers(...)` and `schema.customTypeDefs(...)` – extend generated schema with custom definitions.\n\nExample (Apollo Server):\n\n```ts\nimport { AbimongoGraphQL } from '@abimongo/core';\nimport { ApolloServer } from '@apollo/server';\n\nconst schema = AbimongoGraphQL.generateSchema({ models: [/* models */], options: { enableSubscriptions: true } });\nconst server = new ApolloServer({ schema });\n// start the server with your preferred method\n```\n\nNote: GraphQL generation is powerful but may be considered experimental for very complex schemas—review generated types before using them in production.\n\n---\n\n## CLI scaffolding\n\nThe accompanying CLI accelerates project setup and scaffolding of models, schemas and GraphQL components.\n\n```bash\n# Run the CLI without installing globally (recommended):\nnpx abimongo init my-app-name\n\n# Example: scaffold with GraphQL, multi-tenant and logger support (no installs by default):\nnpx abimongo init my-app-name --with-graphql --multi-tenant --logger\n\n# If you want the scaffold to auto-install dependencies into the generated project, pass `--install`:\nnpx abimongo init my-app-name --with-graphql --multi-tenant --logger --install\n\n# Notes:\n# - By default the scaffold does NOT run `npm`/`pnpm` installs. This keeps scaffolding fast and CI-friendly.\n# - Use `--install` to opt into installing `@abimongo/core` and `@abimongo/logger` into the generated project.\n# - The `abimongo` binary is provided by `@abimongo/core` and is safe to run via `npx` or after installing the package locally.\n```\n\nFlags will toggle features in the generated `abimongo.config.json`. If you omit a flag you can still enable features later by editing the config.\n\nSee the docs-site for a full CLI guide: docs-site/docs/guides/CLI-Scaffolding.md\n\n---\n\n## RBAC\n\nBuilt-in role-based access control utilities make it straightforward to protect resolvers or REST handlers.\n\n- `enforceRBAC(resolver, action)` — wrap resolvers with permission checks\n- `getRBACAction(resolver)` — inspect mapped action\n\nThe RBAC layer integrates with caching for efficient permission evaluation.\n\n---\n\n## Plugin system\n\nExtend the platform using plugins that can add behavior at the model, schema or manager layer.\n\n---\n\n## Bootstrapping\n\n`AbimongoBootstrap` helps initialize new projects, creating a recommended folder layout and a starter `abimongo.config.json`.\n\n---\n\n## API reference (short)\n\nAbbreviated list of commonly used APIs. See the generated docs in the repo for full signatures and options.\n\n- AbimongoModel\n- `create(doc)`\n- `find(filter)`\n- `updateOne(filter, update)`\n- `deleteOne(filter)`\n- `aggregate(pipeline)`\n\n- TenantContext\n- `run(tenantId, callback)`\n- `getTenantId()`\n\n- MultiTenantManager\n- `registerTenant(tenantId, uri)`\n- `getClient(tenantId)`\n\n- AbimongoGraphQL\n- `generateSchema({ models, options })`\n\n- RBAC utilities\n- `enforceRBAC(resolver, action)`\n\n---\n\n## Contributing\n\nContributions are welcome. Please check `CONTRIBUTING.md` in the repository root for guidelines on code style, tests and committing.\n\n---\n\n## License\n\nThis package is published under the MIT license. See the project `LICENSE` for details.\n\n---\n\n## Support\n\nIf you find a bug or need help, open an issue in the repository.\n\n---\n\n## Acknowledgements\n\nThanks to the MongoDB Node.js Driver team and the community contributors.\n","readmeFilename":"README.md","homepage":"https://github.com/NodEm9/abimongo#readme","repository":{"type":"git","url":"git+https://github.com/NodEm9/abimongo.git"},"bugs":{"url":"https://github.com/NodEm9/abimongo/issues"}}
![\"Abimongo](\"../../abimongo-brand/abimongo-logo_socials.png\"){kind=logo}
\n![\"npm](\"https://img.shields.io/npm/v/@abimongo/core.svg?style=flat-square&color=00C4B4\")
\n ![\"GitHub](\"https://img.shields.io/github/stars/Nodem9/abimongo?style=flat-square&color=1E88E5\")
\n ![\"Docs\"](\"https://img.shields.io/badge/docs-online-blue?style=flat-square\"){kind=icon}
\n