IF Commons GitHub

Core

0001Draft

0001-core · owner if · domain commons

The foundation

FR-001checkpassing

Core MUST give errors as values (Result<T, E>, a union of Ok and Err told apart by kind, with ok, err, map, mapErr, andThen, orElse, all, match, unwrapOr, attempt, settle), exhaustive matching (absurd(value: never)) and branded types (Brand<T, B>), one name for each.

Enforced (check): .github: cd commons/core && bun test suite/ — result.test.ts: Result's helpers, absurd with a switch that leaves an alternative out, brands kept apart

Proved by: core/suite/result.test.ts, core/suite/text.test.ts

Written in: core/src/absurd.ts, core/src/brand.ts, core/src/result.ts

Tests: passed: suite/result.test.ts all gives every value in order, or the first failure; passed: suite/result.test.ts map keeps identity and composition (functor laws); passed: suite/result.test.ts ok and andThen are a monad (left identity, right identity, associativity); passed: suite/result.test.ts the types: andThen keeps the error type, and a Result cannot be read without its kind; passed: suite/result.test.ts orElse recovers a failure and leaves a success; unwrapOr, match, attempt and settle and 2 more

Cited by: absurd, brand, Core, result

FR-002checkpassing

Core MUST give decoders from unknown to typed values (string, number, integer, boolean, literal, nullable, array, tuple, record, object with optional fields, tagged unions by kind, oneOf, refine to a brand, json), each failure naming the path of the value, what was expected and what was found. Type assertions that decoding needs MUST be confined to src/decode.ts.

Enforced (check): .github: cd commons/core && bun test suite/ — decode.test.ts: each decoder, its error path and the JSON round trip

Proved by: core/suite/decode.test.ts

Written in: core/src/decode.ts

Tests: passed: suite/decode.test.ts a value written as JSON decodes back to itself (round trip); passed: suite/decode.test.ts refine makes a branded value only where it is valid, and the types follow; passed: suite/decode.test.ts each decoder names the path, what it expected and what it found; passed: suite/decode.test.ts optional fields absent or undefined are left out; unknown fields are dropped; passed: suite/decode.test.ts tagged picks the alternative by kind, and names kind where none fits

Cited by: decode, Core

FR-003checkpassing

Core MUST give the pure text helpers more than one harness wrote: line endings made LF, terminal escapes removed, a command line split into its argument vector without a shell, and an argument vector quoted for a POSIX shell.

Enforced (check): .github: cd commons/core && bun test suite/ — text.test.ts: lf, plain, splitArgs and quoteArgs, and their round trip

Proved by: core/suite/text.test.ts

Written in: core/src/text.ts

Tests: passed: suite/text.test.ts words quoted by quoteArgs split back to the same words; passed: suite/text.test.ts lf, plain, splitArgs and quoteArgs

Cited by: Core, text

FR-004checkpassing

Core MUST give tests of types with no framework (expectType<Equal<A, B>>(), with Equal, Extends and Not), which compile only where the types are as claimed, and its laws MUST be property-tested.

Enforced (check): .github: cd commons/core && bun run check — the type-level tests (expectType, @ts-expect-error) with their negative controls compile; the laws are property-tested with fast-check in the suite

Proved by: core/suite/decode.test.ts, core/suite/graph.test.ts, core/suite/objects.test.ts, core/suite/result.test.ts, core/suite/text.test.ts, crypto/suite/cms.test.ts and 16 more

Written in: core/src/types.ts

Tests: passed: suite/decode.test.ts a value written as JSON decodes back to itself (round trip); passed: suite/decode.test.ts refine makes a branded value only where it is valid, and the types follow; passed: suite/graph.test.ts every node comes after the nodes it needs, every node once, the same order every time; passed: suite/graph.test.ts the schedule runs each node after what it needs, at most jobs at once, and skips what depe; passed: suite/objects.test.ts compact leaves out undefined fields, and its type makes them optional without undefined and 47 more

Cited by: Core, types

FR-005checkpassing

Core MUST order a graph so that each node comes after the nodes it needs, the same way every time, or name a cycle; and MUST run a graph's nodes each the moment the nodes it needs are done, no more at once than asked, skipping (and saying) a node whose needed node failed or was skipped, and holding back nothing else.

Enforced (check): .github: cd commons/core && bun test suite/ — graph.test.ts: random acyclic graphs ordered and scheduled with random outcomes and job limits, cycles, a node that rejects

Proved by: core/suite/graph.test.ts

Written in: core/src/graph.ts

Tests: passed: suite/graph.test.ts every node comes after the nodes it needs, every node once, the same order every time; passed: suite/graph.test.ts the schedule runs each node after what it needs, at most jobs at once, and skips what depe; passed: suite/graph.test.ts a cycle is named; a needed node outside the graph is ignored; passed: suite/graph.test.ts a cycle, or a node that rejects, rejects the schedule

Cited by: graph

FR-006checkpassing

Core MUST give compact, which makes an object from fields some of which may be undefined, leaving those out, typed exactly for exactOptionalPropertyTypes: a field whose type includes undefined becomes optional without undefined, every other field stays as it is.

Enforced (check): .github: cd commons/core && bun test suite/ — objects.test.ts: compact leaves out undefined fields, its type exact under exactOptionalPropertyTypes

Proved by: core/suite/objects.test.ts

Written in: core/src/objects.ts

Tests: passed: suite/objects.test.ts compact leaves out undefined fields, and its type makes them optional without undefined; passed: suite/objects.test.ts compact keeps every defined field in its order, and a __proto__ field as an own field

Cited by: Core, objects

The package

FR-007checkno test run

Core MUST depend on nothing, MUST import nothing outside its own files, MUST name no host global, and MUST be published as compiled modules with their declarations as @intellectual-frontiers/core (commons 0032-libraries-by-concern FR-005), so that it runs on Bun, on Node 26 and in a browser with no build step.

Enforced (check): .github: cd commons/core && bun run verify — the package is built, inspected and packed by tools/pack.ts; tests/commons-packages.test.ts installs the tarball and runs it on Node 26 and Bun and type-checks a consumer

Written in: core/about.ts, core/library.ts, core/src/mod.ts, core/tools/check.ts, core/tools/pack.ts

FR-008checkpassing

Core MUST give the types of the facts a library states of itself for its documentation (About and the types it is made of: its title, its summary, the specification it implements, its folders with what each may import, its commands, its rules with what enforces each, its areas, layers and facts) as a type-only entry @intellectual-frontiers/core/about, which exports no value, so that a library types its about.ts by Core and depends on nothing else for it.

Enforced (check): .github: cd commons/core && bun test suite/ — about.test.ts: an About value of every shape is accepted by the compiler and one with an unknown field or a missing title is refused (type-level), and the entry exports no value

Proved by: core/suite/about.test.ts

Written in: core/src/about.ts

Tests: passed: suite/about.test.ts an About value of every shape is accepted, one with an unknown field or no title is refuse

Acceptance scenarios

  1. Given a switch over a union that leaves an alternative out, When it ends in absurd, Then it does not compile, per FR-001.
  2. Given a value of no known shape, When a decoder reads it, Then a failure names the path, what was expected and what was found, per FR-002.
  3. Given a command line with quotes, When it is split and quoted again, Then the same argument vector comes back, per FR-003.
  4. Given an acyclic graph and a limit, When it is scheduled with random outcomes, Then no more than the limit run at once and a node whose needed node failed is skipped, per FR-005.
  5. Given the packed package installed under node_modules, When Node 26 and Bun import it, Then both give the same ok, err and decode, per FR-007.

Out of scope

Edge cases

  • A graph with a cycle: ordered as an error naming the cycle, per FR-005.
  • A field of an object that is undefined under exactOptionalPropertyTypes: left out by compact, per FR-006.
  • A decoder given null, an array where an object is expected, or an object with an extra field: each named by path, per FR-002.

Assumptions

  • ECMAScript 2024 and the web standards are all that the code needs.

Open questions

  • None.

Key entities

  • Result - a value or an error told apart by kind.
  • Brand - a type made distinct from its representation by a function that validates it.
  • Decoder - a function from unknown to a typed value or an error with a path.

Success criteria

SC-001success criterion

A library of commons uses these and nothing else to be correct at its boundaries.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

absurd, brand, decode, graph, Core, objects, result, text, types

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