adorn-api 1.1.2 → 1.1.4

package/README.md

@@ -337,17 +337,49 @@ export class User {
 
 ```typescript
 // user.dtos.ts
-import { createMetalCrudDtoClasses } from "adorn-api";
+import { createMetalCrudDtoClasses, t } from "adorn-api";
 import { User } from "./user.entity";
 
 export const {
-  GetUserDto,
-  CreateUserDto,
-  UpdateUserDto,
-  ReplaceUserDto,
-  UserQueryDto,
-  UserPagedResponseDto
-} = createMetalCrudDtoClasses(User);
+  response: UserDto,
+  create: CreateUserDto,
+  replace: ReplaceUserDto,
+  update: UpdateUserDto,
+  params: UserParamsDto,
+  queryDto: UserQueryDto,
+  optionsQueryDto: UserOptionsQueryDto,
+  pagedResponseDto: UserPagedResponseDto,
+  optionDto: UserOptionDto,
+  optionsDto: UserOptionsDto,
+  errors: UserErrors,
+  filterMappings: USER_FILTER_MAPPINGS,
+  sortableColumns: USER_SORTABLE_COLUMNS
+} = createMetalCrudDtoClasses(User, {
+  mutationExclude: ["id", "createdAt"],
+  query: {
+    filters: {
+      nameContains: {
+        schema: t.string({ minLength: 1 }),
+        field: "name",
+        operator: "contains"
+      },
+      emailContains: {
+        schema: t.string({ minLength: 1 }),
+        field: "email",
+        operator: "contains"
+      }
+    },
+    sortableColumns: {
+      id: "id",
+      name: "name",
+      createdAt: "createdAt"
+    },
+    options: {
+      labelField: "name"
+    }
+  },
+  errors: true
+});
 ```
 
 ### 3. Create a CRUD Controller
@@ -365,19 +397,28 @@ import {
   Body,
   Query,
   Returns,
+  parseFilter,
   parsePagination,
+  parseSort,
+  t,
   type RequestContext
 } from "adorn-api";
 import { applyFilter, toPagedResponse } from "metal-orm";
 import { createSession } from "./db";
 import { User } from "./user.entity";
 import {
-  GetUserDto,
+  UserDto,
   CreateUserDto,
-  UpdateUserDto,
   ReplaceUserDto,
+  UpdateUserDto,
+  UserParamsDto,
   UserQueryDto,
-  UserPagedResponseDto
+  UserOptionsQueryDto,
+  UserPagedResponseDto,
+  UserOptionsDto,
+  UserErrors,
+  USER_FILTER_MAPPINGS,
+  USER_SORTABLE_COLUMNS
 } from "./user.dtos";
 
 @Controller("/users")
@@ -386,26 +427,52 @@ export class UserController {
   @Query(UserQueryDto)
   @Returns(UserPagedResponseDto)
   async list(ctx: RequestContext<unknown, UserQueryDto>) {
-    const { page, pageSize } = parsePagination(ctx.query);
+    const query = (ctx.query ?? {}) as Record<string, unknown>;
+    const { page, pageSize } = parsePagination(query);
+    const filters = parseFilter(query, USER_FILTER_MAPPINGS);
+    const sort = parseSort(query, USER_SORTABLE_COLUMNS, {
+      defaultSortBy: "id"
+    });
+    const direction = sort?.sortDirection === "desc" ? "DESC" : "ASC";
     const session = createSession();
     
     try {
-      const query = applyFilter(
-        User.select().orderBy(User.id, "ASC"),
+      const ormQuery = applyFilter(
+        User.select().orderBy(User.id, direction),
         User,
-        ctx.query
+        filters
       );
       
-      const paged = await query.executePaged(session, { page, pageSize });
+      const paged = await ormQuery.executePaged(session, { page, pageSize });
       return toPagedResponse(paged);
     } finally {
       await session.dispose();
     }
   }
 
+  @Get("/options")
+  @Query(UserOptionsQueryDto)
+  @Returns(UserOptionsDto)
+  async options(ctx: RequestContext<unknown, UserOptionsQueryDto>) {
+    const query = (ctx.query ?? {}) as Record<string, unknown>;
+    const { page, pageSize } = parsePagination(query);
+    const filters = parseFilter(query, USER_FILTER_MAPPINGS);
+    // run your options query using the same mappings + generated DTOs
+    return {
+      items: [],
+      totalItems: 0,
+      page,
+      pageSize,
+      totalPages: 1,
+      hasNextPage: false,
+      hasPrevPage: false
+    };
+  }
+
   @Get("/:id")
   @Params({ id: t.integer() })
-  @Returns(GetUserDto)
+  @Returns(UserDto)
+  @UserErrors
   async getOne(ctx: RequestContext<unknown, undefined, { id: string }>) {
     const session = createSession();
     
@@ -421,6 +488,48 @@ export class UserController {
 }
 ```
 
+### Migration Guide (Breaking)
+
+Before (duplicated config):
+
+```typescript
+const UserQueryDto = createPagedFilterQueryDtoClass({
+  filters: {
+    nameContains: { schema: t.string(), operator: "contains" }
+  }
+});
+
+const USER_FILTER_MAPPINGS = {
+  nameContains: { field: "name", operator: "contains" as const }
+};
+```
+
+After (single source of truth):
+
+```typescript
+const {
+  queryDto: UserQueryDto,
+  filterMappings: USER_FILTER_MAPPINGS
+} = createMetalCrudDtoClasses(User, {
+  query: {
+    filters: {
+      nameContains: {
+        schema: t.string({ minLength: 1 }),
+        field: "name",
+        operator: "contains"
+      }
+    }
+  }
+});
+```
+
+Breaking changes summary:
+- `createMetalCrudDtoClasses` now generates query/options/paged/error artifacts directly.
+- Query filter definitions now include schema + operator + field mapping in one `query.filters` block.
+- Sort allowlist now lives in `query.sortableColumns` and feeds both DTO schemas and runtime metadata.
+- Generated outputs now include `queryDto`, `optionsQueryDto`, `pagedResponseDto`, `optionDto`, `optionsDto`, `errors`, `filterMappings`, and `sortableColumns`.
+- Consumers no longer need internal `dist/...` imports for query/filter metadata types; all relevant types/utilities are publicly exported from `adorn-api`.
+
 ### Deep Relation Filters
 
 `parseFilter` now accepts nested relation paths, so you can filter deep chains like Alpha → Bravo → Charlie → Delta. If

package/dist/adapter/metal-orm/crud-dtos.d.ts

@@ -1,5 +1,6 @@
+import type { FieldOverride } from "../../core/decorators";
 import type { DtoConstructor } from "../../core/types";
-import type { MetalCrudDtoOptions, MetalCrudDtoClassOptions, MetalCrudDtoDecorators, MetalCrudDtoClasses, NestedCreateDtoOptions } from "./types";
-export declare function createMetalCrudDtos(target: any, options?: MetalCrudDtoOptions): MetalCrudDtoDecorators;
-export declare function createMetalCrudDtoClasses(target: any, options?: MetalCrudDtoClassOptions): MetalCrudDtoClasses;
-export declare function createNestedCreateDtoClass(target: any, overrides: Record<string, any>, options: NestedCreateDtoOptions): DtoConstructor;
+import type { MetalCrudDtoClassOptions, MetalCrudDtoClasses, MetalCrudDtoDecorators, MetalCrudDtoOptions, MetalDtoTarget, NestedCreateDtoOptions } from "./types";
+export declare function createMetalCrudDtos<TEntity extends Record<string, unknown>>(target: MetalDtoTarget, options?: MetalCrudDtoOptions<TEntity>): MetalCrudDtoDecorators;
+export declare function createMetalCrudDtoClasses<TEntity extends Record<string, unknown>>(target: MetalDtoTarget, options?: MetalCrudDtoClassOptions<TEntity>): MetalCrudDtoClasses<TEntity>;
+export declare function createNestedCreateDtoClass(target: MetalDtoTarget, overrides: Record<string, FieldOverride>, options: NestedCreateDtoOptions): DtoConstructor;

package/dist/adapter/metal-orm/crud-dtos.js

@@ -37,7 +37,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMetalCrudDtos = createMetalCrudDtos;
 exports.createMetalCrudDtoClasses = createMetalCrudDtoClasses;
 exports.createNestedCreateDtoClass = createNestedCreateDtoClass;
+const decorators_1 = require("../../core/decorators");
+const metadata_1 = require("../../core/metadata");
+const schema_1 = require("../../core/schema");
 const dto_1 = require("./dto");
+const error_dtos_1 = require("./error-dtos");
+const paged_dtos_1 = require("./paged-dtos");
 function createMetalCrudDtos(target, options = {}) {
     const mutationExclude = options.mutationExclude;
     const immutable = options.immutable;
@@ -69,7 +74,7 @@ function createMetalCrudDtos(target, options = {}) {
     };
 }
 function createMetalCrudDtoClasses(target, options = {}) {
-    const { baseName, names, ...crudOptions } = options;
+    const { baseName, names, query, errors: errorOptions, ...crudOptions } = options;
     const decorators = createMetalCrudDtos(target, crudOptions);
     const entityName = baseName ?? getTargetName(target);
     const defaultNames = {
@@ -77,14 +82,100 @@ function createMetalCrudDtoClasses(target, options = {}) {
         create: `Create${entityName}Dto`,
         replace: `Replace${entityName}Dto`,
         update: `Update${entityName}Dto`,
-        params: `${entityName}ParamsDto`
+        params: `${entityName}ParamsDto`,
+        queryDto: `${entityName}QueryDto`,
+        optionsQueryDto: `${entityName}OptionsQueryDto`,
+        pagedResponseDto: `${entityName}PagedResponseDto`,
+        optionDto: `${entityName}OptionDto`,
+        optionsDto: `${entityName}OptionsDto`
     };
-    const classes = {};
+    const crudClasses = {};
     for (const key of Object.keys(decorators)) {
         const name = names?.[key] ?? defaultNames[key];
-        classes[key] = buildDtoClass(name, decorators[key]);
+        crudClasses[key] = buildDtoClass(name, decorators[key]);
     }
-    return classes;
+    const strict = options.strict ?? false;
+    const queryOptions = query ?? {};
+    const sortByKey = queryOptions.sortByKey ?? "sortBy";
+    const sortDirectionKey = queryOptions.sortDirectionKey ?? "sortDirection";
+    const defaultPageSize = queryOptions.defaultPageSize ?? 25;
+    const maxPageSize = queryOptions.maxPageSize ?? 100;
+    const filters = queryOptions.filters ?? {};
+    const sortableColumns = cloneSortableColumns(queryOptions.sortableColumns ?? {});
+    const filterMappings = buildFilterMappings(filters);
+    const optionsQueryConfig = queryOptions.options ?? {};
+    const optionsEnabled = optionsQueryConfig.enabled ?? true;
+    const optionsSearchKey = optionsQueryConfig.searchKey ?? "search";
+    const optionsLabelField = (optionsQueryConfig.labelField ?? "nome");
+    const optionsValueField = (optionsQueryConfig.valueField ?? "id");
+    const optionsSearchOperator = optionsQueryConfig.searchOperator ?? "contains";
+    const optionsDefaultPageSize = optionsQueryConfig.defaultPageSize ?? defaultPageSize;
+    const optionsMaxPageSize = optionsQueryConfig.maxPageSize ?? maxPageSize;
+    if (optionsEnabled && !(optionsSearchKey in filterMappings)) {
+        filterMappings[optionsSearchKey] = {
+            field: optionsLabelField,
+            operator: optionsSearchOperator
+        };
+    }
+    const queryDtoName = names?.queryDto ?? defaultNames.queryDto;
+    const optionsQueryDtoName = names?.optionsQueryDto ?? defaultNames.optionsQueryDto;
+    const pagedResponseDtoName = names?.pagedResponseDto ?? defaultNames.pagedResponseDto;
+    const optionDtoName = names?.optionDto ?? defaultNames.optionDto;
+    const optionsDtoName = names?.optionsDto ?? defaultNames.optionsDto;
+    const queryDto = createQueryDtoClass({
+        name: queryDtoName,
+        filters,
+        sortableColumns,
+        sortByKey,
+        sortDirectionKey,
+        defaultSortBy: queryOptions.defaultSortBy,
+        defaultSortDirection: queryOptions.defaultSortDirection ?? "asc",
+        defaultPageSize,
+        maxPageSize
+    });
+    const optionsQueryDto = createOptionsQueryDtoClass({
+        name: optionsQueryDtoName,
+        filters,
+        sortableColumns,
+        sortByKey,
+        sortDirectionKey,
+        defaultSortBy: queryOptions.defaultSortBy,
+        defaultSortDirection: queryOptions.defaultSortDirection ?? "asc",
+        defaultPageSize: optionsDefaultPageSize,
+        maxPageSize: optionsMaxPageSize,
+        searchKey: optionsEnabled ? optionsSearchKey : undefined
+    });
+    const optionDto = buildDtoClass(optionDtoName, (0, dto_1.MetalDto)(target, {
+        include: Array.from(new Set([optionsValueField, optionsLabelField])),
+        strict
+    }));
+    const responseDto = crudClasses.response;
+    const pagedResponseDto = (0, paged_dtos_1.createPagedResponseDtoClass)({
+        name: pagedResponseDtoName,
+        itemDto: responseDto,
+        description: `Paged ${entityName} response.`
+    });
+    const optionsDto = (0, paged_dtos_1.createPagedResponseDtoClass)({
+        name: optionsDtoName,
+        itemDto: optionDto,
+        description: `${entityName} options response.`
+    });
+    const errors = buildStandardCrudErrors(entityName, errorOptions);
+    return {
+        response: crudClasses.response,
+        create: crudClasses.create,
+        replace: crudClasses.replace,
+        update: crudClasses.update,
+        params: crudClasses.params,
+        queryDto,
+        optionsQueryDto,
+        pagedResponseDto,
+        optionDto,
+        optionsDto,
+        errors,
+        filterMappings,
+        sortableColumns
+    };
 }
 function createNestedCreateDtoClass(target, overrides, options) {
     const { additionalExclude, name, parentEntity: _parentEntity, ...metalDtoOptions } = options;
@@ -114,6 +205,108 @@ function createNestedCreateDtoClass(target, overrides, options) {
     Object.defineProperty(NestedCreateDto, "name", { value: name, configurable: true });
     return NestedCreateDto;
 }
+function createQueryDtoClass(options) {
+    const fields = buildQueryFields(options);
+    return createRegisteredDtoClass(options.name, fields);
+}
+function createOptionsQueryDtoClass(options) {
+    const fields = buildQueryFields(options);
+    if (options.searchKey) {
+        fields[options.searchKey] = {
+            schema: schema_1.t.optional(schema_1.t.string({ minLength: 1 })),
+            optional: true
+        };
+    }
+    return createRegisteredDtoClass(options.name, fields);
+}
+function buildQueryFields(options) {
+    const fields = {
+        page: {
+            schema: schema_1.t.optional(schema_1.t.integer({ minimum: 1, default: 1 })),
+            optional: true
+        },
+        pageSize: {
+            schema: schema_1.t.optional(schema_1.t.integer({
+                minimum: 1,
+                maximum: options.maxPageSize,
+                default: options.defaultPageSize
+            })),
+            optional: true
+        }
+    };
+    for (const [queryKey, def] of Object.entries(options.filters)) {
+        fields[queryKey] = { schema: schema_1.t.optional(def.schema), optional: true };
+    }
+    const sortableKeys = Object.keys(options.sortableColumns);
+    if (sortableKeys.length > 0) {
+        const sortByOptions = options.defaultSortBy
+            ? { default: options.defaultSortBy }
+            : {};
+        fields[options.sortByKey] = {
+            schema: schema_1.t.optional(schema_1.t.enum(sortableKeys, sortByOptions)),
+            optional: true
+        };
+        fields[options.sortDirectionKey] = {
+            schema: schema_1.t.optional(schema_1.t.enum(["asc", "desc"], { default: options.defaultSortDirection })),
+            optional: true
+        };
+    }
+    return fields;
+}
+function createRegisteredDtoClass(name, fields) {
+    const DtoClass = class {
+    };
+    Object.defineProperty(DtoClass, "name", { value: name, configurable: true });
+    (0, metadata_1.registerDto)(DtoClass, { name, fields });
+    return DtoClass;
+}
+function buildFilterMappings(filters) {
+    const mappings = {};
+    for (const [queryKey, def] of Object.entries(filters)) {
+        mappings[queryKey] = {
+            field: def.field,
+            operator: def.operator ?? "equals"
+        };
+    }
+    return mappings;
+}
+function cloneSortableColumns(sortableColumns) {
+    return Object.fromEntries(Object.entries(sortableColumns).map(([key, value]) => [key, value]));
+}
+function buildStandardCrudErrors(entityName, options) {
+    if (!options) {
+        return undefined;
+    }
+    const config = typeof options === "boolean" ? {} : options;
+    if (config.enabled === false) {
+        return undefined;
+    }
+    const responses = [];
+    const invalidId = config.invalidId;
+    const notFound = config.notFound;
+    if (invalidId !== false) {
+        responses.push({
+            status: 400,
+            description: invalidId?.description ?? `Invalid ${entityName} id.`,
+            contentType: invalidId?.contentType
+        });
+    }
+    if (notFound !== false) {
+        responses.push({
+            status: 404,
+            description: notFound?.description ?? `${entityName} not found.`,
+            contentType: notFound?.contentType
+        });
+    }
+    if (!responses.length) {
+        return undefined;
+    }
+    const schema = config.schema ?? (0, error_dtos_1.createErrorDtoClass)({
+        withDetails: config.withDetails ?? false,
+        includeTraceId: config.includeTraceId ?? true
+    });
+    return (0, decorators_1.Errors)(schema, responses);
+}
 function buildDtoClass(name, decorator) {
     const DtoClass = class {
     };
@@ -144,7 +337,7 @@ function mergeStringArrays(...entries) {
 }
 function buildCrudOptions(base, overrides, extra = {}) {
     const mergedOverrides = mergeOverrides(overrides, base?.overrides);
-    const output = { ...base, ...extra };
+    const output = { ...(base ?? {}), ...extra };
     if (mergedOverrides) {
         output.overrides = mergedOverrides;
     }

package/dist/adapter/metal-orm/filters.d.ts

@@ -5,7 +5,7 @@ import type { Filter, FilterFieldInput, FilterMapping, FilterOperator, ParseFilt
  * @param mappings - Filter field mappings
  * @returns Parsed filter or undefined
  */
-export declare function parseFilter<T, K extends keyof T>(query: Record<string, unknown> | undefined, mappings: Record<string, FilterMapping<T>>): Filter<T, K> | undefined;
+export declare function parseFilter<T, K extends keyof T>(query: object | undefined, mappings: Record<string, FilterMapping<T>>): Filter<T, K> | undefined;
 export declare function parseFilter<T, K extends keyof T>(options: ParseFilterOptions<T>): Filter<T, K> | undefined;
 /**
  * Creates filter mappings for an entity.

package/dist/adapter/metal-orm/index.d.ts

@@ -1,6 +1,7 @@
 export { MetalDto } from "./dto";
 export { parsePagination } from "./pagination";
 export { parseFilter, createFilterMappings } from "./filters";
+export { parseSort } from "./sort";
 export { createPagedQueryDtoClass, createPagedResponseDtoClass, createPagedFilterQueryDtoClass } from "./paged-dtos";
 export { createMetalCrudDtos, createMetalCrudDtoClasses, createNestedCreateDtoClass } from "./crud-dtos";
 export { createMetalTreeDtoClasses } from "./tree-dtos";
@@ -8,4 +9,4 @@ export { createMetalDtoOverrides, type CreateMetalDtoOverridesOptions } from "./
 export { createErrorDtoClass, StandardErrorDto, SimpleErrorDto, BasicErrorDto } from "./error-dtos";
 export { withSession, parseIdOrThrow, compactUpdates, applyInput, getEntityOrThrow } from "./utils";
 export { validateEntityMetadata, hasValidEntityMetadata } from "./field-builder";
-export type { MetalDtoMode, MetalDtoOptions, MetalDtoTarget, PaginationConfig, PaginationOptions, ParsedPagination, Filter, FilterMapping, FilterFieldMapping, FilterFieldPath, FilterFieldPathArray, FilterFieldInput, RelationQuantifier, ParseFilterOptions, PagedQueryDtoOptions, PagedResponseDtoOptions, PagedFilterQueryDtoOptions, FilterFieldDef, MetalCrudDtoOptions, MetalCrudDtoClassOptions, MetalCrudDtoDecorators, MetalCrudDtoClasses, MetalCrudDtoClassNames, NestedCreateDtoOptions, MetalTreeDtoClassOptions, MetalTreeDtoClasses, MetalTreeDtoClassNames, MetalTreeListEntryOptions, ErrorDtoOptions, CreateSessionFn } from "./types";
+export type { MetalDtoMode, MetalDtoOptions, MetalDtoTarget, PaginationConfig, PaginationOptions, ParsedPagination, Filter, FilterMapping, FilterFieldMapping, FilterFieldPath, FilterFieldPathArray, FilterFieldInput, RelationQuantifier, ParseFilterOptions, ParseSortOptions, ParsedSort, SortDirection, PagedQueryDtoOptions, PagedResponseDtoOptions, PagedFilterQueryDtoOptions, FilterFieldDef, MetalCrudQueryFilterDef, MetalCrudSortableColumns, MetalCrudOptionsQueryOptions, MetalCrudQueryOptions, MetalCrudStandardErrorsOptions, MetalCrudDtoOptions, MetalCrudDtoClassOptions, MetalCrudDtoDecorators, MetalCrudDtoClasses, MetalCrudDtoClassNameKey, MetalCrudDtoClassNames, RouteErrorsDecorator, NestedCreateDtoOptions, MetalTreeDtoClassOptions, MetalTreeDtoClasses, MetalTreeDtoClassNames, MetalTreeListEntryOptions, ErrorDtoOptions, CreateSessionFn } from "./types";

package/dist/adapter/metal-orm/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasValidEntityMetadata = exports.validateEntityMetadata = exports.getEntityOrThrow = exports.applyInput = exports.compactUpdates = exports.parseIdOrThrow = exports.withSession = exports.BasicErrorDto = exports.SimpleErrorDto = exports.StandardErrorDto = exports.createErrorDtoClass = exports.createMetalDtoOverrides = exports.createMetalTreeDtoClasses = exports.createNestedCreateDtoClass = exports.createMetalCrudDtoClasses = exports.createMetalCrudDtos = exports.createPagedFilterQueryDtoClass = exports.createPagedResponseDtoClass = exports.createPagedQueryDtoClass = exports.createFilterMappings = exports.parseFilter = exports.parsePagination = exports.MetalDto = void 0;
+exports.hasValidEntityMetadata = exports.validateEntityMetadata = exports.getEntityOrThrow = exports.applyInput = exports.compactUpdates = exports.parseIdOrThrow = exports.withSession = exports.BasicErrorDto = exports.SimpleErrorDto = exports.StandardErrorDto = exports.createErrorDtoClass = exports.createMetalDtoOverrides = exports.createMetalTreeDtoClasses = exports.createNestedCreateDtoClass = exports.createMetalCrudDtoClasses = exports.createMetalCrudDtos = exports.createPagedFilterQueryDtoClass = exports.createPagedResponseDtoClass = exports.createPagedQueryDtoClass = exports.parseSort = exports.createFilterMappings = exports.parseFilter = exports.parsePagination = exports.MetalDto = void 0;
 // Ensure standard decorator metadata is available for metal-orm transformers.
 const symbolMetadata = Symbol.metadata;
 if (!symbolMetadata) {
@@ -13,6 +13,8 @@ Object.defineProperty(exports, "parsePagination", { enumerable: true, get: funct
 var filters_1 = require("./filters");
 Object.defineProperty(exports, "parseFilter", { enumerable: true, get: function () { return filters_1.parseFilter; } });
 Object.defineProperty(exports, "createFilterMappings", { enumerable: true, get: function () { return filters_1.createFilterMappings; } });
+var sort_1 = require("./sort");
+Object.defineProperty(exports, "parseSort", { enumerable: true, get: function () { return sort_1.parseSort; } });
 var paged_dtos_1 = require("./paged-dtos");
 Object.defineProperty(exports, "createPagedQueryDtoClass", { enumerable: true, get: function () { return paged_dtos_1.createPagedQueryDtoClass; } });
 Object.defineProperty(exports, "createPagedResponseDtoClass", { enumerable: true, get: function () { return paged_dtos_1.createPagedResponseDtoClass; } });

package/dist/adapter/metal-orm/pagination.d.ts

@@ -5,4 +5,4 @@ import type { PaginationConfig, ParsedPagination } from "./types";
  * @param config - Pagination configuration
  * @returns Parsed pagination result
  */
-export declare function parsePagination(query: Record<string, unknown>, config?: PaginationConfig): ParsedPagination;
+export declare function parsePagination(query: object, config?: PaginationConfig): ParsedPagination;

package/dist/adapter/metal-orm/pagination.js

@@ -10,11 +10,12 @@ const coerce_1 = require("../../core/coerce");
  */
 function parsePagination(query, config = {}) {
     const { defaultPageSize = 25, maxPageSize = 100 } = config;
-    const page = coerce_1.coerce.integer(query.page, {
+    const q = query;
+    const page = coerce_1.coerce.integer(q.page, {
         min: 1,
         clamp: true
     }) ?? 1;
-    const pageSize = coerce_1.coerce.integer(query.pageSize, {
+    const pageSize = coerce_1.coerce.integer(q.pageSize, {
         min: 1,
         max: maxPageSize,
         clamp: true

package/dist/adapter/metal-orm/sort.d.ts

@@ -0,0 +1,7 @@
+import type { FilterFieldInput, ParseSortOptions, ParsedSort } from "./types";
+/**
+ * Parses sort parameters from query params using an allowed sortable column map.
+ * Returns undefined when no valid sort column is selected.
+ */
+export declare function parseSort<T>(query: Record<string, unknown> | undefined, sortableColumns: Record<string, FilterFieldInput<T>>, options?: Omit<ParseSortOptions<T>, "query" | "sortableColumns">): ParsedSort<T> | undefined;
+export declare function parseSort<T>(options: ParseSortOptions<T>): ParsedSort<T> | undefined;

package/dist/adapter/metal-orm/sort.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSort = parseSort;
+function parseSort(queryOrOptions, sortableColumns, options) {
+    const resolved = sortableColumns
+        ? {
+            query: queryOrOptions,
+            sortableColumns,
+            ...(options ?? {})
+        }
+        : queryOrOptions;
+    const query = resolved?.query;
+    const allowed = resolved?.sortableColumns;
+    if (!query || !allowed || Object.keys(allowed).length === 0) {
+        return undefined;
+    }
+    const sortByKey = resolved.sortByKey ?? "sortBy";
+    const sortDirectionKey = resolved.sortDirectionKey ?? "sortDirection";
+    const defaultSortBy = resolved.defaultSortBy;
+    const defaultDirection = resolved.defaultSortDirection ?? "asc";
+    const requestedSortBy = toTrimmedString(query[sortByKey]);
+    const selectedSortBy = selectSortBy(requestedSortBy, defaultSortBy, allowed);
+    if (!selectedSortBy) {
+        return undefined;
+    }
+    const requestedDirection = toTrimmedString(query[sortDirectionKey]);
+    const sortDirection = normalizeDirection(requestedDirection, defaultDirection);
+    return {
+        sortBy: selectedSortBy,
+        sortDirection,
+        field: allowed[selectedSortBy]
+    };
+}
+function toTrimmedString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function selectSortBy(requestedSortBy, defaultSortBy, allowed) {
+    if (requestedSortBy && requestedSortBy in allowed) {
+        return requestedSortBy;
+    }
+    if (defaultSortBy && defaultSortBy in allowed) {
+        return defaultSortBy;
+    }
+    return undefined;
+}
+function normalizeDirection(raw, fallback) {
+    if (raw === "desc") {
+        return "desc";
+    }
+    if (raw === "asc") {
+        return "asc";
+    }
+    return fallback;
+}