IF Commons GitHub

versions/record

The typed record of a work (commons 0026-works-versioning FR-008, FR-013, FR-027, FR-028, FR-037): the file <work>/release.ts, whose only export is release, an object literal read as data and never run (kernel/ts-literal.ts, as 0020-ifccm reads a harness's declaration), so that a record at a past commit, read from Git, reads like the present one. The decoder, the checks of what a record says against its kind, and the template that writes it.

Pure: text in, data out. A field the record does not know and a field of the wrong type are errors that name the field. A tool writes a record only through releaseSource, which gives every record the same layout and the same order of fields, so that a diff of two records shows only what changed. The version of a record is text here; scheme.ts reads it by the scheme of the work's kind.

import { decodeReleaseSource, releaseSource } from "./record.ts";
const text = releaseSource({ slug: "lib", kind: "Library", title: "A library", authors: [{ name: "A. Person" }], version: "0.1.0" });
decodeReleaseSource(text).kind; // "ok"

Source: commons/mizan/src/versions/record.ts

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

versions.CITATION_FILEconstno test imports it
const CITATION_FILE: "CITATION.cff"

The name of a work's citation file (FR-024).

versions.decodeReleasefunctionno test imports it
function decodeRelease(input: unknown): Result<Release, RecordError>

A record decoded from data (FR-008): its fields, or the first that is unknown, of the wrong type or at odds with the kind.

versions.decodeReleaseSourcefunctionno test imports it
function decodeReleaseSource(source: string): Result<Release, RecordError>

The record read from the text of its file: export const release = { ... } and no other export, read as data and never run. A file that exports something else, or that holds a value that is not a literal, is an error that says so.

versions.kindProblemfunctionno test imports it
function kindProblem(r: Release): string | undefined

What a record says that its kind does not allow (FR-008, FR-012, FR-014): a version on a specification, none on another work, a snapshot on a work that is not data.

versions.RECORD_FIELDSconstno test imports it
const RECORD_FIELDS: readonly ["slug", "kind", "title", "authors", "version", "iri", "partOf", "position", "identifier", "repository", "exclude", "paths", "snapshot", "approval", "retention", "retired", "migratedFrom", "replaces"]

The fields a record may carry, in the order a template writes them.

versions.RECORD_FILEconstno test imports it
const RECORD_FILE: "release.ts"

The name of a record's file in a work's folder.

versions.releaseSourcefunctionno test imports it
function releaseSource(r: Release): string

The text of a record's file, by the one template (FR-008): the header, export const release = { ... };, fields in the order of RECORD_FIELDS, a newline at the end.

versions.slugOffunctionno test imports it
function slugOf(text: string): Slug | undefined

Text as a slug, or undefined where it is not lower-case letters, digits and single hyphens between them.

versions.Approvaltypeno test imports it
type Approval = { readonly approvedBy: string; readonly role: string; readonly on: Day; readonly decision: string };

The approval of a controlled document's revision (FR-013): a person, a role, a day and the Decision.

versions.Authortypeno test imports it
type Author = { readonly name: string };

One author: a name.

versions.Migrationtypeno test imports it
type Migration = { readonly scheme: Scheme; readonly firstVersion: string };

A change of scheme (FR-037): the scheme it came from and the first version of the new scheme.

versions.Releasetypeno test imports it
type Release = { readonly slug: Slug; readonly kind: WorkKind; readonly title: string; readonly authors: readonl… (1050 characters)
type Release = {
  readonly slug: Slug;
  readonly kind: WorkKind;
  readonly title: string;
  readonly authors: readonly Author[];
  /** Written by the scheme of the kind; absent for a specification (FR-014). */
  readonly version?: string;
  readonly iri?: string;
  readonly partOf?: Slug;
  readonly position?: number;
  readonly identifier?: string;
  readonly repository?: string;
  /** Paths of the folder that are not the work's files (FR-009). */
  readonly exclude?: readonly string[];
  /** Paths outside the folder, from the root of the repository, whose files are also the work's: a change there needs a new version too (FR-039). */
  readonly paths?: readonly string[];
  readonly snapshot?: Snapshot;
  readonly approval?: Approval;
  /** An ISO 8601 duration, from the release's day (FR-027). */
  readonly retention?: string;
  readonly retired?: readonly Retired[];
  readonly migratedFrom?: Migration;
  /** The slug of the work this one replaces, where it is a renamed or renumbered one (FR-007). */
  readonly replaces?: Slug;
};

The record of a work.

versions.Retiredtypeno test imports it
type Retired = {
  readonly version: string;
  readonly on: Day;
  readonly replacedBy?: string;
  readonly archivedOn?: Day;
  readonly bytesRemovedOn?: Day;
};

A retired version (FR-028): the day, what replaces it, the day it was archived and, once its bytes are gone, the day they were removed (the tombstone, FR-027).

versions.Slugtypeno test imports it
type Slug = Brand<string, "Slug">;

The slug of a work: lower-case letters, digits and hyphens, the prefix of its tags.

versions.Snapshottypeno test imports it
type Snapshot = { readonly digest: string; readonly schemaVersion: string; readonly schemaPaths?: readonly string[] };

The snapshot of a work of data (FR-012): the SHA-256 of the snapshot, the Semantic Version of its schema and, where named, the paths of the schema's files.

CITATION_FILEconstno test imports it
const CITATION_FILE: "CITATION.cff"

The name of a work's citation file (FR-024).

decodeReleasefunction
function decodeRelease(input: unknown): Result<Release, RecordError>

A record decoded from data (FR-008): its fields, or the first that is unknown, of the wrong type or at odds with the kind.

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

decodeReleaseSourcefunction
function decodeReleaseSource(source: string): Result<Release, RecordError>

The record read from the text of its file: export const release = { ... } and no other export, read as data and never run. A file that exports something else, or that holds a value that is not a literal, is an error that says so.

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

kindProblemfunctionno test imports it
function kindProblem(r: Release): string | undefined

What a record says that its kind does not allow (FR-008, FR-012, FR-014): a version on a specification, none on another work, a snapshot on a work that is not data.

RECORD_FIELDSconstno test imports it
const RECORD_FIELDS: readonly ["slug", "kind", "title", "authors", "version", "iri", "partOf", "position", "identifier", "repository", "exclude", "paths", "snapshot", "approval", "retention", "retired", "migratedFrom", "replaces"]

The fields a record may carry, in the order a template writes them.

RECORD_FILEconst
const RECORD_FILE: "release.ts"

The name of a record's file in a work's folder.

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

releaseSourcefunction
function releaseSource(r: Release): string

The text of a record's file, by the one template (FR-008): the header, export const release = { ... };, fields in the order of RECORD_FIELDS, a newline at the end.

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

slugOffunctionno test imports it
function slugOf(text: string): Slug | undefined

Text as a slug, or undefined where it is not lower-case letters, digits and single hyphens between them.

Approvaltypeno test imports it
type Approval = { readonly approvedBy: string; readonly role: string; readonly on: Day; readonly decision: string };

The approval of a controlled document's revision (FR-013): a person, a role, a day and the Decision.

Authortypeno test imports it
type Author = { readonly name: string };

One author: a name.

Migrationtypeno test imports it
type Migration = { readonly scheme: Scheme; readonly firstVersion: string };

A change of scheme (FR-037): the scheme it came from and the first version of the new scheme.

Releasetype
type Release = { readonly slug: Slug; readonly kind: WorkKind; readonly title: string; readonly authors: readonl… (1050 characters)
type Release = {
  readonly slug: Slug;
  readonly kind: WorkKind;
  readonly title: string;
  readonly authors: readonly Author[];
  /** Written by the scheme of the kind; absent for a specification (FR-014). */
  readonly version?: string;
  readonly iri?: string;
  readonly partOf?: Slug;
  readonly position?: number;
  readonly identifier?: string;
  readonly repository?: string;
  /** Paths of the folder that are not the work's files (FR-009). */
  readonly exclude?: readonly string[];
  /** Paths outside the folder, from the root of the repository, whose files are also the work's: a change there needs a new version too (FR-039). */
  readonly paths?: readonly string[];
  readonly snapshot?: Snapshot;
  readonly approval?: Approval;
  /** An ISO 8601 duration, from the release's day (FR-027). */
  readonly retention?: string;
  readonly retired?: readonly Retired[];
  readonly migratedFrom?: Migration;
  /** The slug of the work this one replaces, where it is a renamed or renumbered one (FR-007). */
  readonly replaces?: Slug;
};

The record of a work.

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

Retiredtypeno test imports it
type Retired = {
  readonly version: string;
  readonly on: Day;
  readonly replacedBy?: string;
  readonly archivedOn?: Day;
  readonly bytesRemovedOn?: Day;
};

A retired version (FR-028): the day, what replaces it, the day it was archived and, once its bytes are gone, the day they were removed (the tombstone, FR-027).

Slugtypeno test imports it
type Slug = Brand<string, "Slug">;

The slug of a work: lower-case letters, digits and hyphens, the prefix of its tags.

Snapshottypeno test imports it
type Snapshot = { readonly digest: string; readonly schemaVersion: string; readonly schemaPaths?: readonly string[] };

The snapshot of a work of data (FR-012): the SHA-256 of the snapshot, the Semantic Version of its schema and, where named, the paths of the schema's files.

folderPathProblemfunctionno test imports it
function folderPathProblem(p: string): string | undefined

A path of the folder: relative, with /, no . or .., no trailing slash.

withVersionfunctionno test imports it
function withVersion(r: Release, version: string): Release

The record with its version replaced: the one change bump makes to a record besides the fields of the kinds that move with it.

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