@azure/provisioning-core 0.1.0-alpha.20261014.1

package/dist/expression/ast-nodes.js

@@ -0,0 +1,127 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+// Typed as `Record<ExpressionNode["kind"], true>` so adding a new variant to
+// `ExpressionNode` forces a compile error here until the new kind is listed.
+const EXPRESSION_NODE_KINDS = {
+    "fn-call": true,
+    "symbolic-value": true,
+    identifier: true,
+    "property-access": true,
+    "array-access": true,
+    binary: true,
+    unary: true,
+    ternary: true,
+    "instance-function-call": true,
+    "interpolated-string": true,
+};
+/** Tests whether a value structurally matches a raw expression AST node. */
+export function isExpressionNode(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        !Object.prototype.hasOwnProperty.call(value, "kind") ||
+        typeof value.kind !== "string") {
+        return false;
+    }
+    const node = value;
+    if (!Object.prototype.hasOwnProperty.call(EXPRESSION_NODE_KINDS, node.kind)) {
+        return false;
+    }
+    switch (node.kind) {
+        case "fn-call":
+            return typeof node.operator === "string" && Array.isArray(node.args);
+        case "symbolic-value":
+            return typeof node.path === "string";
+        case "identifier":
+            return typeof node.id === "string" || typeof node.id === "object";
+        case "property-access":
+            return (isExpressionNode(node.base) &&
+                typeof node.property === "string" &&
+                typeof node.nullish === "boolean");
+        case "array-access":
+            return (isExpressionNode(node.base) &&
+                "index" in node &&
+                typeof node.nullish === "boolean" &&
+                typeof node.fromEnd === "boolean");
+        case "binary":
+            return (typeof node.operator === "string" && "left" in node && "right" in node);
+        case "unary":
+            return typeof node.operator === "string" && "argument" in node;
+        case "ternary":
+            return "condition" in node && "trueValue" in node && "falseValue" in node;
+        case "instance-function-call":
+            return (isExpressionNode(node.base) &&
+                typeof node.name === "string" &&
+                Array.isArray(node.args));
+        case "interpolated-string":
+            return Array.isArray(node.segments);
+        default:
+            return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory functions
+// ---------------------------------------------------------------------------
+export function functionCallExpressionNode(operator, args) {
+    return { kind: "fn-call", operator, args };
+}
+export function symbolicValueExpressionNode(path) {
+    return { kind: "symbolic-value", path };
+}
+export function identifierExpressionNode(identifier) {
+    return { kind: "identifier", id: identifier };
+}
+export function propertyAccessExpressionNode(base, property, options = {}) {
+    return {
+        kind: "property-access",
+        base,
+        property,
+        nullish: options.nullish ?? false,
+        ...(options.armPath === undefined ? {} : { armPath: options.armPath }),
+    };
+}
+export function arrayAccessExpressionNode(base, index, options = {}) {
+    return {
+        kind: "array-access",
+        base,
+        index,
+        nullish: options.nullish ?? false,
+        fromEnd: options.fromEnd ?? false,
+    };
+}
+export function binaryExpressionNode(operator, left, right) {
+    return { kind: "binary", operator, left, right };
+}
+export function unaryExpressionNode(operator, argument) {
+    return { kind: "unary", operator, argument };
+}
+export function ternaryExpressionNode(condition, trueValue, falseValue) {
+    return {
+        kind: "ternary",
+        condition,
+        trueValue,
+        falseValue,
+    };
+}
+export function instanceFunctionCallExpressionNode(base, name, args) {
+    return {
+        kind: "instance-function-call",
+        base,
+        name,
+        args,
+    };
+}
+export function interpolatedStringExpressionNode(segments) {
+    return { kind: "interpolated-string", segments };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function isIdentifierSegment(segment) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/u.test(segment);
+}
+export function accessExpressionNode(base, member, options = {}) {
+    return typeof member === "number" || !isIdentifierSegment(member)
+        ? arrayAccessExpressionNode(base, member, options)
+        : propertyAccessExpressionNode(base, member, options);
+}
+//# sourceMappingURL=ast-nodes.js.map

package/dist/expression/ast-nodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-nodes.js","sourceRoot":"","sources":["../../src/expression/ast-nodes.ts"],"names":[],"mappings":"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"}

package/dist/expression/expressions.d.ts

@@ -0,0 +1,164 @@
+import { type NavShape } from "../shape/shape.js";
+import { type BinaryOperator, type ExpressionNode, type UnaryOperator } from "./ast-nodes.js";
+/**
+ * Runtime symbol key storing the underlying `ExpressionNode` on proxies.
+ * Internal to the package — consumers should use `isExpression()` and
+ * `unwrapExpression()` instead of accessing this directly.
+ */
+export declare const EXPRESSION_BRAND: unique symbol;
+/** Declared symbol type used in the `Expression<T>` interface for branding. */
+declare const __expressionBrand: unique symbol;
+export interface ExpressionBrand<out T> {
+    readonly [__expressionBrand]: ExpressionNode<T>;
+}
+declare const __expressionTag: unique symbol;
+export interface ExpressionTag {
+    readonly [__expressionTag]?: never;
+}
+/**
+ * An opaque deploy-time expression wrapping type `T`.
+ *
+ * For object types, properties of `T` are accessible as
+ * `Expression<Exclude<T[K], undefined>>`. Expression proxies always expose a
+ * symbolic property path, so TypeScript's `undefined` omission marker does not
+ * belong in the projected value type. Explicit `null` remains intact.
+ * For array types, numeric indices return `Expression<element>` and
+ * `.length` is an `Expression<number>`.
+ *
+ * Function-typed keys on `T` are intentionally NOT surfaced — an
+ * `Expression<(...)=>R>` isn't callable at the type level or meaningful
+ * at emit time. When bicep-level array/object methods are needed
+ * (concat, union, etc.), they are added explicitly via dedicated helper
+ * types (e.g. a future `ArrayExpression<T>`), not reflectively derived.
+ *
+ * `NonNullable<T>` is applied at the input boundary, so
+ * `Expression<R | undefined>` yields the same structural surface as
+ * `Expression<R>` — otherwise the `| undefined` union would distribute
+ * and collapse the object branch into `mapped | {}`, erasing the
+ * index signature / member projection.
+ */
+export type Expression<T = unknown> = ExpressionBrand<T> & ExpressionTag & ExpressionShape<NonNullable<T>>;
+export type ExpressionShape<T> = T extends readonly unknown[] ? number extends T["length"] ? {
+    readonly length: Expression<number>;
+    readonly [index: number]: Expression<T[number]>;
+} : {
+    readonly [K in Exclude<keyof T, keyof any[]>]: Expression<T[K]>;
+} & {
+    readonly length: Expression<number>;
+    readonly [index: number]: Expression<T[number]>;
+} : T extends object ? {
+    readonly [K in keyof T as T[K] extends (...a: any[]) => any ? never : K]-?: Expression<Exclude<T[K], undefined>>;
+} : {};
+/**
+ * Carries an *optional* Expression brand on an Input-shaped interface.
+ *
+ * This is the asymmetric-brand trick that makes the Input type system
+ * work without discriminated unions:
+ *
+ * - Every generated `*Input` interface extends `InputOf<Raw>` and therefore
+ *   inherits the optional brand. Plain literal values (e.g. `{ foo: 1 }`)
+ *   trivially satisfy it because the brand property is absent, which is
+ *   permitted by an optional field.
+ * - `Expression<Raw>` carries a *required* brand of the same shape.
+ *   Required-fields-satisfy-optional is part of TS structural assignability,
+ *   so any `Expression<Raw>` is assignable where an `InputOf<Raw>`
+ *   (and thus any `*Input` that extends it) is expected.
+ *
+ * Net effect: a single `MInput` parameter accepts both literals and
+ * whole-subtree `Expression<M>` replacements — no `MInput | Expression<M>`
+ * union is needed in the generated signatures. Callers that want to
+ * inspect whether a value is a literal or expression use `isExpression()`.
+ */
+export interface InputOf<out Raw> {
+    readonly [__expressionBrand]?: ExpressionNode<Raw>;
+}
+/**
+ * Writable input form for an array container.
+ *
+ * Accepts literal `T[]`, another `InputArray<T>`, or `Expression<Raw>`.
+ * Deliberately NOT a subtype of `T[]` — passing a CDK-backed array to
+ * an API that expects a plain `Array<T>` fails at compile time, which
+ * is the correct signal (the value may actually be a Proxy wrapping an
+ * `ExpressionNode`, not a real JS array).
+ */
+export interface InputArray<T, Raw = readonly T[]> extends InputOf<Raw> {
+    length: number | Expression<number>;
+    [index: number]: T;
+}
+/** Writable input form for a `Record<string, V>` container. */
+export interface InputRecord<V, Raw = Record<string, V>> extends InputOf<Raw> {
+    [key: string]: V;
+}
+/** Writable input form for a fixed-length heterogeneous tuple. */
+export type InputTuple<T extends readonly unknown[], Raw extends readonly unknown[] = T> = InputOf<Raw> & {
+    length: T["length"] | Expression<number>;
+    [index: number]: T[number] | Expression<Raw[number]>;
+} & {
+    [K in Exclude<keyof T, keyof any[]>]: T[K];
+};
+/**
+ * Accepts either a plain value `T` or an `Expression<T>` substitution.
+ *
+ * Use this on scalar/leaf Input sites (primitives, enums, literal-only
+ * unions) where a full `InputOf<...>` structural extension doesn't apply.
+ * The result is a simple discriminated union; call `isExpression()` to
+ * branch on the runtime shape.
+ */
+export type ExpressionOrValue<T> = T | Expression<T>;
+/**
+ * Asserts that a deploy-time expression resolves to a specific literal,
+ * so it can be used where a discriminator is expected.
+ *
+ * Discriminator properties on a `@discriminator` model are typed as bare
+ * literals (`kind: "cache"`) rather than `ExpressionOrValue<"cache">`.
+ * That is deliberate: TypeScript only treats a property as a discriminant
+ * when its type is a *unit* type in every constituent of the union, and a
+ * single widened arm disables narrowing for the whole union — completions
+ * then offer every variant's properties and excess-property checking
+ * degrades to "allowed if the property exists in any variant".
+ *
+ * When the discriminator genuinely isn't known until deployment, wrap the
+ * expression with this to state which variant you mean:
+ *
+ * ```ts
+ * widget.properties.primaryRule = {
+ *   kind: asDiscriminator(kindParam),
+ *   cacheKind: "long",
+ *   days: 7,
+ * };
+ * ```
+ *
+ * Every other property is still fully checked — only the discriminator's
+ * type safety is waived. Note that the runtime cannot dispatch on a
+ * non-literal discriminator, so serialization falls back to structural
+ * variant inference; prefer a literal wherever possible.
+ *
+ * The literal is inferred from the expression's own type argument. If the
+ * expression is loosely typed (`Expression<string>`), name the variant
+ * explicitly: `asDiscriminator<"cache">(param)`.
+ */
+export declare function asDiscriminator<L extends string>(value: ExpressionOrValue<L>): L;
+/**
+ * Extracts the underlying `ExpressionNode` from an `Expression<T>` value.
+ *
+ * `Expression<T>` is the public, typed handle for a deploy-time expression
+ * (backed by a Proxy at runtime); `ExpressionNode` is the raw AST node that
+ * the proxy wraps. Use this to walk / inspect / serialize the underlying
+ * tree without reaching for the brand symbol directly.
+ */
+export declare function unwrapExpression<T>(expr: Expression<T>): ExpressionNode<T>;
+/**
+ * Tests whether a value is an `Expression<T>` — the typed, branded handle
+ * for a deploy-time expression (proxy-backed). Returns false for raw
+ * `ExpressionNode` data; use {@link isExpressionNode} from `./ast-nodes.js`
+ * for that.
+ */
+export declare function isExpression(value: unknown): value is Expression<unknown>;
+export declare function wrapExpression<T = unknown>(expression: ExpressionNode, nav?: NavShape): Expression<T>;
+export declare function wrapExpressionOver<TObject extends object, TValue = unknown>(target: TObject, expression: ExpressionNode): TObject & Expression<TValue>;
+export declare function createBinaryExpression<T>(op: BinaryOperator, left: unknown, right: unknown): Expression<T>;
+export declare function createUnaryExpression<T>(op: UnaryOperator, argument: unknown): Expression<T>;
+export declare function createTernaryExpression<T>(condition: unknown, trueValue: unknown, falseValue: unknown): Expression<T>;
+export declare function createFunctionCallExpression<T>(name: string, args: unknown[]): Expression<T>;
+export {};
+//# sourceMappingURL=expressions.d.ts.map

package/dist/expression/expressions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressions.d.ts","sourceRoot":"","sources":["../../src/expression/expressions.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAML,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAEnB,MAAM,gBAAgB,CAAC;AAMxB;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAmC,CAAC;AAE1E,+EAA+E;AAC/E,OAAO,CAAC,MAAM,iBAAiB,EAAE,OAAO,MAAM,CAAC;AAM/C,MAAM,WAAW,eAAe,CAAC,GAAG,CAAC,CAAC;IACpC,QAAQ,CAAC,CAAC,iBAAiB,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;CACjD;AAKD,OAAO,CAAC,MAAM,eAAe,EAAE,OAAO,MAAM,CAAC;AAC7C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,CAAC,eAAe,CAAC,CAAC,EAAE,KAAK,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,eAAe,CAAC,CAAC,CAAC,GACtD,aAAa,GACb,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AAElC,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,OAAO,EAAE,GACzD,MAAM,SAAS,CAAC,CAAC,QAAQ,CAAC,GACxB;IACE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;CACjD,GACD;IACE,QAAQ,EAAE,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAChE,GAAG;IACF,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;CACjD,GACH,CAAC,SAAS,MAAM,GACd;IACE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,KAAK,GAAG,GACvD,KAAK,GACL,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;CAC/C,GACD,EAAE,CAAC;AAMT;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,OAAO,CAAC,GAAG,CAAC,GAAG;IAC9B,QAAQ,CAAC,CAAC,iBAAiB,CAAC,CAAC,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC;CACpD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,EAAE,GAAG,GAAG,SAAS,CAAC,EAAE,CAAE,SAAQ,OAAO,CAAC,GAAG,CAAC;IACrE,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,CAAC;CACpB;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAE,SAAQ,OAAO,CAAC,GAAG,CAAC;IAC3E,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC;CAClB;AAED,kEAAkE;AAClE,MAAM,MAAM,UAAU,CACpB,CAAC,SAAS,SAAS,OAAO,EAAE,EAC5B,GAAG,SAAS,SAAS,OAAO,EAAE,GAAG,CAAC,IAChC,OAAO,CAAC,GAAG,CAAC,GAAG;IACjB,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CACtD,GAAG;KACD,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAC3C,CAAC;AAMF;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;AAMrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAC9C,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC1B,CAAC,CAEH;AAyBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAI1E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAAC,OAAO,CAAC,CAIzE;AAMD,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,EACxC,UAAU,EAAE,cAAc,EAC1B,GAAG,CAAC,EAAE,QAAQ,GACb,UAAU,CAAC,CAAC,CAAC,CAkEf;AAED,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,MAAM,EAAE,MAAM,GAAG,OAAO,EACzE,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,cAAc,GACzB,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CA6D9B;AAMD,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,EAAE,EAAE,cAAc,EAClB,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,GACb,UAAU,CAAC,CAAC,CAAC,CAEf;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,EAAE,EAAE,aAAa,EACjB,QAAQ,EAAE,OAAO,GAChB,UAAU,CAAC,CAAC,CAAC,CAEf;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,SAAS,EAAE,OAAO,EAClB,SAAS,EAAE,OAAO,EAClB,UAAU,EAAE,OAAO,GAClB,UAAU,CAAC,CAAC,CAAC,CAIf;AAED,wBAAgB,4BAA4B,CAAC,CAAC,EAC5C,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EAAE,GACd,UAAU,CAAC,CAAC,CAAC,CAEf"}

package/dist/expression/expressions.js

@@ -0,0 +1,211 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { navigateShape } from "../shape/shape.js";
+import { arrayAccessExpressionNode, binaryExpressionNode, functionCallExpressionNode, propertyAccessExpressionNode, ternaryExpressionNode, unaryExpressionNode, } from "./ast-nodes.js";
+// ---------------------------------------------------------------------------
+// Brand symbol (runtime + type-only)
+// ---------------------------------------------------------------------------
+/**
+ * Runtime symbol key storing the underlying `ExpressionNode` on proxies.
+ * Internal to the package — consumers should use `isExpression()` and
+ * `unwrapExpression()` instead of accessing this directly.
+ */
+export const EXPRESSION_BRAND = Symbol("expression-brand");
+// ---------------------------------------------------------------------------
+// Discriminator escape hatch
+// ---------------------------------------------------------------------------
+/**
+ * Asserts that a deploy-time expression resolves to a specific literal,
+ * so it can be used where a discriminator is expected.
+ *
+ * Discriminator properties on a `@discriminator` model are typed as bare
+ * literals (`kind: "cache"`) rather than `ExpressionOrValue<"cache">`.
+ * That is deliberate: TypeScript only treats a property as a discriminant
+ * when its type is a *unit* type in every constituent of the union, and a
+ * single widened arm disables narrowing for the whole union — completions
+ * then offer every variant's properties and excess-property checking
+ * degrades to "allowed if the property exists in any variant".
+ *
+ * When the discriminator genuinely isn't known until deployment, wrap the
+ * expression with this to state which variant you mean:
+ *
+ * ```ts
+ * widget.properties.primaryRule = {
+ *   kind: asDiscriminator(kindParam),
+ *   cacheKind: "long",
+ *   days: 7,
+ * };
+ * ```
+ *
+ * Every other property is still fully checked — only the discriminator's
+ * type safety is waived. Note that the runtime cannot dispatch on a
+ * non-literal discriminator, so serialization falls back to structural
+ * variant inference; prefer a literal wherever possible.
+ *
+ * The literal is inferred from the expression's own type argument. If the
+ * expression is loosely typed (`Expression<string>`), name the variant
+ * explicitly: `asDiscriminator<"cache">(param)`.
+ */
+export function asDiscriminator(value) {
+    return value;
+}
+// ---------------------------------------------------------------------------
+// Unwrap + type guards
+// ---------------------------------------------------------------------------
+// Two distinct concepts, two distinct guards:
+//
+//   - `isExpression(x)`     — "is `x` a typed `Expression<T>` handle
+//                             (the value-level, proxy-backed form)?"
+//   - `isExpressionNode(x)` — "is `x` a raw `ExpressionNode` data object
+//                             (one of the AST kinds)?"
+//
+// These are *disjoint* — a value is either a wrapped Expression handle or a
+// raw AST node, never both. To check the AST kind of either form, narrow
+// via the discriminated `kind` field:
+//
+//   if (isExpression(value)) {
+//     const node = unwrapExpression(value);
+//     if (node.kind === "fn-call") { /* node: FunctionCallExpressionNode */ }
+//   }
+//   if (isExpressionNode(value)) {
+//     if (value.kind === "binary") { /* value: BinaryExpressionNode */ }
+//   }
+/**
+ * Extracts the underlying `ExpressionNode` from an `Expression<T>` value.
+ *
+ * `Expression<T>` is the public, typed handle for a deploy-time expression
+ * (backed by a Proxy at runtime); `ExpressionNode` is the raw AST node that
+ * the proxy wraps. Use this to walk / inspect / serialize the underlying
+ * tree without reaching for the brand symbol directly.
+ */
+export function unwrapExpression(expr) {
+    return expr[EXPRESSION_BRAND];
+}
+/**
+ * Tests whether a value is an `Expression<T>` — the typed, branded handle
+ * for a deploy-time expression (proxy-backed). Returns false for raw
+ * `ExpressionNode` data; use {@link isExpressionNode} from `./ast-nodes.js`
+ * for that.
+ */
+export function isExpression(value) {
+    return (typeof value === "object" && value !== null && EXPRESSION_BRAND in value);
+}
+// ---------------------------------------------------------------------------
+// Expression proxy factory
+// ---------------------------------------------------------------------------
+export function wrapExpression(expression, nav) {
+    return new Proxy(Object.create(null), {
+        get(_target, prop, _receiver) {
+            if (prop === EXPRESSION_BRAND) {
+                return expression;
+            }
+            if (prop === Symbol.toPrimitive || prop === "toString") {
+                return () => "[Expression]";
+            }
+            if (prop === "valueOf") {
+                return () => expression;
+            }
+            // Avoid being treated as a thenable / Promise
+            if (prop === "then") {
+                return undefined;
+            }
+            if (typeof prop === "symbol") {
+                return undefined;
+            }
+            // Numeric string → array access.
+            if (/^\d+$/u.test(prop)) {
+                const index = Number(prop);
+                const step = navigateShape(nav, index);
+                return wrapExpression(arrayAccessExpressionNode(expression, index), step.next);
+            }
+            // String property → property access. Consult the current nav
+            // shape; stamp the access with the wire armPath if an entry
+            // exists, otherwise pass through unchanged. Container navs
+            // (record/array) yield no stamp but still peel a layer.
+            const step = navigateShape(nav, prop);
+            return wrapExpression(propertyAccessExpressionNode(expression, prop, {
+                armPath: step.stamp?.armPath,
+            }), step.next);
+        },
+        has(_target, prop) {
+            return prop === EXPRESSION_BRAND;
+        },
+        ownKeys() {
+            return [];
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (prop === EXPRESSION_BRAND) {
+                return {
+                    configurable: true,
+                    enumerable: false,
+                    value: expression,
+                };
+            }
+            return undefined;
+        },
+    });
+}
+export function wrapExpressionOver(target, expression) {
+    return new Proxy(target, {
+        get(backing, prop, receiver) {
+            if (prop === EXPRESSION_BRAND) {
+                return expression;
+            }
+            if (prop === Symbol.toPrimitive || prop === "toString") {
+                return () => "[Expression]";
+            }
+            if (prop === "valueOf") {
+                return () => expression;
+            }
+            if (prop === "then") {
+                return undefined;
+            }
+            if (Reflect.has(backing, prop)) {
+                return Reflect.get(backing, prop, receiver);
+            }
+            if (typeof prop === "symbol") {
+                return undefined;
+            }
+            if (/^\d+$/u.test(prop)) {
+                return wrapExpression(arrayAccessExpressionNode(expression, Number(prop)));
+            }
+            return wrapExpression(propertyAccessExpressionNode(expression, prop));
+        },
+        has(backing, prop) {
+            return prop === EXPRESSION_BRAND || Reflect.has(backing, prop);
+        },
+        ownKeys(backing) {
+            const keys = Reflect.ownKeys(backing);
+            if (!keys.includes(EXPRESSION_BRAND)) {
+                keys.push(EXPRESSION_BRAND);
+            }
+            return keys;
+        },
+        getOwnPropertyDescriptor(backing, prop) {
+            if (prop === EXPRESSION_BRAND) {
+                return {
+                    configurable: true,
+                    enumerable: false,
+                    value: expression,
+                };
+            }
+            return Reflect.getOwnPropertyDescriptor(backing, prop);
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Proxied-expression factories (return Expression<T>)
+// ---------------------------------------------------------------------------
+export function createBinaryExpression(op, left, right) {
+    return wrapExpression(binaryExpressionNode(op, left, right));
+}
+export function createUnaryExpression(op, argument) {
+    return wrapExpression(unaryExpressionNode(op, argument));
+}
+export function createTernaryExpression(condition, trueValue, falseValue) {
+    return wrapExpression(ternaryExpressionNode(condition, trueValue, falseValue));
+}
+export function createFunctionCallExpression(name, args) {
+    return wrapExpression(functionCallExpressionNode(name, args));
+}
+//# sourceMappingURL=expressions.js.map

package/dist/expression/expressions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressions.js","sourceRoot":"","sources":["../../src/expression/expressions.ts"],"names":[],"mappings":"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"}