IF Commons GitHub

logical/ports

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0003-integrations-logical FR-001, 0003-integrations-logical FR-002, 0003-integrations-logical FR-003

The ports of Integrations (commons integrations 0003-integrations-logical): typed interfaces, each a record of functions, that the pure cores are written against and the physical layer implements. The credential port hands out a Secret that cannot be printed; the read port can only read, so that the read-only contract of a connector is held by its type; the clock and the trace are ports too, so that no core reads the time or writes a line.

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

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

Jsontype
type Json = null | boolean | number | string | readonly Json[] | { readonly [key: string]: Json };

What JSON can say.

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

Secrettypeno test imports it
type Secret = { readonly reveal: () => string; readonly toJSON: () => string; readonly toString: () => string };

A secret that cannot be printed, logged or serialized by accident: it says [secret] however it is turned into text, and gives its value only to reveal.

SECRET_MASKconst
const SECRET_MASK: "[secret]"

The text a secret shows.

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

secretOffunction
function secretOf(value: string): Secret

A secret holding a value.

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

CredentialErrortypeno test imports it
type CredentialError = { readonly kind: "missing"; readonly ref: CredentialRef } | { readonly kind: "denied"; readonly ref: CredentialRef } | { readonly kind: "vault-unavailable" };

Why a credential cannot be given.

CredentialPorttypeno test imports it
type CredentialPort = { readonly resolve: (ref: CredentialRef) => Promise<Result<Secret, CredentialError>> };

The credential port: a reference to a vault store in, a secret out; nothing else can make a credential.

ReadFailuretypeno test imports it
type ReadFailure = | { readonly kind: "denied"; readonly subject: string } | { readonly kind: "not-found"; readonly … (402 characters)
type ReadFailure =
  | { readonly kind: "denied"; readonly subject: string }
  | { readonly kind: "not-found"; readonly subject: string }
  | { readonly kind: "rate-limited"; readonly subject: string }
  | { readonly kind: "server"; readonly subject: string; readonly status: number }
  | { readonly kind: "network"; readonly subject: string }
  | { readonly kind: "decode"; readonly subject: string };

Why a read failed; the subject is a path of the system and never a payload.

ReadPorttypeno test imports it
type ReadPort = {
  readonly get: (path: string) => Promise<Result<Json, ReadFailure>>;
  readonly pages: (path: string) => AsyncGenerator<Json, Result<number, ReadFailure>>;
};

The read port of a system: one document, or every item of a paged list. There is no way to write through it.

Clocktypeno test imports it
type Clock = { readonly now: () => Instant };

The clock port.

TraceEventtypeno test imports it
type TraceEvent = | { readonly kind: "observe-started"; readonly connector: string } | { readonly kind: "observe-fin… (409 characters)
type TraceEvent =
  | { readonly kind: "observe-started"; readonly connector: string }
  | { readonly kind: "observe-finished"; readonly connector: string; readonly assets: number; readonly records: number; readonly gaps: number }
  | { readonly kind: "exchange-step"; readonly exchange: string; readonly step: string }
  | { readonly kind: "finding-counted"; readonly level: string; readonly count: number };

What a run tells while it works: only identities, counts and codes, never a payload (commons integrations 0003-integrations-logical FR-003).

Tracetypeno test imports it
type Trace = (event: TraceEvent) => void;

Where trace events go.

isObjectfunctionno test imports it
function isObject(j: Json | undefined): j is { readonly [key: string]: Json; }

Whether a JSON value is an object (not null, not an array): a guard that narrows it to one.

memberfunctionno test imports it
function member(j: Json | undefined, key: string): Json | undefined

The member of a JSON object, or undefined where it is not an object or has none.

textOffunctionno test imports it
function textOf(j: Json | undefined, key: string): string | undefined

The text of a member, or undefined where it is not a text.

flagOffunctionno test imports it
function flagOf(j: Json | undefined, key: string): boolean | undefined

The boolean of a member, or undefined where it is not one.

numberOffunctionno test imports it
function numberOf(j: Json | undefined, key: string): number | undefined

The number of a member, or undefined where it is not one.

NO_TRACEconstno test imports it
const NO_TRACE: Trace

A trace that goes nowhere.

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