OpenAPI Sampler

import { sample, inferType, _registerSampler } from "openapi-sampler";

const { sample, inferType, _registerSampler } = require("openapi-sampler");

import { sample } from "openapi-sampler";

// Simple schema sampling
const schema = {
  type: "object",
  properties: {
    name: { type: "string", minLength: 5 },
    age: { type: "integer", minimum: 18 },
    email: { type: "string", format: "email" }
  },
  required: ["name", "age"]
};

const sampleData = sample(schema);
// Result: { name: "string", age: 18, email: "user@example.com" }

// With options
const options = {
  skipNonRequired: true,
  format: "json"
};

const sampleDataMinimal = sample(schema, options);
// Result: { name: "string", age: 18 }

// With $ref resolution
const spec = {
  components: {
    schemas: {
      User: {
        type: "object",
        properties: {
          id: { type: "string", format: "uuid" },
          profile: { $ref: "#/components/schemas/Profile" }
        }
      },
      Profile: {
        type: "object",
        properties: {
          name: { type: "string" },
          bio: { type: "string", maxLength: 100 }
        }
      }
    }
  }
};

const userSchema = { $ref: "#/components/schemas/User" };
const userData = sample(userSchema, {}, spec);

/**
 * Generate sample data from a JSON Schema
 * @param schema - JSON Schema object to generate sample from
 * @param options - Optional configuration options
 * @param document - Optional full OpenAPI specification for $ref resolution
 * @returns Generated sample data (object, array, or primitive)
 */
function sample(schema: JSONSchema7, options?: Options, document?: object): unknown;

/**
 * Register a custom sampler for a specific type
 * @param type - The JSON Schema type to register a sampler for
 * @param sampler - The sampler function to use for this type
 */
function _registerSampler(type: string, sampler: Function): void;

interface Options {
  readonly skipNonRequired?: boolean; // Don't include non-required object properties not specified in required array
  readonly skipReadOnly?: boolean;    // Don't include readOnly object properties
  readonly skipWriteOnly?: boolean;   // Don't include writeOnly object properties
  readonly quiet?: boolean;           // Don't log console warning messages
  readonly enablePatterns?: boolean;  // Enable regex pattern sampling for strings
  readonly format?: 'json' | 'xml';   // Output format (defaults to 'json')
}

type JSONSchema7 = import('@types/json-schema').JSONSchema7;

// Array schema
const arraySchema = {
  type: "array",
  items: { type: "string", format: "email" },
  minItems: 2,
  maxItems: 3
};
const emails = sample(arraySchema);
// Result: ["user@example.com", "user@example.com"]

// AllOf composition
const compositeSchema = {
  allOf: [
    { type: "object", properties: { name: { type: "string" } } },
    { type: "object", properties: { age: { type: "integer" } } }
  ]
};
const person = sample(compositeSchema);
// Result: { name: "string", age: 0 }

// XML format
const xmlSchema = {
  type: "object",
  properties: {
    name: { type: "string" },
    items: {
      type: "array",
      items: { type: "string" },
      xml: { wrapped: true }
    }
  },
  xml: { name: "root" }
};
const xmlData = sample(xmlSchema, { format: "xml" });
// Result: XML string with proper element structure

/**
 * Infer the type of a schema based on its properties and keywords
 * @param schema - JSON Schema object to analyze
 * @returns Inferred type (object, array, string, number, integer, boolean) or null
 */
function inferType(schema: object): string | null;

import { inferType } from "openapi-sampler";

// Explicit type
inferType({ type: "string" }); // "string"

// Inferred from keywords
inferType({ properties: {} }); // "object"
inferType({ items: {} }); // "array"
inferType({ minLength: 5 }); // "string"
inferType({ minimum: 0 }); // "number"

// Array type (takes first)
inferType({ type: ["string", "null"] }); // "string"

// No inference possible
inferType({ description: "Some value" }); // null

/**
 * Register a custom sampler for a specific type
 * @param type - The JSON Schema type to register a sampler for ('string', 'number', 'object', etc.)
 * @param sampler - The sampler function that generates values for this type
 */
function _registerSampler(type: string, sampler: Function): void;

import { _registerSampler } from "openapi-sampler";

// Register a custom string sampler
_registerSampler('string', (schema, options, spec, context) => {
  if (schema.format === 'custom-id') {
    return 'CUSTOM_' + Math.random().toString(36).substr(2, 9);
  }
  // Fallback to default behavior
  return 'string';
});

// Now schemas with format: 'custom-id' will use the custom sampler
const result = sample({
  type: 'string',
  format: 'custom-id'
});
// Result: "CUSTOM_abc123def"

try {
  // This will throw an error because $ref is used without spec
  const result = sample({ $ref: "#/components/schemas/User" });
} catch (error) {
  console.error(error.message); 
  // "Your schema contains $ref. You must provide full specification in the third parameter."
}

// Circular reference handling
const circularSchema = {
  type: 'object',
  properties: {
    self: { $ref: '#' }  // Self-reference
  }
};

const spec = { ...circularSchema };
const result = sample(circularSchema, {}, spec);
// Result: { self: {} } - circular reference resolved to empty object