@amritk/helpers

Shared schema-traversal and runtime helpers for the mjst code generation ecosystem.

Overview

@amritk/helpers is the shared utility belt used by mjst's generators and by the runtime code those generators produce. Each helper is published as its own subpath export so consumers (and generated output) only pull in what they need — no barrel, no incidental dependencies.

Installation

npm install @amritk/helpers
# or
pnpm add @amritk/helpers
# or
yarn add @amritk/helpers
# or
bun add @amritk/helpers

Modules

Schema traversal

| Subpath | Exports | Purpose | |:---|:---|:---| | @amritk/helpers/extract-refs | extractRefs | Collect every $ref reachable from a schema. | | @amritk/helpers/resolve-ref | resolveRef | Resolve a $ref — JSON Pointer, $anchor name, or URI — against a root schema. | | @amritk/helpers/build-anchor-map | buildAnchorMap | Build a map of $anchor / $dynamicAnchor name → JSON Pointer. | | @amritk/helpers/build-dynamic-ref-map | buildDynamicRefMap | Build a map of $dynamicAnchor → resolved location. | | @amritk/helpers/resolve-dynamic-refs | resolveDynamicRefs | Replace $dynamicRef occurrences using the map above. | | @amritk/helpers/assert-id-scopes | assertIdScopes | Reject a document whose $id-scoped fragment ref resolves to nothing in its own resource. | | @amritk/helpers/max-schema-depth | MAX_SCHEMA_DEPTH, assertSchemaDepth | The nesting cap every recursive walker enforces. | | @amritk/helpers/upgrade-draft07-schema | upgradeDraft07Schema, isDraft07Schema | Upgrade a Draft-07 schema to 2020-12. | | @amritk/helpers/ref-to-filename | refToFilename, toKebabCase | Convert a $ref to a stable filename. | | @amritk/helpers/ref-to-name | refToName | Convert a $ref to a TypeScript identifier (PascalCase). | | @amritk/helpers/walk-ref-graph | walkRefGraph, RefNode | The shared $ref-graph traversal every generator runs: upgrades draft-07, resolves each ref, rewrites $dynamicRef, derives type/file names, and hands one pre-computed node per output file to a visit callback. | | @amritk/helpers/build-resource-registry | buildResourceRegistry, ResourceRegistry | Read a document's $id base-URI scopes once, expressed as JSON Pointers. | | @amritk/helpers/normalize-ref-scopes | normalizeRefScopes | Rewrite every $ref / $dynamicRef to a plain root-relative JSON Pointer, applying the $id bases in scope. | | @amritk/helpers/resolve-scoped-ref | resolveScopedRef, ScopedRefTarget | Where a $ref lands once the $id bases in scope are applied. | | @amritk/helpers/graft-external-schemas | graftExternalSchemas, GraftedSchema | Fold already-loaded external documents into the document being generated so cross-document refs resolve like local ones. | | @amritk/helpers/prune-external-schemas | pruneExternalSchemas | Drop the grafted documents nothing references. | | @amritk/helpers/extract-dynamic-anchor-defs | extractDynamicAnchorDefs | Collect a #/... ref for every subschema carrying a $dynamicAnchor. | | @amritk/helpers/fold-nullable | foldNullable | Rewrite OpenAPI 3.0 nullable: true into a null member of type. | | @amritk/helpers/referenced-conditional | referencedConditional | The if/then definition an allOf member's local $ref points at, so the type emitter and the import collectors agree on what gets inlined. | | @amritk/helpers/derive-root-type-name | deriveRootTypeName | Turn a schema title into a PascalCase root type name. | | @amritk/helpers/read-key | readKey, declaresKey | Read an author-chosen name ($defs entry, config key) off a map, treating inherited names such as __proto__ as absent. | | @amritk/helpers/assign-key | assignKey | Assign a key on a rebuilt object without letting __proto__ reach the prototype setter. | | @amritk/helpers/schema-guards | isSchemaObject, hasType, hasProperties, hasOneOf, hasAnyOf, hasAllOf, hasEnum, hasConst, hasPattern, hasFormat, hasDefault, hasExamples, hasRequired, hasItems, hasAdditionalProperties, hasMinLength, hasMaxLength, hasMinimum, hasMaximum, hasExclusiveMinimum, hasExclusiveMaximum, hasMultipleOf, hasMinItems, hasMaxItems, hasUniqueItems, hasMinProperties, hasMaxProperties, … | Type-narrowing predicates for JSON Schema keywords. |

Codegen utilities

| Subpath | Exports | Purpose | |:---|:---|:---| | @amritk/helpers/generate-type-definition | generateTypeDefinition | Render a TypeScript type from a schema node. | | @amritk/helpers/mjst-extension | MJST_EXTENSION_KEY, MjstExtension, hasMjstHint, getMjstInstanceOf, getMjstPrimitive, getMjstBrand, getMjstDiscriminator | Read the x-mjst vendor hints (instanceOf, primitive, brand) a schema carries, and the message discriminator an AsyncAPI channel names. | | @amritk/helpers/generate-index-barrel | generateIndexBarrel | Render the index.ts barrel that re-exports every generated file. A name starting with _ is for sibling files only and is left out. | | @amritk/helpers/identifier-mentions | identifierMentions | Ask whether emitted source names an identifier, ignoring comments, strings, and regex literals — decides which $ref imports a generated file keeps. | | @amritk/helpers/get-default-value | getDefaultValue | The fallback value (as source text) a parser or repairing validator substitutes for missing data: default > const > first enum > first usable examples entry > first union branch > pattern > type. default and examples are used only when they match the declared type. | | @amritk/helpers/generate-default-from-pattern | generateDefaultFromPattern | Build a fallback string that is guaranteed to match a pattern (and length bounds), or null. | | @amritk/helpers/unknown-keys-strategy | UnknownKeysStrategy, UNKNOWN_KEYS_STRATEGIES, DEFAULT_UNKNOWN_KEYS, isUnknownKeysStrategy | How a generated fast path proves a closed object has no extra key: 'count-keys' (default) or 'count-enumerable'. | | @amritk/helpers/escape-regex-pattern | escapeRegexPattern, regexFlagsFor, regexLiteral | Embed a JSON Schema pattern in a generated regex literal, validating it at generation time. | | @amritk/helpers/quote-js-string | quoteJsString | Quote a string as a JS literal, escaping only when needed. | | @amritk/helpers/multiple-of-check | multipleOfPassExpr, multipleOfFailExpr | Emit a multipleOf check that agrees with the runtime interpreter. | | @amritk/helpers/numeric-bound-check | boundPassExpr, boundFailExpr, boundOperator | Emit minimum / maximum / exclusive* checks that agree with the runtime interpreter. | | @amritk/helpers/string-length-check | minLengthPassExpr, maxLengthPassExpr, … | Emit minLength / maxLength checks that count code points, not UTF-16 units. | | @amritk/helpers/unknown-key-check | unknownKeyCheck, INLINE_KEY_LIMIT | Emit an unknown-key sweep — inline comparisons for small key sets, a hoisted Set past the limit. | | @amritk/helpers/parse-documentation | parseDocumentation, ObjectDocumentation | Parse one section of the OpenAPI specification markdown (selected by a commentUrl fragment such as #info-object) into a title, description, and per-property descriptions. | | @amritk/helpers/safe-accessor | safeAccessor, hasOwnCheck, missingCheck, safeKey | Emit a safe JS property-access expression (dot vs bracket notation, own-property guard for Object.prototype names). |

Runtime helpers (also copied into generated output)

| Subpath | Exports | Purpose | |:---|:---|:---| | @amritk/helpers/coercion-runtime | coerceScalar, coerceUnion, valuesEqual, allUnique, everyItem, escapePointer | The validator's coercion and matching runtime, byte-identical to the copy in a validator build's validation-result.ts, for a coercing parser that has to agree with coerceX. | | @amritk/helpers/is-object | isObject | Narrow unknown → Record<string, unknown>. | | @amritk/helpers/has-ref | hasRef | Narrow a value to an object carrying a string $ref. | | @amritk/helpers/validate-array | validateArray | Validate array shape and items. | | @amritk/helpers/validate-record | validateRecord | Validate record shape and additional properties. |

Usage

import { resolveRef } from '@amritk/helpers/resolve-ref'
import { isObjectSchema, hasProperties } from '@amritk/helpers/schema-guards'

const node = resolveRef('#/$defs/info', rootSchema)

if (isObjectSchema(node) && hasProperties(node)) {
  for (const [name, property] of Object.entries(node.properties)) {
    // ...
  }
}

Most helpers have a colocated test file (*.test.ts) — read those for canonical examples.

Related packages

• @amritk/validation — primary consumer
• @amritk/mjst — the CLI surface

License

MIT