IF Commons GitHub

logical/store

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0003-anyfs-logical FR-002

The store: one interface to a place, whose capabilities are in its type. Store<C> has the methods of the capabilities C and no other, and a function that needs a capability takes a Store that has it, so that a store without it is a compile error and not a surprise at run time. A store is made by makeStore from one handler of operations: the store is a facade, so that every layer and every attenuation is a function of operations and none can be bypassed.

The one cast of the library is in makeStore: it builds the object from the capabilities it is given and gives it the type those capabilities say. A test holds it: a store has a method exactly where its capabilities name one. watch and lock are capabilities with no operation, so makeStore makes no store of them yet.

import { makeStore } from "./store.ts";
// a store of `read` alone: store.write does not exist, and a function that needs `write` refuses it

Source: commons/anyfs/src/logical/store.ts

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

OpCapabilitytype
type OpCapability = Exclude<Capability, "watch" | "lock">;

The capabilities that have an operation: every one but watch and lock.

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

Changedtypeno test imports it
type Changed = { readonly path: Path; readonly kind: "put" | "delete" };

The change of an object a watcher is told of.

Subscriptiontypeno test imports it
type Subscription = { stop(): void };

A watch: stop it with stop.

Locktypeno test imports it
type Lock = { release(): Promise<void> };

A held object: give it back with release.

StoreBasetypeno test imports it
type StoreBase = { /** What the store is called in a finding. */ readonly id: string; /** Where it is. */ readon… (478 characters)
type StoreBase = {
  /** What the store is called in a finding. */
  readonly id: string;
  /** Where it is. */
  readonly place: Place;
  readonly consistency: Consistency;
  readonly traits: Traits;
  /** The capabilities it has, as a set a program can read; the type says the same at compile time. */
  readonly capabilities: ReadonlySet<Capability>;
  /** Every operation goes through here, after the check that the store has what it needs. */
  readonly handle: Handler;
};

What every store has, whatever its capabilities.

Storetype
type Store<C extends Capability> = StoreBase & UnionToIntersection<{ [K in C]: Group<K, C> }[C]> & { readonly "@anyfs/capabilities"?: (capability: C) => void };

A store with the capabilities C: it has their methods and no other. The optional marker is a function of C and never present at run time: it lets the compiler read C back from a store (so that readOnly(store) of a store in memory is a store of the capabilities of memory) and keeps a store of more capabilities assignable to a store of fewer.

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

AnyStoretypeno test imports it
type AnyStore = StoreBase;

Any store, whatever its capabilities: what a function that only handles operations takes.

StoreSpectypeno test imports it
type StoreSpec<C extends OpCapability> = {
  readonly id: string;
  readonly place: Place;
  readonly consistency: Consistency;
  readonly traits: Traits;
  readonly capabilities: readonly C[];
  readonly handle: Handler;
};

What a store is made from.

hasOperationconstno test imports it
const hasOperation: (c: "append" | "batch" | "cas" | "delete" | "history" | "list" | "lock" | "merge" | "rangeRead" | "read" | "rename" | "search" | "stat" | "watch" | "write") => c is OpCapability

Whether a capability has an operation.

opCapabilitiesOfconstno test imports it
const opCapabilitiesOf: (store: StoreBase) => readonly OpCapability[]

The capabilities of a store that have an operation.

capabilitiesWithoutfunctionno test imports it
function capabilitiesWithout<C extends Capability, D extends Capability>(store: Store<C>, dropped: readonly D[]): readonly Exclude<C, "lock" | "watch" | D>[]

The capabilities of a store of C that are carried and are not in dropped, typed as the type says: the same fact as the set of the store, with some taken away.

Carriedtypeno test imports it
type Carried<C extends Capability> = Exclude<C, "watch" | "lock">;

What a layer or an attenuation keeps of a store of C: every capability but watch and lock, which have no operation to carry.

carriedCapabilitiesfunctionno test imports it
function carriedCapabilities<C extends Capability>(store: Store<C>): readonly Exclude<C, "lock" | "watch">[]

The capabilities of a store of C that are carried, typed as the type says. The type of a store is its set, so the cast is the same fact.

makeStorefunction
function makeStore<C extends OpCapability>(spec: StoreSpec<C>): Store<C>

The store of its capabilities, made from a handler: it has exactly their methods, checks before each operation that it has what the operation needs, and never throws.

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

supportsfunction
function supports<C extends Capability, D extends Capability>(store: Store<C>, ...needed: readonly D[]): store is StoreBase & UnionToIntersection<{ [K in C]: Group<K, C>; }[C]> & { readonly "@anyfs/capabilities"?: ((capability: C) => void) | undefined; } & UnionToIntersection<{ [K in D]: Group<K, D>; }[D]> & { readonly "@anyfs/capabilities"?: ((capability: D) => void) | undefined; }

Narrows a store to more capabilities where its set has them: the compiler then lets the caller use their methods.

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

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