IF Commons GitHub

docs/layout

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0006-anyfs-documents FR-005

Where the documents of a collection are, as code: a layout is a pair of functions between a typed key and a path below the collection, and the second is the inverse of the first, so that a listing can name the key of every object it finds and name the objects that are none of the collection's. The keys are made by smart constructors: an identifier is a safe name of one segment, a date is a day of the calendar. Three layouts are here (by identifier, by identifier below a shard of its first characters, by day); another is a value of the same type.

import { byId, parseDocId, parseExtension } from "./layout.ts";
const ext = parseExtension(".json");
const id = parseDocId("olympia");
if (ext.kind === "ok" && id.kind === "ok") byId(ext.value).path(id.value); // ok "olympia.json"

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

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

Layouttypeno test imports it
type Layout<K> = {
  readonly name: string;
  path(key: K): Result<Path, string>;
  key(path: Path): Result<K, string>;
};

What a layout does: a key to a path below the collection, and the path back to its key, or why the path is not a document of the layout.

DocIdtype
type DocId = Brand<string, "anyfs doc id">;

The name of one document: one segment of letters, digits and . _ ~ @ + = -, beginning with a letter or digit, of at most 128 characters. Made only by parseDocId.

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

Extensiontypeno test imports it
type Extension = Brand<string, "anyfs extension">;

The end of a file name that says its format: a dot and one to sixteen lower-case letters or digits. Made only by parseExtension.

IsoDatetypeno test imports it
type IsoDate = Brand<string, "anyfs iso date">;

A day of the calendar, as YYYY-MM-DD. Made only by parseIsoDate.

parseDocIdfunction
function parseDocId(text: string): Result<DocId, string>

An identifier from text, or why the text is not one.

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

parseExtensionfunction
function parseExtension(text: string): Result<Extension, string>

An extension from text, or why the text is not one.

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

parseIsoDatefunction
function parseIsoDate(text: string): Result<IsoDate, string>

A day from text, or why the text is not one: the year, month and day are numbers and the day exists in the calendar.

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

byIdfunction
function byId(extension: Extension): Layout<DocId>

The layout with one file for each identifier, directly below the collection: <id><extension>.

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

shardedfunction
function sharded(extension: Extension, width?: number): Result<Layout<DocId>, string>

The layout with the files below a folder of the first width characters of the identifier (one to four): <shard>/<id><extension>, so that no folder holds all of them.

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

DatedKeytypeno test imports it
type DatedKey = { readonly date: IsoDate; readonly id: DocId };

The key of a document kept by day.

byDatefunction
function byDate(extension: Extension): Layout<DatedKey>

The layout with the files below the year, month and day: YYYY/MM/DD/<id><extension>.

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

layoutFindingsfunction
function layoutFindings<K>(layout: Layout<K>, keys: readonly K[], same: (a: K, b: K) => boolean): readonly string[]

What is wrong with a layout over some keys: where the path of a key is refused, or does not give the key back. Nothing wrong is the empty list.

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

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