Overview

@ambiten/core is the foundation of the Ambiten platform.

It provides the runtime responsible for context propagation, model execution, transaction coordination, multi-tenancy, middleware orchestration, and operational observability across MongoDB applications.

Rather than treating data access as an isolated persistence concern, Ambiten treats execution itself as a runtime responsibility.

The goal is to reduce infrastructure plumbing while keeping execution predictable, observable, and safe under real production conditions.

What Ambiten Is

Ambiten is not just a MongoDB ODM.

It 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.

Traditional ODMs focus on mapping data.

Ambiten focuses on coordinating execution.

Mongoose manages models. Ambiten manages execution.

Installation

npm install @ambiten/core mongodb

import {
  AmbitenClient,
  AmbitenModel,
  AmbitenSchema,
  AmbitenContext
} from "@ambiten/core";

const client = new AmbitenClient({
  uri: process.env.MONGODB_URI,
  options: {
    dbName: "app"
  }
});

await client.connect();

const userSchema = new AmbitenSchema({
  name: String,
  email: String
});

const UserModel = new AmbitenModel({
  collectionName: "users",
  schema: userSchema,
  provider: client
});

await AmbitenContext.run(
  {
    tenantId: "tenant-a",
    requestId: "req-001"
  },
  async () => {
    await UserModel.create({
      name: "Alice",
      email: "[email protected]"
    });
  }
);

The application code remains focused on product behavior.

The runtime carries execution state.

Execution Model

Ambiten organizes execution around request-scoped runtime boundaries.

Request
  ↓
Adapter
  ↓
AmbitenContext
  ↓
Middleware
  ↓
AmbitenModel
  ↓
Provider / AmbitenClient
  ↓
MongoDB

Instead 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.

This allows the same execution model to remain consistent across HTTP requests, background workers, queues, scheduled jobs, transactions, and serverless environments.

Core Capabilities

Context Runtime

AmbitenContext provides request-scoped runtime state through AsyncLocalStorage.

await AmbitenContext.run(
  {
    tenantId: "tenant-a"
  },
  async () => {
    await UserModel.find({});
  }
);

The 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.

Runtime Models

AmbitenModel provides CRUD and aggregation capabilities that participate directly in the runtime.

await UserModel.updateOne(
  { email: "[email protected]" },
  {
    $set: {
      active: true
    }
  }
);

Operations can execute inside middleware boundaries, transaction scopes, tenant-aware resolution, instrumentation flows, caching layers, and policy enforcement without departing from familiar MongoDB patterns.

Multi-Tenancy & Transactions

Tenant isolation and transactional execution are coordinated through the runtime.

await AmbitenContext.withTransaction(async () => {
  await UserModel.create(user);
  await AuditModel.create(log);
});

The runtime propagates active sessions automatically while tenant-aware resolution remains attached to the current execution boundary.

Application code stays focused on business logic rather than infrastructure coordination.

Observability & Instrumentation

Ambiten includes runtime instrumentation through utilities such as measureQuery().

await measureQuery(
  {
    operation: "find",
    collectionName: "users"
  },
  async () => {
    return UserModel.find({});
  }
);

Instrumentation can expose execution duration, tenant scope, transaction state, cache behavior, collection activity, and operational metadata for downstream observability systems.

Adapter-Driven Runtime

Ambiten is adapter-driven.

The same runtime model can operate across Express, Fastify, GraphQL systems, NestJS applications, background workers, queues, and serverless environments while preserving consistent execution behavior.

The runtime remains responsible for execution coordination regardless of deployment model.

Why Ambiten Exists

As applications grow, execution concerns become scattered across services, middleware, repositories, background workers, and infrastructure layers.

Context propagation becomes manual.

Transactions become difficult to coordinate.

Tenant isolation becomes inconsistent.

Observability becomes fragmented.

Ambiten exists to centralize those concerns inside the runtime itself so applications remain focused on business logic while execution behavior stays consistent, observable, and safe.

Documentation

The official documentation covers runtime architecture, context propagation, transactions, middleware, instrumentation, multi-tenancy, adapters, deployment strategy, and production-oriented workflows.

Documentation:

https://ambiten.dev

Ecosystem

The 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.

Additional packages continue to evolve around the platform.

Philosophy

Execution behavior should be enforced by the runtime, not maintained manually across application code.

Ambiten exists to make systems more predictable, observable, and operationally consistent as complexity grows.

License

MIT