#1647
Issues/vercel-labs/scriptc/#1647

Clarification / RFC: BigInt(Uint8Array) lowering parity and documentation of runtime-optional storage rules

Openespetroopened 22d ago

Context

Following the investigation in #1644 (Record index-signature read parameter widening) and #1645 (SC2020 diagnostic accuracy), three design and policy questions arose regarding lowering parity and documentation.

Questions for Maintainers

  1. Parity for BigInt(Uint8Array) / BigInt(bytes):

    • In Node.js, BigInt(new Uint8Array([1])) === 1n and BigInt(new Uint8Array([])) === 0n via standard JS ToPrimitive string coercion (multi-element typed arrays throw SyntaxError).
    • Scriptc currently accepts {bigint, string, f64, bool, unit} in lowerBigIntConstructorValue, but omits bytes / Uint8Array.
    • Is extending lowerBigIntConstructorValue to support bytes via runtime dispatch desirable for Node parity?

  2. Diagnostic code policy vs message enhancement:

    • When an expression inside a type guard cannot be lowered because of runtime-optional storage widening, should this eventually receive a dedicated diagnostic code (requiring a surface manifest regeneration), or is refining the existing SC2020/SC1090 message and hint envelope preferred?

  3. Documentation of runtime-optional callee promotion:

    • When indexed reads widen callee parameters to ensure storage safety across call sites, should this rule be explicitly documented under docs/content/limitations/ or types-and-class-definitions/unions.mdx to set expectations for library authors targeting static compilation?

Activity

1
ctate11d ago

Thanks for the questions! Answers below.

  1. Yes, BigInt(Uint8Array) should behave like it does in Node. Node converts the array to a string first, so BigInt(new Uint8Array([1])) is 1n, an empty array is 0n, and an array with more than one element throws a SyntaxError. We'll add support for it in lowerBigIntConstructorValue.

  2. We'd like to keep SC2020 and SC1090 and make their messages and hints more useful, rather than add a new code. #1646 adds the part that's missing today: --explain-dynamic will show which runtime-optional storage decision bypassed the narrowing, and where.

  3. Yes, we'll document the parameter widening from indexed reads. It'll go on the unions page with an example, and the limitations page will link to it.