IF Commons GitHub

ts-literal

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-formats FR-006

Data as TypeScript object literals, for files a program writes for people to read and edit (keys bare where they are identifiers, strings in double quotes, two-space indentation and trailing commas), and the reader of exactly that subset, which never runs the file, so a past version from git show can be read safely (commons 0001-formats FR-006); the writer takes any type shaped as JSON (commons 0001-formats FR-007). Taken from Stolos's src/archon/core/ts-literal.ts; the reader returns a Result instead of throwing.

import { parseTsLiteral, tsLiteral } from "./ts-literal.ts";
const text = tsLiteral({ timezone: "America/New_York", "otel-ui": true });
parseTsLiteral(text); // { kind: "ok", value: { value: { timezone: "America/New_York", "otel-ui": true }, end: text.length } }

Source: commons/formats/src/ts-literal.ts

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

BARE_KEYconstno test imports it
const BARE_KEY: RegExp

A key that needs no quotes: an identifier (letters, digits, _, $; not starting with a digit).

exportedLiteralfunction
function exportedLiteral(source: string, name: string): Result<Literal, LiteralError>

The value of export const <name>[: Type] = <literal>; in a file tsLiteral wrote, or why it cannot be read.

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

parseTsLiteralfunction
function parseTsLiteral(text: string, start?: number): Result<{ readonly value: Literal; readonly end: number; }, LiteralError>

The value of a literal tsLiteral wrote, starting at start, and where it ended: objects with bare or quoted keys, arrays, double-quoted strings, numbers, true, false and null, with trailing commas and // comments. Anything else is an error.

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

tsKeyfunction
function tsKey(key: string): string

A key as TypeScript writes it: bare where it can be, else a double-quoted string.

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

tsLiteralfunction
function tsLiteral<T>(value: T & LiteralShape<T>, depth?: number): string

A value as a TypeScript literal, indented for depth (two spaces each). It takes any value whose type is shaped as JSON (commons 0001-formats FR-007), an interface with no index signature included, and refuses at compile time a value holding a function, a Date, a bigint or another type JSON has not. Objects and arrays span lines (empty ones stay {} and []); properties that are undefined are left out, as JSON.stringify leaves them out. A number that is not finite is written null, as JSON writes it. (The check is on the parameter, T & LiteralShape<T>, because TypeScript refuses T extends LiteralShape<T> as a circular constraint.)

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

Literaltype
type Literal = null | boolean | number | string | readonly Literal[] | { readonly [key: string]: Literal | undefined };

A value that parseTsLiteral reads back, and so tsLiteral writes: what JSON holds.

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

LiteralErrortypeno test imports it
type LiteralError = { readonly kind: "literal"; readonly at: number; readonly expected: string };

Where a text stopped being a literal, and what was expected there.

LiteralShapetype
type LiteralShape<T> = T extends Literal
  ? T
  : T extends readonly unknown[]
    ? { readonly [I in keyof T]: LiteralShape<T[I]> }
    : T extends (...args: never) => unknown
      ? never
      : T extends object
        ? { readonly [K in keyof T]: K extends string ? PropertyShape<T[K]> : never }
        : never;

T itself where T is shaped as JSON at every depth, else a type T is not assignable to, so that a parameter T & LiteralShape<T> takes any JSON-shaped type (commons 0001-formats FR-007), an interface with no index signature included: strings, numbers, booleans and null; arrays and tuples of such values; objects whose string keys hold such values, undefined allowed only as an optional property's. A function, a Date, a Map, a bigint, a symbol or unknown anywhere makes it never there.

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

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