adorn-api 1.1.11 → 1.1.13

package/dist/adapter/native/coercion.js

@@ -0,0 +1,289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInputCoercer = createInputCoercer;
+const metadata_1 = require("../../core/metadata");
+const coerce_1 = require("../../core/coerce");
+const errors_1 = require("../../core/errors");
+/**
+ * Creates an input coercer function for the given input metadata.
+ */
+function createInputCoercer(input, options) {
+    if (!input) {
+        return undefined;
+    }
+    const fields = extractFields(input.schema);
+    if (!fields.length) {
+        return undefined;
+    }
+    return (value) => {
+        const result = coerceRecord(value, fields, options.mode);
+        if (options.mode === "strict" && result.invalidFields.length) {
+            throw new errors_1.HttpError(400, buildInvalidMessage(options.location, result.invalidFields));
+        }
+        return result.value;
+    };
+}
+function coerceRecord(value, fields, mode) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { value, invalidFields: [] };
+    }
+    const input = value;
+    let changed = false;
+    const output = { ...input };
+    const invalidFields = [];
+    for (const field of fields) {
+        if (!(field.name in input)) {
+            continue;
+        }
+        const original = input[field.name];
+        const result = coerceValue(original, field.schema, mode);
+        if (!result.ok && mode === "strict") {
+            invalidFields.push(field.name);
+        }
+        if (result.changed) {
+            output[field.name] = result.value;
+            changed = true;
+        }
+    }
+    return { value: changed ? output : value, invalidFields };
+}
+function coerceValue(value, schema, mode) {
+    switch (schema.kind) {
+        case "integer":
+            return coerceNumber(value, schema, true);
+        case "number":
+            return coerceNumber(value, schema, false);
+        case "boolean": {
+            return coerceBoolean(value);
+        }
+        case "string": {
+            return coerceString(value, schema);
+        }
+        case "array":
+            return coerceArrayValue(value, schema, mode);
+        case "object":
+            return coerceObjectValue(value, schema, mode);
+        case "record":
+            return coerceRecordValue(value, schema, mode);
+        case "ref":
+            return coerceRefValue(value, schema, mode);
+        case "union":
+            return coerceUnionValue(value, schema, mode);
+        default:
+            return { value, ok: true, changed: false };
+    }
+}
+function coerceNumber(value, schema, integer) {
+    if (!isPresent(value)) {
+        return { value, ok: true, changed: false };
+    }
+    const parsed = integer
+        ? coerce_1.coerce.integer(value, { min: schema.minimum, max: schema.maximum })
+        : coerce_1.coerce.number(value, { min: schema.minimum, max: schema.maximum });
+    if (parsed === undefined) {
+        return { value, ok: false, changed: false };
+    }
+    if (schema.exclusiveMinimum !== undefined && parsed <= schema.exclusiveMinimum) {
+        return { value, ok: false, changed: false };
+    }
+    if (schema.exclusiveMaximum !== undefined && parsed >= schema.exclusiveMaximum) {
+        return { value, ok: false, changed: false };
+    }
+    return { value: parsed, ok: true, changed: parsed !== value };
+}
+function coerceBoolean(value) {
+    if (!isPresent(value)) {
+        return { value, ok: true, changed: false };
+    }
+    const parsed = coerce_1.coerce.boolean(value);
+    if (parsed === undefined) {
+        return { value, ok: false, changed: false };
+    }
+    return { value: parsed, ok: true, changed: parsed !== value };
+}
+function coerceString(value, schema) {
+    if (!isPresent(value)) {
+        return { value, ok: true, changed: false };
+    }
+    if (schema.format === "date" || schema.format === "date-time") {
+        const parsed = parseDateValue(value);
+        if (!parsed) {
+            return { value, ok: false, changed: false };
+        }
+        return { value: parsed, ok: true, changed: parsed !== value };
+    }
+    const parsed = coerce_1.coerce.string(value);
+    if (parsed === undefined) {
+        return { value, ok: true, changed: false };
+    }
+    return { value: parsed, ok: true, changed: parsed !== value };
+}
+function parseDateValue(value) {
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? undefined : value;
+    }
+    const text = coerce_1.coerce.string(value);
+    if (text === undefined) {
+        return undefined;
+    }
+    const parsed = new Date(text);
+    if (Number.isNaN(parsed.getTime())) {
+        return undefined;
+    }
+    return parsed;
+}
+function coerceArrayValue(value, schema, mode) {
+    if (value === undefined || value === null) {
+        return { value, ok: true, changed: false };
+    }
+    let input;
+    let changed;
+    if (Array.isArray(value)) {
+        input = value;
+        changed = false;
+    }
+    else if (typeof value === "string" && value.includes(",")) {
+        input = value.split(",").map((s) => s.trim());
+        changed = true;
+    }
+    else {
+        input = [value];
+        changed = true;
+    }
+    let ok = true;
+    const output = input.map((entry) => {
+        const result = coerceValue(entry, schema.items, mode);
+        if (!result.ok) {
+            ok = false;
+        }
+        if (result.changed) {
+            changed = true;
+        }
+        return result.value;
+    });
+    return { value: changed ? output : value, ok, changed };
+}
+function coerceObjectValue(value, schema, mode) {
+    if (value === undefined || value === null) {
+        return { value, ok: true, changed: false };
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return { value, ok: mode === "safe", changed: false };
+    }
+    const properties = schema.properties ?? {};
+    const fields = Object.entries(properties).map(([name, fieldSchema]) => ({
+        name,
+        schema: fieldSchema
+    }));
+    if (!fields.length) {
+        return { value, ok: true, changed: false };
+    }
+    const result = coerceRecord(value, fields, mode);
+    return {
+        value: result.value,
+        ok: result.invalidFields.length === 0,
+        changed: result.value !== value
+    };
+}
+function coerceRecordValue(value, schema, mode) {
+    if (value === undefined || value === null) {
+        return { value, ok: true, changed: false };
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return { value, ok: mode === "safe", changed: false };
+    }
+    const input = value;
+    let changed = false;
+    let ok = true;
+    const output = { ...input };
+    for (const [key, entry] of Object.entries(input)) {
+        const result = coerceValue(entry, schema.values, mode);
+        if (!result.ok) {
+            ok = false;
+        }
+        if (result.changed) {
+            output[key] = result.value;
+            changed = true;
+        }
+    }
+    return { value: changed ? output : value, ok, changed };
+}
+function coerceRefValue(value, schema, mode) {
+    if (value === undefined || value === null) {
+        return { value, ok: true, changed: false };
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return { value, ok: mode === "safe", changed: false };
+    }
+    const meta = getDtoMetaSafe(schema.dto);
+    const fields = Object.entries(meta.fields).map(([name, field]) => ({
+        name,
+        schema: field.schema
+    }));
+    if (!fields.length) {
+        return { value, ok: true, changed: false };
+    }
+    const result = coerceRecord(value, fields, mode);
+    return {
+        value: result.value,
+        ok: result.invalidFields.length === 0,
+        changed: result.value !== value
+    };
+}
+function coerceUnionValue(value, schema, mode) {
+    let fallback;
+    for (const option of schema.anyOf) {
+        const result = coerceValue(value, option, mode);
+        if (!result.ok) {
+            continue;
+        }
+        if (result.changed) {
+            return result;
+        }
+        fallback ??= result;
+    }
+    if (fallback) {
+        return fallback;
+    }
+    return { value, ok: mode === "safe", changed: false };
+}
+function extractFields(schema) {
+    if (isSchemaNode(schema)) {
+        if (schema.kind === "object" && schema.properties) {
+            return Object.entries(schema.properties).map(([name, fieldSchema]) => ({
+                name,
+                schema: fieldSchema
+            }));
+        }
+        return [];
+    }
+    const meta = getDtoMetaSafe(schema);
+    return Object.entries(meta.fields).map(([name, field]) => ({
+        name,
+        schema: field.schema
+    }));
+}
+function getDtoMetaSafe(dto) {
+    const meta = (0, metadata_1.getDtoMeta)(dto);
+    if (!meta) {
+        throw new Error(`DTO "${dto.name}" is missing @Dto decorator.`);
+    }
+    return meta;
+}
+function isSchemaNode(value) {
+    return !!value && typeof value === "object" && "kind" in value;
+}
+function isPresent(value) {
+    return coerce_1.coerce.string(value) !== undefined;
+}
+function buildInvalidMessage(location, fields) {
+    let label = "query parameter";
+    if (location === "params") {
+        label = "path parameter";
+    }
+    else if (location === "body") {
+        label = "request body field";
+    }
+    const suffix = fields.length > 1 ? "s" : "";
+    return `Invalid ${label}${suffix}: ${fields.join(", ")}.`;
+}

package/dist/adapter/native/controllers.d.ts

@@ -0,0 +1,17 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Constructor } from "../../core/types";
+import type { InputCoercionSetting, ValidationOptions } from "./types";
+import { Router } from "./router";
+/**
+ * Registers controllers with a native application router.
+ */
+export declare function registerControllers(router: Router, controllers: Constructor[]): Promise<void>;
+/**
+ * Dispatches a native request to the appropriate controller handler.
+ */
+export declare function dispatchRequest(req: IncomingMessage, res: ServerResponse, match: any, options: {
+    inputCoercion: InputCoercionSetting;
+    validation?: boolean | ValidationOptions;
+    body?: any;
+    query?: Record<string, any>;
+}): Promise<void>;

package/dist/adapter/native/controllers.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerControllers = registerControllers;
+exports.dispatchRequest = dispatchRequest;
+const metadata_1 = require("../../core/metadata");
+const auth_1 = require("../../core/auth");
+const errors_1 = require("../../core/errors");
+const response_1 = require("../../core/response");
+const coercion_1 = require("./coercion");
+const response_serializer_1 = require("./response-serializer");
+const lifecycle_1 = require("../../core/lifecycle");
+const streaming_1 = require("../../core/streaming");
+const validation_1 = require("../../core/validation");
+const validation_errors_1 = require("../../core/validation-errors");
+/**
+ * Registers controllers with a native application router.
+ */
+async function registerControllers(router, controllers) {
+    for (const controller of controllers) {
+        const meta = (0, metadata_1.getControllerMeta)(controller);
+        if (!meta) {
+            throw new Error(`Controller "${controller.name}" is missing @Controller decorator.`);
+        }
+        const instance = new controller();
+        lifecycle_1.lifecycleRegistry.register(instance);
+        await lifecycle_1.lifecycleRegistry.callOnModuleInit(instance);
+        for (const route of meta.routes) {
+            router.add(instance, route, meta.basePath);
+        }
+    }
+}
+/**
+ * Dispatches a native request to the appropriate controller handler.
+ */
+async function dispatchRequest(req, res, match, options) {
+    const { controller: instance, route, params: rawParams } = match;
+    const { inputCoercion, validation, body: rawBody, query: rawQuery } = options;
+    const handler = instance[route.handlerName];
+    if (typeof handler !== "function") {
+        throw new Error(`Handler "${String(route.handlerName)}" is not a function.`);
+    }
+    const coerceParams = inputCoercion === false
+        ? undefined
+        : (0, coercion_1.createInputCoercer)(route.params, { mode: inputCoercion, location: "params" });
+    const coerceQuery = inputCoercion === false
+        ? undefined
+        : (0, coercion_1.createInputCoercer)(route.query, { mode: inputCoercion, location: "query" });
+    const coerceBody = inputCoercion === false
+        ? undefined
+        : (0, coercion_1.createInputCoercer)(route.body, { mode: inputCoercion, location: "body" });
+    const isValidationEnabled = validation !== false && validation?.enabled !== false;
+    const authMeta = (0, auth_1.getRouteAuthMeta)(instance.constructor, route.handlerName);
+    try {
+        // Apply auth guard if metadata exists
+        if (authMeta && authMeta.requiresAuth && !authMeta.isPublic) {
+            const user = req.user;
+            if (!user) {
+                throw new errors_1.HttpError(401, "Unauthorized");
+            }
+            if (authMeta.roles?.length) {
+                const hasRole = authMeta.roles.some((role) => user.roles?.includes(role));
+                if (!hasRole) {
+                    throw new errors_1.HttpError(403, "Insufficient permissions");
+                }
+            }
+            if (authMeta.allRoles?.length) {
+                const hasAllRoles = authMeta.allRoles.every((role) => user.roles?.includes(role));
+                if (!hasAllRoles) {
+                    throw new errors_1.HttpError(403, "Insufficient permissions");
+                }
+            }
+            if (authMeta.guard) {
+                const allowed = await authMeta.guard(user, req);
+                if (!allowed) {
+                    throw new errors_1.HttpError(403, "Access denied by guard");
+                }
+            }
+        }
+        const body = (coerceBody && rawBody) ? coerceBody(rawBody) : rawBody;
+        const query = (coerceQuery && rawQuery) ? coerceQuery(rawQuery) : rawQuery;
+        const params = (coerceParams && rawParams) ? coerceParams(rawParams) : rawParams;
+        if (isValidationEnabled) {
+            const validationErrors = [];
+            if (route.body) {
+                const bodyErrors = (0, validation_1.validate)(body, route.body.schema);
+                validationErrors.push(...bodyErrors);
+            }
+            if (route.query) {
+                const queryErrors = (0, validation_1.validate)(query, route.query.schema);
+                validationErrors.push(...queryErrors);
+            }
+            if (route.params) {
+                const paramsErrors = (0, validation_1.validate)(params, route.params.schema);
+                validationErrors.push(...paramsErrors);
+            }
+            if (route.headers) {
+                const headersErrors = (0, validation_1.validate)(req.headers, route.headers.schema);
+                validationErrors.push(...headersErrors);
+            }
+            if (validationErrors.length > 0) {
+                throw new validation_errors_1.ValidationErrors(validationErrors);
+            }
+        }
+        const ctx = {
+            req,
+            res,
+            body,
+            query,
+            params,
+            headers: req.headers,
+            files: undefined, // Native adapter doesn't support multipart yet
+            sse: route.sse ? (0, streaming_1.createSseEmitter)(res) : undefined,
+            stream: route.streaming || route.sse ? (0, streaming_1.createStreamWriter)(res) : undefined
+        };
+        const result = await handler.call(instance, ctx);
+        if (res.writableEnded || route.sse || route.streaming) {
+            return;
+        }
+        if ((0, response_1.isHttpResponse)(result)) {
+            if (result.headers) {
+                for (const [key, value] of Object.entries(result.headers)) {
+                    if (value !== undefined) {
+                        res.setHeader(key, value);
+                    }
+                }
+            }
+            if (result.body === undefined) {
+                res.statusCode = result.status;
+                res.end();
+            }
+            else if (route.raw) {
+                if (!res.getHeader("Content-Type")) {
+                    const ct = getResponseContentType(route) ?? "application/octet-stream";
+                    res.setHeader("Content-Type", ct);
+                }
+                res.statusCode = result.status;
+                res.end(result.body);
+            }
+            else {
+                const responseSchema = getResponseSchemaForStatus(route, result.status);
+                const output = responseSchema ? (0, response_serializer_1.serializeResponse)(result.body, responseSchema) : result.body;
+                res.statusCode = result.status;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify(output));
+            }
+            return;
+        }
+        if (result === undefined) {
+            res.statusCode = defaultStatus(route);
+            res.end();
+            return;
+        }
+        if (route.raw) {
+            if (!res.getHeader("Content-Type")) {
+                const ct = getResponseContentType(route) ?? "application/octet-stream";
+                res.setHeader("Content-Type", ct);
+            }
+            res.statusCode = defaultStatus(route);
+            res.end(result);
+        }
+        else {
+            const responseSchema = getResponseSchema(route);
+            const output = responseSchema ? (0, response_serializer_1.serializeResponse)(result, responseSchema) : result;
+            res.statusCode = defaultStatus(route);
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify(output));
+        }
+    }
+    catch (error) {
+        if ((0, validation_errors_1.isValidationErrors)(error)) {
+            res.statusCode = error.status;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify(error.body));
+            return;
+        }
+        if ((0, errors_1.isHttpError)(error)) {
+            if (error.headers) {
+                for (const [key, value] of Object.entries(error.headers)) {
+                    if (value !== undefined) {
+                        res.setHeader(key, value);
+                    }
+                }
+            }
+            const body = error.body ?? { message: error.message };
+            res.statusCode = error.status;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify(body));
+            return;
+        }
+        console.error("Unhandled error:", error);
+        res.statusCode = 500;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({ message: "Internal server error" }));
+    }
+}
+function defaultStatus(route) {
+    const responses = route.responses ?? [];
+    const success = responses.find((response) => !response.error && response.status < 400);
+    return success?.status ?? 200;
+}
+function getResponseSchema(route) {
+    const responses = route.responses ?? [];
+    const success = responses.find((response) => !response.error && response.status < 400);
+    return success?.schema;
+}
+function getResponseContentType(route) {
+    const responses = route.responses ?? [];
+    const success = responses.find((r) => !r.error && r.status < 400);
+    return success?.contentType;
+}
+function getResponseSchemaForStatus(route, status) {
+    const responses = route.responses ?? [];
+    const response = responses.find((r) => r.status === status);
+    return response?.schema;
+}

package/dist/adapter/native/index.d.ts

@@ -0,0 +1,14 @@
+import type { NativeAdapterOptions, NativeApp } from "./types";
+export * from "./types";
+export { registerControllers as attachControllers } from "./controllers";
+export { registerOpenApi as attachOpenApi } from "./openapi";
+/**
+ * Creates a native Node.js application with Adorn controllers.
+ * @param options - Native adapter options
+ * @returns Native application object
+ */
+export declare function createNativeApp(options: NativeAdapterOptions): Promise<NativeApp>;
+/**
+ * Trigger shutdown hooks for graceful application shutdown.
+ */
+export declare function shutdownApp(signal?: string): Promise<void>;

package/dist/adapter/native/index.js

@@ -0,0 +1,127 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachOpenApi = exports.attachControllers = void 0;
+exports.createNativeApp = createNativeApp;
+exports.shutdownApp = shutdownApp;
+const node_http_1 = require("node:http");
+const controllers_1 = require("./controllers");
+const openapi_1 = require("./openapi");
+const lifecycle_1 = require("../../core/lifecycle");
+const router_1 = require("./router");
+__exportStar(require("./types"), exports);
+var controllers_2 = require("./controllers");
+Object.defineProperty(exports, "attachControllers", { enumerable: true, get: function () { return controllers_2.registerControllers; } });
+var openapi_2 = require("./openapi");
+Object.defineProperty(exports, "attachOpenApi", { enumerable: true, get: function () { return openapi_2.registerOpenApi; } });
+/**
+ * Creates a native Node.js application with Adorn controllers.
+ * @param options - Native adapter options
+ * @returns Native application object
+ */
+async function createNativeApp(options) {
+    const router = new router_1.Router();
+    const inputCoercion = options.inputCoercion ?? "safe";
+    await (0, controllers_1.registerControllers)(router, options.controllers);
+    if (options.openApi) {
+        (0, openapi_1.registerOpenApi)(router, options.controllers, options.openApi);
+    }
+    const handle = async (req, res) => {
+        const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+        const match = router.match(req.method || "GET", url.pathname);
+        if (!match) {
+            res.statusCode = 404;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ message: `Not Found: ${req.method} ${url.pathname}` }));
+            return;
+        }
+        const query = {};
+        url.searchParams.forEach((value, key) => {
+            if (query[key]) {
+                if (Array.isArray(query[key])) {
+                    query[key].push(value);
+                }
+                else {
+                    query[key] = [query[key], value];
+                }
+            }
+            else {
+                query[key] = value;
+            }
+        });
+        let body = undefined;
+        if (options.jsonBody !== false && (req.method === "POST" || req.method === "PUT" || req.method === "PATCH")) {
+            try {
+                body = await parseJsonBody(req, options.bodyLimit);
+            }
+            catch (error) {
+                res.statusCode = 400;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({ message: "Invalid JSON body" }));
+                return;
+            }
+        }
+        await (0, controllers_1.dispatchRequest)(req, res, match, {
+            inputCoercion,
+            validation: options.validation,
+            body,
+            query
+        });
+    };
+    await lifecycle_1.lifecycleRegistry.callOnApplicationBootstrap();
+    return {
+        handle,
+        listen: (port, callback) => {
+            const server = (0, node_http_1.createServer)(handle);
+            return server.listen(port, callback);
+        }
+    };
+}
+/**
+ * Trigger shutdown hooks for graceful application shutdown.
+ */
+async function shutdownApp(signal) {
+    await lifecycle_1.lifecycleRegistry.callShutdownHooks(signal);
+    lifecycle_1.lifecycleRegistry.clear();
+}
+async function parseJsonBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        let size = 0;
+        req.on("data", (chunk) => {
+            data += chunk;
+            size += chunk.length;
+            if (limit && size > limit) {
+                reject(new Error("Body too large"));
+            }
+        });
+        req.on("end", () => {
+            if (!data) {
+                resolve(undefined);
+                return;
+            }
+            try {
+                resolve(JSON.parse(data));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        req.on("error", (err) => {
+            reject(err);
+        });
+    });
+}

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

@@ -0,0 +1,7 @@
+import type { Constructor } from "../../core/types";
+import type { OpenApiNativeOptions } from "./types";
+import type { Router } from "./router";
+/**
+ * Registers OpenAPI endpoints with a native application router.
+ */
+export declare function registerOpenApi(router: Router, controllers: Constructor[], options: OpenApiNativeOptions): void;