adorn-api 1.1.5 → 1.1.7

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

@@ -1,8 +1,19 @@
 
-import type { BelongsToReference, HasManyCollection, HasOneReference, ManyToManyCollection } from "metal-orm";
+import type {
+  BelongsToReference,
+  ColumnDef,
+  HasManyCollection,
+  HasOneReference,
+  ManyToManyCollection,
+  OrmSession,
+  PagedResponse,
+  SelectQueryBuilder,
+  TableDef
+} from "metal-orm";
 import type { DtoOptions, ErrorResponseOptions, FieldOverride } from "../../core/decorators";
 import type { SchemaNode } from "../../core/schema";
 import type { DtoConstructor } from "../../core/types";
+import type { RequestContext } from "../express/types";
 
 /**
  * Metal ORM DTO modes.
@@ -176,6 +187,11 @@ export interface ParsedSort<T = Record<string, unknown>> {
   field?: FilterFieldInput<T>;
 }
 
+/**
+ * Sort terms accepted by metal-orm execution helpers.
+ */
+export type CrudListSortTerm = ColumnDef | Record<string, unknown>;
+
 /**
  * Ready-to-use list/query configuration extracted from CRUD DTO class generation.
  * Eliminates the need for consumers to reassemble filter/sort/pagination config
@@ -200,6 +216,58 @@ export interface ListConfig<T = Record<string, unknown>> {
   sortDirectionKey: string;
 }
 
+/**
+ * Unified paged list execution options for metal-orm adapter.
+ */
+export interface RunPagedListOptions<
+  TResult,
+  TTable extends TableDef = TableDef,
+  TTarget = unknown,
+  TFilterTarget = Record<string, unknown>
+> extends PaginationConfig {
+  /** Raw request query */
+  query?: Record<string, unknown>;
+  /** Entity class or table used by applyFilter */
+  target: TTarget;
+  /** Base query builder or factory to create one */
+  qb: SelectQueryBuilder<TResult, TTable> | (() => SelectQueryBuilder<TResult, TTable>);
+  /** Active ORM session */
+  session: OrmSession;
+  /** Query key -> filter mapping */
+  filterMappings: Record<string, FilterMapping<TFilterTarget>>;
+  /** Query key -> field path mapping used by parseSort */
+  sortableColumns: Record<string, FilterFieldInput<TFilterTarget>>;
+  /** Optional explicit metal-orm sortable terms, overrides inferred table columns */
+  allowedSortColumns?: Record<string, CrudListSortTerm>;
+  /** Default sort field key */
+  defaultSortBy?: string;
+  /** Default sort direction */
+  defaultSortDirection?: SortDirection;
+  /** Sort field query key */
+  sortByKey?: string;
+  /** Sort direction query key */
+  sortDirectionKey?: string;
+  /** Legacy sort order query key (e.g. sortOrder=DESC) */
+  sortOrderKey?: string;
+  /** Optional stable tie-breaker column name */
+  tieBreakerColumn?: string;
+}
+
+/**
+ * Alias for runPagedList options.
+ */
+export type ExecuteCrudListOptions<
+  TResult,
+  TTable extends TableDef = TableDef,
+  TTarget = unknown,
+  TFilterTarget = Record<string, unknown>
+> = RunPagedListOptions<TResult, TTable, TTarget, TFilterTarget>;
+
+/**
+ * Alias for runPagedList response.
+ */
+export type CrudPagedResponse<TResult> = PagedResponse<TResult>;
+
 /**
  * Filter operator.
  */
@@ -475,6 +543,86 @@ export interface MetalCrudDtoClasses<T = Record<string, unknown>> {
   listConfig: ListConfig<T>;
 }
 
+/**
+ * Awaitable helper for CRUD service methods.
+ */
+export type Awaitable<T> = T | Promise<T>;
+
+/**
+ * Input for CRUD controller service: class or ready instance.
+ */
+export type CrudControllerServiceInput<TDtos extends MetalCrudDtoClasses<any>> =
+  CrudControllerService<TDtos>
+  | (new () => CrudControllerService<TDtos>);
+
+/**
+ * CRUD controller service contract used by createCrudController.
+ */
+export interface CrudControllerService<TDtos extends MetalCrudDtoClasses<any>> {
+  list(
+    ctx: RequestContext<unknown, InstanceType<TDtos["queryDto"]>>
+  ): Awaitable<InstanceType<TDtos["pagedResponseDto"]>>;
+  options?(
+    ctx: RequestContext<unknown, InstanceType<TDtos["optionsQueryDto"]>>
+  ): Awaitable<InstanceType<TDtos["optionsDto"]>>;
+  getById(
+    id: number,
+    ctx: RequestContext<unknown, undefined, InstanceType<TDtos["params"]>>
+  ): Awaitable<InstanceType<TDtos["response"]>>;
+  create(
+    body: InstanceType<TDtos["create"]>,
+    ctx: RequestContext<InstanceType<TDtos["create"]>>
+  ): Awaitable<InstanceType<TDtos["response"]>>;
+  replace?(
+    id: number,
+    body: InstanceType<TDtos["replace"]>,
+    ctx: RequestContext<
+      InstanceType<TDtos["replace"]>,
+      undefined,
+      InstanceType<TDtos["params"]>
+    >
+  ): Awaitable<InstanceType<TDtos["response"]>>;
+  update?(
+    id: number,
+    body: InstanceType<TDtos["update"]>,
+    ctx: RequestContext<
+      InstanceType<TDtos["update"]>,
+      undefined,
+      InstanceType<TDtos["params"]>
+    >
+  ): Awaitable<InstanceType<TDtos["response"]>>;
+  delete?(
+    id: number,
+    ctx: RequestContext<unknown, undefined, InstanceType<TDtos["params"]>>
+  ): Awaitable<void>;
+}
+
+/**
+ * createCrudController options.
+ */
+export interface CreateCrudControllerOptions<
+  TDtos extends MetalCrudDtoClasses<any>
+> {
+  /** Controller path. */
+  path: string;
+  /** Service instance or class (new () => service). */
+  service: CrudControllerServiceInput<TDtos>;
+  /** DTO bundle produced by createMetalCrudDtoClasses. */
+  dtos: TDtos;
+  /** Entity label used by parseIdOrThrow messages. */
+  entityName: string;
+  /** Generate GET /options route (default: true). */
+  withOptionsRoute?: boolean;
+  /** Generate PUT /:id route (default: true). */
+  withReplace?: boolean;
+  /** Generate PATCH /:id route (default: true). */
+  withPatch?: boolean;
+  /** Generate DELETE /:id route (default: true). */
+  withDelete?: boolean;
+  /** Optional OpenAPI tags for generated controller. */
+  tags?: string[];
+}
+
 /**
  * Metal Tree DTO class names.
  */

package/tests/metal-orm-integration/run-paged-list.test.ts

@@ -0,0 +1,169 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import sqlite3 from "sqlite3";
+import {
+  Orm,
+  SqliteDialect,
+  col,
+  createSqliteExecutor,
+  defineTable,
+  selectFrom,
+  type SqliteClientLike
+} from "metal-orm";
+import { runPagedList } from "../../src/adapter/metal-orm/list";
+
+const users = defineTable("users", {
+  id: col.primaryKey(col.autoIncrement(col.int())),
+  name: col.notNull(col.text()),
+  email: col.notNull(col.text())
+});
+
+let db: sqlite3.Database | null = null;
+let orm: Orm | null = null;
+
+function createSqliteClient(database: sqlite3.Database): SqliteClientLike {
+  return {
+    all(sql, params = []) {
+      return new Promise((resolve, reject) => {
+        database.all(sql, params, (err, rows) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve(rows as Record<string, unknown>[]);
+        });
+      });
+    }
+  };
+}
+
+function execSql(sql: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (!db) {
+      reject(new Error("Database not initialized"));
+      return;
+    }
+    db.exec(sql, (err) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+function closeDb(): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (!db) {
+      resolve();
+      return;
+    }
+    db.close((err) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+describe("runPagedList integration", () => {
+  beforeAll(async () => {
+    db = new sqlite3.Database(":memory:");
+    await execSql("create table users (id integer primary key autoincrement, name text not null, email text not null)");
+    await execSql("insert into users (name, email) values ('Ada', 'ada@example.com')");
+    await execSql("insert into users (name, email) values ('Alan', 'alan@example.com')");
+    await execSql("insert into users (name, email) values ('Bruna', 'bruna@example.com')");
+
+    const client = createSqliteClient(db);
+    const executor = createSqliteExecutor(client);
+    orm = new Orm({
+      dialect: new SqliteDialect(),
+      executorFactory: {
+        createExecutor: () => executor,
+        createTransactionalExecutor: () => executor,
+        dispose: async () => {}
+      }
+    });
+  });
+
+  afterAll(async () => {
+    await orm?.dispose();
+    await closeDb();
+  });
+
+  it("runs filtered + sorted + paginated list from raw query", async () => {
+    if (!orm) {
+      throw new Error("ORM not initialized");
+    }
+
+    const session = orm.createSession();
+    try {
+      const result = await runPagedList({
+        query: {
+          page: "1",
+          pageSize: "1",
+          nameContains: "a",
+          sortBy: "name",
+          sortOrder: "DESC"
+        },
+        target: users,
+        qb: () => selectFrom(users).select("id", "name", "email"),
+        session,
+        filterMappings: {
+          nameContains: { field: "name", operator: "contains" }
+        },
+        sortableColumns: {
+          id: "id",
+          name: "name"
+        },
+        defaultSortBy: "id",
+        defaultSortDirection: "asc"
+      });
+
+      expect(result.totalItems).toBe(3);
+      expect(result.items).toHaveLength(1);
+      expect(result.items[0].name).toBe("Bruna");
+      expect(result.page).toBe(1);
+      expect(result.pageSize).toBe(1);
+      expect(result.totalPages).toBe(3);
+      expect(result.hasNextPage).toBe(true);
+      expect(result.hasPrevPage).toBe(false);
+    } finally {
+      await session.dispose();
+    }
+  });
+
+  it("supports defaults when sort/page params are omitted", async () => {
+    if (!orm) {
+      throw new Error("ORM not initialized");
+    }
+
+    const session = orm.createSession();
+    try {
+      const result = await runPagedList({
+        query: {},
+        target: users,
+        qb: () => selectFrom(users).select("id", "name", "email"),
+        session,
+        filterMappings: {},
+        sortableColumns: {
+          id: "id"
+        },
+        defaultSortBy: "id",
+        defaultSortDirection: "desc",
+        defaultPageSize: 2,
+        maxPageSize: 5
+      });
+
+      expect(result.items).toHaveLength(2);
+      expect(result.items[0].id).toBe(3);
+      expect(result.items[1].id).toBe(2);
+      expect(result.pageSize).toBe(2);
+      expect(result.totalItems).toBe(3);
+    } finally {
+      await session.dispose();
+    }
+  });
+});

package/tests/unit/crud-controller-factory.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildOpenApi,
+  createCrudController,
+  createMetalCrudDtoClasses,
+  t,
+  type RequestContext
+} from "../../src/index";
+import { getControllerMeta } from "../../src/core/metadata";
+import { Column, Entity, PrimaryKey, col } from "metal-orm";
+
+@Entity({ tableName: "crud_factory_entities" })
+class CrudFactoryEntity {
+  @PrimaryKey(col.autoIncrement(col.int()))
+  id!: number;
+
+  @Column(col.notNull(col.text()))
+  nome!: string;
+
+  @Column(col.notNull(col.boolean()))
+  ativo!: boolean;
+}
+
+const crudDtos = createMetalCrudDtoClasses(CrudFactoryEntity, {
+  mutationExclude: ["id"],
+  query: {
+    filters: {
+      nomeContains: {
+        schema: t.string({ minLength: 1 }),
+        field: "nome",
+        operator: "contains"
+      },
+      ativo: {
+        schema: t.boolean(),
+        field: "ativo",
+        operator: "equals"
+      }
+    },
+    sortableColumns: {
+      id: "id",
+      nome: "nome"
+    },
+    options: {
+      labelField: "nome"
+    }
+  },
+  errors: true
+});
+
+class CrudFactoryService {
+  async list(_ctx: RequestContext<unknown, InstanceType<typeof crudDtos.queryDto>>) {
+    return { items: [], total: 0, page: 1, pageSize: 25 } as InstanceType<typeof crudDtos.pagedResponseDto>;
+  }
+
+  async options(_ctx: RequestContext<unknown, InstanceType<typeof crudDtos.optionsQueryDto>>) {
+    return { items: [], total: 0, page: 1, pageSize: 25 } as InstanceType<typeof crudDtos.optionsDto>;
+  }
+
+  async getById(
+    id: number,
+    _ctx: RequestContext<unknown, undefined, InstanceType<typeof crudDtos.params>>
+  ) {
+    return { id, nome: "Teste", ativo: true } as InstanceType<typeof crudDtos.response>;
+  }
+
+  async create(
+    body: InstanceType<typeof crudDtos.create>,
+    _ctx: RequestContext<InstanceType<typeof crudDtos.create>>
+  ) {
+    return { id: 1, ...body } as InstanceType<typeof crudDtos.response>;
+  }
+
+  async replace(
+    id: number,
+    body: InstanceType<typeof crudDtos.replace>,
+    _ctx: RequestContext<InstanceType<typeof crudDtos.replace>, undefined, InstanceType<typeof crudDtos.params>>
+  ) {
+    return { id, ...body } as InstanceType<typeof crudDtos.response>;
+  }
+
+  async update(
+    id: number,
+    body: InstanceType<typeof crudDtos.update>,
+    _ctx: RequestContext<InstanceType<typeof crudDtos.update>, undefined, InstanceType<typeof crudDtos.params>>
+  ) {
+    return { id, ...body } as InstanceType<typeof crudDtos.response>;
+  }
+
+  async delete(
+    _id: number,
+    _ctx: RequestContext<unknown, undefined, InstanceType<typeof crudDtos.params>>
+  ) {}
+}
+
+const CrudFactoryController = createCrudController({
+  path: "/crud-factory",
+  service: CrudFactoryService,
+  dtos: crudDtos,
+  entityName: "CrudFactoryEntity"
+});
+
+describe("createCrudController", () => {
+  it("registers CRUD routes with expected schemas and statuses", () => {
+    const meta = getControllerMeta(CrudFactoryController);
+    expect(meta).toBeDefined();
+    expect(meta?.basePath).toBe("/crud-factory");
+
+    const routeKeys = (meta?.routes ?? [])
+      .map((route) => `${route.httpMethod} ${route.path}`)
+      .sort();
+
+    expect(routeKeys).toEqual([
+      "delete /:id",
+      "get /",
+      "get /:id",
+      "get /options",
+      "patch /:id",
+      "post /",
+      "put /:id"
+    ]);
+
+    const byKey = new Map(
+      (meta?.routes ?? []).map((route) => [`${route.httpMethod} ${route.path}`, route] as const)
+    );
+
+    const listRoute = byKey.get("get /");
+    expect(listRoute?.query?.schema).toBe(crudDtos.queryDto);
+    expect(listRoute?.responses).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ status: 200, schema: crudDtos.pagedResponseDto })
+      ])
+    );
+
+    const optionsRoute = byKey.get("get /options");
+    expect(optionsRoute?.query?.schema).toBe(crudDtos.optionsQueryDto);
+    expect(optionsRoute?.responses).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ status: 200, schema: crudDtos.optionsDto })
+      ])
+    );
+
+    const createRoute = byKey.get("post /");
+    expect(createRoute?.body?.schema).toBe(crudDtos.create);
+    expect(createRoute?.responses).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ status: 201, schema: crudDtos.response })
+      ])
+    );
+
+    for (const key of ["get /:id", "put /:id", "patch /:id", "delete /:id"]) {
+      const route = byKey.get(key);
+      expect(route?.params?.schema).toBe(crudDtos.params);
+      expect(route?.responses).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ status: 400, error: true }),
+          expect.objectContaining({ status: 404, error: true })
+        ])
+      );
+    }
+
+    expect(byKey.get("put /:id")?.body?.schema).toBe(crudDtos.replace);
+    expect(byKey.get("patch /:id")?.body?.schema).toBe(crudDtos.update);
+    expect(byKey.get("delete /:id")?.responses).toEqual(
+      expect.arrayContaining([expect.objectContaining({ status: 204 })])
+    );
+  });
+
+  it("exposes matching schemas/status in OpenAPI", () => {
+    const doc = buildOpenApi({
+      info: { title: "Test API", version: "1.0.0" },
+      controllers: [CrudFactoryController]
+    });
+
+    const listResponses = (doc.paths["/crud-factory"]?.get as Record<string, any>)?.responses;
+    const createResponses = (doc.paths["/crud-factory"]?.post as Record<string, any>)?.responses;
+    const getByIdResponses = (doc.paths["/crud-factory/{id}"]?.get as Record<string, any>)?.responses;
+    const deleteResponses = (doc.paths["/crud-factory/{id}"]?.delete as Record<string, any>)?.responses;
+
+    expect(listResponses?.["200"]).toBeDefined();
+    expect(createResponses?.["201"]).toBeDefined();
+    expect(getByIdResponses?.["200"]).toBeDefined();
+    expect(getByIdResponses?.["400"]).toBeDefined();
+    expect(getByIdResponses?.["404"]).toBeDefined();
+    expect(deleteResponses?.["204"]).toBeDefined();
+  });
+
+  it("supports disabling optional routes with flags", () => {
+    const MinimalController = createCrudController({
+      path: "/crud-factory-minimal",
+      service: new CrudFactoryService(),
+      dtos: crudDtos,
+      entityName: "CrudFactoryEntity",
+      withOptionsRoute: false,
+      withReplace: false,
+      withPatch: false,
+      withDelete: false
+    });
+
+    const meta = getControllerMeta(MinimalController);
+    const routeKeys = (meta?.routes ?? [])
+      .map((route) => `${route.httpMethod} ${route.path}`)
+      .sort();
+
+    expect(routeKeys).toEqual([
+      "get /",
+      "get /:id",
+      "post /"
+    ]);
+  });
+
+  it("uses entityName in parseIdOrThrow messages", async () => {
+    const controller = new CrudFactoryController();
+    await expect(
+      controller.getById({
+        params: { id: "invalid" }
+      } as any)
+    ).rejects.toMatchObject({
+      status: 400,
+      message: "Invalid CrudFactoryEntity id."
+    });
+  });
+});

package/tests/unit/run-paged-list.test.ts

@@ -0,0 +1,109 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { col, defineTable } from "metal-orm";
+
+const { executeFilteredPagedMock } = vi.hoisted(() => ({
+  executeFilteredPagedMock: vi.fn()
+}));
+
+vi.mock("metal-orm", async () => {
+  const actual = await vi.importActual<typeof import("metal-orm")>("metal-orm");
+  return {
+    ...actual,
+    executeFilteredPaged: executeFilteredPagedMock
+  };
+});
+
+import { runPagedList } from "../../src/adapter/metal-orm/list";
+
+describe("runPagedList", () => {
+  const users = defineTable("users", {
+    id: col.primaryKey(col.autoIncrement(col.int())),
+    name: col.notNull(col.text()),
+    email: col.notNull(col.text())
+  });
+
+  const qb = {
+    getTable: () => users
+  } as unknown as import("metal-orm").SelectQueryBuilder<
+    { id: number; name: string; email: string },
+    typeof users
+  >;
+
+  beforeEach(() => {
+    executeFilteredPagedMock.mockReset();
+    executeFilteredPagedMock.mockResolvedValue({
+      items: [],
+      totalItems: 0,
+      page: 1,
+      pageSize: 25,
+      totalPages: 0,
+      hasNextPage: false,
+      hasPrevPage: false
+    });
+  });
+
+  it("combines parsing and forwards normalized sort from sortOrder", async () => {
+    await runPagedList({
+      query: {
+        page: "2",
+        pageSize: "10",
+        nameContains: "Ada",
+        sortBy: "name",
+        sortOrder: "DESC"
+      },
+      target: users,
+      qb,
+      session: {} as import("metal-orm").OrmSession,
+      filterMappings: {
+        nameContains: { field: "name", operator: "contains" }
+      },
+      sortableColumns: {
+        name: "name",
+        email: "email"
+      },
+      defaultSortBy: "email",
+      defaultSortDirection: "asc"
+    });
+
+    expect(executeFilteredPagedMock).toHaveBeenCalledTimes(1);
+    expect(executeFilteredPagedMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        page: 2,
+        pageSize: 10,
+        filters: {
+          name: { contains: "Ada" }
+        },
+        sortBy: "name",
+        sortDirection: "DESC",
+        defaultSortBy: undefined,
+        defaultSortDirection: "ASC"
+      })
+    );
+  });
+
+  it("ignores unresolved sortable path and keeps helper execution safe", async () => {
+    await runPagedList({
+      query: {
+        sortBy: "deepField"
+      },
+      target: users,
+      qb,
+      session: {} as import("metal-orm").OrmSession,
+      filterMappings: {},
+      sortableColumns: {
+        deepField: "profile.some.name"
+      },
+      defaultSortBy: "deepField",
+      defaultSortDirection: "desc"
+    });
+
+    expect(executeFilteredPagedMock).toHaveBeenCalledTimes(1);
+    expect(executeFilteredPagedMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sortBy: undefined,
+        defaultSortBy: undefined,
+        defaultSortDirection: "DESC"
+      })
+    );
+  });
+});