adorn-api 1.0.23 → 1.0.24

package/src/core/metadata.ts

@@ -0,0 +1,110 @@
+import type { SchemaNode, SchemaSource } from "./schema";
+import type { Constructor, DtoConstructor, HttpMethod } from "./types";
+
+export interface FieldMeta {
+  schema: SchemaNode;
+  optional?: boolean;
+  description?: string;
+}
+
+export interface DtoMeta {
+  name: string;
+  description?: string;
+  fields: Record<string, FieldMeta>;
+  additionalProperties?: boolean;
+}
+
+export interface InputMeta {
+  schema: SchemaSource;
+  description?: string;
+  required?: boolean;
+  contentType?: string;
+}
+
+export interface ResponseMeta {
+  status: number;
+  schema?: SchemaSource;
+  description?: string;
+  contentType?: string;
+  error?: boolean;
+}
+
+export interface RouteMeta {
+  httpMethod: HttpMethod;
+  path: string;
+  handlerName: string | symbol;
+  summary?: string;
+  description?: string;
+  tags?: string[];
+  body?: InputMeta;
+  query?: InputMeta;
+  params?: InputMeta;
+  headers?: InputMeta;
+  responses: ResponseMeta[];
+}
+
+export interface ControllerMeta {
+  basePath: string;
+  controller: Constructor;
+  routes: RouteMeta[];
+  tags?: string[];
+}
+
+const dtoStore = new Map<DtoConstructor, DtoMeta>();
+const controllerStore = new Map<Constructor, ControllerMeta>();
+
+export const META_KEY: unique symbol = Symbol.for("adorn.metadata");
+
+export interface DecoratorMetadata {
+  [META_KEY]?: AdornMetadata;
+}
+
+export interface AdornMetadata {
+  dtoFields?: Record<string, FieldMeta>;
+  dtoOptions?: {
+    name?: string;
+    description?: string;
+    additionalProperties?: boolean;
+  };
+  routes?: RouteMetaInput[];
+  controllerOptions?: {
+    path?: string;
+    tags?: string[];
+  };
+}
+
+export interface RouteMetaInput extends Partial<RouteMeta> {
+  handlerName: string | symbol;
+  responses: ResponseMeta[];
+}
+
+export function getAdornMetadata(metadata: DecoratorMetadata): AdornMetadata {
+  if (!metadata[META_KEY]) {
+    metadata[META_KEY] = {};
+  }
+  return metadata[META_KEY]!;
+}
+
+export function registerDto(dto: DtoConstructor, meta: DtoMeta): void {
+  dtoStore.set(dto, meta);
+}
+
+export function getDtoMeta(dto: DtoConstructor): DtoMeta | undefined {
+  return dtoStore.get(dto);
+}
+
+export function getAllDtos(): Array<[DtoConstructor, DtoMeta]> {
+  return Array.from(dtoStore.entries());
+}
+
+export function registerController(meta: ControllerMeta): void {
+  controllerStore.set(meta.controller, meta);
+}
+
+export function getControllerMeta(controller: Constructor): ControllerMeta | undefined {
+  return controllerStore.get(controller);
+}
+
+export function getAllControllers(): Array<[Constructor, ControllerMeta]> {
+  return Array.from(controllerStore.entries());
+}

package/src/core/openapi.ts

@@ -0,0 +1,282 @@
+import type { JsonSchema, SchemaBuildContext } from "./schema-builder";
+import type { ControllerMeta, InputMeta, ResponseMeta } from "./metadata";
+import type { Constructor, DtoConstructor } from "./types";
+import {
+  createSchemaContext,
+  buildSchemaFromSource
+} from "./schema-builder";
+import { getAllControllers, getDtoMeta } from "./metadata";
+import type { SchemaNode, SchemaSource } from "./schema";
+
+/**
+ * OpenAPI document information.
+ */
+export interface OpenApiInfo {
+  /** API title */
+  title: string;
+  /** API version */
+  version: string;
+  /** API description */
+  description?: string;
+}
+
+/**
+ * OpenAPI server information.
+ */
+export interface OpenApiServer {
+  /** Server URL */
+  url: string;
+  /** Server description */
+  description?: string;
+}
+
+/**
+ * Options for building OpenAPI documents.
+ */
+export interface OpenApiOptions {
+  /** OpenAPI document information */
+  info: OpenApiInfo;
+  /** Array of servers */
+  servers?: OpenApiServer[];
+  /** Array of controllers to include */
+  controllers?: Constructor[];
+}
+
+/**
+ * OpenAPI document structure.
+ */
+export interface OpenApiDocument {
+  /** OpenAPI specification version */
+  openapi: "3.1.0";
+  /** JSON Schema dialect */
+  jsonSchemaDialect: string;
+  /** API information */
+  info: OpenApiInfo;
+  /** API servers */
+  servers?: OpenApiServer[];
+  /** API paths */
+  paths: Record<string, Record<string, unknown>>;
+  /** Reusable components */
+  components: {
+    /** Schema definitions */
+    schemas: Record<string, JsonSchema>;
+  };
+}
+
+/**
+ * Builds an OpenAPI document from controllers.
+ * @param options - OpenAPI build options
+ * @returns OpenAPI document
+ */
+export function buildOpenApi(options: OpenApiOptions): OpenApiDocument {
+  const context = createSchemaContext();
+
+  const controllers = filterControllers(options.controllers);
+  const paths: Record<string, Record<string, unknown>> = {};
+
+  for (const controller of controllers) {
+    const tagFallback = controller.meta.tags ?? [controller.meta.controller.name];
+    for (const route of controller.meta.routes) {
+      const fullPath = joinPaths(controller.meta.basePath, route.path);
+      const openApiPath = expressPathToOpenApi(fullPath);
+      const pathItem = (paths[openApiPath] ??= {});
+
+      const parameters = [
+        ...buildParameters("path", route.params, context),
+        ...buildParameters("query", route.query, context),
+        ...buildParameters("header", route.headers, context)
+      ];
+
+      const responses = buildResponses(route.responses, context);
+
+      pathItem[route.httpMethod] = {
+        operationId: `${controller.meta.controller.name}.${String(route.handlerName)}`,
+        summary: route.summary,
+        description: route.description,
+        tags: route.tags ?? tagFallback,
+        parameters: parameters.length ? parameters : undefined,
+        requestBody: buildRequestBody(route.body, context),
+        responses
+      };
+    }
+  }
+
+  return {
+    openapi: "3.1.0",
+    jsonSchemaDialect: "https://spec.openapis.org/oas/3.1/dialect/base",
+    info: options.info,
+    servers: options.servers,
+    paths,
+    components: {
+      schemas: context.components
+    }
+  };
+}
+
+function buildRequestBody(
+  body: InputMeta | undefined,
+  context: SchemaBuildContext
+): Record<string, unknown> | undefined {
+  if (!body) {
+    return undefined;
+  }
+  const contentType = body.contentType ?? "application/json";
+  const schema = buildSchemaFromSource(body.schema, context);
+  return {
+    required: body.required ?? true,
+    content: {
+      [contentType]: { schema }
+    }
+  };
+}
+
+function buildResponses(
+  responses: ResponseMeta[],
+  context: SchemaBuildContext
+): Record<string, unknown> {
+  const output: Record<string, unknown> = {};
+  for (const response of responses) {
+    const contentType = response.contentType ?? "application/json";
+    output[String(response.status)] = {
+      description: response.description ?? getDefaultStatusDescription(response.status),
+      content: response.schema
+        ? {
+            [contentType]: {
+              schema: buildSchemaFromSource(response.schema, context)
+            }
+          }
+        : undefined
+    };
+  }
+  return output;
+}
+
+function getDefaultStatusDescription(status: number): string {
+  switch (status) {
+    case 200:
+      return "OK";
+    case 201:
+      return "Created";
+    case 202:
+      return "Accepted";
+    case 204:
+      return "No Content";
+    case 400:
+      return "Bad Request";
+    case 401:
+      return "Unauthorized";
+    case 403:
+      return "Forbidden";
+    case 404:
+      return "Not Found";
+    case 409:
+      return "Conflict";
+    case 422:
+      return "Unprocessable Entity";
+    case 500:
+      return "Internal Server Error";
+    case 503:
+      return "Service Unavailable";
+    default:
+      return "OK";
+  }
+}
+
+function buildParameters(
+  location: "path" | "query" | "header",
+  input: InputMeta | undefined,
+  context: SchemaBuildContext
+): Array<Record<string, unknown>> {
+  if (!input) {
+    return [];
+  }
+  const fieldEntries = extractFields(input.schema);
+  if (!fieldEntries.length) {
+    return [];
+  }
+  return fieldEntries.map((entry) => ({
+    name: entry.name,
+    in: location,
+    required: location === "path" ? true : entry.required,
+    description: entry.description,
+    schema: buildSchemaFromSource(entry.schema, context)
+  }));
+}
+
+function extractFields(
+  schema: SchemaSource
+): Array<{ name: string; schema: SchemaSource; required: boolean; description?: string }> {
+  if (isSchemaNode(schema)) {
+    if (schema.kind === "object" && schema.properties) {
+      const required = new Set(schema.required ?? []);
+      return Object.entries(schema.properties).map(([name, value]) => ({
+        name,
+        schema: value,
+        required: required.has(name),
+        description: value.description
+      }));
+    }
+    return [
+      {
+        name: "value",
+        schema,
+        required: !schema.optional,
+        description: schema.description
+      }
+    ];
+  }
+
+  const dtoMeta = getDtoMetaSafe(schema);
+  return Object.entries(dtoMeta.fields).map(([name, field]) => ({
+    name,
+    schema: field.schema,
+    required: !(field.optional ?? field.schema.optional ?? false),
+    description: field.description ?? field.schema.description
+  }));
+}
+
+function getDtoMetaSafe(dto: DtoConstructor): {
+  fields: Record<string, { schema: SchemaNode; optional?: boolean; description?: string }>;
+} {
+  const meta = getDtoMeta(dto);
+  if (!meta) {
+    throw new Error(`DTO "${dto.name}" is missing @Dto decorator.`);
+  }
+  return meta;
+}
+
+function filterControllers(
+  controllers: Constructor[] | undefined
+): Array<{ meta: ControllerMeta }> {
+  const allControllers = getAllControllers();
+  if (!controllers?.length) {
+    return allControllers.map(([, meta]) => ({ meta }));
+  }
+  const set = new Set(controllers);
+  return allControllers
+    .filter(([controller]) => set.has(controller))
+    .map(([, meta]) => ({ meta }));
+}
+
+function joinPaths(basePath: string, routePath: string): string {
+  const base = basePath ? basePath.replace(/\/+$/, "") : "";
+  const route = routePath ? routePath.replace(/^\/+/, "") : "";
+  if (!base && !route) {
+    return "/";
+  }
+  if (!base) {
+    return `/${route}`;
+  }
+  if (!route) {
+    return base.startsWith("/") ? base : `/${base}`;
+  }
+  return `${base.startsWith("/") ? base : `/${base}`}/${route}`;
+}
+
+function expressPathToOpenApi(path: string): string {
+  return path.replace(/:([A-Za-z0-9_]+)/g, "{$1}");
+}
+
+function isSchemaNode(value: unknown): value is SchemaNode {
+  return !!value && typeof value === "object" && "kind" in (value as SchemaNode);
+}

package/src/core/schema-builder.ts

@@ -0,0 +1,287 @@
+import type { JsonPrimitive, SchemaNode, SchemaSource } from "./schema";
+import type { DtoConstructor } from "./types";
+import { getDtoMeta } from "./metadata";
+
+/**
+ * JSON Schema type.
+ */
+export type JsonSchema = Record<string, unknown>;
+
+/**
+ * Context for building schemas.
+ */
+export interface SchemaBuildContext {
+  /** Schema components */
+  components: Record<string, JsonSchema>;
+  /** Set of seen DTOs to avoid circular references */
+  seen: Set<DtoConstructor>;
+}
+
+/**
+ * Creates a new schema building context.
+ * @returns Schema build context
+ */
+export function createSchemaContext(): SchemaBuildContext {
+  return {
+    components: {},
+    seen: new Set()
+  };
+}
+
+/**
+ * Builds a JSON schema from a schema source.
+ * @param source - Schema source
+ * @param context - Schema build context
+ * @returns JSON schema
+ */
+export function buildSchemaFromSource(source: SchemaSource, context: SchemaBuildContext): JsonSchema {
+  if (isSchemaNode(source)) {
+    return buildSchemaFromNode(source, context);
+  }
+  return buildSchemaFromDto(source, context);
+}
+
+/**
+ * Builds a JSON schema from a DTO constructor.
+ * @param dto - DTO constructor
+ * @param context - Schema build context
+ * @returns JSON schema reference
+ */
+export function buildSchemaFromDto(dto: DtoConstructor, context: SchemaBuildContext): JsonSchema {
+  const name = ensureDtoComponent(dto, context);
+  return { $ref: `#/components/schemas/${name}` };
+}
+
+/**
+ * Ensures a DTO component is registered in the schema context.
+ * @param dto - DTO constructor
+ * @param context - Schema build context
+ * @returns Component name
+ */
+export function ensureDtoComponent(dto: DtoConstructor, context: SchemaBuildContext): string {
+  const dtoMeta = getDtoMeta(dto);
+  if (!dtoMeta) {
+    throw new Error(`DTO "${dto.name}" is missing @Dto decorator.`);
+  }
+  if (context.seen.has(dto)) {
+    return dtoMeta.name;
+  }
+  context.seen.add(dto);
+  context.components[dtoMeta.name] = buildDtoSchema(dtoMeta, context);
+  return dtoMeta.name;
+}
+
+/**
+ * Builds a JSON schema from DTO metadata.
+ * @param meta - DTO metadata
+ * @param context - Schema build context
+ * @returns JSON schema
+ */
+export function buildDtoSchema(
+  meta: { name: string; description?: string; fields: Record<string, { schema: SchemaNode; optional?: boolean; description?: string }>; additionalProperties?: boolean },
+  context: SchemaBuildContext
+): JsonSchema {
+  const properties: Record<string, JsonSchema> = {};
+  const required: string[] = [];
+
+  for (const [name, field] of Object.entries(meta.fields)) {
+    const schema = buildSchemaFromNode(field.schema, context);
+    if (field.description && !schema.description) {
+      schema.description = field.description;
+    }
+    properties[name] = schema;
+    const isOptional = field.optional ?? field.schema.optional ?? false;
+    if (!isOptional) {
+      required.push(name);
+    }
+  }
+
+  const dtoSchema: JsonSchema = {
+    type: "object",
+    properties,
+    additionalProperties: meta.additionalProperties ?? false
+  };
+
+  if (required.length) {
+    dtoSchema.required = required;
+  }
+  if (meta.description) {
+    dtoSchema.description = meta.description;
+  }
+
+  return dtoSchema;
+}
+
+/**
+ * Builds a JSON schema from a schema node.
+ * @param node - Schema node
+ * @param context - Schema build context
+ * @returns JSON schema
+ */
+export function buildSchemaFromNode(node: SchemaNode, context: SchemaBuildContext): JsonSchema {
+  let schema: JsonSchema;
+  switch (node.kind) {
+    case "string":
+      schema = {
+        type: "string",
+        format: node.format,
+        minLength: node.minLength,
+        maxLength: node.maxLength,
+        pattern: node.pattern
+      };
+      break;
+    case "number":
+    case "integer":
+      schema = {
+        type: node.kind,
+        minimum: node.minimum,
+        maximum: node.maximum,
+        exclusiveMinimum: node.exclusiveMinimum,
+        exclusiveMaximum: node.exclusiveMaximum,
+        multipleOf: node.multipleOf
+      };
+      break;
+    case "boolean":
+      schema = { type: "boolean" };
+      break;
+    case "array":
+      schema = {
+        type: "array",
+        items: buildSchemaFromNode(node.items, context),
+        minItems: node.minItems,
+        maxItems: node.maxItems,
+        uniqueItems: node.uniqueItems
+      };
+      break;
+    case "object":
+      schema = {
+        type: "object",
+        properties: node.properties
+          ? mapObjectSchemas(node.properties, context)
+          : undefined,
+        required: node.required,
+        additionalProperties:
+          typeof node.additionalProperties === "object"
+            ? buildSchemaFromNode(node.additionalProperties, context)
+            : node.additionalProperties,
+        minProperties: node.minProperties,
+        maxProperties: node.maxProperties
+      };
+      break;
+    case "enum":
+      schema = {
+        enum: node.values,
+        ...inferEnumType(node.values)
+      };
+      break;
+    case "literal":
+      schema = {
+        const: node.value,
+        ...inferLiteralType(node.value)
+      };
+      break;
+    case "union":
+      schema = {
+        anyOf: node.anyOf.map((entry) => buildSchemaFromNode(entry, context))
+      };
+      break;
+    case "record":
+      schema = {
+        type: "object",
+        additionalProperties: buildSchemaFromNode(node.values, context)
+      };
+      break;
+    case "ref":
+      schema = buildSchemaFromDto(node.dto, context);
+      break;
+    case "any":
+      schema = {};
+      break;
+    case "null":
+      schema = { type: "null" };
+      break;
+    default:
+      schema = {};
+      break;
+  }
+
+  schema = applyBaseOptions(schema, node);
+  schema = applyNullable(schema, node);
+  return stripUndefined(schema);
+}
+
+function mapObjectSchemas(
+  properties: Record<string, SchemaNode>,
+  context: SchemaBuildContext
+): Record<string, JsonSchema> {
+  const mapped: Record<string, JsonSchema> = {};
+  for (const [key, value] of Object.entries(properties)) {
+    mapped[key] = buildSchemaFromNode(value, context);
+  }
+  return mapped;
+}
+
+function applyBaseOptions(schema: JsonSchema, node: SchemaNode): JsonSchema {
+  if (node.description) schema.description = node.description;
+  if (node.title) schema.title = node.title;
+  if (node.default !== undefined) schema.default = node.default;
+  if (node.examples) schema.examples = node.examples;
+  if (node.deprecated !== undefined) schema.deprecated = node.deprecated;
+  if (node.readOnly !== undefined) schema.readOnly = node.readOnly;
+  if (node.writeOnly !== undefined) schema.writeOnly = node.writeOnly;
+  return schema;
+}
+
+function applyNullable(schema: JsonSchema, node: SchemaNode): JsonSchema {
+  if (!node.nullable) {
+    return schema;
+  }
+  if ("$ref" in schema) {
+    return { anyOf: [schema, { type: "null" }] };
+  }
+  if (schema.type && typeof schema.type === "string") {
+    return { ...schema, type: [schema.type, "null"] };
+  }
+  if (Array.isArray(schema.type)) {
+    const types = new Set(schema.type);
+    types.add("null");
+    return { ...schema, type: Array.from(types) };
+  }
+  return { anyOf: [schema, { type: "null" }] };
+}
+
+function inferEnumType(values: JsonPrimitive[]): JsonSchema {
+  const types = new Set<string>();
+  for (const value of values) {
+    if (value === null) {
+      types.add("null");
+    } else {
+      types.add(typeof value);
+    }
+  }
+  if (!types.size) {
+    return {};
+  }
+  const typeArray = Array.from(types);
+  return typeArray.length === 1 ? { type: typeArray[0] } : { type: typeArray };
+}
+
+function inferLiteralType(value: JsonPrimitive): JsonSchema {
+  if (value === null) {
+    return { type: "null" };
+  }
+  return { type: typeof value };
+}
+
+function stripUndefined(schema: JsonSchema): JsonSchema {
+  for (const [key, value] of Object.entries(schema)) {
+    if (value === undefined) {
+      delete schema[key];
+    }
+  }
+  return schema;
+}
+
+function isSchemaNode(value: unknown): value is SchemaNode {
+  return !!value && typeof value === "object" && "kind" in (value as SchemaNode);
+}