@geastack/compiler 1.0.15

package/dist/semantics/normalize/parameter-slot.d.ts

@@ -0,0 +1,264 @@
+import ts from 'typescript';
+import type { StructuralTypeId } from '../../identity/ids.js';
+import type { ParameterBindingCensus } from './parameter-bindings.js';
+import type { IdentityTable } from './identities.js';
+/** The three declaration facts that decide whether a slot has to encode omission. */
+export interface ParameterSlotFlags {
+    readonly optional: boolean;
+    readonly rest: boolean;
+    readonly hasInitializer: boolean;
+}
+/**
+ * What an UNANNOTATED rest parameter's checker-inferred type actually is, when
+ * that type is an open-arity array rather than the closed tuple it might look
+ * like at first read.
+ *
+ * `fetch: (request, Env?, executionCtx?) => ... = (request, ...rest) => {...}`
+ * -- hono's own `Hono.fetch` -- is the concrete case this exists for: the
+ * arrow function's declared type comes from the field it initializes, whose
+ * signature has THREE named parameters and no rest at all. TypeScript's
+ * contextual typing still has to give `rest` SOME type, and does so by
+ * matching the excess of the target signature positionally into a TUPLE --
+ * here `[(E['Bindings'] | {})?, ExecutionContext?]` -- which reads exactly
+ * like a real, closed, two-element shape and is not one: it is the target
+ * signature's tail, re-packaged, and the only reason it has a fixed arity at
+ * all is that the target signature does. A caller of `fetch` is free to pass
+ * zero, one, or two of those trailing arguments -- the language's own rest
+ * binding, unaffected by how the contextual type happened to spell it.
+ *
+ * `structural.ts`'s `typeAt` already reaches exactly this conclusion for a
+ * REFERENCE to such a parameter inside the function's own body (`rest[0]`,
+ * `rest[1]`, a spread) -- see `restParameterArrayElementAt`, which shares
+ * this function's core test. `structural-parts.ts`'s `parameterOf` (the
+ * callable's own published ABI) is a second authority describing the
+ * identical parameter, and calls THIS function (`restParameterArrayTypeOf`)
+ * directly -- it already has the declaration in hand, having resolved it
+ * itself, so it never needed `restParameterArrayElementAt`'s own node-shape
+ * dispatch.
+ *
+ * A THIRD authority describes the same parameter again, through
+ * `restParameterArrayElementAt`, and used to disagree with the other two:
+ * `contributeParameter` (`producers/bindings.ts`) builds the binding that
+ * INITIALIZES `rest` -- the frame slot both the signature and every
+ * body-side read ultimately answer through -- by asking `structural.ts`'s
+ * `typeAt` for the PARAMETER DECLARATION node itself, not a reference to it.
+ * `restParameterArrayElementAt` used to require an identifier
+ * (`ts.isIdentifier(node)`), so that call never reached this collapse at
+ * all and published the checker's raw closed tuple straight into the
+ * binding -- correct for the SIGNATURE (`parameterOf`) and for every
+ * REFERENCE inside the body, wrong for the one binding both of those
+ * actually read through. `restParameterArrayElementAt` now accepts the
+ * declaration node directly (see `restParameterDeclarationAt`, below), so
+ * all three authorities derive the identical collapse from the identical
+ * source and cannot disagree.
+ *
+ * Gated exactly as its body-side counterpart is, for the same reasons:
+ *  - UNANNOTATED only (`declaration.type === undefined`) -- an explicit
+ *    `...args: [string, number]` is the program stating a real, closed
+ *    shape, and this must never override that;
+ *  - the checker's answer must be a tuple with at least one NON-required
+ *    element. A checker-inferred CLOSED tuple (every position required) is
+ *    left exactly alone -- that is a real, settled arity, not an artifact of
+ *    contextual matching against a shorter signature.
+ *
+ * `null` means "the checker's own answer stands", the same safe default
+ * every function in this file shares.
+ */
+/**
+ * The per-position types of a rest parameter whose DECLARED type is a closed
+ * tuple -- every position required, no optional, rest or variadic element --
+ * or `null` for anything else.
+ *
+ * `/** @param {[number, number, number, number, number]} args *\/ function
+ * texStorage2D( ...args ) { gl.texStorage2D( ...args ) }`: three's
+ * `WebGLState.js` as the native-webgl-angle plugin rewrites its `...arguments`
+ * forwarders. The parameter's cell is an array (the rest slot materializes
+ * one), but its declaration states its LENGTH and the type at each position,
+ * and the checker refuses any call that passes a different count. Two
+ * consumers read this one fact: `producers/tuple-spread.ts` expands a spread
+ * of such a parameter into that many constant-index reads, and
+ * `parameter-bindings.ts` hands the callee's formals the position types --
+ * which must agree, or the operands say `number` while the formal's storage
+ * says "unresolved".
+ */
+export declare const declaredClosedTupleRestElementsOf: (checker: ts.TypeChecker, declaration: ts.ParameterDeclaration) => readonly ts.Type[] | null;
+export declare const restParameterArrayTypeOf: (checker: ts.TypeChecker, declaration: ts.ParameterDeclaration) => ts.Type | null;
+/**
+ * The widened element type of an EXPLICITLY ANNOTATED rest parameter whose
+ * declared type is a union of tuples -- `...args: [] | [TNext]`, exactly how
+ * `lib.es2015.generator.d.ts` spells `Generator.prototype.next`'s "zero or one
+ * argument" parameter.
+ *
+ * This says the same thing `[TNext?]` -- one tuple with an optional trailing
+ * element -- would say, in the other of TypeScript's two notations for
+ * variable arity: a single tuple whose optional positions
+ * `restParameterArrayTypeOf` above already widens by reading `elementFlags`
+ * off ONE `TupleTypeReference`. A union of several distinctly-lengthed tuples
+ * is the same fact spread across several types instead of several positions
+ * of one, so this collects every element type out of every arm and widens
+ * across all of them the identical way -- `widestOf` does not care which
+ * tuple or which position an element came from, only whether every element it
+ * is handed agrees on one wider type.
+ *
+ * Left ungated by `declaration.type`, unlike its sibling: there is no bare
+ * checker-inferred form of this shape to guard against overriding -- a
+ * program can only reach a union of tuples here by writing the annotation out
+ * (`restParameterArrayTypeOf` already owns the unannotated, single-tuple
+ * case), so an explicit `[] | [TNext]` is exactly the input this exists to
+ * widen, not a real, closed shape it would be wrong to touch.
+ *
+ * Without this, `structural-parts.ts`'s `parameterOf` finds `declared` is
+ * neither `isArrayType` nor `isTupleType` (a union of tuples is itself
+ * neither), falls into `restNotArrayShaped`'s bare-`any` fallback, and wraps
+ * the WHOLE UNION as if it were one element: `Array<[] | [TNext]>` instead of
+ * `Array<TNext>`. Every call site then argument-packs a raw `TNext` value
+ * against a parameter slot declaring a one-tuple record, which is `next(v)`'s
+ * "passes a scalar argument into a parameter slot carrying record(...)"
+ * emission refusal for any generator whose `TNext` resolved to a native
+ * carrier.
+ *
+ * `widestOf` REFUSING is not a reason to hand the union back untouched. The
+ * arms of a real overload-shaped rest -- hono's `defineWebSocketHelper`,
+ * `...args: [createEvents, options?] | [c, events, options?]` -- state
+ * unrelated types at the same ordinal, so no one element covers the rest, and
+ * before this the whole union fell through to `parameterOf`'s
+ * `restNotArrayShaped` fallback and became `Array<[A, B?] | [C, D, E?]>`:
+ * every element of the array claimed to be a whole argument LIST. That is not
+ * a widening that failed, it is a wrong statement about the value -- the array
+ * holds one argument per slot, never a tuple -- and it is what the binding
+ * (`structural.ts`'s `rest-parameter-array-element`) could never agree with,
+ * since the binding kept the union itself and derived a tagged union of
+ * positional records. The union of every arm's every element states exactly
+ * what the array holds and nothing more, and both authorities derive it from
+ * this one function, so they cannot disagree about it.
+ *
+ * An optional position's `undefined` is dropped from that union, for the reason
+ * `impliedPatternElementOfArms` below already states about the same kind of
+ * evidence: a position's `undefined` is POSITIONAL -- an arm that is shorter,
+ * or a trailing `options?` nobody passed -- and the READ past the end of the
+ * array is what supplies it, per position. Keeping it would wrap the whole
+ * element in `optional(...)`, which says every slot of the array may be absent
+ * even where an arm requires one.
+ */
+export declare const restParameterUnionOfTuplesElementTypeOf: (checker: ts.TypeChecker, declared: ts.Type) => ts.Type | null;
+/**
+ * The type the physical parameter SLOT holds.
+ *
+ * An omitted argument is `undefined`, and a defaulted parameter's initializer
+ * runs inside the callee over exactly this slot, so an optional or defaulted
+ * slot has to hold `undefined` alongside whatever the body ends up binding.
+ *
+ * The widening is done as a TYPE, by the checker, rather than as an absence
+ * flag layered over an already-derived carrier. Those two are not the same
+ * answer: a flag can only say "absent or not", so a parameter whose declared
+ * type already spends absence on `null` -- `f(x: T | null = null)`, and the
+ * JSDoc spelling `@param {?T} [x=null]` that three.js writes throughout -- had
+ * no state left to say WHICH absent value it holds, and was refused outright.
+ * As a type it is just a three-armed union, which `representation/union.ts`
+ * has always carried as a tagged union with a `null` arm, an `undefined` arm
+ * and a `present` arm.
+ *
+ * `getNullableType` is the same public API TypeScript's own `addOptionality`
+ * uses, and it flattens: the result is one flat union, never a union nested
+ * inside a union, which matters because the two are different interned shapes
+ * and only the flat one derives to the three-armed carrier.
+ *
+ * A rest parameter is left alone -- its declared type is already the array the
+ * language binds, and there is no omission to encode.
+ */
+export declare const parameterSlotTypeOf: (internUnion: (members: readonly StructuralTypeId[]) => StructuralTypeId, undefinedType: StructuralTypeId, flags: ParameterSlotFlags, type: StructuralTypeId) => StructuralTypeId;
+/**
+ * AN UNANNOTATED REST PARAMETER IS ALWAYS AN ARRAY AT RUNTIME, WHATEVER
+ * ARITY-TRACKING TUPLE THE CHECKER GAVE IT FOR CHECKING PURPOSES.
+ *
+ * `FunctionDeclarationInstantiation` (ECMA-262 10.2.11 step 28) binds a rest
+ * parameter to a fresh `Array`, unconditionally -- that is what the value
+ * physically is, regardless of how the checker typed the binding. When an
+ * unannotated `...args` is contextually typed against a target with more
+ * than one possible tail shape -- an overloaded call type
+ * (`hono/src/context.ts`'s `NewResponse` has two signatures, `(data,
+ * status?, headers?)` and `(data, init?)`), or a single signature with its
+ * own optional trailing parameters -- the checker states that as a TUPLE
+ * with optional/rest/variadic elements, one arity per possible call shape
+ * joined into one type. That tuple is real and correct for checking a call
+ * `args` is forwarded into, but it does not describe `args` itself: the
+ * program never wrote a fixed-arity value there, and no two calls into this
+ * function are required to pass the same number of arguments.
+ *
+ * `tuple-spread.ts`'s `closedTupleElementTypesOf` already refuses to expand
+ * exactly this shape positionally (an optional/rest/variadic element means
+ * the arity is not settled), which is correct -- but leaving the binding
+ * typed as a tuple after that refusal is what actually breaks: representing
+ * an open-arity tuple needs a dictionary-shaped carrier with no
+ * `[Symbol.iterator]`, so every consumer that needs to iterate or
+ * range-copy `args` (a spread into another call, `for`-`of`) is refused for
+ * a reason that names a carrier this value was never supposed to have.
+ * Collapsing it to the array it actually is restores the native iteration
+ * cursor `hasNativeIterationCursor` already grants any other `T[]`.
+ *
+ * Gated tightly, to touch only the binding itself:
+ *  - the parameter must be UNANNOTATED (`declaration.type === undefined`).
+ *    An explicit `...args: [string, number]` is the program stating a real,
+ *    closed shape, and this must not override that;
+ *  - the checker's type must be a tuple whose elements are NOT all
+ *    `Required` -- a checker-inferred CLOSED tuple (every position
+ *    required, one arity) is left alone: `tuple-spread.ts` already expands
+ *    that positionally, and collapsing it here would throw away real
+ *    per-position typing a sound expansion could still use.
+ *
+ * The array's element type is `widestOf` the tuple's own elements -- the
+ * same join two `return` statements or two branches of a conditional must
+ * already agree through (`derived-expression-type.ts`). When every element
+ * genuinely joins under one type, using it keeps a well-typed forwarding
+ * array native instead of boxing it. When no single element type covers
+ * every position (`widestOf` refuses), this refuses too, rather than
+ * inventing a join the checker never stated -- the existing tuple/record
+ * path is the fallback, unchanged.
+ */
+export declare const restParameterArrayElementAt: (checker: ts.TypeChecker, identities: IdentityTable, node: ts.Node) => ts.Type | null;
+/**
+ * The body-side entry to `restParameterUnionOfTuplesElementTypeOf` above --
+ * the same collapse `structural-parts.ts`'s `parameterOf` applies to the ABI
+ * slot, reached from either shape a node names (`restParameterDeclarationAt`).
+ *
+ * That collapse was wired into `parameterOf` alone when `Generator.next`'s
+ * `[] | [TNext]` needed it, re-opening exactly the disagreement this file's
+ * header describes: the ABI published `array-object(...)` for a rest
+ * parameter annotated as a union of tuples while the binding kept the
+ * checker's raw union, which `derive.ts` lays out as a tagged-union of
+ * positional records once any arm has a non-uniform or optional position.
+ * `projection/abi.ts` then refused the function -- hono's
+ * `defineWebSocketHelper` (`...args: [createEvents, options?] | [c, events,
+ * options?]`) with 'parameter 0 is bound as "tagged-union(...)" but the ABI
+ * declares "array-object(...)"'. `[] | [T]` never showed it only because both
+ * arms happen to derive to the array carrier anyway. The ABI is the right
+ * authority: FunctionDeclarationInstantiation binds a rest parameter to one
+ * fresh Array whatever static shapes describe it, and `packRestArguments`
+ * has no convention for a discriminated rest slot.
+ */
+export declare const restParameterUnionOfTuplesElementAt: (checker: ts.TypeChecker, identities: IdentityTable, node: ts.Node) => ts.Type | null;
+/**
+ * `restParameterArrayElementAt`'s sibling for CALL-SITE evidence rather
+ * than the checker's own contextual-tuple widening: `parameter-bindings.ts`'s
+ * `restElementTypeAt` joins the actual arguments every reachable call passes
+ * at or past the rest parameter's own ordinal, which is real evidence about
+ * what the array holds and outranks a bare checker guess -- the same
+ * priority `structural-parts.ts`'s `parameterOf` already gives an ordinary
+ * parameter's census answer over `restArray`. Resolves the same DECLARATION
+ * `restParameterArrayElementAt` does, from either shape a node names, so a
+ * body-side reference (`structural.ts`'s `typeAt`) and the ABI's own slot
+ * (`parameterOf`) read the identical fact and cannot disagree about it.
+ */
+export declare const censusRestElementAt: (checker: ts.TypeChecker, identities: IdentityTable, parameters: Pick<ParameterBindingCensus, "restElementTypeAt">, node: ts.Node) => ts.Type | null;
+/**
+ * Whether every holder PROVES a value at `position`: each arm is a tuple whose
+ * required prefix reaches past it. The pattern reads out of the array the
+ * parameter stores, so a position is `element | undefined` in general -- but
+ * `[x, y = 2] = [1]` reached only as `m()` never leaves `x` absent, and
+ * spelling it optional there hands `x + y` an optional operand for nothing.
+ * A plain-array arm proves no position; an optional tuple element proves none
+ * either.
+ */
+export declare const impliedPatternPositionPresentEverywhere: (checker: ts.TypeChecker, holders: readonly ts.Type[], position: number) => boolean;
+export declare const impliedPatternElementOfArms: (checker: ts.TypeChecker, holders: readonly ts.Type[], pattern: ts.ArrayBindingPattern) => ts.Type | null;
+export declare const impliedPatternArrayElementAt: (checker: ts.TypeChecker, parameters: ParameterBindingCensus, node: ts.Node) => ts.Type | null;