adorn-api 1.1.11 → 1.1.13

package/dist/adapter/fastify/multipart.d.ts

@@ -0,0 +1,26 @@
+import type { FastifyRequest } from "fastify";
+import type { UploadedFileMeta } from "../../core/metadata";
+import type { UploadedFileInfo } from "../../core/types";
+import type { MultipartOptions } from "./types";
+/**
+ * Normalized multipart options with defaults applied.
+ */
+export interface NormalizedMultipartOptions {
+    storage: "memory" | "disk";
+    dest: string;
+    maxFileSize: number;
+    maxFiles: number;
+}
+/**
+ * Normalizes multipart options with defaults.
+ */
+export declare function normalizeMultipartOptions(options: boolean | MultipartOptions | undefined): NormalizedMultipartOptions | undefined;
+/**
+ * Extracts uploaded files from the Fastify request.
+ * For Fastify, files are expected to be attached to the request by @fastify/multipart
+ */
+export declare function extractFiles(req: FastifyRequest): Promise<Record<string, UploadedFileInfo | UploadedFileInfo[]> | undefined>;
+/**
+ * Checks if a route has file uploads configured.
+ */
+export declare function hasFileUploads(files: UploadedFileMeta[] | undefined): boolean;

package/dist/adapter/fastify/multipart.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeMultipartOptions = normalizeMultipartOptions;
+exports.extractFiles = extractFiles;
+exports.hasFileUploads = hasFileUploads;
+const DEFAULT_OPTIONS = {
+    storage: "memory",
+    dest: "",
+    maxFileSize: 10 * 1024 * 1024, // 10MB
+    maxFiles: 10
+};
+/**
+ * Normalizes multipart options with defaults.
+ */
+function normalizeMultipartOptions(options) {
+    if (!options) {
+        return undefined;
+    }
+    if (options === true) {
+        return DEFAULT_OPTIONS;
+    }
+    return {
+        storage: options.storage ?? DEFAULT_OPTIONS.storage,
+        dest: options.dest ?? DEFAULT_OPTIONS.dest,
+        maxFileSize: options.maxFileSize ?? DEFAULT_OPTIONS.maxFileSize,
+        maxFiles: options.maxFiles ?? DEFAULT_OPTIONS.maxFiles
+    };
+}
+/**
+ * Extracts uploaded files from the Fastify request.
+ * For Fastify, files are expected to be attached to the request by @fastify/multipart
+ */
+async function extractFiles(req) {
+    const parts = req.parts();
+    const filesMap = {};
+    const fields = {};
+    for await (const part of parts) {
+        if (part.file) {
+            const buffer = await part.toBuffer();
+            const info = {
+                originalName: part.filename,
+                mimeType: part.mimetype,
+                size: buffer.length,
+                buffer: buffer,
+                fieldName: part.fieldname
+            };
+            if (filesMap[part.fieldname]) {
+                if (Array.isArray(filesMap[part.fieldname])) {
+                    filesMap[part.fieldname].push(info);
+                }
+                else {
+                    filesMap[part.fieldname] = [filesMap[part.fieldname], info];
+                }
+            }
+            else {
+                filesMap[part.fieldname] = info;
+            }
+        }
+        else {
+            // It's a field
+            fields[part.fieldname] = part.value;
+        }
+    }
+    // Merge fields into body if it's a multipart request
+    if (Object.keys(fields).length > 0) {
+        Object.assign(req.body ?? (req.body = {}), fields);
+    }
+    return Object.keys(filesMap).length > 0 ? filesMap : undefined;
+}
+/**
+ * Checks if a route has file uploads configured.
+ */
+function hasFileUploads(files) {
+    return !!files && files.length > 0;
+}

package/dist/adapter/fastify/openapi.d.ts

@@ -0,0 +1,10 @@
+import type { FastifyInstance } from "fastify";
+import type { Constructor } from "../../core/types";
+import type { OpenApiFastifyOptions } from "./types";
+/**
+ * Attaches OpenAPI endpoints to a Fastify application.
+ * @param app - Fastify application instance
+ * @param controllers - Array of controller classes
+ * @param options - OpenAPI options
+ */
+export declare function attachOpenApi(app: FastifyInstance, controllers: Constructor[], options: OpenApiFastifyOptions): void;

package/dist/adapter/fastify/openapi.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachOpenApi = attachOpenApi;
+const openapi_1 = require("../../core/openapi");
+/**
+ * Attaches OpenAPI endpoints to a Fastify application.
+ * @param app - Fastify application instance
+ * @param controllers - Array of controller classes
+ * @param options - OpenAPI options
+ */
+function attachOpenApi(app, controllers, options) {
+    const openApiPath = normalizePath(options.path, "/openapi.json");
+    const document = (0, openapi_1.buildOpenApi)({
+        info: options.info,
+        servers: options.servers,
+        controllers
+    });
+    app.get(openApiPath, (_req, reply) => {
+        if (options.prettyPrint) {
+            reply.header("Content-Type", "application/json");
+            reply.send(JSON.stringify(document, null, 2));
+        }
+        else {
+            reply.send(document);
+        }
+    });
+    if (!options.docs) {
+        return;
+    }
+    const docsOptions = typeof options.docs === "object" ? options.docs : {};
+    const docsPath = normalizePath(docsOptions.path, "/docs");
+    const title = docsOptions.title ?? `${options.info.title} Docs`;
+    const swaggerUiUrl = (docsOptions.swaggerUiUrl ?? "https://unpkg.com/swagger-ui-dist@5").replace(/\/+$/, "");
+    const html = buildSwaggerUiHtml({ title, swaggerUiUrl, openApiPath });
+    app.get(docsPath, (_req, reply) => {
+        reply.type("text/html").send(html);
+    });
+}
+function normalizePath(path, fallback) {
+    if (!path) {
+        return fallback;
+    }
+    return path.startsWith("/") ? path : `/${path}`;
+}
+function buildSwaggerUiHtml(options) {
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>${options.title}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="stylesheet" href="${options.swaggerUiUrl}/swagger-ui.css" />
+    <style>
+      body {
+        margin: 0;
+        background: #f6f6f6;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="${options.swaggerUiUrl}/swagger-ui-bundle.js"></script>
+    <script>
+      window.onload = () => {
+        window.ui = SwaggerUIBundle({
+          url: "${options.openApiPath}",
+          dom_id: "#swagger-ui",
+          deepLinking: true,
+          presets: [SwaggerUIBundle.presets.apis],
+          layout: "BaseLayout"
+        });
+      };
+    </script>
+  </body>
+</html>`;
+}

package/dist/adapter/fastify/response-serializer.d.ts

@@ -0,0 +1,2 @@
+import type { SchemaSource } from "../../core/schema";
+export declare function serializeResponse(value: unknown, schema: SchemaSource): unknown;

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

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeResponse = serializeResponse;
+const metadata_1 = require("../../core/metadata");
+function serializeResponse(value, schema) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (isSchemaNode(schema)) {
+        return serializeWithSchema(value, schema);
+    }
+    return serializeWithDto(value, schema);
+}
+function serializeWithDto(value, dto) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => serializeWithDto(entry, dto));
+    }
+    const plainValue = toPlainObject(value);
+    if (!plainValue) {
+        return value;
+    }
+    const meta = (0, metadata_1.getDtoMeta)(dto);
+    if (!meta) {
+        return plainValue;
+    }
+    const output = { ...plainValue };
+    for (const [name, field] of Object.entries(meta.fields)) {
+        if (name in plainValue) {
+            output[name] = serializeWithSchema(plainValue[name], field.schema);
+        }
+    }
+    return output;
+}
+function serializeWithSchema(value, schema) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    switch (schema.kind) {
+        case "string":
+            return serializeString(value, schema.format);
+        case "array":
+            if (!Array.isArray(value)) {
+                return value;
+            }
+            return value.map((entry) => serializeWithSchema(entry, schema.items));
+        case "object":
+            return serializeObject(value, schema.properties);
+        case "record":
+            if (!isPlainObject(value)) {
+                return value;
+            }
+            return serializeRecord(value, schema.values);
+        case "ref":
+            return serializeWithDto(value, schema.dto);
+        case "union":
+            return serializeUnion(value, schema.anyOf);
+        default:
+            return value;
+    }
+}
+function serializeString(value, format) {
+    if (format === "byte" && Buffer.isBuffer(value)) {
+        return value.toString("base64");
+    }
+    if (!(value instanceof Date)) {
+        return value;
+    }
+    if (Number.isNaN(value.getTime())) {
+        return value;
+    }
+    if (format === "date") {
+        return value.toISOString().slice(0, 10);
+    }
+    if (format === "date-time") {
+        return value.toISOString();
+    }
+    return value;
+}
+function serializeObject(value, properties) {
+    const plainValue = toPlainObject(value);
+    if (!plainValue) {
+        return value;
+    }
+    const output = { ...plainValue };
+    if (!properties) {
+        return output;
+    }
+    for (const [key, schema] of Object.entries(properties)) {
+        if (key in plainValue) {
+            output[key] = serializeWithSchema(plainValue[key], schema);
+        }
+    }
+    return output;
+}
+function serializeRecord(value, schema) {
+    const output = { ...value };
+    for (const [key, entry] of Object.entries(value)) {
+        output[key] = serializeWithSchema(entry, schema);
+    }
+    return output;
+}
+function serializeUnion(value, options) {
+    for (const option of options) {
+        const serialized = serializeWithSchema(value, option);
+        if (serialized !== value) {
+            return serialized;
+        }
+    }
+    return value;
+}
+function isSchemaNode(value) {
+    return !!value && typeof value === "object" && "kind" in value;
+}
+function isPlainObject(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        !(value instanceof Date));
+}
+function toPlainObject(value) {
+    // 1. Check if value has custom toJSON method (e.g., metal-orm entities)
+    if (value !== null &&
+        typeof value === "object" &&
+        typeof value.toJSON === "function") {
+        // Use the custom toJSON which handles circular refs and includes properly
+        const jsonResult = value.toJSON();
+        return jsonResult;
+    }
+    // 2. Handle lazy-load wrappers (BelongsToReference)
+    if (typeof value === "object" && typeof value.load === "function") {
+        const wrapper = value;
+        if (wrapper.current !== undefined && wrapper.current !== null) {
+            return toPlainObject(wrapper.current);
+        }
+        if (wrapper.loaded) {
+            return null;
+        }
+        return null;
+    }
+    // 3. Handle plain objects
+    if (isPlainObject(value)) {
+        return value;
+    }
+    // 4. Convert class instances to plain objects
+    if (typeof value === "object") {
+        const result = {};
+        for (const key of Object.getOwnPropertyNames(value)) {
+            if (key.startsWith('_') || key === 'constructor' || key === 'prototype')
+                continue;
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (descriptor && descriptor.enumerable) {
+                const propertyValue = value[key];
+                result[key] = propertyValue;
+            }
+        }
+        return result;
+    }
+    return null;
+}

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

@@ -0,0 +1,100 @@
+import type { Constructor, RequestContext as CoreRequestContext, UploadedFileInfo } from "../../core/types";
+import type { OpenApiInfo, OpenApiServer } from "../../core/openapi";
+/**
+ * Request context provided to Fastify route handlers.
+ */
+export type RequestContext<TBody = any, TQuery extends object | undefined = Record<string, any>, TParams extends object | undefined = Record<string, any>, THeaders extends object | undefined = Record<string, any>, TFiles extends Record<string, UploadedFileInfo | UploadedFileInfo[]> | undefined = any> = CoreRequestContext<TBody, TQuery, TParams, THeaders, TFiles>;
+/**
+ * Input coercion modes.
+ */
+export type InputCoercionMode = "safe" | "strict";
+/**
+ * Input coercion setting - can be a mode or disabled.
+ */
+export type InputCoercionSetting = InputCoercionMode | false;
+/**
+ * CORS configuration options.
+ */
+export interface CorsOptions {
+    /** Allowed origins. Use "*" for all, a string, array of strings, or a function for dynamic matching. */
+    origin?: string | string[] | ((origin: string | undefined) => boolean | string);
+    /** Allowed HTTP methods. Defaults to ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"]. */
+    methods?: string[];
+    /** Allowed headers. Defaults to ["Content-Type", "Authorization"]. */
+    allowedHeaders?: string[];
+    /** Headers exposed to the client. */
+    exposedHeaders?: string[];
+    /** Whether to include credentials (cookies, authorization headers). Defaults to false. */
+    credentials?: boolean;
+    /** Max age in seconds for preflight cache. Defaults to 86400 (24 hours). */
+    maxAge?: number;
+}
+/**
+ * Options for OpenAPI documentation UI.
+ */
+export interface OpenApiDocsOptions {
+    /** Path for documentation UI */
+    path?: string;
+    /** Title for documentation page */
+    title?: string;
+    /** URL for Swagger UI assets */
+    swaggerUiUrl?: string;
+}
+/**
+ * OpenAPI configuration for Fastify adapter.
+ */
+export interface OpenApiFastifyOptions {
+    /** OpenAPI document info */
+    info: OpenApiInfo;
+    /** Array of servers */
+    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;
+}
+/**
+ * Multipart file upload configuration.
+ */
+export interface MultipartOptions {
+    /** Storage type: 'memory' or 'disk' (Fastify adapter mainly supports memory via @fastify/multipart) */
+    storage?: "memory" | "disk";
+    /** Directory for disk storage (defaults to OS temp directory) */
+    dest?: string;
+    /** Maximum file size in bytes (defaults to 10MB) */
+    maxFileSize?: number;
+    /** Maximum number of files per field (defaults to 10) */
+    maxFiles?: number;
+}
+/**
+ * Validation configuration options.
+ */
+export interface ValidationOptions {
+    /** Whether validation is enabled. Defaults to true. */
+    enabled?: boolean;
+    /** Validation mode. 'strict' mode fails on any validation error, 'lax' mode may allow some errors. Defaults to 'strict'. */
+    mode?: 'strict' | 'lax';
+}
+/**
+ * Options for creating a Fastify application adapter.
+ */
+export interface FastifyAdapterOptions {
+    /** Array of controller classes */
+    controllers: Constructor[];
+    /** Whether to enable JSON body parsing */
+    jsonBody?: boolean;
+    /** Max JSON body size (e.g. 1048576 for 1MB). */
+    bodyLimit?: number;
+    /** OpenAPI configuration */
+    openApi?: OpenApiFastifyOptions;
+    /** Input coercion setting */
+    inputCoercion?: InputCoercionSetting;
+    /** CORS configuration. Set to true for permissive defaults, or provide options. */
+    cors?: boolean | CorsOptions;
+    /** Multipart file upload configuration. Set to true for defaults, or provide options. */
+    multipart?: boolean | MultipartOptions;
+    /** Validation configuration. Set to false to disable validation, or provide options. */
+    validation?: boolean | ValidationOptions;
+}

package/dist/adapter/fastify/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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/dist/adapter/native/coercion.d.ts

@@ -0,0 +1,12 @@
+import { type InputMeta } from "../../core/metadata";
+import type { InputCoercionMode } from "./types";
+export type InputLocation = "params" | "query" | "body";
+interface CoerceInputOptions {
+    mode: InputCoercionMode;
+    location: InputLocation;
+}
+/**
+ * Creates an input coercer function for the given input metadata.
+ */
+export declare function createInputCoercer<T extends Record<string, unknown> = Record<string, unknown>>(input: InputMeta | undefined, options: CoerceInputOptions): ((value: T) => T) | undefined;
+export {};