adorn-api 1.0.22 → 1.0.24

package/src/core/schema.ts

@@ -0,0 +1,400 @@
+import type { DtoConstructor } from "./types";
+
+/**
+ * JSON primitive types.
+ */
+export type JsonPrimitive = string | number | boolean | null;
+
+/**
+ * Base options for all schema types.
+ */
+export interface BaseSchemaOptions {
+  /** Description of the schema */
+  description?: string;
+  /** Title for the schema */
+  title?: string;
+  /** Default value */
+  default?: unknown;
+  /** Example values */
+  examples?: unknown[];
+  /** Whether the schema is deprecated */
+  deprecated?: boolean;
+  /** Whether the schema is read-only */
+  readOnly?: boolean;
+  /** Whether the schema is write-only */
+  writeOnly?: boolean;
+  /** Whether the schema is optional */
+  optional?: boolean;
+  /** Whether the schema can be null */
+  nullable?: boolean;
+}
+
+/**
+ * String schema definition.
+ * @extends BaseSchemaOptions
+ */
+export interface StringSchema extends BaseSchemaOptions {
+  /** Schema kind identifier */
+  kind: "string";
+  /** Format specification (e.g., "uuid", "date-time") */
+  format?: string;
+  /** Minimum length constraint */
+  minLength?: number;
+  /** Maximum length constraint */
+  maxLength?: number;
+  /** Regular expression pattern constraint */
+  pattern?: string;
+}
+
+/**
+ * Number schema definition.
+ * @extends BaseSchemaOptions
+ */
+export interface NumberSchema extends BaseSchemaOptions {
+  /** Schema kind identifier ("number" or "integer") */
+  kind: "number" | "integer";
+  /** Minimum value constraint */
+  minimum?: number;
+  /** Maximum value constraint */
+  maximum?: number;
+  /** Exclusive minimum value constraint */
+  exclusiveMinimum?: number;
+  /** Exclusive maximum value constraint */
+  exclusiveMaximum?: number;
+  /** Multiple-of constraint */
+  multipleOf?: number;
+}
+
+/**
+ * Boolean schema definition.
+ * @extends BaseSchemaOptions
+ */
+export interface BooleanSchema extends BaseSchemaOptions {
+  /** Schema kind identifier */
+  kind: "boolean";
+}
+
+/**
+ * Array schema definition.
+ * @extends BaseSchemaOptions
+ */
+export interface ArraySchema extends BaseSchemaOptions {
+  /** Schema kind identifier */
+  kind: "array";
+  /** Schema for array items */
+  items: SchemaNode;
+  /** Minimum number of items constraint */
+  minItems?: number;
+  /** Maximum number of items constraint */
+  maxItems?: number;
+  /** Whether items must be unique */
+  uniqueItems?: boolean;
+}
+
+/**
+ * Object schema definition.
+ * @extends BaseSchemaOptions
+ */
+export interface ObjectSchema extends BaseSchemaOptions {
+  /** Schema kind identifier */
+  kind: "object";
+  /** Object properties */
+  properties?: Record<string, SchemaNode>;
+  /** Required property names */
+  required?: string[];
+  /** Additional properties configuration */
+  additionalProperties?: boolean | SchemaNode;
+  /** Minimum number of properties constraint */
+  minProperties?: number;
+  /** Maximum number of properties constraint */
+  maxProperties?: number;
+}
+
+/**
+ * Enum schema definition.
+ * @extends BaseSchemaOptions
+ */
+export interface EnumSchema extends BaseSchemaOptions {
+  /** Schema kind identifier */
+  kind: "enum";
+  /** Array of allowed values */
+  values: JsonPrimitive[];
+}
+
+/**
+ * Literal schema definition.
+ * @extends BaseSchemaOptions
+ */
+export interface LiteralSchema extends BaseSchemaOptions {
+  /** Schema kind identifier */
+  kind: "literal";
+  /** Literal value */
+  value: JsonPrimitive;
+}
+
+/**
+ * Union schema definition.
+ * @extends BaseSchemaOptions
+ */
+export interface UnionSchema extends BaseSchemaOptions {
+  /** Schema kind identifier */
+  kind: "union";
+  /** Array of possible schemas */
+  anyOf: SchemaNode[];
+}
+
+/**
+ * Record schema definition.
+ * @extends BaseSchemaOptions
+ */
+export interface RecordSchema extends BaseSchemaOptions {
+  /** Schema kind identifier */
+  kind: "record";
+  /** Schema for record values */
+  values: SchemaNode;
+}
+
+/**
+ * Reference schema definition.
+ * @extends BaseSchemaOptions
+ */
+export interface RefSchema extends BaseSchemaOptions {
+  /** Schema kind identifier */
+  kind: "ref";
+  /** DTO constructor being referenced */
+  dto: DtoConstructor;
+}
+
+/**
+ * Any schema definition.
+ * @extends BaseSchemaOptions
+ */
+export interface AnySchema extends BaseSchemaOptions {
+  /** Schema kind identifier */
+  kind: "any";
+}
+
+/**
+ * Null schema definition.
+ * @extends BaseSchemaOptions
+ */
+export interface NullSchema extends BaseSchemaOptions {
+  /** Schema kind identifier */
+  kind: "null";
+}
+
+/**
+ * Union type representing all possible schema node types.
+ */
+export type SchemaNode =
+  | StringSchema
+  | NumberSchema
+  | BooleanSchema
+  | ArraySchema
+  | ObjectSchema
+  | EnumSchema
+  | LiteralSchema
+  | UnionSchema
+  | RecordSchema
+  | RefSchema
+  | AnySchema
+  | NullSchema;
+
+/**
+ * Schema source - can be either a schema node or a DTO constructor.
+ */
+export type SchemaSource = SchemaNode | DtoConstructor;
+
+/**
+ * Schema builder object providing helper functions for creating schema nodes.
+ */
+export const t = {
+  /**
+   * Creates a string schema.
+   * @param opts - String schema options
+   * @returns String schema
+   */
+  string: (opts: Omit<StringSchema, "kind"> = {}): StringSchema => ({
+    kind: "string",
+    ...opts
+  }),
+
+  /**
+   * Creates a UUID string schema.
+   * @param opts - String schema options
+   * @returns UUID string schema
+   */
+  uuid: (opts: Omit<StringSchema, "kind" | "format"> = {}): StringSchema => ({
+    kind: "string",
+    format: "uuid",
+    ...opts
+  }),
+
+  /**
+   * Creates a date-time string schema.
+   * @param opts - String schema options
+   * @returns Date-time string schema
+   */
+  dateTime: (opts: Omit<StringSchema, "kind" | "format"> = {}): StringSchema => ({
+    kind: "string",
+    format: "date-time",
+    ...opts
+  }),
+
+  /**
+   * Creates a number schema.
+   * @param opts - Number schema options
+   * @returns Number schema
+   */
+  number: (opts: Omit<NumberSchema, "kind"> = {}): NumberSchema => ({
+    kind: "number",
+    ...opts
+  }),
+
+  /**
+   * Creates an integer schema.
+   * @param opts - Number schema options
+   * @returns Integer schema
+   */
+  integer: (opts: Omit<NumberSchema, "kind"> = {}): NumberSchema => ({
+    kind: "integer",
+    ...opts
+  }),
+
+  /**
+   * Creates a boolean schema.
+   * @param opts - Boolean schema options
+   * @returns Boolean schema
+   */
+  boolean: (opts: Omit<BooleanSchema, "kind"> = {}): BooleanSchema => ({
+    kind: "boolean",
+    ...opts
+  }),
+
+  /**
+   * Creates an array schema.
+   * @param items - Schema for array items
+   * @param opts - Array schema options
+   * @returns Array schema
+   */
+  array: (items: SchemaNode, opts: Omit<ArraySchema, "kind" | "items"> = {}): ArraySchema => ({
+    kind: "array",
+    items,
+    ...opts
+  }),
+
+  /**
+   * Creates an object schema.
+   * @param properties - Object properties
+   * @param opts - Object schema options
+   * @returns Object schema
+   */
+  object: (
+    properties: Record<string, SchemaNode>,
+    opts: Omit<ObjectSchema, "kind" | "properties"> = {}
+  ): ObjectSchema => ({
+    kind: "object",
+    properties,
+    ...opts
+  }),
+
+  /**
+   * Creates a record schema.
+   * @param values - Schema for record values
+   * @param opts - Record schema options
+   * @returns Record schema
+   */
+  record: (values: SchemaNode, opts: Omit<RecordSchema, "kind" | "values"> = {}): RecordSchema => ({
+    kind: "record",
+    values,
+    ...opts
+  }),
+
+  /**
+   * Creates an enum schema.
+   * @param values - Array of allowed values
+   * @param opts - Enum schema options
+   * @returns Enum schema
+   */
+  enum: (values: JsonPrimitive[], opts: Omit<EnumSchema, "kind" | "values"> = {}): EnumSchema => ({
+    kind: "enum",
+    values,
+    ...opts
+  }),
+
+  /**
+   * Creates a literal schema.
+   * @param value - Literal value
+   * @param opts - Literal schema options
+   * @returns Literal schema
+   */
+  literal: (value: JsonPrimitive, opts: Omit<LiteralSchema, "kind" | "value"> = {}): LiteralSchema => ({
+    kind: "literal",
+    value,
+    ...opts
+  }),
+
+  /**
+   * Creates a union schema.
+   * @param anyOf - Array of possible schemas
+   * @param opts - Union schema options
+   * @returns Union schema
+   */
+  union: (anyOf: SchemaNode[], opts: Omit<UnionSchema, "kind" | "anyOf"> = {}): UnionSchema => ({
+    kind: "union",
+    anyOf,
+    ...opts
+  }),
+
+  /**
+   * Creates a reference schema.
+   * @param dto - DTO constructor being referenced
+   * @param opts - Reference schema options
+   * @returns Reference schema
+   */
+  ref: (dto: DtoConstructor, opts: Omit<RefSchema, "kind" | "dto"> = {}): RefSchema => ({
+    kind: "ref",
+    dto,
+    ...opts
+  }),
+
+  /**
+   * Creates an any schema.
+   * @param opts - Any schema options
+   * @returns Any schema
+   */
+  any: (opts: Omit<AnySchema, "kind"> = {}): AnySchema => ({
+    kind: "any",
+    ...opts
+  }),
+
+  /**
+   * Creates a null schema.
+   * @param opts - Null schema options
+   * @returns Null schema
+   */
+  null: (opts: Omit<NullSchema, "kind"> = {}): NullSchema => ({
+    kind: "null",
+    ...opts
+  }),
+
+  /**
+   * Makes a schema optional.
+   * @param schema - Schema to make optional
+   * @returns Modified schema with optional flag
+   */
+  optional: <T extends SchemaNode>(schema: T): T => ({
+    ...schema,
+    optional: true
+  }),
+
+  /**
+   * Makes a schema nullable.
+   * @param schema - Schema to make nullable
+   * @returns Modified schema with nullable flag
+   */
+  nullable: <T extends SchemaNode>(schema: T): T => ({
+    ...schema,
+    nullable: true
+  })
+};

package/src/core/types.ts

@@ -0,0 +1,14 @@
+/**
+ * Generic constructor type.
+ */
+export type Constructor<T = any> = new (...args: any[]) => T;
+
+/**
+ * DTO constructor type.
+ */
+export type DtoConstructor<T = any> = new (...args: any[]) => T;
+
+/**
+ * HTTP method types.
+ */
+export type HttpMethod = "get" | "post" | "put" | "patch" | "delete";

package/src/e2e/http-error.e2e.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import request from "supertest";
+import {
+  Controller,
+  Dto,
+  Errors,
+  Field,
+  Get,
+  HttpError,
+  Returns,
+  createExpressApp,
+  t
+} from "../index";
+
+@Dto()
+class ErrorDto {
+  @Field(t.string())
+  message!: string;
+}
+
+const DemoErrors = Errors(ErrorDto, [
+  { status: 400, description: "Bad request." }
+]);
+
+@Controller("/demo")
+class DemoController {
+  @Get("/bad")
+  @DemoErrors
+  bad() {
+    throw new HttpError(400, "Bad request.");
+  }
+
+  @Get("/ok")
+  @Returns({ status: 204, description: "No content." })
+  @DemoErrors
+  ok() {
+    return;
+  }
+}
+
+describe("http error handling", () => {
+  const app = createExpressApp({ controllers: [DemoController] });
+
+  it("serializes HttpError responses", async () => {
+    const response = await request(app).get("/demo/bad").expect(400);
+    expect(response.body).toEqual({ message: "Bad request." });
+  });
+
+  it("does not let error responses override success defaults", async () => {
+    await request(app).get("/demo/ok").expect(204);
+  });
+});

package/src/e2e/sqlite-metal-orm.e2e.test.ts

@@ -0,0 +1,174 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import request from "supertest";
+import sqlite3 from "sqlite3";
+import {
+  Body,
+  Controller,
+  Dto,
+  Field,
+  Get,
+  Post,
+  Returns,
+  createExpressApp,
+  t,
+  type RequestContext
+} from "../index";
+import {
+  SqliteDialect,
+  Orm,
+  col,
+  createSqliteExecutor,
+  defineTable,
+  selectFrom,
+  type SqliteClientLike
+} from "metal-orm";
+
+const users = defineTable("users", {
+  id: col.primaryKey(col.autoIncrement(col.int())),
+  name: 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();
+    });
+  });
+}
+
+function createSession() {
+  if (!orm) {
+    throw new Error("ORM not initialized");
+  }
+  return orm.createSession();
+}
+
+@Dto()
+class CreateUserDto {
+  @Field(t.string({ minLength: 1 }))
+  name!: string;
+}
+
+@Dto()
+class UserDto {
+  @Field(t.integer())
+  id!: number;
+
+  @Field(t.string({ minLength: 1 }))
+  name!: string;
+}
+
+@Controller("/users")
+class UserController {
+  @Get("/")
+  @Returns(t.array(t.ref(UserDto)))
+  async list() {
+    const session = createSession();
+    try {
+      return await selectFrom(users)
+        .select("id", "name")
+        .orderBy(users.columns.id, "ASC")
+        .executePlain(session);
+    } finally {
+      await session.dispose();
+    }
+  }
+
+  @Post("/")
+  @Body(CreateUserDto)
+  @Returns({ status: 201, schema: UserDto })
+  async create(ctx: RequestContext<CreateUserDto>) {
+    const session = createSession();
+    try {
+      const user = { name: ctx.body.name };
+      session.trackNew(users, user);
+      await session.commit();
+      return user as UserDto;
+    } finally {
+      await session.dispose();
+    }
+  }
+}
+
+describe("e2e sqlite memory (metal-orm)", () => {
+  const app = createExpressApp({ controllers: [UserController] });
+
+  beforeAll(async () => {
+    db = new sqlite3.Database(":memory:");
+    await execSql("create table users (id integer primary key autoincrement, name text not null)");
+
+    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("creates and lists users", async () => {
+    const createResponse = await request(app)
+      .post("/users")
+      .send({ name: "Ada" })
+      .expect(201);
+
+    expect(createResponse.body).toMatchObject({ id: 1, name: "Ada" });
+
+    const listResponse = await request(app)
+      .get("/users")
+      .expect(200);
+
+    expect(listResponse.body).toEqual([{ id: 1, name: "Ada" }]);
+  });
+});