IF Commons GitHub

logical/bisync

Written to: 4 requirements: 4 proved, 0 partly, 0 failing, 0 with no test recorded. 0004-bridge-twoway FR-001, 0004-bridge-twoway FR-002, 0004-bridge-twoway FR-003, 0004-bridge-twoway FR-004

A two-way sync against a base. The base is what the two sides agreed on the last time: for each path, the SHA-256 of its bytes. With it a change is told from a difference: a path that only one side changed goes to the other, a path both changed to the same bytes is agreed, and a path both changed differently is a conflict that a policy written as code decides (newer-wins, keep-both, or fail). A sync has no default base, and the bridge does not guess one: the caller gives a base or says seed, which agrees on what is equal, copies what is only on one side and leaves what differs to the policy, and deletes nothing. A change beats a delete, so that no data is lost to a deletion made without knowing of it.

import { emptyBase } from "./bisync.ts";
emptyBase.entries.size; // 0

Source: commons/anyfs-bridge/src/logical/bisync.ts

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

Basetype
type Base = { readonly entries: ReadonlyMap<Path, string> };

What the two sides agreed on: the SHA-256 of each path, in hex.

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

emptyBaseconst
const emptyBase: Base

A base that agrees on nothing.

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

Seedtypeno test imports it
type Seed = { readonly seed: "union" };

The first sync, said out loud: agree on what is equal, copy what is on one side only, delete nothing.

encodeBaseconst
const encodeBase: (base: Base) => readonly (readonly [string, string])[]

A base as pairs in the order of the paths, to keep it in a document.

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

decodeBasefunction
function decodeBase(pairs: readonly (readonly [string, string])[]): Result<Base, string>

A base from pairs, or why they are not one.

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

ConflictPolicytypeno test imports it
type ConflictPolicy = "newer-wins" | "keep-both" | "fail";

What decides a path both sides changed differently.

SideNametypeno test imports it
type SideName = "a" | "b";

The side of a sync.

BiOptionstype
type BiOptions = {
  readonly conflict: ConflictPolicy;
  /** Whether a delete made on one side reaches the other, and at most how many. */
  readonly deletes: DeletePolicy;
  readonly rails?: Pick<Rails, "include" | "exclude">;
  readonly cache?: DigestCache;
  readonly pageSize?: number;
};

How a two-way sync is planned.

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

BiActiontypeno test imports it
type BiAction = { readonly side: SideName; readonly rel: Path; readonly action: Action };

An action to make at one side: side is the side it changes. rel is the path of the base it concerns.

BiConflicttypeno test imports it
type BiConflict = { readonly rel: Path; readonly reason: "both-changed" | "no-time"; readonly detail: string };

A path the two sides cannot settle.

BiPlantype
type BiPlan = { readonly actions: readonly BiAction[]; readonly conflicts: readonly BiConflict[]; /** What was set… (527 characters)
type BiPlan = {
  readonly actions: readonly BiAction[];
  readonly conflicts: readonly BiConflict[];
  /** What was settled without an action: a path both sides have as the base says, or as each other. */
  readonly unchanged: number;
  /** What was decided by changing the other side, in words. */
  readonly resolved: readonly string[];
  readonly next: Base;
  /** The base the plan was made against: a path whose change does not succeed goes back to its entry here. */
  readonly prior: Base;
  readonly hash: PlanHash;
};

The plan of a two-way sync. next is the base once every action is made.

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

planBisyncfunction
function planBisync(a: Endpoint<Dest>, b: Endpoint<Dest>, base: Base | Seed, options: BiOptions): Promise<Result<BiPlan, PlanRefusal>>

Plans the sync of two sides against a base, and changes nothing.

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

BiReporttypeno test imports it
type BiReport = { readonly a: Report; readonly b: Report; readonly base: Base };

What a two-way apply did: what happened at each side, and the base to keep. A path whose action did not succeed keeps its old base entry.

applyBisyncfunction
function applyBisync(plan: BiPlan, a: Endpoint<Dest>, b: Endpoint<Dest>, options?: ApplyOptions): Promise<BiReport>

Makes the actions of a two-way plan at both sides and returns the base to keep. The copies that keep a loser's bytes are made first, while the loser's file is as the plan saw it. The plan must have no conflicts the caller did not accept.

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

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