@amritk/generate-parsers 0.6.3 → 0.7.1

package/dist/helpers/collect-helpers.js

@@ -0,0 +1,48 @@
+const PACKAGE_IMPORTS = {
+    'is-object': "import { isObject } from '@amritk/helpers/is-object';",
+    'validate-array': "import { validateArray } from '@amritk/helpers/validate-array';",
+    'validate-record': "import { validateRecord } from '@amritk/helpers/validate-record';",
+    // hasRef has historically lived in the schema-guards subpath; preserve that for package mode.
+    'has-ref': "import { hasRef } from '@amritk/helpers/schema-guards';",
+};
+const EMBEDDED_NAMED_EXPORTS = {
+    'is-object': 'isObject',
+    'validate-array': 'validateArray',
+    'validate-record': 'validateRecord',
+    'has-ref': 'hasRef',
+};
+const embeddedImport = (helper, prefix) => `import { ${EMBEDDED_NAMED_EXPORTS[helper]} } from '${prefix}_helpers/${helper}';`;
+/**
+ * Detects which runtime helpers a generated parser body references.
+ *
+ * @param helpersImportPrefix - Relative path prefix to the shared `_helpers/`
+ *   directory in embedded mode. Defaults to `'./'`. The recursive multi-schema
+ *   build passes `'../'`, `'../../'`, etc. so nested parsers can reach a single
+ *   `_helpers/` directory at the output root.
+ */
+export const collectHelpers = (parserFunction, mode, helpersImportPrefix = './') => {
+    const imports = [];
+    const used = new Set();
+    const importFor = (helper) => mode === 'embedded' ? embeddedImport(helper, helpersImportPrefix) : PACKAGE_IMPORTS[helper];
+    if (parserFunction.includes('validateArray')) {
+        imports.push(importFor('validate-array'));
+        used.add('validate-array');
+    }
+    if (parserFunction.includes('validateRecord')) {
+        imports.push(importFor('validate-record'));
+        used.add('validate-record');
+        // The embedded validate-record.ts imports is-object, so it must be shipped too —
+        // but only the `validate-record` line is needed in the parser file unless the
+        // parser body itself references `isObject` (handled below).
+        used.add('is-object');
+    }
+    if (parserFunction.includes('isObject')) {
+        imports.push(importFor('is-object'));
+        used.add('is-object');
+    }
+    if (parserFunction.includes('hasRef(')) {
+        imports.push(importFor('has-ref'));
+        used.add('has-ref');
+    }
+    return { imports, used };
+};

package/dist/helpers/collect-imports.d.ts

@@ -68,3 +68,4 @@ type CollectImportsOptions = {
  */
 export declare const collectImports: (schema: JSONSchema, options?: CollectImportsOptions) => string[];
 export {};
+//# sourceMappingURL=collect-imports.d.ts.map

package/dist/helpers/collect-imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-imports.d.ts","sourceRoot":"","sources":["../../src/helpers/collect-imports.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAIjE;;GAEG;AACH,KAAK,qBAAqB,GAAG;IAC3B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACzD;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,cAAc,WAAY,UAAU,YAAY,qBAAqB,KAAG,MAAM,EAsM1F,CAAA"}

package/dist/helpers/collect-imports.js

@@ -0,0 +1,216 @@
+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, hasItems, hasOneOf, hasRef } from '@amritk/helpers/schema-guards';
+const getImportPathForFilename = (filename) => `./${filename}`;
+/**
+ * Collects all import statements needed for a schema by finding $ref references
+ * that are directly used in the type definition (from properties, items, etc.).
+ * Does not include refs from nested schema definitions.
+ *
+ * Generates both type imports and parser function imports for each $ref.
+ * The parser imports allow validators to delegate validation to the referenced
+ * schema's parser instead of inlining the validation logic.
+ *
+ * Also detects when helper functions (isObject) and validators (validateRecord,
+ * validateArray) are needed based on the schema structure.
+ *
+ * @param schema - The JSON Schema to collect imports from
+ * @param options - Optional settings to control import generation
+ * @returns An array of import statements
+ *
+ * @example
+ * ```ts
+ * const schema = {
+ *   type: 'object',
+ *   properties: {
+ *     contact: { $ref: '#/$defs/contact' },
+ *     server: { $ref: '#/$defs/server' }
+ *   }
+ * }
+ * const imports = collectImports(schema)
+ * // imports = [
+ * //   "import { type Contact, parseContact } from './contact';",
+ * //   "import { type Server, parseServer } from './server';"
+ * // ]
+ *
+ * // With typesOnly, only type imports are generated:
+ * const typeImports = collectImports(schema, { typesOnly: true })
+ * // typeImports = [
+ * //   "import type { Contact } from './contact';",
+ * //   "import type { Server } from './server';"
+ * // ]
+ * ```
+ */
+export const collectImports = (schema, options) => {
+    const typesOnly = options?.typesOnly === true;
+    const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : undefined;
+    const rootSchema = options?.rootSchema;
+    const typeSuffix = options?.typeSuffix;
+    const refs = new Set();
+    const collectRefsFromValue = (value) => {
+        if (typeof value !== 'object' || value === null) {
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                collectRefsFromValue(item);
+            }
+            return;
+        }
+        const record = value;
+        // If this is a $ref, add it — but skip:
+        // - Relative path refs (e.g. /components/messages/foo) which point into example data
+        // - URI refs with fragments pointing into `properties` (not standalone definitions)
+        if (hasRef(record)) {
+            const ref = record.$ref;
+            const isInternal = ref.startsWith('#');
+            const isUri = ref.startsWith('http://') || ref.startsWith('https://');
+            const isPropertyFragment = isUri && ref.includes('#/properties/');
+            if (isInternal || (isUri && !isPropertyFragment)) {
+                refs.add(ref);
+            }
+            return; // Don't traverse further into a $ref
+        }
+        // Check if this is an object type with additionalProperties that has a $ref
+        // This pattern requires validateRecord
+        if (hasAdditionalProperties(record) && hasRef(record.additionalProperties)) {
+            collectRefsFromValue(record.additionalProperties);
+            return;
+        }
+        // Check if this is an array type with items that has a $ref
+        // This pattern requires validateArray
+        if (record.type === 'array' && hasItems(record) && hasRef(record.items)) {
+            collectRefsFromValue(record.items);
+            return;
+        }
+        // Traverse nested properties regardless of whether `type` is explicitly set.
+        if ('properties' in record && typeof record.properties === 'object' && record.properties !== null) {
+            const props = record.properties;
+            for (const key in props) {
+                collectRefsFromValue(props[key]);
+            }
+        }
+        // Traverse into type composition keywords
+        if (hasOneOf(record)) {
+            for (const item of record.oneOf) {
+                collectRefsFromValue(item);
+            }
+        }
+        if (hasAnyOf(record)) {
+            for (const item of record.anyOf) {
+                collectRefsFromValue(item);
+            }
+        }
+        if (hasAllOf(record)) {
+            for (const item of record.allOf) {
+                collectRefsFromValue(item);
+            }
+        }
+        // Traverse into array items
+        if (hasItems(record)) {
+            collectRefsFromValue(record.items);
+        }
+        // Traverse into additionalProperties
+        if (hasAdditionalProperties(record)) {
+            collectRefsFromValue(record.additionalProperties);
+        }
+        // Traverse all patternProperties
+        if ('patternProperties' in record &&
+            typeof record.patternProperties === 'object' &&
+            record.patternProperties !== null) {
+            const patternProps = record.patternProperties;
+            for (const key in patternProps) {
+                collectRefsFromValue(patternProps[key]);
+            }
+        }
+        // Traverse into if/then/else branches
+        if ('then' in record) {
+            collectRefsFromValue(record.then);
+        }
+        if ('else' in record) {
+            collectRefsFromValue(record.else);
+        }
+    };
+    // Collect refs from root-level $ref
+    if (typeof schema === 'object' && schema !== null && hasRef(schema)) {
+        const ref = schema.$ref;
+        const isInternal = ref.startsWith('#');
+        const isUri = ref.startsWith('http://') || ref.startsWith('https://');
+        const isPropertyFragment = isUri && ref.includes('#/properties/');
+        if (isInternal || (isUri && !isPropertyFragment)) {
+            refs.add(ref);
+        }
+    }
+    // Collect refs from properties
+    if (typeof schema === 'object' && schema !== null && 'properties' in schema) {
+        const properties = schema.properties;
+        for (const key in properties) {
+            collectRefsFromValue(properties[key]);
+        }
+    }
+    // Collect refs from root-level additionalProperties
+    if (typeof schema === 'object' && schema !== null && 'additionalProperties' in schema) {
+        collectRefsFromValue(schema.additionalProperties);
+    }
+    // Collect refs from root-level patternProperties
+    if (typeof schema === 'object' && schema !== null && 'patternProperties' in schema) {
+        const patternProps = schema.patternProperties;
+        for (const key in patternProps) {
+            collectRefsFromValue(patternProps[key]);
+        }
+    }
+    // Collect refs from root-level items (when the schema itself is an array type)
+    if (typeof schema === 'object' && schema !== null && hasItems(schema)) {
+        collectRefsFromValue(schema.items);
+    }
+    // Collect refs from root-level composition keywords.
+    if (typeof schema === 'object' && schema !== null && hasOneOf(schema)) {
+        for (const item of schema.oneOf) {
+            collectRefsFromValue(item);
+        }
+    }
+    if (typeof schema === 'object' && schema !== null && hasAnyOf(schema)) {
+        for (const item of schema.anyOf) {
+            collectRefsFromValue(item);
+        }
+    }
+    if (typeof schema === 'object' && schema !== null && hasAllOf(schema)) {
+        for (const item of schema.allOf) {
+            collectRefsFromValue(item);
+        }
+    }
+    // Collect refs from root-level conditional branches.
+    if (typeof schema === 'object' && schema !== null && 'if' in schema) {
+        collectRefsFromValue(schema.if);
+    }
+    if (typeof schema === 'object' && schema !== null && 'then' in schema) {
+        collectRefsFromValue(schema.then);
+    }
+    if (typeof schema === 'object' && schema !== null && 'else' in schema) {
+        collectRefsFromValue(schema.else);
+    }
+    // Convert refs to combined import statements, deduplicating by filename
+    const importMap = new Map();
+    for (const ref of refs) {
+        // For URI refs, skip if the base URI is not resolvable in the root schema.
+        // This prevents generating imports for external schemas that were never generated as files.
+        if (rootSchema !== undefined && (ref.startsWith('http://') || ref.startsWith('https://'))) {
+            if (!resolveRef(ref, rootSchema))
+                continue;
+        }
+        const typeName = refToName(ref, typeSuffix);
+        const filename = refToFilename(ref);
+        // Skip self-referential imports — a file must not import from itself
+        if (selfFilename !== undefined && filename === selfFilename) {
+            continue;
+        }
+        const importPath = getImportPathForFilename(filename);
+        // In types-only mode, omit the parser function import since there is no parser to call
+        const importStatement = typesOnly
+            ? `import type { ${typeName} } from '${importPath}';`
+            : `import { type ${typeName}, parse${typeName}, validate${typeName}Shape } from '${importPath}';`;
+        importMap.set(filename, importStatement);
+    }
+    return Array.from(importMap.values()).sort();
+};

package/dist/helpers/find-discriminator.d.ts

@@ -4,3 +4,4 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  * Returns the property name if a suitable discriminator is found, otherwise null.
  */
 export declare const findDiscriminator: (schemas: readonly JSONSchema[]) => string | null;
+//# sourceMappingURL=find-discriminator.d.ts.map

package/dist/helpers/find-discriminator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-discriminator.d.ts","sourceRoot":"","sources":["../../src/helpers/find-discriminator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAEjE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,YAAa,SAAS,UAAU,EAAE,KAAG,MAAM,GAAG,IA+B3E,CAAA"}

package/dist/helpers/find-discriminator.js

@@ -0,0 +1,33 @@
+import { hasConst, hasEnum, hasProperties, isObjectSchema, isSchemaObject } from '@amritk/helpers/schema-guards';
+/**
+ * Attempts to find a discriminator property that can be used to distinguish between union types.
+ * Returns the property name if a suitable discriminator is found, otherwise null.
+ */
+export const findDiscriminator = (schemas) => {
+    // Look for a property that has different constant/enum values in each schema
+    const propertyValues = new Map();
+    for (const schema of schemas) {
+        if (isObjectSchema(schema) && hasProperties(schema)) {
+            for (const [key, propSchema] of Object.entries(schema.properties)) {
+                if (!propertyValues.has(key)) {
+                    propertyValues.set(key, new Set());
+                }
+                // Check if property has a const value
+                if (isSchemaObject(propSchema) && hasConst(propSchema)) {
+                    propertyValues.get(key)?.add(propSchema.const);
+                }
+                // Check if property has a single enum value
+                else if (isSchemaObject(propSchema) && hasEnum(propSchema) && propSchema.enum.length === 1) {
+                    propertyValues.get(key)?.add(propSchema.enum[0]);
+                }
+            }
+        }
+    }
+    // Find a property where each schema has a unique value
+    for (const [key, values] of propertyValues.entries()) {
+        if (values.size === schemas.length) {
+            return key;
+        }
+    }
+    return null;
+};

package/dist/helpers/get-default-value.d.ts

@@ -5,3 +5,4 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  * These defaults ensure that parsing never fails, even with missing data.
  */
 export declare const getDefaultValue: (schema: JSONSchema) => string;
+//# sourceMappingURL=get-default-value.d.ts.map

package/dist/helpers/get-default-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-default-value.d.ts","sourceRoot":"","sources":["../../src/helpers/get-default-value.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAGjE;;;;GAIG;AACH,eAAO,MAAM,eAAe,WAAY,UAAU,KAAG,MA0EpD,CAAA"}

package/dist/helpers/get-default-value.js

@@ -0,0 +1,74 @@
+import { getMjstPrimitive } from '@amritk/helpers/mjst-extension';
+import { hasAllOf, hasAnyOf, hasDefault, hasEnum, hasExamples, hasOneOf, hasPattern, hasType, isSchemaObject, } from '@amritk/helpers/schema-guards';
+import { generateDefaultFromPattern } from '../generators/generate-default-from-pattern.js';
+/**
+ * Returns the default value for a JSON Schema property.
+ * Priority order: explicit default > first enum value > first example > union first schema > pattern-based > type-based.
+ * These defaults ensure that parsing never fails, even with missing data.
+ */
+export const getDefaultValue = (schema) => {
+    if (!isSchemaObject(schema)) {
+        return 'undefined';
+    }
+    // Explicit default takes highest priority
+    if (hasDefault(schema)) {
+        return JSON.stringify(schema.default);
+    }
+    // Use first enum value if available
+    if (hasEnum(schema) && schema.enum.length > 0) {
+        return JSON.stringify(schema.enum[0]);
+    }
+    // Use first example if available
+    if (hasExamples(schema) && schema.examples.length > 0) {
+        return JSON.stringify(schema.examples[0]);
+    }
+    // Handle union types - use first schema's default
+    if (hasOneOf(schema) && schema.oneOf.length > 0) {
+        const firstSchema = schema.oneOf[0];
+        if (firstSchema !== undefined) {
+            return getDefaultValue(firstSchema);
+        }
+    }
+    if (hasAnyOf(schema) && schema.anyOf.length > 0) {
+        const firstSchema = schema.anyOf[0];
+        if (firstSchema !== undefined) {
+            return getDefaultValue(firstSchema);
+        }
+    }
+    // Handle allOf - use first schema's default
+    if (hasAllOf(schema) && schema.allOf.length > 0) {
+        const firstSchema = schema.allOf[0];
+        if (firstSchema !== undefined) {
+            return getDefaultValue(firstSchema);
+        }
+    }
+    // x-mjst bigint has no native JSON type but a sensible zero default.
+    if (getMjstPrimitive(schema) === 'bigint') {
+        return '0n';
+    }
+    if (!hasType(schema)) {
+        return 'undefined';
+    }
+    switch (schema.type) {
+        case 'string': {
+            if (hasPattern(schema)) {
+                const patternDefault = generateDefaultFromPattern(schema.pattern);
+                if (patternDefault) {
+                    return patternDefault;
+                }
+            }
+            return '""';
+        }
+        case 'number':
+        case 'integer':
+            return '0';
+        case 'boolean':
+            return 'false';
+        case 'array':
+            return '[]';
+        case 'object':
+            return '{}';
+        default:
+            return 'undefined';
+    }
+};

package/dist/helpers/get-discriminator-value.d.ts

@@ -4,3 +4,4 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  * Returns the const value or single enum value if available.
  */
 export declare const getDiscriminatorValue: (schema: JSONSchema, discriminatorKey: string) => unknown | null;
+//# sourceMappingURL=get-discriminator-value.d.ts.map

package/dist/helpers/get-discriminator-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-discriminator-value.d.ts","sourceRoot":"","sources":["../../src/helpers/get-discriminator-value.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAEjE;;;GAGG;AACH,eAAO,MAAM,qBAAqB,WAAY,UAAU,oBAAoB,MAAM,KAAG,OAAO,GAAG,IAa9F,CAAA"}

package/dist/helpers/get-discriminator-value.js

@@ -0,0 +1,19 @@
+import { hasConst, hasEnum, hasProperties, isObjectSchema, isSchemaObject } from '@amritk/helpers/schema-guards';
+/**
+ * Gets the discriminator value for a specific schema.
+ * Returns the const value or single enum value if available.
+ */
+export const getDiscriminatorValue = (schema, discriminatorKey) => {
+    if (isObjectSchema(schema) && hasProperties(schema)) {
+        const propSchema = schema.properties[discriminatorKey];
+        if (propSchema && isSchemaObject(propSchema)) {
+            if (hasConst(propSchema)) {
+                return propSchema.const;
+            }
+            if (hasEnum(propSchema) && propSchema.enum.length === 1) {
+                return propSchema.enum[0];
+            }
+        }
+    }
+    return null;
+};

package/dist/index.d.ts

@@ -1 +1,2 @@
-export { buildSchema, type GeneratedFile } from './generators/build-schema';
+export { buildSchema, type GeneratedFile } from './generators/build-schema.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,2BAA2B,CAAA"}