![\"npm](\"https://img.shields.io/npm/v/@ambiten/core?color=0ea5e9&label=npm&style=flat-square\")
\n\n\n \n ![\"GitHub](\"https://img.shields.io/github/stars/AmbitenHQ/ambiten?style=flat-square&color=1E88E5\")
\n \n![\"multi-tenant](\"https://img.shields.io/badge/multi--tenant-native-6366f1?style=flat-square\"){kind=icon}
\n![\"context](\"https://img.shields.io/badge/context-aware-14b8a6?style=flat-square\"){kind=icon}
\n\n
\n A runtime and context-aware data platform for MongoDB applications.\n
\n\n\n Runtime-aware models, transactions, middleware, multi-tenancy, observability, and execution boundaries designed for modern applications.\n
\n\n\n\n---\n\n## Overview\n\n@ambiten/core is the foundation of the Ambiten platform.\n\nIt provides the runtime responsible for context propagation, model execution, transaction coordination, multi-tenancy, middleware orchestration, and operational observability across MongoDB applications.\n\nRather than treating data access as an isolated persistence concern, Ambiten treats execution itself as a runtime responsibility.\n\nThe goal is to reduce infrastructure plumbing while keeping execution predictable, observable, and safe under real production conditions.\n\n## What Ambiten Is\n\nAmbiten is not just a MongoDB ODM.\n\nIt is a runtime and context-aware execution platform that coordinates context propagation, transactions, multi-tenancy, middleware, instrumentation, and runtime policies across the entire execution lifecycle of an application.\n\nTraditional ODMs focus on mapping data.\n\nAmbiten focuses on coordinating execution.\n\n> Mongoose manages models.\n> Ambiten manages execution.\n\n## Installation\n\n```bash\nnpm install @ambiten/core mongodb\n```\n\n```ts\nimport {\n AmbitenClient,\n AmbitenModel,\n AmbitenSchema,\n AmbitenContext\n} from \"@ambiten/core\";\n\nconst client = new AmbitenClient({\n uri: process.env.MONGODB_URI,\n options: {\n dbName: \"app\"\n }\n});\n\nawait client.connect();\n\nconst userSchema = new AmbitenSchema({\n name: String,\n email: String\n});\n\nconst UserModel = new AmbitenModel({\n collectionName: \"users\",\n schema: userSchema,\n provider: client\n});\n\nawait AmbitenContext.run(\n {\n tenantId: \"tenant-a\",\n requestId: \"req-001\"\n },\n async () => {\n await UserModel.create({\n name: \"Alice\",\n email: \"alice@example.com\"\n });\n }\n);\n```\n\nThe application code remains focused on product behavior.\n\nThe runtime carries execution state.\n\n## Execution Model\n\nAmbiten organizes execution around request-scoped runtime boundaries.\n\n```text\nRequest\n ↓\nAdapter\n ↓\nAmbitenContext\n ↓\nMiddleware\n ↓\nAmbitenModel\n ↓\nProvider / AmbitenClient\n ↓\nMongoDB\n```\n\nInstead of manually threading tenant IDs, transaction sessions, request metadata, instrumentation payloads, or infrastructure state across services, the runtime keeps execution context attached to the active boundary.\n\nThis allows the same execution model to remain consistent across HTTP requests, background workers, queues, scheduled jobs, transactions, and serverless environments.\n\n## Core Capabilities\n\n### Context Runtime\n\nAmbitenContext provides request-scoped runtime state through AsyncLocalStorage.\n\n```ts\nawait AmbitenContext.run(\n {\n tenantId: \"tenant-a\"\n },\n async () => {\n await UserModel.find({});\n }\n);\n```\n\nThe active context can carry tenant identity, request metadata, sessions, budgets, runtime observers, instrumentation metadata, and operational state without forcing application services to manually pass them through every execution layer.\n\n### Runtime Models\n\nAmbitenModel provides CRUD and aggregation capabilities that participate directly in the runtime.\n\n```ts\nawait UserModel.updateOne(\n { email: \"alice@example.com\" },\n {\n $set: {\n active: true\n }\n }\n);\n```\n\nOperations can execute inside middleware boundaries, transaction scopes, tenant-aware resolution, instrumentation flows, caching layers, and policy enforcement without departing from familiar MongoDB patterns.\n\n### Multi-Tenancy & Transactions\n\nTenant isolation and transactional execution are coordinated through the runtime.\n\n```ts\nawait AmbitenContext.withTransaction(async () => {\n await UserModel.create(user);\n await AuditModel.create(log);\n});\n```\n\nThe runtime propagates active sessions automatically while tenant-aware resolution remains attached to the current execution boundary.\n\nApplication code stays focused on business logic rather than infrastructure coordination.\n\n### Observability & Instrumentation\n\nAmbiten includes runtime instrumentation through utilities such as `measureQuery()`.\n\n```ts\nawait measureQuery(\n {\n operation: \"find\",\n collectionName: \"users\"\n },\n async () => {\n return UserModel.find({});\n }\n);\n```\n\nInstrumentation can expose execution duration, tenant scope, transaction state, cache behavior, collection activity, and operational metadata for downstream observability systems.\n\n## Adapter-Driven Runtime\n\nAmbiten is adapter-driven.\n\nThe same runtime model can operate across Express, Fastify, GraphQL systems, NestJS applications, background workers, queues, and serverless environments while preserving consistent execution behavior.\n\nThe runtime remains responsible for execution coordination regardless of deployment model.\n\n## Why Ambiten Exists\n\nAs applications grow, execution concerns become scattered across services, middleware, repositories, background workers, and infrastructure layers.\n\nContext propagation becomes manual.\n\nTransactions become difficult to coordinate.\n\nTenant isolation becomes inconsistent.\n\nObservability becomes fragmented.\n\nAmbiten exists to centralize those concerns inside the runtime itself so applications remain focused on business logic while execution behavior stays consistent, observable, and safe.\n\n## Documentation\n\nThe official documentation covers runtime architecture, context propagation, transactions, middleware, instrumentation, multi-tenancy, adapters, deployment strategy, and production-oriented workflows.\n\nDocumentation:\n\nhttps://docs.ambiten.dev\n\n## Ecosystem\n\nThe Ambiten ecosystem extends beyond the core runtime and includes adapters, logging infrastructure, project scaffolding, GraphQL integration, observability tooling, and future platform capabilities built around the same execution model.\n\nAdditional packages continue to evolve around the platform.\n\n## Philosophy\n\n> Execution behavior should be enforced by the runtime, not maintained manually across application code.\n\nAmbiten exists to make systems more predictable, observable, and operationally consistent as complexity grows.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}