IF Commons GitHub

physical/views

Written to: 4 requirements: 4 proved, 0 partly, 0 failing, 0 with no test recorded. 0005-evidence-capture-views FR-002, 0005-evidence-capture-views FR-003, 0005-evidence-capture-views FR-004, 0005-evidence-capture-views FR-005

Reading back what was captured (0005-evidence-capture-views): the structured difference of the state of an asset between two revisions, what changed over a period, what was known at an instant and whether the journal holds. They read the branch of Git that the policy names through its store; what a state is, and how two states differ, is the caller's (a codec), so that this library knows no kind of machine.

import { verifyJournalOf } from "./views.ts";
// await verifyJournalOf(store, policy.branch)

Source: commons/evidence-capture/src/physical/views.ts

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

physical.StateCodectypeno test imports it
type StateCodec<S, D> = { readonly read: (text: string) => S | undefined; readonly diff: (a: S, b: S) => D };

How the states kept on the branch are read and compared: read gives the state a file's text holds (nothing where it does not), and diff the difference of two.

physical.Diffedtypeno test imports it
type Diffed<D> = { readonly asset: string; readonly from: { readonly commit: string; readonly at: string }; readonly to: { readonly commit: string; readonly at: string }; readonly diff: D };

What diffAsset found: the two states compared (with their instants) and what differs.

physical.diffAssetfunctionno test imports it
function diffAsset<S, D>(store: GitRefStore, branch: string, codec: StateCodec<S, D>, asset: string, o: { readonly from: string; readonly to: string; readonly since: string; readonly now: string; }): Promise<Result<Diffed<D> | undefined, string>>

The structured difference of the state of an asset between two revisions (commits or instants). With none given it is the last change: the state before the newest and the newest. since compares the state at now minus a span with the newest. Nothing to compare (the asset has been kept once or never) is undefined.

physical.Changetypeno test imports it
type Change<D> = { readonly asset: string; readonly at: string; readonly commit: string; readonly first: boolean; readonly diff: D | undefined };

One change of the state of an asset.

physical.changesSincefunctionno test imports it
function changesSince<S, D>(store: GitRefStore, codec: StateCodec<S, D>, o: { readonly since: string; readonly now: string; }): Promise<Result<readonly Change<D>[], string>>

The changes of every asset's state since an instant (or all), newest first, each with its structured difference from the state before.

physical.Knowntypeno test imports it
type Known<S> = { readonly asset: string; readonly state: S | undefined; readonly lastLookAt: string | undefined; readonly lastLook: string | undefined; readonly ageMs: number | undefined };

What was known of an asset at an instant: the state kept then, when it was last looked at, and how that look ended.

physical.knownAtfunctionno test imports it
function knownAt<S, D>(store: GitRefStore, codec: StateCodec<S, D>, at: string): Promise<Result<{ readonly commit: string | undefined; readonly assets: readonly Known<S>[]; }, string>>

What was known at an instant: the state of each asset as the branch held it then, and the last look at it that the journal holds up to then.

physical.verifyJournalOffunctionno test imports it
function verifyJournalOf(store: GitRefStore, branch: string): Promise<Result<{ readonly entries: number; readonly head: string | undefined; readonly branch: string; }, string>>

Whether the journal of the branch holds: its entries and its head, or the first entry that does not follow.

physical.askJournalfunctionno test imports it
function askJournal(store: GitRefStore, branch: string, sql: string, options?: QueryOptions): Promise<Result<Answer, string>>

One read-only question of the journal of the branch (0006-evidence-capture-query FR-004): the journal is read through the store, which verifies its chain, and a branch that does not exist says that nothing was captured.

StateCodectype
type StateCodec<S, D> = { readonly read: (text: string) => S | undefined; readonly diff: (a: S, b: S) => D };

How the states kept on the branch are read and compared: read gives the state a file's text holds (nothing where it does not), and diff the difference of two.

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

Diffedtypeno test imports it
type Diffed<D> = { readonly asset: string; readonly from: { readonly commit: string; readonly at: string }; readonly to: { readonly commit: string; readonly at: string }; readonly diff: D };

What diffAsset found: the two states compared (with their instants) and what differs.

diffAssetfunction
function diffAsset<S, D>(store: GitRefStore, branch: string, codec: StateCodec<S, D>, asset: string, o: { readonly from: string; readonly to: string; readonly since: string; readonly now: string; }): Promise<Result<Diffed<D> | undefined, string>>

The structured difference of the state of an asset between two revisions (commits or instants). With none given it is the last change: the state before the newest and the newest. since compares the state at now minus a span with the newest. Nothing to compare (the asset has been kept once or never) is undefined.

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

Changetypeno test imports it
type Change<D> = { readonly asset: string; readonly at: string; readonly commit: string; readonly first: boolean; readonly diff: D | undefined };

One change of the state of an asset.

changesSincefunction
function changesSince<S, D>(store: GitRefStore, codec: StateCodec<S, D>, o: { readonly since: string; readonly now: string; }): Promise<Result<readonly Change<D>[], string>>

The changes of every asset's state since an instant (or all), newest first, each with its structured difference from the state before.

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

Knowntypeno test imports it
type Known<S> = { readonly asset: string; readonly state: S | undefined; readonly lastLookAt: string | undefined; readonly lastLook: string | undefined; readonly ageMs: number | undefined };

What was known of an asset at an instant: the state kept then, when it was last looked at, and how that look ended.

knownAtfunction
function knownAt<S, D>(store: GitRefStore, codec: StateCodec<S, D>, at: string): Promise<Result<{ readonly commit: string | undefined; readonly assets: readonly Known<S>[]; }, string>>

What was known at an instant: the state of each asset as the branch held it then, and the last look at it that the journal holds up to then.

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

verifyJournalOffunction
function verifyJournalOf(store: GitRefStore, branch: string): Promise<Result<{ readonly entries: number; readonly head: string | undefined; readonly branch: string; }, string>>

Whether the journal of the branch holds: its entries and its head, or the first entry that does not follow.

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

askJournalfunction
function askJournal(store: GitRefStore, branch: string, sql: string, options?: QueryOptions): Promise<Result<Answer, string>>

One read-only question of the journal of the branch (0006-evidence-capture-query FR-004): the journal is read through the store, which verifies its chain, and a branch that does not exist says that nothing was captured.

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

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