@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/esm/provider/db-in-memory/base-repo.repository.js

@@ -0,0 +1,54 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable, unmanaged } from "../../di/inversify.js";
+/**
+ * Base repository class using the repository pattern.
+ * @template T - The type of entity to be stored in the repository.
+ * @public API
+ */
+let BaseRepository = class BaseRepository {
+    dataTable;
+    entityName;
+    constructor(dataProvider, tableName) {
+        this.dataTable = dataProvider.getTable(tableName);
+        this.entityName = tableName;
+    }
+    async create(item) {
+        return this.dataTable.insert(item);
+    }
+    async update(item) {
+        return this.dataTable.update(item);
+    }
+    async delete(id) {
+        return this.dataTable.delete(id);
+    }
+    async find(id) {
+        return this.dataTable.find(id);
+    }
+    async findAll() {
+        return this.dataTable.findAll();
+    }
+    async query(predicate) {
+        return this.dataTable.query(predicate);
+    }
+    async transaction(actions) {
+        await this.dataTable.transaction(actions);
+    }
+};
+BaseRepository = __decorate([
+    injectable(),
+    __param(0, inject("IDataProvider")),
+    __param(1, unmanaged()),
+    __metadata("design:paramtypes", [Object, String])
+], BaseRepository);
+export { BaseRepository };

package/lib/esm/provider/db-in-memory/db-in-memory.interface.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/provider/db-in-memory/db-in-memory.provider.js

@@ -0,0 +1,104 @@
+import { EntityAlreadyExistsError, EntityNotFoundError, } from "./db-in-memory.types.js";
+/**
+ * @deprecated Use {@link InMemoryDBProvider} (v4) instead.
+ *
+ * Kept for backward compatibility but no longer auto-registered via DI.
+ * Users who depend on the v3 API should bind it manually:
+ * ```ts
+ * container.bind(InMemoryDataProvider).toSelf().inSingletonScope();
+ * ```
+ * @public API
+ */
+export class InMemoryDataProvider {
+    name = "In Memory DB Provider";
+    version = "3.0.0";
+    author = "Richard Zampieri";
+    repo = "https://github.com/expressots/expressots";
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    tables = new Map();
+    getTable(tableName) {
+        if (!this.tables.has(tableName)) {
+            this.tables.set(tableName, new InMemoryDataTable(tableName));
+        }
+        return this.tables.get(tableName);
+    }
+}
+/**
+ * In-memory data table implementation.
+ */
+export class InMemoryDataTable {
+    items = new Map();
+    tableName;
+    transactionStack = [];
+    constructor(tableName) {
+        this.tableName = tableName;
+    }
+    async insert(item) {
+        if (this.items.has(item.id)) {
+            throw new EntityAlreadyExistsError(this.tableName, item.id);
+        }
+        this.items.set(item.id, item);
+        return item;
+    }
+    async insertMany(items) {
+        const insertedItems = [];
+        for (const item of items) {
+            const insertedItem = await this.insert(item);
+            insertedItems.push(insertedItem);
+        }
+        return insertedItems;
+    }
+    async update(item) {
+        if (!this.items.has(item.id)) {
+            throw new EntityNotFoundError(this.tableName, item.id);
+        }
+        this.items.set(item.id, item);
+        return item;
+    }
+    async delete(id) {
+        if (!this.items.has(id)) {
+            throw new EntityNotFoundError(this.tableName, id);
+        }
+        return this.items.delete(id);
+    }
+    async find(id) {
+        const item = this.items.get(id);
+        if (!item) {
+            throw new EntityNotFoundError(this.tableName, id);
+        }
+        return item;
+    }
+    async findAll() {
+        return Array.from(this.items.values());
+    }
+    async query(predicate) {
+        return Array.from(this.items.values()).filter(predicate);
+    }
+    async transaction(actions) {
+        this.beginTransaction();
+        try {
+            await actions();
+            this.commitTransaction();
+        }
+        catch (error) {
+            this.rollbackTransaction();
+            throw error;
+        }
+    }
+    beginTransaction() {
+        const snapshot = new Map(this.items);
+        this.transactionStack.push(snapshot);
+    }
+    commitTransaction() {
+        this.transactionStack.pop();
+    }
+    rollbackTransaction() {
+        const snapshot = this.transactionStack.pop();
+        if (snapshot) {
+            this.items = snapshot;
+        }
+        else {
+            throw new Error("No transaction to rollback.");
+        }
+    }
+}

package/lib/esm/provider/db-in-memory/db-in-memory.types.js

@@ -0,0 +1,20 @@
+/**
+ * Error thrown when an entity is not found.
+ * @public API
+ */
+export class EntityNotFoundError extends Error {
+    constructor(entityName, id) {
+        super(`${entityName} with ID ${id} not found.`);
+        this.name = "EntityNotFoundError";
+    }
+}
+/**
+ * Error thrown when an entity already exists.
+ * @public API
+ */
+export class EntityAlreadyExistsError extends Error {
+    constructor(entityName, id) {
+        super(`${entityName} with ID ${id} already exists.`);
+        this.name = "EntityAlreadyExistsError";
+    }
+}

package/lib/esm/provider/db-in-memory/db.provider.js

@@ -0,0 +1,405 @@
+/**
+ * In-Memory Database Provider for ExpressoTS
+ *
+ * The main provider that integrates the in-memory database
+ * with the ExpressoTS framework, including health checks,
+ * metrics, and lifecycle management.
+ *
+ * @module db-in-memory
+ */
+import { InMemoryDatabase, } from "./adapter/index.js";
+/**
+ * In-Memory Database Provider for ExpressoTS.
+ *
+ * A high-performance, Prisma-compatible in-memory database
+ * that integrates seamlessly with the ExpressoTS framework.
+ *
+ * Features:
+ * - Prisma-like query API
+ * - Secondary indexes for O(1) lookups
+ * - Automatic ID generation
+ * - Timestamps (createdAt, updatedAt)
+ * - Soft deletes
+ * - Transactions with rollback
+ * - Relation support (HasMany, HasOne, BelongsTo)
+ * - Reactive subscriptions
+ * - Persistence (file-based)
+ * - Health checks
+ * - Metrics collection
+ *
+ * @example
+ * ```typescript
+ * // Inject the provider
+ * constructor(@inject(InMemoryDBProvider) private db: InMemoryDBProvider) {}
+ *
+ * // Access tables
+ * const users = this.db.table<User>("users");
+ *
+ * // Prisma-like queries
+ * const user = await users.create({
+ *   data: { name: "John", email: "john@example.com" }
+ * });
+ *
+ * const adults = await users.findMany({
+ *   where: { age: { gte: 18 } },
+ *   orderBy: { name: "asc" },
+ *   take: 10
+ * });
+ * ```
+ *
+ * @public API
+ */
+/**
+ * Not auto-registered. Bind explicitly when you need an in-memory store:
+ * ```ts
+ * import { InMemoryDBProvider } from "@expressots/core";
+ * container.bind(InMemoryDBProvider).toSelf().inSingletonScope();
+ * ```
+ */
+export class InMemoryDBProvider {
+    // ═══════════════════════════════════════════════════════════════════════════
+    // PROVIDER METADATA
+    // ═══════════════════════════════════════════════════════════════════════════
+    name = "In-Memory Database Provider";
+    version = "4.0.0";
+    description = "High-performance, Prisma-compatible in-memory database for ExpressoTS";
+    author = "ExpressoTS Team";
+    repo = "https://github.com/expressots/expressots";
+    // ═══════════════════════════════════════════════════════════════════════════
+    // INTERNALS
+    // ═══════════════════════════════════════════════════════════════════════════
+    database;
+    config;
+    queryCount = 0;
+    totalQueryTime = 0;
+    startTime;
+    constructor(config = {}) {
+        this.config = {
+            timestamps: true,
+            softDelete: false,
+            logging: false,
+            maxRecordsPerTable: 0,
+            ...config,
+        };
+        this.database = new InMemoryDatabase(this.config);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CONFIGURATION
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Configure the in-memory database provider.
+     *
+     * Call this method in `configureServices()` to globally configure the database
+     * before the application starts. Configuration changes that affect the database
+     * structure (timestamps, softDelete, persist) will reinitialize the database.
+     *
+     * @param config - Partial configuration to merge with defaults
+     *
+     * @example
+     * ```typescript
+     * // In app.ts configureServices()
+     * async configureServices(): Promise<void> {
+     *   const db = this.Provider.get(InMemoryDBProvider);
+     *   db.configure({
+     *     timestamps: true,
+     *     softDelete: true,
+     *     logging: true,
+     *     persist: {
+     *       storage: "file",
+     *       path: "./data/db.json",
+     *       interval: 30000, // auto-save every 30 seconds
+     *     },
+     *   });
+     * }
+     * ```
+     * @public API
+     */
+    configure(config) {
+        const previousConfig = { ...this.config };
+        // Merge new config with existing
+        this.config = {
+            ...this.config,
+            ...config,
+        };
+        // Check if we need to reinitialize the database
+        // (structural changes require a new database instance)
+        const structuralChange = (config.timestamps !== undefined &&
+            config.timestamps !== previousConfig.timestamps) ||
+            (config.softDelete !== undefined &&
+                config.softDelete !== previousConfig.softDelete) ||
+            config.persist !== undefined;
+        if (structuralChange) {
+            // Preserve existing data if possible
+            const snapshot = this.database.snapshot();
+            // Create new database with updated config
+            this.database = new InMemoryDatabase(this.config);
+            // Restore data if there was any
+            if (snapshot && snapshot !== "{}") {
+                try {
+                    this.database.restore(snapshot);
+                }
+                catch {
+                    // If restore fails, start fresh (schema might have changed)
+                    if (this.config.logging) {
+                        console.log("[InMemoryDB] Could not restore data after config change, starting fresh");
+                    }
+                }
+            }
+            if (this.config.logging) {
+                console.log("[InMemoryDB] Database reinitialized with new configuration");
+            }
+        }
+        if (this.config.logging) {
+            console.log("[InMemoryDB] Configuration updated:", this.config);
+        }
+    }
+    /**
+     * Get the current configuration.
+     * @returns Current database configuration
+     * @public API
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // LIFECYCLE
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Bootstrap the database provider.
+     * Called after the application is fully ready.
+     */
+    async bootstrap() {
+        this.startTime = new Date();
+        // Load persisted data if configured
+        if (this.config.persist) {
+            await this.database.load();
+        }
+        if (this.config.logging) {
+            console.log(`[InMemoryDB] Provider initialized at ${this.startTime.toISOString()}`);
+        }
+    }
+    /**
+     * Shutdown the database provider.
+     * Called when the application shuts down.
+     */
+    async shutdown(signal) {
+        if (this.config.logging) {
+            console.log(`[InMemoryDB] Shutting down (signal: ${signal})`);
+        }
+        this.database.shutdown();
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // HEALTH CHECK
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Perform a health check on the database.
+     * @returns Health check result
+     */
+    healthCheck() {
+        const stats = this.database.getStats();
+        return {
+            status: "healthy",
+            message: `${stats.tableCount} tables, ${stats.totalRecords} total records`,
+            details: {
+                tables: stats.tableCount,
+                records: stats.totalRecords,
+                uptime: this.startTime ? Date.now() - this.startTime.getTime() : 0,
+            },
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // METRICS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Get database metrics.
+     * @returns Metrics object
+     */
+    getMetrics() {
+        const stats = this.database.getStats();
+        const metrics = {
+            "db.tables": stats.tableCount,
+            "db.records.total": stats.totalRecords,
+            "db.queries.total": this.queryCount,
+            "db.queries.avgMs": this.queryCount > 0 ? this.totalQueryTime / this.queryCount : 0,
+        };
+        // Add per-table metrics
+        for (const table of stats.tables) {
+            metrics[`db.table.${table.tableName}.records`] = table.recordCount;
+            metrics[`db.table.${table.tableName}.memory`] = table.memoryEstimate;
+        }
+        return metrics;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // DATABASE API
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Get or create a table adapter.
+     *
+     * @param tableName - Name of the table
+     * @param entityClass - Optional entity class for schema metadata
+     * @returns Table adapter with Prisma-like API
+     *
+     * @example
+     * ```typescript
+     * interface User extends IEntity {
+     *   name: string;
+     *   email: string;
+     *   age: number;
+     * }
+     *
+     * const users = db.table<User>("users");
+     *
+     * // Create
+     * const user = await users.create({
+     *   data: { name: "John", email: "john@example.com", age: 30 }
+     * });
+     *
+     * // Find with complex filters
+     * const results = await users.findMany({
+     *   where: {
+     *     OR: [
+     *       { name: { contains: "John" } },
+     *       { age: { gte: 25 } }
+     *     ]
+     *   },
+     *   orderBy: { createdAt: "desc" },
+     *   take: 10
+     * });
+     * ```
+     */
+    table(tableName, entityClass) {
+        return this.database.table(tableName, entityClass);
+    }
+    /**
+     * Execute operations in a transaction.
+     *
+     * @param fn - Transaction function
+     * @returns Result of the transaction function
+     *
+     * @example
+     * ```typescript
+     * await db.transaction(async (tx) => {
+     *   const user = await tx.table<User>("users").create({
+     *     data: { name: "John", email: "john@example.com" }
+     *   });
+     *
+     *   await tx.table<Post>("posts").create({
+     *     data: { title: "Hello", authorId: user.id }
+     *   });
+     * });
+     * ```
+     */
+    async transaction(fn) {
+        return this.database.transaction(fn);
+    }
+    /**
+     * Create a snapshot of all data.
+     * @returns JSON string of all data
+     */
+    snapshot() {
+        return this.database.snapshot();
+    }
+    /**
+     * Restore data from a snapshot.
+     * @param json - JSON string of snapshot data
+     */
+    restore(json) {
+        this.database.restore(json);
+    }
+    /**
+     * Clear all tables.
+     */
+    clear() {
+        this.database.clear();
+    }
+    /**
+     * Get database statistics.
+     * @returns Statistics for all tables
+     */
+    getStats() {
+        return this.database.getStats();
+    }
+    /**
+     * Get the underlying database instance.
+     * @returns InMemoryDatabase instance
+     */
+    getDatabase() {
+        return this.database;
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// REPOSITORY BASE CLASS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Base Repository class for the new adapter pattern.
+ *
+ * Provides a convenient base class for creating repositories
+ * that work with the in-memory database.
+ *
+ * @example
+ * ```typescript
+ * @provide(UserRepository)
+ * export class UserRepository extends BaseRepository<User> {
+ *   constructor(@inject(InMemoryDBProvider) db: InMemoryDBProvider) {
+ *     super(db, "users");
+ *   }
+ *
+ *   // Add custom methods
+ *   async findByEmail(email: string): Promise<User | null> {
+ *     return this.adapter.findFirst({
+ *       where: { email }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @public API
+ */
+export class BaseRepository {
+    adapter;
+    tableName;
+    constructor(db, tableName, entityClass) {
+        this.tableName = tableName;
+        this.adapter = db.table(tableName, entityClass);
+    }
+    // Delegate all methods to the adapter
+    async findUnique(args) {
+        return this.adapter.findUnique(args);
+    }
+    async findFirst(args) {
+        return this.adapter.findFirst(args);
+    }
+    async findMany(args) {
+        return this.adapter.findMany(args);
+    }
+    async create(args) {
+        return this.adapter.create(args);
+    }
+    async createMany(args) {
+        return this.adapter.createMany(args);
+    }
+    async update(args) {
+        return this.adapter.update(args);
+    }
+    async updateMany(args) {
+        return this.adapter.updateMany(args);
+    }
+    async upsert(args) {
+        return this.adapter.upsert(args);
+    }
+    async delete(args) {
+        return this.adapter.delete(args);
+    }
+    async deleteMany(args) {
+        return this.adapter.deleteMany(args);
+    }
+    async count(args) {
+        return this.adapter.count(args);
+    }
+    async aggregate(args) {
+        return this.adapter.aggregate(args);
+    }
+    async transaction(fn) {
+        return this.adapter.transaction(fn);
+    }
+}

package/lib/esm/provider/db-in-memory/index.js

@@ -0,0 +1,90 @@
+/**
+ * ExpressoTS In-Memory Database
+ *
+ * A high-performance, Prisma-compatible in-memory database
+ * for ExpressoTS applications.
+ *
+ * Features:
+ * - Prisma-like query API
+ * - Type-safe queries with TypeScript
+ * - Secondary indexes for O(1) lookups
+ * - Automatic ID generation
+ * - Timestamps (createdAt, updatedAt)
+ * - Soft deletes
+ * - Transactions with rollback
+ * - Relation support (HasMany, HasOne, BelongsTo)
+ * - Reactive subscriptions
+ * - Persistence (file-based snapshots)
+ * - Health checks and metrics
+ * - Easy migration to real databases
+ *
+ * @example
+ * ```typescript
+ * // Define entities
+ * interface User extends IEntity {
+ *   name: string;
+ *   email: string;
+ *   age: number;
+ * }
+ *
+ * // Inject the provider
+ * constructor(@inject(InMemoryDBProvider) private db: InMemoryDBProvider) {}
+ *
+ * // Access tables
+ * const users = this.db.table<User>("users");
+ *
+ * // Prisma-like queries
+ * const user = await users.create({
+ *   data: { name: "John", email: "john@example.com", age: 30 }
+ * });
+ *
+ * const adults = await users.findMany({
+ *   where: {
+ *     OR: [
+ *       { name: { contains: "John" } },
+ *       { age: { gte: 18 } }
+ *     ]
+ *   },
+ *   orderBy: { createdAt: "desc" },
+ *   take: 10
+ * });
+ * ```
+ *
+ * @module db-in-memory
+ */
+// ═══════════════════════════════════════════════════════════════════════════
+// MAIN PROVIDER
+// ═══════════════════════════════════════════════════════════════════════════
+export { InMemoryDBProvider, BaseRepository, } from "./db.provider.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// ADAPTER
+// ═══════════════════════════════════════════════════════════════════════════
+export { 
+// Implementations
+InMemoryAdapter, InMemoryDatabase, } from "./adapter/index.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// SCHEMA
+// ═══════════════════════════════════════════════════════════════════════════
+export { 
+// Decorators
+Entity, PrimaryKey, AutoGenerate, Index, Unique, Nullable, Default, 
+// Relation decorators
+HasMany, HasOne, BelongsTo, ManyToMany, 
+// Registry
+SchemaRegistry, DB_METADATA_KEYS, } from "./schema/index.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// QUERY
+// ═══════════════════════════════════════════════════════════════════════════
+export { 
+// Engine
+QueryEngine, } from "./query/index.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// STORAGE
+// ═══════════════════════════════════════════════════════════════════════════
+export { MemoryStore, IndexManager, IdGenerator, UniqueConstraintError, EntityNotFoundError, EntityAlreadyExistsError, } from "./storage/index.js";
+// Legacy provider (deprecated, use InMemoryDBProvider)
+export { InMemoryDataProvider, InMemoryDataTable, } from "./db-in-memory.provider.js";
+// Legacy errors (now exported from storage)
+export { EntityNotFoundError as LegacyEntityNotFoundError, EntityAlreadyExistsError as LegacyEntityAlreadyExistsError, } from "./db-in-memory.types.js";
+// Legacy base repository
+export { BaseRepository as LegacyBaseRepository } from "./base-repo.repository.js";

package/lib/esm/provider/db-in-memory/query/index.js

@@ -0,0 +1,6 @@
+/**
+ * Query Module Exports
+ * @module db-in-memory/query
+ */
+export * from "./query.types.js";
+export { QueryEngine } from "./query-engine.js";