@amritk/generate-examples 0.5.1 → 0.5.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 amritk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/generators/build-schema.js

@@ -1,52 +1,25 @@
-import { generateIndexBarrel } from '@amritk/helpers/generate-index-barrel';
-import { walkRefGraph } from '@amritk/helpers/walk-ref-graph';
-import { findSchemaCycles } from './find-schema-cycles.js';
-import { generateExampleFile } from './generate-files.js';
-/**
- * Builds all TypeScript example files from a JSON Schema by traversing all
- * `$ref` / `$dynamicRef` references recursively (via the shared
- * `@amritk/helpers/walk-ref-graph` walker).
- *
- * 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 const buildExampleSchema = async (rootSchema, rootTypeName, typeSuffix = '') => {
-    const files = [];
-    // Cross-file `$ref` cycles (A→B→A across modules) must emit lazy references
-    // for their cycle edges; eager top-level references would crash with a
-    // circular-ESM TDZ error at import. Detect the cycles up front so each file
-    // knows which siblings to defer.
-    const cycles = findSchemaCycles(rootSchema, rootTypeName, typeSuffix);
-    walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
-        // `index` is reserved for the barrel below, so never let a definition of
-        // that name overwrite it.
-        if (node.filename === 'index')
-            return;
-        const lazyRefFilenames = cycles.get(node.filename);
-        const content = generateExampleFile(node.schema, node.typeName, {
-            rootSchema: node.rootSchema,
-            typeSuffix,
-            ...(node.ref !== undefined ? { selfRef: node.ref } : {}),
-            ...(lazyRefFilenames !== undefined ? { lazyRefFilenames } : {}),
-        });
-        files.push({ filename: `${node.filename}.ts`, content });
+import { generateIndexBarrel } from "@amritk/helpers/generate-index-barrel";
+import { walkRefGraph } from "@amritk/helpers/walk-ref-graph";
+import { findSchemaCycles } from "./find-schema-cycles.js";
+import { generateExampleFile } from "./generate-files.js";
+const buildExampleSchema = async (rootSchema, rootTypeName, typeSuffix = "") => {
+  const files = [];
+  const cycles = findSchemaCycles(rootSchema, rootTypeName, typeSuffix);
+  walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
+    if (node.filename === "index")
+      return;
+    const lazyRefFilenames = cycles.get(node.filename);
+    const content = generateExampleFile(node.schema, node.typeName, {
+      rootSchema: node.rootSchema,
+      typeSuffix,
+      ...node.ref !== void 0 ? { selfRef: node.ref } : {},
+      ...lazyRefFilenames !== void 0 ? { lazyRefFilenames } : {}
     });
-    files.push({ filename: 'index.ts', content: generateIndexBarrel(files) });
-    return files;
+    files.push({ filename: `${node.filename}.ts`, content });
+  });
+  files.push({ filename: "index.ts", content: generateIndexBarrel(files) });
+  return files;
+};
+export {
+  buildExampleSchema
 };

package/dist/generators/collect-example-imports.js

@@ -1,100 +1,70 @@
-import { refToFilename } from '@amritk/helpers/ref-to-filename';
-import { refToName } from '@amritk/helpers/ref-to-name';
-import { resolveRef } from '@amritk/helpers/resolve-ref';
-import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasOneOf, hasProperties, hasRef, isSchemaObject, } from '@amritk/helpers/schema-guards';
-/**
- * Generates an import statement for a single $ref, importing both the generated
- * type and its arbitrary from the ref's generated file.
- */
+import { refToFilename } from "@amritk/helpers/ref-to-filename";
+import { refToName } from "@amritk/helpers/ref-to-name";
+import { resolveRef } from "@amritk/helpers/resolve-ref";
+import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasOneOf, hasProperties, hasRef, isSchemaObject } from "@amritk/helpers/schema-guards";
 const buildImport = (ref, suffix) => {
-    const filename = refToFilename(ref);
-    const typeName = refToName(ref, suffix);
-    // `.js` extension so the emitted import resolves under Node ESM, not only Bun.
-    return `import { type ${typeName}, ${typeName}Arbitrary } from './${filename}.js'`;
+  const filename = refToFilename(ref);
+  const typeName = refToName(ref, suffix);
+  return `import { type ${typeName}, ${typeName}Arbitrary } from './${filename}.js'`;
 };
-/**
- * Recursively collects every `$ref` string reachable through the schema surface
- * that the type and arbitrary generators traverse. A generated file's single
- * import block must cover every ref those generators emit, so this walks the
- * *same* nested surface `arbitraryExpr` (generate-arbitrary.ts) descends into —
- * combinator branches, object `properties`/`patternProperties`/
- * `additionalProperties`, and array `items`/`prefixItems` (both the single-schema
- * and tuple array forms) — not just the top level. Missing any of these emits a
- * bare `XxxArbitrary` identifier (or a bare `Xxx` type) with no matching import,
- * producing TypeScript that fails to compile.
- *
- * `$ref` nodes short-circuit (matching `arbitraryExpr`, which resolves a `$ref`
- * and ignores sibling keywords), so recursion is bounded by the schema's own
- * structural nesting and cannot loop on a self-referential ref.
- */
 const collectRefs = (schema) => {
-    if (!isSchemaObject(schema))
-        return [];
-    if (hasRef(schema))
-        return [schema.$ref];
-    const refs = [];
-    const visit = (sub) => {
-        refs.push(...collectRefs(sub));
-    };
-    if (hasOneOf(schema))
-        schema.oneOf.forEach(visit);
-    if (hasAnyOf(schema))
-        schema.anyOf.forEach(visit);
-    if (hasAllOf(schema))
-        schema.allOf.forEach(visit);
-    if (hasProperties(schema))
-        Object.values(schema.properties).forEach(visit);
-    const raw = schema;
-    const patternProperties = raw['patternProperties'];
-    if (typeof patternProperties === 'object' && patternProperties !== null) {
-        Object.values(patternProperties).forEach(visit);
-    }
-    if (hasAdditionalProperties(schema) && isSchemaObject(schema.additionalProperties)) {
-        visit(schema.additionalProperties);
-    }
-    const prefixItems = raw['prefixItems'];
-    if (Array.isArray(prefixItems))
-        prefixItems.forEach(visit);
-    const items = raw['items'];
-    // `items` is either a tuple (draft-07 array form) or a single item schema.
-    if (Array.isArray(items))
-        items.forEach(visit);
-    else if (isSchemaObject(items))
-        visit(items);
-    return refs;
+  if (!isSchemaObject(schema))
+    return [];
+  if (hasRef(schema))
+    return [schema.$ref];
+  const refs = [];
+  const visit = (sub) => {
+    refs.push(...collectRefs(sub));
+  };
+  if (hasOneOf(schema))
+    schema.oneOf.forEach(visit);
+  if (hasAnyOf(schema))
+    schema.anyOf.forEach(visit);
+  if (hasAllOf(schema))
+    schema.allOf.forEach(visit);
+  if (hasProperties(schema))
+    Object.values(schema.properties).forEach(visit);
+  const raw = schema;
+  const patternProperties = raw["patternProperties"];
+  if (typeof patternProperties === "object" && patternProperties !== null) {
+    Object.values(patternProperties).forEach(visit);
+  }
+  if (hasAdditionalProperties(schema) && isSchemaObject(schema.additionalProperties)) {
+    visit(schema.additionalProperties);
+  }
+  const prefixItems = raw["prefixItems"];
+  if (Array.isArray(prefixItems))
+    prefixItems.forEach(visit);
+  const items = raw["items"];
+  if (Array.isArray(items))
+    items.forEach(visit);
+  else if (isSchemaObject(items))
+    visit(items);
+  return refs;
 };
-/**
- * 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 const collectExampleImports = (schema, options) => {
-    const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : null;
-    const rootSchema = options?.rootSchema;
-    const typeSuffix = options?.typeSuffix ?? '';
-    const refs = collectRefs(schema);
-    const seen = new Set();
-    const imports = [];
-    for (const ref of refs) {
-        const filename = refToFilename(ref);
-        if (seen.has(filename))
-            continue;
-        if (selfFilename && filename === selfFilename)
-            continue;
-        // Skip refs that don't resolve in this schema (external / never generated)
-        if (rootSchema) {
-            const resolved = resolveRef(ref, rootSchema);
-            if (!resolved)
-                continue;
-        }
-        seen.add(filename);
-        imports.push(buildImport(ref, typeSuffix));
+const collectExampleImports = (schema, options) => {
+  const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : null;
+  const rootSchema = options?.rootSchema;
+  const typeSuffix = options?.typeSuffix ?? "";
+  const refs = collectRefs(schema);
+  const seen = /* @__PURE__ */ new Set();
+  const imports = [];
+  for (const ref of refs) {
+    const filename = refToFilename(ref);
+    if (seen.has(filename))
+      continue;
+    if (selfFilename && filename === selfFilename)
+      continue;
+    if (rootSchema) {
+      const resolved = resolveRef(ref, rootSchema);
+      if (!resolved)
+        continue;
     }
-    return imports;
+    seen.add(filename);
+    imports.push(buildImport(ref, typeSuffix));
+  }
+  return imports;
+};
+export {
+  collectExampleImports
 };