@scriptc/compiler 0.2.6 → 0.2.8

package/dist/frontend/lowering/runtime-optional-elements.d.ts

@@ -0,0 +1,117 @@
+import * as ts from "../ts7/adapter.js";
+/** Program queries the element-state scan needs from the optional-read
+ * analysis. Element keys name a native array's element ABI (`typeKey` of
+ * the element type); arrays only alias other arrays with the same key,
+ * because a conversion to another element type copies the elements and
+ * rejects holes and undefined while it does. */
+export interface ElementStateHost {
+    /** Element keys of every native array `node` can evaluate to: `[]` when
+     * it is not a native array (or is a dynamic value, whose own storage is
+     * separate), `null` when its element ABI is not known yet (a generic
+     * element type). */
+    arrayKeys(node: ts.Expression): readonly string[] | null;
+    /** The element type behind this key admits `undefined` itself. */
+    elementAdmitsUndefined(key: string): boolean;
+    /** The value stored by `node` can be `undefined` at runtime. */
+    mayBeUndefined(node: ts.Expression): boolean;
+    /** A callback argument can return `undefined` at runtime. */
+    callbackReturnsUndefined(node: ts.Expression): boolean;
+    /** The value may be a plain array-like object, whose missing indices
+     * read as undefined. */
+    isArrayLikeObject(node: ts.Expression): boolean;
+    /** The expression's static type is a string. */
+    isString(node: ts.Expression): boolean;
+    /** `node` names the standard global `name` (`Array`, `Object`, ...). */
+    isGlobal(node: ts.Expression, name: string): boolean;
+    /** Element keys of the rest parameter that the spread arguments of
+     * `call` fill: `[]` when the callee has none, null when it is unknown. */
+    restKeys(call: ts.CallExpression | ts.NewExpression): readonly string[] | null;
+    /** Record that iterating `node`'s binding can observe `undefined`;
+     * `known` when the iterated array's own facts (not only those shared by
+     * its element ABI) say so. Returns true when the binding's record grew. */
+    markIterationBinding(node: ts.Identifier, known: boolean): boolean;
+    /** The storage slot that alone owns the array `node` references, whose
+     * facts are tracked for that slot instead of its element ABI. */
+    ownerOf(node: ts.Expression): ts.Symbol | null;
+    /** The owning slot a newly built array is stored into. */
+    allocationOwner(node: ts.Expression): ts.Symbol | null;
+    /** Debug provenance for a new fact. */
+    note: ((fact: "undefined" | "holes", key: string, site: ts.Node | undefined) => void) | null;
+}
+/** Whole-program facts about which native array element ABIs can hold an
+ * explicit `undefined` value or a hole, refined per expression for arrays
+ * an expression creates itself. An element parameter of an array callback
+ * is present whenever its receiver can hold neither: the callback methods
+ * skip holes (except the find family), and every explicit `undefined`
+ * enters a native array through a store, a copy, or a builtin scanned
+ * here. Facts only grow, so the enclosing fixed point stays monotone. */
+export declare class ArrayElementStates {
+    private readonly host;
+    private readonly undefinedKeys;
+    private readonly holeyKeys;
+    /** A store wrote a possibly undefined value or a hole into an array
+     * whose element ABI is decided per generic instantiation. */
+    private anyUndefined;
+    private anyHoley;
+    /** Facts of arrays owned by one storage slot. */
+    private readonly undefinedOwners;
+    private readonly holeyOwners;
+    /** The node being scanned, for provenance notes. */
+    private site;
+    /** While set, arrays judged only by their element ABI count as present. */
+    private ownFactsOnly;
+    constructor(host: ElementStateHost);
+    /** Every element a callback of `method` receives from `receiver` is a
+     * present value. */
+    elementsPresent(receiver: ts.Expression, method: string): boolean;
+    /** Scans one syntax node; true when a fact was added. */
+    scan(node: ts.Node): boolean;
+    /** `[a, ...rest] = source` copies the remaining indices into a new
+     * array: holes become undefined. */
+    private scanRestPattern;
+    /** `[a, ...rest] = source` as an assignment. */
+    private scanRestAssignment;
+    /** Contents of the array `node` evaluates to; null when its element ABI
+     * is generic. Arrays the expression creates are judged by how they are
+     * built; any other array by the facts of its element ABI. */
+    private contents;
+    /** Contents of an array a call creates; undefined when the call is not a
+     * known array constructor or method. */
+    private builtContents;
+    /** The facts recorded for arrays with these element ABIs. */
+    private stored;
+    /** Reading every index of `node` (a spread, an iteration, `Array.from`)
+     * can produce `undefined`. Only native arrays can: other iterables reject
+     * an undefined value when it is stored. */
+    private mayYieldUndefined;
+    /** One stored value, or the elements a spread copies. */
+    private valueMayBeUndefined;
+    /** Records an array the expression creates, for the slot that owns it
+     * or else under its element ABI. */
+    private record;
+    /** Element ABIs of a built array, including those an enclosing type
+     * assertion gives it (`[a, , b] as T[]`). */
+    private keysAsUsed;
+    /** A store through `receiver` can add an undefined value. */
+    private addUndefinedTo;
+    /** A store through `receiver` can leave holes. */
+    private addHolesTo;
+    private addUndefined;
+    private addHoles;
+    private scanAssignment;
+    private scanCall;
+    /** Writes that bypass the array methods: `Object.assign(xs, ...)`,
+     * `Reflect.set(xs, ...)`, `Array.prototype.push.call(xs, ...)` and the
+     * like may store any value at any index of an array argument. */
+    private scanReflectiveWrite;
+    /** A for-of loop over `node`'s iterable can bind `undefined`: a hole
+     * or a stored undefined in the array it walks. When it cannot, every
+     * element the loop reads is a present value. */
+    loopMayYieldUndefined(node: ts.ForOfStatement): boolean;
+    /** The loop's array itself, as built or as owned by one slot, can hold
+     * a hole or undefined. Facts shared by every array with the same element
+     * ABI are coarser: a loop judged only by them keeps checked reads. */
+    private loopHolesKnown;
+    private loopSource;
+    private scanForOf;
+}