@expressots/core 3.0.0 → 4.0.0-preview.1

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

@@ -0,0 +1,314 @@
+/**
+ * Schema Decorators for ExpressoTS In-Memory Database
+ *
+ * Decorators for defining entity schemas, indexes, relations,
+ * and other metadata for the in-memory database.
+ *
+ * @module db-in-memory/schema
+ */
+import "reflect-metadata";
+export declare const DB_METADATA_KEYS: {
+    entity: string;
+    primaryKey: string;
+    index: string;
+    unique: string;
+    autoGenerate: string;
+    timestamps: string;
+    softDelete: string;
+    default: string;
+    relation: string;
+    nullable: string;
+};
+/**
+ * Options for the @Entity decorator.
+ * @public API
+ */
+export interface EntityOptions {
+    /** Table/collection name (defaults to class name) */
+    name?: string;
+    /** Enable runtime validation (default: false) */
+    validate?: boolean;
+    /** Enable soft deletes (default: false) */
+    softDelete?: boolean;
+    /** Enable automatic timestamps (default: true) */
+    timestamps?: boolean;
+}
+/**
+ * Entity metadata stored on decorated classes.
+ * @internal
+ */
+export interface EntityMetadata {
+    name: string;
+    validate: boolean;
+    softDelete: boolean;
+    timestamps: boolean;
+    target: new (...args: Array<unknown>) => unknown;
+}
+/**
+ * Marks a class as a database entity.
+ *
+ * @param options - Entity configuration options
+ * @returns Class decorator
+ *
+ * @example
+ * ```typescript
+ * @Entity({ name: "users", timestamps: true })
+ * class User {
+ *   @PrimaryKey()
+ *   @AutoGenerate("uuid")
+ *   id!: string;
+ *
+ *   @Index()
+ *   @Unique()
+ *   email!: string;
+ *
+ *   name!: string;
+ * }
+ * ```
+ * @public API
+ */
+export declare function Entity(options?: EntityOptions | string): ClassDecorator;
+/**
+ * Marks a field as the primary key.
+ *
+ * @example
+ * ```typescript
+ * @PrimaryKey()
+ * id!: string;
+ * ```
+ * @public API
+ */
+export declare function PrimaryKey(): PropertyDecorator;
+/**
+ * Auto-generation strategy types.
+ * @public API
+ */
+export type AutoGenerateStrategy = "uuid" | "cuid" | "increment" | "ulid";
+/**
+ * Marks a field for auto-generation.
+ *
+ * @param strategy - The generation strategy (uuid, cuid, increment, ulid)
+ *
+ * @example
+ * ```typescript
+ * @AutoGenerate("uuid")
+ * id!: string;
+ * ```
+ * @public API
+ */
+export declare function AutoGenerate(strategy: AutoGenerateStrategy): PropertyDecorator;
+/**
+ * Index options.
+ * @public API
+ */
+export interface IndexOptions {
+    /** Index name (auto-generated if not provided) */
+    name?: string;
+    /** Composite index with other fields */
+    composite?: Array<string>;
+}
+/**
+ * Marks a field as indexed for faster lookups.
+ *
+ * @param options - Index configuration
+ *
+ * @example
+ * ```typescript
+ * @Index()
+ * email!: string;
+ *
+ * @Index({ composite: ["firstName", "lastName"] })
+ * firstName!: string;
+ * ```
+ * @public API
+ */
+export declare function Index(options?: IndexOptions): PropertyDecorator;
+/**
+ * Marks a field as unique.
+ *
+ * @example
+ * ```typescript
+ * @Unique()
+ * email!: string;
+ * ```
+ * @public API
+ */
+export declare function Unique(): PropertyDecorator;
+/**
+ * Marks a field as nullable.
+ *
+ * @example
+ * ```typescript
+ * @Nullable()
+ * middleName?: string;
+ * ```
+ * @public API
+ */
+export declare function Nullable(): PropertyDecorator;
+/**
+ * Sets a default value for a field.
+ *
+ * @param value - Default value or factory function
+ *
+ * @example
+ * ```typescript
+ * @Default(true)
+ * isActive!: boolean;
+ *
+ * @Default(() => new Date())
+ * createdAt!: Date;
+ * ```
+ * @public API
+ */
+export declare function Default<T>(value: T | (() => T)): PropertyDecorator;
+/**
+ * Relation types.
+ * @public API
+ */
+export type RelationType = "hasOne" | "hasMany" | "belongsTo" | "manyToMany";
+/**
+ * Relation metadata.
+ * @internal
+ */
+export interface RelationMetadata {
+    type: RelationType;
+    target: () => new (...args: Array<unknown>) => unknown;
+    foreignKey: string;
+    field: string | symbol;
+    through?: string;
+}
+/**
+ * Defines a one-to-many relation.
+ *
+ * @param target - Factory function returning the related entity class
+ * @param foreignKey - The foreign key field on the related entity
+ *
+ * @example
+ * ```typescript
+ * @HasMany(() => Post, "authorId")
+ * posts?: Post[];
+ * ```
+ * @public API
+ */
+export declare function HasMany(target: () => new (...args: Array<unknown>) => unknown, foreignKey: string): PropertyDecorator;
+/**
+ * Defines a one-to-one relation.
+ *
+ * @param target - Factory function returning the related entity class
+ * @param foreignKey - The foreign key field
+ *
+ * @example
+ * ```typescript
+ * @HasOne(() => Profile, "userId")
+ * profile?: Profile;
+ * ```
+ * @public API
+ */
+export declare function HasOne(target: () => new (...args: Array<unknown>) => unknown, foreignKey: string): PropertyDecorator;
+/**
+ * Defines a belongs-to relation (inverse of HasMany/HasOne).
+ *
+ * @param target - Factory function returning the related entity class
+ * @param foreignKey - The foreign key field on this entity
+ *
+ * @example
+ * ```typescript
+ * @BelongsTo(() => User, "authorId")
+ * author?: User;
+ *
+ * authorId!: string;
+ * ```
+ * @public API
+ */
+export declare function BelongsTo(target: () => new (...args: Array<unknown>) => unknown, foreignKey: string): PropertyDecorator;
+/**
+ * Defines a many-to-many relation.
+ *
+ * @param target - Factory function returning the related entity class
+ * @param through - The join table/collection name
+ *
+ * @example
+ * ```typescript
+ * @ManyToMany(() => Tag, "post_tags")
+ * tags?: Tag[];
+ * ```
+ * @public API
+ */
+export declare function ManyToMany(target: () => new (...args: Array<unknown>) => unknown, through: string): PropertyDecorator;
+/**
+ * Schema Registry for storing and retrieving entity metadata.
+ * @public API
+ */
+export declare class SchemaRegistry {
+    private static entities;
+    private static entityByName;
+    /**
+     * Register an entity with the schema registry.
+     * @internal
+     */
+    static register(target: new (...args: Array<unknown>) => unknown, metadata: EntityMetadata): void;
+    /**
+     * Get entity metadata by class.
+     * @param target - Entity class
+     * @returns Entity metadata or undefined
+     * @public API
+     */
+    static getMetadata(target: new (...args: Array<unknown>) => unknown): EntityMetadata | undefined;
+    /**
+     * Get entity class by name.
+     * @param name - Entity name
+     * @returns Entity class or undefined
+     * @public API
+     */
+    static getByName(name: string): (new (...args: Array<unknown>) => unknown) | undefined;
+    /**
+     * Get all registered entities.
+     * @returns Array of entity metadata
+     * @public API
+     */
+    static getAll(): Array<EntityMetadata>;
+    /**
+     * Get index metadata for an entity.
+     * @param target - Entity class
+     * @returns Array of index metadata
+     * @public API
+     */
+    static getIndexes(target: new (...args: Array<unknown>) => unknown): Array<{
+        field: string | symbol;
+        name: string;
+        composite?: Array<string>;
+    }>;
+    /**
+     * Get unique field metadata for an entity.
+     * @param target - Entity class
+     * @returns Array of unique field names
+     * @public API
+     */
+    static getUniqueFields(target: new (...args: Array<unknown>) => unknown): Array<string | symbol>;
+    /**
+     * Get auto-generate metadata for an entity.
+     * @param target - Entity class
+     * @returns Object mapping field names to generation strategies
+     * @public API
+     */
+    static getAutoGenerateFields(target: new (...args: Array<unknown>) => unknown): Record<string | symbol, AutoGenerateStrategy>;
+    /**
+     * Get default values for an entity.
+     * @param target - Entity class
+     * @returns Object mapping field names to default values/factories
+     * @public API
+     */
+    static getDefaults(target: new (...args: Array<unknown>) => unknown): Record<string | symbol, unknown>;
+    /**
+     * Get relation metadata for an entity.
+     * @param target - Entity class
+     * @returns Array of relation metadata
+     * @public API
+     */
+    static getRelations(target: new (...args: Array<unknown>) => unknown): Array<RelationMetadata>;
+    /**
+     * Clear all registered entities (useful for testing).
+     * @public API
+     */
+    static clear(): void;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Entity Interfaces for ExpressoTS In-Memory Database
+ *
+ * Base interfaces and types for entity definitions.
+ *
+ * @module db-in-memory/schema
+ */
+/**
+ * Base interface that all entities must implement.
+ * Provides the required `id` field for record identification.
+ *
+ * @example
+ * ```typescript
+ * interface User extends IEntity {
+ *   name: string;
+ *   email: string;
+ * }
+ * ```
+ * @public API
+ */
+export interface IEntity {
+    /** Unique identifier for the entity */
+    id?: string;
+}
+/**
+ * Entity with automatic timestamps.
+ * Extends IEntity with createdAt and updatedAt fields.
+ *
+ * @example
+ * ```typescript
+ * interface User extends ITimestampedEntity {
+ *   name: string;
+ *   email: string;
+ * }
+ * ```
+ * @public API
+ */
+export interface ITimestampedEntity extends IEntity {
+    /** Timestamp when the record was created */
+    createdAt?: Date;
+    /** Timestamp when the record was last updated */
+    updatedAt?: Date;
+}
+/**
+ * Entity with soft delete support.
+ * Extends ITimestampedEntity with deletedAt field.
+ *
+ * @example
+ * ```typescript
+ * interface User extends ISoftDeleteEntity {
+ *   name: string;
+ *   email: string;
+ * }
+ * ```
+ * @public API
+ */
+export interface ISoftDeleteEntity extends ITimestampedEntity {
+    /** Timestamp when the record was soft deleted (null if not deleted) */
+    deletedAt?: Date | null;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Schema Module Exports
+ * @module db-in-memory/schema
+ */
+export { IEntity, ITimestampedEntity, ISoftDeleteEntity, } from "./entity.interface.js";
+export { Entity, EntityOptions, EntityMetadata, PrimaryKey, AutoGenerate, AutoGenerateStrategy, Index, IndexOptions, Unique, Nullable, Default, HasMany, HasOne, BelongsTo, ManyToMany, RelationType, RelationMetadata, SchemaRegistry, DB_METADATA_KEYS, } from "./decorators.js";

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

@@ -0,0 +1,5 @@
+/**
+ * Storage Module Exports
+ * @module db-in-memory/storage
+ */
+export { MemoryStore, MemoryStoreOptions, IndexManager, IdGenerator, UniqueConstraintError, EntityNotFoundError, EntityAlreadyExistsError, } from "./memory-store.js";

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

@@ -0,0 +1,326 @@
+/**
+ * Memory Store for ExpressoTS In-Memory Database
+ *
+ * High-performance in-memory storage with secondary indexes.
+ *
+ * @module db-in-memory/storage
+ */
+import { IEntity } from "../schema/entity.interface.js";
+import { AutoGenerateStrategy } from "../schema/decorators.js";
+/**
+ * Manages secondary indexes for a table.
+ * Provides O(1) lookups for indexed fields.
+ * @internal
+ */
+export declare class IndexManager<T extends IEntity> {
+    /** Map of field name -> value -> Set of entity IDs */
+    private indexes;
+    /** Set of indexed field names */
+    private indexedFields;
+    /** Set of unique field names */
+    private uniqueFields;
+    /**
+     * Create an index for a field.
+     * @param field - Field name to index
+     */
+    createIndex(field: string): void;
+    /**
+     * Mark a field as unique.
+     * @param field - Field name
+     */
+    markUnique(field: string): void;
+    /**
+     * Check if a field is indexed.
+     * @param field - Field name
+     * @returns True if field is indexed
+     */
+    hasIndex(field: string): boolean;
+    /**
+     * Check if a field is unique.
+     * @param field - Field name
+     * @returns True if field is unique
+     */
+    isUnique(field: string): boolean;
+    /**
+     * Add an entity to all indexes.
+     * @param entity - Entity to index
+     * @throws Error if unique constraint is violated
+     */
+    indexEntity(entity: T): void;
+    /**
+     * Remove an entity from all indexes.
+     * @param entity - Entity to remove from indexes
+     */
+    removeFromIndex(entity: T): void;
+    /**
+     * Update an entity in all indexes.
+     * @param oldEntity - Previous entity state
+     * @param newEntity - New entity state
+     */
+    updateIndex(oldEntity: T, newEntity: T): void;
+    /**
+     * Find entity IDs by indexed field value.
+     * @param field - Field name
+     * @param value - Value to find
+     * @returns Set of matching entity IDs or undefined if not indexed
+     */
+    findByIndex(field: string, value: unknown): Set<string> | undefined;
+    /**
+     * Get all values for an indexed field.
+     * @param field - Field name
+     * @returns Array of unique values
+     */
+    getIndexValues(field: string): Array<unknown>;
+    /**
+     * Clear all indexes.
+     */
+    clear(): void;
+    /**
+     * Get index statistics.
+     */
+    getStats(): Array<{
+        field: string;
+        size: number;
+        unique: boolean;
+    }>;
+}
+/**
+ * Error thrown when a unique constraint is violated.
+ * @public API
+ */
+export declare class UniqueConstraintError extends Error {
+    field: string;
+    value: unknown;
+    constructor(field: string, value: unknown);
+}
+/**
+ * Error thrown when an entity is not found.
+ * @public API
+ */
+export declare class EntityNotFoundError extends Error {
+    entityName: string;
+    id: string;
+    constructor(entityName: string, id: string);
+}
+/**
+ * Error thrown when an entity already exists.
+ * @public API
+ */
+export declare class EntityAlreadyExistsError extends Error {
+    entityName: string;
+    id: string;
+    constructor(entityName: string, id: string);
+}
+/**
+ * ID Generator utility.
+ * @internal
+ */
+export declare class IdGenerator {
+    private static incrementCounter;
+    /**
+     * Generate an ID based on the strategy.
+     * @param strategy - Generation strategy
+     * @param tableName - Table name (for increment strategy)
+     * @returns Generated ID
+     */
+    static generate(strategy: AutoGenerateStrategy, tableName: string): string;
+    private static generateCuid;
+    private static generateUlid;
+    private static generateIncrement;
+    /**
+     * Reset increment counters (useful for testing).
+     */
+    static reset(): void;
+}
+/**
+ * Configuration options for MemoryStore.
+ * @public API
+ */
+export interface MemoryStoreOptions {
+    /** Entity class for schema metadata */
+    entityClass?: new (...args: Array<unknown>) => unknown;
+    /** Enable timestamps (createdAt, updatedAt) */
+    timestamps?: boolean;
+    /** Enable soft deletes */
+    softDelete?: boolean;
+}
+/**
+ * High-performance in-memory storage for a single table/collection.
+ * Features:
+ * - O(1) lookups by ID
+ * - O(1) lookups by indexed fields
+ * - Automatic ID generation
+ * - Timestamp management
+ * - Soft delete support
+ * - Transaction snapshots
+ *
+ * @public API
+ */
+export declare class MemoryStore<T extends IEntity> {
+    /** Primary storage: ID -> Entity */
+    private data;
+    /** Index manager for secondary indexes */
+    private indexManager;
+    /** Transaction snapshot stack */
+    private transactionStack;
+    /** Table/collection name */
+    private tableName;
+    /** Entity class for metadata */
+    private entityClass?;
+    /** Enable timestamps */
+    private timestamps;
+    /** Enable soft delete */
+    private softDelete;
+    /** Auto-generate configuration */
+    private autoGenerateFields;
+    /** Default values */
+    private defaultValues;
+    constructor(tableName: string, options?: MemoryStoreOptions);
+    /**
+     * Load schema metadata from decorators.
+     * @private
+     */
+    private loadSchemaMetadata;
+    /**
+     * Apply auto-generation and defaults to entity.
+     * @private
+     */
+    private applyDefaults;
+    /**
+     * Insert a new entity.
+     * @param entity - Entity to insert
+     * @returns Inserted entity with generated fields
+     * @throws EntityAlreadyExistsError if ID already exists
+     * @throws UniqueConstraintError if unique constraint is violated
+     */
+    insert(entity: Partial<T>): T;
+    /**
+     * Insert multiple entities.
+     * @param entities - Entities to insert
+     * @param skipDuplicates - Skip entities with duplicate keys
+     * @returns Array of inserted entities
+     */
+    insertMany(entities: Array<Partial<T>>, skipDuplicates?: boolean): Array<T>;
+    /**
+     * Update an entity by ID.
+     * @param id - Entity ID
+     * @param data - Update data
+     * @returns Updated entity
+     * @throws EntityNotFoundError if entity not found
+     */
+    update(id: string, data: Partial<T>): T;
+    /**
+     * Update multiple entities matching a predicate.
+     * @param predicate - Filter function
+     * @param data - Update data
+     * @returns Number of updated entities
+     */
+    updateMany(predicate: (entity: T) => boolean, data: Partial<T>): number;
+    /**
+     * Delete an entity by ID.
+     * @param id - Entity ID
+     * @returns Deleted entity
+     * @throws EntityNotFoundError if entity not found
+     */
+    delete(id: string): T;
+    /**
+     * Delete multiple entities matching a predicate.
+     * @param predicate - Filter function
+     * @returns Number of deleted entities
+     */
+    deleteMany(predicate?: (entity: T) => boolean): number;
+    /**
+     * Find an entity by ID.
+     * @param id - Entity ID
+     * @returns Entity or undefined
+     */
+    findById(id: string): T | undefined;
+    /**
+     * Find entities by indexed field value (O(1) lookup).
+     * @param field - Field name
+     * @param value - Value to find
+     * @returns Array of matching entities
+     */
+    findByIndex(field: string, value: unknown): Array<T>;
+    /**
+     * Find all entities.
+     * @returns Array of all entities
+     */
+    findAll(): Array<T>;
+    /**
+     * Find entities matching a predicate.
+     * @param predicate - Filter function
+     * @returns Array of matching entities
+     */
+    find(predicate: (entity: T) => boolean): Array<T>;
+    /**
+     * Find the first entity matching a predicate.
+     * @param predicate - Filter function
+     * @returns First matching entity or undefined
+     */
+    findFirst(predicate: (entity: T) => boolean): T | undefined;
+    /**
+     * Count entities.
+     * @param predicate - Optional filter function
+     * @returns Number of entities
+     */
+    count(predicate?: (entity: T) => boolean): number;
+    /**
+     * Check if an entity exists.
+     * @param id - Entity ID
+     * @returns True if entity exists
+     */
+    exists(id: string): boolean;
+    /**
+     * Clear all entities.
+     */
+    clear(): void;
+    /**
+     * Begin a transaction (creates a snapshot).
+     */
+    beginTransaction(): void;
+    /**
+     * Commit the current transaction.
+     */
+    commitTransaction(): void;
+    /**
+     * Rollback the current transaction.
+     * @throws Error if no transaction is active
+     */
+    rollbackTransaction(): void;
+    /**
+     * Execute a function within a transaction.
+     * @param fn - Function to execute
+     * @returns Result of the function
+     */
+    transaction<R>(fn: () => Promise<R>): Promise<R>;
+    /**
+     * Export all data as JSON.
+     * @returns JSON string of all data
+     */
+    toJSON(): string;
+    /**
+     * Import data from JSON.
+     * @param json - JSON string to import
+     */
+    fromJSON(json: string): void;
+    /**
+     * Get store statistics.
+     * @returns Statistics object
+     */
+    getStats(): {
+        tableName: string;
+        recordCount: number;
+        indexes: Array<{
+            field: string;
+            size: number;
+            unique: boolean;
+        }>;
+        memoryEstimate: number;
+    };
+    /**
+     * Estimate memory usage in bytes.
+     * @private
+     */
+    private estimateMemory;
+}