functionalscript 0.46.1 → 0.47.0

package/fjs/types/rtti/host.proof.mjs

@@ -0,0 +1,170 @@
+/**
+ * The rtti readers against values **FunctionalScript cannot build**.
+ *
+ * A `proof.mjs` rather than a `proof.f.mjs`, and deliberately: the fixtures
+ * here need in-place mutation — `Object.setPrototypeOf` to give an array a
+ * prototype that supplies an index, `Object.assign` to put a key past the
+ * index range on one — which [`../../AGENTS.md`](../../AGENTS.md) §3.1 forbids
+ * in authored FunctionalScript. `shouldLoad` in
+ * [`../../dev/module.f.mjs`](../../dev/module.f.mjs) makes a plain
+ * `proof.mjs` the opt-in home for exactly that, so the mutation stays out of
+ * the `.f.mjs` proofs rather than being smuggled through them.
+ *
+ * The values are worth pinning even though the subset cannot express them: a
+ * caller in ordinary JavaScript can hand one to an exported reader, and both
+ * are cases where reading a member by *entry* and reading it by *index*
+ * disagree — which is what these readers had wrong.
+ *
+ * @module
+ *
+ * @import { Type } from './types.ts'
+ * @import { ValidateE } from './common/types.ts'
+ * @import { Unknown } from './ts/types.ts'
+ */
+
+import { assert, assertEq, assertStructurallySame } from '../../asserts/module.f.mjs'
+import { undeclaredMembers } from './common/module.f.mjs'
+import { toData, validate as dataValidate } from './data/module.f.mjs'
+import { array, number, rest, string } from './module.f.mjs'
+import { parse } from './parse/module.f.mjs'
+import { validate } from './validate/module.f.mjs'
+
+/** The three readers with their payload type erased, as `validate/proof.f.mjs` has them. */
+
+/** @type {(t: Type) => ValidateE} */
+const v = t => /** @type {any} */ (validate(t))
+
+/** @type {(t: Type) => ValidateE} */
+const p = t => /** @type {any} */ (parse(t))
+
+/** @type {(t: Type) => ValidateE} */
+const d = t => dataValidate(toData(t))
+
+/** @type {(r: readonly [string, unknown]) => void} */
+const assertOk = ([k]) => { assertEq(k, 'ok', 'expected ok') }
+
+/** @type {(r: readonly [string, unknown]) => void} */
+const assertError = ([k]) => { assertEq(k, 'error', 'expected error') }
+
+/**
+ * An array whose index 1 is readable through the **prototype**: `length` says
+ * 2, index 1 is no own entry, and reading it gives `99`. `Array.isArray` looks
+ * at the value and not at its prototype, so this is still an array to every
+ * reader — and the member is one a schema has to answer for, or the tail
+ * `./ts/types.ts` renders would claim the rest's type over a number.
+ *
+ * @type {() => readonly Unknown[]}
+ */
+const inheritedIndex = () => {
+    const value = [42, ,]
+    Object.setPrototypeOf(value, [0, 99])
+    return value
+}
+
+/**
+ * An array whose prototype supplies an index it **owns anyway**. Nothing about
+ * it is unusual to a reader — the member list is the own one — but it is the
+ * case that separates "the chain names an index" from "the chain supplies one",
+ * which is where the walk decides whether it has anything to merge.
+ *
+ * @type {() => readonly Unknown[]}
+ */
+const shadowedIndex = () => {
+    const value = [42]
+    Object.setPrototypeOf(value, [7])
+    return value
+}
+
+/**
+ * An array carrying `4294967295` — one past the last index the language has.
+ * Assigning it creates an ordinary enumerable property and leaves `length` at
+ * `1`, so it is an undeclared member that no `length`-bounded walk reaches; a
+ * reader treating it as an index found it on neither path and let it through a
+ * closed container.
+ *
+ * @type {() => readonly Unknown[]}
+ */
+const beyondIndexRange = () => Object.assign([1], { '4294967295': 2 })
+
+export const proof = {
+    // `undeclaredMembers` decides a container's members by what an index
+    // *reads*, so both of these are members — one that an own-entry walk
+    // misses, and one that an index-keyed walk misses.
+    undeclaredMembers: {
+        inheritedIndexIsAMember: () => {
+            const value = inheritedIndex()
+            assertEq(value.length, 2, 'the array reaches that far')
+            assert(!Object.hasOwn(value, 1), 'and index 1 is no own entry')
+            assertStructurallySame(undeclaredMembers(['0'], value), [['1', 99]])
+        },
+        // A shadowed one contributes nothing: the value owns the index, so
+        // the member list is what the own walk already answered.
+        shadowedIndexIsTheOwnOne: () => {
+            const value = shadowedIndex()
+            assertEq(value[0], 42, 'the own value wins')
+            assertStructurallySame(undeclaredMembers([], value), [['0', 42]])
+            assertEq(undeclaredMembers(['0'], value).length, 0)
+        },
+        // `2 ** 32 - 1` is not an index: assigning it creates an ordinary
+        // enumerable property and leaves `length` alone, so it is a member by
+        // the non-index half. Reading it as an index put it past both halves.
+        beyondTheIndexRangeIsAMember: () => {
+            const value = beyondIndexRange()
+            assertEq(value.length, 1, '`length` never saw the assignment')
+            assertStructurallySame(
+                undeclaredMembers(['0'], value),
+                [['4294967295', 2]],
+            )
+        },
+    },
+    // Every row runs through all three readers, which is the agreement
+    // `validate/proof.f.mjs`'s table exists to hold: a value one reader
+    // accepts and another rejects is a bug in whichever walk differs, and
+    // both of these fixtures found one.
+    readersAgree: () => {
+        /** @type {readonly (readonly [Type, readonly Unknown[]])[]} */
+        const rows = [
+            // an index read through the prototype is held to the rest like any
+            // other member — on the uniform reader as well as the tuple one
+            [rest([number], string), inheritedIndex()],
+            [rest([number], number), inheritedIndex()],
+            [array(string), inheritedIndex()],
+            [array(number), inheritedIndex()],
+            // a key past the last index the language has is an ordinary
+            // property, so it is a member by the non-index half
+            [[number], beyondIndexRange()],
+            [rest([number], string), beyondIndexRange()],
+            [rest([number], number), beyondIndexRange()],
+        ]
+        for (const [t, value] of rows) {
+            const rv = v(t)(value)
+            assertEq(rv[0], p(t)(value)[0], 'validate and parse must agree')
+            assertEq(rv[0], d(t)(value)[0], 'the data form must agree too')
+        }
+    },
+    // …and what they agree on, which is what the changelog entry claims.
+    inheritedIndexMeetsTheRest: () => {
+        const value = inheritedIndex()
+        for (const read of [v, p, d]) {
+            assertError(read(rest([number], string))(value))
+            assertOk(read(rest([number], number))(value))
+            // `array(t)` is `rest([], t)`, so it walks the value the same way.
+            // An own-entry walk here answered `ok` while the data form's
+            // reader rejected the same value against the same schema.
+            assertError(read(array(string))(value))
+            assertOk(read(array(number))(value))
+        }
+        assert(Object.is(v(rest([number], number))(value)[1], value),
+            '`validate` still hands back the value it was given')
+    },
+    beyondTheIndexRangeIsAMember: () => {
+        const value = beyondIndexRange()
+        for (const read of [v, p, d]) {
+            // a bare container names every member it admits, and not this one
+            assertError(read([number])(value))
+            // a stated rest answers for it like any other undeclared member
+            assertError(read(rest([number], string))(value))
+            assertOk(read(rest([number], number))(value))
+        }
+    },
+}

package/fjs/types/rtti/module.f.d.mts

@@ -7,12 +7,12 @@
  * @import { Includes } from '../array/types.ts'
  * @import { Assert } from '../../asserts/types.ts'
  * @import { Equal } from '../ts/types.ts'
- * @import { Tag0, Primitive0, _Type0, Bigint, Unknown, Tag1, _MakeType1, Array, Record, Or, Type } from './types.ts'
+ * @import { Tag0, Primitive0, _Type0, Bigint, Unknown, Tag1, _MakeType1, _MakeOpen, _MakeRest, Or, Type } from './types.ts'
  */
 import type { Includes } from '../array/types.ts';
 import type { Assert } from '../../asserts/types.ts';
 import type { Equal } from '../ts/types.ts';
-import type { Primitive0, _Type0, Bigint, Unknown, Tag1, _MakeType1, Or, Type } from './types.ts';
+import type { Primitive0, _Type0, Bigint, Unknown, Tag1, _MakeType1, _MakeOpen, _MakeRest, Or, Type } from './types.ts';
 declare const primitive0List: readonly ['bigint', 'boolean', 'number', 'string'];
 export type _Primitive0Pinned = Assert<Equal<Primitive0, typeof primitive0List[number]>>;
 /** @typedef {Assert<Equal<Primitive0, typeof primitive0List[number]>>} _Primitive0Pinned */
@@ -62,22 +62,67 @@ export declare const record: _MakeType1<'record'>;
  * or canonical-form work. All such algebra lives on the serializable data form
  * — see `./data/README.md`.
  *
- * @template {readonly Type[]} T
+ * @template {readonly Type[]} const T
  * @param {T} types
  * @returns {Or<T>}
  */
-export declare const or: <T extends readonly Type[]>(...types: T) => Or<T>;
+export declare const or: <const T extends readonly Type[]>(...types: T) => Or<T>;
 /**
  * Constructs a schema that validates a value matching `T` or `undefined`.
  *
- * @template {Type} T
+ * @template {Type} const T
  * @param {T} t
  * @returns {Or<readonly [T, undefined]>}
  */
-export declare const option: <T extends Type>(t: T) => Or<readonly [T, undefined]>;
+export declare const option: <const T extends Type>(t: T) => Or<readonly [T, undefined]>;
 /**
  * Schema that never matches any value — the empty union, corresponding to TypeScript's `never`.
+ *
  * @type {Or<readonly []>}
  */
 export declare const never: Or<readonly []>;
+/**
+ * Constructs a schema for a container whose **undeclared** members belong to
+ * `r`: the members `c` declares, plus any number of members belonging to `r`.
+ *
+ * A `Struct` or a `Tuple` used on its own is closed — it admits the members it
+ * declares and no others — which is `rest(c, never)` and needs no spelling.
+ * This is how a schema says it wants anything else.
+ *
+ * ```js
+ * rest([number], string)       // one number, then any number of strings
+ * rest({ a: number }, string)  // `a`, plus any number of string-valued keys
+ * open({ a: number })          // `a`, plus anything else
+ * ```
+ *
+ * Both parameters are required. An optional one would need a sentinel for "no
+ * undeclared member", and every candidate — `undefined` most of all — is a
+ * `Type` in its own right, so the sentinel would collide with the schema it
+ * spells. `never` carries no such ambiguity, and a container whose undeclared
+ * members must be the *value* `undefined` states that rest as a wrapped const,
+ * `() => ['const', undefined]`.
+ *
+ * On the array kind `r` constrains the members past the prefix, and a `r` that
+ * admits nothing bounds the array's length — which is what the bare form
+ * already says, so `rest(c, never)` and `c` are one set.
+ *
+ * @type {_MakeRest}
+ */
+export declare const rest: _MakeRest;
+/**
+ * Constructs a schema for an **open** container: the members `c` declares,
+ * plus any number of members of any kind. `open(c)` is `rest(c, unknown)`.
+ *
+ * Openness is what makes a schema forward-compatible with a serialization
+ * format that has grown fields, so a schema read against a wire format
+ * someone else may extend says `open`.
+ *
+ * ```js
+ * open({ a: number })   // any object whose `a` is a number
+ * open([number])        // any array whose position 0 is a number
+ * ```
+ *
+ * @type {_MakeOpen}
+ */
+export declare const open: _MakeOpen;
 export {};

package/fjs/types/rtti/module.f.mjs

@@ -7,7 +7,7 @@
  * @import { Includes } from '../array/types.ts'
  * @import { Assert } from '../../asserts/types.ts'
  * @import { Equal } from '../ts/types.ts'
- * @import { Tag0, Primitive0, _Type0, Bigint, Unknown, Tag1, _MakeType1, Array, Record, Or, Type } from './types.ts'
+ * @import { Tag0, Primitive0, _Type0, Bigint, Unknown, Tag1, _MakeType1, _MakeOpen, _MakeRest, Or, Type } from './types.ts'
  */
 
 import { includes } from '../array/module.f.mjs'
@@ -88,7 +88,7 @@ export const record = type1('record')
  * or canonical-form work. All such algebra lives on the serializable data form
  * — see `./data/README.md`.
  *
- * @template {readonly Type[]} T
+ * @template {readonly Type[]} const T
  * @param {T} types
  * @returns {Or<T>}
  */
@@ -98,7 +98,7 @@ export const or = (...types) =>
 /**
  * Constructs a schema that validates a value matching `T` or `undefined`.
  *
- * @template {Type} T
+ * @template {Type} const T
  * @param {T} t
  * @returns {Or<readonly [T, undefined]>}
  */
@@ -107,6 +107,53 @@ export const option = t =>
 
 /**
  * Schema that never matches any value — the empty union, corresponding to TypeScript's `never`.
+ *
  * @type {Or<readonly []>}
  */
 export const never = or()
+
+/**
+ * Constructs a schema for a container whose **undeclared** members belong to
+ * `r`: the members `c` declares, plus any number of members belonging to `r`.
+ *
+ * A `Struct` or a `Tuple` used on its own is closed — it admits the members it
+ * declares and no others — which is `rest(c, never)` and needs no spelling.
+ * This is how a schema says it wants anything else.
+ *
+ * ```js
+ * rest([number], string)       // one number, then any number of strings
+ * rest({ a: number }, string)  // `a`, plus any number of string-valued keys
+ * open({ a: number })          // `a`, plus anything else
+ * ```
+ *
+ * Both parameters are required. An optional one would need a sentinel for "no
+ * undeclared member", and every candidate — `undefined` most of all — is a
+ * `Type` in its own right, so the sentinel would collide with the schema it
+ * spells. `never` carries no such ambiguity, and a container whose undeclared
+ * members must be the *value* `undefined` states that rest as a wrapped const,
+ * `() => ['const', undefined]`.
+ *
+ * On the array kind `r` constrains the members past the prefix, and a `r` that
+ * admits nothing bounds the array's length — which is what the bare form
+ * already says, so `rest(c, never)` and `c` are one set.
+ *
+ * @type {_MakeRest}
+ */
+export const rest = (c, r) => () => /** @type {any} */ (['rest', c, r])
+
+/**
+ * Constructs a schema for an **open** container: the members `c` declares,
+ * plus any number of members of any kind. `open(c)` is `rest(c, unknown)`.
+ *
+ * Openness is what makes a schema forward-compatible with a serialization
+ * format that has grown fields, so a schema read against a wire format
+ * someone else may extend says `open`.
+ *
+ * ```js
+ * open({ a: number })   // any object whose `a` is a number
+ * open([number])        // any array whose position 0 is a number
+ * ```
+ *
+ * @type {_MakeOpen}
+ */
+export const open = c => /** @type {any} */ (rest(c, unknown))

package/fjs/types/rtti/parse/module.f.d.mts

@@ -5,31 +5,38 @@
  * a `Parse<T>` function. When called with an unknown value, it returns a `Result`
  * that is either `['ok', newValue]` or `['error', { path, message }]`.
  *
- * **Structs and tuples are open.** A value carrying more than the schema
- * declares is accepted; `parse` then returns a freshly constructed value that
- * contains only the declared fields/elements, so the extras are accepted on
- * the way in and absent on the way out:
- *
- * - Tuples: a longer array is accepted; the result has the schema's length.
- * - Structs: undeclared properties are accepted; the result has only the
- *   schema's keys.
+ * **Structs and tuples are closed.** A bare `Struct` or `Tuple` admits the
+ * members it declares and no others, so a value carrying more is rejected:
+ *
+ * - Tuples: an array longer than the schema is rejected — by length as well as
+ *   by member, since a hole past the prefix is no member.
+ * - Structs: an undeclared property is rejected.
  * - Arrays/records: every element/value is itself parsed, so a fresh container is
  *   always returned even if the inner type is a primitive.
  *
- * A member is required exactly when its set excludes `undefined` — an absent
- * member reads as `undefined`, on both kinds — so a shorter array whose
- * trailing position admits `undefined` is accepted and the gap is filled.
+ * Closedness is about *undeclared* members, and leaves the required/optional
+ * rule alone: a member is required exactly when its set excludes `undefined` —
+ * an absent member reads as `undefined`, on both kinds — so a shorter array
+ * whose trailing position admits `undefined` is accepted and the gap is
+ * filled.
+ *
+ * A tuple schema declares by length, so a hole in the *schema* is a declared
+ * position whose schema is `undefined` — see "A hole is a declared position"
+ * in `../README.md`.
  *
- * Openness is what makes this forward-compatible with extended serialization
- * formats: a schema-based parser keeps working when newer versions of the
- * format add extra fields or tuple elements.
+ * The length check is the model rather than an inference from the rendering.
+ * #1622 added one by reading `Ts<readonly[42]>`'s exact tuple as the value
+ * model while the model said open, and was reverted for that reason; what has
+ * changed since is the model, not the reading.
  *
- * **Do not read "the result has the schema's length" as "tuples are closed"
- * and add a length check here.** The set a tuple schema describes includes
- * longer arrays; `Ts<T>` renders the closed approximation only because
- * TypeScript cannot express the open one (see `../ts/types.ts` `TupleTs`), and
- * taking that rendering for the model is what produced #1622. A schema that
- * wants exact members says so — see `../todo/close-type.md`.
+ * **A stated rest widens acceptance, not construction.** `rest(c, r)` holds
+ * every member `c` does not declare to `r`, and `open(c)` — `rest(c, unknown)`
+ * — admits anything else at all; either way the result carries the declared
+ * members and nothing else, so a rest says what an undeclared member must be,
+ * not that the reader should keep it. Openness is what makes a parser
+ * forward-compatible with an extended serialization format, so a schema read
+ * against a wire format someone else may extend says `open`. The reader that
+ * keeps every member is `../validate/module.f.mjs`.
  *
  * The error shape, path bookkeeping, primitive checks, and schema
  * recognition (`visit`) come from `../common/module.f.mjs`.
@@ -38,11 +45,11 @@
  *
  * @module
  *
- * @import { Info1, Struct, Tag1, Tuple, Type } from '../types.ts'
+ * @import { ConstObject, Info1, Tag1, Type } from '../types.ts'
  * @import { Result as CommonResult } from '../../result/types.ts'
  * @import { StringMap } from '../../object/types.ts'
  * @import { List } from '../../list/types.ts'
- * @import { Container, IsContainer, ValidationError, Visitor } from '../common/types.ts'
+ * @import { Container, Fits, IsContainer, SchemaEntries, ValidateE, ValidationError, Visitor } from '../common/types.ts'
  * @import { Unknown } from '../ts/types.ts'
  * @import { Parse } from './types.ts'
  */
@@ -53,5 +60,5 @@ import type { Unknown } from '../ts/types.ts';
 import type { Parse } from './types.ts';
 export type _ItemResult = CommonResult<Unknown, ValidationError>;
 export type _Rebuild = (entries: ReadonlyArray<readonly [string, Unknown]>) => Unknown;
-/** @type {<T extends Type>(rtti: T) => Parse<T>} */
-export declare const parse: <T extends Type>(rtti: T) => Parse<T>;
+/** @type {<const T extends Type>(rtti: T) => Parse<T>} */
+export declare const parse: <const T extends Type>(rtti: T) => Parse<T>;