@zudojs/openapi 0.1.0 → 1.2.0

package/dist/openApiSchema/references.core.js

@@ -1,12 +1,32 @@
+import { COMPONENT_REF_PREFIX } from "../openApiConstants/openApiConstants.core.js";
+/**
+ * Escapes a component name for use inside a JSON Pointer.
+ *
+ * RFC 6901 reserves `~` and `/`; a component called `Order/Line` produces a
+ * pointer that resolves to the wrong place — or nowhere — unless they are
+ * escaped. The `~0` substitution must come first, or the `~1` it introduces
+ * would be escaped again.
+ */
+export function escapeJsonPointerSegment(segment) {
+    return segment.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+/** Reverses {@link escapeJsonPointerSegment}. */
+export function unescapeJsonPointerSegment(segment) {
+    return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
 /**
  * Creates an OpenAPI component reference.
  *
+ * This is the single `$ref` builder in the package — the registry and the
+ * schema registry both delegate here, so escaping cannot be right in one
+ * place and missing in another.
+ *
  * @param section - The component section (e.g., "schemas", "responses")
  * @param name - The component name
  */
 export function createComponentReference(section, name) {
     return {
-        $ref: `#/components/${section}/${name}`,
+        $ref: `${COMPONENT_REF_PREFIX}/${escapeJsonPointerSegment(section)}/${escapeJsonPointerSegment(name)}`,
     };
 }
 //# sourceMappingURL=references.core.js.map

package/dist/openApiSchema/schemaConverter.core.d.ts

@@ -1,11 +1,69 @@
 import type { OpenAPISchema } from "../openApiTypes/openApiTypes.core.js";
+/**
+ * Converts `@zudojs/schema` schemas into OpenAPI schema objects.
+ *
+ * The conversion reads the schema classes' runtime fields directly rather
+ * than importing them, so this package stays usable with any object that
+ * follows the same shape. That structural coupling is the reason every field
+ * name below is named in one place and covered by tests: a rename in
+ * `@zudojs/schema` is not a compile error here, it is a silently empty
+ * document.
+ *
+ * Field names as of `@zudojs/schema@0.1.0`:
+ *   object   `_config.shape`, `_config.requiredKeys` (a Set), `_config.unknownKeys`
+ *   array    `_config.itemSchema`, `_config.min`, `_config.max`, `_config.length`
+ *   string   `_config.min|max|length|pattern|format`
+ *   number   `_config.min|max|int|gt|lt|multipleOf`
+ *   coerce.string / coerce.number
+ *            `_constraints` — the wrapped StringSchema / NumberSchema that
+ *            carries the `_config` above
+ *   union    `_schemas`          intersection `_left` / `_right`
+ *   enum     `_values`           literal      `_expected`
+ *   optional `_inner`            nullable     `_inner`
+ *   default  `_inner`, `_defaultValue` (a value or a factory function)
+ *   refine   `_inner`
+ *   transform `_inner` (`schema.transform(...)`, TransformModifierSchema)
+ *             or `_base` (the standalone TransformSchema class)
+ *   lazy     `_factory` / `_inner`
+ *   record   `_keySchema`, `_valueSchema`     tuple  `_schemas`
+ *   map      `_keySchema`, `_valueSchema`     set    `_valueSchema`
+ *   metadata `_metadata` (description, example, title, deprecated)
+ *
+ * Object parsing accepts a missing key when the field schema is one of
+ * `optional`, `default`, `any` or `unknown` (`ACCEPTS_UNDEFINED` in
+ * schemaObject.core.ts), so exactly those are left out of `required`.
+ */
 export interface SchemaConversionResult {
     readonly schema: OpenAPISchema;
     readonly warnings: readonly string[];
 }
-export declare function convertSchema(input: unknown, _visited?: Set<object>): SchemaConversionResult;
+/** Options controlling how a schema is converted. */
+export interface SchemaConversionOptions {
+    /**
+     * Target specification version. 3.1 expresses nullability as
+     * `type: [t, "null"]`; 3.0 uses `nullable: true`, which 3.1 removed.
+     */
+    readonly version?: string;
+    /**
+     * Depth at which conversion stops descending. Guards against a recursive
+     * schema whose `lazy` wrapper resolves to itself. Default: 32.
+     */
+    readonly maxDepth?: number;
+}
+/** True when the document being produced follows OpenAPI 3.1 or later. */
+export declare function isVersion31(version: string): boolean;
+/**
+ * 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 declare function convertSchema(input: unknown, options?: SchemaConversionOptions): SchemaConversionResult;
 export interface SchemaConverter {
-    convert(input: unknown, visited?: Set<object>): SchemaConversionResult;
+    convert(input: unknown, options?: SchemaConversionOptions): SchemaConversionResult;
 }
-export declare function createSchemaConverter(): SchemaConverter;
+/** Creates a converter bound to a specification version. */
+export declare function createSchemaConverter(defaults?: SchemaConversionOptions): SchemaConverter;
 //# sourceMappingURL=schemaConverter.core.d.ts.map