@geastack/compiler 1.0.15

package/dist/semantics/normalize/producers/protocol.d.ts

@@ -0,0 +1,67 @@
+import ts from 'typescript';
+import type { OperationId, SemanticResultId, StructuralTypeId } from '../../../identity/ids.js';
+import type { SemanticEdge } from '../../model/edges.js';
+import { type OperandSource } from '../../model/operands.js';
+import type { ProtocolOperation } from '../../model/operations.js';
+import type { CensusCandidate } from '../census.js';
+import type { FamilyProducer } from '../contribution.js';
+import type { ProducerContext } from '../producer-context.js';
+/**
+ * `any`/`unknown` is the one iteration source whose `@@iterator` lookup must
+ * stay in the dynamic runtime.  It is deliberately narrower than "not a
+ * native cursor": a typed class or a typed structural iterable still owns a
+ * concrete method carrier, and routing either through `Value` would box a
+ * statically represented value merely to iterate it.
+ */
+export declare const isDynamicIterationSource: (context: ProducerContext, type: StructuralTypeId) => boolean;
+export interface IteratorProtocolOptions {
+    /** `for`-`in` enumerates the object directly; it never looks up a method. */
+    readonly includeGetMethod: boolean;
+    /** Only sync/async iteration calls `IteratorClose` on early exit; enumerate and plain spread never do. */
+    readonly includeClose: boolean;
+    /** A consuming spread drains the record itself; do not pre-step it. */
+    readonly includeNext?: boolean;
+}
+export interface IteratorProtocolSteps {
+    readonly operations: readonly ProtocolOperation[];
+    readonly edges: readonly SemanticEdge[];
+    readonly iteratorRecord: SemanticResultId;
+    readonly recordType: StructuralTypeId;
+    readonly nextValue: SemanticResultId;
+    readonly nextOperationId: OperationId;
+    /** `null` when `includeClose` is false: there is no close step for a caller to route an abrupt exit into. */
+    readonly closeOperationId: OperationId | null;
+}
+/**
+ * Mints the sync/async-iterator or enumerate protocol steps for one source
+ * expression, sharing one implementation between this file's own spread
+ * handling and `control.ts`'s `for`-`of`/`for`-`in`/`yield*` handling so both
+ * always agree on the shape of "the iteration protocol" instead of drifting
+ * into two independently-evolving copies.
+ *
+ * The four possible steps reserve fixed ordinals -- 0 `get-method`, 1
+ * `get-iterator`, 2 `next`, 3 `close` -- by drawing from the counter in that
+ * order even when a step is skipped for this `protocol` (`for`-`in` never has
+ * a `get-method`; plain spread never has a `close`). Without that, `next`
+ * would land at ordinal 1 for `for`-`in` but ordinal 2 for `for`-`of`, and any
+ * other producer that needs to cite "the per-iteration value" for a loop node
+ * -- the binding producer initializing the loop variable -- would have no
+ * fixed identity to build without first knowing which loop variant produced
+ * it. Reserving the ordinal even when unused keeps `next` at ordinal 2
+ * regardless of variant.
+ */
+export declare const mintIteratorSteps: (context: ProducerContext, candidate: CensusCandidate, protocol: ProtocolOperation["protocol"], source: {
+    readonly source: OperandSource;
+    readonly type: StructuralTypeId;
+    readonly iterated: ts.Node | null;
+    /** Census-correct checker type when `iterated` is target syntax rather than the source expression itself. */
+    readonly rawIterated?: ts.Type | null;
+}, options: IteratorProtocolOptions) => IteratorProtocolSteps;
+/**
+ * `SpreadElement` covers both `f(...xs)` and `[...xs]` -- the census assigns
+ * one syntax kind to both contexts, and this producer treats them identically
+ * because the iteration protocol they invoke does not differ by context.
+ * `SpreadAssignment` is object-literal spread and is the only candidate routed
+ * to `contributeObjectSpread`.
+ */
+export declare const createProtocolProducer: (context: ProducerContext) => FamilyProducer;