@geastack/compiler 1.0.15

package/dist/targets/cpp/class-properties/emit-class-properties.d.ts

@@ -0,0 +1,216 @@
+import type { CallableAbi, Representation } from '../../../representation/model.js';
+import type { GetOperation, IrOperand } from '../../../ir/model.js';
+import type { FunctionId } from '../../../identity/ids.js';
+import { type ClassLayout } from '../../../projection/classes.js';
+import { type EmitContext, type ReactiveRevisionOrigin } from '../emit-context.js';
+import { type ClassStaticFieldStorage } from '../class-layout.js';
+/**
+ * `classMemberText`'s result: the initializer expression, plus the DECLARED
+ * type `emitGet` must give the value when it differs from
+ * `operation.result.representation` -- non-null exactly when
+ * `boundMethodValueRepresentation` corrected the receiver-less method-value
+ * representation, so the declaration and the initializer agree on one type
+ * instead of the declaration silently keeping the wrong one.
+ */
+export interface ClassMemberValue {
+    readonly text: string;
+    readonly spelling: string | null;
+}
+/**
+ * `computedClassPrototypeMethodText`'s result: `ClassMemberValue` plus the
+ * CARRIER its arms were materialised at.
+ *
+ * That text is never the whole read. `nativeSidecarGetText`
+ * (`emit-dynamic-properties.ts`) puts it behind an OWN-property test -- 10.1.8.1
+ * runs `OrdinaryGetOwnProperty` before the prototype walk -- so the read the
+ * body finally prints is a ternary whose other arm is the expando/field
+ * lookup, and a `?:` has one type. The prototype arm's carrier is not always
+ * `operation.result.representation`: `boundMethodValueRepresentation` corrects
+ * a method VALUE whose TS-derived signature declares no receiver onto the
+ * convention its thunk really has, receiver first. Handing back only the
+ * rendered text left the sidecar arm and the slot to be spelled from the
+ * UNCORRECTED representation, and the three disagreed at once -- the arms
+ * would not reconcile, and the call that consumed the value passed the
+ * receiver `classMethodValueReceiverClaim` had already committed it to
+ * (`v10.call(b1)` against a `CallableObject<Promise<std::string>()>`).
+ *
+ * So the carrier travels with the text, and the one authority that corrected
+ * it is the one every consumer of the read reads it from.
+ */
+export interface ComputedPrototypeMethodValue extends ClassMemberValue {
+    readonly carrier: Representation;
+}
+/**
+ * One prototype method materialised at the callable convention a particular
+ * property read publishes.
+ *
+ * Kept beside `classMemberText` because a constant `object.method` read and a
+ * computed `object[key]` read must build the identical function object.  The
+ * latter merely chooses between several such objects at run time; it does not
+ * get a second opinion about thunk ABIs, receiver binding or captured state.
+ */
+export declare const classMethodValueText: (ctx: EmitContext, operation: GetOperation, key: string, method: ClassLayout["methods"][number], valueRepresentation?: Representation, receiverText?: string, receiverRepresentation?: Representation) => {
+    readonly text: string;
+    readonly type: string;
+    readonly environment: string;
+};
+/**
+ * The body an instance-method read can invoke directly, or `null` when the
+ * callable carrier is part of the semantics of the read.
+ *
+ * This is deliberately asked before rendering by dead-value analysis as well
+ * as by `classMemberText`: once a call names the body, its callee operand is
+ * not a read of the materialized `CallableObject`. Keeping the two decisions
+ * on this one query prevents a devirtualized call from leaving a dead carrier
+ * construction in every hot invocation.
+ */
+export declare const directClassMethodBody: (ctx: EmitContext, operation: GetOperation, key: string | null) => FunctionId | null;
+/**
+ * A class receiver's key, resolved against what the class and everything it
+ * inherits actually have.
+ *
+ * A field is instance storage and loads with `->`; a method is not stored on
+ * the instance at all -- it lives on the prototype -- so loading it as a member
+ * reads a struct field that does not exist. `[[Get]]` of a method yields the
+ * function object itself, which for a class whose family is closed is the one
+ * pointer pair that implements it.
+ *
+ * An inherited member needs nothing special once the lookup finds it: the
+ * emitted struct really derives from its base's (`records.ts`), so an inherited
+ * field is the same `->` on the same object, and an inherited method's body
+ * takes the base's receiver type, which a `shared_ptr` to the derived class
+ * converts to on its own. What the lookup must not do is find a member whose
+ * storage nothing initializes -- which is why the base's construction has to
+ * run before this path exists at all, not after.
+ */
+/**
+ * What a reactive class-field read obliges a consumer to do, decided from the
+ * projected class layout alone.
+ *
+ * Lifted out of `classMemberText` so this fact has ONE authority with two
+ * callers -- the walk that records it before the body renders
+ * (`reactive-dependencies.ts`) and the JSX consumer that reads it back. It was
+ * a side effect of whichever resolver happened to spell the access, which is
+ * how a fact goes missing: an access answered by an earlier rung of the ladder
+ * recorded nothing, and the consumer silently sampled instead of subscribing.
+ *
+ * `revision` and `cell` are the same fact told two ways. A field whose C++
+ * carrier CAN be a cell is subscribed through that cell; one whose cannot --
+ * an array -- is subscribed through the companion revision cell, which is also
+ * what a write reached through the value has to tick. Which of the two a field
+ * fell into is `records.ts`'s answer during struct rendering
+ * (`representationCanCell`), which no plugin-time fact can state, so it is
+ * asked of `revisions` here rather than re-derived.
+ *
+ * Gated on `operation.reactive`, filled at lowering from the plugin's own
+ * table having walked this exact inheritance chain once, rather than asking
+ * "is this field reactive at all" a second time.
+ */
+export interface ReactiveClassFieldRead {
+    readonly kind: 'revision' | 'cell';
+    readonly origin: ReactiveRevisionOrigin;
+}
+export declare const reactiveClassFieldClaim: (ctx: EmitContext, operation: GetOperation) => ReactiveClassFieldRead | null;
+export declare const classMemberText: (ctx: EmitContext, operation: GetOperation) => ClassMemberValue | null;
+/**
+ * The member and convention an overridden method read has to be DISPATCHED
+ * through, or `null` for every read that is not one.
+ *
+ * A direct bind is only right while nothing below the receiver's class
+ * redeclares the key; where something does, the call has to go through the
+ * object. That is the same family-closure question `classMemberText` resolves
+ * to choose its own spelling, and it is decided entirely from the projected
+ * layouts and the dispatch table this unit emitted -- so it is stated here and
+ * recorded by `emit.ts`'s prepass, rather than as a side effect of the two
+ * branches that happen to spell such a read.
+ *
+ * `super.m()` is excluded for the reason 13.3.7 gives: the language binds it
+ * statically, and dispatching it re-enters the override that wrote it.
+ */
+export declare const virtualCalleeClaim: (ctx: EmitContext, operation: GetOperation) => {
+    readonly member: string;
+    readonly abi: CallableAbi;
+} | null;
+/**
+ * Whether a `[[Get]]` on a class receiver publishes a METHOD VALUE, and the
+ * receiver it went through -- `null` for every other read.
+ *
+ * A method value carries its body's own physical convention, receiver first,
+ * while the language's view of the value declares no receiver; the call that
+ * consumes it therefore has to be handed the object the read went through
+ * (`EmitContext.directCallReceivers`, and `emit-callable.ts`'s use of it).
+ * That is a property of the READ, decided from the projected class layout, so
+ * it is stated here once and recorded by `emit.ts`'s prepass -- the resolvers
+ * below simply spell the value the layout already committed them to.
+ *
+ * Both shapes the class path publishes a method value through are here,
+ * because both hand the same receiver to the same consumer: the ordinary
+ * `object.method` read, and `computedClassPrototypeMethodText`'s finite
+ * `object[key]` dispatch.
+ */
+export declare const classMethodValueReceiverClaim: (ctx: EmitContext, operation: GetOperation) => IrOperand | null;
+/**
+ * A computed class-method read such as Hono's `raw[key]()` where `key` is a
+ * finite `keyof` set whose literal arms share one callable convention.
+ *
+ * String-literal unions intentionally collapse to the native `std::string`
+ * carrier, so the C++ emitter cannot branch on the key's representation.  It
+ * can, however, ask the already-projected class layout for every prototype
+ * method whose body converts to the read's one published callable type.  Each
+ * arm is built by `classMethodValueText`, the same authority used by a static
+ * `.method` read.  A key absent from that finite set falls through to the
+ * ordinary missing-property failure at the caller.
+ *
+ * Overridden families select the exact prototype implementation from the
+ * receiver allocation at READ time. A later call keeps that implementation.
+ * Own fields and expando shadowing are handled by
+ * `nativeSidecarGetText` before it chooses this prototype result.
+ */
+export declare const computedClassPrototypeMethodText: (ctx: EmitContext, operation: GetOperation) => ComputedPrototypeMethodValue | null;
+/**
+ * The emitted global one `ClassName.KEY` names, or `null` when the
+ * whole-program census claimed no storage for it.
+ *
+ * The census (`class-layout.ts`'s `censusClassStaticFieldStorage`, published
+ * by `translation-unit.ts` before any body renders) is the ONLY authority
+ * here -- this re-derives nothing. It records only the assignment-only idiom
+ * (a key no `static` member declares) and refuses a key two writes carried
+ * differently, so a name it answers for is a location whose carrier every
+ * write in the program already agreed on, and a name it declines falls
+ * through to whatever refusal the caller already had.
+ *
+ * Shared by both directions: a read (`classConstructorStaticMemberText`) and
+ * a store (`emit-properties.ts`'s `emitFieldStoreLines`) must resolve the
+ * same key to the same global, and two lookups written separately are how
+ * they would eventually stop doing so.
+ */
+export declare const classConstructorStaticFieldStorage: (ctx: EmitContext, receiver: Representation, key: string) => ClassStaticFieldStorage | null;
+export declare const classConstructorStaticFieldName: (ctx: EmitContext, receiver: Representation, key: string) => string | null;
+/**
+ * `classMemberText`'s twin for the constructor side: `Quaternion.fromEuler`,
+ * a static method or get-only accessor read off the class value itself
+ * rather than off an instance.
+ *
+ * `constructor-family.members` is a list in the model (`representation/
+ * model.ts`) but `deriveClassConstructor` (`representation/derive.ts`) never
+ * produces more than one entry, so every member is tried and the first site
+ * found wins -- the same tolerance `projectClasses` already gives a heritage
+ * value naming several classes, just applied to the read instead of the base
+ * link.
+ *
+ * A key the whole-program static-field census claimed
+ * (`class-layout.ts`'s `censusClassStaticFieldStorage`, published by
+ * `translation-unit.ts` before any body renders) reads its own emitted
+ * global. That census records only the assignment-only idiom -- a key no
+ * `static` member of the class declares -- so it can never disagree with the
+ * `classStaticMemberOf` site below about which storage a key names, and it
+ * is asked FIRST for exactly that reason: the site scan has no answer for a
+ * key nothing declares, and would otherwise fall through to this function's
+ * closing refusal.
+ *
+ * A DECLARED static field (`site.kind === 'field'`) is still refused by
+ * name: the census skips those, so no storage was emitted for one, and
+ * reading it would be a lookup path answering before its storage exists.
+ */
+export declare const classConstructorStaticMemberTextFor: (ctx: EmitContext, receiver: Representation, key: string, result: Representation, receiverText: () => string) => string | null;
+export declare const classConstructorStaticMemberText: (ctx: EmitContext, operation: GetOperation) => string | null;