@scalar/workspace-store 0.41.2 → 0.43.0

package/dist/request-example/builder/helpers/get-example-from-schema.js

@@ -0,0 +1,568 @@
+import { isDefined } from '@scalar/helpers/array/is-defined';
+import { unpackProxyObject } from '../../../helpers/unpack-proxy.js';
+import { resolve } from '../../../resolve.js';
+/** Maximum recursion depth to prevent infinite loops in circular references */
+const MAX_LEVELS_DEEP = 10;
+/** Default name used for additional properties when no custom name is provided */
+const DEFAULT_ADDITIONAL_PROPERTIES_NAME = 'additionalProperty';
+/**
+ * Pre-computed date/time values to avoid expensive Date operations on every call.
+ * These are calculated once at module load time for better performance.
+ */
+const currentISOString = new Date().toISOString();
+const currentDateString = currentISOString.split('T')[0];
+const currentTimeString = currentISOString.split('T')[1].split('.')[0];
+/**
+ * Mapping of OpenAPI string formats to example values.
+ * Used to generate realistic examples for different string formats.
+ */
+const genericExampleValues = {
+    'date-time': currentISOString,
+    'date': currentDateString,
+    'email': 'hello@example.com',
+    'hostname': 'example.com',
+    // https://tools.ietf.org/html/rfc6531#section-3.3
+    'idn-email': 'jane.doe@example.com',
+    // https://tools.ietf.org/html/rfc5890#section-2.3.2.3
+    'idn-hostname': 'example.com',
+    'ipv4': '127.0.0.1',
+    'ipv6': '51d4:7fab:bfbf:b7d7:b2cb:d4b4:3dad:d998',
+    'iri-reference': '/entitiy/1',
+    // https://tools.ietf.org/html/rfc3987
+    'iri': 'https://example.com/entity/123',
+    'json-pointer': '/nested/objects',
+    'password': 'super-secret',
+    'regex': '/[a-z]/',
+    // https://tools.ietf.org/html/draft-handrews-relative-json-pointer-01
+    'relative-json-pointer': '1/nested/objects',
+    // full-time in https://tools.ietf.org/html/rfc3339#section-5.6
+    'time': currentTimeString,
+    // either a URI or relative-reference https://tools.ietf.org/html/rfc3986#section-4.1
+    'uri-reference': '../folder',
+    'uri-template': 'https://example.com/{id}',
+    'uri': 'https://example.com',
+    'uuid': '123e4567-e89b-12d3-a456-426614174000',
+    'object-id': '6592008029c8c3e4dc76256c',
+};
+/**
+ * Extract enum values from the propertyNames keyword of an object schema.
+ * JSON Schema's propertyNames constrains which keys are valid in a map/dict.
+ */
+const getPropertyNamesEnumValues = (schema) => {
+    if (!('propertyNames' in schema) || !schema.propertyNames) {
+        return undefined;
+    }
+    const resolved = resolve.schema(schema.propertyNames);
+    if (resolved && 'enum' in resolved && Array.isArray(resolved.enum) && resolved.enum.length > 0) {
+        return resolved.enum;
+    }
+    return undefined;
+};
+/**
+ * Generate example values for string types based on their format.
+ * Special handling for binary format which returns a File object.
+ */
+const guessFromFormat = (schema, makeUpRandomData = false, fallback = '') => {
+    // Handle binary format specially - return a File object
+    if ('type' in schema && schema.type === 'string' && 'format' in schema && schema.format === 'binary') {
+        return '@filename';
+    }
+    // Return format-specific example if we have one and are making up data
+    if (makeUpRandomData && 'format' in schema && schema.format) {
+        return genericExampleValues[schema.format] ?? fallback;
+    }
+    return fallback;
+};
+/**
+ * WeakMap cache for memoizing resolved example results.
+ * Uses the resolved schema object as the key for efficient lookups.
+ */
+const resultCache = new WeakMap();
+/** Cache required property names per parent schema for O(1) membership checks */
+const requiredNamesCache = new WeakMap();
+/** Normalize schema identity for cache and cycle tracking */
+const getSchemaCacheTarget = (schema) => unpackProxyObject(schema, { depth: 1 });
+/**
+ * Retrieves the set of required property names from a schema.
+ * Caches the result in a WeakMap for efficient lookups.
+ */
+const getRequiredNames = (parentSchema) => {
+    if (!parentSchema) {
+        return undefined;
+    }
+    const cached = requiredNamesCache.get(parentSchema);
+    if (cached) {
+        return cached;
+    }
+    if ('required' in parentSchema) {
+        const required = parentSchema.required;
+        if (Array.isArray(required) && required.length > 0) {
+            const set = new Set(required);
+            requiredNamesCache.set(parentSchema, set);
+            return set;
+        }
+    }
+    return undefined;
+};
+/**
+ * Cache the result for a schema if it is an object type.
+ * Primitive values are not cached to avoid unnecessary WeakMap operations.
+ * Stores a map of cacheKey strings which is made up of the options object.
+ */
+const cache = (schema, result, cacheKey) => {
+    if (typeof result !== 'object' || result === null) {
+        return result;
+    }
+    const rawSchema = getSchemaCacheTarget(schema);
+    const cacheMap = resultCache.get(rawSchema) ?? new Map();
+    if (cacheMap) {
+        cacheMap.set(cacheKey, result);
+    }
+    resultCache.set(rawSchema, cacheMap);
+    return result;
+};
+/**
+ * Check if a schema uses composition keywords (allOf, oneOf, anyOf).
+ * These require special handling for merging or selecting schemas.
+ */
+const isComposed = (schema) => !!(schema.allOf || schema.oneOf || schema.anyOf);
+/**
+ * Determine if a property should be omitted based on the options.
+ * Properties are omitted if they are not required and the option is enabled.
+ */
+const shouldOmitProperty = (schema, parentSchema, propertyName, options) => {
+    // Early exits for schemas that should not be included (deprecated, readOnly, writeOnly)
+    if (schema.deprecated ||
+        (options?.mode === 'write' && schema.readOnly) ||
+        (options?.mode === 'read' && schema.writeOnly)) {
+        return true;
+    }
+    if (options?.omitEmptyAndOptionalProperties !== true) {
+        return false;
+    }
+    // Never omit container types (objects/arrays) or composed schemas
+    const isContainer = ('type' in schema && (schema.type === 'object' || schema.type === 'array')) || isComposed(schema);
+    if (isContainer) {
+        return false;
+    }
+    // Do not omit if explicit example-like values are present
+    if (('examples' in schema && Array.isArray(schema.examples) && schema.examples.length > 0) ||
+        ('example' in schema && schema.example !== undefined) ||
+        ('default' in schema && schema.default !== undefined) ||
+        ('const' in schema && schema.const !== undefined) ||
+        ('enum' in schema && Array.isArray(schema.enum) && schema.enum.length > 0)) {
+        return false;
+    }
+    // Check if the property is required
+    const name = propertyName ?? schema.title ?? '';
+    const requiredNames = getRequiredNames(parentSchema);
+    const isRequired = requiredNames ? requiredNames.has(name) : false;
+    return !isRequired;
+};
+/**
+ * Merge two example values with predictable semantics.
+ * Arrays are concatenated, objects are merged, otherwise the new value wins.
+ */
+const mergeExamples = (baseValue, newValue) => {
+    if (Array.isArray(baseValue) && Array.isArray(newValue)) {
+        return [...baseValue, ...newValue];
+    }
+    if (baseValue && typeof baseValue === 'object' && newValue && typeof newValue === 'object') {
+        return { ...baseValue, ...newValue };
+    }
+    return newValue;
+};
+const getCompositionSelectionKey = (schemaPath, composition) => [...schemaPath, composition].join('.');
+const getCompositionSelectionIndex = (schemaPath, composition, options, length) => {
+    const rawIndex = options?.compositionSelection?.[getCompositionSelectionKey(schemaPath, composition)];
+    if (typeof rawIndex !== 'number' || Number.isNaN(rawIndex)) {
+        return undefined;
+    }
+    return Math.max(0, Math.min(rawIndex, length - 1));
+};
+/**
+ * Build an example for an object schema, including properties, patternProperties,
+ * additionalProperties, and composition (allOf/oneOf/anyOf) merging.
+ */
+const handleObjectSchema = (schema, options, level, seen, cacheKey, schemaPath) => {
+    const response = {};
+    if ('properties' in schema && schema.properties) {
+        const propertyNames = Object.keys(schema.properties);
+        const limit = propertyNames.length;
+        for (let i = 0; i < limit; i++) {
+            const propertyName = propertyNames[i];
+            const propertySchema = resolve.schema(schema.properties[propertyName]);
+            if (!propertySchema) {
+                continue;
+            }
+            const propertyXmlName = options?.xml && 'xml' in propertySchema ? propertySchema.xml?.name : undefined;
+            const value = getExampleFromSchema(propertySchema, options, {
+                level: level + 1,
+                parentSchema: schema,
+                name: propertyName,
+                schemaPath: [...schemaPath, propertyName],
+                seen,
+            });
+            if (typeof value !== 'undefined') {
+                response[propertyXmlName ?? propertyName] = value;
+            }
+        }
+    }
+    if ('patternProperties' in schema && schema.patternProperties) {
+        for (const pattern of Object.keys(schema.patternProperties)) {
+            const propertySchema = resolve.schema(schema.patternProperties[pattern]);
+            if (!propertySchema) {
+                continue;
+            }
+            response[pattern] = getExampleFromSchema(propertySchema, options, {
+                level: level + 1,
+                parentSchema: schema,
+                name: pattern,
+                schemaPath: [...schemaPath, pattern],
+                seen,
+            });
+        }
+    }
+    if ('additionalProperties' in schema && schema.additionalProperties) {
+        const additional = typeof schema.additionalProperties === 'boolean'
+            ? schema.additionalProperties
+            : resolve.schema(schema.additionalProperties);
+        const isAnyType = schema.additionalProperties === true ||
+            (typeof schema.additionalProperties === 'object' && Object.keys(schema.additionalProperties).length === 0);
+        // Check for explicit x-additionalPropertiesName first
+        const hasCustomName = typeof additional === 'object' &&
+            'x-additionalPropertiesName' in additional &&
+            typeof additional['x-additionalPropertiesName'] === 'string' &&
+            additional['x-additionalPropertiesName'].trim().length > 0;
+        // Use propertyNames enum values as example keys when no custom name is set
+        const propertyNamesEnum = hasCustomName ? undefined : getPropertyNamesEnumValues(schema);
+        const additionalName = hasCustomName
+            ? additional['x-additionalPropertiesName'].trim()
+            : DEFAULT_ADDITIONAL_PROPERTIES_NAME;
+        const additionalValue = isAnyType
+            ? 'anything'
+            : typeof additional === 'object'
+                ? getExampleFromSchema(additional, options, {
+                    level: level + 1,
+                    schemaPath: [...schemaPath, additionalName],
+                    seen,
+                })
+                : 'anything';
+        if (propertyNamesEnum && propertyNamesEnum.length > 0) {
+            // Use the first enum value as a realistic example key
+            response[String(propertyNamesEnum[0])] = additionalValue;
+        }
+        else {
+            response[additionalName] = additionalValue;
+        }
+    }
+    const compositionKeyword = schema.oneOf ? 'oneOf' : schema.anyOf ? 'anyOf' : undefined;
+    const oneOfAnyOf = compositionKeyword ? schema[compositionKeyword] : undefined;
+    if (compositionKeyword && oneOfAnyOf?.length) {
+        const index = getCompositionSelectionIndex(schemaPath, compositionKeyword, options, oneOfAnyOf.length) ?? 0;
+        const chosen = resolve.schema(oneOfAnyOf[index]);
+        if (chosen) {
+            Object.assign(response, getExampleFromSchema(chosen, options, {
+                level: level + 1,
+                schemaPath,
+                seen,
+            }));
+        }
+    }
+    // allOf
+    else if (Array.isArray(schema.allOf) && schema.allOf.length > 0) {
+        let merged = response;
+        for (const item of schema.allOf) {
+            const ex = getExampleFromSchema(resolve.schema(item), options, {
+                level: level + 1,
+                parentSchema: schema,
+                seen,
+            });
+            merged = mergeExamples(merged, ex);
+        }
+        if (merged && typeof merged === 'object') {
+            Object.assign(response, merged);
+        }
+    }
+    if (options?.xml && 'xml' in schema && schema.xml?.name && level === 0) {
+        const wrapped = {};
+        wrapped[schema.xml.name] = response;
+        return cache(schema, wrapped, cacheKey);
+    }
+    return cache(schema, response, cacheKey);
+};
+/** Build an example for an array schema, including items, allOf, oneOf/anyOf, and XML wrapping */
+const handleArraySchema = (schema, options, level, seen, cacheKey, schemaPath) => {
+    const items = 'items' in schema ? resolve.schema(schema.items) : undefined;
+    const itemsSchemaPath = [...schemaPath, 'items'];
+    const itemsXmlTagName = items && typeof items === 'object' && 'xml' in items ? items.xml?.name : undefined;
+    const wrapItems = !!(options?.xml && 'xml' in schema && schema.xml?.wrapped && itemsXmlTagName);
+    if (schema.example !== undefined) {
+        return cache(schema, wrapItems ? { [itemsXmlTagName]: schema.example } : schema.example, cacheKey);
+    }
+    if (items && typeof items === 'object') {
+        if (Array.isArray(items.allOf) && items.allOf.length > 0) {
+            const allOf = items.allOf.filter(isDefined);
+            const first = resolve.schema(allOf[0]);
+            if (first && typeof first === 'object' && 'type' in first && first.type === 'object') {
+                const combined = { type: 'object', allOf };
+                const merged = getExampleFromSchema(combined, options, {
+                    level: level + 1,
+                    parentSchema: schema,
+                    schemaPath: itemsSchemaPath,
+                    seen,
+                });
+                return cache(schema, wrapItems ? [{ [itemsXmlTagName]: merged }] : [merged], cacheKey);
+            }
+            const examples = allOf
+                .map((s) => getExampleFromSchema(resolve.schema(s), options, {
+                level: level + 1,
+                parentSchema: schema,
+                schemaPath: itemsSchemaPath,
+                seen,
+            }))
+                .filter(isDefined);
+            return cache(schema, wrapItems ? examples.map((e) => ({ [itemsXmlTagName]: e })) : examples, cacheKey);
+        }
+        const compositionKeyword = items.oneOf ? 'oneOf' : items.anyOf ? 'anyOf' : undefined;
+        const union = compositionKeyword ? items[compositionKeyword] : undefined;
+        if (compositionKeyword && union && union.length > 0) {
+            const selectedIndex = getCompositionSelectionIndex(itemsSchemaPath, compositionKeyword, options, union.length) ?? 0;
+            const selected = union[selectedIndex];
+            const ex = getExampleFromSchema(resolve.schema(selected), options, {
+                level: level + 1,
+                parentSchema: schema,
+                schemaPath: itemsSchemaPath,
+                seen,
+            });
+            return cache(schema, wrapItems ? [{ [itemsXmlTagName]: ex }] : [ex], cacheKey);
+        }
+    }
+    const isObject = items && typeof items === 'object' && (('type' in items && items.type === 'object') || 'properties' in items);
+    const isArray = items && typeof items === 'object' && (('type' in items && items.type === 'array') || 'items' in items);
+    if (items && typeof items === 'object' && (('type' in items && items.type) || isObject || isArray)) {
+        const ex = getExampleFromSchema(items, options, {
+            level: level + 1,
+            schemaPath: itemsSchemaPath,
+            seen,
+        });
+        return cache(schema, wrapItems ? [{ [itemsXmlTagName]: ex }] : [ex], cacheKey);
+    }
+    return cache(schema, [], cacheKey);
+};
+/** Return primitive example value for single-type schemas, or undefined if not primitive */
+const getPrimitiveValue = (schema, makeUpRandomData, emptyString) => {
+    if ('type' in schema && schema.type && !Array.isArray(schema.type)) {
+        switch (schema.type) {
+            case 'string':
+                return guessFromFormat(schema, makeUpRandomData, emptyString ?? '');
+            case 'boolean':
+                return true;
+            case 'integer':
+                return 'minimum' in schema && typeof schema.minimum === 'number' ? schema.minimum : 1;
+            case 'number':
+                return 'minimum' in schema && typeof schema.minimum === 'number' ? schema.minimum : 1;
+            case 'array':
+                return [];
+            default:
+                return undefined;
+        }
+    }
+    return undefined;
+};
+/** Return primitive example value for union-type schemas (type: string[]) */
+const getUnionPrimitiveValue = (schema, makeUpRandomData, emptyString) => {
+    if ('type' in schema && Array.isArray(schema.type)) {
+        if (schema.type.includes('null')) {
+            return null;
+        }
+        const first = schema.type[0];
+        if (first) {
+            switch (first) {
+                case 'string':
+                    return guessFromFormat(schema, makeUpRandomData, emptyString ?? '');
+                case 'boolean':
+                    return true;
+                case 'integer':
+                    return 'minimum' in schema && typeof schema.minimum === 'number' ? schema.minimum : 1;
+                case 'number':
+                    return 'minimum' in schema && typeof schema.minimum === 'number' ? schema.minimum : 1;
+                case 'null':
+                    return null;
+                default:
+                    return undefined;
+            }
+        }
+    }
+    return undefined;
+};
+/** Create stable cache key from the options object */
+const createOptionsCacheKey = (options) => JSON.stringify({
+    emptyString: options?.emptyString,
+    xml: options?.xml,
+    mode: options?.mode,
+    variables: options?.variables,
+    omitEmptyAndOptionalProperties: options?.omitEmptyAndOptionalProperties,
+    compositionSelection: options?.compositionSelection
+        ? Object.entries(options.compositionSelection).sort(([a], [b]) => a.localeCompare(b))
+        : undefined,
+});
+/**
+ * Generate an example value from a given OpenAPI SchemaObject.
+ *
+ * This function recursively processes OpenAPI schemas to create realistic example data.
+ * It handles all OpenAPI schema types including primitives, objects, arrays, and
+ * composition schemas (allOf, oneOf, anyOf).
+ * Uses a tonne of caching for maximum performance.
+ *
+ * @param schema - The OpenAPI SchemaObject to generate an example from.
+ * @param options - Options to customize example generation.
+ * @param level - The current recursion depth.
+ * @param parentSchema - The parent schema, if any.
+ * @param name - The name of the property being processed.
+ * @returns An example value for the given schema.
+ */
+export const getExampleFromSchema = (schema, options, { level = 0, parentSchema, name, seen = new WeakSet(), schemaPath = [], } = {}) => {
+    // Resolve any $ref references to get the actual schema
+    const _schema = resolve.schema(schema);
+    if (!isDefined(_schema)) {
+        return undefined;
+    }
+    // Unpack from all proxies to get the raw schema object for cycle detection
+    const targetValue = getSchemaCacheTarget(_schema);
+    if (seen.has(targetValue)) {
+        return undefined;
+    }
+    seen.add(targetValue);
+    /** Make the cache key unique per options and schema path */
+    const cacheKey = createOptionsCacheKey(options) + (schemaPath.length > 0 ? `:path:${schemaPath.join('.')}` : '');
+    // Check cache first for performance - avoid recomputing the same schema
+    const cached = resultCache.get(targetValue)?.get(cacheKey);
+    if (typeof cached !== 'undefined') {
+        seen.delete(targetValue);
+        return cached;
+    }
+    // Prevent infinite recursion in circular references
+    if (level > MAX_LEVELS_DEEP) {
+        seen.delete(targetValue);
+        return '[Max Depth Exceeded]';
+    }
+    // Determine if we should generate realistic example data
+    const makeUpRandomData = !!options?.emptyString;
+    // Early exits for schemas that should not be included (deprecated, readOnly, writeOnly, omitEmptyAndOptionalProperties)
+    if (shouldOmitProperty(_schema, parentSchema, name, options)) {
+        seen.delete(targetValue);
+        return undefined;
+    }
+    // Handle custom variables (x-variable extension)
+    if ('x-variable' in _schema && _schema['x-variable']) {
+        const value = options?.variables?.[_schema['x-variable']];
+        if (value !== undefined) {
+            // Type coercion for numeric types
+            if ('type' in _schema && (_schema.type === 'number' || _schema.type === 'integer')) {
+                seen.delete(targetValue);
+                return cache(_schema, Number(value), cacheKey);
+            }
+            seen.delete(targetValue);
+            return cache(_schema, value, cacheKey);
+        }
+    }
+    // Priority order: examples > example > default > const > enum
+    if (Array.isArray(_schema.examples) && _schema.examples.length > 0) {
+        seen.delete(targetValue);
+        return cache(_schema, _schema.examples[0], cacheKey);
+    }
+    if (_schema.example !== undefined) {
+        seen.delete(targetValue);
+        return cache(_schema, _schema.example, cacheKey);
+    }
+    if (_schema.default !== undefined) {
+        seen.delete(targetValue);
+        return cache(_schema, _schema.default, cacheKey);
+    }
+    if (_schema.const !== undefined) {
+        seen.delete(targetValue);
+        return cache(_schema, _schema.const, cacheKey);
+    }
+    if (Array.isArray(_schema.enum) && _schema.enum.length > 0) {
+        seen.delete(targetValue);
+        return cache(_schema, _schema.enum[0], cacheKey);
+    }
+    // Handle object types - check for properties to identify objects
+    if ('properties' in _schema || ('type' in _schema && _schema.type === 'object')) {
+        const result = handleObjectSchema(_schema, options, level, seen, cacheKey, schemaPath);
+        seen.delete(targetValue);
+        return result;
+    }
+    // Handle array types
+    if (('type' in _schema && _schema.type === 'array') || 'items' in _schema) {
+        const result = handleArraySchema(_schema, options, level, seen, cacheKey, schemaPath);
+        seen.delete(targetValue);
+        return result;
+    }
+    // Handle primitive types without allocating temporary objects
+    const primitive = getPrimitiveValue(_schema, makeUpRandomData, options?.emptyString);
+    if (primitive !== undefined) {
+        seen.delete(targetValue);
+        return cache(_schema, primitive, cacheKey);
+    }
+    // Handle composition schemas (oneOf, anyOf)
+    const compositionKeyword = _schema.oneOf ? 'oneOf' : _schema.anyOf ? 'anyOf' : undefined;
+    const discriminate = compositionKeyword ? _schema[compositionKeyword] : undefined;
+    if (compositionKeyword && Array.isArray(discriminate) && discriminate.length > 0) {
+        const index = getCompositionSelectionIndex(schemaPath, compositionKeyword, options, discriminate.length);
+        const candidate = index !== undefined
+            ? discriminate[index]
+            : discriminate.find((item) => {
+                const resolved = resolve.schema(item);
+                return resolved && (!('type' in resolved) || resolved.type !== 'null');
+            });
+        if (candidate) {
+            const resolved = resolve.schema(candidate);
+            if (resolved) {
+                seen.delete(targetValue);
+                return cache(_schema, getExampleFromSchema(resolved, options, {
+                    level: level + 1,
+                    schemaPath,
+                    seen,
+                }), cacheKey);
+            }
+        }
+        seen.delete(targetValue);
+        return cache(_schema, null, cacheKey);
+    }
+    // Handle allOf at root level (non-object/array schemas)
+    if (Array.isArray(_schema.allOf) && _schema.allOf.length > 0) {
+        let merged = undefined;
+        const items = _schema.allOf;
+        for (const item of items) {
+            const ex = getExampleFromSchema(item, options, {
+                level: level + 1,
+                parentSchema: _schema,
+                schemaPath,
+                seen,
+            });
+            if (merged === undefined) {
+                merged = ex;
+            }
+            else if (merged && typeof merged === 'object' && ex && typeof ex === 'object') {
+                merged = mergeExamples(merged, ex);
+            }
+            else if (ex !== undefined) {
+                // Prefer the latest defined primitive value
+                merged = ex;
+            }
+        }
+        seen.delete(targetValue);
+        return cache(_schema, merged ?? null, cacheKey);
+    }
+    // Handle union types (array of types)
+    const unionPrimitive = getUnionPrimitiveValue(_schema, makeUpRandomData, options?.emptyString);
+    if (unionPrimitive !== undefined) {
+        seen.delete(targetValue);
+        return cache(_schema, unionPrimitive, cacheKey);
+    }
+    // Default fallback
+    seen.delete(targetValue);
+    return cache(_schema, null, cacheKey);
+};

package/dist/request-example/builder/helpers/get-example.d.ts

@@ -0,0 +1,10 @@
+import type { ExampleObject, MediaTypeObject, ParameterObject, RequestBodyObject } from '@scalar/workspace-store/schemas/v3.1/strict/openapi-document';
+/**
+ * Resolve an example value for a parameter or requestBody from either `examples` or `content.*.examples`.
+ * Or the [deprecated] `example` field.
+ * If no exampleKey is provided it will fallback to the first example in the examples object then the [deprecated]
+ * `example` field.
+ * Used both for send-request and generating code snippets.
+ */
+export declare const getExample: (param: ParameterObject | RequestBodyObject | MediaTypeObject, exampleName: string | undefined, contentType: string | undefined) => ExampleObject | undefined;
+//# sourceMappingURL=get-example.d.ts.map

package/dist/request-example/builder/helpers/get-example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-example.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/helpers/get-example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,eAAe,EACf,iBAAiB,EAClB,MAAM,8DAA8D,CAAA;AAgCrE;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GACrB,OAAO,eAAe,GAAG,iBAAiB,GAAG,eAAe,EAC5D,aAAa,MAAM,GAAG,SAAS,EAC/B,aAAa,MAAM,GAAG,SAAS,KAC9B,aAAa,GAAG,SA6ClB,CAAA"}

package/dist/request-example/builder/helpers/get-example.js

@@ -0,0 +1,66 @@
+import { getResolvedRef } from '../../../helpers/get-resolved-ref.js';
+/** Helper to get example from examples object with fallback to example field */
+const getExampleFromExamples = (examples, exampleField, exampleName) => {
+    if (!examples && !exampleField) {
+        return undefined;
+    }
+    const hasExamples = !!examples && Object.keys(examples).length > 0;
+    // Grab the example key
+    const key = exampleName || Object.keys(examples ?? {})[0] || '';
+    const example = getResolvedRef(examples?.[key]);
+    if (example !== undefined) {
+        return example;
+    }
+    // Fallback to example field when no examples map exists,
+    // or when no specific example key was requested.
+    if ((!hasExamples || !exampleName) && exampleField !== undefined) {
+        return { value: getResolvedRef(exampleField) };
+    }
+    return undefined;
+};
+/**
+ * Resolve an example value for a parameter or requestBody from either `examples` or `content.*.examples`.
+ * Or the [deprecated] `example` field.
+ * If no exampleKey is provided it will fallback to the first example in the examples object then the [deprecated]
+ * `example` field.
+ * Used both for send-request and generating code snippets.
+ */
+export const getExample = (param, exampleName, contentType) => {
+    // Content based parameters
+    if ('content' in param) {
+        const content = param.content?.[contentType ?? Object.keys(param.content)[0] ?? ''];
+        const result = getExampleFromExamples(content?.examples, content?.example, exampleName);
+        if (result !== undefined) {
+            return result;
+        }
+    }
+    // Schema based parameters
+    if ('examples' in param || 'example' in param) {
+        const result = getExampleFromExamples(param.examples, param.example, exampleName);
+        if (result !== undefined) {
+            return result;
+        }
+    }
+    // Derive value from the schema
+    const resolvedParam = getResolvedRef(param);
+    if ('schema' in resolvedParam && resolvedParam.schema) {
+        const schema = resolvedParam.schema;
+        // Default value
+        if ('default' in schema && schema.default !== undefined) {
+            return { value: schema.default };
+        }
+        // Enum value
+        if ('enum' in schema && schema.enum?.[0] !== undefined) {
+            return { value: schema.enum[0] };
+        }
+        // Examples value
+        if ('examples' in schema && schema.examples?.[0] !== undefined) {
+            return { value: schema.examples[0] };
+        }
+        // Example value
+        if ('example' in schema && schema.example !== undefined) {
+            return { value: schema.example };
+        }
+    }
+    return undefined;
+};

package/dist/request-example/builder/helpers/get-resolved-url.d.ts

@@ -0,0 +1,20 @@
+import type { ServerObject } from '../../../schemas/v3.1/strict/server.js';
+/**
+ * Resolves the full request URL by:
+ * 1. Applying OpenAPI server variables to the server URL template.
+ * 2. Merging the resolved server URL with the OpenAPI path and optional URL parameters.
+ * 3. Applying "allowReserved" query parameter logic if needed (for RFC3986 reserved chars).
+ *
+ * @param server - The OpenAPI server object or null
+ * @param path - The OpenAPI operation path (may contain {variables})
+ * @param urlParams - Optional URLSearchParams to include as query parameters
+ * @param allowReservedQueryParameters - Optional set of parameter names for which reserved characters should not be percent-encoded
+ * @returns The resolved URL as a string
+ */
+export declare const getResolvedUrl: ({ server, path, urlParams, }: {
+    server: ServerObject | null;
+    path: string;
+    urlParams?: URLSearchParams;
+    allowReservedQueryParameters?: Set<string>;
+}) => string;
+//# sourceMappingURL=get-resolved-url.d.ts.map

package/dist/request-example/builder/helpers/get-resolved-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-resolved-url.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/helpers/get-resolved-url.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAEhE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GAAI,8BAI5B;IACD,MAAM,EAAE,YAAY,GAAG,IAAI,CAAA;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,4BAA4B,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAC3C,WAGA,CAAA"}