tsc-ts 0.0.10 → 0.1.0

package/dist/api/compiler/shared-results.d.ts

@@ -0,0 +1,463 @@
+import { type Node, type SourceFile } from './ast.js';
+import type { Checker } from './checker.js';
+import { ConditionalType, LiteralType, ObjectType, TupleType, Type, TypeAlias, UnionType, Signature } from './checker-types.js';
+import { type Symbol } from './symbol.js';
+declare const enum RecordKind {
+    /** A type the checker creates when it starts: `num` is its position in `initialTypes`. */
+    Initial = 0,
+    /** A regular literal type: `flags`, `text` or `num`. */
+    Literal = 1,
+    /** The fresh type of the literal type `refs[0]`. */
+    FreshLiteral = 2,
+    /** The literal type of the enum member `symbol`. */
+    EnumLiteral = 3,
+    /** The unique symbol type of `symbol`. */
+    UniqueSymbol = 4,
+    /** The declared type of `symbol` (class, interface, enum, type parameter). */
+    Declared = 5,
+    /** The this-type of the declared class or interface type of `symbol`. */
+    ThisType = 6,
+    /** The type of the value `symbol` (the anonymous type of a function, class, enum or module). */
+    SymbolType = 7,
+    /** The type of the type node `node` (a type literal, function or constructor type, mapped or conditional type). */
+    NodeType = 8,
+    /** A reference to the generic type `refs[0]` with the type arguments `refs[1..]`. */
+    Reference = 9,
+    /** The tuple target with the element flags `nums`, labeled by `nodes`, readonly when `num` is 1. */
+    TupleTarget = 10,
+    /**
+     * The instantiation of the anonymous, mapped or deferred reference type `refs[0]` with the `num` outer type arguments
+     * after it, then the return types its signatures had resolved (built after it).
+     */
+    Instantiation = 11,
+    /** A union of `refs`, with the origin `num` (a record index, or -1). */
+    Union = 12,
+    /** An intersection of `refs`. */
+    Intersection = 13,
+    /** `keyof refs[0]` with the index flags `num`. */
+    Index = 14,
+    /** `refs[0][refs[1]]` with the access flags `num`. */
+    IndexedAccess = 15,
+    /** The instantiation of the conditional type of `node` with outer type arguments `refs`, for constraints when `num` is 1. */
+    Conditional = 16,
+    /** A template literal type of `texts` and `refs`. */
+    Template = 17,
+    /** The string mapping `symbol` of `refs[0]`. */
+    StringMapping = 18,
+    /** A substitution type of `refs[0]` constrained by `refs[1]`. */
+    Substitution = 19,
+    /** `NoInfer<refs[0]>`. */
+    NoInfer = 20,
+    /**
+     * The member for the constituent `refs[last]` of the distribution of the conditional type of `node` instantiated
+     * with outer type arguments `refs[0..last)`, for constraints when `num` is 1.
+     */
+    DistributedConditional = 21,
+    /**
+     * An anonymous object type of the object literal `symbol` with members resolved when it was created (an object
+     * literal type, or its regular, widened or spread form), with the object flags `flags`. Its members come with the
+     * `CompleteObject` record that follows them.
+     */
+    AnonymousObject = 22,
+    /** The members of the `AnonymousObject` record `num`: the properties `refs` and the index infos `indexInfos`. */
+    CompleteObject = 23,
+    /**
+     * A property symbol a checker created (`text` its name, `flags` its symbol flags, `num` its check flags): its
+     * declarations `nodes`, value declaration `node`, type `refs[0]`, name type `refs[1]` (or -1), the symbol it was
+     * made from `refs[2]` (a property record, or -1 for `symbol`, a symbol of the program) and its parent `aliasSymbol`.
+     */
+    Property = 24
+}
+/** An index signature of an `AnonymousObject` record. */
+export declare class PortableIndexInfo {
+    readonly keyType: number;
+    readonly valueType: number;
+    readonly isReadonly: boolean;
+    readonly declaration: Node | undefined;
+    readonly components: readonly Node[];
+    constructor(keyType: number, valueType: number, isReadonly: boolean, declaration: Node | undefined, components: readonly Node[]);
+}
+export declare class PortableRecord {
+    readonly kind: RecordKind;
+    readonly flags: number;
+    readonly num: number;
+    readonly text: string;
+    symbol: Symbol | undefined;
+    readonly node: Node | undefined;
+    readonly refs: readonly number[];
+    nums: readonly number[];
+    nodes: readonly (Node | undefined)[];
+    texts: readonly string[];
+    /** For a symbol a checker merged: the id of a symbol it merged, which keys every checker's merged symbol. */
+    mergedId: number;
+    /** The alias: its symbol and the records of its type arguments. */
+    aliasSymbol: Symbol | undefined;
+    aliasMergedId: number;
+    aliasRefs: readonly number[];
+    indexInfos: readonly PortableIndexInfo[];
+    /** The producer's type id, which keys the consumer's translations of the producer's types. */
+    readonly id: number;
+    constructor(kind: RecordKind, id: number, flags: number, num: number, text: string, symbol: Symbol | undefined, node: Node | undefined, refs: readonly number[]);
+}
+/** The types every checker creates when it starts, in the same order; marker types are left out. */
+export declare function initialTypes(c: Checker): Type[];
+/** A checker's `Exporter.mergedOrigins`, kept while its merged symbols stay the same. */
+export declare class MergedOrigins {
+    origins: Map<Symbol, number>;
+    size: number;
+}
+/** Writes a result as records; `failure` names the first part that has no record kind. */
+export declare class Exporter {
+    readonly c: Checker;
+    records: PortableRecord[];
+    readonly indexes: Map<Type, number>;
+    /**
+     * The index of `records[0]`. A checker's exporter keeps the indexes of the types it exported before
+     * (`ThreadSharing.post`): their records are in its store already, and a result's records are only the new ones.
+     */
+    base: number;
+    /** The types and properties the export in progress gave indexes, which a failed export forgets again. */
+    readonly addedTypes: Type[];
+    readonly addedProperties: Symbol[];
+    /** Appends `record`; its index. */
+    push(record: PortableRecord): number;
+    readonly initial: Map<Type, number>;
+    failure: string | undefined;
+    /** The ids above which nodes and symbols are the checker thread's own (lazily parsed JSDoc), or Infinity. */
+    nodeLimit: number;
+    symbolLimit: number;
+    constructor(c: Checker, initial: Map<Type, number>);
+    /** Whether `node` is one every checker shares; fails if not. */
+    sharedNode(node: Node | undefined): boolean;
+    /** The ids of the symbols each merged symbol merged (`getMergedSymbol`), built on first use. */
+    mergedOrigins: Map<Symbol, number> | undefined;
+    /** Where the checker keeps `mergedOrigins` between exports. */
+    originsCache: MergedOrigins | undefined;
+    /**
+     * Sets the symbol of `record`: a symbol of the program, which every checker shares, or a symbol the checker merged,
+     * by the id of a symbol it merged. Other symbols are the checker's own.
+     */
+    symbolOf(record: PortableRecord, symbol: Symbol, alias: boolean): boolean;
+    /** `new PortableRecord` with the symbol `symbol` (see `symbolOf`); undefined if it is the checker's own. */
+    withSymbol(kind: RecordKind, t: Type, symbol: Symbol, num: number, refs: readonly number[]): PortableRecord | undefined;
+    addWithSymbol(kind: RecordKind, t: Type, symbol: Symbol, num: number, refs: readonly number[]): number;
+    fail(reason: string): number;
+    add(t: Type, record: PortableRecord): number;
+    types(list: readonly Type[]): number[];
+    aliasOf(record: PortableRecord, alias: TypeAlias | undefined): PortableRecord;
+    type(t: Type): number;
+    literal(t: LiteralType): number;
+    union(t: UnionType): number;
+    object(t: ObjectType): number;
+    /** An object literal type, or one made from one, with its properties and index infos. */
+    anonymousObject(t: ObjectType): number;
+    /** The records of property symbols, by symbol. */
+    readonly properties: Map<Symbol, number>;
+    /** A property symbol of an object literal type: a checker's own, made from one of the program or from another. */
+    property(prop: Symbol): number;
+    tupleTarget(t: TupleType): number;
+    /** An instantiated anonymous or mapped type, or a deferred type reference: its target and outer type arguments. */
+    instantiation(t: ObjectType): number;
+    /**
+     * Adds to `refs` the return types the checker resolved for the signatures of the instantiation `t`, exported after
+     * it. The consumer then creates them right after `t` and before the types that contain it, as this checker did:
+     * inference stops at references whose type ids grow along its stack (`isDeeplyNestedType`), so a consumer that
+     * created them later, when it resolved them, could stop an inference this checker made.
+     */
+    resolvedReturnTypes(t: ObjectType, refs: number[]): void;
+    /**
+     * The record of `t`, or -1 if it can't be exported; that leaves the export in progress as it was. An export that
+     * failed before stays failed.
+     */
+    optionalType(t: Type): number;
+    conditional(t: ConditionalType): number;
+}
+/** Translates records into a checker's own types; one translation per producer type. */
+export declare class Translator {
+    readonly c: Checker;
+    readonly translated: Map<number, Type>;
+    readonly initial: Type[];
+    /** Set when a record has no counterpart here; the translation is then abandoned. */
+    failed: boolean;
+    constructor(c: Checker);
+    /** A property symbol made as the producer made it. */
+    property(r: PortableRecord, types: Type[], symbols: (Symbol | undefined)[]): Symbol;
+    /** Sets the members of the `AnonymousObject` record a `CompleteObject` record completes. */
+    complete(r: PortableRecord, types: Type[], symbols: (Symbol | undefined)[]): void;
+    record(r: PortableRecord, types: Type[]): Type;
+    /**
+     * Resolves the declared type of the type alias whose declaration contains the type node `node`, as resolving its
+     * nodes through the alias does: that records the alias's type parameters, which its variances are measured with.
+     * Sets `failed` if the alias's declared type is being resolved here.
+     */
+    aliasOfNode(node: Node): void;
+    alias(r: PortableRecord, types: Type[]): TypeAlias | undefined;
+    symbol(r: PortableRecord): Symbol;
+    build(r: PortableRecord, types: Type[]): Type;
+}
+/** Whether the type of `symbol` is shared: a variable or property declared in the program, other than parameters. */
+export declare function isSharedValueSymbol(symbol: Symbol): boolean;
+/** Whether the return type of `sig` is shared: the signature of a declaration, as `getSignatureFromDeclaration` makes it. */
+export declare function isSharedReturnSignature(c: Checker, sig: Signature): boolean;
+/** Whether checker threads share results (TSC_TS_SHARE=1). */
+export declare const shareThreads: boolean;
+/**
+ * What a checker thread needs to share results with the others; posted in its `workerData` (a plain object: class
+ * instances arrive without their class).
+ */
+export interface ThreadSharingData {
+    readonly index: number;
+    readonly count: number;
+    /**
+     * For each file, by file index: -2 if no checker checks it, -1 if checkers check it in statement ranges, 0 until a
+     * checker takes it, and 1 + k once checker k took it.
+     */
+    readonly takers: SharedArrayBuffer;
+    /**
+     * For each file, by file index, the checkers (one bit each) that took a result for a declaration in it before any
+     * checker took the file: they never check it, and hand its positions on (`handoff`).
+     */
+    readonly forbidden: SharedArrayBuffer;
+    /**
+     * Positions of the order a checker handed on: a lock, their number, the number of checkers that may still hand
+     * positions on, then the positions.
+     */
+    readonly handoff: SharedArrayBuffer;
+    readonly typeTable: SharedArrayBuffer;
+    readonly returnTable: SharedArrayBuffer;
+    /** The ids above which nodes and symbols are a thread's own. */
+    readonly nodeIds: number;
+    readonly symbolIds: number;
+    /**
+     * Each checker's store of the records of the results it shares, by checker index: their numbers, and the code units
+     * of their strings. `used` has two counters per checker, how much of each it wrote. (Results go through shared
+     * memory: a message a worker receives synchronously makes the native build store the number fields of classes as
+     * doubles.)
+     */
+    readonly numberLogs: SharedArrayBuffer[];
+    readonly stringLogs: SharedArrayBuffer[];
+    readonly used: SharedArrayBuffer;
+    /** For each checker, where each record of its store is in its number log, and each object's completion. */
+    readonly recordTables: SharedArrayBuffer[];
+}
+/**
+ * The size of each checker's logs: numbers (int32s) and string code units (2 bytes each), 8 MB and 2 MB. Only the
+ * pages a checker writes take memory.
+ */
+export declare const numberLogSize: number;
+export declare const stringLogSize: number;
+/** The number of records each checker's store can hold. */
+export declare const recordTableSize: number;
+/** The number of entries of each result table: a power of two. */
+export declare const resultTableSize: number;
+/**
+ * The most checker threads that share results: a result's state (`postedState`) holds the checker and an offset in
+ * its number log, below `numberLogSize` (2^21), in one int32, so the count times 2^21 stays below 2^31 - 2.
+ */
+export declare const maxSharingCheckers = 1023;
+/** The state of the result checker `producer` of `count` posted at `offset` of its number log. */
+export declare function postedState(count: number, producer: number, offset: number): number;
+/** The checker that posted the result of `state`, of `count` checkers. */
+export declare function postedProducer(count: number, state: number): number;
+/** The offset in its producer's number log of the result of `state`, of `count` checkers. */
+export declare function postedOffset(count: number, state: number): number;
+/** The int32 words of each file's forbidden bits (`ThreadSharingData.forbidden`): a bit for each of `count` checkers. */
+export declare function forbiddenWords(count: number): number;
+/** Whether checker `index` of `count` took results for declarations of file `file` before any checker took it. */
+export declare function isForbidden(forbidden: Int32Array, count: number, file: number, index: number): boolean;
+/**
+ * An open-addressing table in a SharedArrayBuffer, from a key (a symbol or node id) to a result's state: 0 until a
+ * checker posts it, then `postedState`.
+ */
+export declare class ResultTable {
+    readonly words: Int32Array;
+    constructor(buffer: SharedArrayBuffer);
+    /** The slot of `key`, inserted if absent; -1 if the table is full. */
+    slot(key: number): number;
+    state(slot: number): number;
+    /** The slot of `key`, or -1 if it has none. */
+    find(key: number): number;
+    /** Sets the state of `slot` to a posted result's unless one is there already. */
+    publish(slot: number, state: number): void;
+}
+/** Sets the sharing data of this checker thread; its first checker shares with the other threads. */
+export declare function setThreadSharingData(data: ThreadSharingData | undefined): void;
+/** Gives `c` the thread's sharing state, if the thread shares and no checker of it has it yet. */
+export declare function startThreadSharing(c: Checker): void;
+/** A checker's state of sharing with the other checker threads. */
+/** A set of ids (symbol or node ids), a bit each. */
+export declare class IdBits {
+    private bits;
+    has(id: number): boolean;
+    add(id: number): void;
+}
+/**
+ * The files of the diagnostics of results, by key (a symbol or declaration id), with a bit per key: most results have
+ * none, and the bit answers that without a lookup.
+ */
+export declare class FilesByKey {
+    private readonly files;
+    private readonly keys;
+    get(key: number): readonly string[] | undefined;
+    set(key: number, files: readonly string[]): void;
+}
+export declare class ThreadSharing {
+    readonly c: Checker;
+    readonly data: ThreadSharingData;
+    readonly types: ResultTable;
+    readonly returns: ResultTable;
+    /** TSC_TS_SHARE_MIN_MS: the shortest computation this checker posts. */
+    readonly minMs: number;
+    readonly initialIndexes: Map<Type, number>;
+    readonly initial: Type[];
+    readonly numberLogs: Int32Array[];
+    readonly recordTables: Int32Array[];
+    readonly stringLogs: Uint16Array[];
+    readonly used: Int32Array;
+    readonly takers: Int32Array;
+    readonly forbidden: Int32Array;
+    /** The number of results this checker posted. */
+    posted: number;
+    translated: number;
+    /** Outermost shared-kind computations: nesting depth, the kind of the current one, and the time by kind. */
+    depth: number;
+    kind: number;
+    readonly kindMs: number[];
+    /** Kinds: 0 owned, 1 computed here for a file another checker took, 2 translated, 3 other. */
+    addOutermost(ms: number): void;
+    notShareable: number;
+    notShareableMs: number;
+    /** Whether the outermost computations are timed by kind (TSC_TS_SHARE_SUMMARY). */
+    readonly timing: boolean;
+    /** TSC_TS_SHARE_VERIFY: translations checked, and those equal only as text. */
+    verified: number;
+    verifiedIdentity: number;
+    belowMin: number;
+    belowMinMs: number;
+    exportFailed: number;
+    exportFailedMs: number;
+    readonly exportFailures: Map<string, number>;
+    packFailed: number;
+    /** Of `packFailed`, the results that didn't fit in this checker's logs. */
+    logFull: number;
+    computedPrivately: number;
+    /** How often a posted result couldn't be taken here; and results for declarations of the checker's own files. */
+    sawDoneUnusable: number;
+    owned: number;
+    unpackMs: number;
+    /** The program's nodes results named, by id. */
+    readonly nodesById: Map<number, Node>;
+    readonly origins: MergedOrigins;
+    translationMs: number;
+    exportMs: number;
+    /** The symbol and signature whose next `getTypeOfSymbol` or `getReturnTypeOfSignature` computes here. */
+    computing: Symbol | undefined;
+    computingSignature: Signature | undefined;
+    /** The value type of `symbol`, or else the return type of `sig`, computed here. */
+    computeHere(symbol: Symbol | undefined, sig: Signature | undefined): Type;
+    /**
+     * The files of the diagnostics each value type (by symbol id) and return type (by declaration id) reported, with
+     * those of the results it used, cached and translated ones too; only for results with diagnostics. A checker that
+     * takes a result checks none of these files, since it would have reported the diagnostics in them.
+     */
+    readonly typeFiles: FilesByKey;
+    readonly returnFiles: FilesByKey;
+    /** The files of the computations in progress, innermost last. */
+    readonly fileStack: (Set<string> | undefined)[];
+    /** Adds `files` to those of the computation in progress. */
+    noteFiles(files: readonly string[] | undefined): void;
+    /** The last `computeShared`: whether its result can be shared, and how long it took. */
+    lastShareable: boolean;
+    lastMs: number;
+    /** `tracked`, recording whether the result can be shared, which it can't when the computation met a resolution cycle. */
+    computeShared(files: FilesByKey, key: number, symbol: Symbol | undefined, sig: Signature | undefined): Type;
+    /** Runs `compute`, keeping in `files` under `key` the files of its diagnostics and of the results it used. */
+    tracked(files: FilesByKey, key: number, symbol: Symbol | undefined, sig: Signature | undefined): Type;
+    constructor(c: Checker, data: ThreadSharingData);
+    summary(): string;
+    /**
+     * Whether this checker checks `file`, or may: a result computed for a declaration in it is never taken here. That is
+     * a file it took, and one checked in statement ranges; a file no checker took yet it never checks once it took a
+     * result for it (`forbid`).
+     */
+    owns(file: SourceFile): boolean;
+    /** After taking a result for a declaration in `file`: if no checker took the file yet, this one never will. */
+    forbid(file: SourceFile): void;
+    /**
+     * Whether taking a result would leave file `index` to no checker: no checker took it, and every other checker
+     * took results for its declarations already. The main thread would check it, alone.
+     */
+    forbidsLast(index: number): boolean;
+    forbidsLastNamed(fileName: string): boolean;
+    forbidNamed(fileName: string): void;
+    filesByName: Map<string, SourceFile> | undefined;
+    ownsFileNamed(fileName: string): boolean;
+    /** The result checker `k` posted at `offset` in its number log. */
+    result(k: number, offset: number): StoredResult;
+    /** The exporter of this checker's store: it exports each type once. */
+    storeExporter: Exporter | undefined;
+    /**
+     * Exports `t` into this checker's store and logs a result with it as the root; returns its state for the result
+     * tables, -1 if it doesn't fit in the logs or a node or symbol in it can't be named across threads, or why it can't
+     * be exported.
+     */
+    post(t: Type, diagnosticFiles: readonly string[]): number | string;
+    /** The records this checker stored. */
+    storedRecords: number;
+    /** The readers of the other checkers' stores. */
+    readonly readers: (StoreReader | undefined)[];
+    /** The translation of `posted` into this checker, or undefined if it can't be taken here. */
+    translatePosted(producer: number, posted: StoredResult, files: FilesByKey, key: number, declarationFile: SourceFile): Type | undefined;
+}
+/** A result in a checker's store: the record of its type, and the files of its diagnostics. */
+export declare class StoredResult {
+    readonly root: number;
+    readonly files: string[];
+    constructor(root: number, files: string[]);
+}
+/** Shares the value type of `symbol` with the other checker threads, computing it with `compute` where needed. */
+export declare function threadTypeOfSymbol(c: Checker, symbol: Symbol): Type;
+/** Notes that the computation in progress used the cached return type of `sig` (see `ThreadSharing.typeFiles`). */
+export declare function noteReturnTypeUse(c: Checker, sig: Signature): void;
+export declare function threadReturnType(c: Checker, sig: Signature): Type;
+/** Reads records from a checker's store. */
+declare class RecordUnpacker {
+    readonly c: Checker;
+    readonly f: Int32Array;
+    readonly strings: Uint16Array;
+    at: number;
+    failed: boolean;
+    /** The nodes found so far, by id. */
+    readonly nodesById: Map<number, Node>;
+    constructor(c: Checker, numbers: Int32Array, strings: Uint16Array, nodesById: Map<number, Node>);
+    next(): number;
+    double(): number;
+    text(): string;
+    list(): number[];
+    node(): Node | undefined;
+    nodes(): (Node | undefined)[];
+    symbol(): Symbol | undefined;
+}
+/**
+ * A consumer's translations of another checker's store: each record is read and translated once, when a result
+ * first needs it, in the order of the store, which is the order the producer exported them in.
+ */
+declare class StoreReader {
+    readonly sharing: ThreadSharing;
+    readonly producer: number;
+    readonly translator: Translator;
+    readonly table: Int32Array;
+    readonly unpacker: RecordUnpacker;
+    /** By record: the record, its translation and whether it is translated. */
+    readonly records: (PortableRecord | undefined)[];
+    readonly types: Type[];
+    readonly symbols: (Symbol | undefined)[];
+    readonly built: number[];
+    constructor(sharing: ThreadSharing, producer: number);
+    private ensure;
+    /** Record `index`, read on first use; undefined if a node or symbol in it isn't in this program. */
+    private record;
+    /** The translation of record `root` and the records it needs; undefined if one can't be translated here. */
+    translate(root: number): Type | undefined;
+}
+export {};