@geastack/compiler 1.0.15

package/dist/targets/cpp/emit-carrier-members.d.ts

@@ -0,0 +1,406 @@
+import type { DefineOwnPropertyOperation, GetOperation, IrOperand, IrResult, SetOperation } from '../../ir/model.js';
+import type { IrValueId } from '../../identity/ids.js';
+import { type ReactiveRevisionOrigin, type EmitContext, type PrototypeMethodRead } from './emit-context.js';
+import type { Ownership, Representation } from '../../representation/model.js';
+import { type ConversionSite } from './emit-narrowing.js';
+import { type RecordIndexSidecar } from './records.js';
+/**
+ * How a member reads on each built-in carrier.
+ *
+ * These are renderings, not decisions. `emit-properties.ts` remains the one
+ * place that *chooses* which of them a given key means -- its own header
+ * explains why that choice must not be split, and this file does not split it.
+ * What moves here is the mechanical part: given that the receiver is already
+ * known to be an Array, a typed array, a string or a scalar, what text does
+ * the member read render to. Each answers `null` for a receiver that is not
+ * its own, so the caller's dispatch stays a single ordered sequence.
+ */
+export { canonicalIndexLiteral } from '../../representation/array-index.js';
+/**
+ * An element already PROVEN present, written in the result's own carrier, or
+ * `null` when that carrier is not absence-capable and the element stands as it
+ * is.
+ *
+ * Two readers produce a proven-present element and both need this: the guarded
+ * arm of `absentCapableElementText`, whose guard is the proof, and the dense
+ * window's fast path, whose flag is (`ir/dense-loops.ts` admits a window only
+ * for an array with no hole and an index the loop's own bound covers -- the
+ * general form is what runs otherwise). Stating it once is what keeps the two
+ * arms of that window's conditional in one C++ type instead of leaving the
+ * conditional operator to find one through `Optional<T>`'s converting
+ * constructor.
+ */
+export declare const presentElementText: (ctx: ConversionSite, element: Representation, result: IrResult | null, text: string) => string | null;
+/**
+ * Whether an Array member read is a deferred `Array.prototype` METHOD read,
+ * and what it is.
+ *
+ * The one statement of that test. `arrayAccessText` below asks it rather than
+ * repeating it, and so does the walk that settles
+ * `EmitContext.prototypeMethodReads` before a body renders -- one
+ * implementation, two callers, which is what keeps a fact to one authority.
+ * The exclusions are the branches that claim the key FIRST and are therefore
+ * part of the same question: `length`, a field the array's extension declares,
+ * and a canonical index.
+ */
+export declare const deferredArrayMethodClaim: (staticKeyTexts: ReadonlyMap<IrValueId, string>, receiver: IrOperand, key: IrOperand) => PrototypeMethodRead | null;
+export declare const arrayAccessText: (ctx: EmitContext, receiver: IrOperand, key: IrOperand, result: IrResult | null) => string | null;
+/**
+ * The TypedArray reading of a property access, or `null` when the receiver
+ * is not a typed array.
+ *
+ * Unlike `array-object`, a typed array has no ordinary-property domain at
+ * all -- ECMA-262 23.2's integer-indexed exotic object answers every
+ * non-canonical-index key through the ordinary `[[Get]]` this carrier keeps
+ * no table for, so a constant key other than `length` or a canonical index
+ * is refused by name exactly the way `arrayAccessText` refuses one for an
+ * Array.
+ */
+/**
+ * Whether a typed-array member read is a deferred `%TypedArray%.prototype`
+ * method read. Stated once, asked by the renderer below and by the walk that
+ * settles `EmitContext.prototypeMethodReads`. The exclusions are the keys
+ * claimed first and therefore part of the same question: `length`, a canonical
+ * index, and the three block-shaped members `emit-buffers.ts` owns.
+ */
+export declare const deferredTypedArrayMethodClaim: (staticKeyTexts: ReadonlyMap<IrValueId, string>, receiver: IrOperand, key: IrOperand) => PrototypeMethodRead | null;
+export declare const typedArrayAccessText: (ctx: EmitContext, receiver: IrOperand, key: IrOperand, result: IrResult | null) => string | null;
+/**
+ * `absentCapableElementText` for the typed-array reader.
+ *
+ * The same defect and the same cure, one carrier along: under
+ * `noUncheckedIndexedAccess` the checker types `view[i]` as `number |
+ * undefined`, and `TypedArray::elementAt` cannot answer that `undefined` --
+ * it aborts on an index outside the view. Left as the bare reader, this half
+ * is WORSE than the Array half was: `Optional<double>` converts implicitly
+ * from the `double` the reader returns, so the mismatch compiles, and the
+ * program aborts on a read JavaScript answers with a value.
+ *
+ * The payload is required to be a `scalar` rather than converted, because
+ * what `elementAt` produces is not a carrier this backend selected -- the
+ * reader's return type is `double` for all eight views, whatever the element
+ * domain is. Asking `convertedValueText` would mean inventing a source
+ * carrier to ask about; requiring the one payload that reader fits is the
+ * same fact stated where it is true.
+ */
+export declare const absentCapableNumericElementText: (receiverText: string, keyText: string, result: IrResult | null) => string | null;
+/**
+ * The String reading of a property access, or `null` when the receiver is not
+ * a `string`.
+ *
+ * `length` is the only own data property a JavaScript string has; everything
+ * else `String.prototype` exposes is a method, and a method reference is a
+ * `[[Get]]` too -- `s.slice(...)`'s callee is its own `property` operation,
+ * cited by the call the same way a class method's is. Rendering one as a
+ * value needs a receiver-carrying calling convention, and the checker's
+ * structural signature for an ambient interface method (as opposed to a class
+ * method body) carries no `this` parameter -- `structural.ts`'s
+ * `implicitReceiverOf` synthesizes one only for a class's own method, not for
+ * a `lib.es5.d.ts` interface member. Rendering the method anyway would emit a
+ * call that drops the receiver, exactly the mismatch `emit.ts`'s call
+ * emission already refuses by its own fail-closed guard.
+ *
+ * A key naming one of `stringPrototypeMethods` (see `emit-prototype-string.ts`,
+ * the one authority for which those are) is the one exception: instead of rendering the method here, the access
+ * defers -- it records which member was reached off which receiver and
+ * renders nothing, and the following call fuses receiver, method and
+ * arguments into one expression, sidestepping the missing-receiver problem
+ * entirely rather than solving it generically. Every other key is still
+ * refused by name instead of guessed at: the gap is the missing receiver
+ * upstream, not a rendering this file could supply for an unimplemented
+ * method.
+ *
+ * The one key that is neither `length` nor a method is a canonical INDEX --
+ * `s[i]`, ECMA-262 10.4.3's String exotic `[[Get]]`, which answers a
+ * single-code-unit string. See `stringIndexText`.
+ */
+export declare const isDeclaredStringPrototypeKey: (key: string) => boolean;
+/**
+ * A symbol's own `description` -- `Symbol.prototype.description`, ECMA-262
+ * 20.4.3.2, an accessor whose value is `undefined` for `Symbol()` and the
+ * string given otherwise, which is exactly the `gea::Optional<std::string>`
+ * `gea::symbolDescription` answers and the `optional(string)` carrier the
+ * checker's `string | undefined` derives to. test262's `propertyHelper.js`
+ * reads it for every symbol-keyed `verifyProperty`. The other
+ * `Symbol.prototype` members (`toString`, `valueOf`, `[@@toPrimitive]`) are
+ * methods and refuse by name until an invocation asks for them.
+ */
+export declare const symbolMemberText: (ctx: EmitContext, receiver: IrOperand, key: IrOperand, result: IrResult | null) => string | null;
+/**
+ * Whether a String member read is a deferred `String.prototype` method read.
+ * One statement of the test; `stringMemberText` and the prototype-read walk
+ * both ask it.
+ */
+export declare const deferredStringMethodClaim: (staticKeyTexts: ReadonlyMap<IrValueId, string>, receiver: IrOperand, key: IrOperand) => PrototypeMethodRead | null;
+export declare const stringMemberText: (ctx: EmitContext, receiver: IrOperand, key: IrOperand, result: IrResult | null) => string | null;
+/**
+ * `s[i]` -- ECMA-262 10.4.3's String exotic `[[Get]]`.
+ *
+ * The result is a one-code-unit string, and the unit is
+ * `gea::runtime::string::charAt`'s: this backend stores a string as UTF-8 and
+ * the spec indexes it in UTF-16 code units, so `charAt` -- which already owns
+ * that projection (`substringUtf16` over `utf16Length`) -- is where the index
+ * space is decided, rather than restated here where the two could disagree.
+ *
+ * ## Out of range, and the carrier
+ *
+ * The spec's answer for an out-of-range or non-integer index is `undefined`,
+ * and `charAt`'s is the empty string. That divergence is not observable
+ * through the type the checker gives this read: `lib.es5.d.ts` declares
+ * `String`'s index signature `readonly [index: number]: string`, so the result
+ * carrier is `string`, there is no `undefined` in it to produce, and a program
+ * that compares the result against `undefined` is refused by the checker
+ * before this emitter is reached ("types 'string' and 'undefined' have no
+ * overlap"). `arrayAccessText`'s `elementAt` answers an out-of-range Array
+ * index the same way and for the same reason -- the checker types `a[i]` as
+ * `T`, not `T | undefined` -- so this is the backend's existing convention,
+ * not a new one taken here.
+ *
+ * A program compiled with `noUncheckedIndexedAccess` is the case where the
+ * difference IS in the type: the checker then says `string | undefined`, the
+ * carrier is absence-capable, and a bare `std::string` would be the wrong
+ * one. That is refused by name rather than rendered, because producing the
+ * absence needs a materialization this function is not the place to decide.
+ *
+ * The integer guard on the computed path is this access's own rule and not
+ * `charAt`'s: `charAt(1.5)` truncates to 1 and answers a real code unit,
+ * while `s[1.5]` reads the ordinary property `"1.5"`, which a string does not
+ * have. Under a `string` carrier the honest answer for it is the same empty
+ * string every other out-of-range index gets. A constant index has already
+ * been proved canonical by `canonicalIndexLiteral`, so it needs no guard at
+ * all.
+ */
+export declare const stringIndexText: (receiverText: string, indexText: string, result: IrResult | null, staticKey: string | null) => string;
+/**
+ * The scalar reading of a property access, or `null` when the receiver is not
+ * a `scalar`.
+ *
+ * A `scalar` (`number`, `boolean`, `bigint`, ...) has no own data property at
+ * all: `Number.prototype`/`Boolean.prototype` expose only methods (`toFixed`,
+ * `toString`, `valueOf`, ...), never a stored field the way String's `length`
+ * is. So this is `stringMemberText`'s non-`length` branch with nothing left
+ * over to carve out first -- and it defers on the same terms: a key naming one
+ * of `numberPrototypeMethods` records the read and renders nothing, so the
+ * call that follows fuses receiver, method and arguments into one expression.
+ * Every other key is a method reference refused for the identical reason the
+ * String path refuses one: the checker's structural signature for a
+ * `lib.es5.d.ts` interface method carries no `this` parameter, so there is no
+ * receiver a rendered call could close over.
+ */
+/**
+ * A `promise` receiver's members.
+ *
+ * A promise has no data property at all: `then`/`catch`/`finally` are
+ * `Promise.prototype` methods, and the checker's structural signature for one
+ * carries no `this` parameter -- the same missing-receiver reason
+ * `stringMemberText` and `scalarMemberText` state. So `then` defers and fuses
+ * with its call, and every other member is refused by name.
+ *
+ * `finally` is deliberately not deferred. 27.2.5.3 runs its callback on BOTH
+ * settlements and then re-raises the original one -- a fulfilled promise's
+ * value passes through and a rejected promise's rejection is re-thrown after
+ * the callback -- which is a rendering this backend does not have. `catch`
+ * does: `gea::Promise` carries a rejection (an `exception_ptr`, see the
+ * carrier's own comment) and `promiseCatchText` renders the handler over it.
+ */
+/** Whether a Promise member read is a deferred `Promise.prototype` method read. Stated once; the renderer and the walk both ask it. */
+export declare const deferredPromiseMethodClaim: (staticKeyTexts: ReadonlyMap<IrValueId, string>, receiver: IrOperand, key: IrOperand) => PrototypeMethodRead | null;
+export declare const promiseMemberText: (ctx: EmitContext, receiver: IrOperand, key: IrOperand, result: IrValueId | null) => string | null;
+/**
+ * An `iterator` receiver's members -- a generator value or one of the four
+ * fixed-storage cursor sources, all carried as `gea::Iterator<T, TReturn,
+ * TNext>` (`representation/model.ts`'s `iterator` kind) -- of which `next`,
+ * `return` and `throw` are the ones this backend renders.
+ *
+ * Deferred and fused with its call exactly as a Promise member is, and for
+ * the same reason `stringMemberText` states: the ambient `Generator`
+ * interface method has no `this` parameter, so there is no receiver-carrying
+ * calling convention a first-class value could be built from. The claimed
+ * member set is `iteratorPrototypeMethods`'s (`emit-prototype-iterator.ts`),
+ * one authority with the renderer -- and `manifest/capabilities.ts` claims
+ * the same members by name (`iterator(next):get:false`, and its `return`/
+ * `throw` siblings), so a member that reaches here unclaimed is a preflight
+ * defect, reported as one. `iteratorCallText` refines `return`/`throw`
+ * further, by the receiver's own `source` tag, to the one carrier
+ * (`'generator'`) whose real prototype defines them at all.
+ */
+/** Whether an iterator member read is a deferred `%GeneratorPrototype%` method read. Stated once; the renderer and the walk both ask it. */
+export declare const deferredIteratorMethodClaim: (staticKeyTexts: ReadonlyMap<IrValueId, string>, receiver: IrOperand, key: IrOperand) => PrototypeMethodRead | null;
+export declare const iteratorMemberText: (ctx: EmitContext, receiver: IrOperand, key: IrOperand, result: IrValueId | null) => string | null;
+/** Whether a Map/Set/WeakMap/WeakSet member read is a deferred prototype method read. Stated once; the renderer and the walk both ask it. */
+export declare const deferredKeyedCollectionMethodClaim: (staticKeyTexts: ReadonlyMap<IrValueId, string>, receiver: IrOperand, key: IrOperand) => PrototypeMethodRead | null;
+export declare const keyedCollectionMemberText: (ctx: EmitContext, receiver: IrOperand, key: IrOperand, result: IrValueId | null) => string | null;
+/**
+ * `shared-refcount` is a `shared_ptr` and needs `->`; `owned`/`borrowed` are the
+ * struct itself (or a reference to it) and use `.`.
+ *
+ * Lives here rather than in `emit-properties.ts`, where every call site of it
+ * is, because `recordIndexSidecarTableOf` below needs it too and this file
+ * cannot import back from that one (`emit-properties.ts` already imports the
+ * carrier renderers *from* here; the dependency only runs one way). A single
+ * mechanical helper crossing that line is cheaper than reversing it.
+ */
+export declare const memberAccessOperator: (ownership: Ownership) => string;
+/**
+ * The companion revision cell a reactive origin ticks, spelled.
+ *
+ * The fact (`ReactiveRevisionOrigin`) names the owning OPERAND and the field;
+ * the C++ name of that operand exists only once its defining operation has
+ * rendered, which is why the spelling is taken here, at the store that ticks
+ * it, and not at the read that recorded the origin.
+ */
+export declare const reactiveRevisionText: (ctx: EmitContext, origin: ReactiveRevisionOrigin) => string;
+/**
+ * One key, spelled in the domain the keyed container is actually keyed by --
+ * for a struct's index sidecar and for a bare `dictionary` receiver alike.
+ *
+ * A property key is a string in the source language: `a[0]` and `{ [N]: v }`
+ * with `const N = 2` both publish the constant `"0"`/`"2"`, while
+ * `gea::NumericDictionary` is keyed by `double`. The two have to be reconciled
+ * or the emitted subscript does not compile. This is the identical rule
+ * `emit-allocation.ts`'s `emitAllocateDictionary` already applies to the fields
+ * an allocation installs, lifted to one function so an allocation, a later
+ * store and a read cannot end up with three opinions about how a key is
+ * spelled.
+ *
+ * A key whose own carrier already matches the container's domain passes through
+ * untouched -- `strings[i]` with a `double` index is already a `double`. Only a
+ * cross-domain key needs the language conversion. A number used against a
+ * string-keyed sidecar is ordinary `ToPropertyKey`, so it goes through the
+ * backend's exact Number::toString renderer. A string used against a
+ * number-keyed sidecar only passes when it is constant and canonicalizable;
+ * converting an arbitrary runtime string would make `a["01"]` and `a[1]`
+ * name the same slot.
+ */
+/**
+ * An `Object.prototype` method reached through a `dictionary` receiver:
+ * recorded as a deferred prototype read and rendered at the call, exactly as a
+ * String or Date member is.
+ *
+ * Answering `true` means the access produced no C++ of its own and the caller
+ * must return -- the read's value is materialized by
+ * `prototypeMethodCallText`, which fuses receiver and call into one
+ * expression. `false` means this is not one, and every remaining path is
+ * unchanged.
+ *
+ * Only a CONSTANT key is claimed. `bag[k]` with a runtime `k` really is an
+ * index read even when `k` happens to spell `"hasOwnProperty"` at runtime,
+ * and the checker types it as the index's own value; claiming it here would
+ * be this file disagreeing with the carrier the rest of the program agreed
+ * on.
+ */
+/**
+ * Whether a dictionary member read is a deferred `Object.prototype` method
+ * read. Stated once; the renderer and the walk both ask it. Only a CONSTANT
+ * key is claimed -- `bag[k]` with a runtime `k` is an index read even when `k`
+ * happens to spell `"hasOwnProperty"`.
+ */
+export declare const deferredDictionaryMethodClaim: (staticKeyTexts: ReadonlyMap<IrValueId, string>, receiver: IrOperand, key: IrOperand) => PrototypeMethodRead | null;
+export declare const dictionaryPrototypeMemberRead: (ctx: EmitContext, operation: GetOperation) => boolean;
+export declare const keyedTableKeyText: (ctx: EmitContext, key: IrOperand, domain: "string" | "number" | "symbol") => string;
+/**
+ * The dynamic-property sidecar behind a `record-with-index`/`native-record-ref`
+ * receiver, in both spellings a use of it needs -- the identical shape a bare
+ * `dictionary` carrier's own table function returns (`emit-properties.ts`'s
+ * `dictionaryTableOf`), aimed one member deeper at the struct's `gea_dynamic`
+ * field instead of at the receiver itself.
+ *
+ * `record-with-index` carries its `indexes` inline (model.ts); a
+ * `native-record-ref` only names a shape, so its sidecar (if it has one) is
+ * resolved through `records.ts`'s `recordIndexesOfShape` -- the identical
+ * deriver-backed lookup `emit-properties.ts`'s `declaredFieldRepresentation`
+ * already uses for a `native-record-ref`'s named fields, asked for its index
+ * instead of its fields. `null` covers three different receivers with one
+ * answer -- neither carrier, a `record-with-index` (impossible: every one has
+ * an index by construction), and a `native-record-ref` whose named shape has
+ * none -- the last of which is exactly what `preflight/property-access.ts`'s
+ * `nativeRecordRefHasIndexSidecar` already refuses to certify, so an
+ * uncertified program is the only way emission reaches here for one.
+ *
+ * The sidecar field is always embedded *by value* in the struct
+ * (`records.ts`'s `renderStructDefinition`), regardless of the struct's own
+ * ownership -- so reaching the struct itself uses the receiver's own
+ * accessor (`->` for `shared-refcount`, `.` otherwise), and every operation
+ * on the sidecar value it names uses `.`, never a second dispatch on an
+ * ownership the sidecar does not have its own copy of.
+ */
+export declare const recordIndexSidecarTableOf: (ctx: EmitContext, receiver: IrOperand, key: IrOperand) => {
+    readonly member: string;
+    readonly subscript: string;
+    readonly key: string;
+    readonly value: Representation;
+    readonly receiver: string;
+    readonly accessor: string;
+    readonly propertyKey: string;
+    readonly attributes: string;
+    readonly disjoint: boolean;
+    readonly index: RecordIndexSidecar;
+} | null;
+/**
+ * Reading a computed-keyed property out of a `record-with-index`/
+ * `native-record-ref` receiver's dynamic-property sidecar.
+ *
+ * Identical to `emit-properties.ts`'s `dictionaryReadText`, one member
+ * deeper: the checker itself routes a computed numeric/string read of an
+ * interface that mixes named fields with an index signature
+ * (`ArrayLike<number>`) through the index signature rather than through any
+ * specific named field, because a runtime key's identity is not known at
+ * compile time -- so this is reached exactly when
+ * `preflight/property-access.ts` admits it, over the identical
+ * `gea::Dictionary`/`gea::NumericDictionary` machinery, never over a struct
+ * member the checker could not have meant.
+ */
+export declare const recordIndexSidecarReadText: (ctx: EmitContext, operation: GetOperation) => string | null;
+/**
+ * Writing a property that names no declared field -- constant or computed --
+ * into a `record-with-index`/`native-record-ref` receiver's index sidecar.
+ *
+ * The store counterpart of `recordIndexSidecarReadText` directly above, and
+ * built the identical way: `recordIndexSidecarTableOf` already declines a
+ * CONSTANT key that names one of the receiver's own declared fields (the
+ * struct half of the split layout, written by the generic field store at the
+ * end of `emitFieldStoreLines` instead), so asking it is enough to tell the
+ * two halves apart -- this function does not re-decide that split, only
+ * dispatch on its answer. A COMPUTED key can never name a declared field in
+ * the first place (`recordIndexSidecarReadText`'s own comment states why:
+ * the checker itself routes a computed access of a mixed-shape type through
+ * the index signature, never through a named field, because a runtime key's
+ * identity is not known at compile time), so `recordIndexSidecarTableOf`
+ * answers it unconditionally, the same way `record-with-index:get:true`
+ * already claims the read.
+ *
+ * `{ count: 1, 0: 'zero' }` against
+ * `interface Mixed { count: number; [index: number]: string }` is ordinary
+ * TypeScript: `count` is the struct half of the split layout and `0` is the
+ * open half. Only an index signature admits the second key at all -- without
+ * one TypeScript rejects it as an excess property -- so this is reached
+ * exactly when the sidecar is the key's only possible home.
+ *
+ * The read side has resolved both halves since it was written; the store
+ * side originally had a counterpart for the constant half only, so a
+ * constant key that named no field fell through every branch of
+ * `emitFieldStoreLines` to the generic struct-member write at its end and
+ * spelled `receiver->gea_slot_0`, a member `records.ts` never laid out
+ * because it laid out the sidecar instead -- and a COMPUTED key that named no
+ * field fell all the way to `emitNativeSidecarSet`, which reaches this same
+ * receiver but through the wrong table: its own `gea::nativeDynamicSet` is
+ * the BOXED dynamic-property expando a native type's `(this as any)[k] = v`
+ * cast reaches, keyed and valued in `gea::Value`, not the typed table this
+ * carrier's own index signature already states a value carrier for -- so an
+ * array-typed (or otherwise unboxed) sidecar value had no box tag to go
+ * through and refused outright, though the identical value already reads
+ * back correctly through `recordIndexSidecarReadText` on the very same
+ * carrier. Widening this function to the computed case, ahead of
+ * `emitNativeSidecarSet` in `emitFieldStoreLines`'s own dispatch order
+ * (unchanged), is what makes the store side total the way the read side
+ * already is; `emitNativeSidecarSet` keeps its computed-key claim for every
+ * receiver that has no such typed sidecar to route into at all.
+ */
+export declare const recordIndexAttributeKeyText: (index: RecordIndexSidecar, key: Representation, text: string) => string;
+export declare const emitRecordIndexSidecarStore: (ctx: EmitContext, lines: string[], operation: SetOperation | DefineOwnPropertyOperation) => boolean;
+/**
+ * Whether a scalar member read is a deferred `Number`/`BigInt.prototype`
+ * method read. Stated once; the renderer and the walk both ask it.
+ */
+export declare const deferredScalarMethodClaim: (staticKeyTexts: ReadonlyMap<IrValueId, string>, receiver: IrOperand, key: IrOperand) => PrototypeMethodRead | null;
+export declare const scalarMemberText: (ctx: EmitContext, receiver: IrOperand, key: IrOperand, result: IrValueId | null) => string | null;