adorn-api 1.0.39 → 1.0.41

package/dist/adapter/express/openapi.js

@@ -16,7 +16,13 @@ function attachOpenApi(app, controllers, options) {
         controllers
     });
     app.get(openApiPath, (_req, res) => {
-        res.json(document);
+        if (options.prettyPrint) {
+            res.setHeader("Content-Type", "application/json");
+            res.send(JSON.stringify(document, null, 2));
+        }
+        else {
+            res.json(document);
+        }
     });
     if (!options.docs) {
         return;

package/dist/adapter/express/response-serializer.js

@@ -62,6 +62,9 @@ function serializeWithSchema(value, schema) {
     }
 }
 function serializeString(value, format) {
+    if (format === "byte" && Buffer.isBuffer(value)) {
+        return value.toString("base64");
+    }
     if (!(value instanceof Date)) {
         return value;
     }

package/dist/adapter/express/types.d.ts

@@ -94,6 +94,8 @@ export interface OpenApiExpressOptions {
     servers?: OpenApiServer[];
     /** Path for OpenAPI JSON endpoint */
     path?: string;
+    /** Whether to pretty-print the JSON output (defaults to false for minified output) */
+    prettyPrint?: boolean;
     /** Documentation UI configuration */
     docs?: boolean | OpenApiDocsOptions;
 }

package/dist/core/metadata.js

@@ -8,6 +8,11 @@ exports.getAllDtos = getAllDtos;
 exports.registerController = registerController;
 exports.getControllerMeta = getControllerMeta;
 exports.getAllControllers = getAllControllers;
+// Ensure standard decorator metadata is available for Stage 3 decorators.
+const symbolMetadata = Symbol.metadata;
+if (!symbolMetadata) {
+    Symbol.metadata = Symbol("Symbol.metadata");
+}
 const dtoStore = new Map();
 const controllerStore = new Map();
 exports.META_KEY = Symbol.for("adorn.metadata");

package/dist/core/schema.d.ts

@@ -210,6 +210,14 @@ export declare const t: {
      * @returns Date-time string schema
      */
     dateTime: (opts?: Omit<StringSchema, "kind" | "format">) => StringSchema;
+    /**
+     * Creates a bytes (base64-encoded binary) string schema.
+     * Maps to OpenAPI type: "string" with format: "byte".
+     * Buffer values are automatically base64-encoded during response serialization.
+     * @param opts - String schema options
+     * @returns Bytes string schema
+     */
+    bytes: (opts?: Omit<StringSchema, "kind" | "format">) => StringSchema;
     /**
      * Creates a number schema.
      * @param opts - Number schema options

package/dist/core/schema.js

@@ -34,6 +34,18 @@ exports.t = {
         format: "date-time",
         ...opts
     }),
+    /**
+     * Creates a bytes (base64-encoded binary) string schema.
+     * Maps to OpenAPI type: "string" with format: "byte".
+     * Buffer values are automatically base64-encoded during response serialization.
+     * @param opts - String schema options
+     * @returns Bytes string schema
+     */
+    bytes: (opts = {}) => ({
+        kind: "string",
+        format: "byte",
+        ...opts
+    }),
     /**
      * Creates a number schema.
      * @param opts - Number schema options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adorn-api",
-  "version": "1.0.39",
+  "version": "1.0.41",
   "description": "Decorator-first web framework with OpenAPI 3.1 schema generation.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,7 +15,7 @@
   },
   "dependencies": {
     "express": "^4.19.2",
-    "metal-orm": "^1.0.109"
+    "metal-orm": "^1.0.114"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.3.15",

package/src/adapter/express/openapi.ts

@@ -22,7 +22,12 @@ export function attachOpenApi(
   });
 
   app.get(openApiPath, (_req, res) => {
-    res.json(document);
+    if (options.prettyPrint) {
+      res.setHeader("Content-Type", "application/json");
+      res.send(JSON.stringify(document, null, 2));
+    } else {
+      res.json(document);
+    }
   });
 
   if (!options.docs) {

package/src/adapter/express/response-serializer.ts

@@ -65,6 +65,9 @@ function serializeWithSchema(value: unknown, schema: SchemaNode): unknown {
 }
 
 function serializeString(value: unknown, format: string | undefined): unknown {
+  if (format === "byte" && Buffer.isBuffer(value)) {
+    return value.toString("base64");
+  }
   if (!(value instanceof Date)) {
     return value;
   }

package/src/adapter/express/types.ts

@@ -107,6 +107,8 @@ export interface OpenApiExpressOptions {
   servers?: OpenApiServer[];
   /** Path for OpenAPI JSON endpoint */
   path?: string;
+  /** Whether to pretty-print the JSON output (defaults to false for minified output) */
+  prettyPrint?: boolean;
   /** Documentation UI configuration */
   docs?: boolean | OpenApiDocsOptions;
 }

package/src/core/schema.ts

@@ -255,6 +255,19 @@ export const t = {
     ...opts
   }),
 
+  /**
+   * Creates a bytes (base64-encoded binary) string schema.
+   * Maps to OpenAPI type: "string" with format: "byte".
+   * Buffer values are automatically base64-encoded during response serialization.
+   * @param opts - String schema options
+   * @returns Bytes string schema
+   */
+  bytes: (opts: Omit<StringSchema, "kind" | "format"> = {}): StringSchema => ({
+    kind: "string",
+    format: "byte",
+    ...opts
+  }),
+
   /**
    * Creates a number schema.
    * @param opts - Number schema options

package/tests/e2e/file-upload.e2e.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from "vitest";
 import request from "supertest";
 import {
   Controller,
+  Get,
   Post,
   UploadedFile,
   UploadedFiles,
@@ -146,4 +147,80 @@ describe("File Upload E2E", () => {
       description: "The file to upload"
     });
   });
+
+  it("should pretty print OpenAPI JSON when enabled", async () => {
+    @Controller("/api")
+    class PrettyPrintController {
+      @Get("/test")
+      @Returns({ status: 200, description: "Success" })
+      async test() {
+        return { success: true };
+      }
+    }
+
+    const app = await createExpressApp({
+      controllers: [PrettyPrintController],
+      openApi: {
+        info: { title: "Test API", version: "1.0.0" },
+        path: "/openapi.json",
+        prettyPrint: true
+      }
+    });
+
+    const response = await request(app).get("/openapi.json");
+    expect(response.status).toBe(200);
+    expect(response.headers["content-type"]).toContain("application/json");
+    expect(response.text).toContain('  "openapi": "3.1.0"');
+    expect(response.text).toContain('  "info": {');
+    expect(response.text).toContain('    "title": "Test API"');
+  });
+
+  it("should return minified JSON when prettyPrint is disabled", async () => {
+    @Controller("/api")
+    class MinifiedController {
+      @Get("/test")
+      @Returns({ status: 200, description: "Success" })
+      async test() {
+        return { success: true };
+      }
+    }
+
+    const app = await createExpressApp({
+      controllers: [MinifiedController],
+      openApi: {
+        info: { title: "Test API", version: "1.0.0" },
+        path: "/openapi.json",
+        prettyPrint: false
+      }
+    });
+
+    const response = await request(app).get("/openapi.json");
+    expect(response.status).toBe(200);
+    expect(response.text).not.toContain('  "openapi": "3.1.0"');
+    expect(response.text).toContain('"openapi":"3.1.0"');
+  });
+
+  it("should return minified JSON by default when prettyPrint is not set", async () => {
+    @Controller("/api")
+    class DefaultController {
+      @Get("/test")
+      @Returns({ status: 200, description: "Success" })
+      async test() {
+        return { success: true };
+      }
+    }
+
+    const app = await createExpressApp({
+      controllers: [DefaultController],
+      openApi: {
+        info: { title: "Test API", version: "1.0.0" },
+        path: "/openapi.json"
+      }
+    });
+
+    const response = await request(app).get("/openapi.json");
+    expect(response.status).toBe(200);
+    expect(response.text).not.toContain('  "openapi": "3.1.0"');
+    expect(response.text).toContain('"openapi":"3.1.0"');
+  });
 });

package/tests/unit/response-serializer.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect } from "vitest";
+import { serializeResponse } from "../../src/adapter/express/response-serializer";
+import { t } from "../../src/core/schema";
+
+describe("serializeResponse", () => {
+  describe("Buffer with format: byte", () => {
+    it("serializes Buffer to base64 string when format is byte", () => {
+      const buffer = Buffer.from("Hello, World!");
+      const schema = t.bytes();
+
+      const result = serializeResponse(buffer, schema);
+
+      expect(result).toBe("SGVsbG8sIFdvcmxkIQ==");
+    });
+
+    it("serializes Buffer in object property with format: byte", () => {
+      const data = { content: Buffer.from("binary data") };
+      const schema = t.object({ content: t.bytes() });
+
+      const result = serializeResponse(data, schema);
+
+      expect(result).toEqual({ content: "YmluYXJ5IGRhdGE=" });
+    });
+
+    it("serializes Buffer in array with format: byte", () => {
+      const data = [Buffer.from("first"), Buffer.from("second")];
+      const schema = t.array(t.bytes());
+
+      const result = serializeResponse(data, schema);
+
+      expect(result).toEqual(["Zmlyc3Q=", "c2Vjb25k"]);
+    });
+
+    it("handles empty Buffer", () => {
+      const buffer = Buffer.alloc(0);
+      const schema = t.bytes();
+
+      const result = serializeResponse(buffer, schema);
+
+      expect(result).toBe("");
+    });
+
+    it("handles binary data (non-UTF8)", () => {
+      const buffer = Buffer.from([0x00, 0xff, 0x80, 0x7f]);
+      const schema = t.bytes();
+
+      const result = serializeResponse(buffer, schema);
+
+      expect(result).toBe("AP+Afw==");
+    });
+
+    it("does not affect non-Buffer values with format: byte", () => {
+      const schema = t.bytes();
+
+      expect(serializeResponse("already a string", schema)).toBe("already a string");
+      expect(serializeResponse(123, schema)).toBe(123);
+      expect(serializeResponse(null, schema)).toBe(null);
+    });
+
+    it("does not convert Buffer to base64 when format is not byte", () => {
+      const buffer = Buffer.from("test");
+      const schema = t.string();
+
+      const result = serializeResponse(buffer, schema);
+
+      expect(result).toEqual(buffer);
+    });
+  });
+
+  describe("Date serialization (unchanged)", () => {
+    it("serializes Date to ISO string for date-time format", () => {
+      const date = new Date("2024-01-15T10:30:00.000Z");
+      const schema = t.dateTime();
+
+      const result = serializeResponse(date, schema);
+
+      expect(result).toBe("2024-01-15T10:30:00.000Z");
+    });
+
+    it("serializes Date to date string for date format", () => {
+      const date = new Date("2024-01-15T10:30:00.000Z");
+      const schema = t.string({ format: "date" });
+
+      const result = serializeResponse(date, schema);
+
+      expect(result).toBe("2024-01-15");
+    });
+
+    it("does not serialize invalid Date", () => {
+      const date = new Date("invalid");
+      const schema = t.dateTime();
+
+      const result = serializeResponse(date, schema);
+
+      expect(result).toBe(date);
+    });
+  });
+
+  describe("record with bytes values", () => {
+    it("serializes all Buffer values in a record to base64", () => {
+      const data = {
+        file1: Buffer.from("content1"),
+        file2: Buffer.from("content2"),
+      };
+      const schema = t.record(t.bytes());
+
+      const result = serializeResponse(data, schema);
+
+      expect(result).toEqual({
+        file1: "Y29udGVudDE=",
+        file2: "Y29udGVudDI=",
+      });
+    });
+  });
+
+  describe("union with bytes", () => {
+    it("serializes Buffer in union when format is byte", () => {
+      const buffer = Buffer.from("union content");
+      const schema = t.union([t.bytes(), t.string()]);
+
+      const result = serializeResponse(buffer, schema);
+
+      expect(result).toBe("dW5pb24gY29udGVudA==");
+    });
+  });
+});
+
+describe("t.bytes() helper", () => {
+  it("creates a string schema with format: byte", () => {
+    const schema = t.bytes();
+
+    expect(schema).toEqual({
+      kind: "string",
+      format: "byte",
+    });
+  });
+
+  it("accepts additional options", () => {
+    const schema = t.bytes({ description: "Binary data" });
+
+    expect(schema).toEqual({
+      kind: "string",
+      format: "byte",
+      description: "Binary data",
+    });
+  });
+});