IF Commons GitHub

family

Written to: 4 requirements: 4 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-kanon-checker FR-005, 0001-kanon-checker FR-010, 0001-kanon-checker FR-011, 0001-kanon-checker FR-004

The family of a Kanon library (commons 0033-kanon FR-021): the naming rule of the packages that extend a host, as data of the host's table, and the names that rule makes and reads. A host @scope/archon has dialects @scope/archon-dialect-<tool> and plugins @scope/archon-<noun>; the rule is two templates, never a pattern in a program.

Parse, don't validate: an instance name, a plugin noun and a template are branded types made only by their smart constructors, so a function that takes one never checks it again. The name of a member is derived from the rule (memberPackage), never written twice, and read back by classify, which returns one case of the closed union Member; a dialect is tried before a plugin, so a noun that would read as a dialect (dialect-x) is not a plugin, and memberPackage refuses it.

import { classify, parseNameTemplate, parsePackageName } from "@intellectual-frontiers/kanon";

Source: commons/kanon/src/family.ts

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

classifyfunction
function classify(rule: FamilyRule, host: PackageName, candidate: string): Member | undefined

What a package name is in the host's family: the host itself, a dialect, a plugin, or none of them (undefined). A dialect is tried before a plugin.

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

FamilyRuletypeno test imports it
type FamilyRule = {
  readonly dialect: NameTemplate;
  readonly plugin: NameTemplate;
  /** The subpath of the host's `exports` that is the plugin contract (`./plugin`): each plugin imports it, and the host exports it. */
  readonly contract?: string;
  /** Whose scope a member may be of: `own` (the host's, where absent) or `any` (0033-kanon FR-027). */
  readonly scope?: "own" | "any";
};

The naming rule of a family, as data (0033-kanon FR-021): a template for the dialects and one for the plugins, and optionally the export of the host that defines what a plugin is.

InstanceNametype
type InstanceName = Brand<string, "kanon instance name">;

The name of one dialect of a host, as ansible: made only by parseInstanceName.

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

Membertypeno test imports it
type Member =
  | { readonly kind: "host" }
  | { readonly kind: "dialect"; readonly name: InstanceName }
  | { readonly kind: "plugin"; readonly noun: PluginNoun };

What a package of a family is: a closed union.

memberPackagefunction
function memberPackage(rule: FamilyRule, host: PackageName, member: { readonly kind: "dialect"; readonly name: InstanceName; } | { readonly kind: "plugin"; readonly noun: PluginNoun; }): Result<PackageName, string>

The package of a member of the host's family, from the rule: the one way a member's package name is made. A plugin whose noun would read as a dialect is refused.

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

NameTemplatetypeno test imports it
type NameTemplate = Brand<string, "kanon name template">;

A template of the name of a family's packages, with {host} and {name} once each: made only by parseNameTemplate.

parseInstanceNamefunction
function parseInstanceName(text: string): Result<InstanceName, string>

An instance name from text, or why the text is not one.

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

parseNameTemplatefunctionno test imports it
function parseNameTemplate(text: string): Result<NameTemplate, string>

A name template from text, or why the text is not one: it holds {host} once and {name} once, and lower-case letters, digits and hyphens.

parsePluginNounfunction
function parsePluginNoun(text: string): Result<PluginNoun, string>

A plugin noun from text, or why the text is not one.

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

PluginNountypeno test imports it
type PluginNoun = Brand<string, "kanon plugin noun">;

The noun of one plugin of a host, as server: made only by parsePluginNoun.

rootPackagefunctionno test imports it
function rootPackage(specifier: string): string

The package an import specifier names: @scope/name/sub is @scope/name.

splitPackagefunctionno test imports it
function splitPackage(name: string): { readonly scope: string; readonly base: string; }

The scope of a package name (@scope/, or empty) and its base.

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