Omnist

Appearance

API reference ​

Looking for the complete generated TypeDoc documentation? See the TypeDoc API Reference (opens in a new tab). (VitePress's client-side router intercepts same-page <a> clicks regardless of a plain target="_self" attribute -- confirmed empirically: the top nav's "TypeDoc" link, the sidebar's, and this page's own prev/next pager link to the same URL all still get swallowed by the router when clicked from within rendered page content, even though the top-nav item itself (a different Vue component, not routed through content-click interception) does work with target="_self". target="_blank" reliably bypasses this everywhere, since opening a new tab is native browser behavior no SPA router can intercept.)

Every public name exported from @omnist-dev/omnist (see src/index.ts), grouped by area, with signatures. This mirrors the Python package's __all__ -- see layout.md for which src/*.ts module owns each group.

Errors ​

  • class OmnistError extends Error -- the base of every error this library throws.
  • class SchemaError extends OmnistError -- code?: string and path?: string are populated for osd.ts's lexical/tokenization errors (the parse.* family, omnist-spec Sec8.3.1, extended by spec#46 to cover OSD's own lexing stage), with a line:col path (Sec8.4). Every other throw site leaves both undefined.
  • class ParseError extends OmnistError -- code?: string and path?: string are populated for oml.ts's lexer/parser errors (the parse.* family, omnist-spec Sec8.3.1), with a line:col path (Sec8.4). Ten of the eleven parse.* codes are reachable from OML's grammar; parse.separator-in-array is not (see src/oml.ts's file-top comment). Every other throw site leaves code undefined -- some (invalid DATE/TIME/DATETIME literal values) still carry a path, since the position is always known there even without a code. The resource limits are coded: document.limit.depth and document.limit.nodes at $, and document.limit.int-digits at the integer literal's Document path (spec E-4a); every reader takes maxDepth, maxNodes and maxIntDigits to set them. A YAML !!omap, !!pairs or !!set is a ParseError with code format.tag-forbidden and path $ (C-13).
  • class WriteError extends OmnistError
  • class DocumentError extends OmnistError -- code?: string and path?: string; the YAML alias expansion limit (D-18/D-20) throws it with code document.limit.alias-expansion and path $, and the YAML expanded-size limit (D-22) with code document.limit.expanded-size and path $.
  • class DetachedNode extends OmnistError
  • class UnsafeXMLWarning extends OmnistError
  • type OmnistIssue -- the shape of a single validation/lint finding.

Documents ​

  • class Doc -- a guarded wrapper around a Node.
    • static of(value: unknown): Doc
    • constructor(node: Node, path?: string)
    • get isLeaf(): boolean
    • get value(): Scalar
    • edges(): Array<[string, Doc]>
    • labels(): string[]
    • get(label: string): Doc[]
    • getOne(label: string): Doc
    • count(label: string): number
    • child(label: string): Doc
    • add(label: string, value: unknown): Doc
    • remove(label: string): Doc
    • set(label: string, value: unknown): Doc
    • toData(): Node
    • toGrouped(): unknown
    • equals(other: unknown): boolean
  • function doc(value: unknown): Doc -- builds a Doc from a plain JS value, or passes an existing Doc through.
  • type Node = Scalar | Edge[]
  • type Edge = { label: string; target: Node }
  • type Scalar = string | number | boolean | Date | null

Schema model ​

  • class Schema -- a root RefType plus an environment of named Records.
    • constructor(root: RefType, env?)
    • readonly root: RefType
    • readonly env: ReadonlyMap<string, Record>
    • resolve(type: FieldType): Record | ScalarType | AnyFieldType
    • validate(d: Doc): ValidationResult
    • validates(d: Doc): boolean
    • compatibleWith(other: Schema): boolean
    • equivalent(other: Schema): boolean
    • normalize(): Schema
    • prune(): Schema
    • isEmpty(): boolean
  • function schema(root: RefType | string, env?): Schema
  • function record(...fields: Field[]): Record
  • function field(label: string, type: FieldType, min?: number, max?: number | null): Field
  • function ref(name: string): RefType
  • function nullable(scalarType: ScalarType | AnyFieldType): ScalarType
  • const t: { string, integer, number, boolean, date, time, datetime } -- the seven pre-built ScalarTypes.
  • const ANY: AnyFieldType
  • const SCALAR_KINDS: readonly ScalarKind[]
  • function cardinalityStr(f: Field): string
  • function recordField(rec: Record, label: string): Field | undefined
  • function fieldTypeEquals(a, b): boolean
  • function recordEquals(a, b): boolean
  • function schemaEquals(a, b): boolean
  • function matchesKind(value: unknown, name: ScalarKind): boolean
  • function valueKind(v: unknown): ScalarKind
  • function validationResultToString(res: ValidationResult): string
  • Types: ScalarKind, FieldType, ScalarType, RefType, AnyFieldType, Field, Record, ValidationResult.

OSD ​

  • function parseSchema(text: string): Schema
  • function toOsd(schema: Schema, opts?: ToOsdOptions): string
  • type ToOsdOptions

Operations ​

  • function infer(samples: readonly unknown[], options?: InferOptions): Schema
  • function inferWithReport(samples, options?): { schema: Schema; report: AnyFallback[] }
  • type InferOptions = { rootName?: string; allowAny?: boolean }
  • type AnyFallback
  • function materialize(node: Node, schema: Schema): Node -- schema-directed deserialization (upgrades value-exact leaves to match the schema).
  • function lint(s: Schema): LintFinding[]
  • type LintFinding
  • Schema.prototype.compatibleWith(other) / .equivalent(other) / .normalize() / .prune() / .isEmpty() -- the schema-comparison and -reduction operations. Package exports only publish the top-level @omnist-dev/omnist module (see package.json), so extract, isomorphic, and the standalone ops/* functions these methods delegate to are internal implementation detail, not public API, in this release.

Formats ​

Every format module exports the same three-function shape:

  • readJson(text, opts?: ReadJsonOptions): Node / writeJson(node, opts?: WriteJsonOptions): string / checkJson(node): WriteReport
  • readOml(text, opts?): Node / writeOml(node, opts?: WriteOmlOptions): string / checkOml(node): WriteReport
  • readXml(text, opts?: ReadXmlOptions): Node / writeXml(node, opts?: WriteXmlOptions): string / checkXml(node): WriteReport
  • readToml(text, opts?: ReadTomlOptions): Node / writeToml(node, opts?: WriteTomlOptions): string / checkToml(node): WriteReport
  • readYaml(text, opts?: ReadYamlOptions): Node (ReadYamlOptions.maxAliasExpansion: the D-18 maximum expansion factor, default DEFAULT_MAX_ALIAS_EXPANSION = 50, at most MAX_RECOMMENDED_ALIAS_EXPANSION = 10000) / writeYaml(node, opts?: WriteYamlOptions): string / checkYaml(node): WriteReport

Every read* function takes maxInputBytes in its options (spec D-23): the largest input, in UTF-8 bytes, it reads at all. The default is DEFAULT_MAX_INPUT_BYTES = 64 MiB; an integer of at least 1, otherwise a RangeError. A larger input is refused with a ParseError whose code is document.limit.input-size and path is $, before anything is decoded or parsed; an input of exactly the maximum is accepted, and a leading byte-order mark counts. readFormat(name, text, opts?) reads with any registered format under the same limit, checking the size before a plugin reader runs. See Limitations.

Every read* function also takes the three universal safety limits of spec D-9 as options (DocumentLimits): maxDepth (default DEFAULT_MAX_DEPTH = 200, levels of node nesting counted from the Document root, which is level 1), maxNodes (DEFAULT_MAX_NODES = 1,000,000, the root included, a scalar leaf not) and maxIntDigits (DEFAULT_MAX_INT_DIGITS = 4,300, the decimal digits of an integer's value, D-28). Each is an integer of at least 1, otherwise a RangeError. A refusal carries code DEPTH_CODE / NODES_CODE (document.limit.depth, document.limit.nodes) at path $, or INT_DIGITS_CODE (document.limit.int-digits) at the integer literal's Document path. See Limitations.

Every write* and check* function throws WriteError (write.unsupported-value, at the Document path of the node holding the string) for a string value or edge label with no UTF-8 encoding, a lone surrogate (spec C-9), whatever strict says; checkOml is no longer always empty for that reason.

See Formats for the per-format mapping and caveats.

Adjustment reports ​

  • class WriteReport -- .adjustments: Adjustment[], .ok: boolean.
  • type Adjustment = { code: string; path: string; message: string; severity: Severity }
  • type Severity
  • function finishWrite(opts: FinishWriteOptions): WriteReport
  • type FinishWriteOptions

Format registry ​

  • function registerFormat(f: Format): void
  • function getFormat(name: string): Format
  • function formats(): string[]
  • type Format = { name: string; read; write; check }

Version ​

  • const VERSION = "0.0.1-alpha"