IF Commons GitHub

physical/source

Written to: 1 requirement: 0 proved, 0 partly, 0 failing, 1 with no test recorded. 0004-planning-sources FR-002

What a source is (0037-planning FR-013, FR-030, FR-032): a typed lens over one kind of place with a name, its capabilities and a place; acquire reads the place and returns its observations and findings; preview gives the plan a patch would carry out; write carries a plan out and returns what the place now holds. defineSource makes one from a typed record and refuses a record that says one thing of what it can write and does another; applyPatch is the one way a patch reaches a source, a dry run unless it names the hash of the preview, refusing a hash that is not the plan's, and sending a patch the source cannot apply to the outbox.

import { defineSource } from "./source.ts";
// defineSource({ name: "table", place: "t", capabilities: ["read"], acquire })

Source: commons/planning/src/physical/source.ts

0 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.SourceProblemtypeno test imports it
type SourceProblem =
  | { readonly kind: "read"; readonly message: string }
  | { readonly kind: "conflict"; readonly path: string; readonly message: string }
  | { readonly kind: "unexpressed"; readonly reason: string }
  | { readonly kind: "refused"; readonly message: string };

Why a source could not read or write a place.

physical.SourceFindingtypeno test imports it
type SourceFinding = { readonly path: string; readonly message: string };

A thing a source could not read, and why: a finding, not a failure of the read.

physical.Acquiredtypeno test imports it
type Acquired = { readonly observations: readonly Observation[]; readonly findings: readonly SourceFinding[] };

What a read of a place gives: its observations, in a fixed order, and what it could not read.

physical.Sourcetypeno test imports it
type Source = { readonly name: string; readonly place: string; readonly capabilities: ReadonlySet<Capability>; a… (514 characters)
type Source = {
  readonly name: string;
  readonly place: string;
  readonly capabilities: ReadonlySet<Capability>;
  acquire(): Promise<Result<Acquired, SourceProblem>>;
  /** The plan a patch would carry out, or why this place cannot say it. Present when the source can write. */
  preview?(patch: Patch): Promise<Result<Plan, SourceProblem>>;
  /** Carries a plan out and returns what the place now holds. Present when the source can write. */
  write?(plan: Plan): Promise<Result<Acquired, SourceProblem>>;
};

A source: a lens over one kind of place.

physical.SourceRecordtypeno test imports it
type SourceRecord = {
  readonly name: string;
  readonly place: string;
  readonly capabilities: readonly Capability[];
  readonly acquire: Source["acquire"];
  readonly preview?: Source["preview"];
  readonly write?: Source["write"];
};

What a person gives to make a source.

physical.DefineProblemtypeno test imports it
type DefineProblem = { readonly kind: "write-mismatch"; readonly message: string } | { readonly kind: "bad-name"; readonly message: string };

Why a record is not a source.

physical.defineSourcefunctionno test imports it
function defineSource(record: SourceRecord): Result<Source, DefineProblem>

A source from a typed record: a record whose preview or write is present while its capabilities say it cannot write, or absent while they say it can, is refused.

physical.Appliedtypeno test imports it
type Applied =
  | { readonly kind: "dry-run"; readonly preview: Preview }
  | { readonly kind: "written"; readonly preview: Preview; readonly now: Acquired }
  | { readonly kind: "stale"; readonly given: string; readonly preview: Preview }
  | { readonly kind: "outbox"; readonly entry: OutboxEntry }
  | { readonly kind: "failed"; readonly problem: SourceProblem };

What applying a patch came to.

physical.applyPatchfunctionno test imports it
function applyPatch(source: Source, patch: Patch, at: Instant, hash?: string | undefined): Promise<Applied>

The one way a patch reaches a source. A patch for another source or place than the source's own is refused (a write needs an explicit target); a patch the source cannot apply, or that its place cannot say, is an outbox entry; otherwise the plan is made and the write is a dry run unless hash is the hash of its preview.

SourceProblemtypeno test imports it
type SourceProblem =
  | { readonly kind: "read"; readonly message: string }
  | { readonly kind: "conflict"; readonly path: string; readonly message: string }
  | { readonly kind: "unexpressed"; readonly reason: string }
  | { readonly kind: "refused"; readonly message: string };

Why a source could not read or write a place.

SourceFindingtypeno test imports it
type SourceFinding = { readonly path: string; readonly message: string };

A thing a source could not read, and why: a finding, not a failure of the read.

Acquiredtypeno test imports it
type Acquired = { readonly observations: readonly Observation[]; readonly findings: readonly SourceFinding[] };

What a read of a place gives: its observations, in a fixed order, and what it could not read.

Sourcetypeno test imports it
type Source = { readonly name: string; readonly place: string; readonly capabilities: ReadonlySet<Capability>; a… (514 characters)
type Source = {
  readonly name: string;
  readonly place: string;
  readonly capabilities: ReadonlySet<Capability>;
  acquire(): Promise<Result<Acquired, SourceProblem>>;
  /** The plan a patch would carry out, or why this place cannot say it. Present when the source can write. */
  preview?(patch: Patch): Promise<Result<Plan, SourceProblem>>;
  /** Carries a plan out and returns what the place now holds. Present when the source can write. */
  write?(plan: Plan): Promise<Result<Acquired, SourceProblem>>;
};

A source: a lens over one kind of place.

SourceRecordtypeno test imports it
type SourceRecord = {
  readonly name: string;
  readonly place: string;
  readonly capabilities: readonly Capability[];
  readonly acquire: Source["acquire"];
  readonly preview?: Source["preview"];
  readonly write?: Source["write"];
};

What a person gives to make a source.

DefineProblemtypeno test imports it
type DefineProblem = { readonly kind: "write-mismatch"; readonly message: string } | { readonly kind: "bad-name"; readonly message: string };

Why a record is not a source.

defineSourcefunctionno test imports it
function defineSource(record: SourceRecord): Result<Source, DefineProblem>

A source from a typed record: a record whose preview or write is present while its capabilities say it cannot write, or absent while they say it can, is refused.

Appliedtypeno test imports it
type Applied =
  | { readonly kind: "dry-run"; readonly preview: Preview }
  | { readonly kind: "written"; readonly preview: Preview; readonly now: Acquired }
  | { readonly kind: "stale"; readonly given: string; readonly preview: Preview }
  | { readonly kind: "outbox"; readonly entry: OutboxEntry }
  | { readonly kind: "failed"; readonly problem: SourceProblem };

What applying a patch came to.

applyPatchfunctionno test imports it
function applyPatch(source: Source, patch: Patch, at: Instant, hash?: string | undefined): Promise<Applied>

The one way a patch reaches a source. A patch for another source or place than the source's own is refused (a write needs an explicit target); a patch the source cannot apply, or that its place cannot say, is an outbox entry; otherwise the plan is made and the write is a dry run unless hash is the hash of its preview.

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