@geastack/compiler 1.0.15

package/dist/targets/cpp/host/object-protocol.d.ts

@@ -0,0 +1,351 @@
+import type { RecordField, Representation } from '../../../representation/model.js';
+import type { GetOperation, IrOperand } from '../../../ir/model.js';
+import { type EmitContext, type PrototypeMethodRead } from '../emit-context.js';
+import type { IrValueId } from '../../../identity/ids.js';
+/**
+ * The object primitives every `Object` static is defined in terms of.
+ *
+ * ECMA-262 does not define ten independent operations. It defines three --
+ * `[[OwnPropertyKeys]]` filtered by `[[Enumerable]]`, `Get(o, key)` and
+ * `Set(o, key, v)` -- and then writes each static as a loop over them.
+ * `Object.assign` is the clearest case (7.3.25 is literally "for each own
+ * enumerable key of source: Set(target, key, Get(source, key))"), but
+ * `Object.keys`, `values`, `entries`, `hasOwn` and `fromEntries` are the same
+ * three in different arrangements, and so are `{...spread}`, rest
+ * destructuring, `for...in` and `JSON.stringify` of a plain object.
+ *
+ * So this file states the three once and `emit-host-object.ts` spells each
+ * member as the loop it is. The alternative -- which is what was here before
+ * -- is ten renderers that each rediscover the receiver question, agree on the
+ * refusal (`refuseObjectCarrier` was already shared) and disagree on
+ * everything else: `keys` and `values` grew a static arm, `entries`, `assign`
+ * and `defineProperty` refused every known shape outright, and the refusal
+ * they printed explained enumeration even when the member was not enumerating
+ * anything. `Object.assign(this, opts)` in hono's own constructor refused with
+ * "a class instance's own enumerable keys are the fields its constructor
+ * actually assigned" -- a true sentence about the SOURCE position, printed for
+ * a failure in the TARGET position, where nothing enumerates the class at all.
+ *
+ * ## The two arms
+ *
+ * Each primitive has a static arm and a dynamic one, and neither is the
+ * other's fallback.
+ *
+ * The static arm renders against a carrier whose fields the checker knows. The
+ * key list is a compile-time constant, `Get` is a struct member read and `Set`
+ * is a struct member store -- the loop is unrolled at emission because its
+ * bounds are known, which is the same move `Object.values` already made when
+ * it emitted a braced `std::vector` rather than a runtime walk.
+ *
+ * The dynamic arm renders against a value the program itself declared `any`.
+ * There the loop belongs to the runtime, because its bounds are only known
+ * there, and `gea::host::ObjectConstructor` states each member as one call.
+ *
+ * ## The third arm, which is not this file's
+ *
+ * Every struct this backend emits also carries the three primitives as
+ * methods: `gea_ownFieldKeys`, `gea_readOwnField` and `gea_writeOwnField`
+ * (`records.ts`'s `renderFieldDispatcher`). That is the same three operations
+ * for the case where the OBJECT is statically known and the KEY is not, and it
+ * shares this file's enumeration order through `enumerationOrdered` so the two
+ * cannot answer a different key sequence for one struct. Nothing here calls
+ * it: when the key is known too, a direct member access is what the dispatcher
+ * would find anyway, without the round trip through `gea::Value` it takes to
+ * carry a field past a `PropertyKey`.
+ */
+/** Whether a carrier is the genuine dynamic boundary these renderers walk a real table for. */
+export declare const isDynamicCarrier: (representation: Representation) => boolean;
+export declare const refuseObjectCarrier: (member: string, representation: Representation, detail: string) => never;
+/**
+ * A receiver whose own properties this file can name, or the dynamic object
+ * whose table the runtime walks.
+ *
+ * `fields` is the static arm's whole subject: the key list, the read and the
+ * store all come from it. `receiver`/`accessor` are how a field of it is
+ * spelled, which differs by ownership and not by carrier kind -- a `record`, a
+ * `native-record-ref` and a `class-ref` are all struct members behind either
+ * `.` or `->`.
+ */
+export type ObjectView = {
+    readonly kind: 'known';
+    readonly representation: Representation;
+    readonly fields: readonly RecordField[];
+    readonly receiver: string;
+    readonly accessor: string;
+} | {
+    readonly kind: 'dynamic';
+    readonly receiver: string;
+}
+/**
+ * A `gea::Dictionary<V>` receiver -- the THIRD shape with a real
+ * own-property enumeration, and the one this family used to refuse by name.
+ *
+ * That refusal read "gea::Dictionary is a std::map, so its keys are sorted
+ * rather than kept in creation order", and it stopped being true when the
+ * container was reimplemented as a `std::deque` of entries in creation order
+ * with a position index beside it. The runtime states 10.1.11 order on the
+ * container itself (`Dictionary::propertyKeys`, whose own comment points at
+ * this file's refusal as the gap it was waiting for), so a dictionary
+ * enumerates exactly as soundly as a record does -- and unlike a record it
+ * needs no field list, because the keys are the table's runtime contents.
+ *
+ * `receiver` is already dereferenced to the table itself: every member here
+ * passes it to a runtime overload taking `const gea::Dictionary<V>&`, and
+ * whether the carrier held it behind a `gea::Ref` is not their question.
+ */
+ | {
+    readonly kind: 'dictionary';
+    readonly representation: Extract<Representation, {
+        kind: 'dictionary';
+    }>;
+    readonly receiver: string;
+    readonly value: Representation;
+};
+/**
+ * The refusal every member shares for a receiver that is neither a known shape
+ * nor a declared dynamic value.
+ *
+ * Stated once so the ten members cannot drift into ten different explanations
+ * of the same fact, and phrased as what is missing rather than as what was
+ * asked -- a `dictionary` receiver is a gap in the container, not in the call.
+ *
+ * `position` names which of the call's objects failed, because these members
+ * take more than one and a refusal that does not say which is a report nobody
+ * can act on: `Object.assign(target, source)` refusing "of a class-ref
+ * carrier" left a reader to guess whether the class was the thing being
+ * enumerated or the thing being written into, and those have different cures.
+ */
+export declare const refuseObjectReceiver: (member: string, representation: Representation, position: string) => never;
+/** The caller supplies the value produced by its certified conversion. */
+export declare const setOwnCallableText: (receiver: string, key: string, value: string) => string;
+/**
+ * The receiver question, answered once.
+ *
+ * Every member of this family asks it and none of them may answer it
+ * differently, which is the reason this returns a view rather than a boolean:
+ * a member that tested `isDynamic` itself and then re-derived the field list
+ * is two answers to one question, and that is how `assign` came to refuse a
+ * shape `keys` renders.
+ */
+export declare const objectViewOf: (ctx: EmitContext, member: string, operand: IrOperand, position: string) => ObjectView;
+/**
+ * The same question asked of a carrier and a spelling rather than an operand,
+ * for the one caller that has neither: a TAGGED UNION receiver is enumerated
+ * arm by arm (`emit-host-object.ts`'s `overCarrier`), and an arm is a
+ * representation plus a `get<N>()` text, never an operand of its own.
+ */
+export declare const objectViewFrom: (ctx: EmitContext, member: string, representation: Representation, receiver: string, position: string) => ObjectView;
+/**
+ * The refusal for a member that HAS a sound dictionary rendering nobody has
+ * written yet, stated by name.
+ *
+ * Kept apart from `refuseObjectReceiver` for the reason this file's header
+ * gives about `freeze` and `defineProperty`: "this carrier cannot be
+ * enumerated" and "this carrier can, and this member's arm for it is missing"
+ * are different facts with different cures, and reporting the second as the
+ * first sends a reader to the wrong one.
+ */
+export declare const refuseDictionaryArm: (member: string, view: Extract<ObjectView, {
+    kind: "dictionary";
+}>, detail: string) => never;
+/**
+ * PRIMITIVE 1a -- `[[Enumerable]]`: whether this field is an own key at all,
+ * as C++ that answers at run time, or `null` when it statically is one.
+ *
+ * A field the declaration makes OPTIONAL is not statically present: `{ a: 1 }`
+ * typed `{ a: number; b?: number }` has one own key, not two, and treating a
+ * fixed list of both as the key set would report a property that is not there.
+ * So an optional field answers from the independent presence bit emitted next
+ * to its value. This remains exact for `undefined`, `null`, and dynamic value
+ * carriers because none of those values doubles as property absence.
+ */
+export declare const ownKeyPresenceText: (member: string, view: Extract<ObjectView, {
+    kind: "known";
+}>, field: RecordField) => string | null;
+/**
+ * PRIMITIVE 1 -- `[[OwnPropertyKeys]]`, filtered to own enumerable string keys.
+ *
+ * ECMA-262 10.1.11.1 order, from the same authority the emitted struct's own
+ * `gea_ownFieldKeys` uses (`enumerationOrdered`) -- two lists of one object's
+ * own keys that could disagree is exactly the shape this compiler keeps
+ * finding. A view whose fields are all statically present renders as a flat
+ * constant; one with an optional field renders as the push loop, with the
+ * optionals IN PLACE rather than appended after the required ones, since a
+ * present optional occupies its own creation position.
+ */
+/** A known view's fields in enumeration order -- the one place that order is decided, so a member's keys and its values cannot disagree about it. */
+export declare const ownKeyFields: (view: Extract<ObjectView, {
+    kind: "known";
+}>) => readonly RecordField[];
+export declare const ownEnumerableKeysText: (member: string, view: ObjectView, dynamicCall: string) => string;
+/**
+ * PRIMITIVE 2 -- `Get(o, key)` for one own key of a known view.
+ *
+ * Presence is stored separately, so the field's value carrier comes through
+ * unchanged. In particular, a present `undefined` stays `undefined`; it is not
+ * unwrapped or confused with the missing-key state.
+ *
+ * There is no dynamic arm. A per-key get on a value the runtime owns is a
+ * `gea::runtime::object::get` call, and no member here needs one: the dynamic
+ * arm of every member in this family expresses its whole loop as a single
+ * runtime call, so the iteration and the get stay on the same side.
+ */
+export declare const getOwnValue: (ctx: EmitContext, view: Extract<ObjectView, {
+    kind: "known";
+}>, field: RecordField) => {
+    readonly text: string;
+    readonly representation: Representation;
+};
+/**
+ * PRIMITIVE 3 -- `Set(o, key, v)` into one own key of a known view.
+ *
+ * The store's own carrier comes from `declaredFieldRepresentationOf`, the one
+ * authority `emitFieldStore` and `emitFieldInits` already ask, so this cannot
+ * become a second opinion about what a field holds; and the value is
+ * reconciled against it through `convertedValueText`, the same one an ordinary
+ * store uses. A pair with no installed conversion refuses by naming both
+ * carriers rather than assigning across and leaving clang to reject it.
+ *
+ * There is no dynamic arm here either, and for the same reason as `Get`.
+ */
+export declare const setOwnText: (ctx: EmitContext, member: string, view: Extract<ObjectView, {
+    kind: "known";
+}>, key: string, value: {
+    readonly text: string;
+    readonly representation: Representation;
+}) => string;
+/**
+ * `hasOwnProperty`/`propertyIsEnumerable` reached as INSTANCE methods off a
+ * known-shape receiver (`record`/`native-record-ref`/`class-ref`) -- the
+ * method-call spelling of the identical question `Object.hasOwn` already
+ * answers off the same layout (`hasOwnText` above).
+ *
+ * Left unclaimed, the checker still resolves `{ a: 1 }.hasOwnProperty` (every
+ * object type structurally carries `Object.prototype`), and the record's own
+ * field list has no member of that name -- so the generic dynamic-property
+ * sidecar (`emit-dynamic-properties.ts`'s `nativeSidecarGetText`) answered it
+ * instead, BOXING a statically known fact into a `gea::Value`-carried
+ * `CallableObject` purely to call it once. That is the forbidden shortcut the
+ * "no boxing" rule names: the record's own layout is a typed fact, and it has
+ * no business inside a box just because the member that reads it is an
+ * ambient `Object.prototype` declaration rather than one the record's own
+ * shape states.
+ *
+ * Deferred exactly the way `dictionaryPrototypeMemberRead`
+ * (`emit-carrier-members.ts`) defers `hasOwnProperty` off a dictionary: the
+ * GET renders nothing, and the CALL that follows fuses receiver, key and
+ * field list into one expression (`objectShapeCallText` below).
+ *
+ * The set itself lives in `projection/callee.ts`: the slot census's
+ * `calleeRenderingOf` states the identical claim (a call through one of
+ * these names renders from a template, not `Object.prototype`'s declared
+ * convention) so the two do not drift into a printer that claims one set of
+ * calls and a census that converts arguments for a different one.
+ */
+/**
+ * The claim, asked at the `[[Get]]`.
+ *
+ * Gated on the receiver representation BEFORE `objectViewFrom` is ever asked:
+ * that function THROWS for a receiver it cannot enumerate (a `dictionary`
+ * already has its own claim; a `dynamic` receiver is a genuine boundary whose
+ * `hasOwnProperty` really does need the runtime table), and this claim must
+ * answer `false` for those rather than refuse a program this file was never
+ * meant to gate.
+ */
+/**
+ * Whether a known-shape receiver's `hasOwnProperty`/`propertyIsEnumerable` is
+ * a deferred `Object.prototype` read, and what the call needs from it.
+ *
+ * Stated once; the renderer below and the prototype-read walk both ask it.
+ * `objectViewFrom` is the authority for what a known shape's fields and member
+ * accessor are, so it is asked here rather than re-derived -- with an empty
+ * receiver TEXT, because the `known` arm's `fields` and `accessor` do not
+ * depend on it and the receiver is spelled at the call from the operand this
+ * record carries.
+ */
+export declare const deferredObjectShapeMethodClaim: (ctx: EmitContext, operation: GetOperation) => PrototypeMethodRead | null;
+export declare const objectShapePrototypeMemberRead: (ctx: EmitContext, operation: GetOperation) => boolean;
+/**
+ * The call text for a deferred `hasOwnProperty`/`propertyIsEnumerable` read.
+ *
+ * A literal key answers at compile time, exactly as `Object.hasOwn` does for
+ * one. A key only known at runtime dispatches over the SAME finite field set
+ * a static receiver's own computed key already switches over
+ * (`emit-dynamic-properties.ts`'s `constructorFamilyComputedGetText` is the
+ * reference for the shape): every field the layout declares gets one `if`
+ * arm, and a key naming none of them is not an own property. Only a string
+ * key is admitted -- ToPropertyKey of anything else is a question `hasOwnText`
+ * above refuses too, and a record's fields are never symbol- or number-keyed.
+ *
+ * Presence and enumerability are separate native metadata. defineProperty
+ * can make a present fixed field non-enumerable without moving its value to
+ * a dynamic sidecar; the query must read that stored attribute too.
+ */
+export declare const objectShapeCallText: (ctx: EmitContext, member: string, receiver: string, accessor: string, fields: readonly RecordField[], args: readonly IrOperand[]) => string;
+/**
+ * `hasOwnProperty`/`propertyIsEnumerable` off a `native-handle` receiver
+ * (`Math.hasOwnProperty(...)`, or `Object.prototype.hasOwnProperty.call(Math,
+ * ...)` after the borrowed-call rewrite), for the SAME finite own-member list
+ * `getOwnPropertyDescriptorText`'s native-handle arm reads
+ * (`ctx.hosts.intrinsicMembers`) -- see that table's own comment for where it
+ * comes from and why it is never hand-listed here.
+ *
+ * `propertyIsEnumerable` needs no key at all: ECMA-262 specifies every own
+ * member of a host intrinsic non-enumerable, whether it is a data constant
+ * (21.3.1) or a builtin method (10.2.4) -- so the honest answer is `false`
+ * unconditionally, the same fact `emitNativeHandleEnumerateIterator`
+ * (`emit-iterator.ts`) already renders as an always-empty `for`-`in` walk.
+ * Asking `hasOwnProperty` first and `false` never matters because
+ * `propertyIsEnumerable` of an ABSENT key is `false` too -- one constant
+ * covers both cases of ECMA-262 20.1.3.7's own two-step definition.
+ *
+ * `hasOwnProperty` is real membership: a literal key folds against the list
+ * at compile time, and a runtime key becomes a switch over it, mirroring
+ * `objectShapeCallText`'s own two arms for a record receiver.
+ */
+/**
+ * `fn.hasOwnProperty(k)` / `fn.propertyIsEnumerable(k)`: the callable's own
+ * properties are its one shared function-object table, with the `name`/
+ * `length` facts installed first so both answer for them (10.2.10: present,
+ * non-enumerable) exactly as `callableDynamicGet` sees them.
+ */
+export declare const callableShapeCallText: (ctx: EmitContext, member: string, receiver: string, args: readonly IrOperand[]) => string;
+export declare const nativeHandleShapeCallText: (ctx: EmitContext, member: string, protocol: string, args: readonly IrOperand[]) => string;
+/**
+ * `hasOwnProperty` off a receiver the program itself declared dynamic (a
+ * `--dynamic-fallback` boxed value carrying a real `gea::DynamicObject`).
+ *
+ * `objectShapePrototypeMemberRead` above deliberately answers `false` for one
+ * of these (`known` excludes `'dynamic'`) rather than claim it, and its own
+ * comment says why: "a `dynamic` receiver is a genuine boundary whose
+ * `hasOwnProperty` really does need the runtime table". This is that table --
+ * `gea::runtime::object::hasOwnProperty` (gea_runtime.h) already implements
+ * 20.1.3.7's OWN-half-only membership test for an arbitrary `gea::Value`
+ * receiver, generically, for any key. Left unclaimed, this member falls
+ * through to `dynamicGetText` (`emit-dynamic-properties.ts`), which reads
+ * "hasOwnProperty" as an ordinary property THROUGH the object's real
+ * `[[Prototype]]` chain -- correct for a program-defined member, but wrong
+ * for this one, because this runtime never links a `DynamicObject` to an
+ * `Object.prototype` analogue: the chain a user constructor builds
+ * (`instance` -> `Ctor.prototype` -> `null`) has no entry that could ever
+ * answer an ambient `Object.prototype` method, so the read comes back
+ * `undefined` and calling it aborts.
+ *
+ * `propertyIsEnumerable` is deliberately left unclaimed here: nothing in this
+ * file states which `PropertyDescriptor.enumerable` bit a THIRD idiom
+ * (`Object.prototype.propertyIsEnumerable.call(...)`) should read against a
+ * `DynamicObject`, and no probe in this codebase exercises it yet -- adding
+ * it un-exercised would be a guess, not an answer.
+ */
+export declare const dynamicObjectPrototypeMethods: ReadonlySet<string>;
+/** The claim, asked at the `[[Get]]` -- the dynamic-receiver twin of `objectShapePrototypeMemberRead` above. */
+export declare const deferredDynamicObjectMethodClaim: (staticKeyTexts: ReadonlyMap<IrValueId, string>, receiver: IrOperand, key: IrOperand) => PrototypeMethodRead | null;
+export declare const dynamicObjectPrototypeMemberRead: (ctx: EmitContext, operation: GetOperation) => boolean;
+/**
+ * The call text for a deferred `hasOwnProperty` read off a dynamic receiver.
+ *
+ * Only a string key is admitted, for the identical reason `objectShapeCallText`
+ * and `nativeHandleShapeCallText` above refuse anything else: ToPropertyKey of
+ * a non-string runs ToPrimitive, which this backend does not perform.
+ */
+export declare const dynamicObjectCallText: (ctx: EmitContext, member: string, receiver: string, args: readonly IrOperand[]) => string;