@scriptc/compiler 0.3.5 → 0.4.0

package/dist/frontend/type-mapper.d.ts

@@ -5,7 +5,11 @@ export { typeKey };
 /** Empty JS object inference describes no fixed layout. Keep these values
  * in checked storage across fields, parameters and function signatures. */
 export declare function jsOpenObjectType(decl: ts.Node | undefined, type: IrType, shapes: ShapeRegistry, unions: UnionRegistry): IrType;
-export declare const FETCH_AMBIENT_TYPES: readonly ["Response", "Request", "ResponseInit", "RequestInit", "Event", "CustomEvent", "EventTarget", "AddEventListenerOptions", "EventListenerOptions", "EventInit", "CustomEventInit", "AbortController", "AbortSignal", "Headers", "ReadableStream", "ReadableStreamDefaultReader", "ReadableStreamDefaultController", "ReadableStreamReadResult", "ReadableStreamReadValueResult", "ReadableStreamReadDoneResult", "Blob", "File", "BlobPropertyBag", "FilePropertyBag", "BlobOptions", "FileOptions"];
+/** The WebCrypto interfaces whose values are checked-dynamic: the crypto
+ * global, SubtleCrypto, CryptoKey handles and the algorithm dictionaries
+ * (scr_webcrypto.c). */
+export declare const WEBCRYPTO_DYN_TYPES: ReadonlySet<string>;
+export declare const FETCH_AMBIENT_TYPES: readonly ["Response", "Request", "ResponseInit", "RequestInit", "Event", "CustomEvent", "MessageEvent", "EventTarget", "AddEventListenerOptions", "EventListenerOptions", "EventInit", "CustomEventInit", "AbortController", "AbortSignal", "Headers", "ReadableStream", "ReadableStreamDefaultReader", "ReadableStreamDefaultController", "ReadableStreamReadResult", "ReadableStreamReadValueResult", "ReadableStreamReadDoneResult", "Blob", "File", "BlobPropertyBag", "FilePropertyBag", "BlobOptions", "FileOptions"];
 /** node:crypto's Cipheriv and Decipheriv names in @types/node. */
 export declare const CIPHER_TYPE_NAMES: ReadonlySet<string>;
 /** True for the parseArgs type family that deliberately rides dyn. Exported
@@ -112,6 +116,24 @@ export declare class ShapeRegistry {
         type: IrType;
     }[], tuple?: boolean, indexValue?: IrType, declaredOrder?: string[]): string;
     get(shapeId: string): IrRecordShape | undefined;
+    /** Names extendShape added to a shape, which every key-order table the
+     * shape adopts lists after its declared names. */
+    private readonly extendedNames;
+    /** The members extendShape attached to a shape (empty for most). */
+    attachedNames(shapeId: string): readonly string[];
+    private withExtendedNames;
+    /** Adds optional fields to an interned shape in place: members a type
+     * assertion attaches to the shape's values (`r as R & { tag: string }`
+     * followed by `view.tag = ...`; see assertion-members.ts). Every value
+     * of the shape holds them absent until a write through such a view, so
+     * the shape keeps its id, both structural keys resolve to it, and its
+     * key-order table lists the new names after the declared ones. Runs
+     * before any body lowers; existing layouts change, so the revision
+     * advances like a closing recursive placeholder. */
+    extendShape(shapeId: string, extra: readonly {
+        name: string;
+        type: IrType;
+    }[]): void;
 }
 /** The frontend's union interner — mirrors ShapeRegistry. A union's
  * canonical identity includes its typeKey-sorted arms and literal
@@ -179,6 +201,20 @@ export declare function execResultShape(shapes: ShapeRegistry): string;
 /** toJSON()'s plain object over an entry: the same fields without the
  * marker. */
 export declare function perfEntryJsonShape(shapes: ShapeRegistry): string;
+/** True when the declaration's nearest enclosing namespace is `name`
+ * (`declare global { namespace NodeJS { ... } }` — the NodeJS-global
+ * interfaces @types/node declares outside any ambient module). */
+export declare function isDeclaredInAmbientNamespace(d: ts.Declaration, name: string): boolean;
+/** Whether `type` is one of the stream spellings the general stream
+ * representation (TypeMapperCtx.generalNodeStreams) maps differently:
+ * NodeJS.ReadableStream / NodeJS.WritableStream, @types/node's
+ * stream.Readable / stream.Writable, or the fallback declarations'
+ * ChildStdin. */
+export declare function isGeneralNodeStreamInterface(type: ts.Type, ctx: Pick<TypeMapperCtx, "isStdlibFile">): boolean;
+/** A type declared in the shipped WebAssembly namespace (scriptc.d.ts):
+ * its modules, instances, memories, tables, globals, error classes and the
+ * Exports/Imports records. */
+export declare function isWebAssemblyType(type: ts.Type, ctx: Pick<TypeMapperCtx, "checker" | "isStdlibFile">): boolean;
 /** True when a type contains a record anywhere (the trigger for the
  * shape-mismatch diagnostic SC2002 — non-record mismatches are tsc's or
  * the validator's business). */
@@ -227,6 +263,17 @@ export type TypeParamTsResolver = (t: ts.Type) => ts.Type | null;
  * one new field here, not a new parameter at every call site. */
 export interface TypeMapperCtx {
     checker: ts.TypeChecker;
+    /** JavaScript declarations whose instance or object-literal types only
+     * the checked-dynamic representation holds (js-dynamic-objects.ts).
+     * Absent when the program has none: every mapping is unchanged. */
+    jsDynamicDeclaration?: (decl: ts.Node) => boolean;
+    /** Set while mapping a generic callable member's erased type
+     * (erasedGenericMemberType): the signature's own type parameters
+     * resolve to `unknown` instead of refusing the mapping. */
+    erasingSignature?: ts.Signature;
+    /** True while an erased generic body lowers (its type parameters are
+     * bound to `unknown`). */
+    isErasing?: () => boolean;
     shapes: ShapeRegistry;
     unions: UnionRegistry;
     classNamer: ClassNamer;
@@ -250,7 +297,10 @@ export interface TypeMapperCtx {
      * inside members, self-referential member types), null outside any
      * mixin context (the type alone cannot name a call site). */
     mixinClassInstance?: (decl: ts.ClassLikeDeclaration) => IrType | null;
-    localClassInstance?: (decl: ts.ClassLikeDeclaration) => IrType | null;
+    localClassInstance?: (decl: ts.ClassLikeDeclaration, instanceType?: ts.Type) => IrType | null;
+    /** The runtime-provided class whose static side a type is (`typeof
+     * EventEmitter`, `ErrorConstructor`), when values of it construct. */
+    runtimeClassValue?: (type: ts.Type) => string | null;
     /** Live class protocols retain identity and receiver dispatch rather than
      * copying an instance into an unrelated record layout. */
     classImplementedProtocol?: (type: ts.Type) => boolean;
@@ -270,6 +320,19 @@ export interface TypeMapperCtx {
      * type descriptions for project-owned values, but their imported runtime
      * bindings are fenced separately by the Lowerer. */
     isExternalTypeFile: (sf: ts.SourceFile) => boolean;
+    /** The program's general stream representation (lowerToIr decides it
+     * per program): NodeJS.ReadableStream / NodeJS.WritableStream and
+     * @types/node's stream.Readable / stream.Writable map to the runtime
+     * stream classes instead of the child/process stdio handles, so values
+     * from every stream producer share their slots. Off (the default), the
+     * stdio handles keep those spellings. */
+    generalNodeStreams?: boolean;
+    /** With generalNodeStreams, the program's checked-dynamic stream slots
+     * (lowerToIr decides it per program, dyn-streams.ts): NodeJS.ReadableStream
+     * and NodeJS.WritableStream map to the checked-dynamic representation, so
+     * a slot holds a native stream (a boxed runtime stream, identity kept) or
+     * a JavaScript stream object. Members dispatch per value at run time. */
+    dynNodeStreams?: boolean;
     /** Successful context-free mappings, keyed by the
      * TypeScript server's stable type id. A generated facade can reference the
      * same large record/function type thousands of times; remapping its full
@@ -293,6 +356,9 @@ export interface TypeMapperCtx {
     /** The InternTable instance type (@scriptc/experimental), when `decl` is
      * that package's class declaration (lowering/intern-tables.ts). */
     internTableClass?: (decl: ts.ClassDeclaration) => IrType | null;
+    /** The ThreadSlots instance type (@scriptc/experimental), when `decl` is
+     * that package's class declaration (lowering/thread-slots.ts). */
+    threadSlotsClass?: (decl: ts.ClassDeclaration) => IrType | null;
 }
 export declare function isLegacyUrlType(type: ts.Type, ctx: Pick<TypeMapperCtx, "checker" | "isStdlibFile">): boolean;
 /** A symbol declared as one of node:url's legacy record interfaces, or as
@@ -310,7 +376,31 @@ export declare function isOsConstantsSymbol(symbol: ts.Symbol | null | undefined
 /** True for a type built only from worker handles, null/undefined, and
  * arrays of those: values that keep the live DYN representation. */
 export declare function isWorkerHandleType(type: ts.Type, ctx: Pick<TypeMapperCtx, "checker" | "isStdlibFile">): boolean;
+/** The return annotation of an `async *` declaration spelled with the
+ * protocol interfaces the generator object implements —
+ * `AsyncIterator<T>`, `AsyncIterableIterator<T>` or `AsyncIterable<T>` (pi's
+ * `async *[Symbol.asyncIterator](): AsyncIterator<T>`): the body always
+ * produces an async generator, so the declaration maps exactly like an
+ * `AsyncGenerator<T, TReturn, TNext>` annotation. Values of these types
+ * elsewhere stay unmapped (they can hold any object implementing the
+ * protocol). Null when the annotation is not one of them. */
+export declare function mapAsyncGeneratorAnnotation(type: ts.Type, ctx: TypeMapperCtx): IrType | null;
+/** The native fetch handles (Headers, Request, Response), optionally in
+ * arrays or with null/undefined: checked-dynamic handles wherever they are
+ * stored, like the worker handles above. */
+export declare function isFetchHandleType(type: ts.Type, ctx: Pick<TypeMapperCtx, "checker" | "isStdlibFile">): boolean;
 export declare function mapType(type: ts.Type, ctx: TypeMapperCtx): IrType | null;
+/** The element types of a REST parameter's type when it is a fixed tuple:
+ * a tuple of required elements (`[number, string]`, the empty `[]`), a type
+ * parameter bound to one, or `Parameters<F>` over a bound function type.
+ * Such a rest parameter has a compile-time arity, so its native ABI is the
+ * flattened positional list (exactly the equivalent fixed signature —
+ * TypeScript treats `(...a: [A, B]) => R` and `(a: A, b: B) => R` alike). */
+export declare function restTupleElementTypes(type: ts.Type, ctx: TypeMapperCtx): ts.Type[] | null;
+/** The mapped element types of a fixed-tuple rest parameter type
+ * (restTupleElementTypes), null when it is not one or an element does not
+ * map. */
+export declare function restTupleParamTypes(type: ts.Type, ctx: TypeMapperCtx): IrType[] | null;
 /** `Partial<T>` / `Readonly<T>` where T is a STILL-GENERIC type parameter —
  * the one mapped-type spelling a monomorphized body can contain that the
  * checker cannot resolve for us (`keyof T` is unknown inside the body, so
@@ -383,6 +473,36 @@ export declare function withUnitArm(t: IrType, kind: "nullT" | "undefinedT", uni
  * Object.keys over such a shape omits the member (a pin — every excluded
  * member is a function the key walk would name). */
 export declare function isGenericCallableMemberType(t: ts.Type, checker: ts.TypeChecker): boolean;
+/** A generic callable member's runtime type: its one call signature with
+ * every own type parameter bound to `unknown`, the erased instance a stored
+ * or escaping definition carries (JavaScript erases type parameters the
+ * same way). Undefined when the member has overloads or the erased
+ * signature does not map: the member then stays out of the shape, and only
+ * calls on a provable definition compile. */
+export declare function erasedGenericMemberType(t: ts.Type, ctx: TypeMapperCtx): IrType | null | undefined;
+/** An OVERLOADED callable member type (`on(event: "a", h: (x: number) =>
+ * void): () => void; on(event: "b", h: (x: string) => void): () => void`
+ * in a program interface or type literal): two or more call signatures and
+ * nothing else (no data properties, construct signatures, or index
+ * signatures), every one declared in TypeScript program source. Such a
+ * member keeps a record slot holding its erased runtime function
+ * (erasedOverloadMemberType); calls convert per their resolved overload
+ * (lowerRecordFieldCall). */
+export declare function isOverloadedCallableMemberType(t: ts.Type, checker: ts.TypeChecker): boolean;
+/** An overloaded member's runtime type (isOverloadedCallableMemberType).
+ * JavaScript stores ONE function under the member; overload signatures only
+ * constrain call sites. The slot's type joins the overloads per parameter
+ * position and result (joinOverloadTypes), and a position some overloads
+ * omit is optional. Each overload's own type parameters erase to `unknown`
+ * first. Calls pick their overload statically, convert arguments into the
+ * slot's parameter types and the result back to the overload's; an
+ * implementation converts into the slot like any function value. Undefined
+ * when the set does not join (rest parameters, a void result beside a
+ * value result, a component outside the checked-dynamic boundary): the
+ * member keeps its fence. */
+export declare function erasedOverloadMemberType(t: ts.Type, ctx: TypeMapperCtx): IrType | undefined;
+/** `any[]` (or `readonly any[]`): an array type whose element is `any`. */
+export declare function isAnyArrayType(t: ts.Type, checker: ts.TypeChecker): boolean;
 /** When an unmapped type is a SUPPORTED container/composite whose failure
  * lives in a component, answer a message tail naming the component (the
  * SC2009 story); null when the shape itself is the blocker (the caller