IF Commons GitHub

governance/document

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0004-grc-documents FR-001, 0004-grc-documents FR-002

The document envelope (0004-grc-documents): everything GRC persists or exchanges is { kind, schema, id, createdAt, provenance, ...body }. defineKind makes the decoder of a kind from the decoders of its body, a registry of kinds holds them by kind, and readDocument reads text or a value through it, knowing exactly the schema each kind has in this release: a document of another schema is an error value that names both, never read by a second reader.

import { createKinds, defineKind, readDocument } from "./document.ts";
import { string } from "@intellectual-frontiers/core";
const note = defineKind("grc.note", "1", { text: string });
const kinds = createKinds();
kinds.register(note);
readDocument(kinds, "{}"); // an error value: the kind is missing

Source: commons/grc/src/governance/document.ts

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

governance.instantconstno test imports it
const instant: Decoder<string>

An ISO 8601 instant with a zone.

governance.provenanceDecoderconstno test imports it
const provenanceDecoder: Decoder<ObjectOf<{ producer: Decoder<ObjectOf<{ name: Decoder<string>; version: Decoder<string>; }, Record<never, never>>>; inputs: Decoder<readonly string[]>; }, { actor: Decoder<string>; }>>

Provenance: the producer, what it was made from (ids or digests), and optionally who or what acted.

governance.Provenancetypeno test imports it
type Provenance = Decoded<typeof provenanceDecoder>;

Provenance.

governance.Documenttypeno test imports it
type Document = {
  readonly kind: string;
  readonly schema: string;
  readonly id: string;
  readonly createdAt: string;
  readonly provenance: Provenance;
};

What every document has.

governance.DocumentKindtypeno test imports it
type DocumentKind<T extends Document = Document> = {
  readonly id: string;
  readonly kind: string;
  readonly schema: string;
  readonly decode: Decoder<T>;
};

A kind of document: its decoder, with the one schema it knows. Its id is its kind, the stable id in the registry of kinds.

governance.defineKindfunctionno test imports it
function defineKind<R extends Fields, O extends Fields = Record<never, never>>(kind: string, schema: string, required: R… (447 characters)
function defineKind<R extends Fields, O extends Fields = Record<never, never>>(kind: string, schema: string, required: R, optional?: O | undefined, validate?: ((value: Document & { readonly [K in keyof R]: Decoded<R[K]>; } & { readonly [K in keyof O]?: Decoded<O[K]> | undefined; }) => string | undefined) | undefined): DocumentKind<Document & { readonly [K in keyof R]: Decoded<R[K]>; } & { readonly [K in keyof O]?: Decoded<O[K]> | undefined; }>

The kind kind at schema, with a body of these required and optional fields, and optionally a check of the whole that says what is wrong.

governance.Kindstypeno test imports it
type Kinds = Registry<DocumentKind>;

A registry of kinds of documents.

governance.createKindsfunctionno test imports it
function createKinds(): Kinds

A registry of kinds, empty.

governance.ReadProblemtypeno test imports it
type ReadProblem =
  | { readonly kind: "json"; readonly message: string }
  | { readonly kind: "no-kind"; readonly found: string }
  | { readonly kind: "unknown-kind"; readonly found: string }
  | { readonly kind: "schema"; readonly documentKind: string; readonly found: string; readonly expected: string }
  | { readonly kind: "decode"; readonly error: DecodeError };

Why a document was not read.

governance.readDocumentfunctionno test imports it
function readDocument(kinds: Kinds, input: unknown): Result<Document, ReadProblem>

The document in input (a value, or its JSON text), through the registry; or why it cannot be read.

governance.describeReadProblemfunctionno test imports it
function describeReadProblem(p: ReadProblem): string

One sentence for a problem.

governance.PRODUCERconstno test imports it
const PRODUCER: { readonly name: "@intellectual-frontiers/grc"; readonly version: "0.2.0"; }

The producer every document of this library names.

governance.provenanceOffunctionno test imports it
function provenanceOf(inputs?: readonly string[], actor?: string | undefined): ObjectOf<{ producer: Decoder<ObjectOf<{ name: Decoder<string>; version: Decoder<string>; }, Record<never, never>>>; inputs: Decoder<readonly string[]>; }, { actor: Decoder<string>; }>

Provenance for a document made here from the documents or digests inputs.

instantconstno test imports it
const instant: Decoder<string>

An ISO 8601 instant with a zone.

provenanceDecoderconstno test imports it
const provenanceDecoder: Decoder<ObjectOf<{ producer: Decoder<ObjectOf<{ name: Decoder<string>; version: Decoder<string>; }, Record<never, never>>>; inputs: Decoder<readonly string[]>; }, { actor: Decoder<string>; }>>

Provenance: the producer, what it was made from (ids or digests), and optionally who or what acted.

Provenancetypeno test imports it
type Provenance = Decoded<typeof provenanceDecoder>;

Provenance.

Documenttypeno test imports it
type Document = {
  readonly kind: string;
  readonly schema: string;
  readonly id: string;
  readonly createdAt: string;
  readonly provenance: Provenance;
};

What every document has.

DocumentKindtypeno test imports it
type DocumentKind<T extends Document = Document> = {
  readonly id: string;
  readonly kind: string;
  readonly schema: string;
  readonly decode: Decoder<T>;
};

A kind of document: its decoder, with the one schema it knows. Its id is its kind, the stable id in the registry of kinds.

defineKindfunction
function defineKind<R extends Fields, O extends Fields = Record<never, never>>(kind: string, schema: string, required: R… (447 characters)
function defineKind<R extends Fields, O extends Fields = Record<never, never>>(kind: string, schema: string, required: R, optional?: O | undefined, validate?: ((value: Document & { readonly [K in keyof R]: Decoded<R[K]>; } & { readonly [K in keyof O]?: Decoded<O[K]> | undefined; }) => string | undefined) | undefined): DocumentKind<Document & { readonly [K in keyof R]: Decoded<R[K]>; } & { readonly [K in keyof O]?: Decoded<O[K]> | undefined; }>

The kind kind at schema, with a body of these required and optional fields, and optionally a check of the whole that says what is wrong.

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

Kindstypeno test imports it
type Kinds = Registry<DocumentKind>;

A registry of kinds of documents.

createKindsfunction
function createKinds(): Kinds

A registry of kinds, empty.

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

ReadProblemtypeno test imports it
type ReadProblem =
  | { readonly kind: "json"; readonly message: string }
  | { readonly kind: "no-kind"; readonly found: string }
  | { readonly kind: "unknown-kind"; readonly found: string }
  | { readonly kind: "schema"; readonly documentKind: string; readonly found: string; readonly expected: string }
  | { readonly kind: "decode"; readonly error: DecodeError };

Why a document was not read.

readDocumentfunction
function readDocument(kinds: Kinds, input: unknown): Result<Document, ReadProblem>

The document in input (a value, or its JSON text), through the registry; or why it cannot be read.

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

describeReadProblemfunction
function describeReadProblem(p: ReadProblem): string

One sentence for a problem.

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

PRODUCERconstno test imports it
const PRODUCER: { readonly name: "@intellectual-frontiers/grc"; readonly version: "0.2.0"; }

The producer every document of this library names.

provenanceOffunctionno test imports it
function provenanceOf(inputs?: readonly string[], actor?: string | undefined): ObjectOf<{ producer: Decoder<ObjectOf<{ name: Decoder<string>; version: Decoder<string>; }, Record<never, never>>>; inputs: Decoder<readonly string[]>; }, { actor: Decoder<string>; }>

Provenance for a document made here from the documents or digests inputs.

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