@zudojs/openapi 0.1.0 → 1.1.0

package/dist/openApiSchema/schemaConverter.core.js

@@ -1,141 +1,498 @@
-function isOptional(value) {
-    if (value && typeof value === "object" && "_type" in value) {
-        return value._type === "optional";
-    }
-    return false;
+import { DEFAULT_OPENAPI_VERSION } from "../openApiConstants/openApiConstants.core.js";
+/** Maps `@zudojs/schema` string formats onto OpenAPI `format` values. */
+const STRING_FORMATS = {
+    email: "email",
+    url: "uri",
+    uuid: "uuid",
+    "uuid-v4": "uuid",
+    datetime: "date-time",
+    date: "date",
+    time: "time",
+    ipv4: "ipv4",
+    ipv6: "ipv6",
+};
+/**
+ * Assigns a property that may be named `__proto__`.
+ *
+ * `properties["__proto__"] = schema` on a plain object literal sets the
+ * object's prototype instead of adding a member: the property vanishes from
+ * the generated document with no error anywhere. A schema field genuinely
+ * called `__proto__` is unusual; one supplied by an attacker to make a
+ * constraint disappear from the published contract is exactly the point.
+ */
+function defineProperty(target, key, value) {
+    Object.defineProperty(target, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+}
+function isSchemaLike(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value._type === "string");
+}
+function isOptionalSchema(value) {
+    return isSchemaLike(value) && value._type === "optional";
 }
 function extractMeta(schema) {
-    const m = schema._metadata;
-    if (!m)
+    const meta = schema._metadata;
+    if (!meta)
         return {};
     return {
-        ...(m.description ? { description: m.description } : {}),
-        ...(m.example !== undefined ? { example: m.example } : {}),
-        ...(m.deprecated ? { deprecated: true } : {}),
-        ...(m.title ? { title: m.title } : {}),
+        ...(meta.description ? { description: meta.description } : {}),
+        ...(meta.example !== undefined ? { example: meta.example } : {}),
+        ...(meta.deprecated ? { deprecated: true } : {}),
+        ...(meta.title ? { title: meta.title } : {}),
     };
 }
-export function convertSchema(input, _visited = new Set()) {
-    if (input && typeof input === "object" && "_type" in input) {
-        const schema = input;
-        const meta = extractMeta(schema);
-        switch (schema._type) {
-            case "string":
-            case "number":
-            case "boolean":
-                return { schema: { type: schema._type, ...meta }, warnings: [] };
-            case "object": {
-                const shape = schema.shape ?? {};
-                const requiredKeys = schema.requiredKeys ?? [];
-                const properties = {};
-                const required = [];
-                const warnings = [];
-                for (const [key, value] of Object.entries(shape)) {
-                    const converted = convertSchema(value, _visited);
-                    properties[key] = converted.schema;
-                    warnings.push(...converted.warnings);
-                    if (!isOptional(value) && requiredKeys.includes(key))
-                        required.push(key);
-                }
-                return {
-                    schema: {
-                        type: "object",
-                        ...(Object.keys(properties).length > 0 ? { properties } : {}),
-                        ...(required.length > 0 ? { required } : {}),
-                        ...meta,
-                    },
-                    warnings,
-                };
+function config(schema) {
+    const raw = schema["_config"];
+    return typeof raw === "object" && raw !== null
+        ? raw
+        : {};
+}
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? value
+        : undefined;
+}
+/** True when the document being produced follows OpenAPI 3.1 or later. */
+export function isVersion31(version) {
+    return !version.startsWith("3.0");
+}
+/**
+ * Applies nullability in the way the target version expresses it.
+ *
+ * 3.1 dropped `nullable` in favour of a type union, so emitting `nullable`
+ * into a 3.1 document produces a schema validators quietly ignore.
+ */
+function applyNullable(schema, version) {
+    if (!isVersion31(version)) {
+        return { ...schema, nullable: true };
+    }
+    if (schema.type === undefined) {
+        // No type to widen — express it as a union with the null type.
+        return { ...schema, anyOf: [...(schema.anyOf ?? []), { type: "null" }] };
+    }
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (types.includes("null"))
+        return schema;
+    return { ...schema, type: [...types, "null"] };
+}
+function convertString(schema, state) {
+    const c = config(schema);
+    const format = typeof c["format"] === "string" ? c["format"] : undefined;
+    const pattern = c["pattern"];
+    const exact = num(c["length"]);
+    if (format !== undefined && STRING_FORMATS[format] === undefined) {
+        state.warnings.push(`String format "${format}" has no OpenAPI equivalent; the constraint ` +
+            `was dropped from the schema.`);
+    }
+    if (pattern instanceof RegExp) {
+        // `pattern` in JSON Schema carries no flags. An `i` regex silently
+        // becomes case-sensitive in the document, so the published contract is
+        // stricter than the code that validates against it — the kind of drift
+        // that only shows up as a rejected request in production.
+        const meaningful = pattern.flags.replace(/[gy]/g, "");
+        if (meaningful.length > 0) {
+            state.warnings.push(`Pattern /${pattern.source}/${pattern.flags} has flags OpenAPI ` +
+                `cannot express; the emitted pattern is case- and mode-sensitive.`);
+        }
+    }
+    else if (pattern !== undefined && typeof pattern !== "string") {
+        state.warnings.push("A `pattern` constraint was not a RegExp and could not be emitted.");
+    }
+    return {
+        type: "string",
+        ...(format && STRING_FORMATS[format]
+            ? { format: STRING_FORMATS[format] }
+            : {}),
+        ...(exact !== undefined
+            ? { minLength: exact, maxLength: exact }
+            : {
+                ...(num(c["min"]) !== undefined ? { minLength: num(c["min"]) } : {}),
+                ...(num(c["max"]) !== undefined ? { maxLength: num(c["max"]) } : {}),
+            }),
+        ...(pattern instanceof RegExp
+            ? { pattern: pattern.source }
+            : typeof pattern === "string"
+                ? { pattern }
+                : {}),
+    };
+}
+/**
+ * Renders an exclusive bound the way the target version spells it.
+ *
+ * 3.1 (JSON Schema 2020-12) gives `exclusiveMinimum` the numeric bound. 3.0
+ * defines it as a *boolean* modifier on `minimum`, so emitting the number
+ * into a 3.0 document produces a keyword of the wrong type: a strict
+ * validator rejects the document and a lenient one ignores the bound — either
+ * way the constraint is gone.
+ */
+function exclusiveBound(kind, value, version) {
+    if (isVersion31(version)) {
+        return kind === "minimum"
+            ? { exclusiveMinimum: value }
+            : { exclusiveMaximum: value };
+    }
+    return kind === "minimum"
+        ? { minimum: value, exclusiveMinimum: true }
+        : { maximum: value, exclusiveMaximum: true };
+}
+function convertNumber(schema, state) {
+    const c = config(schema);
+    const gt = num(c["gt"]);
+    const lt = num(c["lt"]);
+    const version = state.version;
+    const exclusiveMin = gt !== undefined
+        ? gt
+        : c["positive"] === true && num(c["min"]) === undefined
+            ? 0
+            : undefined;
+    const exclusiveMax = lt !== undefined
+        ? lt
+        : c["negative"] === true && num(c["max"]) === undefined
+            ? 0
+            : undefined;
+    return {
+        type: c["int"] === true ? "integer" : "number",
+        ...(num(c["min"]) !== undefined ? { minimum: num(c["min"]) } : {}),
+        ...(num(c["max"]) !== undefined ? { maximum: num(c["max"]) } : {}),
+        ...(num(c["multipleOf"]) !== undefined
+            ? { multipleOf: num(c["multipleOf"]) }
+            : {}),
+        ...(exclusiveMin !== undefined
+            ? exclusiveBound("minimum", exclusiveMin, version)
+            : {}),
+        ...(exclusiveMax !== undefined
+            ? exclusiveBound("maximum", exclusiveMax, version)
+            : {}),
+    };
+}
+/** Infers the JSON Schema type of a literal or enum member. */
+function typeOfValue(value) {
+    if (typeof value === "string")
+        return "string";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? "integer" : "number";
+    if (typeof value === "boolean")
+        return "boolean";
+    if (value === null)
+        return "null";
+    return undefined;
+}
+function enumSchema(values, version) {
+    const types = new Set(values.map(typeOfValue));
+    const type = types.size === 1 ? [...types][0] : undefined;
+    // `"null"` is not a type in 3.0; leaving the enum untyped is correct there.
+    const usable = type === "null" && version !== undefined && !isVersion31(version)
+        ? undefined
+        : type;
+    return {
+        ...(usable ? { type: usable } : {}),
+        enum: [...values],
+    };
+}
+function convertNode(input, state) {
+    if (state.depth > state.maxDepth) {
+        state.warnings.push(`Schema nesting exceeded the maximum depth of ${state.maxDepth}.`);
+        return {};
+    }
+    if (!isSchemaLike(input)) {
+        return convertLiteralValue(input, state);
+    }
+    // Cycle guard. `lazy` schemas exist precisely to describe self-referential
+    // shapes, so without this a comment-with-replies schema recurses until the
+    // stack gives out.
+    if (state.visited.has(input)) {
+        state.warnings.push(`Recursive schema detected at "${input._type}"; emitted an empty schema. ` +
+            `Register the schema as a named component and reference it with $ref.`);
+        return {};
+    }
+    state.visited.add(input);
+    state.depth++;
+    try {
+        return { ...convertSchemaNode(input, state), ...extractMeta(input) };
+    }
+    finally {
+        state.depth--;
+        state.visited.delete(input);
+    }
+}
+function convertSchemaNode(schema, state) {
+    const c = config(schema);
+    switch (schema._type) {
+        case "string":
+        case "coerce.string":
+            return convertString(schema, state);
+        case "number":
+        case "coerce.number":
+            return convertNumber(schema, state);
+        case "boolean":
+        case "coerce.boolean":
+            return { type: "boolean" };
+        case "coerce.bigint":
+            return { type: "string", format: "int64" };
+        case "null":
+            // 3.0 has no `null` type; `nullable` on an untyped schema is the
+            // closest it can express.
+            return isVersion31(state.version)
+                ? { type: "null" }
+                : { nullable: true };
+        case "any":
+        case "unknown":
+            return {};
+        case "never":
+            return { not: {} };
+        case "undefined":
+            state.warnings.push("An `undefined` schema has no OpenAPI equivalent; emitted an empty schema.");
+            return {};
+        case "object": {
+            const shape = c["shape"] ?? {};
+            const requiredKeys = c["requiredKeys"];
+            const properties = {};
+            const required = [];
+            for (const [key, value] of Object.entries(shape)) {
+                defineProperty(properties, key, convertNode(value, state));
+                // A field is required unless it is wrapped in `optional`. An explicit
+                // `requiredKeys` set (from `.required()`) forces it back on.
+                const forced = requiredKeys instanceof Set && requiredKeys.has(key);
+                if (forced || !isOptionalSchema(value))
+                    required.push(key);
             }
-            case "array": {
-                const items = schema.items;
-                const warnings = [];
-                let itemsSchema;
-                if (items) {
-                    const converted = convertSchema(items, _visited);
-                    itemsSchema = converted.schema;
-                    warnings.push(...converted.warnings);
-                }
+            const unknownKeys = c["unknownKeys"];
+            return {
+                type: "object",
+                ...(Object.keys(properties).length > 0 ? { properties } : {}),
+                ...(required.length > 0 ? { required } : {}),
+                ...(unknownKeys === "strip" || unknownKeys === "strict"
+                    ? { additionalProperties: false }
+                    : {}),
+            };
+        }
+        case "record": {
+            const valueSchema = c["_valueSchema"] ?? schema["_valueSchema"];
+            return {
+                type: "object",
+                additionalProperties: valueSchema === undefined ? true : convertNode(valueSchema, state),
+            };
+        }
+        case "array": {
+            const items = c["itemSchema"];
+            const exact = num(c["length"]);
+            return {
+                type: "array",
+                ...(items !== undefined ? { items: convertNode(items, state) } : {}),
+                ...(exact !== undefined
+                    ? { minItems: exact, maxItems: exact }
+                    : {
+                        ...(num(c["min"]) !== undefined
+                            ? { minItems: num(c["min"]) }
+                            : {}),
+                        ...(num(c["max"]) !== undefined
+                            ? { maxItems: num(c["max"]) }
+                            : {}),
+                    }),
+            };
+        }
+        case "set": {
+            const valueSchema = schema["_valueSchema"];
+            return {
+                type: "array",
+                uniqueItems: true,
+                ...(valueSchema !== undefined
+                    ? { items: convertNode(valueSchema, state) }
+                    : {}),
+            };
+        }
+        case "map": {
+            const valueSchema = schema["_valueSchema"];
+            state.warnings.push("A `map` schema is represented as an object with additionalProperties; " +
+                "non-string keys cannot be expressed in OpenAPI.");
+            return {
+                type: "object",
+                additionalProperties: valueSchema === undefined ? true : convertNode(valueSchema, state),
+            };
+        }
+        case "tuple": {
+            const schemas = schema["_schemas"];
+            if (!Array.isArray(schemas))
+                return { type: "array" };
+            const items = schemas.map((entry) => convertNode(entry, state));
+            if (!isVersion31(state.version)) {
+                // 3.0 has no positional items. `anyOf` over the member schemas keeps
+                // the length constraint honest without claiming a per-position type
+                // the version cannot express; emitting `prefixItems` instead produces
+                // a keyword every 3.0 validator ignores.
+                state.warnings.push("A `tuple` schema cannot express positional item types in " +
+                    "OpenAPI 3.0; emitted a length-constrained array instead.");
                 return {
-                    schema: {
-                        type: "array",
-                        ...(itemsSchema ? { items: itemsSchema } : {}),
-                        ...meta,
-                    },
-                    warnings,
+                    type: "array",
+                    ...(items.length > 0 ? { items: { anyOf: items } } : {}),
+                    minItems: items.length,
+                    maxItems: items.length,
                 };
             }
-            case "enum":
-            case "literal":
-                return {
-                    schema: {
-                        type: "string",
-                        enum: schema.values ?? [],
-                        ...meta,
-                    },
-                    warnings: [],
-                };
-            case "union": {
-                const options = schema.options ?? [];
-                const warnings = [];
-                const oneOf = options.map((option) => {
-                    const converted = convertSchema(option, _visited);
-                    warnings.push(...converted.warnings);
-                    return converted.schema;
-                });
-                return { schema: { oneOf, ...meta }, warnings };
+            return {
+                type: "array",
+                prefixItems: items,
+                minItems: items.length,
+                maxItems: items.length,
+            };
+        }
+        case "enum": {
+            const values = schema["_values"];
+            if (!Array.isArray(values) || values.length === 0) {
+                state.warnings.push("An `enum` schema had no values; `enum` must be non-empty in OpenAPI.");
+                return {};
             }
-            case "optional": {
-                const inner = schema.inner;
-                if (!inner)
-                    return {
-                        schema: {},
-                        warnings: ["Optional schema has no inner schema."],
-                    };
-                return convertSchema(inner, _visited);
+            return enumSchema(values, state.version);
+        }
+        case "literal": {
+            const value = schema["_expected"];
+            if (value === undefined) {
+                state.warnings.push("A `literal` schema had no value.");
+                return {};
             }
-            case "nullable": {
-                const inner = schema.inner;
-                if (!inner)
-                    return {
-                        schema: { nullable: true },
-                        warnings: ["Nullable schema has no inner schema."],
-                    };
-                const converted = convertSchema(inner, _visited);
-                return {
-                    schema: { ...converted.schema, nullable: true },
-                    warnings: converted.warnings,
-                };
+            // `const` arrived with JSON Schema 2020-12; a 3.0 document expresses a
+            // single permitted value as a one-member enum.
+            return isVersion31(state.version)
+                ? { ...enumSchema([value], state.version), const: value }
+                : enumSchema([value], state.version);
+        }
+        case "union": {
+            const schemas = schema["_schemas"];
+            if (!Array.isArray(schemas) || schemas.length === 0) {
+                state.warnings.push("A `union` schema had no members.");
+                return {};
             }
-            default:
-                return {
-                    schema: {},
-                    warnings: [
-                        `Unsupported schema type: ${schema._type ?? "unknown"}`,
-                    ],
-                };
+            return { anyOf: schemas.map((entry) => convertNode(entry, state)) };
         }
-    }
-    if (Array.isArray(input)) {
-        const items = input[0];
-        if (items) {
-            const converted = convertSchema(items, _visited);
+        case "discriminatedUnion": {
+            const map = schema["_schemaMap"];
+            const discriminator = schema["_discriminator"];
+            const members = map instanceof Map ? [...map.values()] : [];
+            if (members.length === 0) {
+                state.warnings.push("A `discriminatedUnion` schema had no members.");
+                return {};
+            }
             return {
-                schema: { type: "array", items: converted.schema },
-                warnings: converted.warnings,
+                oneOf: members.map((entry) => convertNode(entry, state)),
+                ...(typeof discriminator === "string"
+                    ? { discriminator: { propertyName: discriminator } }
+                    : {}),
             };
         }
-        return { schema: { type: "array" }, warnings: [] };
+        case "intersection": {
+            const left = schema["_left"];
+            const right = schema["_right"];
+            const parts = [left, right].filter((part) => part !== undefined);
+            if (parts.length === 0) {
+                state.warnings.push("An `intersection` schema had no members.");
+                return {};
+            }
+            return { allOf: parts.map((part) => convertNode(part, state)) };
+        }
+        case "optional":
+            // Optionality is expressed by the parent's `required` list, not by the
+            // property schema, so the wrapper contributes nothing of its own.
+            return convertInner(schema["_inner"], state, "optional");
+        case "nullable":
+            return applyNullable(convertInner(schema["_inner"], state, "nullable"), state.version);
+        case "default": {
+            const inner = convertInner(schema["_inner"], state, "default");
+            const defaultValue = schema["_defaultValue"];
+            return defaultValue === undefined
+                ? inner
+                : { ...inner, default: defaultValue };
+        }
+        case "refine":
+            // A refinement is a runtime predicate with no schema equivalent; the
+            // inner shape is still the right description of the data.
+            return convertInner(schema["_inner"], state, "refine");
+        case "transform":
+            return convertInner(schema["_base"], state, "transform");
+        case "lazy": {
+            const resolved = schema["_inner"] ?? resolveLazy(schema, state);
+            if (resolved === undefined)
+                return {};
+            return convertNode(resolved, state);
+        }
+        default:
+            state.warnings.push(`Unsupported schema type: ${schema._type}`);
+            return {};
+    }
+}
+function resolveLazy(schema, state) {
+    const factory = schema["_factory"];
+    if (typeof factory !== "function")
+        return undefined;
+    try {
+        return factory();
+    }
+    catch (error) {
+        state.warnings.push(`A \`lazy\` schema could not be resolved: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+function convertInner(inner, state, wrapper) {
+    if (inner === undefined) {
+        state.warnings.push(`A \`${wrapper}\` schema has no inner schema.`);
+        return {};
+    }
+    return convertNode(inner, state);
+}
+/**
+ * Converts a bare JavaScript value used as a shorthand schema.
+ *
+ * `["a"]` means "array of string" and `"x"` means "string" — a convenience
+ * for hand-written metadata, not for real schemas.
+ */
+function convertLiteralValue(input, state) {
+    if (Array.isArray(input)) {
+        const first = input[0];
+        if (first === undefined)
+            return { type: "array" };
+        return { type: "array", items: convertNode(first, state) };
     }
     if (typeof input === "string")
-        return { schema: { type: "string" }, warnings: [] };
-    if (typeof input === "number")
-        return { schema: { type: "number" }, warnings: [] };
+        return { type: "string" };
+    if (typeof input === "number") {
+        return { type: Number.isInteger(input) ? "integer" : "number" };
+    }
     if (typeof input === "boolean")
-        return { schema: { type: "boolean" }, warnings: [] };
-    return { schema: {}, warnings: ["Unable to convert unknown schema input."] };
+        return { type: "boolean" };
+    if (input === null) {
+        return isVersion31(state.version) ? { type: "null" } : { nullable: true };
+    }
+    state.warnings.push("Unable to convert unknown schema input.");
+    return {};
+}
+/**
+ * Converts a schema into an OpenAPI schema object.
+ *
+ * Warnings describe everything that could not be represented exactly. They
+ * are part of the result rather than a side channel, because silently
+ * emitting `{}` for an unsupported construct is how a specification ends up
+ * documenting nothing.
+ */
+export function convertSchema(input, options) {
+    const state = {
+        warnings: [],
+        visited: new Set(),
+        version: options?.version ?? DEFAULT_OPENAPI_VERSION,
+        maxDepth: options?.maxDepth ?? 32,
+        depth: 0,
+    };
+    const schema = convertNode(input, state);
+    return { schema, warnings: state.warnings };
 }
-export function createSchemaConverter() {
-    return { convert: convertSchema };
+/** Creates a converter bound to a specification version. */
+export function createSchemaConverter(defaults) {
+    return {
+        convert: (input, options) => convertSchema(input, { ...defaults, ...options }),
+    };
 }
 //# sourceMappingURL=schemaConverter.core.js.map