@skmtc/core 0.29.0 → 0.31.0

package/esm/parse/v3-2/securitySchemes/toSecuritySchemes.js

@@ -0,0 +1,152 @@
+import { OasHttpSecurityScheme, OasApiKeySecurityScheme, OasOAuth2SecurityScheme, OasOpenIdSecurityScheme } from '../../../oas/securitySchemes/SecurityScheme.js';
+import * as v from 'valibot';
+import { oasApiKeySecuritySchemeData, oasHttpSecuritySchemeData, oasOAuth2FlowsData, oasOAuth2SecuritySchemeData, oasOpenIdSecuritySchemeData } from '../../../oas/securitySchemes/security-scheme-types.js';
+import { toRefV31 } from '../ref/toRefV31.js';
+import { isRef } from '../../../helpers/refFns.js';
+import { tryParseAt } from '../../../context/tryParseAt.js';
+import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+// The shared schemas are the 3.0/3.1 shape; these add the 3.2 fields.
+const deprecatedField = v.optional(v.boolean());
+const httpSecuritySchemeData = v.object({
+    ...oasHttpSecuritySchemeData.entries,
+    deprecated: deprecatedField
+});
+const apiKeySecuritySchemeData = v.object({
+    ...oasApiKeySecuritySchemeData.entries,
+    deprecated: deprecatedField
+});
+const deviceAuthorizationOAuth2FlowData = v.object({
+    deviceAuthorizationUrl: v.string(),
+    tokenUrl: v.string(),
+    refreshUrl: v.optional(v.string()),
+    scopes: v.optional(v.record(v.string(), v.string()))
+});
+const oAuth2FlowsData = v.object({
+    ...oasOAuth2FlowsData.entries,
+    deviceAuthorization: v.optional(deviceAuthorizationOAuth2FlowData)
+});
+const oAuth2SecuritySchemeData = v.object({
+    ...oasOAuth2SecuritySchemeData.entries,
+    deprecated: deprecatedField,
+    oauth2MetadataUrl: v.optional(v.string()),
+    flows: oAuth2FlowsData
+});
+const openIdSecuritySchemeData = v.object({
+    ...oasOpenIdSecuritySchemeData.entries,
+    deprecated: deprecatedField
+});
+export const toSecuritySchemesV3 = ({ securitySchemes, stackTrail, context }) => {
+    if (!securitySchemes) {
+        return undefined;
+    }
+    const output = {};
+    for (const [key, value] of Object.entries(securitySchemes)) {
+        // Isolate per scheme: a single malformed security scheme is logged and
+        // skipped, the rest of the record continues (parity with toSchemasV3).
+        const parsed = tryParseAt({
+            stackTrail,
+            key,
+            context,
+            type: 'INVALID_SECURITY_SCHEME',
+            parent: value,
+            fn: st => toSecuritySchemeV3({ securityScheme: value, stackTrail: st, context })
+        });
+        if (parsed !== undefined) {
+            output[key] = parsed;
+        }
+    }
+    return output;
+};
+/**
+ * Log the keys of `value` that `known` does not name as skipped fields.
+ * `v.parse` on a `v.object` schema strips unknown keys, so they are read
+ * off the raw object. `x-` extensions are not logged.
+ */
+const logSkippedKeys = ({ value, known, parentType, stackTrail, context }) => {
+    const skipped = Object.fromEntries(Object.entries(value).filter(([key]) => !Object.hasOwn(known, key)));
+    toSpecificationExtensionsV3({ skipped, parent: value, parentType, stackTrail, context });
+};
+const toSecuritySchemeV3 = ({ securityScheme, stackTrail, context }) => {
+    if (isRef(securityScheme)) {
+        return toRefV31({ ref: securityScheme, refType: 'securityScheme', stackTrail, context });
+    }
+    switch (securityScheme.type) {
+        case 'http': {
+            const { description, deprecated, scheme, bearerFormat } = v.parse(httpSecuritySchemeData, securityScheme);
+            logSkippedKeys({
+                value: securityScheme,
+                known: httpSecuritySchemeData.entries,
+                parentType: 'securityScheme:http',
+                stackTrail,
+                context
+            });
+            return new OasHttpSecurityScheme({
+                description,
+                deprecated,
+                scheme,
+                bearerFormat
+            });
+        }
+        case 'apiKey': {
+            const { in: location, description, deprecated, name } = v.parse(apiKeySecuritySchemeData, securityScheme);
+            logSkippedKeys({
+                value: securityScheme,
+                known: apiKeySecuritySchemeData.entries,
+                parentType: 'securityScheme:apiKey',
+                stackTrail,
+                context
+            });
+            return new OasApiKeySecurityScheme({
+                description,
+                deprecated,
+                name,
+                in: location
+            });
+        }
+        case 'oauth2': {
+            const { flows, description, deprecated, oauth2MetadataUrl } = v.parse(oAuth2SecuritySchemeData, securityScheme);
+            logSkippedKeys({
+                value: securityScheme,
+                known: oAuth2SecuritySchemeData.entries,
+                parentType: 'securityScheme:oauth2',
+                stackTrail,
+                context
+            });
+            stackTrail.trace('flows', st => logSkippedKeys({
+                value: securityScheme.flows,
+                known: oAuth2FlowsData.entries,
+                parentType: 'oauthFlows',
+                stackTrail: st,
+                context
+            }));
+            return new OasOAuth2SecurityScheme({
+                description,
+                deprecated,
+                oauth2MetadataUrl,
+                flows
+            });
+        }
+        case 'openIdConnect': {
+            const { description, deprecated, openIdConnectUrl } = v.parse(openIdSecuritySchemeData, securityScheme);
+            logSkippedKeys({
+                value: securityScheme,
+                known: openIdSecuritySchemeData.entries,
+                parentType: 'securityScheme:openIdConnect',
+                stackTrail,
+                context
+            });
+            return new OasOpenIdSecurityScheme({
+                description,
+                deprecated,
+                openIdConnectUrl
+            });
+        }
+        default: {
+            // Exhaustive over the discriminated union: a value reaching here has a
+            // `type` outside the OpenAPI set. `tryParseAt` isolates the throw to
+            // this one scheme.
+            const _exhaustiveCheck = securityScheme;
+            throw new Error(`Unknown security scheme type: ${JSON.stringify(_exhaustiveCheck)}`);
+        }
+    }
+};

package/esm/parse/v3-2/server/toServerV3.d.ts

@@ -0,0 +1,26 @@
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { OpenAPIV3 } from 'openapi-types';
+import { OasServer } from '../../../oas/server/Server.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+/** A 3.2 Server Object: the 3.0 shape plus `name`. */
+export type ServerObjectV32 = OpenAPIV3.ServerObject & {
+    name?: string;
+};
+export type ToServersV3Args = {
+    servers: ServerObjectV32[];
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toServersV3: ({ servers, stackTrail, context }: ToServersV3Args) => OasServer[];
+export type ToOptionalServersV3Args = {
+    servers: ServerObjectV32[] | undefined;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toOptionalServersV3: ({ servers, stackTrail, context }: ToOptionalServersV3Args) => OasServer[] | undefined;
+export type ToServerV3Args = {
+    server: ServerObjectV32;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toServerV3: ({ server, stackTrail, context }: ToServerV3Args) => OasServer;

package/esm/parse/v3-2/server/toServerV3.js

@@ -0,0 +1,31 @@
+import { OasServer } from '../../../oas/server/Server.js';
+import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+import { toOptionalServerVariablesV3 } from '../serverVariable/toServerVariableV3.js';
+export const toServersV3 = ({ servers, stackTrail, context }) => {
+    return servers.map((server, index) => {
+        return stackTrail.trace(server.url ?? index, st => toServerV3({ server, stackTrail: st, context }));
+    });
+};
+export const toOptionalServersV3 = ({ servers, stackTrail, context }) => {
+    if (!servers) {
+        return undefined;
+    }
+    return toServersV3({ servers, stackTrail, context });
+};
+export const toServerV3 = ({ server, stackTrail, context }) => {
+    const { description, name, url, variables, ...skipped } = server;
+    const extensionFields = toSpecificationExtensionsV3({
+        skipped,
+        parent: server,
+        context,
+        stackTrail,
+        parentType: 'server'
+    });
+    return new OasServer({
+        description,
+        name,
+        url,
+        variables: toOptionalServerVariablesV3({ serverVariables: variables, stackTrail, context }),
+        extensionFields
+    });
+};

package/esm/parse/v3-2/serverVariable/toServerVariableV3.d.ts

@@ -0,0 +1,22 @@
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { OpenAPIV3 } from 'openapi-types';
+import { OasServerVariable } from '../../../oas/serverVariable/ServerVariable.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export type ToServerVariablesV3Args = {
+    serverVariables: Record<string, OpenAPIV3.ServerVariableObject>;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toServerVariablesV3: ({ serverVariables, stackTrail, context }: ToServerVariablesV3Args) => Record<string, OasServerVariable>;
+export type ToOptionalServerVariablesV3Args = {
+    serverVariables: Record<string, OpenAPIV3.ServerVariableObject> | undefined;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toOptionalServerVariablesV3: ({ serverVariables, stackTrail, context }: ToOptionalServerVariablesV3Args) => Record<string, OasServerVariable> | undefined;
+export type ToServerVariableV3Args = {
+    serverVariable: OpenAPIV3.ServerVariableObject;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toServerVariableV3: ({ serverVariable, stackTrail, context }: ToServerVariableV3Args) => OasServerVariable;

package/esm/parse/v3-2/serverVariable/toServerVariableV3.js

@@ -0,0 +1,30 @@
+import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+import { OasServerVariable } from '../../../oas/serverVariable/ServerVariable.js';
+export const toServerVariablesV3 = ({ serverVariables, stackTrail, context }) => {
+    return Object.fromEntries(Object.entries(serverVariables).map(([key, serverVariable]) => [
+        key,
+        toServerVariableV3({ serverVariable, stackTrail, context })
+    ]));
+};
+export const toOptionalServerVariablesV3 = ({ serverVariables, stackTrail, context }) => {
+    if (!serverVariables) {
+        return undefined;
+    }
+    return toServerVariablesV3({ serverVariables, stackTrail, context });
+};
+export const toServerVariableV3 = ({ serverVariable, stackTrail, context }) => {
+    const { description, default: defaultValue, enum: enums, ...skipped } = serverVariable;
+    const extensionFields = toSpecificationExtensionsV3({
+        skipped,
+        parent: serverVariable,
+        context,
+        stackTrail,
+        parentType: 'serverVariable'
+    });
+    return new OasServerVariable({
+        description,
+        default: defaultValue,
+        enums,
+        extensionFields
+    });
+};

package/esm/parse/v3-2/specificationExtensions/toSpecificationExtensionsV3.d.ts

@@ -0,0 +1,14 @@
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export type ToSpecificationExtensionsV3Args = {
+    skipped: Record<string, unknown>;
+    parent: unknown;
+    parentType: string;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toSpecificationExtensionsV3: ({ skipped: s, parent, parentType, stackTrail, context }: ToSpecificationExtensionsV3Args) => Record<string, unknown> | undefined;
+export declare const extractExtensions: (item: Record<string, unknown>) => {
+    skipped: Record<string, unknown> | undefined;
+    extensionFields: Record<string, unknown> | undefined;
+};

package/esm/parse/v3-2/specificationExtensions/toSpecificationExtensionsV3.js

@@ -0,0 +1,25 @@
+import { isEmpty } from '../../../helpers/isEmpty.js';
+export const toSpecificationExtensionsV3 = ({ skipped: s, parent, parentType, stackTrail, context }) => {
+    const { skipped, extensionFields } = extractExtensions(s);
+    if (skipped) {
+        context.logSkippedFields({ skipped, parent, stackTrail, parentType });
+    }
+    return extensionFields;
+};
+export const extractExtensions = (item) => {
+    const entries = Object.entries(item);
+    const skipped = {};
+    const extensionFields = {};
+    for (const [key, value] of entries) {
+        if (!key.startsWith('x-')) {
+            skipped[key] = value;
+        }
+        else {
+            extensionFields[key] = value;
+        }
+    }
+    return {
+        skipped: isEmpty(skipped) ? undefined : skipped,
+        extensionFields: isEmpty(extensionFields) ? undefined : extensionFields
+    };
+};

package/esm/parse/v3-2/string/toString.d.ts

@@ -0,0 +1,146 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { OasString } from '../../../oas/string/String.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+/**
+ * Arguments for transforming an OpenAPI string schema into OAS representation.
+ */
+export type ToStringArgs = {
+    /** The OpenAPI v3 schema object to transform (must be type 'string') */
+    value: OpenAPIV3.SchemaObject;
+    /** The stack trail for tracing */
+    stackTrail: StackTrail;
+    /** Parse context providing utilities and tracing capabilities */
+    context: ParseContextType;
+};
+/**
+ * Transforms an OpenAPI v3 string schema object into an internal OAS string representation.
+ *
+ * This function processes OpenAPI string 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 string representation with proper validation
+ * of string formats and constraints.
+ *
+ * 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
+ * 4. Parse default values
+ * 5. Create final OasString instance with format validation
+ *
+ * @param args - Transformation arguments
+ * @param args.context - Parse context providing utilities and tracing
+ * @param args.value - The OpenAPI v3 string schema object to transform
+ * @returns Transformed OAS string object with parsed properties
+ *
+ * @example Basic string transformation
+ * ```typescript
+ * import { toString } from '@skmtc/core';
+ *
+ * const openApiString = {
+ *   type: 'string',
+ *   format: 'email',
+ *   maxLength: 255,
+ *   pattern: '^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$'
+ * };
+ *
+ * const oasString = toString({
+ *   context: parseContext,
+ *   value: openApiString
+ * });
+ *
+ * console.log(oasString.format); // 'email'
+ * console.log(oasString.maxLength); // 255
+ * ```
+ *
+ * @example String with nullable and enums
+ * ```typescript
+ * const statusString = {
+ *   type: 'string',
+ *   nullable: true,
+ *   enum: ['active', 'inactive', 'pending', null],
+ *   default: 'active',
+ *   example: 'pending'
+ * };
+ *
+ * const oasString = toString({
+ *   context: parseContext,
+ *   value: statusString
+ * });
+ *
+ * console.log(oasString.nullable); // true
+ * console.log(oasString.enums); // ['active', 'inactive', 'pending', null]
+ * ```
+ */
+export declare const toString: ({ context, value, stackTrail }: ToStringArgs) => OasString;
+type ToParsedStringArgs<Nullable extends boolean | undefined> = {
+    value: Omit<OpenAPIV3.SchemaObject, 'nullable' | 'example' | 'enums' | 'default'>;
+    context: ParseContextType;
+    nullable: Nullable;
+    example: Nullable extends true ? string | null | undefined : string | undefined;
+    enums: Nullable extends true ? (string | null)[] | undefined : string[] | undefined;
+    defaultValue: Nullable extends true ? string | null | undefined : string | undefined;
+    stackTrail: StackTrail;
+};
+/**
+ * Creates an OAS string instance from pre-parsed string schema components.
+ *
+ * This function is the final step in the string transformation pipeline, taking
+ * already-parsed nullable, example, enum, and default values and combining them
+ * with the remaining string properties to create the complete OasString instance.
+ *
+ * The function handles format validation against known OpenAPI string formats,
+ * length constraints parsing, pattern validation, and specification extension
+ * processing. It logs warnings for unrecognized formats while still preserving
+ * them in the output.
+ *
+ * @template Nullable - Boolean type indicating if the string can be null
+ * @param args - Pre-parsed string components
+ * @param args.context - Parse context for tracing and issue logging
+ * @param args.nullable - Parsed nullable flag
+ * @param args.example - Parsed example value (type-safe with nullable)
+ * @param args.enums - Parsed enumeration constraints (type-safe with nullable)
+ * @param args.defaultValue - Parsed default value (type-safe with nullable)
+ * @param args.value - OpenAPI string object without parsed fields
+ * @returns Complete OAS string instance with all properties and validation
+ *
+ * @example Date-time string with validation
+ * ```typescript
+ * const dateTimeString = toParsedString({
+ *   context: parseContext,
+ *   nullable: false,
+ *   example: '2023-12-25T10:00:00Z',
+ *   enums: undefined,
+ *   defaultValue: undefined,
+ *   value: {
+ *     type: 'string',
+ *     format: 'date-time',
+ *     title: 'Event Date',
+ *     description: 'When the event occurs'
+ *   }
+ * });
+ *
+ * console.log(dateTimeString.format); // 'date-time'
+ * ```
+ *
+ * @example String with custom format (generates warning)
+ * ```typescript
+ * const customFormatString = toParsedString({
+ *   context: parseContext,
+ *   nullable: false,
+ *   example: 'ABC123',
+ *   enums: undefined,
+ *   defaultValue: undefined,
+ *   value: {
+ *     type: 'string',
+ *     format: 'custom-id', // Unknown format, will log warning
+ *     pattern: '^[A-Z]{3}[0-9]{3}$'
+ *   }
+ * });
+ *
+ * // Logs: "Unexpected format: custom-id"
+ * console.log(customFormatString.format); // 'custom-id' (still preserved)
+ * ```
+ */
+export declare const toParsedString: <Nullable extends boolean | undefined>({ context, nullable, example, enums, defaultValue, value, stackTrail }: ToParsedStringArgs<Nullable>) => OasString<Nullable>;
+export {};

package/esm/parse/v3-2/string/toString.js

@@ -0,0 +1,211 @@
+import { OasString } from '../../../oas/string/String.js';
+import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+import { oasStringData } from '../../../oas/string/string-types.js';
+import * as v from 'valibot';
+import { parseNullable } from '../_helpers/parseNullable.js';
+import { parseEnum } from '../_helpers/parseEnum.js';
+import { parseExample } from '../_helpers/parseExample.js';
+import { parseDefault } from '../_helpers/parseDefault.js';
+/**
+ * Transforms an OpenAPI v3 string schema object into an internal OAS string representation.
+ *
+ * This function processes OpenAPI string 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 string representation with proper validation
+ * of string formats and constraints.
+ *
+ * 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
+ * 4. Parse default values
+ * 5. Create final OasString instance with format validation
+ *
+ * @param args - Transformation arguments
+ * @param args.context - Parse context providing utilities and tracing
+ * @param args.value - The OpenAPI v3 string schema object to transform
+ * @returns Transformed OAS string object with parsed properties
+ *
+ * @example Basic string transformation
+ * ```typescript
+ * import { toString } from '@skmtc/core';
+ *
+ * const openApiString = {
+ *   type: 'string',
+ *   format: 'email',
+ *   maxLength: 255,
+ *   pattern: '^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$'
+ * };
+ *
+ * const oasString = toString({
+ *   context: parseContext,
+ *   value: openApiString
+ * });
+ *
+ * console.log(oasString.format); // 'email'
+ * console.log(oasString.maxLength); // 255
+ * ```
+ *
+ * @example String with nullable and enums
+ * ```typescript
+ * const statusString = {
+ *   type: 'string',
+ *   nullable: true,
+ *   enum: ['active', 'inactive', 'pending', null],
+ *   default: 'active',
+ *   example: 'pending'
+ * };
+ *
+ * const oasString = toString({
+ *   context: parseContext,
+ *   value: statusString
+ * });
+ *
+ * console.log(oasString.nullable); // true
+ * console.log(oasString.enums); // ['active', 'inactive', 'pending', null]
+ * ```
+ */
+export const toString = ({ context, value, stackTrail }) => {
+    if (value.type === 'string' && Object.keys(value).length === 1) {
+        return context.withStackTrail(stackTrail, () => new OasString({}, context));
+    }
+    const { nullable, value: valueWithoutNullable } = parseNullable({
+        value,
+        context,
+        stackTrail
+    });
+    const { example: unparsedExample, ...valueWithoutExample } = valueWithoutNullable;
+    const example = parseExample({
+        value: unparsedExample,
+        context,
+        parent: valueWithoutNullable,
+        nullable,
+        check: isString,
+        toMessage: item => `Removed invalid example. Expected "string", got: ${item}`,
+        stackTrail
+    });
+    const { enum: unparsedEnums, ...valueWithoutEnums } = valueWithoutExample;
+    const enums = parseEnum({
+        value: unparsedEnums,
+        nullable,
+        parent: valueWithoutExample,
+        context,
+        check: isString,
+        toMessage: item => `Removed invalid enum. Expected "string", got: ${item}`,
+        stackTrail
+    });
+    const { default: unparsedDefaultValue, ...valueWithoutDefault } = valueWithoutEnums;
+    const defaultValue = parseDefault({
+        value: unparsedDefaultValue,
+        context,
+        parent: valueWithoutEnums,
+        nullable,
+        check: isString,
+        toMessage: item => `Removed invalid default. Expected "string", got: ${item}`,
+        stackTrail
+    });
+    return toParsedString({
+        context,
+        nullable,
+        example,
+        enums,
+        defaultValue,
+        value: valueWithoutDefault,
+        stackTrail
+    });
+};
+/**
+ * Creates an OAS string instance from pre-parsed string schema components.
+ *
+ * This function is the final step in the string transformation pipeline, taking
+ * already-parsed nullable, example, enum, and default values and combining them
+ * with the remaining string properties to create the complete OasString instance.
+ *
+ * The function handles format validation against known OpenAPI string formats,
+ * length constraints parsing, pattern validation, and specification extension
+ * processing. It logs warnings for unrecognized formats while still preserving
+ * them in the output.
+ *
+ * @template Nullable - Boolean type indicating if the string can be null
+ * @param args - Pre-parsed string components
+ * @param args.context - Parse context for tracing and issue logging
+ * @param args.nullable - Parsed nullable flag
+ * @param args.example - Parsed example value (type-safe with nullable)
+ * @param args.enums - Parsed enumeration constraints (type-safe with nullable)
+ * @param args.defaultValue - Parsed default value (type-safe with nullable)
+ * @param args.value - OpenAPI string object without parsed fields
+ * @returns Complete OAS string instance with all properties and validation
+ *
+ * @example Date-time string with validation
+ * ```typescript
+ * const dateTimeString = toParsedString({
+ *   context: parseContext,
+ *   nullable: false,
+ *   example: '2023-12-25T10:00:00Z',
+ *   enums: undefined,
+ *   defaultValue: undefined,
+ *   value: {
+ *     type: 'string',
+ *     format: 'date-time',
+ *     title: 'Event Date',
+ *     description: 'When the event occurs'
+ *   }
+ * });
+ *
+ * console.log(dateTimeString.format); // 'date-time'
+ * ```
+ *
+ * @example String with custom format (generates warning)
+ * ```typescript
+ * const customFormatString = toParsedString({
+ *   context: parseContext,
+ *   nullable: false,
+ *   example: 'ABC123',
+ *   enums: undefined,
+ *   defaultValue: undefined,
+ *   value: {
+ *     type: 'string',
+ *     format: 'custom-id', // Unknown format, will log warning
+ *     pattern: '^[A-Z]{3}[0-9]{3}$'
+ *   }
+ * });
+ *
+ * // Logs: "Unexpected format: custom-id"
+ * console.log(customFormatString.format); // 'custom-id' (still preserved)
+ * ```
+ */
+export const toParsedString = ({ context, nullable, example, enums, defaultValue, value, stackTrail }) => {
+    if (!v.is(oasStringData, value)) {
+        v.parse(oasStringData, value);
+    }
+    const { type: _type, title, description, format, maxLength, minLength, pattern, readOnly, writeOnly, deprecated, ...skipped } = value;
+    const extensionFields = toSpecificationExtensionsV3({
+        skipped,
+        parent: value,
+        context,
+        stackTrail,
+        parentType: 'schema:string'
+    });
+    // `format` is an open vocabulary — custom string formats (e.g. `decimal`,
+    // `utc_datetime`) are spec-legal. The value is preserved on the OasString
+    // below, so an unrecognised format is passed through, not warned.
+    return context.withStackTrail(stackTrail, () => new OasString({
+        title,
+        description,
+        enums,
+        nullable,
+        example,
+        format,
+        maxLength,
+        minLength,
+        pattern,
+        readOnly,
+        writeOnly,
+        default: defaultValue,
+        extensionFields,
+        deprecated
+    }, context));
+};
+const isString = (value) => {
+    return typeof value === 'string';
+};

package/esm/parse/v3-2/tag/toTagsV3.d.ts

@@ -0,0 +1,22 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { OasTag } from '../../../oas/tag/Tag.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+/** A 3.2 Tag Object: the 3.0 shape plus `summary`, `parent` and `kind`. */
+export type TagObjectV32 = OpenAPIV3.TagObject & {
+    summary?: string;
+    parent?: string;
+    kind?: string;
+};
+export type ToTagsV3Args = {
+    tags: TagObjectV32[] | undefined;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toTagsV3: ({ tags, stackTrail, context }: ToTagsV3Args) => OasTag[] | undefined;
+export type ToTagV3Args = {
+    tag: TagObjectV32;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toTagV3: ({ tag, stackTrail, context }: ToTagV3Args) => OasTag;