@ambiten/core 1.0.0

package/dist/config/loadAmbitenConfig.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAmbitenConfig = loadAmbitenConfig;
+const tslib_1 = require("tslib");
+const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const path_1 = tslib_1.__importDefault(require("path"));
+const ajv_1 = tslib_1.__importDefault(require("ajv"));
+const ambiten_config_schema_json_1 = tslib_1.__importDefault(require("./ambiten.config.schema.json"));
+const ajv = new ajv_1.default({
+    allErrors: true,
+    useDefaults: true,
+    strict: false,
+    coerceTypes: true,
+});
+let validate = null;
+const DEFAULT_CONFIG_FILENAME = 'ambiten.config.json';
+function normalizeAmbitenConfig(rawConfig) {
+    const cfg = { ...rawConfig };
+    if (typeof cfg.logger === 'boolean') {
+        cfg.logger = { enabled: cfg.logger };
+    }
+    if (cfg.logger && typeof cfg.logger === 'object') {
+        if (typeof cfg.logger.enableMetrics === 'boolean') {
+            cfg.logger.enableMetrics = {
+                enabled: cfg.logger.enableMetrics,
+                logInterval: 60000,
+            };
+        }
+        if (!cfg.logger.enableMetrics) {
+            cfg.logger.enableMetrics = {
+                enabled: false,
+                logInterval: 60000,
+            };
+        }
+        if (typeof cfg.logger.compressLogFiles === 'boolean') {
+            cfg.logger.compressLogFiles = {
+                enabled: cfg.logger.compressLogFiles,
+            };
+        }
+        if (!cfg.logger.compressLogFiles) {
+            cfg.logger.compressLogFiles = {
+                enabled: false,
+            };
+        }
+    }
+    if (typeof cfg.graphql === 'boolean') {
+        cfg.graphql = { enabled: cfg.graphql };
+    }
+    if (typeof cfg.advanced === 'boolean') {
+        cfg.advanced = {
+            garbageCollector: { enabled: cfg.advanced },
+        };
+    }
+    if (cfg.advanced && typeof cfg.advanced.garbageCollector === 'boolean') {
+        cfg.advanced.garbageCollector = {
+            enabled: cfg.advanced.garbageCollector,
+        };
+    }
+    if (!cfg.features) {
+        cfg.features = {};
+    }
+    if (typeof cfg.features.useRedisCache === 'undefined') {
+        cfg.features.useRedisCache = false;
+    }
+    return cfg;
+}
+function assertValidAmbitenConfig(config) {
+    if (!config.connection?.uri) {
+        throw new Error('Invalid config: "connection.uri" is required.');
+    }
+    if (config.multiTenant?.enabled &&
+        config.multiTenant.tenants &&
+        typeof config.multiTenant.tenants !== 'object') {
+        throw new Error('Invalid config: "multiTenant.tenants" must be a tenant-to-URI map.');
+    }
+}
+async function loadAmbitenConfig(configPath) {
+    const candidates = configPath
+        ? [path_1.default.resolve(configPath)]
+        : [
+            path_1.default.resolve(process.cwd(), DEFAULT_CONFIG_FILENAME),
+            path_1.default.resolve(process.cwd(), 'config', DEFAULT_CONFIG_FILENAME),
+            path_1.default.resolve(process.cwd(), 'src', 'config', DEFAULT_CONFIG_FILENAME),
+            path_1.default.resolve(__dirname, DEFAULT_CONFIG_FILENAME),
+            path_1.default.resolve(__dirname, '..', DEFAULT_CONFIG_FILENAME),
+        ];
+    let finalPath;
+    for (const candidate of candidates) {
+        if (await fs_extra_1.default.pathExists(candidate)) {
+            finalPath = candidate;
+            break;
+        }
+    }
+    if (!finalPath) {
+        throw new Error(`Config file not found at any of: ${candidates.join(', ')}`);
+    }
+    let parsed;
+    try {
+        const raw = await fs_extra_1.default.readFile(finalPath, 'utf-8');
+        parsed = normalizeAmbitenConfig(JSON.parse(raw));
+    }
+    catch (err) {
+        throw new Error(`[Ambiten] Failed to parse config file: ${err}`);
+    }
+    if (!validate) {
+        validate = ajv.compile(ambiten_config_schema_json_1.default);
+    }
+    const isValid = validate(parsed);
+    if (!isValid) {
+        console.error(JSON.stringify(validate.errors, null, 2));
+        const errors = validate.errors
+            ?.map((e) => {
+            const location = e.instancePath || '(root)';
+            const extra = e.keyword === 'additionalProperties'
+                ? `: ${e.params.additionalProperty}`
+                : '';
+            return `${location} ${e.message}${extra}`;
+        })
+            .join('; ');
+        throw new Error(`[Ambiten] Invalid configuration: ${errors}`);
+    }
+    assertValidAmbitenConfig(parsed);
+    parsed.graphql ??= { enabled: false };
+    parsed.features ??= { useRedisCache: false };
+    parsed.advanced ??= {
+        circuitBreaker: { enabled: false },
+        garbageCollector: { enabled: false },
+    };
+    return parsed;
+}
+;

package/dist/context/ambitenContext.d.ts

@@ -0,0 +1,35 @@
+import type { ClientSession, MongoClient } from 'mongodb';
+import { AmbitenContextState, AmbitenLoggerLike, AmbitenQueryObserver, AmbitenQuotaBudget, AmbitenQuotaBudgetInput } from '../types';
+export interface AmbitenTransactionResolver {
+    resolveClient: (tenantId?: string, dbName?: string) => Promise<MongoClient | undefined> | MongoClient | undefined;
+}
+declare class AmbitenContextManager {
+    private readonly storage;
+    private transactionResolver?;
+    run<T>(context: AmbitenContextState, callback: () => T): T;
+    get(): AmbitenContextState;
+    hasActiveContext(): boolean;
+    set(patch: Partial<AmbitenContextState>): void;
+    clear(): void;
+    configureTransactionResolver(resolver: AmbitenTransactionResolver): void;
+    getTenantId(): string | undefined;
+    getRequestId(): string | undefined;
+    getDbName(): string | undefined;
+    getCollectionName(): string | undefined;
+    getSession(): ClientSession | undefined;
+    getLogger(): AmbitenLoggerLike | undefined;
+    getLoggerMeta(): Record<string, any> | undefined;
+    getObserver(): AmbitenQueryObserver | undefined;
+    normalizeBudget(budget?: AmbitenQuotaBudgetInput): AmbitenQuotaBudget;
+    getBudget(): AmbitenQuotaBudget;
+    setBudget(budget: AmbitenQuotaBudgetInput): void;
+    assertQueryBudget(): void;
+    incrementQueries(): AmbitenQuotaBudget;
+    addQueryTime(durationMs: number): AmbitenQuotaBudget;
+    isDebug(): boolean;
+    withTransaction<T>(callback: (session: ClientSession) => Promise<T>): Promise<T>;
+    hasTransactionResolver(): boolean;
+}
+export declare const AmbitenContext: AmbitenContextManager;
+export {};
+//# sourceMappingURL=ambitenContext.d.ts.map

package/dist/context/ambitenContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ambitenContext.d.ts","sourceRoot":"","sources":["../../src/context/ambitenContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EACN,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,MAAM,UAAU,CAAC;AAGlB,MAAM,WAAW,0BAA0B;IAC1C,aAAa,EAAE,CACd,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,KACX,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,GAAG,WAAW,GAAG,SAAS,CAAC;CAChE;AAQD,cAAM,qBAAqB;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgD;IACxE,OAAO,CAAC,mBAAmB,CAAC,CAA6B;IAEzD,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC;IAe1D,GAAG,IAAI,mBAAmB;IAI1B,gBAAgB,IAAI,OAAO;IAI3B,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI;IAM9C,KAAK,IAAI,IAAI;IASb,4BAA4B,CAAC,QAAQ,EAAE,0BAA0B,GAAG,IAAI;IAIxE,WAAW,IAAI,MAAM,GAAG,SAAS;IAIjC,YAAY,IAAI,MAAM,GAAG,SAAS;IAIlC,SAAS,IAAI,MAAM,GAAG,SAAS;IAI/B,iBAAiB,IAAI,MAAM,GAAG,SAAS;IAIvC,UAAU,IAAI,aAAa,GAAG,SAAS;IAIvC,SAAS,IAAI,iBAAiB,GAAG,SAAS;IAI1C,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAIhD,WAAW,IAAI,oBAAoB,GAAG,SAAS;IAI/C,eAAe,CAAC,MAAM,CAAC,EAAE,uBAAuB,GAAG,kBAAkB;IASrE,SAAS,IAAI,kBAAkB;IAO/B,SAAS,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI;IAKhD,iBAAiB,IAAI,IAAI;IAWzB,gBAAgB,IAAI,kBAAkB;IAOtC,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB;IAMpD,OAAO,IAAI,OAAO;IASZ,eAAe,CAAC,CAAC,EACtB,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC;IA6Cb,sBAAsB,IAAI,OAAO;CAGjC;AAED,eAAO,MAAM,cAAc,uBAA8B,CAAC"}

package/dist/context/ambitenContext.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AmbitenContext = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+const runManualTransaction_1 = require("./helpers/runManualTransaction");
+const DEFAULT_AMBITEN_BUDGET = {
+    maxQueries: Infinity,
+    queriesExecuted: 0,
+    totalTimeMs: 0
+};
+class AmbitenContextManager {
+    storage = new node_async_hooks_1.AsyncLocalStorage();
+    transactionResolver;
+    run(context, callback) {
+        const parent = this.storage.getStore() ?? {};
+        const merged = {
+            ...parent,
+            ...context,
+            budget: context.budget
+                ? this.normalizeBudget(context.budget)
+                : parent.budget
+                    ? this.normalizeBudget(parent.budget)
+                    : undefined
+        };
+        return this.storage.run(merged, callback);
+    }
+    get() {
+        return this.storage.getStore() ?? {};
+    }
+    hasActiveContext() {
+        return this.storage.getStore() !== undefined;
+    }
+    set(patch) {
+        const current = this.storage.getStore();
+        if (!current)
+            return;
+        Object.assign(current, patch);
+    }
+    clear() {
+        const current = this.storage.getStore();
+        if (!current)
+            return;
+        for (const key of Object.keys(current)) {
+            delete current[key];
+        }
+    }
+    configureTransactionResolver(resolver) {
+        this.transactionResolver = resolver;
+    }
+    getTenantId() {
+        return this.get().tenantId;
+    }
+    getRequestId() {
+        return this.get().requestId;
+    }
+    getDbName() {
+        return this.get().dbName;
+    }
+    getCollectionName() {
+        return this.get().collectionName;
+    }
+    getSession() {
+        return this.get().session;
+    }
+    getLogger() {
+        return this.get().logger;
+    }
+    getLoggerMeta() {
+        return this.get().loggerMeta;
+    }
+    getObserver() {
+        return this.get().observer;
+    }
+    normalizeBudget(budget) {
+        return {
+            maxQueries: budget?.maxQueries ?? DEFAULT_AMBITEN_BUDGET.maxQueries,
+            queriesExecuted: budget?.queriesExecuted ?? DEFAULT_AMBITEN_BUDGET.queriesExecuted,
+            totalTimeMs: budget?.totalTimeMs ?? DEFAULT_AMBITEN_BUDGET.totalTimeMs
+        };
+    }
+    getBudget() {
+        const state = this.get();
+        const normalized = this.normalizeBudget(state.budget);
+        state.budget = normalized;
+        return normalized;
+    }
+    setBudget(budget) {
+        const state = this.get();
+        state.budget = this.normalizeBudget(budget);
+    }
+    assertQueryBudget() {
+        const state = this.get();
+        const budget = this.getBudget();
+        if (budget.queriesExecuted >= budget.maxQueries) {
+            throw new Error(`[Ambiten] Tenant ${state.tenantId ?? 'unknown'} exceeded query budget for this request.`);
+        }
+    }
+    incrementQueries() {
+        this.assertQueryBudget();
+        const budget = this.getBudget();
+        budget.queriesExecuted += 1;
+        return budget;
+    }
+    addQueryTime(durationMs) {
+        const budget = this.getBudget();
+        budget.totalTimeMs += durationMs;
+        return budget;
+    }
+    isDebug() {
+        const ctx = this.get();
+        return Boolean(ctx.debug ||
+            process.env.AMBITEN_DEBUG === 'true' ||
+            process.env.AMBITEN_DEBUG === '1');
+    }
+    async withTransaction(callback) {
+        const current = this.get();
+        if (current.session) {
+            return callback(current.session);
+        }
+        if (!this.transactionResolver) {
+            throw new Error('AmbitenContext transaction resolver is not configured.');
+        }
+        const client = await this.transactionResolver.resolveClient(current.tenantId, current.dbName);
+        if (!client) {
+            throw new Error(`No MongoClient available for${current.tenantId ? ` tenant "${current.tenantId}"` : ' current context'}.`);
+        }
+        const session = client.startSession();
+        if (typeof session.withTransaction === 'function') {
+            try {
+                let result;
+                await session.withTransaction(async () => {
+                    result = await this.run({ session }, () => callback(session));
+                    return result;
+                });
+                return result;
+            }
+            finally {
+                await session.endSession();
+            }
+        }
+        return this.run({ session }, () => (0, runManualTransaction_1.runManualTransaction)(session, callback));
+    }
+    hasTransactionResolver() {
+        return Boolean(this.transactionResolver);
+    }
+}
+exports.AmbitenContext = new AmbitenContextManager();

package/dist/context/helpers/runManualTransaction.d.ts

@@ -0,0 +1,3 @@
+import type { ClientSession } from 'mongodb';
+export declare function runManualTransaction<T>(session: ClientSession, operation: (session: ClientSession) => Promise<T>): Promise<T>;
+//# sourceMappingURL=runManualTransaction.d.ts.map

package/dist/context/helpers/runManualTransaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runManualTransaction.d.ts","sourceRoot":"","sources":["../../../src/context/helpers/runManualTransaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7C,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAChD,OAAO,CAAC,CAAC,CAAC,CAmBZ"}

package/dist/context/helpers/runManualTransaction.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runManualTransaction = runManualTransaction;
+const transactionSession_1 = require("./transactionSession");
+async function runManualTransaction(session, operation) {
+    if (!(0, transactionSession_1.hasManualTransactionMethods)(session)) {
+        throw new Error('Session does not implement manual transaction methods.');
+    }
+    session.startTransaction();
+    try {
+        const result = await operation(session);
+        await session.commitTransaction();
+        return result;
+    }
+    catch (error) {
+        await session.abortTransaction();
+        throw error;
+    }
+    finally {
+        await session.endSession();
+    }
+}

package/dist/context/helpers/transactionSession.d.ts

@@ -0,0 +1,9 @@
+import type { ClientSession } from 'mongodb';
+export interface ManualTransactionSession extends ClientSession {
+    startTransaction(): void;
+    commitTransaction(): Promise<void>;
+    abortTransaction(): Promise<void>;
+    endSession(): Promise<void>;
+}
+export declare function hasManualTransactionMethods(session: ClientSession): session is ManualTransactionSession;
+//# sourceMappingURL=transactionSession.d.ts.map

package/dist/context/helpers/transactionSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactionSession.d.ts","sourceRoot":"","sources":["../../../src/context/helpers/transactionSession.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,wBAAyB,SAAQ,aAAa;IAC7D,gBAAgB,IAAI,IAAI,CAAC;IACzB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,aAAa,GACrB,OAAO,IAAI,wBAAwB,CAMrC"}

package/dist/context/helpers/transactionSession.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasManualTransactionMethods = hasManualTransactionMethods;
+function hasManualTransactionMethods(session) {
+    return (typeof session.startTransaction === 'function' &&
+        typeof session.commitTransaction === 'function' &&
+        typeof session.abortTransaction === 'function');
+}

package/dist/context/index.d.ts

@@ -0,0 +1,4 @@
+export * from './ambitenContext';
+export * from './helpers/transactionSession';
+export * from './helpers/runManualTransaction';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC"}

package/dist/context/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./ambitenContext"), exports);
+tslib_1.__exportStar(require("./helpers/transactionSession"), exports);
+tslib_1.__exportStar(require("./helpers/runManualTransaction"), exports);

package/dist/debug/debugLog.d.ts

@@ -0,0 +1,2 @@
+export declare function debugLog(message: string, meta?: Record<string, any>): void;
+//# sourceMappingURL=debugLog.d.ts.map

package/dist/debug/debugLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugLog.d.ts","sourceRoot":"","sources":["../../src/debug/debugLog.ts"],"names":[],"mappings":"AAEA,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAC7B,IAAI,CAqBN"}

package/dist/debug/debugLog.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.debugLog = debugLog;
+const context_1 = require("../context");
+function debugLog(message, meta = {}) {
+    if (!context_1.AmbitenContext.isDebug())
+        return;
+    const logger = context_1.AmbitenContext.getLogger();
+    const loggerMeta = context_1.AmbitenContext.getLoggerMeta() ?? {};
+    const payload = {
+        tenantId: context_1.AmbitenContext.getTenantId(),
+        requestId: context_1.AmbitenContext.getRequestId(),
+        dbName: context_1.AmbitenContext.getDbName(),
+        collectionName: context_1.AmbitenContext.getCollectionName(),
+        ...loggerMeta,
+        ...meta
+    };
+    if (logger?.debug) {
+        logger.debug(message, payload);
+        return;
+    }
+    console.debug(`[AMBITEN_DEBUG] ${message}`, payload);
+}

package/dist/debug/index.d.ts

@@ -0,0 +1,2 @@
+export * from './debugLog';
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/debug/index.js

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

package/dist/gc/ambitenGC.d.ts

@@ -0,0 +1,49 @@
+import type { ModelContext } from '../types';
+import { type GarbageCollectorRunResult } from './gcManager';
+export interface GCOptions {
+    enabled?: boolean;
+    interval?: string;
+    retentionPeriod?: number;
+    logResults?: boolean;
+    cron?: string;
+    ctx?: ModelContext;
+    continueOnError?: boolean;
+    logger?: {
+        info?: (message: string, meta?: Record<string, unknown>) => void;
+        warn?: (message: string, meta?: Record<string, unknown>) => void;
+        error?: (message: string, meta?: Record<string, unknown>) => void;
+    };
+}
+export declare class AmbitenGC {
+    private readonly options;
+    private readonly enabled;
+    private intervalMs;
+    private intervalRef;
+    private cronTask;
+    constructor(options?: GCOptions);
+    /**
+     * Starts interval-based garbage collection.
+     */
+    start(): void;
+    /**
+     * Stops interval or cron-based garbage collection.
+     */
+    stop(): void;
+    /**
+     * Runs garbage collection once across registered models.
+     *
+     * @param ctx - Optional model execution context override.
+     * @returns Summary of the GC run.
+     */
+    runOnce(ctx?: ModelContext): Promise<GarbageCollectorRunResult>;
+    /**
+     * Parses interval strings such as "30s", "5m", "1h", or "1d".
+     *
+     * @param duration - Interval duration.
+     * @returns Duration in milliseconds.
+     * @throws {Error} When the interval format is invalid.
+     */
+    private parseInterval;
+    private log;
+}
+//# sourceMappingURL=ambitenGC.d.ts.map

package/dist/gc/ambitenGC.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ambitenGC.d.ts","sourceRoot":"","sources":["../../src/gc/ambitenGC.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,YAAY,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;QACjE,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;QACjE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;KACnE,CAAC;CACH;AAED,qBAAa,SAAS;IAMR,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,QAAQ,CAAmC;gBAEtB,OAAO,GAAE,SAAc;IAiCpD;;OAEG;IACH,KAAK,IAAI,IAAI;IAmBb;;OAEG;IACH,IAAI,IAAI,IAAI;IAcZ;;;;;OAKG;IACG,OAAO,CAAC,GAAG,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAyBrE;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAwBrB,OAAO,CAAC,GAAG;CAwBZ"}

package/dist/gc/ambitenGC.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AmbitenGC = void 0;
+const tslib_1 = require("tslib");
+const cron = tslib_1.__importStar(require("node-cron"));
+const utils_1 = require("../utils");
+const gcManager_1 = require("./gcManager");
+class AmbitenGC {
+    options;
+    enabled;
+    intervalMs;
+    intervalRef = null;
+    cronTask = null;
+    constructor(options = {}) {
+        this.options = options;
+        this.enabled = options.enabled !== false;
+        this.intervalMs = options.interval
+            ? this.parseInterval(options.interval)
+            : 60_000;
+        if (options.retentionPeriod) {
+            this.intervalMs = options.retentionPeriod * 24 * 60 * 60 * 1000;
+        }
+        if (!this.enabled) {
+            this.log('info', '[AmbitenGC] Garbage Collector is disabled.');
+            return;
+        }
+        if (options.cron) {
+            this.cronTask = cron.schedule(options.cron, () => {
+                void this.runOnce();
+            });
+            this.log('info', `[AmbitenGC] Cron schedule set to: ${options.cron}`);
+            return;
+        }
+        if (options.interval) {
+            this.start();
+            this.log('info', `[AmbitenGC] Interval set to: ${options.interval}`);
+            return;
+        }
+        this.log('info', '[AmbitenGC] Initialized. Manual run mode enabled.');
+    }
+    /**
+     * Starts interval-based garbage collection.
+     */
+    start() {
+        if (!this.enabled) {
+            return;
+        }
+        if (this.intervalRef) {
+            return;
+        }
+        this.intervalRef = setInterval(() => {
+            void this.runOnce();
+        }, this.intervalMs);
+        this.log('info', `[AmbitenGC] Started GC loop every ${this.intervalMs} ms`);
+    }
+    /**
+     * Stops interval or cron-based garbage collection.
+     */
+    stop() {
+        if (this.intervalRef) {
+            clearInterval(this.intervalRef);
+            this.intervalRef = null;
+        }
+        if (this.cronTask) {
+            this.cronTask.stop();
+            this.cronTask = null;
+        }
+        this.log('info', '[AmbitenGC] Stopped.');
+    }
+    /**
+     * Runs garbage collection once across registered models.
+     *
+     * @param ctx - Optional model execution context override.
+     * @returns Summary of the GC run.
+     */
+    async runOnce(ctx) {
+        if (!this.enabled) {
+            return {
+                scanned: 0,
+                succeeded: 0,
+                failed: 0,
+                models: []
+            };
+        }
+        const result = await (0, gcManager_1.runGarbageCollectorOnAllModels)({
+            ctx: ctx ?? this.options.ctx,
+            continueOnError: this.options.continueOnError ?? true
+        });
+        if (this.options.logResults) {
+            this.log(result.failed > 0 ? 'warn' : 'info', `[AmbitenGC] Completed. scanned=${result.scanned}, succeeded=${result.succeeded}, failed=${result.failed}`);
+        }
+        return result;
+    }
+    /**
+     * Parses interval strings such as "30s", "5m", "1h", or "1d".
+     *
+     * @param duration - Interval duration.
+     * @returns Duration in milliseconds.
+     * @throws {Error} When the interval format is invalid.
+     */
+    parseInterval(duration) {
+        const match = duration.match(/^(\d+)([smhd])$/);
+        if (!match) {
+            throw new Error(`Invalid interval format: ${duration}`);
+        }
+        const [, num, unit] = match;
+        const value = Number.parseInt(num, 10);
+        switch (unit) {
+            case 's':
+                return value * 1000;
+            case 'm':
+                return value * 60 * 1000;
+            case 'h':
+                return value * 60 * 60 * 1000;
+            case 'd':
+                return value * 24 * 60 * 60 * 1000;
+            default:
+                throw new Error(`Unknown time unit: ${unit}`);
+        }
+    }
+    log(level, message, meta) {
+        const logger = this.options.logger;
+        if (logger?.[level]) {
+            logger[level]?.(message, meta);
+            return;
+        }
+        if (level === 'error') {
+            console.error((0, utils_1.colorize)(message, 'red'), meta ?? '');
+            return;
+        }
+        if (level === 'warn') {
+            console.warn((0, utils_1.colorize)(message, 'yellow'), meta ?? '');
+            return;
+        }
+        console.log((0, utils_1.colorize)(message, 'blue'), meta ?? '');
+    }
+}
+exports.AmbitenGC = AmbitenGC;

package/dist/gc/gcCron.browser.d.ts

@@ -0,0 +1,2 @@
+export declare const startGarbageCollector: () => void;
+//# sourceMappingURL=gcCron.browser.d.ts.map

package/dist/gc/gcCron.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcCron.browser.d.ts","sourceRoot":"","sources":["../../src/gc/gcCron.browser.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,qBAAqB,YAGjC,CAAC"}

package/dist/gc/gcCron.browser.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startGarbageCollector = void 0;
+const utils_1 = require("../utils");
+const startGarbageCollector = () => {
+    // No-op for browsers
+    console.warn((0, utils_1.colorize)('[GC] Garbage collector is disabled in the browser.', 'red'));
+};
+exports.startGarbageCollector = startGarbageCollector;

package/dist/gc/gcCron.node.d.ts

@@ -0,0 +1,19 @@
+import * as cron from 'node-cron';
+import type { ModelContext } from '../types';
+export interface GarbageCollectorScheduleOptions {
+    cronExpr?: string;
+    ctx?: ModelContext;
+    continueOnError?: boolean;
+}
+/**
+ * Schedules registry-driven garbage collection.
+ *
+ * The cron task uses registered model instances and delegates cleanup to
+ * `model.runGC()` so Ambiten's runtime context, middleware, schema hooks,
+ * instrumentation, cache invalidation, and events remain centralized.
+ *
+ * @param options - Cron expression or scheduler options.
+ * @returns The scheduled cron task.
+ */
+export declare function scheduleGarbageCollector(options?: string | GarbageCollectorScheduleOptions): cron.ScheduledTask;
+//# sourceMappingURL=gcCron.node.d.ts.map