IF Commons GitHub

logical/ledger

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0006-integrations-exchange FR-013, 0006-integrations-exchange FR-014, 0006-integrations-exchange FR-015

The ledger port of exchange (commons integrations 0006-integrations-exchange): a typed record of functions, each returning a Result, with which a consumer keeps the trail of a load without the library knowing where it is kept (a database, a file, memory). It appends stage events, checks the intake of a content by its hash, and records the outcome of a validation or an acknowledgement by code. A stage is an opaque branded text: the consumer's code list of stages lives with the consumer, not here. An event never carries a payload value: its fields are identifiers, a code, an instant and a digest, each made by a smart constructor that admits no free text.

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

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

LoadIdtypeno test imports it
type LoadId = Brand<string, "LoadId">;

The identity of one load, as the consumer names it.

Stagetypeno test imports it
type Stage = Brand<string, "Stage">;

A stage of the consumer's pipeline, an opaque code such as RECEIVED or VALIDATED.

OutcomeCodetypeno test imports it
type OutcomeCode = Brand<string, "OutcomeCode">;

A code that says why, or what came of a check: lower-case words joined by dashes.

ItemKeytypeno test imports it
type ItemKey = Brand<string, "ItemKey">;

The key that names the same item across loads (a message id, a control number): what two contents of one item share.

parseLoadIdconst
const parseLoadId: (t: string) => Result<LoadId, IdError>

A load id: letters, digits and . _ : -, up to 128. Free text is refused, and the refusal does not repeat it.

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

parseStageconst
const parseStage: (t: string) => Result<Stage, IdError>

A stage: upper-case words joined by underscores.

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

parseOutcomeCodeconst
const parseOutcomeCode: (t: string) => Result<OutcomeCode, IdError>

An outcome or reason code.

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

parseItemKeyconst
const parseItemKey: (t: string) => Result<ItemKey, IdError>

An item key.

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

LedgerEventtypeno test imports it
type LedgerEvent = { readonly loadId: LoadId; readonly stage: Stage; readonly reasonCode?: OutcomeCode; readonly at: Instant; readonly contentHash?: Sha256 };

One event of a load: a stage reached, with a reason code and a digest where there are any. Never a payload value.

IntakeRequesttypeno test imports it
type IntakeRequest = { readonly loadId: LoadId; readonly itemKey: ItemKey; readonly contentHash: Sha256; readonly at: Instant };

What a content is, on intake.

Intaketypeno test imports it
type Intake = { readonly kind: "first-seen" } | { readonly kind: "duplicate"; readonly of: LoadId } | { readonly kind: "conflict"; readonly with: LoadId };

What the ledger says of a content on intake: never seen; the same content seen before (in the load named); or another content of the same item (in the load named).

OutcomeKindtypeno test imports it
type OutcomeKind = "validation" | "acknowledgement";

Which check an outcome is of.

OutcomeRecordtypeno test imports it
type OutcomeRecord = { readonly loadId: LoadId; readonly kind: OutcomeKind; readonly code: OutcomeCode; readonly at: Instant };

The outcome of a check, by code.

LedgerErrortypeno test imports it
type LedgerError = { readonly kind: "unavailable" } | { readonly kind: "unknown-load"; readonly loadId: LoadId };

Why the ledger could not answer.

LedgerPorttype
type LedgerPort = { readonly append: (event: LedgerEvent) => Promise<Result<void, LedgerError>>; readonly intake: (r… (459 characters)
type LedgerPort = {
  readonly append: (event: LedgerEvent) => Promise<Result<void, LedgerError>>;
  readonly intake: (request: IntakeRequest) => Promise<Result<Intake, LedgerError>>;
  readonly outcome: (record: OutcomeRecord) => Promise<Result<void, LedgerError>>;
  readonly events: (loadId: LoadId) => Promise<Result<readonly LedgerEvent[], LedgerError>>;
  readonly outcomes: (loadId: LoadId) => Promise<Result<readonly OutcomeRecord[], LedgerError>>;
};

The ledger port.

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

memoryLedgerfunction
function memoryLedger(): LedgerPort

A ledger in memory.

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

LedgerFindingtypeno test imports it
type LedgerFinding = { readonly rule: string; readonly message: string };

What a ledger conformance finds wrong.

conformLedgerfunction
function conformLedger(make: () => LedgerPort, ids: { readonly load: (n: number) => LoadId; readonly stage: (name: string) => Stage; readonly code: (name: string) => OutcomeCode; readonly key: (n: number) => ItemKey; readonly hash: (n: number) => Sha256; readonly at: Instant; }): Promise<readonly LedgerFinding[]>

The conformance suite of a ledger: make gives a fresh, empty ledger each time. It finds a ledger that does not keep events in the order appended, that does not tell first-seen from duplicate from conflict, that accepts an outcome for a load it has no event of, or that does not keep outcomes. Any implementation (memory, a database) runs it.

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

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