@amritk/generate-parsers 0.3.1 → 0.5.0

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

@@ -34,6 +34,12 @@ export type GeneratedFile = {
  * @param helpersMode - `'package'` (default) emits `import ... from '@amritk/helpers/...'`.
  *   `'embedded'` emits `import ... from './_helpers/...'` and appends the helper sources
  *   as additional `GeneratedFile` entries so the output directory is self-contained.
+ * @param helpersImportPrefix - Relative path prefix to the `_helpers/` directory in
+ *   embedded mode. Defaults to `'./'`. The recursive multi-schema build passes `'../'`,
+ *   `'../../'`, etc. so nested parsers can import from a single shared `_helpers/`
+ *   directory while the helper sources are emitted once at the output root.
+ * @param readonly - When true, every property, array, and record in the generated type
+ *   definitions is emitted as `readonly`.
  * @returns An array of generated TypeScript files
  *
  * @example
@@ -66,4 +72,4 @@ export type GeneratedFile = {
  * });
  * ```
  */
-export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean, strict?: boolean, helpersMode?: HelpersMode) => Promise<GeneratedFile[]>;
+export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean, strict?: boolean, helpersMode?: HelpersMode, helpersImportPrefix?: string, readonly?: boolean) => Promise<GeneratedFile[]>;

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

@@ -37,6 +37,18 @@ type GenerateFileOptions = {
      *   be shipped alongside the generated files.
      */
     readonly helpersMode?: HelpersMode;
+    /**
+     * Relative path prefix to the shared `_helpers/` directory in embedded mode.
+     * Defaults to `'./'`. The recursive multi-schema build passes `'../'`,
+     * `'../../'`, etc. so a nested parser can reach a single `_helpers/` directory
+     * at the output root.
+     */
+    readonly helpersImportPrefix?: string;
+    /**
+     * When true, every property, array, and record in the generated type
+     * definitions is emitted as `readonly`.
+     */
+    readonly readonly?: boolean;
 };
 /** Result of generating a single parser file. */
 export type GeneratedFileContent = {

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

@@ -12,5 +12,12 @@ export type CollectedHelpers = {
      */
     readonly used: Set<RuntimeHelperName>;
 };
-/** Detects which runtime helpers a generated parser body references. */
-export declare const collectHelpers: (parserFunction: string, mode: HelpersMode) => CollectedHelpers;
+/**
+ * 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 declare const collectHelpers: (parserFunction: string, mode: HelpersMode, helpersImportPrefix?: string) => CollectedHelpers;

package/dist/index.d.ts

@@ -1 +1 @@
-export { buildSchema } from './generators/build-schema';
+export { buildSchema, type GeneratedFile } from './generators/build-schema';

package/dist/index.js

@@ -375,6 +375,31 @@ var isSchemaObject2 = (schema) => {
 var isObjectSchema = (schema) => {
   return isSchemaObject2(schema) && (("type" in schema) && schema.type === "object" || ("properties" in schema));
 };
+var MJST_EXTENSION_KEY = "x-mjst";
+var IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var SUPPORTED_PRIMITIVES = new Set(["bigint"]);
+var SAFE_BRAND = /^[\w$ -]+$/;
+var readExtensionString = (schema, field) => {
+  if (!isSchemaObject2(schema))
+    return;
+  const extension = schema[MJST_EXTENSION_KEY];
+  if (typeof extension !== "object" || extension === null)
+    return;
+  const value = extension[field];
+  return typeof value === "string" ? value : undefined;
+};
+var getMjstInstanceOf = (schema) => {
+  const instanceOf = readExtensionString(schema, "instanceOf");
+  return instanceOf !== undefined && IDENTIFIER.test(instanceOf) ? instanceOf : undefined;
+};
+var getMjstPrimitive = (schema) => {
+  const primitive = readExtensionString(schema, "primitive");
+  return primitive !== undefined && SUPPORTED_PRIMITIVES.has(primitive) ? primitive : undefined;
+};
+var getMjstBrand = (schema) => {
+  const brand = readExtensionString(schema, "brand");
+  return brand !== undefined && SAFE_BRAND.test(brand) ? brand : undefined;
+};
 var toKebabCase4 = (value) => value.replace(/OAuth/g, "Oauth").replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").replace(/([a-z\d])([A-Z])/g, "$1-$2").toLowerCase();
 var uriRefToFilename4 = (uri) => {
   const hashIndex = uri.indexOf("#");
@@ -515,13 +540,27 @@ var buildJsDocBlock = (title, description, commentUrl) => {
 `;
   return block;
 };
-var getTypeScriptType = (schema) => {
+var getTypeScriptType = (schema, options = {}) => {
+  const base = getUnbrandedType(schema, options);
+  const brand = getMjstBrand(schema);
+  return brand ? `(${base} & { readonly __brand: '${brand}' })` : base;
+};
+var recordType = (keyType, valueType, options) => options.readonly ? `Readonly<Record<${keyType}, ${valueType}>>` : `Record<${keyType}, ${valueType}>`;
+var getUnbrandedType = (schema, options = {}) => {
   if (typeof schema === "boolean") {
     return getBooleanSubSchemaType(schema);
   }
   if (typeof schema !== "object" || schema === null) {
     return "unknown";
   }
+  const instanceOf = getMjstInstanceOf(schema);
+  if (instanceOf) {
+    return instanceOf;
+  }
+  const primitive = getMjstPrimitive(schema);
+  if (primitive) {
+    return primitive;
+  }
   if (schema.$ref) {
     if (!schema.$ref.startsWith("#")) {
       return "unknown";
@@ -555,29 +594,29 @@ var getTypeScriptType = (schema) => {
     return multiEnumUnion;
   }
   if (schema.oneOf && Array.isArray(schema.oneOf) && schema.oneOf.length > 0) {
-    let oneOfUnion = getTypeScriptType(schema.oneOf[0]);
+    let oneOfUnion = getTypeScriptType(schema.oneOf[0], options);
     for (let i = 1;i < schema.oneOf.length; i++) {
-      oneOfUnion += " | " + getTypeScriptType(schema.oneOf[i]);
+      oneOfUnion += " | " + getTypeScriptType(schema.oneOf[i], options);
     }
     return oneOfUnion;
   }
   if (schema.anyOf && Array.isArray(schema.anyOf) && schema.anyOf.length > 0) {
-    let anyOfUnion = getTypeScriptType(schema.anyOf[0]);
+    let anyOfUnion = getTypeScriptType(schema.anyOf[0], options);
     for (let i = 1;i < schema.anyOf.length; i++) {
-      anyOfUnion += " | " + getTypeScriptType(schema.anyOf[i]);
+      anyOfUnion += " | " + getTypeScriptType(schema.anyOf[i], options);
     }
     return anyOfUnion;
   }
   if (schema.allOf && Array.isArray(schema.allOf) && schema.allOf.length > 0) {
-    let intersectionTypes = getTypeScriptType(schema.allOf[0]);
+    let intersectionTypes = getTypeScriptType(schema.allOf[0], options);
     for (let i = 1;i < schema.allOf.length; i++) {
-      intersectionTypes += " & " + getTypeScriptType(schema.allOf[i]);
+      intersectionTypes += " & " + getTypeScriptType(schema.allOf[i], options);
     }
     return intersectionTypes;
   }
   const conditionalResult = getConditionalObjectSchema(schema);
   if (conditionalResult) {
-    const baseType = getTypeScriptType(conditionalResult.schema);
+    const baseType = getTypeScriptType(conditionalResult.schema, options);
     if (conditionalResult.thenRef) {
       return `(${baseType}) & ${refToName2(conditionalResult.thenRef)}`;
     }
@@ -586,20 +625,20 @@ var getTypeScriptType = (schema) => {
   if (!schema.type) {
     if (schema.additionalProperties !== undefined) {
       if (typeof schema.additionalProperties === "boolean") {
-        return `Record<string, ${getBooleanSubSchemaType(schema.additionalProperties)}>`;
+        return recordType("string", getBooleanSubSchemaType(schema.additionalProperties), options);
       }
-      return `Record<string, ${getTypeScriptType(schema.additionalProperties)}>`;
+      return recordType("string", getTypeScriptType(schema.additionalProperties, options), options);
     }
     if (schema.patternProperties && typeof schema.patternProperties === "object") {
       const firstEntry = Object.entries(schema.patternProperties)[0];
       if (firstEntry) {
         const [pattern, value] = firstEntry;
         if (value !== undefined) {
-          const valueType = typeof value === "boolean" ? getBooleanSubSchemaType(value) : getTypeScriptType(value);
+          const valueType = typeof value === "boolean" ? getBooleanSubSchemaType(value) : getTypeScriptType(value, options);
           if (pattern === "^x-") {
-            return `Record<\`x-\${string}\`, ${valueType}>`;
+            return recordType("`x-${string}`", valueType, options);
           }
-          return `Record<string, ${valueType}>`;
+          return recordType("string", valueType, options);
         }
       }
     }
@@ -652,41 +691,42 @@ var getTypeScriptType = (schema) => {
       return "boolean";
     case "array":
       if (schema.items) {
-        const itemType = getTypeScriptType(schema.items);
+        const itemType = getTypeScriptType(schema.items, options);
         const wrappedItemType = itemType.includes(" | ") ? `(${itemType})` : itemType;
-        return `${wrappedItemType}[]`;
+        return options.readonly ? `readonly ${wrappedItemType}[]` : `${wrappedItemType}[]`;
       }
-      return "unknown[]";
+      return options.readonly ? "readonly unknown[]" : "unknown[]";
     case "object":
       if (schema.properties) {
+        const readonlyPrefix = options.readonly ? "readonly " : "";
         let properties = "";
         let first = true;
         for (const key in schema.properties) {
           const propSchema = schema.properties[key];
           const isRequired = schema.required?.includes(key) ?? false;
           const optional = isRequired ? "" : "?";
-          const propType = getTypeScriptType(propSchema);
+          const propType = getTypeScriptType(propSchema, options);
           if (!first)
             properties += "; ";
-          properties += safeKey(key) + optional + ": " + propType;
+          properties += readonlyPrefix + safeKey(key) + optional + ": " + propType;
           first = false;
         }
         return "{ " + properties + " }";
       }
       if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
-        const additionalPropType = getTypeScriptType(schema.additionalProperties);
-        return `Record<string, ${additionalPropType}>`;
+        const additionalPropType = getTypeScriptType(schema.additionalProperties, options);
+        return recordType("string", additionalPropType, options);
       }
       if (schema.patternProperties && typeof schema.patternProperties === "object") {
         const firstEntry = Object.entries(schema.patternProperties)[0];
         if (firstEntry) {
           const [pattern, patternVal] = firstEntry;
           if (patternVal) {
-            const valueType = getTypeScriptType(patternVal);
+            const valueType = getTypeScriptType(patternVal, options);
             if (pattern === "^x-") {
-              return `Record<\`x-\${string}\`, ${valueType}>`;
+              return recordType("`x-${string}`", valueType, options);
             }
-            return `Record<string, ${valueType}>`;
+            return recordType("string", valueType, options);
           }
         }
       }
@@ -695,9 +735,10 @@ var getTypeScriptType = (schema) => {
       return "unknown";
   }
 };
-var generateTypeDefinition = (schema, typeName) => {
+var generateTypeDefinition = (schema, typeName, options = {}) => {
+  const readonlyPrefix = options.readonly ? "readonly " : "";
   if (!isObjectLikeSchema(schema)) {
-    const tsType = getTypeScriptType(schema);
+    const tsType = getTypeScriptType(schema, options);
     let result = "";
     if (isSchemaObject2(schema) && schema.$comment && typeof schema.$comment === "string") {
       result += buildJsDocBlock(typeName, schema.$comment);
@@ -725,23 +766,23 @@ var generateTypeDefinition = (schema, typeName) => {
       if (firstPatternProperty === undefined) {
         return `export type ${typeName} = Record<string, unknown>;`;
       }
-      const patternPropType = typeof firstPatternProperty === "boolean" ? getBooleanSubSchemaType(firstPatternProperty) : getTypeScriptType(firstPatternProperty);
+      const patternPropType = typeof firstPatternProperty === "boolean" ? getBooleanSubSchemaType(firstPatternProperty) : getTypeScriptType(firstPatternProperty, options);
       const keyType = firstPattern === "^x-" ? "`x-${string}`" : "string";
       let result2 = "";
       if (jsDocTitle && jsDocDescription) {
         result2 += buildJsDocBlock(jsDocTitle, jsDocDescription);
       }
-      result2 += `export type ${typeName} = Record<${keyType}, ${patternPropType}>;`;
+      result2 += `export type ${typeName} = ${recordType(keyType, patternPropType, options)};`;
       return result2;
     }
     if (!hasProperties2 && hasAdditionalProperties2 && normalizedSchema.additionalProperties) {
-      const additionalPropType = getTypeScriptType(normalizedSchema.additionalProperties);
+      const additionalPropType = getTypeScriptType(normalizedSchema.additionalProperties, options);
       let result2 = "";
       if (jsDocTitle && jsDocDescription) {
         result2 += buildJsDocBlock(jsDocTitle, jsDocDescription);
       }
       result2 += `export type ${typeName} = {
-  [key: string]: ${additionalPropType};
+  ${readonlyPrefix}[key: string]: ${additionalPropType};
 };`;
       return result2;
     }
@@ -752,8 +793,8 @@ var generateTypeDefinition = (schema, typeName) => {
       const propSchema = schemaProps[key];
       const isRequired = normalizedSchema.required?.includes(key) ?? false;
       const optional = isRequired ? "" : "?";
-      const propType = getTypeScriptType(propSchema);
-      const quotedKey = safeKey(key);
+      const propType = getTypeScriptType(propSchema, options);
+      const quotedKey = readonlyPrefix + safeKey(key);
       if (!isFirstProp)
         properties += `
 `;
@@ -803,31 +844,32 @@ var PACKAGE_IMPORTS = {
   "validate-record": "import { validateRecord } from '@amritk/helpers/validate-record';",
   "has-ref": "import { hasRef } from '@amritk/helpers/schema-guards';"
 };
-var EMBEDDED_IMPORTS = {
-  "is-object": "import { isObject } from './_helpers/is-object';",
-  "validate-array": "import { validateArray } from './_helpers/validate-array';",
-  "validate-record": "import { validateRecord } from './_helpers/validate-record';",
-  "has-ref": "import { hasRef } from './_helpers/has-ref';"
+var EMBEDDED_NAMED_EXPORTS = {
+  "is-object": "isObject",
+  "validate-array": "validateArray",
+  "validate-record": "validateRecord",
+  "has-ref": "hasRef"
 };
-var collectHelpers = (parserFunction, mode) => {
+var embeddedImport = (helper, prefix) => `import { ${EMBEDDED_NAMED_EXPORTS[helper]} } from '${prefix}_helpers/${helper}';`;
+var collectHelpers = (parserFunction, mode, helpersImportPrefix = "./") => {
   const imports = [];
   const used = new Set;
-  const table = mode === "embedded" ? EMBEDDED_IMPORTS : PACKAGE_IMPORTS;
+  const importFor = (helper) => mode === "embedded" ? embeddedImport(helper, helpersImportPrefix) : PACKAGE_IMPORTS[helper];
   if (parserFunction.includes("validateArray")) {
-    imports.push(table["validate-array"]);
+    imports.push(importFor("validate-array"));
     used.add("validate-array");
   }
   if (parserFunction.includes("validateRecord")) {
-    imports.push(table["validate-record"]);
+    imports.push(importFor("validate-record"));
     used.add("validate-record");
     used.add("is-object");
   }
   if (parserFunction.includes("isObject")) {
-    imports.push(table["is-object"]);
+    imports.push(importFor("is-object"));
     used.add("is-object");
   }
   if (parserFunction.includes("hasRef(")) {
-    imports.push(table["has-ref"]);
+    imports.push(importFor("has-ref"));
     used.add("has-ref");
   }
   return { imports, used };
@@ -1082,6 +1124,31 @@ var safeKey2 = (key) => {
   return `'${key}'`;
 };
 
+// ../helpers/dist/mjst-extension.js
+var isSchemaObject4 = (schema) => {
+  return typeof schema === "object" && schema !== null && typeof schema !== "boolean";
+};
+var MJST_EXTENSION_KEY2 = "x-mjst";
+var IDENTIFIER2 = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var SUPPORTED_PRIMITIVES2 = new Set(["bigint"]);
+var readExtensionString2 = (schema, field) => {
+  if (!isSchemaObject4(schema))
+    return;
+  const extension = schema[MJST_EXTENSION_KEY2];
+  if (typeof extension !== "object" || extension === null)
+    return;
+  const value = extension[field];
+  return typeof value === "string" ? value : undefined;
+};
+var getMjstInstanceOf2 = (schema) => {
+  const instanceOf = readExtensionString2(schema, "instanceOf");
+  return instanceOf !== undefined && IDENTIFIER2.test(instanceOf) ? instanceOf : undefined;
+};
+var getMjstPrimitive2 = (schema) => {
+  const primitive = readExtensionString2(schema, "primitive");
+  return primitive !== undefined && SUPPORTED_PRIMITIVES2.has(primitive) ? primitive : undefined;
+};
+
 // src/generators/generate-default-from-pattern.ts
 var generateDefaultFromPattern = (pattern) => {
   if (pattern.includes("@") || pattern.includes("[a-zA-Z0-9]") && pattern.includes("\\.")) {
@@ -1139,6 +1206,9 @@ var getDefaultValue = (schema) => {
       return getDefaultValue(firstSchema);
     }
   }
+  if (getMjstPrimitive2(schema) === "bigint") {
+    return "0n";
+  }
   if (!hasType(schema)) {
     return "undefined";
   }
@@ -1234,6 +1304,24 @@ var generatePropertyAssertion = (key, propSchema, isRequired, typeName) => {
     return lines;
   if (hasRef(propSchema))
     return lines;
+  const instanceOf = getMjstInstanceOf2(propSchema);
+  if (instanceOf) {
+    if (isRequired) {
+      lines.push(`  if (!(${acc} instanceof ${instanceOf})) throw new Error('[${typeName}] field "${key}" must be ${instanceOf}');`);
+    } else {
+      lines.push(`  if (${acc} !== undefined && !(${acc} instanceof ${instanceOf})) throw new Error('[${typeName}] field "${key}" must be ${instanceOf}');`);
+    }
+    return lines;
+  }
+  const primitive = getMjstPrimitive2(propSchema);
+  if (primitive) {
+    if (isRequired) {
+      lines.push(`  if (typeof ${acc} !== "${primitive}") throw new Error('[${typeName}] field "${key}" must be ${primitive}');`);
+    } else {
+      lines.push(`  if (${acc} !== undefined && typeof ${acc} !== "${primitive}") throw new Error('[${typeName}] field "${key}" must be ${primitive}');`);
+    }
+    return lines;
+  }
   if (hasEnum(propSchema)) {
     const allowed = JSON.stringify(propSchema.enum);
     const label = propSchema.enum.map((v) => JSON.stringify(v)).join(", ");
@@ -1270,6 +1358,14 @@ var generateObjectStrictAssertion = (schema, typeName) => {
   return lines;
 };
 var generateScalarStrictAssertion = (schema, typeName) => {
+  const instanceOf = getMjstInstanceOf2(schema);
+  if (instanceOf) {
+    return `  if (!(input instanceof ${instanceOf})) throw new Error(\`[${typeName}] expected ${instanceOf}, got \${input === null ? "null" : typeof input}\`);`;
+  }
+  const primitive = getMjstPrimitive2(schema);
+  if (primitive) {
+    return `  if (typeof input !== "${primitive}") throw new Error(\`[${typeName}] expected ${primitive}, got \${input === null ? "null" : typeof input}\`);`;
+  }
   if (!isSchemaObject3(schema) || !hasType(schema))
     return null;
   const t = schema.type;
@@ -1329,6 +1425,14 @@ var generateEnumCheck = (accessor, enumValues) => {
 // src/generators/generate-schema-checks.ts
 var generateSchemaChecks = (accessor, schema) => {
   const checks = [];
+  const instanceOf = getMjstInstanceOf2(schema);
+  if (instanceOf) {
+    return [`${accessor} instanceof ${instanceOf}`];
+  }
+  const primitive = getMjstPrimitive2(schema);
+  if (primitive) {
+    return [`typeof ${accessor} === "${primitive}"`];
+  }
   if (!hasType(schema)) {
     return checks;
   }
@@ -1461,6 +1565,11 @@ var generateNonDiscriminatedUnionValidation = (accessor, schemas, defaultValue,
 };
 
 // src/generators/generate-validation-expression.ts
+var getInstanceCoercion = (accessor, instanceOf) => {
+  if (instanceOf === "Date")
+    return `new Date(${accessor} as string | number | Date)`;
+  return null;
+};
 var getTypeCoercion = (accessor, schema, defaultValue) => {
   if (!hasType(schema)) {
     return null;
@@ -1489,6 +1598,20 @@ var generateValidationExpression = (key, schema, defaultValue, isRequired, rootS
   if (!isSchemaObject3(schema)) {
     return isRequired ? `${accessor} ?? ${defaultValue}` : accessor;
   }
+  const instanceOf = getMjstInstanceOf2(schema);
+  if (instanceOf) {
+    const valid = `${accessor} instanceof ${instanceOf}`;
+    const coercion = getInstanceCoercion(accessor, instanceOf);
+    if (isRequired) {
+      return coercion ? `${valid} ? ${accessor} : (${accessor} !== undefined ? ${coercion} : ${defaultValue})` : `${valid} ? ${accessor} : ${defaultValue}`;
+    }
+    return coercion ? `${valid} ? ${accessor} : (${accessor} !== undefined ? ${coercion} : undefined)` : `${valid} ? ${accessor} : undefined`;
+  }
+  const primitive = getMjstPrimitive2(schema);
+  if (primitive) {
+    const valid = `typeof ${accessor} === "${primitive}"`;
+    return isRequired ? `${valid} ? ${accessor} : ${defaultValue}` : `${valid} ? ${accessor} : undefined`;
+  }
   if (hasRef(schema) && rootSchema) {
     const ref = schema.$ref;
     if (visitedRefs?.has(ref)) {
@@ -2443,7 +2566,7 @@ var generateFile = (schema, typeName, options) => {
   const selfRef = options?.selfRef;
   const rootSchema = options?.rootSchema;
   const helpersMode = options?.helpersMode ?? "package";
-  const typeDefinition = generateTypeDefinition(schema, typeName);
+  const typeDefinition = generateTypeDefinition(schema, typeName, { readonly: options?.readonly ?? false });
   if (typesOnly) {
     const imports2 = collectImports(schema, { typesOnly: true, selfRef, rootSchema });
     let result2 = "";
@@ -2468,7 +2591,7 @@ var generateFile = (schema, typeName, options) => {
   const combinedFunctions = `${shapeValidator}
 
 ${parserFunction}`;
-  const helpers = collectHelpers(combinedFunctions, helpersMode);
+  const helpers = collectHelpers(combinedFunctions, helpersMode, options?.helpersImportPrefix);
   const imports = [...collectImports(schema, { selfRef, rootSchema }), ...helpers.imports];
   let result = "";
   if (imports.length > 0) {
@@ -2512,7 +2635,7 @@ var extractDynamicAnchorDefs = (schema) => {
   }
   return refs;
 };
-var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = "package") => {
+var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = "package", helpersImportPrefix = "./", readonly = false) => {
   rootSchema = upgradeDraft07Schema(rootSchema);
   const files = [];
   const processedRefs = new Set;
@@ -2526,6 +2649,8 @@ var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWar
     typesOnly: typesOnly ?? false,
     rootSchema,
     helpersMode,
+    helpersImportPrefix,
+    readonly,
     ...logWarnings !== undefined ? { logWarnings } : {},
     ...strict !== undefined ? { strict } : {}
   });
@@ -2561,6 +2686,8 @@ var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWar
       selfRef: ref,
       rootSchema,
       helpersMode,
+      helpersImportPrefix,
+      readonly,
       ...logWarnings !== undefined ? { logWarnings } : {},
       ...strict !== undefined ? { strict } : {}
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-parsers",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
@@ -48,8 +48,8 @@
     }
   },
   "dependencies": {
-    "json-schema-typed": "catalog:",
-    "@amritk/helpers": "workspace:*",
-    "@amritk/generate-markdown": "workspace:*"
+    "json-schema-typed": "^8.0.1",
+    "@amritk/helpers": "0.5.0",
+    "@amritk/generate-markdown": "0.2.1"
   }
 }

package/src/generators/build-schema.test.ts

@@ -681,6 +681,30 @@ describe('build-schema', () => {
       expect(filenames).toContain('_helpers/is-object.ts')
     })
 
+    it('honours a custom helpersImportPrefix so nested parsers import from a shared root _helpers/', async () => {
+      const schema: JSONSchema = {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+      }
+
+      const result = await buildSchema(
+        schema,
+        'Document',
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        'embedded',
+        '../../',
+      )
+      const root = result.find((f) => f.filename === 'document.ts')
+      const filenames = result.map((f) => f.filename)
+
+      expect(root?.content).toContain("import { isObject } from '../../_helpers/is-object';")
+      // Helper sources keep their canonical filenames; the orchestrator relocates them to the root.
+      expect(filenames).toContain('_helpers/is-object.ts')
+    })
+
     it('ships validate-array.ts (plus its transitive is-object.ts) for array schemas', async () => {
       const schema: JSONSchema = {
         type: 'object',

package/src/generators/build-schema.ts

@@ -90,6 +90,12 @@ const extractDynamicAnchorDefs = (schema: JSONSchema): string[] => {
  * @param helpersMode - `'package'` (default) emits `import ... from '@amritk/helpers/...'`.
  *   `'embedded'` emits `import ... from './_helpers/...'` and appends the helper sources
  *   as additional `GeneratedFile` entries so the output directory is self-contained.
+ * @param helpersImportPrefix - Relative path prefix to the `_helpers/` directory in
+ *   embedded mode. Defaults to `'./'`. The recursive multi-schema build passes `'../'`,
+ *   `'../../'`, etc. so nested parsers can import from a single shared `_helpers/`
+ *   directory while the helper sources are emitted once at the output root.
+ * @param readonly - When true, every property, array, and record in the generated type
+ *   definitions is emitted as `readonly`.
  * @returns An array of generated TypeScript files
  *
  * @example
@@ -130,6 +136,8 @@ export const buildSchema = async (
   logWarnings?: boolean,
   strict?: boolean,
   helpersMode: HelpersMode = 'package',
+  helpersImportPrefix = './',
+  readonly = false,
 ): Promise<GeneratedFile[]> => {
   // Upgrade draft-07 schemas to 2020-12 conventions before processing.
   // This renames `definitions` → `$defs` recursively so the rest of the
@@ -155,6 +163,8 @@ export const buildSchema = async (
     typesOnly: typesOnly ?? false,
     rootSchema: rootSchema as Record<string, unknown>,
     helpersMode,
+    helpersImportPrefix,
+    readonly,
     ...(logWarnings !== undefined ? { logWarnings } : {}),
     ...(strict !== undefined ? { strict } : {}),
   })
@@ -205,6 +215,8 @@ export const buildSchema = async (
       selfRef: ref,
       rootSchema: rootSchema as Record<string, unknown>,
       helpersMode,
+      helpersImportPrefix,
+      readonly,
       ...(logWarnings !== undefined ? { logWarnings } : {}),
       ...(strict !== undefined ? { strict } : {}),
     })

package/src/generators/generate-files.ts

@@ -47,6 +47,18 @@ type GenerateFileOptions = {
    *   be shipped alongside the generated files.
    */
   readonly helpersMode?: HelpersMode
+  /**
+   * Relative path prefix to the shared `_helpers/` directory in embedded mode.
+   * Defaults to `'./'`. The recursive multi-schema build passes `'../'`,
+   * `'../../'`, etc. so a nested parser can reach a single `_helpers/` directory
+   * at the output root.
+   */
+  readonly helpersImportPrefix?: string
+  /**
+   * When true, every property, array, and record in the generated type
+   * definitions is emitted as `readonly`.
+   */
+  readonly readonly?: boolean
 }
 
 /** Result of generating a single parser file. */
@@ -93,7 +105,7 @@ export const generateFile = (
   const selfRef = options?.selfRef
   const rootSchema = options?.rootSchema
   const helpersMode: HelpersMode = options?.helpersMode ?? 'package'
-  const typeDefinition = generateTypeDefinition(schema, typeName)
+  const typeDefinition = generateTypeDefinition(schema, typeName, { readonly: options?.readonly ?? false })
 
   if (typesOnly) {
     // In types-only mode, skip the parser function and use type-only imports
@@ -118,7 +130,7 @@ export const generateFile = (
   })
   const shapeValidator = generateShapeValidator(schema, typeName, true)
   const combinedFunctions = `${shapeValidator}\n\n${parserFunction}`
-  const helpers: CollectedHelpers = collectHelpers(combinedFunctions, helpersMode)
+  const helpers: CollectedHelpers = collectHelpers(combinedFunctions, helpersMode, options?.helpersImportPrefix)
   const imports = [...collectImports(schema, { selfRef, rootSchema }), ...helpers.imports]
 
   // Build file output using string concatenation instead of array join for performance

package/src/generators/generate-schema-checks.test.ts

@@ -319,4 +319,12 @@ describe('generate-schema-checks', () => {
     const result = generateSchemaChecks('input?.name', { type: 'string', minLength: 1 })
     expect(result).toEqual(['typeof input?.name === "string"', 'input?.name.length >= 1'])
   })
+
+  it('returns an instanceof check for an x-mjst instanceOf node', () => {
+    expect(generateSchemaChecks('value', { 'x-mjst': { instanceOf: 'Date' } })).toEqual(['value instanceof Date'])
+  })
+
+  it('returns a typeof check for an x-mjst bigint node', () => {
+    expect(generateSchemaChecks('value', { 'x-mjst': { primitive: 'bigint' } })).toEqual(['typeof value === "bigint"'])
+  })
 })

package/src/generators/generate-schema-checks.ts

@@ -1,3 +1,4 @@
+import { getMjstInstanceOf, getMjstPrimitive } from '@amritk/helpers/mjst-extension'
 import {
   hasAdditionalProperties,
   hasEnum,
@@ -28,6 +29,18 @@ import { generateEnumCheck } from './generate-enum-check'
 export const generateSchemaChecks = (accessor: string, schema: JSONSchema): string[] => {
   const checks: string[] = []
 
+  // x-mjst instanceOf nodes validate purely by instance check (no native type).
+  const instanceOf = getMjstInstanceOf(schema)
+  if (instanceOf) {
+    return [`${accessor} instanceof ${instanceOf}`]
+  }
+
+  // x-mjst primitive nodes (e.g. bigint) validate purely by typeof check.
+  const primitive = getMjstPrimitive(schema)
+  if (primitive) {
+    return [`typeof ${accessor} === "${primitive}"`]
+  }
+
   if (!hasType(schema)) {
     return checks
   }

package/src/generators/generate-strict-assertion.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest'
+
+import { generateObjectStrictAssertion, generateScalarStrictAssertion } from './generate-strict-assertion'
+
+describe('generate-strict-assertion x-mjst instanceOf', () => {
+  it('asserts instanceof for a required Date property', () => {
+    const schema = {
+      type: 'object' as const,
+      properties: { createdAt: { 'x-mjst': { instanceOf: 'Date' } } },
+      required: ['createdAt'],
+    }
+    const lines = generateObjectStrictAssertion(schema, 'Event').join('\n')
+
+    expect(lines).toContain('missing required property "createdAt"')
+    expect(lines).toContain('!(input.createdAt instanceof Date)')
+    expect(lines).toContain('field "createdAt" must be Date')
+  })
+
+  it('guards undefined before asserting instanceof for an optional Date property', () => {
+    const schema = {
+      type: 'object' as const,
+      properties: { createdAt: { 'x-mjst': { instanceOf: 'Date' } } },
+    }
+    const lines = generateObjectStrictAssertion(schema, 'Event').join('\n')
+
+    expect(lines).toContain('input.createdAt !== undefined && !(input.createdAt instanceof Date)')
+  })
+
+  it('asserts instanceof for a top-level Date schema', () => {
+    const line = generateScalarStrictAssertion({ 'x-mjst': { instanceOf: 'Date' } }, 'When')
+
+    expect(line).toContain('!(input instanceof Date)')
+    expect(line).toContain('expected Date')
+  })
+})
+
+describe('generate-strict-assertion x-mjst primitive', () => {
+  it('asserts typeof bigint for a required property', () => {
+    const schema = {
+      type: 'object' as const,
+      properties: { balance: { 'x-mjst': { primitive: 'bigint' } } },
+      required: ['balance'],
+    }
+    const lines = generateObjectStrictAssertion(schema, 'Account').join('\n')
+
+    expect(lines).toContain('missing required property "balance"')
+    expect(lines).toContain('typeof input.balance !== "bigint"')
+    expect(lines).toContain('field "balance" must be bigint')
+  })
+
+  it('guards undefined before asserting typeof for an optional bigint property', () => {
+    const schema = {
+      type: 'object' as const,
+      properties: { balance: { 'x-mjst': { primitive: 'bigint' } } },
+    }
+    const lines = generateObjectStrictAssertion(schema, 'Account').join('\n')
+
+    expect(lines).toContain('input.balance !== undefined && typeof input.balance !== "bigint"')
+  })
+
+  it('asserts typeof for a top-level bigint schema', () => {
+    const line = generateScalarStrictAssertion({ 'x-mjst': { primitive: 'bigint' } }, 'Big')
+
+    expect(line).toContain('typeof input !== "bigint"')
+    expect(line).toContain('expected bigint')
+  })
+})

package/src/generators/generate-strict-assertion.ts

@@ -1,3 +1,4 @@
+import { getMjstInstanceOf, getMjstPrimitive } from '@amritk/helpers/mjst-extension'
 import { safeAccessor } from '@amritk/helpers/safe-accessor'
 import {
   hasEnum,
@@ -134,6 +135,34 @@ const generatePropertyAssertion = (
   if (!isSchemaObject(propSchema)) return lines
   if (hasRef(propSchema)) return lines
 
+  const instanceOf = getMjstInstanceOf(propSchema)
+  if (instanceOf) {
+    if (isRequired) {
+      lines.push(
+        `  if (!(${acc} instanceof ${instanceOf})) throw new Error('[${typeName}] field "${key}" must be ${instanceOf}');`,
+      )
+    } else {
+      lines.push(
+        `  if (${acc} !== undefined && !(${acc} instanceof ${instanceOf})) throw new Error('[${typeName}] field "${key}" must be ${instanceOf}');`,
+      )
+    }
+    return lines
+  }
+
+  const primitive = getMjstPrimitive(propSchema)
+  if (primitive) {
+    if (isRequired) {
+      lines.push(
+        `  if (typeof ${acc} !== "${primitive}") throw new Error('[${typeName}] field "${key}" must be ${primitive}');`,
+      )
+    } else {
+      lines.push(
+        `  if (${acc} !== undefined && typeof ${acc} !== "${primitive}") throw new Error('[${typeName}] field "${key}" must be ${primitive}');`,
+      )
+    }
+    return lines
+  }
+
   if (hasEnum(propSchema)) {
     const allowed = JSON.stringify(propSchema.enum)
     const label = (propSchema.enum as unknown[]).map((v) => JSON.stringify(v)).join(', ')
@@ -202,6 +231,16 @@ export const generateObjectStrictAssertion = (schema: JSONSchema, typeName: stri
  * Returns null when the schema has no type information to assert on.
  */
 export const generateScalarStrictAssertion = (schema: JSONSchema, typeName: string): string | null => {
+  const instanceOf = getMjstInstanceOf(schema)
+  if (instanceOf) {
+    return `  if (!(input instanceof ${instanceOf})) throw new Error(\`[${typeName}] expected ${instanceOf}, got \${input === null ? "null" : typeof input}\`);`
+  }
+
+  const primitive = getMjstPrimitive(schema)
+  if (primitive) {
+    return `  if (typeof input !== "${primitive}") throw new Error(\`[${typeName}] expected ${primitive}, got \${input === null ? "null" : typeof input}\`);`
+  }
+
   if (!isSchemaObject(schema) || !hasType(schema)) return null
   const t = schema.type as string
   const wrongType = wrongTypeCondition('input', t)

package/src/generators/generate-validation-expression.test.ts

@@ -791,4 +791,41 @@ describe('generate-validation-expression', () => {
 
     expect(result).toContain('? input?.status : undefined')
   })
+
+  it('checks instanceof and coerces a required x-mjst Date field', () => {
+    const schema = { 'x-mjst': { instanceOf: 'Date' } }
+    const result = generateValidationExpression('createdAt', schema, '{}', true)
+
+    expect(result).toContain('input?.createdAt instanceof Date')
+    expect(result).toContain('new Date(input?.createdAt as string | number | Date)')
+  })
+
+  it('checks instanceof and coerces an optional x-mjst Date field', () => {
+    const schema = { 'x-mjst': { instanceOf: 'Date' } }
+    const result = generateValidationExpression('createdAt', schema, 'undefined', false)
+
+    expect(result).toContain('input?.createdAt instanceof Date')
+    expect(result).toContain('? input?.createdAt : (input?.createdAt !== undefined ? new Date')
+  })
+
+  it('falls back to the default for an unknown instanceOf with no coercion', () => {
+    const schema = { 'x-mjst': { instanceOf: 'CustomThing' } }
+    const result = generateValidationExpression('value', schema, '{}', true)
+
+    expect(result).toBe('input?.value instanceof CustomThing ? input?.value : {}')
+  })
+
+  it('checks typeof bigint for a required x-mjst primitive field', () => {
+    const schema = { 'x-mjst': { primitive: 'bigint' } }
+    const result = generateValidationExpression('balance', schema, '0n', true)
+
+    expect(result).toBe('typeof input?.balance === "bigint" ? input?.balance : 0n')
+  })
+
+  it('checks typeof bigint for an optional x-mjst primitive field', () => {
+    const schema = { 'x-mjst': { primitive: 'bigint' } }
+    const result = generateValidationExpression('balance', schema, '0n', false)
+
+    expect(result).toBe('typeof input?.balance === "bigint" ? input?.balance : undefined')
+  })
 })

package/src/generators/generate-validation-expression.ts

@@ -1,3 +1,4 @@
+import { getMjstInstanceOf, getMjstPrimitive } from '@amritk/helpers/mjst-extension'
 import { resolveRef } from '@amritk/helpers/resolve-ref'
 import { safeAccessor } from '@amritk/helpers/safe-accessor'
 import {
@@ -34,6 +35,17 @@ import { generateEnumCheck } from './generate-enum-check'
 import { generateNonDiscriminatedUnionValidation } from './generate-non-discriminated-union-validation'
 import { generateSchemaChecks } from './generate-schema-checks'
 
+/**
+ * Coercion expression for an `x-mjst` instanceOf value, when one is known.
+ * `Date` can be reconstructed from the common JSON encodings (ISO string or
+ * epoch number); other classes have no safe generic coercion, so we return null
+ * and the caller falls back to the default.
+ */
+const getInstanceCoercion = (accessor: string, instanceOf: string): string | null => {
+  if (instanceOf === 'Date') return `new Date(${accessor} as string | number | Date)`
+  return null
+}
+
 /**
  * Generates a type coercion expression for converting a value to the expected type.
  */
@@ -85,6 +97,34 @@ export const generateValidationExpression = (
     return isRequired ? `${accessor} ?? ${defaultValue}` : accessor
   }
 
+  // Handle x-mjst instanceOf (e.g. Date): the value must be an instance of the
+  // named class. Invalid values are coerced when a coercer is known, otherwise
+  // they fall back to the default (required) or undefined (optional).
+  const instanceOf = getMjstInstanceOf(schema)
+  if (instanceOf) {
+    const valid = `${accessor} instanceof ${instanceOf}`
+    const coercion = getInstanceCoercion(accessor, instanceOf)
+
+    if (isRequired) {
+      return coercion
+        ? `${valid} ? ${accessor} : (${accessor} !== undefined ? ${coercion} : ${defaultValue})`
+        : `${valid} ? ${accessor} : ${defaultValue}`
+    }
+    return coercion
+      ? `${valid} ? ${accessor} : (${accessor} !== undefined ? ${coercion} : undefined)`
+      : `${valid} ? ${accessor} : undefined`
+  }
+
+  // Handle x-mjst primitive (e.g. bigint): validate with typeof. We do not
+  // coerce — BigInt() throws on invalid input, which a pure coercion expression
+  // cannot guard — so invalid values fall back to the default (required) or
+  // undefined (optional).
+  const primitive = getMjstPrimitive(schema)
+  if (primitive) {
+    const valid = `typeof ${accessor} === "${primitive}"`
+    return isRequired ? `${valid} ? ${accessor} : ${defaultValue}` : `${valid} ? ${accessor} : undefined`
+  }
+
   // Handle $ref - resolve and validate against the referenced schema
   if (hasRef(schema) && rootSchema) {
     const ref = schema.$ref

package/src/helpers/collect-helpers.test.ts

@@ -99,5 +99,17 @@ describe('collect-helpers', () => {
       expect(result.imports).toContain("import { validateRecord } from './_helpers/validate-record';")
       expect(result.imports).toContain("import { isObject } from './_helpers/is-object';")
     })
+
+    it('applies a custom import prefix so nested parsers can reach a shared _helpers/ at the root', () => {
+      const parser = 'if (isObject(input)) { const arr = validateArray(input.items, parseItem) }'
+      const result = collectHelpers(parser, 'embedded', '../../')
+      expect(result.imports).toContain("import { isObject } from '../../_helpers/is-object';")
+      expect(result.imports).toContain("import { validateArray } from '../../_helpers/validate-array';")
+    })
+
+    it('ignores the import prefix in package mode', () => {
+      const result = collectHelpers('if (isObject(input)) {', 'package', '../')
+      expect(result.imports).toEqual(["import { isObject } from '@amritk/helpers/is-object';"])
+    })
   })
 })

package/src/helpers/collect-helpers.ts

@@ -23,26 +23,41 @@ const PACKAGE_IMPORTS: Record<RuntimeHelperName, string> = {
   'has-ref': "import { hasRef } from '@amritk/helpers/schema-guards';",
 }
 
-const EMBEDDED_IMPORTS: Record<RuntimeHelperName, string> = {
-  'is-object': "import { isObject } from './_helpers/is-object';",
-  'validate-array': "import { validateArray } from './_helpers/validate-array';",
-  'validate-record': "import { validateRecord } from './_helpers/validate-record';",
-  'has-ref': "import { hasRef } from './_helpers/has-ref';",
+const EMBEDDED_NAMED_EXPORTS: Record<RuntimeHelperName, string> = {
+  'is-object': 'isObject',
+  'validate-array': 'validateArray',
+  'validate-record': 'validateRecord',
+  'has-ref': 'hasRef',
 }
 
-/** Detects which runtime helpers a generated parser body references. */
-export const collectHelpers = (parserFunction: string, mode: HelpersMode): CollectedHelpers => {
+const embeddedImport = (helper: RuntimeHelperName, prefix: string): string =>
+  `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: string,
+  mode: HelpersMode,
+  helpersImportPrefix = './',
+): CollectedHelpers => {
   const imports: string[] = []
   const used = new Set<RuntimeHelperName>()
-  const table = mode === 'embedded' ? EMBEDDED_IMPORTS : PACKAGE_IMPORTS
+  const importFor = (helper: RuntimeHelperName): string =>
+    mode === 'embedded' ? embeddedImport(helper, helpersImportPrefix) : PACKAGE_IMPORTS[helper]
 
   if (parserFunction.includes('validateArray')) {
-    imports.push(table['validate-array'])
+    imports.push(importFor('validate-array'))
     used.add('validate-array')
   }
 
   if (parserFunction.includes('validateRecord')) {
-    imports.push(table['validate-record'])
+    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
@@ -51,12 +66,12 @@ export const collectHelpers = (parserFunction: string, mode: HelpersMode): Colle
   }
 
   if (parserFunction.includes('isObject')) {
-    imports.push(table['is-object'])
+    imports.push(importFor('is-object'))
     used.add('is-object')
   }
 
   if (parserFunction.includes('hasRef(')) {
-    imports.push(table['has-ref'])
+    imports.push(importFor('has-ref'))
     used.add('has-ref')
   }
 

package/src/helpers/get-default-value.test.ts

@@ -132,4 +132,8 @@ describe('get-default-value', () => {
   it('handles empty oneOf array and falls back', () => {
     expect(getDefaultValue({ oneOf: [], type: 'boolean' })).toBe('false')
   })
+
+  it('returns 0n for an x-mjst bigint schema', () => {
+    expect(getDefaultValue({ 'x-mjst': { primitive: 'bigint' } })).toBe('0n')
+  })
 })

package/src/helpers/get-default-value.ts

@@ -1,3 +1,4 @@
+import { getMjstPrimitive } from '@amritk/helpers/mjst-extension'
 import {
   hasAllOf,
   hasAnyOf,
@@ -60,6 +61,11 @@ export const getDefaultValue = (schema: JSONSchema): string => {
     }
   }
 
+  // x-mjst bigint has no native JSON type but a sensible zero default.
+  if (getMjstPrimitive(schema) === 'bigint') {
+    return '0n'
+  }
+
   if (!hasType(schema)) {
     return 'undefined'
   }

package/src/index.ts

@@ -1 +1 @@
-export { buildSchema } from './generators/build-schema'
+export { buildSchema, type GeneratedFile } from './generators/build-schema'