IF Commons GitHub

logical/plugin

Written to: 4 requirements: 4 proved, 0 partly, 0 failing, 0 with no test recorded. 0008-integrations-plugins FR-001, 0008-integrations-plugins FR-002, 0008-integrations-plugins FR-003, 0008-integrations-plugins FR-004

The plugin contract of standards (commons integrations 0008-integrations-plugins): a standard is a package that gives the library a codec (parse and serialize one syntax to the abstract tree) and loaders (read the machine-readable definitions of schemas, profiles and terminologies from data the user supplies or the issuer publishes), behind typed ports, and registers its standards with their licences. The library embeds none of any standard.

Source: commons/integrations/src/logical/plugin.ts

5 of 14 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

SyntaxCodetypeno test imports it
type SyntaxCode = "empty" | "bad-envelope" | "bad-delimiter" | "bad-character" | "bad-structure" | "unbalanced" | "too-long" | "unexpected-end";

Why a text is not of a syntax: a code and an offset, never the text.

SyntaxProblemtypeno test imports it
type SyntaxProblem = { readonly kind: "syntax"; readonly code: SyntaxCode; readonly offset: number };

A problem of the first level of validation: the offset at which the text could not be read.

Codectypeno test imports it
type Codec = {
  readonly syntax: Ref<"syntax">;
  readonly parse: (text: string) => Result<Interchange, SyntaxProblem>;
  readonly serialize: (i: Interchange) => Result<string, SyntaxProblem>;
};

The codec port of one syntax: parse a text to the tree and serialize the tree to a text.

Suppliedtypeno test imports it
type Supplied = { readonly origin: Source; readonly standard: StandardUrn; readonly text: string };

What a loader is given: where the text came from, which standard it defines and the text.

LoadErrortypeno test imports it
type LoadError =
  | { readonly kind: "source-not-allowed"; readonly standard: StandardUrn; readonly origin: Source }
  | { readonly kind: "malformed"; readonly standard: StandardUrn; readonly code: "not-json" | "not-xml" | "wrong-resource" | "no-elements" }
  | { readonly kind: "unknown-standard"; readonly standard: StandardUrn };

Why a definition is not loaded.

Definitionstypeno test imports it
type Definitions = { readonly schemas: readonly Schema[]; readonly profiles: readonly Profile[]; readonly terminologies: readonly Terminology[] };

What a definition gives.

Loadertype
type Loader = { readonly standard: StandardUrn; readonly load: (supplied: Supplied) => Result<Definitions, LoadError> };

The loader port: a definition in, schemas, profiles and terminologies out.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

AckPorttypeno test imports it
type AckPort = {
  readonly acknowledge: (received: Interchange, status: "accepted" | "accepted-with-errors" | "rejected") => Result<Interchange, SyntaxProblem>;
  readonly read: (i: Interchange) => Result<readonly Acknowledgement[], SyntaxProblem>;
};

The port that makes and reads the acknowledgements of a standard.

StandardsPlugintypeno test imports it
type StandardsPlugin = {
  readonly id: string;
  readonly standards: readonly Standard[];
  readonly codec: Codec;
  readonly loaders: readonly Loader[];
  readonly acks: AckPort | undefined;
};

A plugin: the standards it registers and the ports it gives.

PluginRegistrytype
type PluginRegistry = ReadonlyMap<StandardUrn, StandardsPlugin>;

Plugins by the urn of the syntax they parse.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

PluginErrortypeno test imports it
type PluginError =
  | { readonly kind: "syntax-taken"; readonly urn: StandardUrn; readonly by: string }
  | { readonly kind: "no-such-standard"; readonly urn: StandardUrn }
  | { readonly kind: "loader-for-unlisted"; readonly urn: StandardUrn };

Why a plugin is not registered.

registerPluginfunction
function registerPlugin(reg: PluginRegistry, p: StandardsPlugin): Result<PluginRegistry, PluginError>

The registry with a plugin: its codec's syntax must be one of its standards at the level syntax, and each loader's standard one of its own.

Imported by 13 tests of the run (13 passed, 0 failed): the library's results

loadFromfunction
function loadFrom(plugin: StandardsPlugin, supplied: Supplied): Result<Definitions, LoadError>

A definition taken from a source only where the licence of its standard lets that source be used.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

detectfunction
function detect(reg: PluginRegistry, text: string): Result<{ readonly plugin: StandardsPlugin; readonly tree: Interchange; }, SyntaxProblem>

The first plugin that parses a text, with its tree: the syntaxes are tried in the order of the registry.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.