@azure/provisioning-core 1.0.0-beta.1

package/dist/esm/expression/ast-nodes.d.ts

@@ -0,0 +1,100 @@
+import type { Resource } from "../constructs/resource/resource.js";
+import type { BinaryOperator, UnaryOperator } from "../serialization/contract/index.js";
+import type { PropertySegment } from "../types.js";
+export type { BinaryOperator, UnaryOperator };
+export interface FunctionCallExpressionNode<_TValue = unknown, TOperator extends string = string> {
+    readonly kind: "fn-call";
+    readonly operator: TOperator;
+    readonly args: readonly unknown[];
+}
+export interface SymbolicValueExpressionNode<_TValue = unknown, TPath extends string = string> {
+    readonly kind: "symbolic-value";
+    readonly path: TPath;
+}
+export interface IdentifierExpressionNode<_TValue = unknown> {
+    readonly kind: "identifier";
+    readonly id: string | Resource;
+}
+export interface PropertyAccessExpressionNode<_TValue = unknown> {
+    readonly kind: "property-access";
+    readonly base: ExpressionNode;
+    readonly property: string;
+    readonly nullish: boolean;
+    /**
+     * Optional ARM wire-path segments. When present, the serialization
+     * lowering pass rewrites this single access into a chain that walks
+     * these segments (handling renames + `@flattenProperty` hoisting).
+     * Untyped / hand-built expressions leave this `undefined` and pass
+     * through unchanged.
+     */
+    readonly armPath?: readonly string[] | undefined;
+}
+export interface ArrayAccessExpressionNode<_TValue = unknown> {
+    readonly kind: "array-access";
+    readonly base: ExpressionNode;
+    /**
+     * The index into the array. A literal `number`/`string` lowers to an
+     * integer/string array-access (or a property-access for identifier-like
+     * strings) at serialize time. Any {@link ExpressionNode} is serialized
+     * recursively into the wire array-access's `index` slot — e.g. a looped
+     * `.at(loop.index)` stores the unwrapped `symbolic-value` node (emitting
+     * `sym[i]`), and a computed offset stores a `binary` / `fn-call` node
+     * (`sym[i + 1]`). `Expression<T>` proxies are always unwrapped to their
+     * raw node before landing here, per the "state holds normalized raw
+     * nodes" invariant — so a proxy is never stored directly.
+     */
+    readonly index: ArrayAccessIndex;
+    readonly nullish: boolean;
+    readonly fromEnd: boolean;
+}
+export interface BinaryExpressionNode<_TValue = unknown> {
+    readonly kind: "binary";
+    readonly operator: BinaryOperator;
+    readonly left: unknown;
+    readonly right: unknown;
+}
+export interface UnaryExpressionNode<_TValue = unknown> {
+    readonly kind: "unary";
+    readonly operator: UnaryOperator;
+    readonly argument: unknown;
+}
+export interface TernaryExpressionNode<_TValue = unknown> {
+    readonly kind: "ternary";
+    readonly condition: unknown;
+    readonly trueValue: unknown;
+    readonly falseValue: unknown;
+}
+export interface InstanceFunctionCallExpressionNode<_TValue = unknown> {
+    readonly kind: "instance-function-call";
+    readonly base: ExpressionNode;
+    readonly name: string;
+    readonly args: readonly unknown[];
+}
+export interface InterpolatedStringExpressionNode<_TValue = unknown> {
+    readonly kind: "interpolated-string";
+    readonly segments: readonly unknown[];
+}
+export type ExpressionNode<T = unknown> = FunctionCallExpressionNode<T> | SymbolicValueExpressionNode<T> | IdentifierExpressionNode<T> | PropertyAccessExpressionNode<T> | ArrayAccessExpressionNode<T> | BinaryExpressionNode<T> | UnaryExpressionNode<T> | TernaryExpressionNode<T> | InstanceFunctionCallExpressionNode<T> | InterpolatedStringExpressionNode<T>;
+/**
+ * The index stored on an {@link ArrayAccessExpressionNode}: a literal
+ * `number` or `string`, or a raw {@link ExpressionNode} evaluated at
+ * serialize time (e.g. a loop's `symbolic-value` index, or a `binary` /
+ * `fn-call` node for a computed offset). `Expression<T>` proxies are
+ * unwrapped to their raw node before being stored, so the proxy type is
+ * intentionally absent here.
+ */
+export type ArrayAccessIndex = number | string | ExpressionNode;
+/** Tests whether a value structurally matches a raw expression AST node. */
+export declare function isExpressionNode(value: unknown): value is ExpressionNode;
+export declare function functionCallExpressionNode<TValue = unknown, TOperator extends string = string>(operator: TOperator, args: readonly unknown[]): FunctionCallExpressionNode<TValue, TOperator>;
+export declare function symbolicValueExpressionNode<TValue = unknown, TPath extends string = string>(path: TPath): SymbolicValueExpressionNode<TValue, TPath>;
+export declare function identifierExpressionNode<TValue = unknown>(identifier: string | Resource): IdentifierExpressionNode<TValue>;
+export declare function propertyAccessExpressionNode<TValue = unknown>(base: ExpressionNode, property: string, options?: Partial<Pick<PropertyAccessExpressionNode, "armPath" | "nullish">>): PropertyAccessExpressionNode<TValue>;
+export declare function arrayAccessExpressionNode<TValue = unknown>(base: ExpressionNode, index: ArrayAccessIndex, options?: Partial<Pick<ArrayAccessExpressionNode, "nullish" | "fromEnd">>): ArrayAccessExpressionNode<TValue>;
+export declare function binaryExpressionNode<TValue = unknown>(operator: BinaryOperator, left: unknown, right: unknown): BinaryExpressionNode<TValue>;
+export declare function unaryExpressionNode<TValue = unknown>(operator: UnaryOperator, argument: unknown): UnaryExpressionNode<TValue>;
+export declare function ternaryExpressionNode<TValue = unknown>(condition: unknown, trueValue: unknown, falseValue: unknown): TernaryExpressionNode<TValue>;
+export declare function instanceFunctionCallExpressionNode<TValue = unknown>(base: ExpressionNode, name: string, args: readonly unknown[]): InstanceFunctionCallExpressionNode<TValue>;
+export declare function interpolatedStringExpressionNode<TValue = unknown>(segments: readonly unknown[]): InterpolatedStringExpressionNode<TValue>;
+export declare function accessExpressionNode(base: ExpressionNode, member: PropertySegment, options?: Partial<Pick<PropertyAccessExpressionNode, "armPath" | "nullish">>): PropertyAccessExpressionNode | ArrayAccessExpressionNode;
+//# sourceMappingURL=ast-nodes.d.ts.map

package/dist/esm/expression/ast-nodes.d.ts.map

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

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

@@ -0,0 +1,125 @@
+// 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/esm/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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","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT License.\n\nimport type { Resource } from \"../constructs/resource/resource.js\";\nimport type { BinaryOperator, UnaryOperator } from \"../serialization/contract/index.js\";\nimport type { PropertySegment } from \"../types.js\";\n\nexport type { BinaryOperator, UnaryOperator };\n\n// ---------------------------------------------------------------------------\n// Expression node interfaces (the raw discriminated union members)\n// ---------------------------------------------------------------------------\n\n// Note: every interface declares a phantom `TValue` (when otherwise it wouldn't\n// need one). `TValue` is *not* used in any field of any interface — but its\n// presence in the variant *type-parameter slot* is what allows\n// `ExpressionNode<T>` to thread `T` through to each variant, which in turn is\n// what lets `ExpressionBrand<T>` carry inference-visible `T` across project-\n// reference boundaries. Removing `TValue` and making `ExpressionNode<T>` a\n// fully-phantom alias breaks `coalesce<T>(...)` inference and the\n// `as DeploymentParameter<...>` cast in cross-project consumers (e.g. `demo`).\n\nexport interface FunctionCallExpressionNode<_TValue = unknown, TOperator extends string = string> {\n  readonly kind: \"fn-call\";\n  readonly operator: TOperator;\n  readonly args: readonly unknown[];\n}\n\nexport interface SymbolicValueExpressionNode<_TValue = unknown, TPath extends string = string> {\n  readonly kind: \"symbolic-value\";\n  readonly path: TPath;\n}\n\nexport interface IdentifierExpressionNode<_TValue = unknown> {\n  readonly kind: \"identifier\";\n  readonly id: string | Resource;\n}\n\nexport interface PropertyAccessExpressionNode<_TValue = unknown> {\n  readonly kind: \"property-access\";\n  readonly base: ExpressionNode;\n  readonly property: string;\n  readonly nullish: boolean;\n  /**\n   * Optional ARM wire-path segments. When present, the serialization\n   * lowering pass rewrites this single access into a chain that walks\n   * these segments (handling renames + `@flattenProperty` hoisting).\n   * Untyped / hand-built expressions leave this `undefined` and pass\n   * through unchanged.\n   */\n  readonly armPath?: readonly string[] | undefined;\n}\n\nexport interface ArrayAccessExpressionNode<_TValue = unknown> {\n  readonly kind: \"array-access\";\n  readonly base: ExpressionNode;\n  /**\n   * The index into the array. A literal `number`/`string` lowers to an\n   * integer/string array-access (or a property-access for identifier-like\n   * strings) at serialize time. Any {@link ExpressionNode} is serialized\n   * recursively into the wire array-access's `index` slot — e.g. a looped\n   * `.at(loop.index)` stores the unwrapped `symbolic-value` node (emitting\n   * `sym[i]`), and a computed offset stores a `binary` / `fn-call` node\n   * (`sym[i + 1]`). `Expression<T>` proxies are always unwrapped to their\n   * raw node before landing here, per the \"state holds normalized raw\n   * nodes\" invariant — so a proxy is never stored directly.\n   */\n  readonly index: ArrayAccessIndex;\n  readonly nullish: boolean;\n  readonly fromEnd: boolean;\n}\n\nexport interface BinaryExpressionNode<_TValue = unknown> {\n  readonly kind: \"binary\";\n  readonly operator: BinaryOperator;\n  readonly left: unknown;\n  readonly right: unknown;\n}\n\nexport interface UnaryExpressionNode<_TValue = unknown> {\n  readonly kind: \"unary\";\n  readonly operator: UnaryOperator;\n  readonly argument: unknown;\n}\n\nexport interface TernaryExpressionNode<_TValue = unknown> {\n  readonly kind: \"ternary\";\n  readonly condition: unknown;\n  readonly trueValue: unknown;\n  readonly falseValue: unknown;\n}\n\nexport interface InstanceFunctionCallExpressionNode<_TValue = unknown> {\n  readonly kind: \"instance-function-call\";\n  readonly base: ExpressionNode;\n  readonly name: string;\n  readonly args: readonly unknown[];\n}\n\nexport interface InterpolatedStringExpressionNode<_TValue = unknown> {\n  readonly kind: \"interpolated-string\";\n  readonly segments: readonly unknown[];\n}\n\n// ---------------------------------------------------------------------------\n// ExpressionNode union\n// ---------------------------------------------------------------------------\n\n// `T` is threaded through every variant. See the long comment above the node\n// interfaces for why this matters.\nexport type ExpressionNode<T = unknown> =\n  | FunctionCallExpressionNode<T>\n  | SymbolicValueExpressionNode<T>\n  | IdentifierExpressionNode<T>\n  | PropertyAccessExpressionNode<T>\n  | ArrayAccessExpressionNode<T>\n  | BinaryExpressionNode<T>\n  | UnaryExpressionNode<T>\n  | TernaryExpressionNode<T>\n  | InstanceFunctionCallExpressionNode<T>\n  | InterpolatedStringExpressionNode<T>;\n\n/**\n * The index stored on an {@link ArrayAccessExpressionNode}: a literal\n * `number` or `string`, or a raw {@link ExpressionNode} evaluated at\n * serialize time (e.g. a loop's `symbolic-value` index, or a `binary` /\n * `fn-call` node for a computed offset). `Expression<T>` proxies are\n * unwrapped to their raw node before being stored, so the proxy type is\n * intentionally absent here.\n */\nexport type ArrayAccessIndex = number | string | ExpressionNode;\n\n// Typed as `Record<ExpressionNode[\"kind\"], true>` so adding a new variant to\n// `ExpressionNode` forces a compile error here until the new kind is listed.\nconst EXPRESSION_NODE_KINDS: Record<ExpressionNode[\"kind\"], true> = {\n  \"fn-call\": true,\n  \"symbolic-value\": true,\n  identifier: true,\n  \"property-access\": true,\n  \"array-access\": true,\n  binary: true,\n  unary: true,\n  ternary: true,\n  \"instance-function-call\": true,\n  \"interpolated-string\": true,\n};\n\n/** Tests whether a value structurally matches a raw expression AST node. */\nexport function isExpressionNode(value: unknown): value is ExpressionNode {\n  if (\n    typeof value !== \"object\" ||\n    value === null ||\n    !Object.prototype.hasOwnProperty.call(value, \"kind\") ||\n    typeof (value as { kind: unknown }).kind !== \"string\"\n  ) {\n    return false;\n  }\n  const node = value as Record<string, unknown>;\n  if (!Object.prototype.hasOwnProperty.call(EXPRESSION_NODE_KINDS, node.kind as string)) {\n    return false;\n  }\n  switch (node.kind) {\n    case \"fn-call\":\n      return typeof node.operator === \"string\" && Array.isArray(node.args);\n    case \"symbolic-value\":\n      return typeof node.path === \"string\";\n    case \"identifier\":\n      return typeof node.id === \"string\" || typeof node.id === \"object\";\n    case \"property-access\":\n      return (\n        isExpressionNode(node.base) &&\n        typeof node.property === \"string\" &&\n        typeof node.nullish === \"boolean\"\n      );\n    case \"array-access\":\n      return (\n        isExpressionNode(node.base) &&\n        \"index\" in node &&\n        typeof node.nullish === \"boolean\" &&\n        typeof node.fromEnd === \"boolean\"\n      );\n    case \"binary\":\n      return typeof node.operator === \"string\" && \"left\" in node && \"right\" in node;\n    case \"unary\":\n      return typeof node.operator === \"string\" && \"argument\" in node;\n    case \"ternary\":\n      return \"condition\" in node && \"trueValue\" in node && \"falseValue\" in node;\n    case \"instance-function-call\":\n      return (\n        isExpressionNode(node.base) && typeof node.name === \"string\" && Array.isArray(node.args)\n      );\n    case \"interpolated-string\":\n      return Array.isArray(node.segments);\n    default:\n      return false;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory functions\n// ---------------------------------------------------------------------------\n\nexport function functionCallExpressionNode<TValue = unknown, TOperator extends string = string>(\n  operator: TOperator,\n  args: readonly unknown[],\n): FunctionCallExpressionNode<TValue, TOperator> {\n  return { kind: \"fn-call\", operator, args };\n}\n\nexport function symbolicValueExpressionNode<TValue = unknown, TPath extends string = string>(\n  path: TPath,\n): SymbolicValueExpressionNode<TValue, TPath> {\n  return { kind: \"symbolic-value\", path };\n}\n\nexport function identifierExpressionNode<TValue = unknown>(\n  identifier: string | Resource,\n): IdentifierExpressionNode<TValue> {\n  return { kind: \"identifier\", id: identifier };\n}\n\nexport function propertyAccessExpressionNode<TValue = unknown>(\n  base: ExpressionNode,\n  property: string,\n  options: Partial<Pick<PropertyAccessExpressionNode, \"armPath\" | \"nullish\">> = {},\n): PropertyAccessExpressionNode<TValue> {\n  return {\n    kind: \"property-access\",\n    base,\n    property,\n    nullish: options.nullish ?? false,\n    ...(options.armPath === undefined ? {} : { armPath: options.armPath }),\n  };\n}\n\nexport function arrayAccessExpressionNode<TValue = unknown>(\n  base: ExpressionNode,\n  index: ArrayAccessIndex,\n  options: Partial<Pick<ArrayAccessExpressionNode, \"nullish\" | \"fromEnd\">> = {},\n): ArrayAccessExpressionNode<TValue> {\n  return {\n    kind: \"array-access\",\n    base,\n    index,\n    nullish: options.nullish ?? false,\n    fromEnd: options.fromEnd ?? false,\n  };\n}\n\nexport function binaryExpressionNode<TValue = unknown>(\n  operator: BinaryOperator,\n  left: unknown,\n  right: unknown,\n): BinaryExpressionNode<TValue> {\n  return { kind: \"binary\", operator, left, right };\n}\n\nexport function unaryExpressionNode<TValue = unknown>(\n  operator: UnaryOperator,\n  argument: unknown,\n): UnaryExpressionNode<TValue> {\n  return { kind: \"unary\", operator, argument };\n}\n\nexport function ternaryExpressionNode<TValue = unknown>(\n  condition: unknown,\n  trueValue: unknown,\n  falseValue: unknown,\n): TernaryExpressionNode<TValue> {\n  return {\n    kind: \"ternary\",\n    condition,\n    trueValue,\n    falseValue,\n  };\n}\n\nexport function instanceFunctionCallExpressionNode<TValue = unknown>(\n  base: ExpressionNode,\n  name: string,\n  args: readonly unknown[],\n): InstanceFunctionCallExpressionNode<TValue> {\n  return {\n    kind: \"instance-function-call\",\n    base,\n    name,\n    args,\n  };\n}\n\nexport function interpolatedStringExpressionNode<TValue = unknown>(\n  segments: readonly unknown[],\n): InterpolatedStringExpressionNode<TValue> {\n  return { kind: \"interpolated-string\", segments };\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction isIdentifierSegment(segment: string): boolean {\n  return /^[A-Za-z_][A-Za-z0-9_]*$/u.test(segment);\n}\n\nexport function accessExpressionNode(\n  base: ExpressionNode,\n  member: PropertySegment,\n  options: Partial<Pick<PropertyAccessExpressionNode, \"armPath\" | \"nullish\">> = {},\n): PropertyAccessExpressionNode | ArrayAccessExpressionNode {\n  return typeof member === \"number\" || !isIdentifierSegment(member)\n    ? arrayAccessExpressionNode(base, member, options)\n    : propertyAccessExpressionNode(base, member, options);\n}\n"]}

package/dist/esm/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 snippet:ignore
+ * 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/esm/expression/expressions.d.ts.map

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

package/dist/esm/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 snippet:ignore
+ * 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