@warlock.js/core 5.25.0 → 5.27.0

package/esm/openapi/cast-schema.mjs

@@ -0,0 +1,89 @@
+//#region ../core/src/openapi/cast-schema.ts
+/**
+* JSON Schema of the DEFAULT date output of a resource field (`iso`, `format`, `timestamp`
+* and `humanTime` on; `timezone`, `locale` and `offset` off), matching `BaseCastOutput<"date">`.
+*/
+const DEFAULT_DATE_SCHEMA = {
+	type: "object",
+	properties: {
+		iso: {
+			type: "string",
+			format: "date-time"
+		},
+		format: { type: "string" },
+		timestamp: { type: "number" },
+		humanTime: { type: "string" }
+	},
+	required: [
+		"iso",
+		"format",
+		"timestamp",
+		"humanTime"
+	]
+};
+function baseCastSchema(base) {
+	switch (base) {
+		case "string":
+		case "localized": return { type: "string" };
+		case "url":
+		case "uploadsUrl":
+		case "storageUrl": return {
+			type: "string",
+			format: "uri"
+		};
+		case "number":
+		case "float": return { type: "number" };
+		case "int": return { type: "integer" };
+		case "boolean": return { type: "boolean" };
+		case "object": return { type: "object" };
+		case "array": return { type: "array" };
+		case "date": return structuredClone(DEFAULT_DATE_SCHEMA);
+		default: return;
+	}
+}
+/**
+* Make a schema accept `null` too, the 3.1 way: `type: [T, "null"]`. A schema without a plain
+* `type` (a `$ref`, `{}`) is wrapped in `anyOf` with `{ type: "null" }`.
+*/
+function makeNullable(schema) {
+	if (typeof schema.type === "string") return {
+		...schema,
+		type: [schema.type, "null"]
+	};
+	if (Array.isArray(schema.type)) return schema.type.includes("null") ? schema : {
+		...schema,
+		type: [...schema.type, "null"]
+	};
+	return { anyOf: [schema, { type: "null" }] };
+}
+/**
+* JSON Schema of a resource cast string, suffixes included (`"string"`, `"number?"`,
+* `"string[]"`, `"date[]?"`). `?` means "always present, value or null"; `[]` wraps the base
+* in an array, and with `?` it is the array that may be null.
+*
+* @returns `undefined` for a cast this mapper does not know.
+*/
+function castToJsonSchema(cast) {
+	let base = cast;
+	let nullable = false;
+	let isArray = false;
+	if (base.endsWith("?")) {
+		nullable = true;
+		base = base.slice(0, -1);
+	}
+	if (base.endsWith("[]")) {
+		isArray = true;
+		base = base.slice(0, -2);
+	}
+	const baseSchema = baseCastSchema(base);
+	if (!baseSchema) return;
+	const shaped = isArray ? {
+		type: "array",
+		items: baseSchema
+	} : baseSchema;
+	return nullable ? makeNullable(shaped) : shaped;
+}
+
+//#endregion
+export { castToJsonSchema };
+//# sourceMappingURL=cast-schema.mjs.map

package/esm/openapi/cast-schema.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cast-schema.mjs","names":[],"sources":["../../../../../../../core/src/openapi/cast-schema.ts"],"sourcesContent":["import type { OpenApiSchema } from \"./types\";\n\n/**\n * JSON Schema of the DEFAULT date output of a resource field (`iso`, `format`, `timestamp`\n * and `humanTime` on; `timezone`, `locale` and `offset` off), matching `BaseCastOutput<\"date\">`.\n */\nconst DEFAULT_DATE_SCHEMA: OpenApiSchema = {\n  type: \"object\",\n  properties: {\n    iso: { type: \"string\", format: \"date-time\" },\n    format: { type: \"string\" },\n    timestamp: { type: \"number\" },\n    humanTime: { type: \"string\" },\n  },\n  required: [\"iso\", \"format\", \"timestamp\", \"humanTime\"],\n};\n\nfunction baseCastSchema(base: string): OpenApiSchema | undefined {\n  switch (base) {\n    case \"string\":\n    case \"localized\":\n      return { type: \"string\" };\n    case \"url\":\n    case \"uploadsUrl\":\n    case \"storageUrl\":\n      return { type: \"string\", format: \"uri\" };\n    case \"number\":\n    case \"float\":\n      return { type: \"number\" };\n    case \"int\":\n      return { type: \"integer\" };\n    case \"boolean\":\n      return { type: \"boolean\" };\n    case \"object\":\n      return { type: \"object\" };\n    case \"array\":\n      return { type: \"array\" };\n    case \"date\":\n      return structuredClone(DEFAULT_DATE_SCHEMA);\n    default:\n      return undefined;\n  }\n}\n\n/**\n * Make a schema accept `null` too, the 3.1 way: `type: [T, \"null\"]`. A schema without a plain\n * `type` (a `$ref`, `{}`) is wrapped in `anyOf` with `{ type: \"null\" }`.\n */\nexport function makeNullable(schema: OpenApiSchema): OpenApiSchema {\n  if (typeof schema.type === \"string\") {\n    return { ...schema, type: [schema.type, \"null\"] };\n  }\n\n  if (Array.isArray(schema.type)) {\n    return schema.type.includes(\"null\") ? schema : { ...schema, type: [...schema.type, \"null\"] };\n  }\n\n  return { anyOf: [schema, { type: \"null\" }] };\n}\n\n/**\n * JSON Schema of a resource cast string, suffixes included (`\"string\"`, `\"number?\"`,\n * `\"string[]\"`, `\"date[]?\"`). `?` means \"always present, value or null\"; `[]` wraps the base\n * in an array, and with `?` it is the array that may be null.\n *\n * @returns `undefined` for a cast this mapper does not know.\n */\nexport function castToJsonSchema(cast: string): OpenApiSchema | undefined {\n  let base = cast;\n  let nullable = false;\n  let isArray = false;\n\n  if (base.endsWith(\"?\")) {\n    nullable = true;\n    base = base.slice(0, -1);\n  }\n\n  if (base.endsWith(\"[]\")) {\n    isArray = true;\n    base = base.slice(0, -2);\n  }\n\n  const baseSchema = baseCastSchema(base);\n\n  if (!baseSchema) {\n    return undefined;\n  }\n\n  const shaped: OpenApiSchema = isArray ? { type: \"array\", items: baseSchema } : baseSchema;\n\n  return nullable ? makeNullable(shaped) : shaped;\n}\n"],"mappings":";;;;;AAMA,MAAM,sBAAqC;CACzC,MAAM;CACN,YAAY;EACV,KAAK;GAAE,MAAM;GAAU,QAAQ;EAAY;EAC3C,QAAQ,EAAE,MAAM,SAAS;EACzB,WAAW,EAAE,MAAM,SAAS;EAC5B,WAAW,EAAE,MAAM,SAAS;CAC9B;CACA,UAAU;EAAC;EAAO;EAAU;EAAa;CAAW;AACtD;AAEA,SAAS,eAAe,MAAyC;CAC/D,QAAQ,MAAR;EACE,KAAK;EACL,KAAK,aACH,OAAO,EAAE,MAAM,SAAS;EAC1B,KAAK;EACL,KAAK;EACL,KAAK,cACH,OAAO;GAAE,MAAM;GAAU,QAAQ;EAAM;EACzC,KAAK;EACL,KAAK,SACH,OAAO,EAAE,MAAM,SAAS;EAC1B,KAAK,OACH,OAAO,EAAE,MAAM,UAAU;EAC3B,KAAK,WACH,OAAO,EAAE,MAAM,UAAU;EAC3B,KAAK,UACH,OAAO,EAAE,MAAM,SAAS;EAC1B,KAAK,SACH,OAAO,EAAE,MAAM,QAAQ;EACzB,KAAK,QACH,OAAO,gBAAgB,mBAAmB;EAC5C,SACE;CACJ;AACF;;;;;AAMA,SAAgB,aAAa,QAAsC;CACjE,IAAI,OAAO,OAAO,SAAS,UACzB,OAAO;EAAE,GAAG;EAAQ,MAAM,CAAC,OAAO,MAAM,MAAM;CAAE;CAGlD,IAAI,MAAM,QAAQ,OAAO,IAAI,GAC3B,OAAO,OAAO,KAAK,SAAS,MAAM,IAAI,SAAS;EAAE,GAAG;EAAQ,MAAM,CAAC,GAAG,OAAO,MAAM,MAAM;CAAE;CAG7F,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,EAAE;AAC7C;;;;;;;;AASA,SAAgB,iBAAiB,MAAyC;CACxE,IAAI,OAAO;CACX,IAAI,WAAW;CACf,IAAI,UAAU;CAEd,IAAI,KAAK,SAAS,GAAG,GAAG;EACtB,WAAW;EACX,OAAO,KAAK,MAAM,GAAG,EAAE;CACzB;CAEA,IAAI,KAAK,SAAS,IAAI,GAAG;EACvB,UAAU;EACV,OAAO,KAAK,MAAM,GAAG,EAAE;CACzB;CAEA,MAAM,aAAa,eAAe,IAAI;CAEtC,IAAI,CAAC,YACH;CAGF,MAAM,SAAwB,UAAU;EAAE,MAAM;EAAS,OAAO;CAAW,IAAI;CAE/E,OAAO,WAAW,aAAa,MAAM,IAAI;AAC3C"}

package/esm/openapi/collect-openapi-document.mjs

@@ -0,0 +1,40 @@
+import { runRegistrationChild } from "../production/registration-child-runner.mjs";
+import { OPENAPI_RESULT_MESSAGE, parseOpenApiChildResult } from "./openapi-protocol.mjs";
+
+//#region ../core/src/openapi/collect-openapi-document.ts
+/**
+* Build the app's OpenAPI document in a fresh process.
+*
+* Uses the same registration child as `warlock build` (it imports the route modules without
+* booting connectors) in OpenAPI mode: the document is built inside the child, where the Seal
+* schemas and resource classes live, and only the finished JSON crosses IPC.
+*/
+function collectOpenApiDocument(options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	const openapi = {
+		version: 1,
+		...options.title !== void 0 ? { title: options.title } : {},
+		...options.server !== void 0 ? { server: options.server } : {},
+		...options.includePages !== void 0 ? { includePages: options.includePages } : {}
+	};
+	return runRegistrationChild({
+		cwd,
+		timeoutMs: options.timeoutMs,
+		childEntry: options.childEntry,
+		forkProcess: options.forkProcess,
+		request: {
+			version: 1,
+			cwd,
+			environment: options.environment,
+			runtimeStrategy: options.runtimeStrategy,
+			openapi
+		},
+		resultMessageType: OPENAPI_RESULT_MESSAGE,
+		resultNoun: "document",
+		readResult: (message) => parseOpenApiChildResult(message.result)
+	});
+}
+
+//#endregion
+export { collectOpenApiDocument };
+//# sourceMappingURL=collect-openapi-document.mjs.map

package/esm/openapi/collect-openapi-document.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-openapi-document.mjs","names":[],"sources":["../../../../../../../core/src/openapi/collect-openapi-document.ts"],"sourcesContent":["import {\n  runRegistrationChild,\n  type RegistrationChildForker,\n} from \"../production/registration-child-runner\";\nimport type { Environment, RuntimeStrategy } from \"../utils/environment\";\nimport {\n  OPENAPI_PROTOCOL_VERSION,\n  OPENAPI_RESULT_MESSAGE,\n  parseOpenApiChildResult,\n  type OpenApiChildRequestOptions,\n  type OpenApiChildResult,\n} from \"./openapi-protocol\";\n\nexport type CollectOpenApiDocumentOptions = Readonly<{\n  cwd?: string;\n  environment?: Environment;\n  runtimeStrategy?: RuntimeStrategy;\n  timeoutMs?: number;\n  childEntry?: string;\n  forkProcess?: RegistrationChildForker;\n  title?: string;\n  server?: string;\n  includePages?: boolean;\n}>;\n\n/**\n * Build the app's OpenAPI document in a fresh process.\n *\n * Uses the same registration child as `warlock build` (it imports the route modules without\n * booting connectors) in OpenAPI mode: the document is built inside the child, where the Seal\n * schemas and resource classes live, and only the finished JSON crosses IPC.\n */\nexport function collectOpenApiDocument(\n  options: CollectOpenApiDocumentOptions = {},\n): Promise<OpenApiChildResult> {\n  const cwd = options.cwd ?? process.cwd();\n  const openapi: OpenApiChildRequestOptions = {\n    version: OPENAPI_PROTOCOL_VERSION,\n    ...(options.title !== undefined ? { title: options.title } : {}),\n    ...(options.server !== undefined ? { server: options.server } : {}),\n    ...(options.includePages !== undefined ? { includePages: options.includePages } : {}),\n  };\n\n  return runRegistrationChild<OpenApiChildResult>({\n    cwd,\n    timeoutMs: options.timeoutMs,\n    childEntry: options.childEntry,\n    forkProcess: options.forkProcess,\n    request: {\n      version: 1,\n      cwd,\n      environment: options.environment,\n      runtimeStrategy: options.runtimeStrategy,\n      openapi,\n    },\n    resultMessageType: OPENAPI_RESULT_MESSAGE,\n    resultNoun: \"document\",\n    readResult: (message) => parseOpenApiChildResult(message.result),\n  });\n}\n"],"mappings":";;;;;;;;;;;AAgCA,SAAgB,uBACd,UAAyC,CAAC,GACb;CAC7B,MAAM,MAAM,QAAQ,OAAO,QAAQ,IAAI;CACvC,MAAM,UAAsC;EAC1C;EACA,GAAI,QAAQ,UAAU,SAAY,EAAE,OAAO,QAAQ,MAAM,IAAI,CAAC;EAC9D,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;EACjE,GAAI,QAAQ,iBAAiB,SAAY,EAAE,cAAc,QAAQ,aAAa,IAAI,CAAC;CACrF;CAEA,OAAO,qBAAyC;EAC9C;EACA,WAAW,QAAQ;EACnB,YAAY,QAAQ;EACpB,aAAa,QAAQ;EACrB,SAAS;GACP,SAAS;GACT;GACA,aAAa,QAAQ;GACrB,iBAAiB,QAAQ;GACzB;EACF;EACA,mBAAmB;EACnB,YAAY;EACZ,aAAa,YAAY,wBAAwB,QAAQ,MAAM;CACjE,CAAC;AACH"}

package/esm/openapi/development-openapi-provider.d.mts

@@ -0,0 +1,17 @@
+import { OpenApiBuildResult } from "./types.mjs";
+
+//#region ../core/src/openapi/development-openapi-provider.d.ts
+type DevelopmentOpenApiProvider = () => Promise<OpenApiBuildResult>;
+/**
+ * Called by the dev server at startup. The builder lives under `dev-server/`, so the
+ * production entry never reaches it; this registry is the only thing the root exports.
+ */
+declare function registerDevelopmentOpenApiProvider(build: DevelopmentOpenApiProvider): void;
+/**
+ * The OpenAPI document for the routes registered in this process, built by the dev
+ * server's provider. Throws outside `warlock dev`, where no provider is registered.
+ */
+declare function getDevelopmentOpenApiDocument(): Promise<OpenApiBuildResult>;
+//#endregion
+export { getDevelopmentOpenApiDocument, registerDevelopmentOpenApiProvider };
+//# sourceMappingURL=development-openapi-provider.d.mts.map

package/esm/openapi/development-openapi-provider.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"development-openapi-provider.d.mts","names":[],"sources":["../../../../../../../core/src/openapi/development-openapi-provider.ts"],"mappings":";;;KAEK,0BAAA,SAAmC,OAAO,CAAC,kBAAA;;AAFE;;;iBAUlC,kCAAA,CAAmC,KAAiC,EAA1B,0BAA0B;AARlB;AAQlE;;;AARkE,iBAgB5C,6BAAA,IAAiC,OAAO,CAAC,kBAAA"}

package/esm/openapi/development-openapi-provider.mjs

@@ -0,0 +1,21 @@
+//#region ../core/src/openapi/development-openapi-provider.ts
+let provider;
+/**
+* Called by the dev server at startup. The builder lives under `dev-server/`, so the
+* production entry never reaches it; this registry is the only thing the root exports.
+*/
+function registerDevelopmentOpenApiProvider(build) {
+	provider = build;
+}
+/**
+* The OpenAPI document for the routes registered in this process, built by the dev
+* server's provider. Throws outside `warlock dev`, where no provider is registered.
+*/
+async function getDevelopmentOpenApiDocument() {
+	if (!provider) throw new Error("No development OpenAPI provider is registered; the API docs are only available under `warlock dev`.");
+	return provider();
+}
+
+//#endregion
+export { getDevelopmentOpenApiDocument, registerDevelopmentOpenApiProvider };
+//# sourceMappingURL=development-openapi-provider.mjs.map

package/esm/openapi/development-openapi-provider.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"development-openapi-provider.mjs","names":[],"sources":["../../../../../../../core/src/openapi/development-openapi-provider.ts"],"sourcesContent":["import type { OpenApiBuildResult } from \"./types\";\n\ntype DevelopmentOpenApiProvider = () => Promise<OpenApiBuildResult>;\n\nlet provider: DevelopmentOpenApiProvider | undefined;\n\n/**\n * Called by the dev server at startup. The builder lives under `dev-server/`, so the\n * production entry never reaches it; this registry is the only thing the root exports.\n */\nexport function registerDevelopmentOpenApiProvider(build: DevelopmentOpenApiProvider): void {\n  provider = build;\n}\n\n/**\n * The OpenAPI document for the routes registered in this process, built by the dev\n * server's provider. Throws outside `warlock dev`, where no provider is registered.\n */\nexport async function getDevelopmentOpenApiDocument(): Promise<OpenApiBuildResult> {\n  if (!provider) {\n    throw new Error(\n      \"No development OpenAPI provider is registered; the API docs are only available under `warlock dev`.\",\n    );\n  }\n\n  return provider();\n}\n"],"mappings":";AAIA,IAAI;;;;;AAMJ,SAAgB,mCAAmC,OAAyC;CAC1F,WAAW;AACb;;;;;AAMA,eAAsB,gCAA6D;CACjF,IAAI,CAAC,UACH,MAAM,IAAI,MACR,qGACF;CAGF,OAAO,SAAS;AAClB"}

package/esm/openapi/error-responses.mjs

@@ -0,0 +1,67 @@
+import { describeStatus } from "./response-schemas.mjs";
+
+//#region ../core/src/openapi/error-responses.ts
+const DEFAULT_VALIDATION_RESPONSE = {
+	errors: "errors",
+	inputKey: "input",
+	inputError: "error",
+	status: 422
+};
+/**
+* The `validation.response` config over its documented defaults, as `Response.failedSchema`
+* reads it.
+*/
+function resolveValidationResponse(config) {
+	const merged = { ...DEFAULT_VALIDATION_RESPONSE };
+	if (typeof config?.errors === "string" && config.errors) merged.errors = config.errors;
+	if (typeof config?.inputKey === "string" && config.inputKey) merged.inputKey = config.inputKey;
+	if (typeof config?.inputError === "string" && config.inputError) merged.inputError = config.inputError;
+	if (typeof config?.status === "number" && Number.isInteger(config.status)) merged.status = config.status;
+	return merged;
+}
+/**
+* The failed-validation response: `{ [errors]: [{ [inputKey]: string, [inputError]: string }] }`
+* under the configured status. The body is a shared component, emitted once.
+*/
+function buildValidationFailedResponse(shape, registry) {
+	const ref = registry.shared("ValidationFailed", {
+		type: "object",
+		properties: { [shape.errors]: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					[shape.inputKey]: { type: "string" },
+					[shape.inputError]: { type: "string" }
+				},
+				required: [shape.inputKey, shape.inputError]
+			}
+		} },
+		required: [shape.errors]
+	});
+	return {
+		status: String(shape.status),
+		response: {
+			description: describeStatus("422"),
+			content: { "application/json": { schema: ref } }
+		}
+	};
+}
+/**
+* The 401 response of a guarded route: the conventional `{ error: string }` body.
+*/
+function buildUnauthorizedResponse(registry) {
+	const ref = registry.shared("Unauthorized", {
+		type: "object",
+		properties: { error: { type: "string" } },
+		required: ["error"]
+	});
+	return {
+		description: describeStatus("401"),
+		content: { "application/json": { schema: ref } }
+	};
+}
+
+//#endregion
+export { buildUnauthorizedResponse, buildValidationFailedResponse, resolveValidationResponse };
+//# sourceMappingURL=error-responses.mjs.map

package/esm/openapi/error-responses.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-responses.mjs","names":[],"sources":["../../../../../../../core/src/openapi/error-responses.ts"],"sourcesContent":["import { describeStatus } from \"./response-schemas\";\nimport type { SchemaRegistry } from \"./schema-registry\";\nimport type { OpenApiResponse, OpenApiValidationResponseConfig } from \"./types\";\n\nconst DEFAULT_VALIDATION_RESPONSE = {\n  errors: \"errors\",\n  inputKey: \"input\",\n  inputError: \"error\",\n  status: 422,\n};\n\nexport type ValidationResponseShape = typeof DEFAULT_VALIDATION_RESPONSE;\n\n/**\n * The `validation.response` config over its documented defaults, as `Response.failedSchema`\n * reads it.\n */\nexport function resolveValidationResponse(\n  config: OpenApiValidationResponseConfig | undefined,\n): ValidationResponseShape {\n  const merged = { ...DEFAULT_VALIDATION_RESPONSE };\n\n  if (typeof config?.errors === \"string\" && config.errors) {\n    merged.errors = config.errors;\n  }\n\n  if (typeof config?.inputKey === \"string\" && config.inputKey) {\n    merged.inputKey = config.inputKey;\n  }\n\n  if (typeof config?.inputError === \"string\" && config.inputError) {\n    merged.inputError = config.inputError;\n  }\n\n  if (typeof config?.status === \"number\" && Number.isInteger(config.status)) {\n    merged.status = config.status;\n  }\n\n  return merged;\n}\n\n/**\n * The failed-validation response: `{ [errors]: [{ [inputKey]: string, [inputError]: string }] }`\n * under the configured status. The body is a shared component, emitted once.\n */\nexport function buildValidationFailedResponse(\n  shape: ValidationResponseShape,\n  registry: SchemaRegistry,\n): { status: string; response: OpenApiResponse } {\n  const ref = registry.shared(\"ValidationFailed\", {\n    type: \"object\",\n    properties: {\n      [shape.errors]: {\n        type: \"array\",\n        items: {\n          type: \"object\",\n          properties: {\n            [shape.inputKey]: { type: \"string\" },\n            [shape.inputError]: { type: \"string\" },\n          },\n          required: [shape.inputKey, shape.inputError],\n        },\n      },\n    },\n    required: [shape.errors],\n  });\n\n  return {\n    status: String(shape.status),\n    response: {\n      description: describeStatus(\"422\"),\n      content: { \"application/json\": { schema: ref } },\n    },\n  };\n}\n\n/**\n * The 401 response of a guarded route: the conventional `{ error: string }` body.\n */\nexport function buildUnauthorizedResponse(registry: SchemaRegistry): OpenApiResponse {\n  const ref = registry.shared(\"Unauthorized\", {\n    type: \"object\",\n    properties: { error: { type: \"string\" } },\n    required: [\"error\"],\n  });\n\n  return {\n    description: describeStatus(\"401\"),\n    content: { \"application/json\": { schema: ref } },\n  };\n}\n"],"mappings":";;;AAIA,MAAM,8BAA8B;CAClC,QAAQ;CACR,UAAU;CACV,YAAY;CACZ,QAAQ;AACV;;;;;AAQA,SAAgB,0BACd,QACyB;CACzB,MAAM,SAAS,EAAE,GAAG,4BAA4B;CAEhD,IAAI,OAAO,QAAQ,WAAW,YAAY,OAAO,QAC/C,OAAO,SAAS,OAAO;CAGzB,IAAI,OAAO,QAAQ,aAAa,YAAY,OAAO,UACjD,OAAO,WAAW,OAAO;CAG3B,IAAI,OAAO,QAAQ,eAAe,YAAY,OAAO,YACnD,OAAO,aAAa,OAAO;CAG7B,IAAI,OAAO,QAAQ,WAAW,YAAY,OAAO,UAAU,OAAO,MAAM,GACtE,OAAO,SAAS,OAAO;CAGzB,OAAO;AACT;;;;;AAMA,SAAgB,8BACd,OACA,UAC+C;CAC/C,MAAM,MAAM,SAAS,OAAO,oBAAoB;EAC9C,MAAM;EACN,YAAY,GACT,MAAM,SAAS;GACd,MAAM;GACN,OAAO;IACL,MAAM;IACN,YAAY;MACT,MAAM,WAAW,EAAE,MAAM,SAAS;MAClC,MAAM,aAAa,EAAE,MAAM,SAAS;IACvC;IACA,UAAU,CAAC,MAAM,UAAU,MAAM,UAAU;GAC7C;EACF,EACF;EACA,UAAU,CAAC,MAAM,MAAM;CACzB,CAAC;CAED,OAAO;EACL,QAAQ,OAAO,MAAM,MAAM;EAC3B,UAAU;GACR,aAAa,eAAe,KAAK;GACjC,SAAS,EAAE,oBAAoB,EAAE,QAAQ,IAAI,EAAE;EACjD;CACF;AACF;;;;AAKA,SAAgB,0BAA0B,UAA2C;CACnF,MAAM,MAAM,SAAS,OAAO,gBAAgB;EAC1C,MAAM;EACN,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,EAAE;EACxC,UAAU,CAAC,OAAO;CACpB,CAAC;CAED,OAAO;EACL,aAAa,eAAe,KAAK;EACjC,SAAS,EAAE,oBAAoB,EAAE,QAAQ,IAAI,EAAE;CACjD;AACF"}

package/esm/openapi/index.d.mts

@@ -0,0 +1,3 @@
+import { AuthDescriptor, OpenApiBuildResult, OpenApiComponents, OpenApiContext, OpenApiDocument, OpenApiOperation, OpenApiParameter, OpenApiRequestBody, OpenApiResponse, OpenApiRouteInput, OpenApiSchema, OpenApiSecurityRequirement, OpenApiSecurityScheme, OpenApiValidationResponseConfig, WarningSink } from "./types.mjs";
+import { getDevelopmentOpenApiDocument, registerDevelopmentOpenApiProvider } from "./development-openapi-provider.mjs";
+import { OPENAPI_JSON_SCHEMA_DIALECT, buildOpenApiDocument } from "./build-openapi-document.mjs";

package/esm/openapi/index.mjs

@@ -0,0 +1,4 @@
+import { getDevelopmentOpenApiDocument, registerDevelopmentOpenApiProvider } from "./development-openapi-provider.mjs";
+import { OPENAPI_JSON_SCHEMA_DIALECT, buildOpenApiDocument } from "./build-openapi-document.mjs";
+
+export {  };

package/esm/openapi/openapi-child-output.mjs

@@ -0,0 +1,57 @@
+import { httpConfig } from "../http/config.mjs";
+import { router } from "../router/router.mjs";
+import { buildOpenApiDocument } from "./build-openapi-document.mjs";
+import { collectResourceExportMap } from "../router/named-api-routes-with-responses.mjs";
+import config from "@mongez/config";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+
+//#region ../core/src/openapi/openapi-child-output.ts
+async function readAppPackage(cwd) {
+	try {
+		return JSON.parse(await readFile(path.join(cwd, "package.json"), "utf8"));
+	} catch {
+		return {};
+	}
+}
+function stringOr(value, fallback) {
+	return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+/**
+* `http://<host>:<port>` from the `http` config. A wildcard bind address is not a place a
+* client can call, so it becomes `localhost`.
+*/
+function resolveDefaultServer() {
+	const host = stringOr(httpConfig("host"), "localhost");
+	const port = httpConfig("port");
+	return `http://${host === "0.0.0.0" || host === "::" ? "localhost" : host}${typeof port === "number" || typeof port === "string" ? `:${port}` : ""}`;
+}
+/**
+* Build the OpenAPI document from the routes registered in THIS process.
+*
+* Runs inside the registration child, after the app's route modules are loaded and config is
+* available. Maps resource classes to their export names, reads `info` from the app
+* `package.json`, the server from the `http` config and the 422 shape from
+* `validation.response`.
+*/
+async function buildOpenApiForChild(options) {
+	const routes = router.list();
+	const resourceMap = routes.some((route) => route.handler?.responseSchema) ? await collectResourceExportMap(options.files, options.onWarn) : void 0;
+	const pkg = await readAppPackage(options.cwd);
+	const validationResponse = config.get("validation.response", {});
+	return buildOpenApiDocument(routes, {
+		info: {
+			title: options.request.title ?? stringOr(pkg.name, "Warlock API"),
+			version: stringOr(pkg.version, "0.0.0"),
+			...typeof pkg.description === "string" && pkg.description ? { description: pkg.description } : {}
+		},
+		servers: [options.request.server ?? resolveDefaultServer()],
+		includePages: options.request.includePages === true,
+		resolveResourceName: (resource) => resourceMap?.get(resource)?.exportName,
+		validationResponse
+	});
+}
+
+//#endregion
+export { buildOpenApiForChild, resolveDefaultServer };
+//# sourceMappingURL=openapi-child-output.mjs.map

package/esm/openapi/openapi-child-output.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-child-output.mjs","names":[],"sources":["../../../../../../../core/src/openapi/openapi-child-output.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { readFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { httpConfig } from \"../http/config\";\nimport {\n  collectResourceExportMap,\n  type ResourceSourceFile,\n} from \"../router/named-api-routes-with-responses\";\nimport { router } from \"../router/router\";\nimport { buildOpenApiDocument } from \"./build-openapi-document\";\nimport type { OpenApiChildRequestOptions } from \"./openapi-protocol\";\nimport type { OpenApiBuildResult, OpenApiValidationResponseConfig } from \"./types\";\n\nexport type BuildOpenApiForChildOptions = Readonly<{\n  /** Application root (the child's cwd). */\n  cwd: string;\n  /** Every source file the orchestrator knows; `*.resource.ts(x)` ones are mapped to exports. */\n  files: Iterable<ResourceSourceFile>;\n  request: OpenApiChildRequestOptions;\n  onWarn?: (message: string) => void;\n}>;\n\ntype AppPackage = { name?: unknown; version?: unknown; description?: unknown };\n\nasync function readAppPackage(cwd: string): Promise<AppPackage> {\n  try {\n    return JSON.parse(await readFile(path.join(cwd, \"package.json\"), \"utf8\")) as AppPackage;\n  } catch {\n    return {};\n  }\n}\n\nfunction stringOr(value: unknown, fallback: string): string {\n  return typeof value === \"string\" && value.length > 0 ? value : fallback;\n}\n\n/**\n * `http://<host>:<port>` from the `http` config. A wildcard bind address is not a place a\n * client can call, so it becomes `localhost`.\n */\nexport function resolveDefaultServer(): string {\n  const host = stringOr(httpConfig(\"host\"), \"localhost\");\n  const port = httpConfig(\"port\");\n  const callable = host === \"0.0.0.0\" || host === \"::\" ? \"localhost\" : host;\n\n  return `http://${callable}${typeof port === \"number\" || typeof port === \"string\" ? `:${port}` : \"\"}`;\n}\n\n/**\n * Build the OpenAPI document from the routes registered in THIS process.\n *\n * Runs inside the registration child, after the app's route modules are loaded and config is\n * available. Maps resource classes to their export names, reads `info` from the app\n * `package.json`, the server from the `http` config and the 422 shape from\n * `validation.response`.\n */\nexport async function buildOpenApiForChild(\n  options: BuildOpenApiForChildOptions,\n): Promise<OpenApiBuildResult> {\n  const routes = router.list();\n  const declaresSchema = routes.some((route) => route.handler?.responseSchema);\n  const resourceMap = declaresSchema\n    ? await collectResourceExportMap(options.files, options.onWarn)\n    : undefined;\n  const pkg = await readAppPackage(options.cwd);\n  const validationResponse = config.get(\n    \"validation.response\",\n    {},\n  ) as OpenApiValidationResponseConfig;\n\n  return buildOpenApiDocument(routes, {\n    info: {\n      title: options.request.title ?? stringOr(pkg.name, \"Warlock API\"),\n      version: stringOr(pkg.version, \"0.0.0\"),\n      ...(typeof pkg.description === \"string\" && pkg.description\n        ? { description: pkg.description }\n        : {}),\n    },\n    servers: [options.request.server ?? resolveDefaultServer()],\n    includePages: options.request.includePages === true,\n    resolveResourceName: (resource) => resourceMap?.get(resource)?.exportName,\n    validationResponse,\n  });\n}\n"],"mappings":";;;;;;;;;AAwBA,eAAe,eAAe,KAAkC;CAC9D,IAAI;EACF,OAAO,KAAK,MAAM,MAAM,SAAS,KAAK,KAAK,KAAK,cAAc,GAAG,MAAM,CAAC;CAC1E,QAAQ;EACN,OAAO,CAAC;CACV;AACF;AAEA,SAAS,SAAS,OAAgB,UAA0B;CAC1D,OAAO,OAAO,UAAU,YAAY,MAAM,SAAS,IAAI,QAAQ;AACjE;;;;;AAMA,SAAgB,uBAA+B;CAC7C,MAAM,OAAO,SAAS,WAAW,MAAM,GAAG,WAAW;CACrD,MAAM,OAAO,WAAW,MAAM;CAG9B,OAAO,UAFU,SAAS,aAAa,SAAS,OAAO,cAAc,OAEzC,OAAO,SAAS,YAAY,OAAO,SAAS,WAAW,IAAI,SAAS;AAClG;;;;;;;;;AAUA,eAAsB,qBACpB,SAC6B;CAC7B,MAAM,SAAS,OAAO,KAAK;CAE3B,MAAM,cADiB,OAAO,MAAM,UAAU,MAAM,SAAS,cAC5B,IAC7B,MAAM,yBAAyB,QAAQ,OAAO,QAAQ,MAAM,IAC5D;CACJ,MAAM,MAAM,MAAM,eAAe,QAAQ,GAAG;CAC5C,MAAM,qBAAqB,OAAO,IAChC,uBACA,CAAC,CACH;CAEA,OAAO,qBAAqB,QAAQ;EAClC,MAAM;GACJ,OAAO,QAAQ,QAAQ,SAAS,SAAS,IAAI,MAAM,aAAa;GAChE,SAAS,SAAS,IAAI,SAAS,OAAO;GACtC,GAAI,OAAO,IAAI,gBAAgB,YAAY,IAAI,cAC3C,EAAE,aAAa,IAAI,YAAY,IAC/B,CAAC;EACP;EACA,SAAS,CAAC,QAAQ,QAAQ,UAAU,qBAAqB,CAAC;EAC1D,cAAc,QAAQ,QAAQ,iBAAiB;EAC/C,sBAAsB,aAAa,aAAa,IAAI,QAAQ,CAAC,EAAE;EAC/D;CACF,CAAC;AACH"}

package/esm/openapi/openapi-protocol.mjs

@@ -0,0 +1,30 @@
+//#region ../core/src/openapi/openapi-protocol.ts
+/** Version of the OpenAPI mode of the registration child protocol. */
+const OPENAPI_PROTOCOL_VERSION = 1;
+/** `type` of the one message the child answers with in OpenAPI mode. */
+const OPENAPI_RESULT_MESSAGE = "openapi-registration:document";
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Validate the `openapi` request field inside the child. Throws on anything unexpected.
+*/
+function parseOpenApiChildOptions(value) {
+	if (!isRecord(value) || value.version !== 1 || !(value.title === void 0 || typeof value.title === "string") || !(value.server === void 0 || typeof value.server === "string") || !(value.includePages === void 0 || typeof value.includePages === "boolean")) throw new Error("Route registration child received an invalid OpenAPI request.");
+	return value;
+}
+/**
+* Validate the result message in the parent. Throws on anything unexpected.
+*/
+function parseOpenApiChildResult(value) {
+	if (!isRecord(value) || value.version !== 1 || !isRecord(value.document) || typeof value.document.openapi !== "string" || !isRecord(value.document.paths) || !Array.isArray(value.warnings) || !value.warnings.every((warning) => typeof warning === "string")) throw new Error("Route registration child sent an invalid OpenAPI document payload.");
+	return Object.freeze({
+		version: 1,
+		document: value.document,
+		warnings: Object.freeze([...value.warnings])
+	});
+}
+
+//#endregion
+export { OPENAPI_RESULT_MESSAGE, parseOpenApiChildOptions, parseOpenApiChildResult };
+//# sourceMappingURL=openapi-protocol.mjs.map

package/esm/openapi/openapi-protocol.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-protocol.mjs","names":[],"sources":["../../../../../../../core/src/openapi/openapi-protocol.ts"],"sourcesContent":["import type { OpenApiDocument } from \"./types\";\n\n/** Version of the OpenAPI mode of the registration child protocol. */\nexport const OPENAPI_PROTOCOL_VERSION = 1;\n\n/** `type` of the one message the child answers with in OpenAPI mode. */\nexport const OPENAPI_RESULT_MESSAGE = \"openapi-registration:document\";\n\n/**\n * The `openapi` field of the registration child request. Its presence switches the child\n * from \"send the route snapshot\" to \"build the OpenAPI document in this process\".\n */\nexport type OpenApiChildRequestOptions = Readonly<{\n  version: typeof OPENAPI_PROTOCOL_VERSION;\n  /** Overrides `info.title` (default: the app `package.json` name). */\n  title?: string;\n  /** Overrides `servers[0].url` (default: built from the `http` config). */\n  server?: string;\n  includePages?: boolean;\n}>;\n\n/** What the child sends back: plain JSON only, never a Seal instance. */\nexport type OpenApiChildResult = Readonly<{\n  version: typeof OPENAPI_PROTOCOL_VERSION;\n  document: OpenApiDocument;\n  warnings: readonly string[];\n}>;\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * Validate the `openapi` request field inside the child. Throws on anything unexpected.\n */\nexport function parseOpenApiChildOptions(value: unknown): OpenApiChildRequestOptions {\n  if (\n    !isRecord(value) ||\n    value.version !== OPENAPI_PROTOCOL_VERSION ||\n    !(value.title === undefined || typeof value.title === \"string\") ||\n    !(value.server === undefined || typeof value.server === \"string\") ||\n    !(value.includePages === undefined || typeof value.includePages === \"boolean\")\n  ) {\n    throw new Error(\"Route registration child received an invalid OpenAPI request.\");\n  }\n\n  return value as OpenApiChildRequestOptions;\n}\n\n/**\n * Validate the result message in the parent. Throws on anything unexpected.\n */\nexport function parseOpenApiChildResult(value: unknown): OpenApiChildResult {\n  if (\n    !isRecord(value) ||\n    value.version !== OPENAPI_PROTOCOL_VERSION ||\n    !isRecord(value.document) ||\n    typeof value.document.openapi !== \"string\" ||\n    !isRecord(value.document.paths) ||\n    !Array.isArray(value.warnings) ||\n    !value.warnings.every((warning) => typeof warning === \"string\")\n  ) {\n    throw new Error(\"Route registration child sent an invalid OpenAPI document payload.\");\n  }\n\n  return Object.freeze({\n    version: OPENAPI_PROTOCOL_VERSION,\n    document: value.document as unknown as OpenApiDocument,\n    warnings: Object.freeze([...(value.warnings as string[])]),\n  });\n}\n"],"mappings":";;AAGA,MAAa,2BAA2B;;AAGxC,MAAa,yBAAyB;AAsBtC,SAAS,SAAS,OAAkD;CAClE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;;;;AAKA,SAAgB,yBAAyB,OAA4C;CACnF,IACE,CAAC,SAAS,KAAK,KACf,MAAM,iBACN,EAAE,MAAM,UAAU,UAAa,OAAO,MAAM,UAAU,aACtD,EAAE,MAAM,WAAW,UAAa,OAAO,MAAM,WAAW,aACxD,EAAE,MAAM,iBAAiB,UAAa,OAAO,MAAM,iBAAiB,YAEpE,MAAM,IAAI,MAAM,+DAA+D;CAGjF,OAAO;AACT;;;;AAKA,SAAgB,wBAAwB,OAAoC;CAC1E,IACE,CAAC,SAAS,KAAK,KACf,MAAM,iBACN,CAAC,SAAS,MAAM,QAAQ,KACxB,OAAO,MAAM,SAAS,YAAY,YAClC,CAAC,SAAS,MAAM,SAAS,KAAK,KAC9B,CAAC,MAAM,QAAQ,MAAM,QAAQ,KAC7B,CAAC,MAAM,SAAS,OAAO,YAAY,OAAO,YAAY,QAAQ,GAE9D,MAAM,IAAI,MAAM,oEAAoE;CAGtF,OAAO,OAAO,OAAO;EACnB;EACA,UAAU,MAAM;EAChB,UAAU,OAAO,OAAO,CAAC,GAAI,MAAM,QAAqB,CAAC;CAC3D,CAAC;AACH"}

package/esm/openapi/paths.mjs

@@ -0,0 +1,63 @@
+//#region ../core/src/openapi/paths.ts
+/**
+* The concrete verbs an `all` route expands into. Mirrors `ALL_METHODS` in the route registry.
+*/
+const ALL_METHODS = [
+	"get",
+	"post",
+	"put",
+	"patch",
+	"delete",
+	"options",
+	"head"
+];
+const PATH_PARAM_PATTERN = /:([A-Za-z_][A-Za-z0-9_]*)(\([^)]*\))?/g;
+/**
+* Convert a Warlock path into an OpenAPI path template: `/users/:id` -> `/users/{id}`.
+* A Fastify-style regex suffix (`:id(\d+)`) is dropped.
+*/
+function toOpenApiPath(path) {
+	return path.replace(PATH_PARAM_PATTERN, (_match, name) => `{${name}}`);
+}
+/**
+* Names of the path parameters of a Warlock path, in order of appearance.
+*/
+function extractPathParamNames(path) {
+	return [...path.matchAll(PATH_PARAM_PATTERN)].flatMap((match) => match[1] ?? []);
+}
+/**
+* Lowercase operation verbs of a route method; `all` expands to every verb.
+*/
+function expandMethods(method) {
+	const lowered = String(method).toLowerCase();
+	if (lowered === "all") return [...ALL_METHODS];
+	return ALL_METHODS.includes(lowered) ? [lowered] : [];
+}
+/**
+* `operationId` for an operation. A named route keeps its name (with `.<verb>` appended when
+* an `all` route expands into several operations); an unnamed route gets a `method_path_slug`
+* id such as `get_users_id`.
+*/
+function buildOperationId(name, method, path, expanded) {
+	if (name) return expanded ? `${name}.${method}` : name;
+	const slug = path.replace(PATH_PARAM_PATTERN, "$1").replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+	return slug ? `${method}_${slug}` : method;
+}
+/**
+* Tag of a route: its first static path segment (`/users/:id` -> `users`).
+*/
+function firstSegmentTag(path) {
+	const segment = path.split("/").find((part) => part.length > 0);
+	if (!segment || segment.startsWith(":") || segment === "*") return;
+	return segment;
+}
+/**
+* Verbs whose requests carry no body, so unscoped validation maps to query parameters.
+*/
+function isBodylessMethod(method) {
+	return method === "get" || method === "head" || method === "delete" || method === "options";
+}
+
+//#endregion
+export { buildOperationId, expandMethods, extractPathParamNames, firstSegmentTag, isBodylessMethod, toOpenApiPath };
+//# sourceMappingURL=paths.mjs.map

package/esm/openapi/paths.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.mjs","names":[],"sources":["../../../../../../../core/src/openapi/paths.ts"],"sourcesContent":["import type { RequestMethod } from \"../router/types\";\n\n/**\n * The concrete verbs an `all` route expands into. Mirrors `ALL_METHODS` in the route registry.\n */\nconst ALL_METHODS = [\"get\", \"post\", \"put\", \"patch\", \"delete\", \"options\", \"head\"] as const;\n\nexport type OpenApiMethod = (typeof ALL_METHODS)[number];\n\nconst PATH_PARAM_PATTERN = /:([A-Za-z_][A-Za-z0-9_]*)(\\([^)]*\\))?/g;\n\n/**\n * Convert a Warlock path into an OpenAPI path template: `/users/:id` -> `/users/{id}`.\n * A Fastify-style regex suffix (`:id(\\d+)`) is dropped.\n */\nexport function toOpenApiPath(path: string): string {\n  return path.replace(PATH_PARAM_PATTERN, (_match, name: string) => `{${name}}`);\n}\n\n/**\n * Names of the path parameters of a Warlock path, in order of appearance.\n */\nexport function extractPathParamNames(path: string): string[] {\n  return [...path.matchAll(PATH_PARAM_PATTERN)].flatMap((match) => match[1] ?? []);\n}\n\n/**\n * Lowercase operation verbs of a route method; `all` expands to every verb.\n */\nexport function expandMethods(method: RequestMethod | string): OpenApiMethod[] {\n  const lowered = String(method).toLowerCase();\n\n  if (lowered === \"all\") {\n    return [...ALL_METHODS];\n  }\n\n  return (ALL_METHODS as readonly string[]).includes(lowered) ? [lowered as OpenApiMethod] : [];\n}\n\n/**\n * `operationId` for an operation. A named route keeps its name (with `.<verb>` appended when\n * an `all` route expands into several operations); an unnamed route gets a `method_path_slug`\n * id such as `get_users_id`.\n */\nexport function buildOperationId(\n  name: string | undefined,\n  method: OpenApiMethod,\n  path: string,\n  expanded: boolean,\n): string {\n  if (name) {\n    return expanded ? `${name}.${method}` : name;\n  }\n\n  const slug = path\n    .replace(PATH_PARAM_PATTERN, \"$1\")\n    .replace(/[^A-Za-z0-9]+/g, \"_\")\n    .replace(/^_+|_+$/g, \"\");\n\n  return slug ? `${method}_${slug}` : method;\n}\n\n/**\n * Tag of a route: its first static path segment (`/users/:id` -> `users`).\n */\nexport function firstSegmentTag(path: string): string | undefined {\n  const segment = path.split(\"/\").find((part) => part.length > 0);\n\n  if (!segment || segment.startsWith(\":\") || segment === \"*\") {\n    return undefined;\n  }\n\n  return segment;\n}\n\n/**\n * Verbs whose requests carry no body, so unscoped validation maps to query parameters.\n */\nexport function isBodylessMethod(method: OpenApiMethod): boolean {\n  return method === \"get\" || method === \"head\" || method === \"delete\" || method === \"options\";\n}\n"],"mappings":";;;;AAKA,MAAM,cAAc;CAAC;CAAO;CAAQ;CAAO;CAAS;CAAU;CAAW;AAAM;AAI/E,MAAM,qBAAqB;;;;;AAM3B,SAAgB,cAAc,MAAsB;CAClD,OAAO,KAAK,QAAQ,qBAAqB,QAAQ,SAAiB,IAAI,KAAK,EAAE;AAC/E;;;;AAKA,SAAgB,sBAAsB,MAAwB;CAC5D,OAAO,CAAC,GAAG,KAAK,SAAS,kBAAkB,CAAC,CAAC,CAAC,SAAS,UAAU,MAAM,MAAM,CAAC,CAAC;AACjF;;;;AAKA,SAAgB,cAAc,QAAiD;CAC7E,MAAM,UAAU,OAAO,MAAM,CAAC,CAAC,YAAY;CAE3C,IAAI,YAAY,OACd,OAAO,CAAC,GAAG,WAAW;CAGxB,OAAQ,YAAkC,SAAS,OAAO,IAAI,CAAC,OAAwB,IAAI,CAAC;AAC9F;;;;;;AAOA,SAAgB,iBACd,MACA,QACA,MACA,UACQ;CACR,IAAI,MACF,OAAO,WAAW,GAAG,KAAK,GAAG,WAAW;CAG1C,MAAM,OAAO,KACV,QAAQ,oBAAoB,IAAI,CAAC,CACjC,QAAQ,kBAAkB,GAAG,CAAC,CAC9B,QAAQ,YAAY,EAAE;CAEzB,OAAO,OAAO,GAAG,OAAO,GAAG,SAAS;AACtC;;;;AAKA,SAAgB,gBAAgB,MAAkC;CAChE,MAAM,UAAU,KAAK,MAAM,GAAG,CAAC,CAAC,MAAM,SAAS,KAAK,SAAS,CAAC;CAE9D,IAAI,CAAC,WAAW,QAAQ,WAAW,GAAG,KAAK,YAAY,KACrD;CAGF,OAAO;AACT;;;;AAKA,SAAgB,iBAAiB,QAAgC;CAC/D,OAAO,WAAW,SAAS,WAAW,UAAU,WAAW,YAAY,WAAW;AACpF"}

package/esm/openapi/request-schemas.mjs

@@ -0,0 +1,138 @@
+import { extractPathParamNames, isBodylessMethod } from "./paths.mjs";
+
+//#region ../core/src/openapi/request-schemas.ts
+const VALIDATING_LOCATIONS = [
+	"body",
+	"query",
+	"params",
+	"headers"
+];
+/**
+* Convert a Seal validator to a JSON Schema object (`draft-2020-12`, the OpenAPI 3.1 dialect)
+* and split it into properties and required keys. Never throws: a validator that cannot be
+* converted is reported through `warn` and yields `undefined`.
+*/
+function readObjectSchema(validator, what, warn) {
+	const convert = validator?.toJsonSchema;
+	if (typeof convert !== "function") return;
+	let schema;
+	try {
+		schema = convert.call(validator, "draft-2020-12");
+	} catch (error) {
+		warn(`${what} could not be converted to JSON Schema and is not documented: ${error instanceof Error ? error.message : String(error)}`);
+		return;
+	}
+	const properties = schema?.properties;
+	if (typeof schema !== "object" || schema === null || !isRecord(properties)) {
+		warn(`${what} is not an object schema and is not documented.`);
+		return;
+	}
+	const required = schema.required;
+	return {
+		schema,
+		properties,
+		required: new Set(Array.isArray(required) ? required.filter((key) => typeof key === "string") : [])
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describeParameter(name, location, schema, required) {
+	const parameter = {
+		name,
+		in: location,
+		required,
+		schema
+	};
+	if (typeof schema.description === "string") parameter.description = schema.description;
+	if (location === "query" && schema.type === "object") {
+		parameter.style = "deepObject";
+		parameter.explode = true;
+	}
+	return parameter;
+}
+/**
+* Where an unscoped or scoped `validating` puts the non-path properties.
+*
+* `validateAll` merges body and query (unset) or exactly the listed sources. The OpenAPI
+* placement follows: unset -> by method, a single source -> that source, `body` + `query`
+* -> body for verbs that carry one, query for the rest (and a warning, it is ambiguous).
+*/
+function resolvePrimaryLocation(method, validating, warn) {
+	if (validating.length === 0) return isBodylessMethod(method) ? "query" : "body";
+	const hasBody = validating.includes("body");
+	const hasQuery = validating.includes("query");
+	if (hasBody && hasQuery) {
+		warn(`validating lists both "body" and "query"; the properties are documented as ${isBodylessMethod(method) ? "query parameters" : "the request body"}.`);
+		return isBodylessMethod(method) ? "query" : "body";
+	}
+	if (hasBody) return "body";
+	if (hasQuery) return "query";
+	if (validating.includes("headers")) return "header";
+}
+/**
+* Map a handler's `validation` to OpenAPI parameters and a request body.
+*
+* - `validation.params` -> one required path parameter per property.
+* - Path segments without a declared schema -> required string path parameters.
+* - `validation.schema` -> request body (verbs that carry one) or query parameters, placed by
+*   `validating` exactly as `validateAll` reads the request; a property named like a path
+*   segment is a path parameter whenever `params` is validated (unset counts).
+*/
+function buildRequestParts(input) {
+	const { method, path, validation, warn } = input;
+	const validating = (validation?.validating ?? []).filter((location) => VALIDATING_LOCATIONS.includes(location));
+	const pathNames = extractPathParamNames(path);
+	const paramsSchema = validation?.params ? readObjectSchema(validation.params, "validation.params", warn) : void 0;
+	const mainSchema = validation?.schema ? readObjectSchema(validation.schema, "validation.schema", warn) : void 0;
+	const pathSchemas = /* @__PURE__ */ new Map();
+	const primary = resolvePrimaryLocation(method, validating, warn);
+	const takesPathNames = validating.length === 0 || validating.includes("params");
+	const located = {
+		body: [],
+		query: [],
+		header: []
+	};
+	if (paramsSchema) {
+		for (const name of pathNames) if (paramsSchema.properties[name]) pathSchemas.set(name, paramsSchema.properties[name]);
+	}
+	if (mainSchema) for (const [key, propertySchema] of Object.entries(mainSchema.properties)) {
+		if (takesPathNames && pathNames.includes(key)) {
+			if (!pathSchemas.has(key)) pathSchemas.set(key, propertySchema);
+			continue;
+		}
+		if (!primary) {
+			warn(`validation.schema property "${key}" is not a path parameter and is not documented.`);
+			continue;
+		}
+		located[primary].push({
+			key,
+			schema: propertySchema
+		});
+	}
+	const requiredKeys = mainSchema?.required ?? /* @__PURE__ */ new Set();
+	const parameters = pathNames.map((name) => describeParameter(name, "path", pathSchemas.get(name) ?? { type: "string" }, true));
+	for (const { key, schema } of located.query) parameters.push(describeParameter(key, "query", schema, requiredKeys.has(key)));
+	for (const { key, schema } of located.header) parameters.push(describeParameter(key.toLowerCase(), "header", schema, requiredKeys.has(key)));
+	if (located.body.length === 0 || !mainSchema) return { parameters };
+	const properties = {};
+	for (const { key, schema } of located.body) properties[key] = schema;
+	const required = located.body.filter(({ key }) => mainSchema.required.has(key)).map(({ key }) => key);
+	const bodySchema = {
+		...mainSchema.schema,
+		properties
+	};
+	if (required.length > 0) bodySchema.required = required;
+	else delete bodySchema.required;
+	return {
+		parameters,
+		requestBody: {
+			required: required.length > 0,
+			content: { "application/json": { schema: bodySchema } }
+		}
+	};
+}
+
+//#endregion
+export { buildRequestParts };
+//# sourceMappingURL=request-schemas.mjs.map

package/esm/openapi/request-schemas.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-schemas.mjs","names":[],"sources":["../../../../../../../core/src/openapi/request-schemas.ts"],"sourcesContent":["import type { RequestHandlerValidation } from \"../router/types\";\nimport { extractPathParamNames, isBodylessMethod, type OpenApiMethod } from \"./paths\";\nimport type {\n  OpenApiParameter,\n  OpenApiRequestBody,\n  OpenApiSchema,\n  WarningSink,\n} from \"./types\";\n\ntype ValidatingLocation = \"body\" | \"query\" | \"params\" | \"headers\";\n\ntype ObjectSchemaParts = {\n  schema: OpenApiSchema;\n  properties: Record<string, OpenApiSchema>;\n  required: Set<string>;\n};\n\n/** A `validation.schema` property placed in a request location, with its JSON Schema. */\ntype LocatedProperty = {\n  key: string;\n  schema: OpenApiSchema;\n};\n\nexport type RequestParts = {\n  parameters: OpenApiParameter[];\n  requestBody?: OpenApiRequestBody;\n};\n\nexport type BuildRequestPartsInput = {\n  method: OpenApiMethod;\n  /** Warlock path, with `:param` segments. */\n  path: string;\n  validation: RequestHandlerValidation | undefined;\n  warn: WarningSink;\n};\n\nconst VALIDATING_LOCATIONS: readonly string[] = [\"body\", \"query\", \"params\", \"headers\"];\n\n/**\n * Convert a Seal validator to a JSON Schema object (`draft-2020-12`, the OpenAPI 3.1 dialect)\n * and split it into properties and required keys. Never throws: a validator that cannot be\n * converted is reported through `warn` and yields `undefined`.\n */\nfunction readObjectSchema(\n  validator: unknown,\n  what: string,\n  warn: WarningSink,\n): ObjectSchemaParts | undefined {\n  const convert = (validator as { toJsonSchema?: unknown } | undefined)?.toJsonSchema;\n\n  if (typeof convert !== \"function\") {\n    return undefined;\n  }\n\n  let schema: unknown;\n\n  try {\n    schema = convert.call(validator, \"draft-2020-12\");\n  } catch (error) {\n    warn(\n      `${what} could not be converted to JSON Schema and is not documented: ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n    );\n\n    return undefined;\n  }\n\n  const properties = (schema as { properties?: unknown } | undefined)?.properties;\n\n  if (typeof schema !== \"object\" || schema === null || !isRecord(properties)) {\n    warn(`${what} is not an object schema and is not documented.`);\n\n    return undefined;\n  }\n\n  const required = (schema as { required?: unknown }).required;\n\n  return {\n    schema: schema as OpenApiSchema,\n    properties: properties as Record<string, OpenApiSchema>,\n    required: new Set(Array.isArray(required) ? required.filter((key) => typeof key === \"string\") : []),\n  };\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction describeParameter(\n  name: string,\n  location: OpenApiParameter[\"in\"],\n  schema: OpenApiSchema,\n  required: boolean,\n): OpenApiParameter {\n  const parameter: OpenApiParameter = { name, in: location, required, schema };\n\n  if (typeof schema.description === \"string\") {\n    parameter.description = schema.description;\n  }\n\n  if (location === \"query\" && schema.type === \"object\") {\n    parameter.style = \"deepObject\";\n    parameter.explode = true;\n  }\n\n  return parameter;\n}\n\n/**\n * Where an unscoped or scoped `validating` puts the non-path properties.\n *\n * `validateAll` merges body and query (unset) or exactly the listed sources. The OpenAPI\n * placement follows: unset -> by method, a single source -> that source, `body` + `query`\n * -> body for verbs that carry one, query for the rest (and a warning, it is ambiguous).\n */\nfunction resolvePrimaryLocation(\n  method: OpenApiMethod,\n  validating: ValidatingLocation[],\n  warn: WarningSink,\n): \"body\" | \"query\" | \"header\" | undefined {\n  if (validating.length === 0) {\n    return isBodylessMethod(method) ? \"query\" : \"body\";\n  }\n\n  const hasBody = validating.includes(\"body\");\n  const hasQuery = validating.includes(\"query\");\n\n  if (hasBody && hasQuery) {\n    warn(\n      `validating lists both \"body\" and \"query\"; the properties are documented as ${\n        isBodylessMethod(method) ? \"query parameters\" : \"the request body\"\n      }.`,\n    );\n\n    return isBodylessMethod(method) ? \"query\" : \"body\";\n  }\n\n  if (hasBody) {\n    return \"body\";\n  }\n\n  if (hasQuery) {\n    return \"query\";\n  }\n\n  if (validating.includes(\"headers\")) {\n    return \"header\";\n  }\n\n  return undefined;\n}\n\n/**\n * Map a handler's `validation` to OpenAPI parameters and a request body.\n *\n * - `validation.params` -> one required path parameter per property.\n * - Path segments without a declared schema -> required string path parameters.\n * - `validation.schema` -> request body (verbs that carry one) or query parameters, placed by\n *   `validating` exactly as `validateAll` reads the request; a property named like a path\n *   segment is a path parameter whenever `params` is validated (unset counts).\n */\nexport function buildRequestParts(input: BuildRequestPartsInput): RequestParts {\n  const { method, path, validation, warn } = input;\n  const validating = (validation?.validating ?? []).filter((location): location is ValidatingLocation =>\n    VALIDATING_LOCATIONS.includes(location),\n  );\n  const pathNames = extractPathParamNames(path);\n\n  const paramsSchema = validation?.params\n    ? readObjectSchema(validation.params, \"validation.params\", warn)\n    : undefined;\n  const mainSchema = validation?.schema\n    ? readObjectSchema(validation.schema, \"validation.schema\", warn)\n    : undefined;\n\n  const pathSchemas = new Map<string, OpenApiSchema>();\n  const primary = resolvePrimaryLocation(method, validating, warn);\n  const takesPathNames = validating.length === 0 || validating.includes(\"params\");\n\n  const located: Record<\"body\" | \"query\" | \"header\", LocatedProperty[]> = {\n    body: [],\n    query: [],\n    header: [],\n  };\n\n  if (paramsSchema) {\n    for (const name of pathNames) {\n      if (paramsSchema.properties[name]) {\n        pathSchemas.set(name, paramsSchema.properties[name]);\n      }\n    }\n  }\n\n  if (mainSchema) {\n    for (const [key, propertySchema] of Object.entries(mainSchema.properties)) {\n      if (takesPathNames && pathNames.includes(key)) {\n        if (!pathSchemas.has(key)) {\n          pathSchemas.set(key, propertySchema);\n        }\n\n        continue;\n      }\n\n      if (!primary) {\n        warn(`validation.schema property \"${key}\" is not a path parameter and is not documented.`);\n\n        continue;\n      }\n\n      located[primary].push({ key, schema: propertySchema });\n    }\n  }\n\n  const requiredKeys = mainSchema?.required ?? new Set<string>();\n\n  const parameters: OpenApiParameter[] = pathNames.map((name) =>\n    describeParameter(name, \"path\", pathSchemas.get(name) ?? { type: \"string\" }, true),\n  );\n\n  for (const { key, schema } of located.query) {\n    parameters.push(describeParameter(key, \"query\", schema, requiredKeys.has(key)));\n  }\n\n  for (const { key, schema } of located.header) {\n    parameters.push(describeParameter(key.toLowerCase(), \"header\", schema, requiredKeys.has(key)));\n  }\n\n  if (located.body.length === 0 || !mainSchema) {\n    return { parameters };\n  }\n\n  const properties: Record<string, OpenApiSchema> = {};\n\n  for (const { key, schema } of located.body) {\n    properties[key] = schema;\n  }\n\n  const required = located.body.filter(({ key }) => mainSchema.required.has(key)).map(({ key }) => key);\n  const bodySchema: OpenApiSchema = { ...mainSchema.schema, properties };\n\n  if (required.length > 0) {\n    bodySchema.required = required;\n  } else {\n    delete bodySchema.required;\n  }\n\n  return {\n    parameters,\n    requestBody: {\n      required: required.length > 0,\n      content: { \"application/json\": { schema: bodySchema } },\n    },\n  };\n}\n"],"mappings":"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"}