IF Commons GitHub

docs/collection

Written to: 5 requirements: 5 proved, 0 partly, 0 failing, 0 with no test recorded. 0006-anyfs-documents FR-007, 0006-anyfs-documents FR-008, 0006-anyfs-documents FR-009, 0006-anyfs-documents FR-010, 0006-anyfs-documents FR-011

A collection: a typed set of documents under a prefix of a store, whose keys have paths by a layout written as code and whose bytes are made by a codec. Every document comes with the revision it was read at, and every write states what it expects, as the store does. What a collection may do is in its type: a collection of a store that cannot write has no put, and update, the read-modify-write that retries where another writer got there first, needs a store with cas. A listing reads the objects lazily, and an object that is not a good document is a finding beside the others.

The one cast of the module is in collection: it builds the object with every method and gives it the type its capabilities say, as makeStore does for a store. The methods that need a capability the store does not have refuse at run time through the store, and update and migrate refuse before they read.

import { collection, jsonTree, byId, parseExtension, defineSchema } from "@intellectual-frontiers/anyfs/docs";
// const docs = collection(store, { prefix, layout: byId(ext), codec: versioned(jsonTree, schema) });
// const doc = await docs.get(key);          // ok { value, rev, stale }
// await docs.update(key, (d) => ({ kind: "put", value: next(d?.value) }));

Source: commons/anyfs/src/docs/collection.ts

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

Doctypeno test imports it
type Doc<T, K> = { readonly key: K; readonly path: Path; readonly value: T; readonly rev: Revision; readonly stale: boolean; readonly modified?: string };

A document with the key it is kept under, the path, the revision it was read at and whether it was written at an older version than the current.

Savedtypeno test imports it
type Saved<K> = { readonly key: K; readonly path: Path; readonly rev: Revision; readonly created: boolean };

What a put made.

Pagetypeno test imports it
type Page<T, K> = { readonly docs: readonly Doc<T, K>[]; readonly findings: readonly Finding[]; readonly next?: Cursor };

One page of a listing: the good documents and the findings in the order of the paths, and where the next page begins where there is one.

Itemtypeno test imports it
type Item<T, K> = { readonly kind: "doc"; readonly doc: Doc<T, K> } | { readonly kind: "finding"; readonly finding: Finding };

One item of a scan.

Updatetypeno test imports it
type Update<T, C extends Capability = Capability> = { readonly kind: "put"; readonly value: T } | { readonly kind: "keep" } | ("delete" extends C ? { readonly kind: "delete" } : never);

What an update does with the document it is given: write a value, remove it (only where the store can delete), or leave it.

Updatedtypeno test imports it
type Updated<T, K> =
  | { readonly kind: "put"; readonly doc: Doc<T, K>; readonly created: boolean; readonly attempts: number }
  | { readonly kind: "deleted"; readonly attempts: number }
  | { readonly kind: "kept"; readonly doc?: Doc<T, K>; readonly attempts: number };

What an update ended with, and in how many attempts.

Migratedtypeno test imports it
type Migrated = { readonly scanned: number; readonly rewritten: number; readonly findings: readonly Finding[]; readonly failures: readonly DocProblem[] };

What migrate did.

CollectionConfigtypeno test imports it
type CollectionConfig<T, K> = { /** Where the documents are in the store. */ readonly prefix: Prefix; readonly lay… (678 characters)
type CollectionConfig<T, K> = {
  /** Where the documents are in the store. */
  readonly prefix: Prefix;
  readonly layout: Layout<K>;
  readonly codec: Codec<T>;
  /** The attempts of an update where another writer changed the document first; 5 where not given. */
  readonly attempts?: number;
  /** How many documents a page lists and reads; 100 where not given. */
  readonly pageSize?: number;
  /** How many documents are read at once in a page; 8 where not given. */
  readonly readers?: number;
  /** What an update waits for between attempts, given the attempt that failed: it does not wait where not given. */
  readonly pause?: (attempt: number) => Promise<void>;
};

What a collection is made from.

CollectionBasetypeno test imports it
type CollectionBase<K> = {
  /** The path of a key, or why it has none. */
  pathOf(key: K): Result<Path, DocProblem>;
};

What every collection has.

Collectiontypeno test imports it
type Collection<T, K, C extends Capability> = CollectionBase<K> & Gate<C, "read", { get(key: K): Promise<Result<Doc<T,… (859 characters)
type Collection<T, K, C extends Capability> = CollectionBase<K> &
  Gate<C, "read", { get(key: K): Promise<Result<Doc<T, K>, DocProblem>> }> &
  Gate<C, "write", { put(key: K, value: T, expect: ExpectFor<C>): Promise<Result<Saved<K>, DocProblem>> }> &
  Gate<C, "delete", { delete(key: K, expect: ExpectFor<C>): Promise<Result<{ readonly existed: boolean }, DocProblem>> }> &
  Gate<
    C,
    "list" | "read",
    {
      list(options?: { readonly after?: Cursor }): Promise<Result<Page<T, K>, DocProblem>>;
      scan(): AsyncGenerator<Item<T, K>, void, undefined>;
    }
  > &
  Gate<C, "read" | "write" | "cas", { update(key: K, f: (current: Doc<T, K> | undefined) => Update<T, C> | Promise<Update<T, C>>): Promise<Result<Updated<T, K>, DocProblem>> }> &
  Gate<C, "list" | "read" | "write" | "cas", { migrate(): Promise<Result<Migrated, DocProblem>> }>;

A collection of the capabilities C of its store: it has the methods that C can do, and no other.

CanDotypeno test imports it
type CanDo<C extends Capability, K extends Capability> = Has<C, K>;

The same for a store that has the capability named, to read in a type: whether a capability is in a set.

collectionfunction
function collection<T, K, C extends Capability>(store: Store<C>, config: CollectionConfig<T, K>): Collection<T, K, C>

A collection over a store: see the module.

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

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