@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -0,0 +1,71 @@
+/**
+ * ExpressoTS In-Memory Database
+ *
+ * A high-performance, Prisma-compatible in-memory database
+ * for ExpressoTS applications.
+ *
+ * Scope: this database is intended for development, testing, and
+ * prototyping. Data lives in process memory (with optional file
+ * snapshots) and does not provide the crash safety, concurrency, or
+ * multi-process guarantees of a real database engine. It implements the
+ * universal `IDataAdapter` contract so it can be swapped for a
+ * production adapter (Prisma, TypeORM, etc.) without rewriting
+ * repositories.
+ *
+ * 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
+ */
+export { InMemoryDBProvider, InMemoryDBConfig, BaseRepository, } from "./db.provider.js";
+export { IDataAdapter, ITableAdapter, IMultiTableAdapter, IReactiveDataAdapter, ISubscription, ChangeEvent, ChangeType, InMemoryAdapter, InMemoryAdapterOptions, InMemoryDatabase, InMemoryDatabaseOptions, } from "./adapter/index.js";
+export { IEntity, ITimestampedEntity, ISoftDeleteEntity, Entity, EntityOptions, EntityMetadata, PrimaryKey, AutoGenerate, AutoGenerateStrategy, Index, IndexOptions, Unique, Nullable, Default, HasMany, HasOne, BelongsTo, ManyToMany, RelationType, RelationMetadata, SchemaRegistry, DB_METADATA_KEYS, } from "./schema/index.js";
+export { StringFilter, NumberFilter, BooleanFilter, DateFilter, FieldFilter, WhereInput, WhereUniqueInput, OrderByInput, SortOrder, SelectInput, IncludeInput, FindUniqueArgs, FindFirstArgs, FindManyArgs, CreateArgs, CreateInput, CreateManyArgs, UpdateArgs, UpdateInput, UpdateManyArgs, UpsertArgs, DeleteArgs, DeleteManyArgs, CountArgs, CountSelect, AggregateArgs, AggregateResult, NumericFieldsOnly, GroupByArgs, BatchPayload, TransactionClient, QueryEngine, } from "./query/index.js";
+export { MemoryStore, MemoryStoreOptions, IndexManager, IdGenerator, UniqueConstraintError, EntityNotFoundError, EntityAlreadyExistsError, MaxRecordsExceededError, EntityValidationError, } from "./storage/index.js";
+export { IRepository, IDataTable, IDataProvider, } from "./db-in-memory.interface.js";
+export { InMemoryDataProvider, InMemoryDataTable, } from "./db-in-memory.provider.js";
+export { EntityNotFoundError as LegacyEntityNotFoundError, EntityAlreadyExistsError as LegacyEntityAlreadyExistsError, } from "./db-in-memory.types.js";
+export { BaseRepository as LegacyBaseRepository } from "./base-repo.repository.js";

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

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

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

@@ -0,0 +1,114 @@
+/**
+ * Query Engine for ExpressoTS In-Memory Database
+ *
+ * Parses and executes Prisma-like queries against the MemoryStore.
+ *
+ * @module db-in-memory/query
+ */
+import { IEntity } from "../schema/entity.interface.js";
+import { MemoryStore } from "../storage/memory-store.js";
+import { WhereInput, WhereUniqueInput, OrderByInput, FindManyArgs, SelectInput, AggregateArgs, AggregateResult } from "./query.types.js";
+/**
+ * Query Engine for parsing and executing Prisma-like queries.
+ *
+ * Features:
+ * - Type-safe where clauses with operators
+ * - Logical operators (AND, OR, NOT)
+ * - Sorting with multiple fields
+ * - Pagination (skip, take, cursor)
+ * - Field selection
+ * - Aggregations
+ *
+ * @public API
+ */
+export declare class QueryEngine<T extends IEntity> {
+    private store;
+    constructor(store: MemoryStore<T>);
+    /**
+     * Execute a where clause and return matching entities.
+     * @param where - Where clause
+     * @returns Array of matching entities
+     */
+    executeWhere(where?: WhereInput<T>): Array<T>;
+    /**
+     * Check if an entity matches a where clause.
+     * @param entity - Entity to check
+     * @param where - Where clause
+     * @returns True if entity matches
+     */
+    matchesWhere(entity: T, where: WhereInput<T>): boolean;
+    /**
+     * Check if a value matches a condition.
+     * @param value - Value to check
+     * @param condition - Condition (value or filter object)
+     * @returns True if value matches
+     */
+    private matchesCondition;
+    /**
+     * Compare two values for equality.
+     */
+    private compareValues;
+    private isStringFilter;
+    private matchesStringFilter;
+    private isNumberFilter;
+    private matchesNumberFilter;
+    private isBooleanFilter;
+    private matchesBooleanFilter;
+    private isDateFilter;
+    private matchesDateFilter;
+    /**
+     * Sort entities by order clauses.
+     * @param entities - Entities to sort
+     * @param orderBy - Order by clause(s)
+     * @returns Sorted entities
+     */
+    executeOrderBy(entities: Array<T>, orderBy?: OrderByInput<T> | Array<OrderByInput<T>>): Array<T>;
+    private compareForSort;
+    /**
+     * Apply pagination to entities.
+     * @param entities - Entities to paginate
+     * @param skip - Number of entities to skip
+     * @param take - Number of entities to take
+     * @returns Paginated entities
+     */
+    executePagination(entities: Array<T>, skip?: number, take?: number): Array<T>;
+    /**
+     * Apply cursor-based pagination. The cursor identifies a record (by id or
+     * any other field combination) within the ordered result set; the returned
+     * slice starts at that record. Combine with `skip` (typically `skip: 1` to
+     * exclude the cursor itself) and `take`.
+     *
+     * Should be applied after `orderBy` and before `skip`/`take`.
+     *
+     * @param entities - Ordered entities to slice
+     * @param cursor - Unique cursor identifying the start record
+     * @returns Entities starting at the cursor (empty array if not found)
+     */
+    executeCursor(entities: Array<T>, cursor?: WhereUniqueInput<T>): Array<T>;
+    /**
+     * Get distinct entities by specified fields.
+     * @param entities - Entities to filter
+     * @param distinct - Fields to check for distinctness
+     * @returns Distinct entities
+     */
+    executeDistinct(entities: Array<T>, distinct?: Array<keyof T>): Array<T>;
+    /**
+     * Apply field selection to entities.
+     * @param entities - Entities to project
+     * @param select - Fields to select
+     * @returns Projected entities
+     */
+    executeSelect(entities: Array<T>, select?: SelectInput<T>): Array<Partial<T>>;
+    /**
+     * Execute aggregate operations.
+     * @param args - Aggregate arguments
+     * @returns Aggregate result
+     */
+    executeAggregate(args: AggregateArgs<T>): AggregateResult<T>;
+    /**
+     * Execute a full findMany query.
+     * @param args - FindMany arguments
+     * @returns Array of matching entities
+     */
+    executeFindMany(args?: FindManyArgs<T>): Array<T>;
+}

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

@@ -0,0 +1,318 @@
+/**
+ * Query Types for ExpressoTS In-Memory Database
+ *
+ * Prisma-inspired type-safe query interfaces that provide
+ * a familiar, intuitive API for database operations.
+ *
+ * @module db-in-memory/query
+ */
+import { IEntity } from "../schema/entity.interface.js";
+/**
+ * Filter operations for string fields.
+ * @public API
+ */
+export interface StringFilter {
+    equals?: string;
+    not?: string | StringFilter;
+    in?: Array<string>;
+    notIn?: Array<string>;
+    contains?: string;
+    startsWith?: string;
+    endsWith?: string;
+    /** Case-insensitive matching (default: false) */
+    mode?: "default" | "insensitive";
+}
+/**
+ * Filter operations for number fields.
+ * @public API
+ */
+export interface NumberFilter {
+    equals?: number;
+    not?: number | NumberFilter;
+    in?: Array<number>;
+    notIn?: Array<number>;
+    lt?: number;
+    lte?: number;
+    gt?: number;
+    gte?: number;
+}
+/**
+ * Filter operations for boolean fields.
+ * @public API
+ */
+export interface BooleanFilter {
+    equals?: boolean;
+    not?: boolean | BooleanFilter;
+}
+/**
+ * Filter operations for date fields.
+ * @public API
+ */
+export interface DateFilter {
+    equals?: Date;
+    not?: Date | DateFilter;
+    in?: Array<Date>;
+    notIn?: Array<Date>;
+    lt?: Date;
+    lte?: Date;
+    gt?: Date;
+    gte?: Date;
+}
+/**
+ * Union type for all field filters.
+ * @public API
+ */
+export type FieldFilter = StringFilter | NumberFilter | BooleanFilter | DateFilter;
+/**
+ * Helper type to resolve the filter type for a field.
+ * Uses NonNullable to properly handle optional fields (e.g., age?: number).
+ * @internal
+ */
+type FieldFilterType<T> = NonNullable<T> extends string ? string | StringFilter | null : NonNullable<T> extends number ? number | NumberFilter | null : NonNullable<T> extends boolean ? boolean | BooleanFilter | null : NonNullable<T> extends Date ? Date | DateFilter | null : T;
+/**
+ * Generic where input that works with any entity type.
+ * Supports field-level filters and logical operators.
+ * Properly handles optional fields by using NonNullable.
+ * @public API
+ */
+export type WhereInput<T> = {
+    [K in keyof T]?: FieldFilterType<T[K]>;
+} & {
+    AND?: WhereInput<T> | Array<WhereInput<T>>;
+    OR?: Array<WhereInput<T>>;
+    NOT?: WhereInput<T> | Array<WhereInput<T>>;
+};
+/**
+ * Sort direction.
+ * @public API
+ */
+export type SortOrder = "asc" | "desc";
+/**
+ * Order by input for sorting results.
+ * @public API
+ */
+export type OrderByInput<T> = {
+    [K in keyof T]?: SortOrder;
+};
+/**
+ * Select specific fields to return.
+ * @public API
+ */
+export type SelectInput<T> = {
+    [K in keyof T]?: boolean;
+};
+/**
+ * Include related entities.
+ * @public API
+ */
+export type IncludeInput<T> = {
+    [K in keyof T]?: T[K] extends Array<infer U> ? boolean | FindManyArgs<U extends IEntity ? U : never> : T[K] extends IEntity ? boolean | FindUniqueArgs<T[K]> : never;
+};
+/**
+ * Arguments for finding a single unique record.
+ * @public API
+ */
+export interface FindUniqueArgs<T> {
+    where: WhereUniqueInput<T>;
+    select?: SelectInput<T>;
+    include?: IncludeInput<T>;
+}
+/**
+ * Where input for unique lookups (requires unique field).
+ * @public API
+ */
+export type WhereUniqueInput<T> = {
+    id?: string;
+} & Partial<T>;
+/**
+ * Arguments for finding the first matching record.
+ * @public API
+ */
+export interface FindFirstArgs<T> {
+    where?: WhereInput<T>;
+    select?: SelectInput<T>;
+    include?: IncludeInput<T>;
+    orderBy?: OrderByInput<T> | Array<OrderByInput<T>>;
+    skip?: number;
+}
+/**
+ * Arguments for finding multiple records.
+ * @public API
+ */
+export interface FindManyArgs<T> {
+    where?: WhereInput<T>;
+    select?: SelectInput<T>;
+    include?: IncludeInput<T>;
+    orderBy?: OrderByInput<T> | Array<OrderByInput<T>>;
+    skip?: number;
+    take?: number;
+    cursor?: WhereUniqueInput<T>;
+    distinct?: Array<keyof T>;
+}
+/**
+ * Arguments for creating a single record.
+ * @public API
+ */
+export interface CreateArgs<T> {
+    data: CreateInput<T>;
+    select?: SelectInput<T>;
+    include?: IncludeInput<T>;
+}
+/**
+ * Input data for creating a record.
+ * @public API
+ */
+export type CreateInput<T> = Omit<T, "id" | "createdAt" | "updatedAt"> & {
+    id?: string;
+};
+/**
+ * Arguments for creating multiple records.
+ * @public API
+ */
+export interface CreateManyArgs<T> {
+    data: Array<CreateInput<T>>;
+    skipDuplicates?: boolean;
+}
+/**
+ * Arguments for updating a single record.
+ * @public API
+ */
+export interface UpdateArgs<T> {
+    where: WhereUniqueInput<T>;
+    data: UpdateInput<T>;
+    select?: SelectInput<T>;
+    include?: IncludeInput<T>;
+}
+/**
+ * Input data for updating a record.
+ * @public API
+ */
+export type UpdateInput<T> = Partial<Omit<T, "id" | "createdAt">>;
+/**
+ * Arguments for updating multiple records.
+ * @public API
+ */
+export interface UpdateManyArgs<T> {
+    where: WhereInput<T>;
+    data: UpdateInput<T>;
+}
+/**
+ * Arguments for upserting (update or insert) a record.
+ * @public API
+ */
+export interface UpsertArgs<T> {
+    where: WhereUniqueInput<T>;
+    create: CreateInput<T>;
+    update: UpdateInput<T>;
+    select?: SelectInput<T>;
+    include?: IncludeInput<T>;
+}
+/**
+ * Arguments for deleting a single record.
+ * @public API
+ */
+export interface DeleteArgs<T> {
+    where: WhereUniqueInput<T>;
+    select?: SelectInput<T>;
+    include?: IncludeInput<T>;
+}
+/**
+ * Arguments for deleting multiple records.
+ * @public API
+ */
+export interface DeleteManyArgs<T> {
+    where?: WhereInput<T>;
+}
+/**
+ * Arguments for counting records.
+ * @public API
+ */
+export interface CountArgs<T> {
+    where?: WhereInput<T>;
+    cursor?: WhereUniqueInput<T>;
+    skip?: number;
+    take?: number;
+    orderBy?: OrderByInput<T> | Array<OrderByInput<T>>;
+    select?: CountSelect<T>;
+}
+/**
+ * Select specific fields for count.
+ * @public API
+ */
+export type CountSelect<T> = {
+    [K in keyof T]?: boolean;
+} & {
+    _all?: boolean;
+};
+/**
+ * Arguments for aggregate operations.
+ * @public API
+ */
+export interface AggregateArgs<T> {
+    where?: WhereInput<T>;
+    cursor?: WhereUniqueInput<T>;
+    skip?: number;
+    take?: number;
+    orderBy?: OrderByInput<T> | Array<OrderByInput<T>>;
+    _count?: boolean | CountSelect<T>;
+    _avg?: NumericFieldsOnly<T>;
+    _sum?: NumericFieldsOnly<T>;
+    _min?: SelectInput<T>;
+    _max?: SelectInput<T>;
+}
+/**
+ * Select only numeric fields for avg/sum operations.
+ * Uses NonNullable to properly handle optional number fields (e.g., age?: number).
+ * @public API
+ */
+export type NumericFieldsOnly<T> = {
+    [K in keyof T as NonNullable<T[K]> extends number ? K : never]?: boolean;
+};
+/**
+ * Result of aggregate operations.
+ * @public API
+ */
+export interface AggregateResult<T> {
+    _count?: number | Partial<Record<keyof T | "_all", number>>;
+    _avg?: Partial<Record<keyof T, number | null>>;
+    _sum?: Partial<Record<keyof T, number | null>>;
+    _min?: Partial<T>;
+    _max?: Partial<T>;
+}
+/**
+ * Arguments for grouping records.
+ * @public API
+ */
+export interface GroupByArgs<T> {
+    where?: WhereInput<T>;
+    by: Array<keyof T>;
+    having?: WhereInput<T>;
+    orderBy?: OrderByInput<T> | Array<OrderByInput<T>>;
+    skip?: number;
+    take?: number;
+    _count?: boolean | CountSelect<T>;
+    _avg?: NumericFieldsOnly<T>;
+    _sum?: NumericFieldsOnly<T>;
+    _min?: SelectInput<T>;
+    _max?: SelectInput<T>;
+}
+/**
+ * Result of batch operations (createMany, updateMany, deleteMany).
+ * @public API
+ */
+export interface BatchPayload {
+    count: number;
+}
+/**
+ * Transaction client interface for nested transactions.
+ * @public API
+ */
+export interface TransactionClient<T extends IEntity = IEntity> {
+    findUnique(args: FindUniqueArgs<T>): Promise<T | null>;
+    findFirst(args: FindFirstArgs<T>): Promise<T | null>;
+    findMany(args?: FindManyArgs<T>): Promise<Array<T>>;
+    create(args: CreateArgs<T>): Promise<T>;
+    update(args: UpdateArgs<T>): Promise<T>;
+    delete(args: DeleteArgs<T>): Promise<T>;
+}
+export {};