IF Commons GitHub

docs/codec

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

The codec of a document: a pair of functions between a value and the bytes of an object, with the media type of the bytes. A codec never throws: it ends with a result, and the bytes it makes are canonical, so that one value is always the same bytes and therefore the same revision on a store that names revisions by content. The codecs here are the ones that need nothing: bytes, text and JSON (./formats has the codecs that need the file formats of commons).

import { jsonTree, canonicalJson } from "./codec.ts";
canonicalJson({ b: 1, a: [true, null] }); // '{\n  "a": [\n    true,\n    null\n  ],\n  "b": 1\n}\n'
jsonTree.mediaType; // "application/json"

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

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

JsonValuetypeno test imports it
type JsonValue = null | boolean | number | string | readonly JsonValue[] | JsonObject;

A JSON value: what every tree codec reads and writes.

JsonObjecttypeno test imports it
type JsonObject = { readonly [key: string]: JsonValue };

A JSON object.

CODEC_REASONSconstno test imports it
const CODEC_REASONS: readonly ["malformed", "invalid", "newer-version", "unencodable"]

Why a codec could not make or read a document: a closed list.

CodecReasontypeno test imports it
type CodecReason = (typeof CODEC_REASONS)[number];

One reason a codec could not make or read a document.

CodecProblemtypeno test imports it
type CodecProblem = { readonly reason: CodecReason; readonly detail: string };

What a codec says when it does not: the reason and one sentence.

Decodedtypeno test imports it
type Decoded<T> = { readonly value: T; readonly stale: boolean };

What a codec read: the value and whether the bytes were written at an older version than the current one.

Codectypeno test imports it
type Codec<T> = {
  readonly mediaType: string;
  encode(value: T): Result<Uint8Array, CodecProblem>;
  decode(bytes: Uint8Array): Result<Decoded<T>, CodecProblem>;
};

Bytes to a value and back, with the media type of the bytes.

problemconstno test imports it
const problem: (reason: "invalid" | "malformed" | "newer-version" | "unencodable", detail: string) => CodecProblem

A problem of one reason.

toJsonValuefunction
function toJsonValue(value: unknown, depth?: number): Result<JsonValue, string>

A value as a JSON value, or why it is not one: only null, booleans, finite numbers, well-formed strings, arrays and plain objects are, to a depth of 64.

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

isJsonObjectconstno test imports it
const isJsonObject: (value: JsonValue) => value is JsonObject

Whether a JSON value is an object.

canonicalJsonfunction
function canonicalJson(value: JsonValue): string

A JSON value as canonical text: keys in order, two-space indentation, one newline at the end, so that one value is one text.

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

bytesCodecconst
const bytesCodec: Codec<Uint8Array<ArrayBufferLike>>

The bytes as they are.

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

textCodecconst
const textCodec: Codec<string>

The bytes as UTF-8 text: bytes that are not UTF-8 are malformed.

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

jsonTreeconst
const jsonTree: Codec<JsonValue>

The bytes as canonical JSON of any value.

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

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