@elsikora/nestjs-crud-automator 3.0.2 → 4.0.0-dev.2

package/dist/esm/class/api/controller/get-list/query/plan-compiler.class.js

@@ -1,11 +1,14 @@
 import { createHash } from 'node:crypto';
+import { API_CONTROLLER_CURSOR_TOKEN_MAX_LENGTH } from '../../../../../constant/api-controller-cursor.constant.js';
 import '../../../../../constant/decorator/api/function.constant.js';
 import { PROPERTY_DESCRIBE_DECORATOR_API_CONSTANT } from '../../../../../constant/decorator/api/property-describe.constant.js';
 import { FILTER_OPERATOR_REGISTRY_CONSTANT } from '../../../../../constant/filter/operator-registry.constant.js';
+import { UNSAFE_OBJECT_PROPERTY_NAMES_CONSTANT } from '../../../../../constant/safe-object-property-names.constant.js';
 import { DTO_GENERATE_CONSTANT } from '../../../../../constant/utility/dto/generate.constant.js';
 import '../../../../../enum/decorator/api/action.enum.js';
 import '../../../../../enum/decorator/api/authentication-type.enum.js';
 import { EApiControllerGetListQueryFilterMissingBehavior } from '../../../../../enum/decorator/api/controller/get-list/query/filter/missing-behavior.enum.js';
+import { EApiControllerGetListQueryPaginationMode } from '../../../../../enum/decorator/api/controller/get-list/query/pagination-mode.enum.js';
 import { EApiControllerGetListQueryUnlistedFields } from '../../../../../enum/decorator/api/controller/get-list/query/unlisted-fields.enum.js';
 import '../../../../../enum/decorator/api/controller/relation-reference-shape.enum.js';
 import { EApiControllerRequestTarget } from '../../../../../enum/decorator/api/controller/request/target.enum.js';
@@ -27,64 +30,133 @@ import '../../../../../enum/decorator/api/property/date/identifier.enum.js';
 import '../../../../../enum/decorator/api/property/date/type.enum.js';
 import { EApiPropertyDescribeType } from '../../../../../enum/decorator/api/property/desribe-type.enum.js';
 import { EApiPropertyNumberType } from '../../../../../enum/decorator/api/property/number-type.enum.js';
-import '../../../../../enum/decorator/api/property/string-type.enum.js';
+import { EApiPropertyStringType } from '../../../../../enum/decorator/api/property/string-type.enum.js';
 import '../../../../../enum/decorator/api/route/subscriber-authorization-expectation.enum.js';
 import { EApiRouteType } from '../../../../../enum/decorator/api/route/type.enum.js';
 import { EFilterOperand } from '../../../../../enum/filter/operand.enum.js';
 import { EFilterOperation } from '../../../../../enum/filter/operation.enum.js';
-import '../../../../../enum/filter/order-direction.enum.js';
+import { EFilterOrderDirection } from '../../../../../enum/filter/order-direction.enum.js';
+import { EManualDtoPropertyMetadataDecorator } from '../../../../../enum/utility/manual-dto-property-metadata-decorator.enum.js';
 import { ApiControllerGetListQueryEnumValues } from '../../../../../utility/api/controller/get-list/query/enum-values.utility.js';
+import { ApiControllerGetListQueryResolveCursorOrderFields } from '../../../../../utility/api/controller/get-list/query/resolve-cursor-order-fields.utility.js';
 import { FilterOrderByFromEntity } from '../../../../../utility/api/filter-order-by-from-entity.utility.js';
+import { DtoGetDecoratorConfig } from '../../../../../utility/dto/get/decorator-config.utility.js';
 import { DtoIsPropertyShouldBeMarked } from '../../../../../utility/dto/is/property/should-be-marked.utility.js';
+import { GetManualDtoPropertyMetadata } from '../../../../../utility/dto/manual/property-metadata/get.utility.js';
 import { ErrorException } from '../../../../../utility/error/exception.utility.js';
 import { GenerateEntityInformation } from '../../../../../utility/generate-entity-information.utility.js';
 import { getMetadataArgsStorage } from 'typeorm';
 
+const CURSOR_RESPONSE_PROPERTY_COUNT = 3;
+const CURSOR_MAXIMUM_ARRAY_INDEX_PROPERTY = 4_294_967_294;
+const CURSOR_BIGINT_COLUMN_TYPES = new Set(["bigint", "int8"]);
+const CURSOR_BOOLEAN_COLUMN_TYPES = new Set(["bool", "boolean", "boolean-constructor"]);
+const CURSOR_ENUM_INTEGER_COLUMN_TYPES = new Set(["int", "int2", "int4", "integer", "smallint"]);
+const CURSOR_INTEGER_COLUMN_TYPES = new Set([...CURSOR_ENUM_INTEGER_COLUMN_TYPES, "number-constructor"]);
+const CURSOR_NON_PERSISTED_COLUMN_MODES = new Set(["array", "treeChildrenCount", "virtual", "virtual-property"]);
+const CURSOR_UUID_COLUMN_TYPES = new Set(["uuid"]);
 class ApiControllerGetListQueryPlanCompiler {
     static compile(controller, entity, entityMetadata, routeConfig) {
         const queryTarget = routeConfig.request?.[EApiControllerRequestTarget.QUERY];
-        if (!queryTarget?.filter && !queryTarget?.order) {
+        if (!queryTarget?.filter && !queryTarget?.order && !queryTarget?.pagination) {
             return undefined;
         }
         if (routeConfig.dto?.[EApiDtoType.QUERY]) {
             throw ErrorException("Generated GET_LIST query configuration cannot be combined with a manual QUERY DTO");
         }
         const currentGuard = routeConfig.security?.authentication?.guard;
-        const filterBaseline = this.buildFilterBaseline(entityMetadata, currentGuard);
-        const orderBaseline = this.buildOrderBaseline(entity, entityMetadata);
-        const filter = queryTarget.filter ? this.compileFilter(queryTarget.filter, filterBaseline) : Object.freeze({ fields: filterBaseline, isLegacy: true });
-        const order = queryTarget.order ? this.compileOrder(queryTarget.order, orderBaseline) : Object.freeze({ fields: orderBaseline, isLegacy: true });
+        const pagination = this.compilePagination(queryTarget.pagination);
+        const isCursor = pagination.mode === EApiControllerGetListQueryPaginationMode.CURSOR;
+        const filterBaseline = this.buildFilterBaseline(entity, entityMetadata, currentGuard, isCursor);
+        const serverOrderBaseline = this.buildServerOrderBaseline(entity, entityMetadata, isCursor);
+        const orderBaseline = this.buildOrderBaseline(entity, entityMetadata, serverOrderBaseline, isCursor);
+        const filter = queryTarget.filter ? this.compileFilter(queryTarget.filter, filterBaseline, isCursor) : Object.freeze({ fields: filterBaseline, isLegacy: !isCursor, ...(isCursor ? { unlistedFields: EApiControllerGetListQueryUnlistedFields.INHERIT } : {}) });
+        const order = queryTarget.order ? this.compileOrder(queryTarget.order, orderBaseline, serverOrderBaseline, isCursor) : Object.freeze({ fields: orderBaseline, isLegacy: true, serverFields: serverOrderBaseline });
+        const cursorFields = isCursor ? ApiControllerGetListQueryResolveCursorOrderFields(order) : Object.freeze([]);
+        if (isCursor) {
+            this.validateCursorPlan(entity, entityMetadata, order, cursorFields, routeConfig);
+        }
+        const normalizedOrder = {
+            fields: Object.values(order.fields).map((field) => ({
+                isEnabled: field.isEnabled,
+                ...(isCursor ? { metadata: this.createCursorOrderFieldFingerprint(field) } : {}),
+                path: field.path,
+            })),
+            isLegacy: order.isLegacy,
+            unlistedFields: order.unlistedFields,
+        };
+        if (queryTarget.order?.defaultOrder !== undefined) {
+            normalizedOrder.defaultOrder = order.defaultOrder;
+        }
+        if (queryTarget.order?.tieBreakers !== undefined) {
+            normalizedOrder.tieBreakers = order.tieBreakers;
+        }
+        if (isCursor) {
+            normalizedOrder.effectiveFields = cursorFields.map((path) => {
+                const field = order.serverFields[path];
+                if (!field) {
+                    throw ErrorException(`CURSOR GET_LIST order field "${path}" is unavailable`);
+                }
+                return {
+                    metadata: this.createCursorOrderFieldFingerprint(field),
+                    path,
+                    storage: {
+                        hasTransformer: field.hasTransformer,
+                        isArray: field.isColumnArray,
+                        isSelected: field.isSelected,
+                        isUnsigned: field.isUnsigned,
+                        mode: field.columnMode,
+                        precision: field.precision,
+                        scale: field.scale,
+                        type: field.columnType,
+                    },
+                };
+            });
+        }
         const normalizedPlan = {
             filter: {
                 fields: Object.values(filter.fields).map((field) => ({
                     allowedOperations: field.allowedOperations,
                     defaultCondition: field.defaultCondition,
                     isEnabled: field.isEnabled,
+                    ...(isCursor ? { metadata: this.createFieldFingerprint(field) } : {}),
                     missingBehavior: field.missingBehavior,
                     path: field.path,
                 })),
                 isLegacy: filter.isLegacy,
                 unlistedFields: filter.unlistedFields,
             },
-            order: {
-                fields: Object.values(order.fields).map((field) => ({
-                    isEnabled: field.isEnabled,
-                    path: field.path,
-                })),
-                isLegacy: order.isLegacy,
-                unlistedFields: order.unlistedFields,
-            },
+            order: normalizedOrder,
         };
+        if (isCursor) {
+            normalizedPlan.pagination = pagination;
+        }
         const signature = createHash("sha256").update(JSON.stringify(normalizedPlan)).digest("hex");
-        return Object.freeze({
-            controllerName: controller.name || "AnonymousController",
+        const controllerName = controller.name || "AnonymousController";
+        const schemaName = `${controllerName}${entityMetadata.name ?? "UnknownResource"}GetListQuery${signature}DTO`;
+        if (!isCursor) {
+            const pageFields = Object.freeze(Object.fromEntries(Object.entries(order.fields).map(([path, field]) => [path, Object.freeze({ isEnabled: field.isEnabled, path: field.path })])));
+            const pageOrderProperties = {};
+            for (const [key, value] of Object.entries(order)) {
+                if (key === "serverFields") {
+                    continue;
+                }
+                pageOrderProperties[key] = key === "fields" ? pageFields : value;
+            }
+            const pageOrder = Object.freeze(pageOrderProperties);
+            return Object.freeze({ controllerName, filter, order: pageOrder, schemaName, signature });
+        }
+        const plan = Object.freeze({
+            controllerName,
             filter,
             order,
-            schemaName: `${controller.name || "AnonymousController"}${entityMetadata.name ?? "UnknownResource"}GetListQuery${signature}DTO`,
+            pagination: pagination,
+            schemaName,
             signature,
         });
+        return plan;
     }
-    static buildFilterBaseline(entityMetadata, currentGuard) {
+    static buildFilterBaseline(entity, entityMetadata, currentGuard, isCursor) {
         const fields = {};
         for (const column of entityMetadata.columns) {
             const metadata = this.getPropertyMetadata(column);
@@ -96,7 +168,7 @@ class ApiControllerGetListQueryPlanCompiler {
                 if (!DtoIsPropertyShouldBeMarked(EApiRouteType.GET_LIST, EApiDtoType.QUERY, path, metadata, column.isPrimary, currentGuard)) {
                     continue;
                 }
-                fields[path] = this.createFilterField(path, metadata, this.isColumnNullable(entityMetadata.name, path, metadata));
+                fields[path] = this.createFilterField(path, metadata, this.isColumnNullable(entity, entityMetadata.name, path, metadata, isCursor));
                 continue;
             }
             if (!column.relation?.target || !this.isToOneRelation(column) || !DtoIsPropertyShouldBeMarked(EApiRouteType.GET_LIST, EApiDtoType.QUERY, path, metadata, column.isPrimary, currentGuard)) {
@@ -119,22 +191,46 @@ class ApiControllerGetListQueryPlanCompiler {
                     continue;
                 }
                 const nestedPath = `${path}.${nestedName}`;
-                fields[nestedPath] = this.createFilterField(nestedPath, nestedMetadata, this.isColumnNullable(relationMetadata.name, nestedName, nestedMetadata));
+                fields[nestedPath] = this.createFilterField(nestedPath, nestedMetadata, this.isColumnNullable(column.relation.target, relationMetadata.name, nestedName, nestedMetadata, isCursor));
             }
         }
-        return Object.freeze(this.sortRecord(fields));
+        return Object.freeze(this.sortRecord(fields, isCursor));
     }
-    static buildOrderBaseline(entity, entityMetadata) {
+    static buildOrderBaseline(entity, entityMetadata, serverBaseline, isCursor) {
         const fields = {};
         const orderFields = FilterOrderByFromEntity(entity, entityMetadata, EApiRouteType.GET_LIST, EApiDtoType.QUERY);
         for (const path of Object.values(orderFields)
             .map(String)
-            .toSorted((left, right) => left.localeCompare(right))) {
-            fields[path] = Object.freeze({ isEnabled: true, path });
+            .toSorted((left, right) => this.compareStrings(left, right, isCursor))) {
+            const field = serverBaseline[path];
+            if (field) {
+                fields[path] = field;
+            }
         }
         return Object.freeze(fields);
     }
-    static compileAllowedOperations(rawOperations, field) {
+    static buildServerOrderBaseline(entity, entityMetadata, isCursor) {
+        const fields = {};
+        for (const column of entityMetadata.columns) {
+            const metadata = this.getPropertyMetadata(column);
+            if (!column.relation && metadata && metadata.type !== EApiPropertyDescribeType.OBJECT && metadata.type !== EApiPropertyDescribeType.RELATION) {
+                const path = String(column.name);
+                const columnMetadata = this.findColumnMetadata(entity, entityMetadata.name, path);
+                fields[path] = this.createOrderField(path, metadata, this.isColumnNullable(entity, entityMetadata.name, path, metadata, isCursor), columnMetadata);
+            }
+        }
+        return Object.freeze(this.sortRecord(fields, isCursor));
+    }
+    static compareStrings(left, right, isCursor) {
+        if (!isCursor) {
+            return left.localeCompare(right);
+        }
+        if (left < right) {
+            return -1;
+        }
+        return left > right ? 1 : 0;
+    }
+    static compileAllowedOperations(rawOperations, field, isCursor) {
         if (!Array.isArray(rawOperations) || rawOperations.length === 0) {
             throw ErrorException(`Enabled GET_LIST filter field "${field.path}" requires non-empty allowedOperations`);
         }
@@ -152,7 +248,7 @@ class ApiControllerGetListQueryPlanCompiler {
                 operations.push(operation);
             }
         }
-        return Object.freeze(operations.toSorted((left, right) => left.localeCompare(right)));
+        return Object.freeze(operations.toSorted((left, right) => this.compareStrings(left, right, isCursor)));
     }
     static compileDefaultCondition(rawCondition, field, allowedOperations) {
         const condition = this.requireRecord(rawCondition, `GET_LIST filter defaultCondition for "${field.path}"`);
@@ -181,13 +277,13 @@ class ApiControllerGetListQueryPlanCompiler {
         }
         return Object.freeze({ operation, values: Object.freeze([...conditionValues]) });
     }
-    static compileFilter(config, baseline) {
+    static compileFilter(config, baseline, isCursor) {
         const rawConfig = this.requireRecord(config, "GET_LIST filter");
         this.requireExactKeys(rawConfig, ["fields", "unlistedFields"], "GET_LIST filter");
         this.validateUnlistedFields(config.unlistedFields, "filter");
         const configuredFields = this.requireRecord(config.fields, "GET_LIST filter fields");
         const fields = config.unlistedFields === EApiControllerGetListQueryUnlistedFields.INHERIT ? { ...baseline } : {};
-        for (const [path, rawField] of Object.entries(configuredFields).toSorted(([left], [right]) => left.localeCompare(right))) {
+        for (const [path, rawField] of Object.entries(configuredFields).toSorted(([left], [right]) => this.compareStrings(left, right, isCursor))) {
             const baselineField = baseline[path];
             if (!baselineField) {
                 throw ErrorException(`GET_LIST filter field "${path}" is not an enabled direct scalar or one-hop to-one scalar path`);
@@ -203,7 +299,7 @@ class ApiControllerGetListQueryPlanCompiler {
                 throw ErrorException(`GET_LIST filter field "${path}" must declare isEnabled`);
             }
             this.requireAllowedKeys(field, ["allowedOperations", "defaultCondition", "isEnabled", "missingBehavior"], `GET_LIST filter field "${path}"`);
-            const allowedOperations = this.compileAllowedOperations(field.allowedOperations, baselineField);
+            const allowedOperations = this.compileAllowedOperations(field.allowedOperations, baselineField, isCursor);
             const missingBehavior = field.missingBehavior ?? EApiControllerGetListQueryFilterMissingBehavior.OMIT;
             if (!Object.values(EApiControllerGetListQueryFilterMissingBehavior).includes(missingBehavior)) {
                 throw ErrorException(`GET_LIST filter field "${path}" has an invalid missingBehavior`);
@@ -224,18 +320,18 @@ class ApiControllerGetListQueryPlanCompiler {
             });
         }
         return Object.freeze({
-            fields: Object.freeze(this.sortRecord(fields)),
+            fields: Object.freeze(this.sortRecord(fields, isCursor)),
             isLegacy: false,
             unlistedFields: config.unlistedFields,
         });
     }
-    static compileOrder(config, baseline) {
+    static compileOrder(config, baseline, serverBaseline, isCursor) {
         const rawConfig = this.requireRecord(config, "GET_LIST order");
-        this.requireExactKeys(rawConfig, ["fields", "unlistedFields"], "GET_LIST order");
+        this.requireAllowedKeys(rawConfig, ["defaultOrder", "fields", "tieBreakers", "unlistedFields"], "GET_LIST order");
         this.validateUnlistedFields(config.unlistedFields, "order");
         const configuredFields = this.requireRecord(config.fields, "GET_LIST order fields");
         const fields = config.unlistedFields === EApiControllerGetListQueryUnlistedFields.INHERIT ? { ...baseline } : {};
-        for (const [path, rawField] of Object.entries(configuredFields).toSorted(([left], [right]) => left.localeCompare(right))) {
+        for (const [path, rawField] of Object.entries(configuredFields).toSorted(([left], [right]) => this.compareStrings(left, right, isCursor))) {
             const baselineField = baseline[path];
             if (!baselineField) {
                 throw ErrorException(`GET_LIST order field "${path}" is not an enabled direct scalar path`);
@@ -247,41 +343,236 @@ class ApiControllerGetListQueryPlanCompiler {
             }
             fields[path] = Object.freeze({ ...baselineField, isEnabled: field.isEnabled });
         }
+        const defaultOrder = this.compileOrderEntries(config.defaultOrder, serverBaseline, "defaultOrder");
+        const tieBreakers = this.compileOrderEntries(config.tieBreakers, serverBaseline, "tieBreakers");
+        for (const defaultEntry of defaultOrder) {
+            const tieBreaker = tieBreakers.find((entry) => entry.field === defaultEntry.field);
+            if (tieBreaker && tieBreaker.direction !== defaultEntry.direction) {
+                throw ErrorException(`GET_LIST order field "${defaultEntry.field}" has conflicting directions across defaultOrder and tieBreakers`);
+            }
+        }
         return Object.freeze({
-            fields: Object.freeze(this.sortRecord(fields)),
+            ...(config.defaultOrder === undefined ? {} : { defaultOrder }),
+            fields: Object.freeze(this.sortRecord(fields, isCursor)),
             isLegacy: false,
+            serverFields: serverBaseline,
+            ...(config.tieBreakers === undefined ? {} : { tieBreakers }),
             unlistedFields: config.unlistedFields,
         });
     }
+    static compileOrderEntries(rawEntries, baseline, context) {
+        if (rawEntries === undefined) {
+            return Object.freeze([]);
+        }
+        if (!Array.isArray(rawEntries)) {
+            throw ErrorException(`GET_LIST order ${context} must be an array`);
+        }
+        const entries = [];
+        const seenFields = new Set();
+        for (const [index, rawEntry] of rawEntries.entries()) {
+            const entry = this.requireRecord(rawEntry, `GET_LIST order ${context}[${index}]`);
+            this.requireExactKeys(entry, ["direction", "field"], `GET_LIST order ${context}[${index}]`);
+            const field = entry.field;
+            const direction = entry.direction;
+            if (typeof field !== "string" || !baseline[field]) {
+                throw ErrorException(`GET_LIST order ${context}[${index}] must target a described direct scalar entity field`);
+            }
+            if (direction !== EFilterOrderDirection.ASC && direction !== EFilterOrderDirection.DESC) {
+                throw ErrorException(`GET_LIST order ${context}[${index}] has an invalid direction`);
+            }
+            if (seenFields.has(field)) {
+                throw ErrorException(`GET_LIST order ${context} contains duplicate field "${field}"`);
+            }
+            seenFields.add(field);
+            entries.push(Object.freeze({ direction, field }));
+        }
+        return Object.freeze(entries);
+    }
+    static compilePagination(config) {
+        if (config === undefined) {
+            return Object.freeze({ mode: EApiControllerGetListQueryPaginationMode.PAGE });
+        }
+        const rawConfig = this.requireRecord(config, "GET_LIST pagination");
+        this.requireExactKeys(rawConfig, ["mode"], "GET_LIST pagination");
+        if (!Object.values(EApiControllerGetListQueryPaginationMode).includes(config.mode)) {
+            throw ErrorException("GET_LIST pagination mode must be PAGE or CURSOR");
+        }
+        return Object.freeze({ mode: config.mode });
+    }
+    static createCursorOrderFieldFingerprint(field) {
+        const fingerprint = { type: field.type };
+        if ("format" in field.metadata) {
+            fingerprint.format = field.metadata.format;
+        }
+        if ("enum" in field.metadata) {
+            const values = ApiControllerGetListQueryEnumValues(field.metadata.enum);
+            let enumKind = "mixed";
+            if (values.every((value) => typeof value === "number")) {
+                enumKind = "number";
+            }
+            else if (values.every((value) => typeof value === "string")) {
+                enumKind = "string";
+            }
+            fingerprint.enumKind = enumKind;
+        }
+        return fingerprint;
+    }
+    static createFieldFingerprint(field) {
+        const metadata = field.metadata;
+        const fingerprint = {
+            isNullable: field.isNullable,
+            type: field.type,
+        };
+        for (const key of ["format", "identifier", "isArray", "maximum", "maxLength", "minimum", "minLength", "multipleOf", "pattern"]) {
+            if (key in metadata) {
+                fingerprint[key] = metadata[key];
+            }
+        }
+        if ("enum" in field.metadata) {
+            fingerprint.enum = ApiControllerGetListQueryEnumValues(field.metadata.enum);
+        }
+        return fingerprint;
+    }
     static createFilterField(path, metadata, isNullable) {
         const allowedOperations = Object.freeze(Object.values(EFilterOperation).filter((operation) => {
             const descriptor = FILTER_OPERATOR_REGISTRY_CONSTANT.OPERATORS[operation];
             return descriptor.kinds.includes(metadata.type) && (descriptor.operand !== EFilterOperand.NONE || isNullable);
         }));
-        const planMetadata = "enum" in metadata ? { ...metadata, enum: Object.freeze({ ...metadata.enum }) } : { ...metadata };
+        const planMetadata = this.createPlanMetadata(metadata);
         return Object.freeze({
             allowedOperations,
             isEnabled: true,
             isNullable,
-            metadata: Object.freeze(planMetadata),
+            metadata: planMetadata,
             missingBehavior: EApiControllerGetListQueryFilterMissingBehavior.OMIT,
             path,
             type: metadata.type,
         });
     }
+    static createOrderField(path, metadata, isNullable, columnMetadata) {
+        return Object.freeze({
+            columnMode: columnMetadata?.mode ?? "unknown",
+            columnType: this.normalizeColumnType(columnMetadata),
+            hasTransformer: columnMetadata?.options.transformer !== undefined,
+            isColumnArray: columnMetadata?.options.array === true,
+            isEnabled: true,
+            isNullable,
+            isSelected: columnMetadata?.options.select !== false,
+            isUnsigned: columnMetadata?.options.unsigned === true,
+            metadata: this.createPlanMetadata(metadata),
+            path,
+            ...(columnMetadata?.options.precision === undefined ? {} : { precision: columnMetadata.options.precision }),
+            ...(columnMetadata?.options.scale === undefined ? {} : { scale: columnMetadata.options.scale }),
+            type: metadata.type,
+        });
+    }
+    static createPlanMetadata(metadata) {
+        const planMetadata = "enum" in metadata ? { ...metadata, enum: Object.freeze({ ...metadata.enum }) } : { ...metadata };
+        return Object.freeze(planMetadata);
+    }
+    static findColumnMetadata(entity, entityName, propertyName) {
+        const targets = [];
+        if (typeof entity === "function") {
+            let current = entity;
+            while (typeof current === "function" && current !== Object) {
+                targets.push(current, current.name);
+                current = Object.getPrototypeOf(current);
+            }
+        }
+        else if (typeof entity.name === "string") {
+            targets.push(entity.name);
+        }
+        if (entityName && !targets.includes(entityName)) {
+            targets.push(entityName);
+        }
+        for (const expectedTarget of targets) {
+            const column = getMetadataArgsStorage().columns.find(({ propertyName: currentPropertyName, target }) => currentPropertyName === propertyName && (target === expectedTarget || (typeof expectedTarget === "string" && typeof target !== "string" && target.name === expectedTarget)));
+            if (column) {
+                return column;
+            }
+        }
+        return undefined;
+    }
     static getPropertyMetadata(column) {
         return column.metadata?.[PROPERTY_DESCRIBE_DECORATOR_API_CONSTANT.METADATA_KEY];
     }
-    static isColumnNullable(entityName, propertyName, metadata) {
-        const column = getMetadataArgsStorage().columns.find(({ propertyName: currentPropertyName, target }) => currentPropertyName === propertyName && (typeof target === "string" ? target === entityName : target.name === entityName));
+    static hasAfterLoadListener(entity) {
+        if (typeof entity !== "function") {
+            return false;
+        }
+        const targets = new Set();
+        let current = entity;
+        while (typeof current === "function" && current !== Object) {
+            targets.add(current);
+            current = Object.getPrototypeOf(current);
+        }
+        return getMetadataArgsStorage().entityListeners.some((listener) => listener.type === "after-load" && targets.has(listener.target));
+    }
+    static hasPropertyAccessor(entity, propertyName) {
+        if (typeof entity === "function") {
+            try {
+                const instance = Reflect.construct(entity, []);
+                const ownDescriptor = Object.getOwnPropertyDescriptor(instance, propertyName);
+                if (ownDescriptor && !("value" in ownDescriptor)) {
+                    return true;
+                }
+            }
+            catch {
+                return true;
+            }
+        }
+        let current = typeof entity === "function" ? Reflect.get(entity, "prototype") : undefined;
+        while (current && typeof current === "object" && current !== Object.prototype) {
+            const descriptor = Object.getOwnPropertyDescriptor(current, propertyName);
+            if (descriptor && !("value" in descriptor)) {
+                return true;
+            }
+            current = Object.getPrototypeOf(current);
+        }
+        return false;
+    }
+    static isColumnNullable(entity, entityName, propertyName, metadata, isCursor) {
+        const column = isCursor ? this.findColumnMetadata(entity, entityName, propertyName) : getMetadataArgsStorage().columns.find(({ propertyName: currentPropertyName, target }) => currentPropertyName === propertyName && (typeof target === "string" ? target === entityName : target.name === entityName));
         return column?.options.nullable === true || metadata.isNullable === true;
     }
+    static isCursorEnvelopeStringMetadata(metadata) {
+        if (metadata.decorator !== EManualDtoPropertyMetadataDecorator.STRING || !this.isManualRawResponseProperty(metadata, false, true)) {
+            return false;
+        }
+        return metadata.properties.format === EApiPropertyStringType.STRING && metadata.properties.minLength === 1 && metadata.properties.maxLength === API_CONTROLLER_CURSOR_TOKEN_MAX_LENGTH && metadata.properties.pattern === "/^[A-Za-z0-9_-]+$/";
+    }
     static isGloballyDisabled(metadata) {
         return metadata.properties?.[EApiRouteType.GET_LIST]?.[EApiDtoType.QUERY]?.isEnabled === false;
     }
+    static isManualRawResponseProperty(metadata, isArray, isNullable) {
+        const properties = metadata.properties;
+        const hasExpectedArrayShape = isArray ? properties.isArray === true : properties.isArray !== true;
+        const hasExpectedNullability = isNullable ? properties.isNullable === true : properties.isNullable !== true;
+        return hasExpectedArrayShape && hasExpectedNullability && properties.isRequired === true && properties.isResponse === true && properties.isExpose !== false;
+    }
     static isToOneRelation(column) {
         return column.type === "many-to-one" || column.type === "one-to-one";
     }
+    static isUnsafeCursorFieldName(fieldName) {
+        const numericName = Number(fieldName);
+        return UNSAFE_OBJECT_PROPERTY_NAMES_CONSTANT.has(fieldName) || (Number.isInteger(numericName) && numericName >= 0 && numericName <= CURSOR_MAXIMUM_ARRAY_INDEX_PROPERTY && String(numericName) === fieldName);
+    }
+    static normalizeColumnType(column) {
+        const columnType = column?.options.type;
+        if (columnType === Boolean) {
+            return "boolean-constructor";
+        }
+        if (columnType === Date) {
+            return "date-constructor";
+        }
+        if (columnType === Number) {
+            return "number-constructor";
+        }
+        if (columnType === String) {
+            return "string-constructor";
+        }
+        return typeof columnType === "string" ? columnType.trim().toLowerCase() : "unknown";
+    }
     static requireAllowedKeys(value, allowedKeys, context) {
         const invalidKey = Object.keys(value).find((key) => !allowedKeys.includes(key));
         if (invalidKey) {
@@ -301,8 +592,155 @@ class ApiControllerGetListQueryPlanCompiler {
         }
         return value;
     }
-    static sortRecord(record) {
-        return Object.fromEntries(Object.entries(record).toSorted(([left], [right]) => left.localeCompare(right)));
+    static sortRecord(record, isCursor) {
+        return Object.fromEntries(Object.entries(record).toSorted(([left], [right]) => this.compareStrings(left, right, isCursor)));
+    }
+    static validateCursorCustomResponseDto(routeConfig, fields, order) {
+        const responseDto = routeConfig.dto?.[EApiDtoType.RESPONSE];
+        if (!responseDto) {
+            return;
+        }
+        let itemType;
+        if (typeof responseDto === "function") {
+            const wrapperMetadata = GetManualDtoPropertyMetadata(Reflect.get(responseDto, "prototype"));
+            const itemsMetadata = wrapperMetadata.get("items");
+            const nextCursorMetadata = wrapperMetadata.get("nextCursor");
+            const previousCursorMetadata = wrapperMetadata.get("previousCursor");
+            if (wrapperMetadata.size !== CURSOR_RESPONSE_PROPERTY_COUNT ||
+                itemsMetadata?.decorator !== EManualDtoPropertyMetadataDecorator.OBJECT ||
+                nextCursorMetadata?.decorator !== EManualDtoPropertyMetadataDecorator.STRING ||
+                previousCursorMetadata?.decorator !== EManualDtoPropertyMetadataDecorator.STRING ||
+                !this.isManualRawResponseProperty(itemsMetadata, true, false) ||
+                Array.isArray(itemsMetadata.properties.type) ||
+                typeof itemsMetadata.properties.type !== "function" ||
+                itemsMetadata.properties.type === Object ||
+                !this.isCursorEnvelopeStringMetadata(nextCursorMetadata) ||
+                !this.isCursorEnvelopeStringMetadata(previousCursorMetadata) ||
+                this.hasPropertyAccessor(responseDto, "items") ||
+                this.hasPropertyAccessor(responseDto, "nextCursor") ||
+                this.hasPropertyAccessor(responseDto, "previousCursor")) {
+                throw ErrorException("CURSOR GET_LIST custom response DTO must prove the flat raw cursor envelope through Automator property metadata");
+            }
+            itemType = itemsMetadata.properties.type;
+        }
+        else if (typeof responseDto === "object" && "itemType" in responseDto && typeof responseDto.itemType === "function") {
+            itemType = responseDto.itemType;
+        }
+        if (!itemType) {
+            throw ErrorException("CURSOR GET_LIST custom response DTO must expose a statically provable item type");
+        }
+        this.validateCursorItemDto(itemType, fields, order);
+    }
+    static validateCursorItemDto(itemType, fields, order) {
+        const itemMetadata = GetManualDtoPropertyMetadata(Reflect.get(itemType, "prototype"));
+        for (const fieldName of fields) {
+            const field = order.serverFields[fieldName];
+            const metadata = itemMetadata.get(fieldName);
+            const expectedDecorator = field && field.type !== EApiPropertyDescribeType.OBJECT && field.type !== EApiPropertyDescribeType.RELATION ? field.type : undefined;
+            const expectedFormat = field && "format" in field.metadata ? field.metadata.format : undefined;
+            const actualFormat = metadata && "format" in metadata.properties ? metadata.properties.format : undefined;
+            if (!field || !metadata || metadata.decorator !== expectedDecorator || !this.isManualRawResponseProperty(metadata, false, false) || actualFormat !== expectedFormat || this.hasPropertyAccessor(itemType, fieldName)) {
+                throw ErrorException(`CURSOR GET_LIST custom item DTO must raw-expose protected field "${fieldName}" through compatible Automator property metadata`);
+            }
+        }
+    }
+    static validateCursorPlan(entity, entityMetadata, order, cursorFields, routeConfig) {
+        const primaryColumns = entityMetadata.columns.filter((column) => column.isPrimary);
+        if (primaryColumns.length !== 1) {
+            throw ErrorException("CURSOR GET_LIST requires exactly one primary column");
+        }
+        if (order.isLegacy) {
+            throw ErrorException("CURSOR GET_LIST requires explicit order configuration");
+        }
+        if (this.hasAfterLoadListener(entity)) {
+            throw ErrorException("CURSOR GET_LIST entity cannot declare TypeORM after-load listeners");
+        }
+        const primaryField = String(primaryColumns[0]?.name);
+        const tieBreakers = order.tieBreakers ?? [];
+        const finalTieBreaker = tieBreakers.at(-1);
+        if (finalTieBreaker?.field !== primaryField) {
+            throw ErrorException(`CURSOR GET_LIST requires the sole primary field "${primaryField}" as the final explicit tie-breaker`);
+        }
+        if ((order.defaultOrder ?? []).some((entry) => entry.field === primaryField) || tieBreakers.slice(0, -1).some((entry) => entry.field === primaryField) || order.fields[primaryField]?.isEnabled === true) {
+            throw ErrorException(`CURSOR GET_LIST primary field "${primaryField}" may appear only as the final tie-breaker`);
+        }
+        const potentialFields = new Set(cursorFields);
+        for (const fieldName of potentialFields) {
+            const field = order.serverFields[fieldName];
+            if (this.isUnsafeCursorFieldName(fieldName)) {
+                throw ErrorException(`CURSOR GET_LIST order field "${fieldName}" is not a safe stable object property name`);
+            }
+            if (!field || field.isNullable || ("isArray" in field.metadata && field.metadata.isArray === true)) {
+                throw ErrorException(`CURSOR GET_LIST order field "${fieldName}" must be a described non-null direct scalar field`);
+            }
+            this.validateCursorStorageField(field);
+            if (this.hasPropertyAccessor(entity, fieldName)) {
+                throw ErrorException(`CURSOR GET_LIST order field "${fieldName}" must be a raw data property, not an accessor`);
+            }
+            this.validateCursorResponseExposure(entityMetadata, fieldName);
+        }
+        this.validateCursorCustomResponseDto(routeConfig, potentialFields, order);
+    }
+    static validateCursorResponseExposure(entityMetadata, fieldName) {
+        const column = entityMetadata.columns.find((candidate) => String(candidate.name) === fieldName);
+        const metadata = column ? this.getPropertyMetadata(column) : undefined;
+        if (!column || !metadata) {
+            throw ErrorException(`CURSOR GET_LIST order field "${fieldName}" must be raw-exposed in the generated response`);
+        }
+        const effectiveResponse = DtoGetDecoratorConfig(EApiRouteType.GET_LIST, metadata, EApiDtoType.RESPONSE);
+        if (effectiveResponse.guard || !DtoIsPropertyShouldBeMarked(EApiRouteType.GET_LIST, EApiDtoType.RESPONSE, fieldName, metadata, column.isPrimary) || effectiveResponse.isEnabled === false || effectiveResponse.isResponse !== true || effectiveResponse.isExpose !== true) {
+            throw ErrorException(`CURSOR GET_LIST order field "${fieldName}" must be unconditionally raw-exposed in the generated response`);
+        }
+    }
+    static validateCursorStorageField(field) {
+        if (field.columnType === "unknown" || CURSOR_NON_PERSISTED_COLUMN_MODES.has(field.columnMode) || field.hasTransformer || field.isColumnArray || !field.isSelected) {
+            throw ErrorException(`CURSOR GET_LIST order field "${field.path}" must be a selected persisted column without a transformer`);
+        }
+        if (field.isUnsigned) {
+            throw ErrorException(`CURSOR GET_LIST order field "${field.path}" cannot use unsigned storage in PostgreSQL v1`);
+        }
+        if (field.type === EApiPropertyDescribeType.BOOLEAN) {
+            if (!CURSOR_BOOLEAN_COLUMN_TYPES.has(field.columnType)) {
+                throw ErrorException(`CURSOR GET_LIST boolean order field "${field.path}" requires PostgreSQL boolean storage`);
+            }
+            return;
+        }
+        if (field.type === EApiPropertyDescribeType.NUMBER) {
+            if (!("format" in field.metadata) || field.metadata.format !== EApiPropertyNumberType.INTEGER) {
+                throw ErrorException(`CURSOR GET_LIST numeric order field "${field.path}" supports only INTEGER metadata in PostgreSQL v1`);
+            }
+            if (!CURSOR_INTEGER_COLUMN_TYPES.has(field.columnType)) {
+                throw ErrorException(`CURSOR GET_LIST integer order field "${field.path}" requires signed PostgreSQL int2/int4 storage`);
+            }
+            return;
+        }
+        if (field.type === EApiPropertyDescribeType.STRING) {
+            const format = "format" in field.metadata ? field.metadata.format : undefined;
+            if (format !== EApiPropertyStringType.BIGINT_STRING) {
+                throw ErrorException(`CURSOR GET_LIST string order field "${field.path}" supports only BIGINT_STRING metadata in PostgreSQL v1`);
+            }
+            if (!CURSOR_BIGINT_COLUMN_TYPES.has(field.columnType)) {
+                throw ErrorException(`CURSOR GET_LIST bigint-string order field "${field.path}" requires signed PostgreSQL int8 storage`);
+            }
+            return;
+        }
+        if (field.type === EApiPropertyDescribeType.ENUM) {
+            const enumValues = ApiControllerGetListQueryEnumValues("enum" in field.metadata ? field.metadata.enum : {});
+            if (enumValues.length === 0 || !enumValues.every((value) => typeof value === "number" && Number.isSafeInteger(value))) {
+                throw ErrorException(`CURSOR GET_LIST enum order field "${field.path}" requires safe numeric values in PostgreSQL v1`);
+            }
+            if (!CURSOR_ENUM_INTEGER_COLUMN_TYPES.has(field.columnType)) {
+                throw ErrorException(`CURSOR GET_LIST enum order field "${field.path}" requires signed PostgreSQL int2/int4 storage`);
+            }
+            return;
+        }
+        if (field.type === EApiPropertyDescribeType.UUID) {
+            if (!CURSOR_UUID_COLUMN_TYPES.has(field.columnType)) {
+                throw ErrorException(`CURSOR GET_LIST UUID order field "${field.path}" requires native PostgreSQL UUID storage`);
+            }
+            return;
+        }
+        throw ErrorException(`CURSOR GET_LIST order field "${field.path}" is not supported by PostgreSQL CURSOR v1`);
     }
     static validateStaticValue(value, field) {
         let isValid;