@formscript/loader

Include resolution for §4.15 of the specification, and the parameters of §4.16.

A document may name another document and merge it into itself. This package does that merge: it reads the documents an include names, splices their statements into the form that names them, and reports what it could not do.

The merge is a transformation of the tree, not of the text. Everything downstream — the scope, the dependency graph, the output projection, the render intents — reads the tree, so a module that is merged is a module the engine understands like any other part of the form.

Usage

import { resolveIncludes } from '@formscript/loader';
import { nodeResolver } from '@formscript/loader/node';

const { document, diagnostics, files, edges } = resolveIncludes(parsed, {
  path: '/forms/loan.forms',
  resolver: nodeResolver,
});

resolveIncludes takes a parsed document and returns a new one. The original is not modified.

What it does

The alias is a group because that is what an alias has to do: it introduces a data level, so the module's fields have the paths alias.name, and it opens a scope, so a reference the module makes to one of its own fields still resolves to that field.

The parameters

A module may declare parameters, and the form that includes it may give them values:

form address version = "1.0" {
  param street_label = "Street"

  field street {
    type  = string
    label = street_label
  }
}

include "./address.forms" as applicant with {
  street_label = "Address of applicant"
}

The value is substituted when the module is merged, so the merged form holds no parameter and is a form like any other: the same fields, the same validity states, the same error codes, the same output document.

Every value is a literal, or the name of a parameter of the including document. A value is written in the including form's scope and lands in the module's scope, and a literal has no scope, so it cannot be captured by a name the module happens to use.

The edges

edges is every include that was resolved: the document that wrote it, the document it names, the data path of the scope it was written in, and the alias when it had one. It is what a change-impact tool needs — the path is what says where the module's declarations land in the form that includes it.

{ from: '/forms/loan.forms', to: '/forms/address.forms', prefix: ['applicant'], alias: 'addr' }

What it reports

• E-REF-03 — the target could not be read;
• E-REF-04 — the documents include each other in a cycle, reported with the path of the cycle;
• E-BLOCK-01 — the included document declares something that may not be merged: an output block, a relation, a state, an action, a source. These declare the document rather than a part of it, and merging two of them would give one document two output schemas.
• E-REF-05 — the include supplies a name the included document does not declare as a parameter;
• E-REF-06 — a parameter has neither a supplied value nor a declared one;
• E-REF-07 — the name of a parameter is also used by another declaration or binding in the document that declares it;
• E-REF-08 — the value of a parameter is not a literal.

The diagnostics of a document that did not parse are the parser's own, and they stop the merge of that document.

Every statement that came from an included document carries the name of the file it came from, so a diagnostic inside a module names the module rather than the form that included it.

The resolver

The package reads no files itself. A SourceResolver says how a path becomes a canonical path and how a canonical path is read, so the merge can be driven by a file system, by a test, or by an editor holding its documents in memory.

@formscript/loader/node provides one over the file system. The resolver must give the same file the same canonical path every time, because a cycle is detected on the canonical path.

Public API

15 exported symbols.