@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/esm/types/provider/db-in-memory/adapter/in-memory.adapter.d.ts

@@ -0,0 +1,239 @@
+/**
+ * In-Memory Adapter for ExpressoTS
+ *
+ * High-performance in-memory implementation of IDataAdapter
+ * with Prisma-compatible API.
+ *
+ * @module db-in-memory/adapter
+ */
+import { IEntity } from "../schema/entity.interface.js";
+import { MemoryStoreOptions } from "../storage/memory-store.js";
+import { FindUniqueArgs, FindFirstArgs, FindManyArgs, CreateArgs, CreateManyArgs, UpdateArgs, UpdateManyArgs, UpsertArgs, DeleteArgs, DeleteManyArgs, CountArgs, AggregateArgs, AggregateResult, BatchPayload, GroupByArgs } from "../query/query.types.js";
+import { IDataAdapter, ITableAdapter, IReactiveDataAdapter, ISubscription, ChangeEvent, ChangeType } from "./adapter.interface.js";
+/**
+ * Configuration options for InMemoryAdapter.
+ * @public API
+ */
+export interface InMemoryAdapterOptions extends MemoryStoreOptions {
+    /** Database reference for relation resolution */
+    database?: InMemoryDatabase;
+}
+/**
+ * High-performance in-memory implementation of IDataAdapter.
+ *
+ * Features:
+ * - Prisma-compatible query API
+ * - Secondary indexes for O(1) lookups
+ * - Automatic ID generation
+ * - Timestamps (createdAt, updatedAt)
+ * - Soft deletes
+ * - Transactions with rollback
+ * - Relation support
+ * - Reactive subscriptions
+ *
+ * @example
+ * ```typescript
+ * const userAdapter = new InMemoryAdapter<User>("users");
+ *
+ * // Create
+ * const user = await userAdapter.create({
+ *   data: { name: "John", email: "john@example.com" }
+ * });
+ *
+ * // Find with filters
+ * const adults = await userAdapter.findMany({
+ *   where: { age: { gte: 18 } },
+ *   orderBy: { name: "asc" }
+ * });
+ * ```
+ *
+ * @public API
+ */
+export declare class InMemoryAdapter<T extends IEntity> implements ITableAdapter<T>, IReactiveDataAdapter<T> {
+    readonly tableName: string;
+    private store;
+    private queryEngine;
+    private database?;
+    private entityClass?;
+    private subscribers;
+    private typeSubscribers;
+    constructor(tableName: string, options?: InMemoryAdapterOptions);
+    findUnique(args: FindUniqueArgs<T>): Promise<T | null>;
+    findUniqueOrThrow(args: FindUniqueArgs<T>): Promise<T>;
+    findFirst(args?: FindFirstArgs<T>): Promise<T | null>;
+    findFirstOrThrow(args?: FindFirstArgs<T>): Promise<T>;
+    findMany(args?: FindManyArgs<T>): Promise<Array<T>>;
+    create(args: CreateArgs<T>): Promise<T>;
+    createMany(args: CreateManyArgs<T>): Promise<BatchPayload>;
+    update(args: UpdateArgs<T>): Promise<T>;
+    updateMany(args: UpdateManyArgs<T>): Promise<BatchPayload>;
+    upsert(args: UpsertArgs<T>): Promise<T>;
+    delete(args: DeleteArgs<T>): Promise<T>;
+    deleteMany(args?: DeleteManyArgs<T>): Promise<BatchPayload>;
+    count(args?: CountArgs<T>): Promise<number>;
+    aggregate(args: AggregateArgs<T>): Promise<AggregateResult<T>>;
+    groupBy(args: GroupByArgs<T>): Promise<Array<Partial<T> & AggregateResult<T>>>;
+    transaction<R>(fn: (tx: IDataAdapter<T>) => Promise<R>): Promise<R>;
+    /**
+     * Resolve include clauses for relations.
+     * @private
+     */
+    private resolveIncludes;
+    /**
+     * Resolve a single relation.
+     * @private
+     */
+    private resolveRelation;
+    subscribe(callback: (event: ChangeEvent<T>) => void): ISubscription;
+    on(type: ChangeType, callback: (event: ChangeEvent<T>) => void): ISubscription;
+    private emit;
+    /**
+     * Clear all data in this table.
+     */
+    clear(): void;
+    /**
+     * Export table data as JSON.
+     * @returns JSON string
+     */
+    toJSON(): string;
+    /**
+     * Import table data from JSON.
+     * @param json - JSON string
+     */
+    fromJSON(json: string): void;
+    /**
+     * Get table statistics.
+     * @returns Statistics object
+     */
+    getStats(): {
+        tableName: string;
+        recordCount: number;
+        indexes: Array<{
+            field: string;
+            size: number;
+            unique: boolean;
+        }>;
+        memoryEstimate: number;
+    };
+}
+/**
+ * Configuration options for InMemoryDatabase.
+ * @public API
+ */
+export interface InMemoryDatabaseOptions {
+    /** Enable timestamps by default for all tables */
+    timestamps?: boolean;
+    /** Enable soft deletes by default for all tables */
+    softDelete?: boolean;
+    /** Persistence configuration */
+    persist?: {
+        /** Storage type */
+        storage: "file" | "memory";
+        /** File path (for file storage) */
+        path?: string;
+        /** Auto-save interval in ms (0 to disable) */
+        interval?: number;
+    };
+}
+/**
+ * In-Memory Database with multi-table support.
+ *
+ * The main entry point for the in-memory database system.
+ * Provides a clean API for managing multiple tables with
+ * relation support.
+ *
+ * @example
+ * ```typescript
+ * const db = new InMemoryDatabase();
+ *
+ * // Access tables
+ * const users = db.table<User>("users");
+ * const posts = db.table<Post>("posts");
+ *
+ * // Create with relations
+ * const user = await users.create({
+ *   data: { name: "John", email: "john@example.com" }
+ * });
+ *
+ * const post = await posts.create({
+ *   data: { title: "Hello", authorId: user.id }
+ * });
+ *
+ * // Query with includes
+ * const userWithPosts = await users.findUnique({
+ *   where: { id: user.id },
+ *   include: { posts: true }
+ * });
+ * ```
+ *
+ * @public API
+ */
+export declare class InMemoryDatabase {
+    private tables;
+    private options;
+    private persistInterval?;
+    constructor(options?: InMemoryDatabaseOptions);
+    /**
+     * Get or create a table adapter.
+     * @param tableName - Name of the table
+     * @param entityClass - Optional entity class for schema metadata
+     * @returns Table adapter
+     */
+    table<T extends IEntity>(tableName: string, entityClass?: new (...args: Array<unknown>) => unknown): InMemoryAdapter<T>;
+    /**
+     * Execute operations in a transaction across all tables.
+     * @param fn - Transaction function
+     * @returns Result of the transaction function
+     */
+    transaction<R>(fn: (db: InMemoryDatabase) => Promise<R>): Promise<R>;
+    /**
+     * Create a snapshot of all data.
+     * @returns JSON string of all data
+     */
+    snapshot(): string;
+    /**
+     * Restore data from a snapshot.
+     * @param json - JSON string of snapshot data
+     */
+    restore(json: string): void;
+    /**
+     * Load data from persistence storage.
+     */
+    load(): Promise<void>;
+    /**
+     * Clear all tables.
+     */
+    clear(): void;
+    /**
+     * Get database statistics.
+     * @returns Statistics for all tables
+     */
+    getStats(): {
+        tableCount: number;
+        totalRecords: number;
+        tables: Array<{
+            tableName: string;
+            recordCount: number;
+            indexes: Array<{
+                field: string;
+                size: number;
+                unique: boolean;
+            }>;
+            memoryEstimate: number;
+        }>;
+    };
+    /**
+     * Shutdown the database (cleanup).
+     */
+    shutdown(): void;
+    /**
+     * Write data to file (Node.js only).
+     * @private
+     */
+    private writeToFile;
+    /**
+     * Read data from file (Node.js only).
+     * @private
+     */
+    private readFromFile;
+}

package/lib/esm/types/provider/db-in-memory/adapter/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Adapter Module Exports
+ * @module db-in-memory/adapter
+ */
+export { IDataAdapter, ITableAdapter, IMultiTableAdapter, IReactiveDataAdapter, ISubscription, ChangeEvent, ChangeType, } from "./adapter.interface.js";
+export { InMemoryAdapter, InMemoryAdapterOptions, InMemoryDatabase, InMemoryDatabaseOptions, } from "./in-memory.adapter.js";

package/lib/esm/types/provider/db-in-memory/base-repo.repository.d.ts

@@ -0,0 +1,18 @@
+import { IDataProvider, IDataTable, IEntity, IRepository } from "./db-in-memory.interface.js";
+/**
+ * Base repository class using the repository pattern.
+ * @template T - The type of entity to be stored in the repository.
+ * @public API
+ */
+export declare class BaseRepository<T extends IEntity> implements IRepository<T> {
+    protected dataTable: IDataTable<T>;
+    protected entityName: string;
+    constructor(dataProvider: IDataProvider, tableName: string);
+    create(item: T): Promise<T>;
+    update(item: T): Promise<T>;
+    delete(id: string): Promise<boolean>;
+    find(id: string): Promise<T>;
+    findAll(): Promise<Array<T>>;
+    query(predicate: (item: T) => boolean): Promise<Array<T>>;
+    transaction(actions: () => Promise<void>): Promise<void>;
+}

package/lib/esm/types/provider/db-in-memory/db-in-memory.interface.d.ts

@@ -0,0 +1,43 @@
+import { IProvider } from "../provider-manager.js";
+export interface IEntity {
+    id?: string;
+}
+/**
+ * IRepository Interface
+ * Generic interface that defines the structure of a repository.
+ * @template T - The type of entity to be stored in the repository.
+ * @public API
+ */
+export interface IRepository<T extends IEntity> {
+    create(item: T): Promise<T>;
+    update(item: T): Promise<T>;
+    delete(id: string): Promise<boolean>;
+    find(id: string): Promise<T>;
+    findAll(): Promise<Array<T>>;
+    query(predicate: (item: T) => boolean): Promise<Array<T>>;
+    transaction(actions: () => Promise<void>): Promise<void>;
+}
+/**
+ * IDataTable Interface for CRUD operations
+ * Generic interface that defines the structure of a data table.
+ * @template T - The type of entity to be stored in the data table.
+ * @public API
+ */
+export interface IDataTable<T extends IEntity> {
+    insert(item: T): Promise<T>;
+    insertMany(items: Array<T>): Promise<Array<T>>;
+    update(item: T): Promise<T>;
+    delete(id: string): Promise<boolean>;
+    find(id: string): Promise<T>;
+    findAll(): Promise<Array<T>>;
+    query(predicate: (item: T) => boolean): Promise<Array<T>>;
+    transaction(actions: () => Promise<void>): Promise<void>;
+}
+/**
+ * IDataProvider Interface for obtaining data tables
+ * Generic interface that defines the structure of a data provider.
+ * @public API
+ */
+export interface IDataProvider extends IProvider {
+    getTable<T extends IEntity>(tableName: string): IDataTable<T>;
+}

package/lib/esm/types/provider/db-in-memory/db-in-memory.provider.d.ts

@@ -0,0 +1,39 @@
+import { IDataProvider, IEntity, IDataTable } from "./db-in-memory.interface.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 declare class InMemoryDataProvider implements IDataProvider {
+    name: string;
+    version: string;
+    author: string;
+    repo: string;
+    private tables;
+    getTable<T extends IEntity>(tableName: string): IDataTable<T>;
+}
+/**
+ * In-memory data table implementation.
+ */
+export declare class InMemoryDataTable<T extends IEntity> implements IDataTable<T> {
+    private items;
+    private tableName;
+    private transactionStack;
+    constructor(tableName: string);
+    insert(item: T): Promise<T>;
+    insertMany(items: Array<T>): Promise<Array<T>>;
+    update(item: T): Promise<T>;
+    delete(id: string): Promise<boolean>;
+    find(id: string): Promise<T>;
+    findAll(): Promise<Array<T>>;
+    query(predicate: (item: T) => boolean): Promise<Array<T>>;
+    transaction(actions: () => Promise<void>): Promise<void>;
+    private beginTransaction;
+    private commitTransaction;
+    private rollbackTransaction;
+}

package/lib/esm/types/provider/db-in-memory/db-in-memory.types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Error thrown when an entity is not found.
+ * @public API
+ */
+export declare class EntityNotFoundError extends Error {
+    constructor(entityName: string, id: string);
+}
+/**
+ * Error thrown when an entity already exists.
+ * @public API
+ */
+export declare class EntityAlreadyExistsError extends Error {
+    constructor(entityName: string, id: string);
+}

package/lib/esm/types/provider/db-in-memory/db.provider.d.ts

@@ -0,0 +1,281 @@
+/**
+ * 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 { IProvider, IHealthCheck, IMetrics, HealthCheckResult, ProviderMetrics } from "../provider.interface.js";
+import { IBootstrap, IShutdown } from "../../lifecycle/lifecycle.interface.js";
+import { IEntity } from "./schema/entity.interface.js";
+import { InMemoryDatabase, InMemoryDatabaseOptions, InMemoryAdapter } from "./adapter/index.js";
+/**
+ * Configuration options for InMemoryDBProvider.
+ * @public API
+ */
+export interface InMemoryDBConfig extends InMemoryDatabaseOptions {
+    /** Log database operations (default: false) */
+    logging?: boolean;
+    /** Maximum number of records per table (0 = unlimited) */
+    maxRecordsPerTable?: number;
+}
+/**
+ * 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 declare class InMemoryDBProvider implements IProvider, IHealthCheck, IMetrics, IBootstrap, IShutdown {
+    readonly name = "In-Memory Database Provider";
+    readonly version = "4.0.0";
+    readonly description = "High-performance, Prisma-compatible in-memory database for ExpressoTS";
+    readonly author = "ExpressoTS Team";
+    readonly repo = "https://github.com/expressots/expressots";
+    private database;
+    private config;
+    private queryCount;
+    private totalQueryTime;
+    private startTime?;
+    constructor(config?: InMemoryDBConfig);
+    /**
+     * 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: Partial<InMemoryDBConfig>): void;
+    /**
+     * Get the current configuration.
+     * @returns Current database configuration
+     * @public API
+     */
+    getConfig(): Readonly<InMemoryDBConfig>;
+    /**
+     * Bootstrap the database provider.
+     * Called after the application is fully ready.
+     */
+    bootstrap(): Promise<void>;
+    /**
+     * Shutdown the database provider.
+     * Called when the application shuts down.
+     */
+    shutdown(signal?: NodeJS.Signals): Promise<void>;
+    /**
+     * Perform a health check on the database.
+     * @returns Health check result
+     */
+    healthCheck(): HealthCheckResult;
+    /**
+     * Get database metrics.
+     * @returns Metrics object
+     */
+    getMetrics(): ProviderMetrics;
+    /**
+     * 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<T extends IEntity>(tableName: string, entityClass?: new (...args: Array<unknown>) => unknown): InMemoryAdapter<T>;
+    /**
+     * 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 }
+     *   });
+     * });
+     * ```
+     */
+    transaction<R>(fn: (db: InMemoryDatabase) => Promise<R>): Promise<R>;
+    /**
+     * Create a snapshot of all data.
+     * @returns JSON string of all data
+     */
+    snapshot(): string;
+    /**
+     * Restore data from a snapshot.
+     * @param json - JSON string of snapshot data
+     */
+    restore(json: string): void;
+    /**
+     * Clear all tables.
+     */
+    clear(): void;
+    /**
+     * Get database statistics.
+     * @returns Statistics for all tables
+     */
+    getStats(): {
+        tableCount: number;
+        totalRecords: number;
+        tables: Array<{
+            tableName: string;
+            recordCount: number;
+            indexes: Array<{
+                field: string;
+                size: number;
+                unique: boolean;
+            }>;
+            memoryEstimate: number;
+        }>;
+    };
+    /**
+     * Get the underlying database instance.
+     * @returns InMemoryDatabase instance
+     */
+    getDatabase(): InMemoryDatabase;
+}
+/**
+ * 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 declare abstract class BaseRepository<T extends IEntity> {
+    protected adapter: InMemoryAdapter<T>;
+    protected tableName: string;
+    constructor(db: InMemoryDBProvider, tableName: string, entityClass?: new (...args: Array<unknown>) => unknown);
+    findUnique(args: Parameters<InMemoryAdapter<T>["findUnique"]>[0]): Promise<T | null>;
+    findFirst(args?: Parameters<InMemoryAdapter<T>["findFirst"]>[0]): Promise<T | null>;
+    findMany(args?: Parameters<InMemoryAdapter<T>["findMany"]>[0]): Promise<Array<T>>;
+    create(args: Parameters<InMemoryAdapter<T>["create"]>[0]): Promise<T>;
+    createMany(args: Parameters<InMemoryAdapter<T>["createMany"]>[0]): Promise<{
+        count: number;
+    }>;
+    update(args: Parameters<InMemoryAdapter<T>["update"]>[0]): Promise<T>;
+    updateMany(args: Parameters<InMemoryAdapter<T>["updateMany"]>[0]): Promise<{
+        count: number;
+    }>;
+    upsert(args: Parameters<InMemoryAdapter<T>["upsert"]>[0]): Promise<T>;
+    delete(args: Parameters<InMemoryAdapter<T>["delete"]>[0]): Promise<T>;
+    deleteMany(args?: Parameters<InMemoryAdapter<T>["deleteMany"]>[0]): Promise<{
+        count: number;
+    }>;
+    count(args?: Parameters<InMemoryAdapter<T>["count"]>[0]): Promise<number>;
+    aggregate(args: Parameters<InMemoryAdapter<T>["aggregate"]>[0]): Promise<ReturnType<InMemoryAdapter<T>["aggregate"]>>;
+    transaction<R>(fn: (tx: InMemoryAdapter<T>) => Promise<R>): Promise<R>;
+}