@ambiten/core 1.0.0

package/dist/init-cli/generate.project.d.ts

@@ -0,0 +1,9 @@
+import type { AmbitenConfig } from '../types';
+export interface GeneratedProjectResult {
+    projectRoot: string;
+    configPath: string;
+    entryFilePath: string;
+}
+export declare function generateProject(options: AmbitenConfig): Promise<GeneratedProjectResult>;
+export declare function generateProjectWithConfig(config: AmbitenConfig): Promise<GeneratedProjectResult>;
+//# sourceMappingURL=generate.project.d.ts.map

package/dist/init-cli/generate.project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.project.d.ts","sourceRoot":"","sources":["../../src/init-cli/generate.project.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,sBAAsB,CAAC,CA8BjC;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,sBAAsB,CAAC,CAKjC"}

package/dist/init-cli/generate.project.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateProject = generateProject;
+exports.generateProjectWithConfig = generateProjectWithConfig;
+const tslib_1 = require("tslib");
+const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const path_1 = tslib_1.__importDefault(require("path"));
+const templates_1 = require("../templates");
+const utils_1 = require("../utils");
+async function generateProject(options) {
+    const startedAt = Date.now();
+    const projectName = options.projectName?.trim() || 'Ambiten-app';
+    const projectRoot = path_1.default.resolve(process.cwd(), projectName);
+    const configPath = path_1.default.join(projectRoot, 'Ambiten.config.json');
+    const entryFilePath = path_1.default.join(projectRoot, 'src', 'main.ts');
+    console.log((0, utils_1.colorize)(`\n🚀 Creating project "${projectName}"`, 'green'));
+    console.log((0, utils_1.colorize)(`📁 Location: ${projectRoot}\n`, 'blue'));
+    await fs_extra_1.default.ensureDir(projectRoot);
+    const logger = (0, utils_1.createScaffoldLogger)(projectRoot);
+    const resolvedOptions = {
+        ...options,
+        projectName,
+    };
+    await (0, templates_1.generateAppStructure)(projectRoot, resolvedOptions, logger);
+    const durationMs = Date.now() - startedAt;
+    logger.printSummary(projectName, resolvedOptions, durationMs);
+    return {
+        projectRoot,
+        configPath,
+        entryFilePath,
+    };
+}
+async function generateProjectWithConfig(config) {
+    return generateProject({
+        ...config,
+        projectName: config.projectName || 'Ambiten-app',
+    });
+}

package/dist/instrumentation/index.d.ts

@@ -0,0 +1,3 @@
+export * from './measureQueryWithErrors';
+export * from './measureQuery.browser';
+//# sourceMappingURL=index.d.ts.map

package/dist/instrumentation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/instrumentation/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC"}

package/dist/instrumentation/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./measureQueryWithErrors"), exports);
+tslib_1.__exportStar(require("./measureQuery.browser"), exports);

package/dist/instrumentation/measureQuery.browser.d.ts

@@ -0,0 +1,3 @@
+import { QueryInstrumentationMeta } from "./measureQueryWithErrors";
+export declare function measureQueryForBrowser<T>(_meta: QueryInstrumentationMeta, executor: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=measureQuery.browser.d.ts.map

package/dist/instrumentation/measureQuery.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measureQuery.browser.d.ts","sourceRoot":"","sources":["../../src/instrumentation/measureQuery.browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,KAAK,EAAE,wBAAwB,EAC/B,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAEZ"}

package/dist/instrumentation/measureQuery.browser.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.measureQueryForBrowser = measureQueryForBrowser;
+async function measureQueryForBrowser(_meta, executor) {
+    return executor();
+}

package/dist/instrumentation/measureQueryWithErrors.d.ts

@@ -0,0 +1,11 @@
+export interface QueryInstrumentationMeta {
+    operation: string;
+    collectionName?: string;
+    filter?: unknown;
+    update?: unknown;
+    pipeline?: unknown;
+    documentCount?: number;
+    extra?: Record<string, any>;
+}
+export declare function measureQuery<T>(meta: QueryInstrumentationMeta, executor: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=measureQueryWithErrors.d.ts.map

package/dist/instrumentation/measureQueryWithErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measureQueryWithErrors.d.ts","sourceRoot":"","sources":["../../src/instrumentation/measureQueryWithErrors.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,wBAAwB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED,wBAAsB,YAAY,CAAC,CAAC,EACnC,IAAI,EAAE,wBAAwB,EAC9B,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC,CA8FZ"}

package/dist/instrumentation/measureQueryWithErrors.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.measureQuery = measureQuery;
+const perf_hooks_1 = require("perf_hooks");
+const ambitenContext_1 = require("../context/ambitenContext");
+async function measureQuery(meta, executor) {
+    if (!ambitenContext_1.AmbitenContext.hasActiveContext()) {
+        throw new Error('[Ambiten] Missing runtime context.');
+    }
+    const logger = ambitenContext_1.AmbitenContext.getLogger();
+    const observer = ambitenContext_1.AmbitenContext.getObserver();
+    const loggerMeta = ambitenContext_1.AmbitenContext.getLoggerMeta() ?? {};
+    const tenantId = ambitenContext_1.AmbitenContext.getTenantId();
+    const requestId = ambitenContext_1.AmbitenContext.getRequestId();
+    const dbName = ambitenContext_1.AmbitenContext.getDbName();
+    const collectionName = meta.collectionName ?? ambitenContext_1.AmbitenContext.getCollectionName();
+    const budgetAfterIncrement = ambitenContext_1.AmbitenContext.incrementQueries();
+    const start = perf_hooks_1.performance.now();
+    try {
+        const result = await executor();
+        const durationMs = Math.round((perf_hooks_1.performance.now() - start) * 100) / 100;
+        const budgetAfterTime = ambitenContext_1.AmbitenContext.addQueryTime(durationMs);
+        const payload = {
+            operation: meta.operation,
+            collectionName,
+            durationMs,
+            status: 'success',
+            tenantId,
+            requestId,
+            dbName,
+            filter: meta.filter,
+            update: meta.update,
+            pipeline: meta.pipeline,
+            documentCount: meta.documentCount,
+            queriesExecuted: budgetAfterIncrement.queriesExecuted,
+            maxQueries: budgetAfterIncrement.maxQueries,
+            totalBudgetUsed: budgetAfterTime.totalTimeMs,
+            ...loggerMeta,
+            ...(meta.extra ?? {})
+        };
+        setImmediate(() => {
+            observer?.onQuery?.(payload);
+            if (logger?.info) {
+                logger.info('[Ambiten Query]', payload);
+            }
+            else if (ambitenContext_1.AmbitenContext.isDebug()) {
+                console.log('[Ambiten Query]', payload);
+            }
+        });
+        return result;
+    }
+    catch (error) {
+        const durationMs = Math.round((perf_hooks_1.performance.now() - start) * 100) / 100;
+        const budgetAfterTime = ambitenContext_1.AmbitenContext.addQueryTime(durationMs);
+        const payload = {
+            operation: meta.operation,
+            collectionName,
+            durationMs,
+            status: 'error',
+            tenantId,
+            requestId,
+            dbName,
+            filter: meta.filter,
+            update: meta.update,
+            pipeline: meta.pipeline,
+            documentCount: meta.documentCount,
+            queriesExecuted: budgetAfterTime.queriesExecuted,
+            maxQueries: budgetAfterTime.maxQueries,
+            totalBudgetUsed: budgetAfterTime.totalTimeMs,
+            errorMessage: error?.message,
+            errorName: error?.name,
+            ...loggerMeta,
+            ...(meta.extra ?? {})
+        };
+        setImmediate(() => {
+            observer?.onQueryError?.({
+                ...payload,
+                error
+            });
+            if (logger?.error) {
+                logger.error('[Ambiten Query Error]', payload);
+            }
+            else if (ambitenContext_1.AmbitenContext.isDebug()) {
+                console.error('[Ambiten Query Error]', payload);
+            }
+        });
+        throw error;
+    }
+}
+;

package/dist/lib-core/ambitenClient.d.ts

@@ -0,0 +1,115 @@
+import { MongoClient, Db, Document, Collection, TopologyClosedEvent, TopologyOpeningEvent, ClientSession } from 'mongodb';
+import 'dotenv/config';
+import type { AmbitenClientConfig, BootstrapClient, ModelContext } from '../types';
+import type { Transporter } from '@ambiten/logger';
+type ClusterInfo = {
+    type: 'sharded';
+} | {
+    type: 'replicaSet';
+    setName?: string;
+    hosts?: string[];
+} | {
+    type: 'standalone';
+};
+/**
+ * AmbitenClient is a MongoDB client wrapper that provides a simplified interface
+ * for connecting to and interacting with MongoDB databases.
+ */
+export declare class AmbitenClient implements BootstrapClient {
+    private readonly _opts;
+    private _uri;
+    private _client?;
+    private _db?;
+    private collectionRef?;
+    private _connected;
+    private readonly _defaultDbName;
+    private _overrideDbName?;
+    private static instances;
+    private static defaultUri;
+    constructor(_opts: AmbitenClientConfig);
+    static init(opts?: Partial<AmbitenClientConfig>): AmbitenClient;
+    private ensureMongoDependency;
+    /**
+     * Resolution order:
+     * 1. explicit ctx.db
+     * 2. tenant-aware db resolution
+     * 3. explicit ctx.dbName on base client
+     * 4. mutable override dbName
+     * 5. default dbName
+     */
+    db(ctx?: ModelContext): Promise<Db>;
+    static db(ctx?: ModelContext): Promise<Db>;
+    validateUri(uri: string): void;
+    connect(): Promise<this>;
+    client(ctx?: ModelContext): Promise<MongoClient>;
+    useCollection(collectionName: string): Promise<Collection<any>>;
+    collection<T extends Document = Document>(collectionName: string, ctx?: ModelContext): Promise<Collection<T>>;
+    getCollection<T extends Document>(collectionName: string, ctx?: ModelContext): Promise<Collection<T>>;
+    getClusterInfo(): Promise<ClusterInfo>;
+    /**
+ * Resolves database + session + runtime binding
+ */
+    static resolveRuntime(): Promise<{
+        db: Db;
+        session: ClientSession | undefined;
+    }>;
+    /**
+     * Mutable legacy helper. Prefer withDatabase() or withScope() in request-safe flows.
+     */
+    useDatabase(dbName: string): Promise<{
+        db: Db;
+        client: MongoClient;
+    }>;
+    withDatabase(dbName: string): BootstrapClient;
+    /**
+ * Resolves the active database name.
+ *
+ * @param overrideDbName - Optional database override.
+ * @returns The resolved database name.
+ * @throws {Error} When no database name can be resolved.
+ */
+    private resolveDbName;
+    /**
+ * Resolves the active client execution scope by combining explicit method
+ * arguments, active Ambiten runtime context, and client-level defaults.
+ *
+ * Resolution priority:
+ * 1. Explicit method arguments
+ * 2. Active Ambiten runtime context
+ * 3. Client configuration
+ * 4. Client defaults
+ *
+ * This method does not mutate runtime context or client configuration.
+ *
+ * @param input - Optional scope overrides for database, collection, and session.
+ * @returns The resolved execution scope for client-level operations.
+ * @throws {Error} When no database name can be resolved.
+ */
+    private resolveClientScope;
+    private static resolveDbFromTenant;
+    withContext<R>(context: {
+        tenantId?: string;
+        requestId?: string;
+        dbName?: string;
+        collectionName?: string;
+        session?: ClientSession;
+    }, callback: () => Promise<R>): Promise<R>;
+    private logWithContext;
+    withTenant(tenantId: string): BootstrapClient;
+    withScope(scope: {
+        tenantId?: string;
+        dbName?: string;
+    }): BootstrapClient;
+    resetDatabase(): void;
+    startSession(ctx?: ModelContext): Promise<ClientSession>;
+    dropCollection(collectionName?: string, ctx?: ModelContext): Promise<void>;
+    dropDatabase(ctx?: ModelContext): Promise<boolean>;
+    close(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    static handleTopologyEvent(event: TopologyOpeningEvent | TopologyClosedEvent): void;
+    static handleLogBatch(batch: Array<TopologyOpeningEvent | TopologyClosedEvent>, transporter?: Pick<Transporter, 'write'>): Promise<void>;
+}
+export declare function createAmbitenClientModule(opts: AmbitenClientConfig): AmbitenClient;
+export {};
+//# sourceMappingURL=ambitenClient.d.ts.map

package/dist/lib-core/ambitenClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ambitenClient.d.ts","sourceRoot":"","sources":["../../src/lib-core/ambitenClient.ts"],"names":[],"mappings":"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"}