@expressots/core 4.0.0-preview.1 → 4.0.0-preview.3

package/lib/cjs/framework-version.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FRAMEWORK_VERSION = void 0;
+/**
+ * Framework version string surfaced in startup banners and diagnostics.
+ *
+ * This file is auto-synced from the root `package.json` by
+ * `scripts/sync-version.js` before each build. Do not edit by hand.
+ */
+exports.FRAMEWORK_VERSION = "4.0.0-preview.3";

package/lib/cjs/lazy-loading/index.js

@@ -36,7 +36,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createLazyModuleWarmup = exports.LazyModuleWarmup = exports.createLazyLoadMetrics = exports.LazyLoadMetrics = exports.createLazyModuleManager = exports.LazyModuleManager = exports.createLazyModuleLoader = exports.LazyModuleLoader = exports.LAZY_MODULE_METADATA_KEY = exports.getModuleName = exports.isLazyModule = exports.createLazyModule = exports.CreateLazyModule = exports.LazyModule = void 0;
+exports.createLazyModuleWarmup = exports.LazyModuleWarmup = exports.createLazyLoadMetrics = exports.LazyLoadMetrics = exports.createLazyModuleManager = exports.LazyModuleManager = exports.createLazyModuleLoader = exports.LazyModuleLoader = exports.withLazyConfig = exports.withPreloadHint = exports.LAZY_MODULE_METADATA_KEY = exports.getModuleName = exports.isLazyModule = exports.createLazyModule = exports.CreateLazyModule = exports.LazyModule = void 0;
 // ============================================================================
 // Lazy Module
 // ============================================================================
@@ -47,6 +47,10 @@ Object.defineProperty(exports, "createLazyModule", { enumerable: true, get: func
 Object.defineProperty(exports, "isLazyModule", { enumerable: true, get: function () { return lazy_module_js_1.isLazyModule; } });
 Object.defineProperty(exports, "getModuleName", { enumerable: true, get: function () { return lazy_module_js_1.getModuleName; } });
 Object.defineProperty(exports, "LAZY_MODULE_METADATA_KEY", { enumerable: true, get: function () { return lazy_module_js_1.LAZY_MODULE_METADATA_KEY; } });
+// Free-function wrappers for the LazyModule chain methods.
+var lazy_module_helpers_js_1 = require("./lazy-module-helpers.js");
+Object.defineProperty(exports, "withPreloadHint", { enumerable: true, get: function () { return lazy_module_helpers_js_1.withPreloadHint; } });
+Object.defineProperty(exports, "withLazyConfig", { enumerable: true, get: function () { return lazy_module_helpers_js_1.withLazyConfig; } });
 // ============================================================================
 // Lazy Module Loader
 // ============================================================================

package/lib/cjs/lazy-loading/lazy-module-helpers.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Standalone (free-function) wrappers around `LazyModule` chain methods.
+ *
+ * The fluent API (`module.withPreloadHint(...).withLazyConfig(...)`) remains
+ * the recommended style. These helpers exist so users can compose lazy
+ * configurations with point-free style or apply the same hint to a list of
+ * modules:
+ *
+ * ```ts
+ * import { CreateLazyModule, withPreloadHint, withLazyConfig } from "@expressots/core";
+ *
+ * const Admin = withPreloadHint(
+ *   CreateLazyModule([AdminController]),
+ *   "low",
+ * );
+ *
+ * const Analytics = withLazyConfig(
+ *   CreateLazyModule([AnalyticsController]),
+ *   { preloadHint: "medium", prefetchAfterIdle: 5000 },
+ * );
+ * ```
+ *
+ * @public API
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withPreloadHint = withPreloadHint;
+exports.withLazyConfig = withLazyConfig;
+/**
+ * Set a preload hint on the supplied lazy module and return it.
+ *
+ * Equivalent to `module.withPreloadHint(hint)`. Returned reference is the same
+ * instance — no copy is made.
+ *
+ * @public API
+ */
+function withPreloadHint(module, hint) {
+    return module.withPreloadHint(hint);
+}
+/**
+ * Merge the supplied partial config into the lazy module and return it.
+ *
+ * Equivalent to `module.withLazyConfig(config)`.
+ *
+ * @public API
+ */
+function withLazyConfig(module, config) {
+    return module.withLazyConfig(config);
+}

package/lib/cjs/middleware/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mergeUploadConfigs = exports.clearGlobalUploadConfig = exports.hasGlobalUploadConfig = exports.getGlobalUploadConfig = exports.setGlobalUploadConfig = exports.resetMiddlewareRegistry = exports.getMiddlewareRegistry = exports.MiddlewareRegistry = exports.timeout = exports.parallel = exports.when = exports.compose = exports.use = exports.PlainTextFormatter = exports.YamlFormatter = exports.CsvFormatter = exports.XmlFormatter = exports.JsonFormatter = exports.AcceptHeaderParser = exports.FormatterRegistry = exports.ContentNegotiationService = exports.mergePresets = exports.createPreset = exports.getPresetsByTag = exports.getPresetNames = exports.getPreset = exports.MIDDLEWARE_PRESETS = exports.MiddlewareProfiler = exports.MIDDLEWARE_REGISTRY = exports.getPackageName = exports.clearMiddlewareCache = exports.getRegisteredMiddleware = exports.getAvailableMiddleware = exports.resolvePackage = exports.isPackageAvailable = exports.isMiddlewareAvailable = exports.middlewareResolver = exports.ExpressoMiddleware = exports.Middleware = void 0;
+exports.mergeUploadConfigs = exports.clearGlobalUploadConfig = exports.hasGlobalUploadConfig = exports.getGlobalUploadConfig = exports.setGlobalUploadConfig = exports.resetMiddlewareRegistry = exports.getMiddlewareRegistry = exports.MiddlewareRegistry = exports.clearStandalonePresets = exports.getStandalonePresetNames = exports.applyPreset = exports.definePreset = exports.timeout = exports.parallel = exports.when = exports.compose = exports.use = exports.PlainTextFormatter = exports.YamlFormatter = exports.CsvFormatter = exports.XmlFormatter = exports.JsonFormatter = exports.AcceptHeaderParser = exports.FormatterRegistry = exports.ContentNegotiationService = exports.MiddlewareProfiler = exports.MIDDLEWARE_REGISTRY = exports.getPackageName = exports.clearMiddlewareCache = exports.getRegisteredMiddleware = exports.getAvailableMiddleware = exports.resolvePackage = exports.isPackageAvailable = exports.isMiddlewareAvailable = exports.middlewareResolver = exports.ExpressoMiddleware = exports.Middleware = void 0;
 // Core middleware service and types
 var middleware_service_js_1 = require("./middleware-service.js");
 Object.defineProperty(exports, "Middleware", { enumerable: true, get: function () { return middleware_service_js_1.Middleware; } });
@@ -19,14 +19,6 @@ Object.defineProperty(exports, "MIDDLEWARE_REGISTRY", { enumerable: true, get: f
 // Middleware profiler
 var middleware_profiler_js_1 = require("./middleware-profiler.js");
 Object.defineProperty(exports, "MiddlewareProfiler", { enumerable: true, get: function () { return middleware_profiler_js_1.MiddlewareProfiler; } });
-// Middleware presets
-var middleware_presets_js_1 = require("./middleware-presets.js");
-Object.defineProperty(exports, "MIDDLEWARE_PRESETS", { enumerable: true, get: function () { return middleware_presets_js_1.MIDDLEWARE_PRESETS; } });
-Object.defineProperty(exports, "getPreset", { enumerable: true, get: function () { return middleware_presets_js_1.getPreset; } });
-Object.defineProperty(exports, "getPresetNames", { enumerable: true, get: function () { return middleware_presets_js_1.getPresetNames; } });
-Object.defineProperty(exports, "getPresetsByTag", { enumerable: true, get: function () { return middleware_presets_js_1.getPresetsByTag; } });
-Object.defineProperty(exports, "createPreset", { enumerable: true, get: function () { return middleware_presets_js_1.createPreset; } });
-Object.defineProperty(exports, "mergePresets", { enumerable: true, get: function () { return middleware_presets_js_1.mergePresets; } });
 // Content Negotiation exports
 var index_js_1 = require("./content-negotiation/index.js");
 Object.defineProperty(exports, "ContentNegotiationService", { enumerable: true, get: function () { return index_js_1.ContentNegotiationService; } });
@@ -47,6 +39,13 @@ Object.defineProperty(exports, "compose", { enumerable: true, get: function () {
 Object.defineProperty(exports, "when", { enumerable: true, get: function () { return middleware_utils_js_1.when; } });
 Object.defineProperty(exports, "parallel", { enumerable: true, get: function () { return middleware_utils_js_1.parallel; } });
 Object.defineProperty(exports, "timeout", { enumerable: true, get: function () { return middleware_utils_js_1.timeout; } });
+// V4 Standalone preset helpers (free-function wrappers around
+// Middleware.definePreset / Middleware.applyPreset)
+var presets_standalone_js_1 = require("./presets-standalone.js");
+Object.defineProperty(exports, "definePreset", { enumerable: true, get: function () { return presets_standalone_js_1.definePreset; } });
+Object.defineProperty(exports, "applyPreset", { enumerable: true, get: function () { return presets_standalone_js_1.applyPreset; } });
+Object.defineProperty(exports, "getStandalonePresetNames", { enumerable: true, get: function () { return presets_standalone_js_1.getStandalonePresetNames; } });
+Object.defineProperty(exports, "clearStandalonePresets", { enumerable: true, get: function () { return presets_standalone_js_1.clearStandalonePresets; } });
 // V4 Middleware registry
 var middleware_registry_js_1 = require("./middleware-registry.js");
 Object.defineProperty(exports, "MiddlewareRegistry", { enumerable: true, get: function () { return middleware_registry_js_1.MiddlewareRegistry; } });

package/lib/cjs/middleware/middleware-service.js

@@ -245,6 +245,8 @@ class Middleware {
         this.profilingEnabled = false;
         // v4: Custom presets storage
         this.customPresets = new Map();
+        // v4: Last applied preset info (for Studio integration)
+        this._lastPreset = null;
         // v4: Middleware registry reference
         this.registry = (0, middleware_registry_js_1.getMiddlewareRegistry)();
         // v4: Buffered startup logs (displayed after banner)
@@ -304,7 +306,9 @@ class Middleware {
      * @returns The type of the middleware.
      */
     getMiddlewareType(middleware) {
-        if (middleware && typeof middleware === "object" && "path" in middleware) {
+        if (middleware &&
+            typeof middleware === "object" &&
+            ("path" in middleware || "middlewares" in middleware)) {
             return MiddlewareType.Config;
         }
         if (typeof middleware === "function") {
@@ -367,7 +371,12 @@ class Middleware {
         const middlewareType = this.getMiddlewareType(m.middleware);
         if (middlewareType === MiddlewareType.Config) {
             const config = m.middleware;
-            return config.path || "ConfigMiddleware";
+            if (config.path)
+                return config.path;
+            const names = config.middlewares
+                .map((fn) => typeof fn === "function" ? fn.name : fn?.constructor?.name)
+                .filter((n) => n && n !== "anonymous" && n !== "");
+            return names.length > 0 ? names.join(", ") : "ConfigMiddleware";
         }
         else if (middlewareType === MiddlewareType.IExpressoMiddleware) {
             return m.middleware.constructor.name;
@@ -464,7 +473,11 @@ class Middleware {
             this._logger.warn(`No middlewares in the route [${config.path}]. Skipping...`, "middleware-service");
             return;
         }
-        const configKey = config.path || `config_${this.insertionOrder}`;
+        const inferredName = config.middlewares
+            .map((fn) => (typeof fn === "function" ? fn.name : fn?.constructor?.name))
+            .filter((n) => n && n !== "anonymous" && n !== "")
+            .join(", ");
+        const configKey = config.path || inferredName || `custom_${this.insertionOrder}`;
         if (this.middlewareExists(configKey)) {
             this._logger.warn(`[${config.path}] route already exists. Skipping...`, "middleware-service");
             return;
@@ -1231,6 +1244,7 @@ class Middleware {
                     origin: true,
                     credentials: true,
                     methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+                    allowedHeaders: ["Content-Type", "Authorization", "X-Requested-With"],
                 },
                 rateLimit: { windowMs: 60000, max: 100 },
             },
@@ -1484,6 +1498,11 @@ class Middleware {
         const finalConfig = overrides
             ? this.mergeConfigs(config, overrides)
             : config;
+        this._lastPreset = {
+            name: preset,
+            hasOverrides: !!overrides,
+            config: finalConfig,
+        };
         // Apply each category
         if (finalConfig.parse) {
             if (typeof finalConfig.parse === "boolean") {
@@ -1533,31 +1552,62 @@ class Middleware {
         const custom = Object.fromEntries(this.customPresets);
         return { ...builtIn, ...custom };
     }
+    /**
+     * Returns info about the last applied preset (name, whether overrides
+     * were used, and the effective merged config). Used by the adapter to
+     * forward preset metadata to Studio.
+     */
+    getLastAppliedPreset() {
+        return this._lastPreset;
+    }
     /**
      * Get built-in presets.
+     *
+     * Each preset is tuned for a specific workload:
+     * - api: REST APIs (large payloads, rate-limited, strict CORS)
+     * - web: traditional server-rendered apps (cookies, sessions, relaxed CORS)
+     * - spa: single-page apps served with static fallback
+     * - microservice: internal service-to-service (minimal surface, no security)
+     * - graphql: single endpoint with large JSON payloads
+     * - minimal: parsing only, no security or compression
+     * - development: relaxed for local iteration, verbose logging
+     * - production: hardened defaults for shipped deployments
      */
     getBuiltInPresets() {
         return {
             api: {
-                parse: true,
+                parse: {
+                    json: { limit: "10mb" },
+                    urlencoded: { extended: true, limit: "10mb" },
+                },
                 logger: { implementation: "auto" },
                 security: "api",
-                compress: true,
+                compress: { level: 6 },
             },
             web: {
-                parse: { json: true, urlencoded: true, cookies: true },
+                parse: {
+                    json: { limit: "5mb" },
+                    urlencoded: { extended: true, limit: "5mb" },
+                    cookies: true,
+                },
                 logger: { implementation: "auto" },
                 security: "standard",
                 compress: true,
             },
             spa: {
-                parse: { json: true, urlencoded: true },
+                parse: {
+                    json: { limit: "5mb" },
+                    urlencoded: { extended: true, limit: "5mb" },
+                },
                 security: "standard",
                 compress: true,
             },
             microservice: {
-                parse: { json: { limit: "1mb" } },
-                compress: true,
+                parse: {
+                    json: { limit: "1mb" },
+                    urlencoded: { extended: false, limit: "1mb" },
+                },
+                compress: { level: 6 },
             },
             graphql: {
                 parse: { json: { limit: "50mb" } },
@@ -1571,15 +1621,21 @@ class Middleware {
                 parse: true,
             },
             development: {
-                parse: true,
+                parse: {
+                    json: { limit: "50mb" },
+                    urlencoded: { extended: true, limit: "50mb" },
+                },
                 logger: { implementation: "morgan", options: { format: "dev" } },
                 security: "relaxed",
             },
             production: {
-                parse: true,
+                parse: {
+                    json: { limit: "10mb" },
+                    urlencoded: { extended: true, limit: "10mb" },
+                },
                 logger: { implementation: "auto", disableInTest: true },
                 security: "strict",
-                compress: true,
+                compress: { level: 6 },
             },
         };
     }

package/lib/cjs/middleware/presets-standalone.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Standalone (free-function) wrappers around the v4 middleware preset system.
+ *
+ * These exist alongside the `Middleware.definePreset` / `Middleware.applyPreset`
+ * instance methods so user code that doesn't have DI access to the `Middleware`
+ * provider — for example, declarative config files outside of the request
+ * lifecycle — can still register and apply presets.
+ *
+ * Usage:
+ * ```ts
+ * import { definePreset, applyPreset } from "@expressots/core";
+ *
+ * definePreset("my-api", {
+ *   parse: { json: { limit: "1mb" } },
+ *   security: { cors: { origin: "https://app.example.com" } },
+ * });
+ *
+ * // ...later, inside configureServices(), with the Middleware DI provider:
+ * applyPreset(this.services.middleware, "my-api");
+ * ```
+ *
+ * @public API
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definePreset = definePreset;
+exports.applyPreset = applyPreset;
+exports.getStandalonePresetNames = getStandalonePresetNames;
+exports.clearStandalonePresets = clearStandalonePresets;
+/** Module-level registry of presets defined via the standalone helper. */
+const standalonePresets = new Map();
+/**
+ * Register a custom middleware preset under the given name.
+ *
+ * The preset is stored in a module-level registry so it can be referenced
+ * later by `applyPreset(middleware, name)`. Calling `definePreset` with an
+ * existing name overwrites the previous definition.
+ *
+ * @param name   unique identifier for the preset
+ * @param config v4 middleware config object describing the preset
+ *
+ * @public API
+ */
+function definePreset(name, config) {
+    standalonePresets.set(name, config);
+}
+/**
+ * Apply a previously defined preset (built-in or registered via
+ * `definePreset`) to the supplied `Middleware` instance.
+ *
+ * Resolution order:
+ *  1. Built-in v4 presets (`api`, `web`, `spa`, `microservice`, `graphql`,
+ *     `minimal`, `development`, `production`) are matched by the
+ *     `Middleware` instance itself.
+ *  2. Custom presets previously registered via `Middleware.definePreset`
+ *     on the same instance.
+ *  3. Custom presets registered via the standalone `definePreset` here —
+ *     these are forwarded to the instance on demand.
+ *
+ * @param middleware the active `Middleware` provider (typically resolved from
+ *                   the DI container inside `configureServices()`)
+ * @param name       preset to apply
+ * @param overrides  optional partial config that is merged on top of the
+ *                   preset before application
+ *
+ * @public API
+ */
+function applyPreset(middleware, name, overrides) {
+    const standalone = standalonePresets.get(name);
+    if (standalone !== undefined) {
+        middleware.definePreset(name, standalone);
+    }
+    middleware.applyPreset(name, overrides);
+}
+/**
+ * Returns the names of every preset registered through the standalone
+ * `definePreset` helper. Built-in presets and per-instance custom presets
+ * are NOT included — those live on the `Middleware` instance.
+ *
+ * @public API
+ */
+function getStandalonePresetNames() {
+    return Array.from(standalonePresets.keys());
+}
+/**
+ * Remove every preset registered through the standalone `definePreset`
+ * helper. Useful in tests; rarely needed at runtime.
+ *
+ * @public API
+ */
+function clearStandalonePresets() {
+    standalonePresets.clear();
+}

package/lib/cjs/provider/db-in-memory/adapter/in-memory.adapter.js

@@ -381,6 +381,28 @@ class InMemoryAdapter {
                     where: { id: foreignKeyValue },
                 });
             }
+            case "manyToMany": {
+                // Resolve through a join table. Convention: the `through` table holds
+                // link records with two foreign keys named `<sourceClass>Id` and
+                // `<targetClass>Id` (class names lowercased). For example, a
+                // Post <-> Tag relation through "post_tags" stores rows shaped like
+                // `{ postId, tagId }`.
+                if (!relation.through || !this.entityClass)
+                    return [];
+                const sourceKey = `${this.entityClass.name.toLowerCase()}Id`;
+                const targetKey = `${relation.target().name.toLowerCase()}Id`;
+                const joinAdapter = this.database.table(relation.through);
+                const joinRecords = await joinAdapter.findMany({
+                    where: { [sourceKey]: entity.id },
+                });
+                const targetIds = joinRecords
+                    .map((record) => record[targetKey])
+                    .filter((value) => typeof value === "string");
+                if (targetIds.length === 0)
+                    return [];
+                const related = await Promise.all(targetIds.map((id) => relatedAdapter.findUnique({ where: { id } })));
+                return related.filter((item) => item !== null);
+            }
             default:
                 return null;
         }
@@ -530,6 +552,7 @@ class InMemoryDatabase {
                 entityClass,
                 timestamps: this.options.timestamps,
                 softDelete: this.options.softDelete,
+                maxRecordsPerTable: this.options.maxRecordsPerTable,
             }));
         }
         return this.tables.get(tableName);

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

@@ -5,6 +5,14 @@
  * 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
@@ -54,7 +62,7 @@
  * @module db-in-memory
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LegacyBaseRepository = exports.LegacyEntityAlreadyExistsError = exports.LegacyEntityNotFoundError = exports.InMemoryDataTable = exports.InMemoryDataProvider = exports.EntityAlreadyExistsError = exports.EntityNotFoundError = exports.UniqueConstraintError = exports.IdGenerator = exports.IndexManager = exports.MemoryStore = exports.QueryEngine = exports.DB_METADATA_KEYS = exports.SchemaRegistry = exports.ManyToMany = exports.BelongsTo = exports.HasOne = exports.HasMany = exports.Default = exports.Nullable = exports.Unique = exports.Index = exports.AutoGenerate = exports.PrimaryKey = exports.Entity = exports.InMemoryDatabase = exports.InMemoryAdapter = exports.BaseRepository = exports.InMemoryDBProvider = void 0;
+exports.LegacyBaseRepository = exports.LegacyEntityAlreadyExistsError = exports.LegacyEntityNotFoundError = exports.InMemoryDataTable = exports.InMemoryDataProvider = exports.EntityValidationError = exports.MaxRecordsExceededError = exports.EntityAlreadyExistsError = exports.EntityNotFoundError = exports.UniqueConstraintError = exports.IdGenerator = exports.IndexManager = exports.MemoryStore = exports.QueryEngine = exports.DB_METADATA_KEYS = exports.SchemaRegistry = exports.ManyToMany = exports.BelongsTo = exports.HasOne = exports.HasMany = exports.Default = exports.Nullable = exports.Unique = exports.Index = exports.AutoGenerate = exports.PrimaryKey = exports.Entity = exports.InMemoryDatabase = exports.InMemoryAdapter = exports.BaseRepository = exports.InMemoryDBProvider = void 0;
 // ═══════════════════════════════════════════════════════════════════════════
 // MAIN PROVIDER
 // ═══════════════════════════════════════════════════════════════════════════
@@ -104,6 +112,8 @@ Object.defineProperty(exports, "IdGenerator", { enumerable: true, get: function
 Object.defineProperty(exports, "UniqueConstraintError", { enumerable: true, get: function () { return index_js_4.UniqueConstraintError; } });
 Object.defineProperty(exports, "EntityNotFoundError", { enumerable: true, get: function () { return index_js_4.EntityNotFoundError; } });
 Object.defineProperty(exports, "EntityAlreadyExistsError", { enumerable: true, get: function () { return index_js_4.EntityAlreadyExistsError; } });
+Object.defineProperty(exports, "MaxRecordsExceededError", { enumerable: true, get: function () { return index_js_4.MaxRecordsExceededError; } });
+Object.defineProperty(exports, "EntityValidationError", { enumerable: true, get: function () { return index_js_4.EntityValidationError; } });
 // Legacy provider (deprecated, use InMemoryDBProvider)
 var db_in_memory_provider_js_1 = require("./db-in-memory.provider.js");
 Object.defineProperty(exports, "InMemoryDataProvider", { enumerable: true, get: function () { return db_in_memory_provider_js_1.InMemoryDataProvider; } });

package/lib/cjs/provider/db-in-memory/query/query-engine.js

@@ -411,6 +411,33 @@ class QueryEngine {
         return result;
     }
     // ═══════════════════════════════════════════════════════════════════════════
+    // CURSOR
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * 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, cursor) {
+        if (!cursor)
+            return entities;
+        const keys = Object.keys(cursor).filter((key) => cursor[key] !== undefined);
+        if (keys.length === 0)
+            return entities;
+        const index = entities.findIndex((entity) => keys.every((key) => entity[key] ===
+            cursor[key]));
+        if (index === -1)
+            return [];
+        return entities.slice(index);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
     // DISTINCT
     // ═══════════════════════════════════════════════════════════════════════════
     /**
@@ -563,6 +590,7 @@ class QueryEngine {
         let entities = this.executeWhere(args.where);
         entities = this.executeDistinct(entities, args.distinct);
         entities = this.executeOrderBy(entities, args.orderBy);
+        entities = this.executeCursor(entities, args.cursor);
         entities = this.executePagination(entities, args.skip, args.take);
         if (args.select) {
             return this.executeSelect(entities, args.select);

package/lib/cjs/provider/db-in-memory/schema/decorators.js

@@ -388,6 +388,24 @@ class SchemaRegistry {
     static getRelations(target) {
         return Reflect.getMetadata(exports.DB_METADATA_KEYS.relation, target) || [];
     }
+    /**
+     * Get primary key field names for an entity.
+     * @param target - Entity class
+     * @returns Array of primary key field names
+     * @public API
+     */
+    static getPrimaryKeys(target) {
+        return Reflect.getMetadata(exports.DB_METADATA_KEYS.primaryKey, target) || [];
+    }
+    /**
+     * Get nullable field names for an entity.
+     * @param target - Entity class
+     * @returns Array of nullable field names
+     * @public API
+     */
+    static getNullableFields(target) {
+        return Reflect.getMetadata(exports.DB_METADATA_KEYS.nullable, target) || [];
+    }
     /**
      * Clear all registered entities (useful for testing).
      * @public API

package/lib/cjs/provider/db-in-memory/storage/index.js

@@ -4,7 +4,7 @@
  * @module db-in-memory/storage
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EntityAlreadyExistsError = exports.EntityNotFoundError = exports.UniqueConstraintError = exports.IdGenerator = exports.IndexManager = exports.MemoryStore = void 0;
+exports.EntityValidationError = exports.MaxRecordsExceededError = exports.EntityAlreadyExistsError = exports.EntityNotFoundError = exports.UniqueConstraintError = exports.IdGenerator = exports.IndexManager = exports.MemoryStore = void 0;
 var memory_store_js_1 = require("./memory-store.js");
 Object.defineProperty(exports, "MemoryStore", { enumerable: true, get: function () { return memory_store_js_1.MemoryStore; } });
 Object.defineProperty(exports, "IndexManager", { enumerable: true, get: function () { return memory_store_js_1.IndexManager; } });
@@ -12,3 +12,5 @@ Object.defineProperty(exports, "IdGenerator", { enumerable: true, get: function
 Object.defineProperty(exports, "UniqueConstraintError", { enumerable: true, get: function () { return memory_store_js_1.UniqueConstraintError; } });
 Object.defineProperty(exports, "EntityNotFoundError", { enumerable: true, get: function () { return memory_store_js_1.EntityNotFoundError; } });
 Object.defineProperty(exports, "EntityAlreadyExistsError", { enumerable: true, get: function () { return memory_store_js_1.EntityAlreadyExistsError; } });
+Object.defineProperty(exports, "MaxRecordsExceededError", { enumerable: true, get: function () { return memory_store_js_1.MaxRecordsExceededError; } });
+Object.defineProperty(exports, "EntityValidationError", { enumerable: true, get: function () { return memory_store_js_1.EntityValidationError; } });

package/lib/cjs/provider/db-in-memory/storage/memory-store.js

@@ -7,7 +7,7 @@
  * @module db-in-memory/storage
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryStore = exports.IdGenerator = exports.EntityAlreadyExistsError = exports.EntityNotFoundError = exports.UniqueConstraintError = exports.IndexManager = void 0;
+exports.MemoryStore = exports.IdGenerator = exports.EntityAlreadyExistsError = exports.EntityValidationError = exports.MaxRecordsExceededError = exports.EntityNotFoundError = exports.UniqueConstraintError = exports.IndexManager = void 0;
 const node_crypto_1 = require("node:crypto");
 const decorators_js_1 = require("../schema/decorators.js");
 // ═══════════════════════════════════════════════════════════════════════════
@@ -194,6 +194,33 @@ class EntityNotFoundError extends Error {
     }
 }
 exports.EntityNotFoundError = EntityNotFoundError;
+/**
+ * Error thrown when a table reaches its configured record limit.
+ * @public API
+ */
+class MaxRecordsExceededError extends Error {
+    constructor(tableName, limit) {
+        super(`Table '${tableName}' has reached its maximum of ${limit} records`);
+        this.name = "MaxRecordsExceededError";
+        this.tableName = tableName;
+        this.limit = limit;
+    }
+}
+exports.MaxRecordsExceededError = MaxRecordsExceededError;
+/**
+ * Error thrown when entity validation fails (when `@Entity({ validate: true })`).
+ * @public API
+ */
+class EntityValidationError extends Error {
+    constructor(tableName, field, message) {
+        super(message ??
+            `Validation failed on '${tableName}': field '${field}' is required`);
+        this.name = "EntityValidationError";
+        this.tableName = tableName;
+        this.field = field;
+    }
+}
+exports.EntityValidationError = EntityValidationError;
 /**
  * Error thrown when an entity already exists.
  * @public API
@@ -288,10 +315,15 @@ class MemoryStore {
         this.autoGenerateFields = {};
         /** Default values */
         this.defaultValues = {};
+        /** Enable runtime validation (from @Entity({ validate: true })) */
+        this.validate = false;
+        /** Fields that must be present and non-null when validation is enabled */
+        this.requiredFields = [];
         this.tableName = tableName;
         this.entityClass = options.entityClass;
         this.timestamps = options.timestamps ?? true;
         this.softDelete = options.softDelete ?? false;
+        this.maxRecords = options.maxRecordsPerTable ?? 0;
         // Load schema metadata if entity class is provided
         if (this.entityClass) {
             this.loadSchemaMetadata();
@@ -331,6 +363,37 @@ class MemoryStore {
         if (entityMeta) {
             this.timestamps = entityMeta.timestamps;
             this.softDelete = entityMeta.softDelete;
+            this.validate = entityMeta.validate;
+        }
+        // When validation is enabled, treat primary-key and unique fields as
+        // required (must be present and non-null) unless explicitly @Nullable.
+        if (this.validate) {
+            const nullable = new Set(decorators_js_1.SchemaRegistry.getNullableFields(this.entityClass).map(String));
+            const required = new Set();
+            for (const field of decorators_js_1.SchemaRegistry.getPrimaryKeys(this.entityClass)) {
+                required.add(String(field));
+            }
+            for (const field of decorators_js_1.SchemaRegistry.getUniqueFields(this.entityClass)) {
+                required.add(String(field));
+            }
+            this.requiredFields = Array.from(required).filter((field) => !nullable.has(field));
+        }
+    }
+    /**
+     * Validate an entity against the schema (only when `validate` is enabled).
+     * Ensures required fields (primary key + unique, excluding @Nullable) are
+     * present and non-null.
+     * @private
+     * @throws ValidationError when a required field is missing or null
+     */
+    validateEntity(entity) {
+        if (!this.validate)
+            return;
+        for (const field of this.requiredFields) {
+            const value = entity[field];
+            if (value === undefined || value === null) {
+                throw new EntityValidationError(this.tableName, field);
+            }
         }
     }
     /**
@@ -380,6 +443,12 @@ class MemoryStore {
         if (this.data.has(prepared.id)) {
             throw new EntityAlreadyExistsError(this.tableName, prepared.id);
         }
+        // Enforce per-table record limit (0 = unlimited)
+        if (this.maxRecords > 0 && this.data.size >= this.maxRecords) {
+            throw new MaxRecordsExceededError(this.tableName, this.maxRecords);
+        }
+        // Validate required fields (no-op unless @Entity({ validate: true }))
+        this.validateEntity(prepared);
         // Index first (will throw if unique constraint violated)
         this.indexManager.indexEntity(prepared);
         // Then store
@@ -426,6 +495,8 @@ class MemoryStore {
         if (this.timestamps) {
             updated.updatedAt = new Date();
         }
+        // Validate required fields (no-op unless @Entity({ validate: true }))
+        this.validateEntity(updated);
         // Update indexes
         this.indexManager.updateIndex(existing, updated);
         // Store updated entity