@skmtc/core 0.29.0 → 0.31.0

package/esm/parse/v3-2/boolean/toBoolean.d.ts

@@ -0,0 +1,78 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { OasBoolean } from '../../../oas/boolean/Boolean.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export type ToBooleanArgs = {
+    value: OpenAPIV3.SchemaObject;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+/**
+ * Transforms an OpenAPI v3 boolean schema object into an internal OAS boolean representation.
+ *
+ * This function processes OpenAPI boolean schemas by extracting and parsing nullable values,
+ * examples, enumerations, and default values. It handles the complete transformation from
+ * raw OpenAPI JSON to the SKMTC internal boolean representation with proper validation.
+ *
+ * The transformation follows a pipeline approach:
+ * 1. Parse nullable flag and extract base value
+ * 2. Parse example values with nullable support
+ * 3. Parse enumeration constraints (typically [true], [false], or [true, false])
+ * 4. Parse default values
+ * 5. Create final OasBoolean instance
+ *
+ * @param args - Transformation arguments
+ * @param args.value - The OpenAPI v3 boolean schema object to transform
+ * @param args.context - Parse context providing utilities and tracing
+ * @returns Transformed OAS boolean object with parsed properties
+ *
+ * @example Basic boolean transformation
+ * ```typescript
+ * import { toBoolean } from '@skmtc/core';
+ *
+ * const openApiBoolean = {
+ *   type: 'boolean',
+ *   default: false
+ * };
+ *
+ * const oasBoolean = toBoolean({
+ *   value: openApiBoolean,
+ *   context: parseContext
+ * });
+ *
+ * console.log(oasBoolean.default); // false
+ * ```
+ *
+ * @example Boolean with nullable and enum
+ * ```typescript
+ * const flagBoolean = {
+ *   type: 'boolean',
+ *   nullable: true,
+ *   enum: [true, null],
+ *   default: null,
+ *   example: true,
+ *   title: 'Feature Flag',
+ *   description: 'Whether the feature is enabled'
+ * };
+ *
+ * const oasBoolean = toBoolean({
+ *   value: flagBoolean,
+ *   context: parseContext
+ * });
+ *
+ * console.log(oasBoolean.nullable); // true
+ * console.log(oasBoolean.enums); // [true, null]
+ * ```
+ */
+export declare const toBoolean: ({ value, stackTrail, context }: ToBooleanArgs) => OasBoolean;
+type ToParsedBooleanArgs<Nullable extends boolean | undefined> = {
+    value: Omit<OpenAPIV3.SchemaObject, 'nullable' | 'example' | 'enums'>;
+    context: ParseContextType;
+    nullable: Nullable;
+    example: Nullable extends true ? boolean | null | undefined : boolean | undefined;
+    enums: Nullable extends true ? (boolean | null)[] | undefined : boolean[] | undefined;
+    defaultValue: Nullable extends true ? boolean | null | undefined : boolean | undefined;
+    stackTrail: StackTrail;
+};
+export declare const toParsedBoolean: <Nullable extends boolean | undefined>({ context, nullable, example, enums, defaultValue, value, stackTrail }: ToParsedBooleanArgs<Nullable>) => OasBoolean<Nullable>;
+export {};

package/esm/parse/v3-2/boolean/toBoolean.js

@@ -0,0 +1,139 @@
+import { OasBoolean } from '../../../oas/boolean/Boolean.js';
+import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+import { oasBooleanData } from '../../../oas/boolean/boolean-types.js';
+import { parseNullable } from '../_helpers/parseNullable.js';
+import { parseEnum } from '../_helpers/parseEnum.js';
+import { parseExample } from '../_helpers/parseExample.js';
+import { parseDefault } from '../_helpers/parseDefault.js';
+import * as v from 'valibot';
+/**
+ * Transforms an OpenAPI v3 boolean schema object into an internal OAS boolean representation.
+ *
+ * This function processes OpenAPI boolean schemas by extracting and parsing nullable values,
+ * examples, enumerations, and default values. It handles the complete transformation from
+ * raw OpenAPI JSON to the SKMTC internal boolean representation with proper validation.
+ *
+ * The transformation follows a pipeline approach:
+ * 1. Parse nullable flag and extract base value
+ * 2. Parse example values with nullable support
+ * 3. Parse enumeration constraints (typically [true], [false], or [true, false])
+ * 4. Parse default values
+ * 5. Create final OasBoolean instance
+ *
+ * @param args - Transformation arguments
+ * @param args.value - The OpenAPI v3 boolean schema object to transform
+ * @param args.context - Parse context providing utilities and tracing
+ * @returns Transformed OAS boolean object with parsed properties
+ *
+ * @example Basic boolean transformation
+ * ```typescript
+ * import { toBoolean } from '@skmtc/core';
+ *
+ * const openApiBoolean = {
+ *   type: 'boolean',
+ *   default: false
+ * };
+ *
+ * const oasBoolean = toBoolean({
+ *   value: openApiBoolean,
+ *   context: parseContext
+ * });
+ *
+ * console.log(oasBoolean.default); // false
+ * ```
+ *
+ * @example Boolean with nullable and enum
+ * ```typescript
+ * const flagBoolean = {
+ *   type: 'boolean',
+ *   nullable: true,
+ *   enum: [true, null],
+ *   default: null,
+ *   example: true,
+ *   title: 'Feature Flag',
+ *   description: 'Whether the feature is enabled'
+ * };
+ *
+ * const oasBoolean = toBoolean({
+ *   value: flagBoolean,
+ *   context: parseContext
+ * });
+ *
+ * console.log(oasBoolean.nullable); // true
+ * console.log(oasBoolean.enums); // [true, null]
+ * ```
+ */
+export const toBoolean = ({ value, stackTrail, context }) => {
+    const { nullable, value: valueWithoutNullable } = parseNullable({
+        value,
+        context,
+        stackTrail
+    });
+    const { example: unparsedExample, ...valueWithoutExample } = valueWithoutNullable;
+    const example = parseExample({
+        value: unparsedExample,
+        context,
+        parent: valueWithoutNullable,
+        nullable,
+        check: isBoolean,
+        toMessage: item => `Removed invalid example. Expected "boolean", got: ${item}`,
+        stackTrail
+    });
+    const { enum: unparsedEnums, ...valueWithoutEnums } = valueWithoutExample;
+    const enums = parseEnum({
+        value: unparsedEnums,
+        nullable,
+        parent: valueWithoutExample,
+        stackTrail,
+        context,
+        check: isBoolean,
+        toMessage: item => `Removed invalid enum. Expected "boolean", got: ${item}`
+    });
+    const { default: unparsedDefaultValue, ...valueWithoutDefault } = valueWithoutEnums;
+    const defaultValue = parseDefault({
+        value: unparsedDefaultValue,
+        context,
+        parent: valueWithoutEnums,
+        nullable,
+        check: isBoolean,
+        toMessage: item => `Removed invalid default. Expected "boolean", got: ${item}`,
+        stackTrail
+    });
+    return toParsedBoolean({
+        context,
+        nullable,
+        example,
+        enums,
+        defaultValue,
+        value: valueWithoutDefault,
+        stackTrail
+    });
+};
+export const toParsedBoolean = ({ context, nullable, example, enums, defaultValue, value, stackTrail }) => {
+    if (!v.is(oasBooleanData, value)) {
+        v.parse(oasBooleanData, value);
+    }
+    const { type: _type, title, description, readOnly, writeOnly, deprecated, ...skipped } = value;
+    const extensionFields = toSpecificationExtensionsV3({
+        skipped,
+        parent: value,
+        context,
+        stackTrail,
+        parentType: 'schema:boolean'
+    });
+    return context.withStackTrail(stackTrail, () => new OasBoolean({
+        nullable,
+        title,
+        description,
+        example,
+        enums: enums,
+        default: defaultValue,
+        extensionFields,
+        readOnly,
+        writeOnly,
+        deprecated
+    }, context));
+};
+const isBoolean = (value) => {
+    return typeof value === 'boolean';
+};

package/esm/parse/v3-2/components/toComponentsV3.d.ts

@@ -0,0 +1,14 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { OasComponents } from '../../../oas/components/Components.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+/** An OpenAPI 3.2 Components Object: the 3.0/3.1 maps plus `mediaTypes`. */
+export type ComponentsObjectV32 = OpenAPIV3.ComponentsObject & {
+    mediaTypes?: Record<string, unknown>;
+};
+export type ToComponentsV3Args = {
+    components: ComponentsObjectV32 | undefined;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toComponentsV3: ({ components, stackTrail, context }: ToComponentsV3Args) => OasComponents | undefined;

package/esm/parse/v3-2/components/toComponentsV3.js

@@ -0,0 +1,43 @@
+import { toOptionalResponsesV3 } from '../response/toResponseV3.js';
+import { toHeadersV3 } from '../header/toHeadersV3.js';
+import { toLinksV3 } from '../link/toLinksV3.js';
+import { toOptionalSchemasV3 } from '../schema/toSchemasV3.js';
+import { toOptionalParametersV3 } from '../parameter/toParameterV3.js';
+import { toExamplesV3 } from '../example/toExamplesV3.js';
+import { toRequestBodiesV3 } from '../requestBody/toRequestBodiesV3.js';
+import { OasComponents } from '../../../oas/components/Components.js';
+import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+import { toSecuritySchemesV3 } from '../securitySchemes/toSecuritySchemes.js';
+export const toComponentsV3 = ({ components, stackTrail, context }) => {
+    if (!components) {
+        return undefined;
+    }
+    // `mediaTypes` is resolved where it is referenced, inside
+    // `toMediaTypeItemsV3`, so it is read here only to keep it off `skipped`.
+    const { schemas, responses, parameters, examples, requestBodies, headers, securitySchemes, links, mediaTypes: _mediaTypes, ...skipped } = components;
+    const extensionFields = toSpecificationExtensionsV3({
+        skipped,
+        parent: components,
+        context,
+        stackTrail,
+        parentType: 'components'
+    });
+    const fields = {
+        schemas: stackTrail.trace('schemas', st => toOptionalSchemasV3({ schemas, stackTrail: st, context })),
+        responses: stackTrail.trace('responses', st => toOptionalResponsesV3({ responses, stackTrail: st, context })),
+        parameters: stackTrail.trace('parameters', st => toOptionalParametersV3({ parameters, stackTrail: st, context })),
+        examples: toExamplesV3({
+            examples,
+            example: undefined,
+            exampleKey: 'TEMP',
+            stackTrail,
+            context
+        }),
+        requestBodies: stackTrail.trace('requestBodies', st => toRequestBodiesV3({ requestBodies, stackTrail: st, context })),
+        headers: stackTrail.trace('headers', st => toHeadersV3({ headers, stackTrail: st, context })),
+        securitySchemes: stackTrail.trace('securitySchemes', st => toSecuritySchemesV3({ securitySchemes, stackTrail: st, context })),
+        links: stackTrail.trace('links', st => toLinksV3({ links, stackTrail: st, context })),
+        extensionFields
+    };
+    return new OasComponents(fields);
+};

package/esm/parse/v3-2/contact/toContactV3.d.ts

@@ -0,0 +1,5 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { OasContact } from '../../../oas/contact/Contact.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export declare const toContactV3: (contact: OpenAPIV3.ContactObject, stackTrail: StackTrail, context: ParseContextType) => OasContact;

package/esm/parse/v3-2/contact/toContactV3.js

@@ -0,0 +1,18 @@
+import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+import { OasContact } from '../../../oas/contact/Contact.js';
+export const toContactV3 = (contact, stackTrail, context) => {
+    const { name, url, email, ...skipped } = contact;
+    const extensionFields = toSpecificationExtensionsV3({
+        skipped,
+        parent: contact,
+        context,
+        stackTrail,
+        parentType: 'contact'
+    });
+    return new OasContact({
+        name,
+        url,
+        email,
+        extensionFields
+    });
+};

package/esm/parse/v3-2/discriminator/toDiscriminatorV3.d.ts

@@ -0,0 +1,14 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { OasDiscriminator } from '../../../oas/discriminator/Discriminator.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+/** A 3.2 Discriminator Object: the 3.0 shape plus `defaultMapping`. */
+export type DiscriminatorObjectV32 = OpenAPIV3.DiscriminatorObject & {
+    defaultMapping?: string;
+};
+export type ToDiscriminatorV3Args = {
+    discriminator: DiscriminatorObjectV32 | undefined;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toDiscriminatorV3: ({ discriminator, stackTrail, context }: ToDiscriminatorV3Args) => OasDiscriminator | undefined;

package/esm/parse/v3-2/discriminator/toDiscriminatorV3.js

@@ -0,0 +1,21 @@
+import { OasDiscriminator } from '../../../oas/discriminator/Discriminator.js';
+import { isEmpty } from '../../../helpers/isEmpty.js';
+export const toDiscriminatorV3 = ({ discriminator, stackTrail, context }) => {
+    if (!discriminator) {
+        return undefined;
+    }
+    const { propertyName, mapping, defaultMapping, ...skipped } = discriminator;
+    if (!isEmpty(skipped)) {
+        context.logSkippedFields({
+            skipped,
+            parent: discriminator,
+            parentType: 'discriminator',
+            stackTrail
+        });
+    }
+    return new OasDiscriminator({
+        propertyName,
+        mapping,
+        defaultMapping
+    });
+};

package/esm/parse/v3-2/document/toDocumentFieldsV3.d.ts

@@ -0,0 +1,16 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { type WebhooksObject } from '../webhook/toWebhooksV3.js';
+import type { DocumentFields } from '../../../oas/document/Document.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export type ToDocumentV3Args = {
+    documentObject: Omit<OpenAPIV3.Document, 'paths'> & {
+        paths?: OpenAPIV3.PathsObject;
+        webhooks?: WebhooksObject;
+        /** The document's own URI (3.2) */
+        $self?: string;
+    };
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toDocumentFieldsV3: ({ documentObject, stackTrail, context }: ToDocumentV3Args) => DocumentFields;

package/esm/parse/v3-2/document/toDocumentFieldsV3.js

@@ -0,0 +1,33 @@
+import { toTagsV3 } from '../tag/toTagsV3.js';
+import { toOperationsV3 } from '../operation/toOperationsV3.js';
+import { toWebhooksV3 } from '../webhook/toWebhooksV3.js';
+import { toComponentsV3 } from '../components/toComponentsV3.js';
+import { toInfoV3 } from '../info/toInfoV3.js';
+import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+import { toOptionalServersV3 } from '../server/toServerV3.js';
+import { toSecurityRequirementsV3 } from '../securityRequirement/toSecurityRequirement.js';
+import { toExternalDocs } from '../externalDocs/toExternalDocs.js';
+export const toDocumentFieldsV3 = ({ documentObject, stackTrail, context }) => {
+    const { openapi, $self, info, paths, components, tags, servers, security, externalDocs, webhooks, ...skipped } = documentObject;
+    const extensionFields = toSpecificationExtensionsV3({
+        skipped,
+        parent: documentObject,
+        context,
+        stackTrail,
+        parentType: 'document'
+    });
+    return {
+        openapi,
+        $self,
+        info: stackTrail.trace('info', st => toInfoV3({ info, stackTrail: st, context })),
+        servers: stackTrail.trace('servers', st => toOptionalServersV3({ servers, stackTrail: st, context })),
+        operations: stackTrail.trace('paths', st => toOperationsV3({ paths, stackTrail: st, context })),
+        webhooks: stackTrail.trace('webhooks', st => toWebhooksV3({ webhooks, stackTrail: st, context })),
+        components: stackTrail.trace('components', st => toComponentsV3({ components, stackTrail: st, context })),
+        tags: stackTrail.trace('tags', st => toTagsV3({ tags, stackTrail: st, context })),
+        security: stackTrail.trace('security', st => toSecurityRequirementsV3({ security, stackTrail: st, context })),
+        extensionFields,
+        externalDocs: stackTrail.trace('externalDocs', st => toExternalDocs({ externalDocs, stackTrail: st, context }))
+    };
+};
+// stackTrail.trace('info', (x) => formatNumber(x))

package/esm/parse/v3-2/example/toExamplesV3.d.ts

@@ -0,0 +1,77 @@
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { OpenAPIV3 } from 'openapi-types';
+import { OasExample } from '../../../oas/example/Example.js';
+import type { OasRef } from '../../../oas/ref/Ref.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+/** A 3.2 Example Object: the 3.0 shape plus `dataValue` and `serializedValue`. */
+export type ExampleObjectV32 = OpenAPIV3.ExampleObject & {
+    dataValue?: unknown;
+    serializedValue?: string;
+};
+export type ToExampleSimpleV3Args = {
+    /**
+     * The example value itself. The singular `example` field of a media type,
+     * parameter or header is a LITERAL value — not an Example Object — so it
+     * carries no `summary`, `description` or `externalValue` to read.
+     */
+    example: unknown;
+    /** The stack trail for tracing */
+    stackTrail: StackTrail;
+    /** Parse context for tracing and error handling */
+    context: ParseContextType;
+};
+/**
+ * Creates a simple OAS example from a value.
+ *
+ * Wraps a literal example value as an {@link OasExample}. Used for the singular
+ * `example` field, where only the value exists.
+ *
+ * @param args - Arguments containing the example value
+ * @returns OasExample object with the provided value
+ */
+export declare const toExampleSimpleV3: ({ example }: ToExampleSimpleV3Args) => OasExample | OasRef<"example">;
+/**
+ * Arguments for processing OpenAPI v3 examples into OAS example objects.
+ *
+ * Handles both single example and examples collection scenarios,
+ * with context for tracing and error handling.
+ */
+export type ToExamplesV3Args = {
+    /** The singular `example` field — a literal value, not an Example Object */
+    example: unknown;
+    /** Collection of named examples (OpenAPI v3 format) */
+    examples: Record<string, ExampleObjectV32 | OpenAPIV3.ReferenceObject> | undefined;
+    /** Key name for the example context */
+    exampleKey: string;
+    /** The stack trail for tracing */
+    stackTrail: StackTrail;
+    /** Parse context for tracing and error handling */
+    context: ParseContextType;
+};
+/**
+ * Processes OpenAPI v3 examples into OAS example objects.
+ *
+ * Handles both single example and examples collection scenarios,
+ * converting them to the internal OAS representation. Provides
+ * warnings when both formats are specified simultaneously.
+ *
+ * @param args - Arguments containing example data and context
+ * @returns Record of processed examples, or undefined if no examples
+ */
+export declare const toExamplesV3: ({ example, examples, exampleKey, stackTrail, context }: ToExamplesV3Args) => Record<string, OasExample | OasRef<"example">> | undefined;
+export type ToExampleV3Args = {
+    example: ExampleObjectV32 | OpenAPIV3.ReferenceObject;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+/**
+ * Processes a single OpenAPI v3 example into an OAS example object.
+ *
+ * Converts OpenAPI v3 example objects or references into the internal
+ * OAS representation, handling both direct examples and $ref references.
+ * Processes specification extensions and maintains all example metadata.
+ *
+ * @param args - Arguments containing the example and parsing context
+ * @returns OasExample object or reference to an example
+ */
+export declare const toExampleV3: ({ example, stackTrail, context }: ToExampleV3Args) => OasExample | OasRef<"example">;

package/esm/parse/v3-2/example/toExamplesV3.js

@@ -0,0 +1,143 @@
+import { isRef } from '../../../helpers/refFns.js';
+import { toRefV31 } from '../ref/toRefV31.js';
+import { OasExample } from '../../../oas/example/Example.js';
+import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+/**
+ * Creates a simple OAS example from a value.
+ *
+ * Wraps a literal example value as an {@link OasExample}. Used for the singular
+ * `example` field, where only the value exists.
+ *
+ * @param args - Arguments containing the example value
+ * @returns OasExample object with the provided value
+ */
+export const toExampleSimpleV3 = ({ example }) => {
+    const fields = { value: example };
+    return new OasExample(fields);
+};
+/**
+ * Processes OpenAPI v3 examples into OAS example objects.
+ *
+ * Handles both single example and examples collection scenarios,
+ * converting them to the internal OAS representation. Provides
+ * warnings when both formats are specified simultaneously.
+ *
+ * @param args - Arguments containing example data and context
+ * @returns Record of processed examples, or undefined if no examples
+ */
+export const toExamplesV3 = ({ example, examples, exampleKey, stackTrail, context }) => {
+    // An empty map is declared but carries nothing, so it cannot be the richer
+    // field — letting it win would discard the singular in favour of no examples
+    // at all.
+    const namedExamples = examples && Object.keys(examples).length > 0 ? examples : undefined;
+    // `example` is a literal, so test presence rather than truthiness — `false`,
+    // `0` and `''` are all valid example values.
+    if (example !== undefined && examples !== undefined) {
+        context.logIssue({
+            key: 'example',
+            level: 'warning',
+            message: `Both example and examples are defined for ${exampleKey}; using ${namedExamples ? 'examples' : 'example'}`,
+            parent: examples,
+            stackTrail,
+            type: 'EXAMPLE_AND_EXAMPLES_DEFINED'
+        });
+    }
+    // The spec makes the two mutually exclusive, so reaching here with both is
+    // malformed input. Prefer `examples`: it is the richer field — many entries,
+    // each with a summary and description — and the singular carries nothing it
+    // cannot express, so this discards strictly less.
+    if (namedExamples) {
+        return stackTrail.trace('examples', st => {
+            const output = {};
+            const entries = Object.entries(namedExamples);
+            for (const [key, value] of entries) {
+                output[key] = st.trace(key, st2 => toExampleV3({ example: value, stackTrail: st2, context }));
+            }
+            return output;
+        });
+    }
+    if (example !== undefined) {
+        return {
+            [exampleKey]: stackTrail.trace('example', st => toExampleSimpleV3({ example, stackTrail: st, context }))
+        };
+    }
+    return undefined;
+};
+/**
+ * Processes a single OpenAPI v3 example into an OAS example object.
+ *
+ * Converts OpenAPI v3 example objects or references into the internal
+ * OAS representation, handling both direct examples and $ref references.
+ * Processes specification extensions and maintains all example metadata.
+ *
+ * @param args - Arguments containing the example and parsing context
+ * @returns OasExample object or reference to an example
+ */
+export const toExampleV3 = ({ example, stackTrail, context }) => {
+    if (isRef(example)) {
+        return toRefV31({ ref: example, refType: 'example', stackTrail, context });
+    }
+    // `externalValue` is the alternative to `value` — an example too large or too
+    // awkward to inline. Leaving it in `skipped` both loses it and reports a
+    // standard field as an unexpected property.
+    const { summary, description, value, dataValue, serializedValue, externalValue, ...skipped } = example;
+    const extensionFields = toSpecificationExtensionsV3({
+        skipped,
+        parent: example,
+        context,
+        stackTrail,
+        parentType: 'example'
+    });
+    const kept = toKeptValueFields({
+        present: { dataValue, value, serializedValue, externalValue },
+        example,
+        stackTrail,
+        context
+    });
+    return new OasExample({
+        summary,
+        description,
+        value: kept.has('value') ? value : undefined,
+        dataValue: kept.has('dataValue') ? dataValue : undefined,
+        serializedValue: kept.has('serializedValue') ? serializedValue : undefined,
+        externalValue: kept.has('externalValue') ? externalValue : undefined,
+        extensionFields
+    });
+};
+/** The value fields in the order they are kept when two conflict. */
+const valueFieldPrecedence = [
+    'dataValue',
+    'value',
+    'serializedValue',
+    'externalValue'
+];
+/** The fields the 3.2 spec forbids next to each value field. */
+const valueFieldExclusions = {
+    dataValue: ['value'],
+    value: ['dataValue', 'serializedValue', 'externalValue'],
+    serializedValue: ['value', 'externalValue'],
+    externalValue: ['value', 'serializedValue']
+};
+/**
+ * Picks the value fields to keep. A field that conflicts with one already
+ * kept is logged as `INVALID_EXAMPLE` and dropped.
+ */
+const toKeptValueFields = ({ present, example, stackTrail, context }) => {
+    return valueFieldPrecedence
+        .filter(field => present[field] !== undefined)
+        .reduce((kept, field) => {
+        const conflict = valueFieldExclusions[field].find(other => kept.has(other));
+        if (conflict === undefined) {
+            return new Set([...kept, field]);
+        }
+        context.logIssue({
+            key: field,
+            level: 'warning',
+            message: `Example has both '${conflict}' and '${field}', which are mutually exclusive; keeping '${conflict}'`,
+            parent: example,
+            stackTrail,
+            type: 'INVALID_EXAMPLE'
+        });
+        return kept;
+    }, new Set());
+};

package/esm/parse/v3-2/externalDocs/toExternalDocs.d.ts

@@ -0,0 +1,10 @@
+import { OasExternalDocs } from '../../../oas/externalDocs/ExternalDocs.js';
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export type ToExternalDocsArgs = {
+    externalDocs: OpenAPIV3.ExternalDocumentationObject | undefined;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toExternalDocs: ({ externalDocs, stackTrail }: ToExternalDocsArgs) => OasExternalDocs | undefined;

package/esm/parse/v3-2/externalDocs/toExternalDocs.js

@@ -0,0 +1,15 @@
+import { OasExternalDocs } from '../../../oas/externalDocs/ExternalDocs.js';
+import * as v from 'valibot';
+import { oasExternalDocsData } from '../../../oas/externalDocs/externalDocsTypes.js';
+export const toExternalDocs = ({ externalDocs, stackTrail }) => {
+    if (!externalDocs) {
+        return undefined;
+    }
+    if (!v.is(oasExternalDocsData, externalDocs)) {
+        v.parse(oasExternalDocsData, externalDocs);
+    }
+    return new OasExternalDocs({
+        url: externalDocs.url,
+        description: externalDocs.description
+    });
+};

package/esm/parse/v3-2/header/toHeadersV3.d.ts

@@ -0,0 +1,18 @@
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { OpenAPIV3 } from 'openapi-types';
+import { OasHeader } from '../../../oas/header/Header.js';
+import type { OasRef } from '../../../oas/ref/Ref.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export type ToHeadersV3Args = {
+    headers: Record<string, OpenAPIV3.ReferenceObject | OpenAPIV3.HeaderObject> | undefined;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toHeadersV3: ({ headers, stackTrail, context }: ToHeadersV3Args) => Record<string, OasHeader | OasRef<"header">> | undefined;
+export type ToHeaderV3Args = {
+    header: OpenAPIV3.ReferenceObject | OpenAPIV3.HeaderObject;
+    /** The header's name, used to key a singular `example` */
+    name: string;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};