IF Commons GitHub

types

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-workspace-model FR-006

The branded types of Intellectual Frontiers Workspaces (commons 0002-workspace-model FR-006 to FR-012): a Git host's name, a path segment that is valid on Linux, macOS and Windows alike, a path of the workspace, a branch, a commit and a pinned version are each a type of their own, made only by the function that refuses what it should, so that an unchecked string never reaches the layout or the plan.

PortableSegment and RepoPath are made in portable.ts; the others are made here. A refusal is a Result whose error says what is wrong and names the text, never a throw.

Source: commons/ergonex/src/types.ts

6 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.

BranchNametype
type BranchName = Brand<string, "BranchName">;

A branch's name, by the rules of git check-ref-format --branch.

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

branchNamefunction
function branchName(text: string): Result<BranchName, BrandError>

A branch's name, by the rules of Git's ref names (git check-ref-format): no control character, space, ~ ^ : ? * [ \, .. or @{, no component that starts with . or ends in .lock, and no start with -.

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

BrandErrortypeno test imports it
type BrandError =
  | {
      readonly kind: "git-host";
      readonly text: string;
      readonly reason: string;
    }
  | {
      readonly kind: "branch-name";
      readonly text: string;
      readonly reason: string;
    }
  | { readonly kind: "sha"; readonly text: string }
  | {
      readonly kind: "version";
      readonly text: string;
      readonly reason: string;
    };

A text refused as a type of this module, and why.

describeBrandErrorfunctionno test imports it
function describeBrandError(e: BrandError): string

A refusal as one sentence.

GitHosttypeno test imports it
type GitHost = Brand<string, "GitHost">;

A Git host's name in lower case, as the first folder of a repository's path (github.com).

gitHostfunction
function gitHost(text: string): Result<GitHost, BrandError>

A Git host's name: letters, digits, -, _ and . between labels, lower-cased; no port, no scheme, no credential.

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

PortableSegmenttypeno test imports it
type PortableSegment = Brand<string, "PortableSegment">;

One name in a path, valid on every operating system (made only by segment in portable.ts).

RepoPathtype
type RepoPath = Brand<string, "RepoPath">;

A path of the workspace below its root: portable segments with / between them, never absolute and never holding .. (made only by repoPath in portable.ts).

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

Shatypeno test imports it
type Sha = Brand<string, "Sha">;

A commit's object id: 40 (SHA-1) or 64 (SHA-256) lower-case hexadecimal digits.

shafunction
function sha(text: string): Result<Sha, BrandError>

A commit id.

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

Versiontypeno test imports it
type Version = Brand<string, "Version">;

A pinned version of a tool: major.minor.patch with an optional pre-release and build, never latest and never a range.

versionfunction
function version(text: string): Result<Version, BrandError>

A pinned version: a semantic version with no v and nothing around it, so latest, 1.x, ^1.2.0, >=1 and v1.2.3 are refused (0002-workspace-model FR-037).

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

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