@amritk/generate-examples 0.0.0 → 0.1.1

package/dist/generators/build-schema.d.ts

@@ -0,0 +1,32 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Represents a generated TypeScript file with its filename and content.
+ */
+export type GeneratedFile = {
+    filename: string;
+    content: string;
+};
+/**
+ * Builds all TypeScript example files from a JSON Schema by traversing all
+ * $ref references recursively, mirroring the generate-parsers pipeline.
+ *
+ * Each generated file exports:
+ * - A TypeScript type definition
+ * - A `fast-check` arbitrary (`FooArbitrary`) that produces schema-valid values
+ * - A concrete example value (`fooExample`)
+ *
+ * An `index.ts` re-exports everything. The generated output imports `fast-check`,
+ * which consumers must install as a (dev) dependency.
+ *
+ * @param rootSchema - The root JSON Schema to build from
+ * @param rootTypeName - The name for the root type (e.g. "Document")
+ * @param typeSuffix - Suffix appended to every `$ref`-derived name (default `''`)
+ * @returns An array of generated TypeScript files
+ *
+ * @example
+ * ```typescript
+ * const files = await buildExampleSchema(schema, 'Document')
+ * // files → [{ filename: 'document.ts', content: '...' }, { filename: 'index.ts', ... }]
+ * ```
+ */
+export declare const buildExampleSchema: (rootSchema: JSONSchema, rootTypeName: string, typeSuffix?: string) => Promise<GeneratedFile[]>;

package/dist/generators/collect-example-imports.d.ts

@@ -0,0 +1,34 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Options for controlling how example imports are collected.
+ */
+type CollectExampleImportsOptions = {
+    /**
+     * The $ref path of the schema being generated (e.g. `#/$defs/address`).
+     * Prevents a file from importing itself.
+     */
+    readonly selfRef?: string | undefined;
+    /**
+     * The root schema document. URI refs that cannot be resolved within it
+     * are excluded from the import list (they were never generated as files).
+     */
+    readonly rootSchema?: Record<string, unknown> | undefined;
+    /**
+     * Suffix appended to every type/arbitrary name derived from a `$ref`. Must
+     * match the suffix used when generating the referenced files. Defaults to `''`.
+     */
+    readonly typeSuffix?: string;
+};
+/**
+ * Collects import statements for all $ref dependencies of a schema. Each import
+ * brings in both the generated TypeScript type and the arbitrary for that ref.
+ *
+ * @example
+ * ```typescript
+ * const schema = { properties: { address: { $ref: '#/$defs/address' } } }
+ * collectExampleImports(schema)
+ * // ["import { type Address, AddressArbitrary } from './address'"]
+ * ```
+ */
+export declare const collectExampleImports: (schema: JSONSchema, options?: CollectExampleImportsOptions) => string[];
+export {};

package/dist/generators/derive-example.d.ts

@@ -0,0 +1,29 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Derives a single concrete, schema-valid value from a JSON Schema.
+ *
+ * Prefers explicit hints in this order: `const`, `examples[0]`, `default`,
+ * `enum[0]`; otherwise produces a canonical value for the declared type.
+ * `$ref`s are resolved and inlined by value; recursive refs short-circuit to
+ * `null` (tracked via `seen`).
+ *
+ * Note: values constrained only by `pattern` are not guaranteed to match the
+ * pattern — use the generated arbitrary when pattern fidelity matters.
+ */
+export declare const deriveExample: (schema: JSONSchema, rootSchema?: Record<string, unknown>, seen?: ReadonlySet<string>) => unknown;
+/**
+ * Serializes a derived value into a TypeScript source expression. Handles the
+ * non-JSON values `deriveExample` can produce (`Date`, `bigint`) in addition to
+ * plain JSON.
+ */
+export declare const serializeValue: (value: unknown) => string;
+/**
+ * Generates an exported const holding a concrete, schema-valid example value.
+ *
+ * @example
+ * ```typescript
+ * generateExampleConst({ type: 'object', properties: { name: { type: 'string' } } }, 'Info')
+ * // export const infoExample: Info = { "name": "string" }
+ * ```
+ */
+export declare const generateExampleConst: (schema: JSONSchema, typeName: string, rootSchema?: Record<string, unknown>) => string;

package/dist/generators/generate-arbitrary.d.ts

@@ -0,0 +1,11 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Generates a `fast-check` arbitrary that produces schema-valid values.
+ *
+ * @example
+ * ```typescript
+ * generateArbitrary({ type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, 'Info')
+ * // export const InfoArbitrary: fc.Arbitrary<Info> = fc.record({ "name": fc.string() })
+ * ```
+ */
+export declare const generateArbitrary: (schema: JSONSchema, typeName: string, suffix?: string) => string;

package/dist/generators/generate-files.d.ts

@@ -0,0 +1,42 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Options for controlling what gets generated in an example file.
+ */
+type GenerateExampleFileOptions = {
+    /**
+     * The $ref path of the schema being generated (e.g. `#/$defs/address`).
+     * Prevents the file from importing itself.
+     */
+    readonly selfRef?: string;
+    /**
+     * The root schema document. Used to resolve `$ref`s when deriving a concrete
+     * example value, and to filter out unresolvable refs from the import list.
+     */
+    readonly rootSchema?: Record<string, unknown>;
+    /**
+     * Suffix appended to every type/arbitrary name derived from a `$ref`.
+     * Defaults to `''` (no suffix).
+     */
+    readonly typeSuffix?: string;
+};
+/**
+ * Generates a complete TypeScript example file from a JSON Schema.
+ *
+ * The file contains:
+ * - An import of `fast-check` and imports for any `$ref` types and arbitraries
+ * - The exported TypeScript type definition
+ * - An exported `fast-check` arbitrary (`FooArbitrary`)
+ * - An exported concrete example value (`fooExample`)
+ *
+ * @example
+ * ```typescript
+ * const schema = { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] }
+ * generateExampleFile(schema, 'Info')
+ * // import * as fc from 'fast-check'
+ * // export type Info = { title: string }
+ * // export const InfoArbitrary: fc.Arbitrary<Info> = fc.record({ "title": fc.string() })
+ * // export const infoExample: Info = { "title": "string" }
+ * ```
+ */
+export declare const generateExampleFile: (schema: JSONSchema, typeName: string, options?: GenerateExampleFileOptions) => string;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { GeneratedFile } from './generators/build-schema';
+export { buildExampleSchema } from './generators/build-schema';
+export { deriveExample, generateExampleConst, serializeValue } from './generators/derive-example';
+export { generateArbitrary } from './generators/generate-arbitrary';