adorn-api 1.1.12 → 1.1.13

package/README.md

@@ -639,6 +639,24 @@ export class UserController {
 
 The `listConfig` object contains: `filterMappings`, `sortableColumns`, `defaultSortBy`, `defaultSortDirection`, `defaultPageSize`, `maxPageSize`, `sortByKey`, and `sortDirectionKey`.
 
+### Type-Only Query Interfaces
+
+For consumer projects that need pure TypeScript interfaces (without creating extra DTO classes), Adorn exports:
+- `PaginationQueryParams`
+- `SortingQueryParams`
+- `PagedQueryParams`
+
+```typescript
+import type { PagedQueryParams } from "adorn-api";
+
+interface CaixaEntradaQueryDto extends PagedQueryParams {
+  usuarioId?: number;
+  lido?: boolean;
+}
+```
+
+`sortDirection` is the official typed sort field (`"asc" | "desc"`). `sortOrder` remains parser compatibility for legacy/external clients.
+
 ### `BaseService.list` Before/After (Boilerplate Reduction)
 
 Before:

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

@@ -11,4 +11,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, ParseSortOptions, ParsedSort, SortDirection, CrudListSortTerm, RunPagedListOptions, ExecuteCrudListOptions, CrudPagedResponse, ListConfig, PagedQueryDtoOptions, PagedResponseDtoOptions, PagedFilterQueryDtoOptions, FilterFieldDef, MetalCrudQueryFilterDef, MetalCrudSortableColumns, MetalCrudOptionsQueryOptions, MetalCrudQueryOptions, MetalCrudStandardErrorsOptions, MetalCrudDtoOptions, MetalCrudDtoClassOptions, MetalCrudDtoDecorators, MetalCrudDtoClasses, MetalCrudDtoClassNameKey, MetalCrudDtoClassNames, CrudControllerService, CrudControllerServiceInput, CreateCrudControllerOptions, RouteErrorsDecorator, NestedCreateDtoOptions, MetalTreeDtoClassOptions, MetalTreeDtoClasses, MetalTreeDtoClassNames, MetalTreeListEntryOptions, ErrorDtoOptions, CreateSessionFn } from "./types";
+export type { MetalDtoMode, MetalDtoOptions, MetalDtoTarget, PaginationConfig, PaginationOptions, ParsedPagination, PaginationQueryParams, Filter, FilterMapping, FilterFieldMapping, FilterFieldPath, FilterFieldPathArray, FilterFieldInput, RelationQuantifier, ParseFilterOptions, ParseSortOptions, ParsedSort, SortDirection, SortingQueryParams, PagedQueryParams, CrudListSortTerm, RunPagedListOptions, ExecuteCrudListOptions, CrudPagedResponse, ListConfig, PagedQueryDtoOptions, PagedResponseDtoOptions, PagedFilterQueryDtoOptions, FilterFieldDef, MetalCrudQueryFilterDef, MetalCrudSortableColumns, MetalCrudOptionsQueryOptions, MetalCrudQueryOptions, MetalCrudStandardErrorsOptions, MetalCrudDtoOptions, MetalCrudDtoClassOptions, MetalCrudDtoDecorators, MetalCrudDtoClasses, MetalCrudDtoClassNameKey, MetalCrudDtoClassNames, CrudControllerService, CrudControllerServiceInput, CreateCrudControllerOptions, RouteErrorsDecorator, NestedCreateDtoOptions, MetalTreeDtoClassOptions, MetalTreeDtoClasses, MetalTreeDtoClassNames, MetalTreeListEntryOptions, ErrorDtoOptions, CreateSessionFn } from "./types";

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

@@ -56,6 +56,15 @@ export interface ParsedPagination {
     /** Page size */
     pageSize: number;
 }
+/**
+ * Pagination query params for consumer-side TypeScript interfaces.
+ */
+export interface PaginationQueryParams {
+    /** Page number */
+    page?: number;
+    /** Page size */
+    pageSize?: number;
+}
 /**
  * Filter field mapping.
  */
@@ -108,6 +117,20 @@ export interface ParseFilterOptions<T = Record<string, unknown>> {
  * Sort direction.
  */
 export type SortDirection = "asc" | "desc";
+/**
+ * Sorting query params for consumer-side TypeScript interfaces.
+ */
+export interface SortingQueryParams {
+    /** Requested sort key */
+    sortBy?: string;
+    /** Sort direction */
+    sortDirection?: SortDirection;
+}
+/**
+ * Combined pagination + sorting query params.
+ */
+export interface PagedQueryParams extends PaginationQueryParams, SortingQueryParams {
+}
 /**
  * Sort parsing options.
  */

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "adorn-api",
-  "version": "1.1.12",
+  "version": "1.1.13",
   "description": "Decorator-first web framework with OpenAPI 3.1 schema generation.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "pretest": "npm run build",
     "dev": "tsx examples/basic/index.ts",
     "test": "vitest run",
     "test:watch": "vitest",
+    "typecheck:tests": "tsc -p tsconfig.typecheck.json --noEmit",
     "example": "node scripts/run-example.js",
     "check": "tsc -p tsconfig.json --noEmit && npm test",
     "lint": "eslint . --ext .ts,.tsx,.js"

package/src/adapter/metal-orm/index.ts

@@ -78,6 +78,7 @@ export type {
   PaginationConfig,
   PaginationOptions,
   ParsedPagination,
+  PaginationQueryParams,
   Filter,
   FilterMapping,
   FilterFieldMapping,
@@ -89,6 +90,8 @@ export type {
   ParseSortOptions,
   ParsedSort,
   SortDirection,
+  SortingQueryParams,
+  PagedQueryParams,
   CrudListSortTerm,
   RunPagedListOptions,
   ExecuteCrudListOptions,

package/src/adapter/metal-orm/types.ts

@@ -74,6 +74,16 @@ export interface ParsedPagination {
   pageSize: number;
 }
 
+/**
+ * Pagination query params for consumer-side TypeScript interfaces.
+ */
+export interface PaginationQueryParams {
+  /** Page number */
+  page?: number;
+  /** Page size */
+  pageSize?: number;
+}
+
 /**
  * Filter field mapping.
  */
@@ -155,6 +165,21 @@ export interface ParseFilterOptions<T = Record<string, unknown>> {
  */
 export type SortDirection = "asc" | "desc";
 
+/**
+ * Sorting query params for consumer-side TypeScript interfaces.
+ */
+export interface SortingQueryParams {
+  /** Requested sort key */
+  sortBy?: string;
+  /** Sort direction */
+  sortDirection?: SortDirection;
+}
+
+/**
+ * Combined pagination + sorting query params.
+ */
+export interface PagedQueryParams extends PaginationQueryParams, SortingQueryParams {}
+
 /**
  * Sort parsing options.
  */

package/tests/typecheck/query-params.typecheck.ts

@@ -0,0 +1,42 @@
+import type {
+  PagedQueryParams,
+  PaginationQueryParams,
+  SortDirection,
+  SortingQueryParams
+} from "../../src/index";
+
+type Assert<T extends true> = T;
+type IsEqual<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends
+    (<T>() => T extends B ? 1 : 2)
+    ? true
+    : false;
+
+type _SortDirectionMatchesPublicType = Assert<
+  IsEqual<SortingQueryParams["sortDirection"], SortDirection | undefined>
+>;
+
+const paginationOnly: PaginationQueryParams = {
+  page: 1,
+  pageSize: 25
+};
+
+const sortingOnly: SortingQueryParams = {
+  sortBy: "createdAt",
+  sortDirection: "desc"
+};
+
+const pagedWithSorting: PagedQueryParams = {
+  page: paginationOnly.page,
+  pageSize: paginationOnly.pageSize,
+  sortBy: sortingOnly.sortBy,
+  sortDirection: "asc"
+};
+
+// @ts-expect-error sortDirection accepts only "asc" | "desc"
+const invalidSorting: SortingQueryParams = { sortDirection: "ASC" };
+
+void paginationOnly;
+void sortingOnly;
+void pagedWithSorting;
+void invalidSorting;

package/tsconfig.typecheck.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts", "tests/typecheck/**/*.ts"]
+}

package/vitest.config.ts

@@ -1,14 +1,54 @@
+import path from "node:path";
+import fs from "node:fs";
+import * as ts from "typescript";
 import { defineConfig } from "vitest/config";
 
+function transpileSourcePlugin() {
+  return {
+    name: "transpile-source",
+    enforce: "pre",
+    load(id: string) {
+      const cleanId = id.split(/[?#]/)[0];
+      const normalizedId = cleanId.split(path.sep).join("/");
+      if (
+        !normalizedId.includes("/src/") &&
+        !normalizedId.includes("/examples/") &&
+        !normalizedId.includes("/tests/")
+      ) {
+        return undefined;
+      }
+      if (!normalizedId.endsWith(".ts") && !normalizedId.endsWith(".tsx")) {
+        return undefined;
+      }
+
+      const code = fs.readFileSync(cleanId, "utf8");
+      const result = ts.transpileModule(code, {
+        compilerOptions: {
+          target: ts.ScriptTarget.ES2022,
+          module: ts.ModuleKind.ESNext,
+          moduleResolution: ts.ModuleResolutionKind.Node,
+          experimentalDecorators: false,
+          emitDecoratorMetadata: false,
+          useDefineForClassFields: true,
+          esModuleInterop: true,
+          sourceMap: true
+        },
+        fileName: cleanId
+      });
+
+      return {
+        code: result.outputText,
+        map: result.sourceMapText ? JSON.parse(result.sourceMapText) : undefined
+      };
+    }
+  };
+}
+
 export default defineConfig({
+  plugins: [transpileSourcePlugin()],
   test: {
     environment: "node",
-    include: ["src/**/*.test.ts", "tests/**/*.test.ts"],
-    pool: "forks",
-    poolOptions: {
-      forks: {
-        singleFork: true
-      }
-    }
+    pool: "threads",
+    include: ["src/**/*.test.ts", "tests/**/*.test.ts"]
   }
 });