@azure/provisioning-core 1.0.0-beta.1

package/dist/esm/constructs/resource/resource-query.js

@@ -0,0 +1,69 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { isResourceDeclaration, isLoopedResource, isLoopedResourceOf } from "./resource-utils.js";
+import { deref } from "./resource-proxy.js";
+// ---------------------------------------------------------------------------
+// Query engine (module-private)
+// ---------------------------------------------------------------------------
+// Imports only brand guards (`resource-utils`) — which do not import
+// `ProvisioningComponent`/`Stack` at runtime — plus types (type-only), so there is no
+// import cycle.
+/**
+ * Collect the resource declarations beneath `root` (the root itself is never
+ * included). `recursive` descends the whole subtree via `visit`; otherwise
+ * only `root`'s direct children are considered. `wantLooped` selects the
+ * looped declarations (`Ctor.fromLoop(...)`) vs. the scalar ones.
+ */
+function collectResourcesUnder(root, wantLooped, recursive) {
+    const result = [];
+    const consider = (node) => {
+        if (!isResourceDeclaration(node))
+            return;
+        const r = node.self;
+        if (isLoopedResource(r) === wantLooped)
+            result.push(r);
+    };
+    for (const child of root.children) {
+        if (recursive)
+            child.visit(consider);
+        else
+            consider(child);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Engine entry points — thin, loosely-typed; `Stack` supplies the public
+// typed overloads and delegates here.
+// ---------------------------------------------------------------------------
+/** Scalar (un-looped) resource declarations. */
+export function getResources(root, typeOrOptions, maybeOptions) {
+    const isCtor = typeof typeOrOptions === "function";
+    const type = isCtor ? typeOrOptions : undefined;
+    const options = (isCtor ? maybeOptions : typeOrOptions);
+    const recursive = options?.recursive ?? true;
+    const found = collectResourcesUnder(root, false, recursive);
+    return type === undefined ? found : found.filter((r) => r instanceof type);
+}
+/** Loop-expanded resource declarations (`Ctor.fromLoop(...)`). */
+export function getLoopedResources(root, typeOrOptions, maybeOptions) {
+    const isCtor = typeof typeOrOptions === "function";
+    const type = isCtor ? typeOrOptions : undefined;
+    const options = (isCtor ? maybeOptions : typeOrOptions);
+    const recursive = options?.recursive ?? true;
+    const found = collectResourcesUnder(root, true, recursive);
+    return type === undefined ? found : found.filter((r) => isLoopedResourceOf(r, type));
+}
+/**
+ * First scalar resource of `type` whose literal name equals `name`, or
+ * `undefined`. `deref` resolves the name's expression proxy to its literal
+ * (a `Resource`'s `name` is an `Expression`, so `r.name === name` is always
+ * false without it).
+ */
+export function getResource(root, type, name, options) {
+    for (const r of getResources(root, type, options)) {
+        if (deref(r.name) === name)
+            return r;
+    }
+    return undefined;
+}
+//# sourceMappingURL=resource-query.js.map

package/dist/esm/constructs/resource/resource-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-query.js","sourceRoot":"","sources":["../../../../src/constructs/resource/resource-query.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT License.\n\nimport { isResourceDeclaration, isLoopedResource, isLoopedResourceOf } from \"./resource-utils.js\";\nimport { deref } from \"./resource-proxy.js\";\nimport type { ProvisioningComponent } from \"../provisioning-component.js\";\nimport type { LoopedResource, Resource } from \"./resource.js\";\nimport type { ResourceCtor } from \"./resource-registry.js\";\n\n// ---------------------------------------------------------------------------\n// Query result types\n// ---------------------------------------------------------------------------\n\n/** Options accepted by the `Stack` resource queries. */\nexport interface QueryOptions {\n  /**\n   * Whether to walk the stack's entire subtree (default `true`) or only its\n   * **direct children** (`false`).\n   */\n  readonly recursive?: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Query engine (module-private)\n// ---------------------------------------------------------------------------\n// Imports only brand guards (`resource-utils`) — which do not import\n// `ProvisioningComponent`/`Stack` at runtime — plus types (type-only), so there is no\n// import cycle.\n\n/**\n * Collect the resource declarations beneath `root` (the root itself is never\n * included). `recursive` descends the whole subtree via `visit`; otherwise\n * only `root`'s direct children are considered. `wantLooped` selects the\n * looped declarations (`Ctor.fromLoop(...)`) vs. the scalar ones.\n */\nfunction collectResourcesUnder(\n  root: ProvisioningComponent,\n  wantLooped: boolean,\n  recursive: boolean,\n): (Resource | LoopedResource<Resource>)[] {\n  const result: (Resource | LoopedResource<Resource>)[] = [];\n  const consider = (node: ProvisioningComponent): void => {\n    if (!isResourceDeclaration(node)) return;\n    const r = node.self as Resource | LoopedResource<Resource>;\n    if (isLoopedResource(r) === wantLooped) result.push(r);\n  };\n  for (const child of root.children) {\n    if (recursive) child.visit(consider);\n    else consider(child);\n  }\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// Engine entry points — thin, loosely-typed; `Stack` supplies the public\n// typed overloads and delegates here.\n// ---------------------------------------------------------------------------\n\n/** Scalar (un-looped) resource declarations. */\nexport function getResources(\n  root: ProvisioningComponent,\n  typeOrOptions?: ResourceCtor<Resource> | QueryOptions,\n  maybeOptions?: QueryOptions,\n): Resource[] {\n  const isCtor = typeof typeOrOptions === \"function\";\n  const type = isCtor ? (typeOrOptions as ResourceCtor<Resource>) : undefined;\n  const options = (isCtor ? maybeOptions : typeOrOptions) as QueryOptions | undefined;\n  const recursive = options?.recursive ?? true;\n  const found = collectResourcesUnder(root, false, recursive) as Resource[];\n  return type === undefined ? found : found.filter((r) => r instanceof type);\n}\n\n/** Loop-expanded resource declarations (`Ctor.fromLoop(...)`). */\nexport function getLoopedResources(\n  root: ProvisioningComponent,\n  typeOrOptions?: ResourceCtor<Resource> | QueryOptions,\n  maybeOptions?: QueryOptions,\n): LoopedResource<Resource>[] {\n  const isCtor = typeof typeOrOptions === \"function\";\n  const type = isCtor ? (typeOrOptions as ResourceCtor<Resource>) : undefined;\n  const options = (isCtor ? maybeOptions : typeOrOptions) as QueryOptions | undefined;\n  const recursive = options?.recursive ?? true;\n  const found = collectResourcesUnder(root, true, recursive) as LoopedResource<Resource>[];\n  return type === undefined ? found : found.filter((r) => isLoopedResourceOf(r, type));\n}\n\n/**\n * First scalar resource of `type` whose literal name equals `name`, or\n * `undefined`. `deref` resolves the name's expression proxy to its literal\n * (a `Resource`'s `name` is an `Expression`, so `r.name === name` is always\n * false without it).\n */\nexport function getResource<T extends Resource>(\n  root: ProvisioningComponent,\n  type: ResourceCtor<T>,\n  name: string,\n  options?: QueryOptions,\n): T | undefined {\n  for (const r of getResources(root, type, options)) {\n    if (deref((r as Resource).name) === name) return r as T;\n  }\n  return undefined;\n}\n"]}

package/dist/esm/constructs/resource/resource-registry.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Global registry mapping a resource class's registry key to its
+ * constructor.
+ *
+ * Populated at module load by each class's `static {}` initializer
+ * (via {@link Resource.register}). The deserializer reads this
+ * registry to construct the correct class instance — preserving
+ * identity, prototype methods, and constructor-initialized child
+ * collections — instead of materialising a base `Resource`.
+ *
+ * Each `type@apiVersion` entry is either one flat constructor or a flat list
+ * of concrete constructors paired with ordered variant selectors. A selector
+ * can contain singleton `name`, model discriminators such as `kind`, and
+ * nested discriminator segments.
+ *
+ * Resolution has two modes:
+ *
+ * - **Best-effort (default).** Exact `(type, apiVersion)` first, then
+ *   falls back to the highest registered `apiVersion` for the same
+ *   selector. Enables
+ *   deserializing older JSON against a newer package version without
+ *   losing typed handles.
+ * - **Strict** (opt-in via `{ strict: true }`). Exact match only;
+ *   returns `undefined` for any apiVersion the package doesn't ship.
+ *
+ * The shared registry tracks the highest `apiVersion` per `(type, selector)`.
+ * Best-effort lookups consult it in O(1); no scanning is needed.
+ *
+ * Keyed on a process-global symbol so multiple copies of `@azure/provisioning-core`
+ * in the same realm share one registry, mirroring the cross-realm
+ * strategy used by {@link isResource}'s brand symbol.
+ */
+import type { Resource } from "./resource.js";
+import { type FlatVariantSelector } from "./resource-type-registry.js";
+/**
+ * A `Resource` class that's eligible to live in the registry.
+ *
+ * - The construct signature uses `any` for both `context` and `props`
+ *   because concrete classes narrow these (child resources require a
+ *   specific parent class as context; each resource has its own `Props`
+ *   shape). TypeScript's parameter contravariance would reject any
+ *   concrete parameter types here. The deserializer is the sole caller
+ *   of resolved constructors and forwards already-correct values it
+ *   built from the wire document.
+ * - The two static fields `resourceType` and `apiVersion` form the
+ *   registry key and are always present on emitter-generated classes
+ *   (and on the hand-maintained `ResourceGroup`).
+ * - The generic `T` propagates the instance type — used by the query
+ *   API (`stack.getResources(KeyVault)` → `KeyVault[]`) to narrow
+ *   return types without needing a separate descriptor object.
+ */
+export type ResourceCtor<T extends Resource = Resource> = {
+    new (context: any, props: any, options?: any): T;
+    readonly resourceType: string;
+    readonly apiVersion: string;
+};
+/**
+ * Options controlling how {@link resolveResource} handles
+ * apiVersion mismatches.
+ */
+export interface ResolveOptions {
+    /**
+     * When `true`, only an exact `(resourceType, apiVersion)` match is
+     * returned; the best-effort fallback to the highest registered
+     * version for the type is skipped. Defaults to `false`.
+     */
+    readonly strict?: boolean;
+}
+/**
+ * Register `ctor` as the canonical class for its
+ * `(resourceType, apiVersion[, variantSelector])` key.
+ *
+ * Pass an ordered selector for variants; omit it for ordinary resources.
+ * Re-registering the same constructor for the
+ * same key is a silent no-op so module-graph re-entry (test
+ * harnesses, dual-format builds) is safe. Registering a *different*
+ * constructor for an existing key throws — that's a genuine conflict
+ * (e.g. two packages claiming the same ARM type).
+ *
+ * A `(resourceType, apiVersion)` pair is either entirely flat or entirely
+ * variant-based. Attempting to mix both modes throws,
+ * preserving the invariant the deserializer relies on.
+ */
+export declare function registerResource(ctor: ResourceCtor, variantSelector?: FlatVariantSelector): void;
+/**
+ * Resolve the registered class for a wire resource.
+ *
+ * Default is best-effort:
+ *  1. Try the exact `(type, apiVersion)` entry and match its selectors
+ *     against ARM-side keys in `state`.
+ *  2. On miss, retry with the highest registered version of each selector.
+ *
+ * Pass `{ strict: true }` to skip step 2 and require an exact match.
+ *
+ * Returns `undefined` when nothing matches — callers (notably the
+ * deserializer) then fall back to constructing a base `Resource`.
+ */
+export declare function resolveResource(type: string, apiVersion: string, state?: Record<string, unknown>, options?: ResolveOptions): ResourceCtor | undefined;
+//# sourceMappingURL=resource-registry.d.ts.map

package/dist/esm/constructs/resource/resource-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-registry.d.ts","sourceRoot":"","sources":["../../../../src/constructs/resource/resource-registry.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAE7F;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAAI;IACxD,KAAK,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAkBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,EAAE,eAAe,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAEhG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,cAAc,GACvB,YAAY,GAAG,SAAS,CAK1B"}

package/dist/esm/constructs/resource/resource-registry.js

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { ResourceTypeRegistry } from "./resource-type-registry.js";
+const REGISTRY_SYMBOL = Symbol.for("@azure/provisioning-core.resourceRegistry");
+function getRegistry() {
+    const host = globalThis;
+    let registry = host[REGISTRY_SYMBOL];
+    if (registry === undefined) {
+        registry = new ResourceTypeRegistry();
+        host[REGISTRY_SYMBOL] = registry;
+    }
+    return registry;
+}
+/**
+ * Register `ctor` as the canonical class for its
+ * `(resourceType, apiVersion[, variantSelector])` key.
+ *
+ * Pass an ordered selector for variants; omit it for ordinary resources.
+ * Re-registering the same constructor for the
+ * same key is a silent no-op so module-graph re-entry (test
+ * harnesses, dual-format builds) is safe. Registering a *different*
+ * constructor for an existing key throws — that's a genuine conflict
+ * (e.g. two packages claiming the same ARM type).
+ *
+ * A `(resourceType, apiVersion)` pair is either entirely flat or entirely
+ * variant-based. Attempting to mix both modes throws,
+ * preserving the invariant the deserializer relies on.
+ */
+export function registerResource(ctor, variantSelector) {
+    getRegistry().register(ctor.resourceType, ctor.apiVersion, ctor, variantSelector);
+}
+/**
+ * Resolve the registered class for a wire resource.
+ *
+ * Default is best-effort:
+ *  1. Try the exact `(type, apiVersion)` entry and match its selectors
+ *     against ARM-side keys in `state`.
+ *  2. On miss, retry with the highest registered version of each selector.
+ *
+ * Pass `{ strict: true }` to skip step 2 and require an exact match.
+ *
+ * Returns `undefined` when nothing matches — callers (notably the
+ * deserializer) then fall back to constructing a base `Resource`.
+ */
+export function resolveResource(type, apiVersion, state, options) {
+    return getRegistry().resolve(type, apiVersion, state ?? {}, {
+        strict: options?.strict ?? false,
+        valueKeyedBy: "arm",
+    });
+}
+//# sourceMappingURL=resource-registry.js.map

package/dist/esm/constructs/resource/resource-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-registry.js","sourceRoot":"","sources":["../../../../src/constructs/resource/resource-registry.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,kCAAkC;AAoClC,OAAO,EAAE,oBAAoB,EAA4B,MAAM,6BAA6B,CAAC;AAsC7F,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;AAMhF,SAAS,WAAW;IAClB,MAAM,IAAI,GAAG,UAAqC,CAAC;IACnD,IAAI,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,CAAC;IACrC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,QAAQ,GAAG,IAAI,oBAAoB,EAAgB,CAAC;QACpD,IAAI,CAAC,eAAe,CAAC,GAAG,QAAQ,CAAC;IACnC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAkB,EAAE,eAAqC;IACxF,WAAW,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC;AACpF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAY,EACZ,UAAkB,EAClB,KAA+B,EAC/B,OAAwB;IAExB,OAAO,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,IAAI,EAAE,EAAE;QAC1D,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,KAAK;QAChC,YAAY,EAAE,KAAK;KACpB,CAAC,CAAC;AACL,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT License.\n\n/**\n * Global registry mapping a resource class's registry key to its\n * constructor.\n *\n * Populated at module load by each class's `static {}` initializer\n * (via {@link Resource.register}). The deserializer reads this\n * registry to construct the correct class instance — preserving\n * identity, prototype methods, and constructor-initialized child\n * collections — instead of materialising a base `Resource`.\n *\n * Each `type@apiVersion` entry is either one flat constructor or a flat list\n * of concrete constructors paired with ordered variant selectors. A selector\n * can contain singleton `name`, model discriminators such as `kind`, and\n * nested discriminator segments.\n *\n * Resolution has two modes:\n *\n * - **Best-effort (default).** Exact `(type, apiVersion)` first, then\n *   falls back to the highest registered `apiVersion` for the same\n *   selector. Enables\n *   deserializing older JSON against a newer package version without\n *   losing typed handles.\n * - **Strict** (opt-in via `{ strict: true }`). Exact match only;\n *   returns `undefined` for any apiVersion the package doesn't ship.\n *\n * The shared registry tracks the highest `apiVersion` per `(type, selector)`.\n * Best-effort lookups consult it in O(1); no scanning is needed.\n *\n * Keyed on a process-global symbol so multiple copies of `@azure/provisioning-core`\n * in the same realm share one registry, mirroring the cross-realm\n * strategy used by {@link isResource}'s brand symbol.\n */\n\nimport type { Resource } from \"./resource.js\";\nimport { ResourceTypeRegistry, type FlatVariantSelector } from \"./resource-type-registry.js\";\n\n/**\n * A `Resource` class that's eligible to live in the registry.\n *\n * - The construct signature uses `any` for both `context` and `props`\n *   because concrete classes narrow these (child resources require a\n *   specific parent class as context; each resource has its own `Props`\n *   shape). TypeScript's parameter contravariance would reject any\n *   concrete parameter types here. The deserializer is the sole caller\n *   of resolved constructors and forwards already-correct values it\n *   built from the wire document.\n * - The two static fields `resourceType` and `apiVersion` form the\n *   registry key and are always present on emitter-generated classes\n *   (and on the hand-maintained `ResourceGroup`).\n * - The generic `T` propagates the instance type — used by the query\n *   API (`stack.getResources(KeyVault)` → `KeyVault[]`) to narrow\n *   return types without needing a separate descriptor object.\n */\nexport type ResourceCtor<T extends Resource = Resource> = {\n  new (context: any, props: any, options?: any): T;\n  readonly resourceType: string;\n  readonly apiVersion: string;\n};\n\n/**\n * Options controlling how {@link resolveResource} handles\n * apiVersion mismatches.\n */\nexport interface ResolveOptions {\n  /**\n   * When `true`, only an exact `(resourceType, apiVersion)` match is\n   * returned; the best-effort fallback to the highest registered\n   * version for the type is skipped. Defaults to `false`.\n   */\n  readonly strict?: boolean;\n}\n\nconst REGISTRY_SYMBOL = Symbol.for(\"@azure/provisioning-core.resourceRegistry\");\n\ninterface RegistryHost {\n  [REGISTRY_SYMBOL]?: ResourceTypeRegistry<ResourceCtor>;\n}\n\nfunction getRegistry(): ResourceTypeRegistry<ResourceCtor> {\n  const host = globalThis as unknown as RegistryHost;\n  let registry = host[REGISTRY_SYMBOL];\n  if (registry === undefined) {\n    registry = new ResourceTypeRegistry<ResourceCtor>();\n    host[REGISTRY_SYMBOL] = registry;\n  }\n  return registry;\n}\n\n/**\n * Register `ctor` as the canonical class for its\n * `(resourceType, apiVersion[, variantSelector])` key.\n *\n * Pass an ordered selector for variants; omit it for ordinary resources.\n * Re-registering the same constructor for the\n * same key is a silent no-op so module-graph re-entry (test\n * harnesses, dual-format builds) is safe. Registering a *different*\n * constructor for an existing key throws — that's a genuine conflict\n * (e.g. two packages claiming the same ARM type).\n *\n * A `(resourceType, apiVersion)` pair is either entirely flat or entirely\n * variant-based. Attempting to mix both modes throws,\n * preserving the invariant the deserializer relies on.\n */\nexport function registerResource(ctor: ResourceCtor, variantSelector?: FlatVariantSelector): void {\n  getRegistry().register(ctor.resourceType, ctor.apiVersion, ctor, variantSelector);\n}\n\n/**\n * Resolve the registered class for a wire resource.\n *\n * Default is best-effort:\n *  1. Try the exact `(type, apiVersion)` entry and match its selectors\n *     against ARM-side keys in `state`.\n *  2. On miss, retry with the highest registered version of each selector.\n *\n * Pass `{ strict: true }` to skip step 2 and require an exact match.\n *\n * Returns `undefined` when nothing matches — callers (notably the\n * deserializer) then fall back to constructing a base `Resource`.\n */\nexport function resolveResource(\n  type: string,\n  apiVersion: string,\n  state?: Record<string, unknown>,\n  options?: ResolveOptions,\n): ResourceCtor | undefined {\n  return getRegistry().resolve(type, apiVersion, state ?? {}, {\n    strict: options?.strict ?? false,\n    valueKeyedBy: \"arm\",\n  });\n}\n"]}

package/dist/esm/constructs/resource/resource-type-registry.d.ts

@@ -0,0 +1,46 @@
+import type { DiscriminatorNames } from "../../shape/shape.js";
+/** One discriminator pinned to a fixed value by a concrete flat variant. */
+export interface FlatVariantPin {
+    readonly discriminator: DiscriminatorNames;
+    readonly value: string;
+}
+/** Pins selecting one concrete flat variant. */
+export type FlatVariantSelector = readonly FlatVariantPin[];
+/** One concrete variant together with a selector that chooses it. */
+export interface FlatVariantSelection<T> {
+    readonly variant: T;
+    readonly selector: FlatVariantSelector;
+}
+/** One selector-to-target record stored in a variant registry bucket. */
+export interface FlatVariantRegistryEntry<T> {
+    readonly selector: FlatVariantSelector;
+    readonly target: T;
+}
+/** One `(resourceType, apiVersion)` registry bucket. */
+export type ResourceTypeRegistryEntry<T> = {
+    readonly kind: "flat";
+    readonly target: T;
+} | {
+    readonly kind: "variants";
+    readonly variants: FlatVariantRegistryEntry<T>[];
+};
+export interface ResourceTypeRegistryResolveOptions {
+    readonly strict: boolean;
+    readonly valueKeyedBy: "js" | "arm";
+}
+/** Registry for versioned resource-type targets with optional variants. */
+export declare class ResourceTypeRegistry<T> {
+    #private;
+    register(resourceType: string, apiVersion: string, target: T, variantSelector?: FlatVariantSelector): void;
+    resolve(resourceType: string, apiVersion: string, state: Record<string, unknown>, options: ResourceTypeRegistryResolveOptions): T | undefined;
+}
+/**
+ * Stable identity for duplicate detection and version indexes.
+ * Pins are sorted in the key because the matched state is flat and selector
+ * matching is a conjunction of discriminator/value pairs, independent of
+ * hierarchy order. The selector itself is not mutated.
+ */
+export declare function flatVariantSelectorKey(selector: FlatVariantSelector): string;
+/** Resolve the first registered selector exactly matched by `state`. */
+export declare function resolveFlatVariant<T>(entries: readonly FlatVariantRegistryEntry<T>[], state: Record<string, unknown> | undefined, valueKeyedBy: "js" | "arm"): T | undefined;
+//# sourceMappingURL=resource-type-registry.d.ts.map

package/dist/esm/constructs/resource/resource-type-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-type-registry.d.ts","sourceRoot":"","sources":["../../../../src/constructs/resource/resource-type-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,aAAa,EAAE,kBAAkB,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,gDAAgD;AAChD,MAAM,MAAM,mBAAmB,GAAG,SAAS,cAAc,EAAE,CAAC;AAE5D,qEAAqE;AACrE,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;CACxC;AAED,yEAAyE;AACzE,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;CACpB;AAED,wDAAwD;AACxD,MAAM,MAAM,yBAAyB,CAAC,CAAC,IACnC;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;CACpB,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC,CAAC,CAAC,EAAE,CAAC;CAClD,CAAC;AAEN,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,IAAI,GAAG,KAAK,CAAC;CACrC;AAOD,2EAA2E;AAC3E,qBAAa,oBAAoB,CAAC,CAAC;;IAIjC,QAAQ,CACN,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,CAAC,EACT,eAAe,CAAC,EAAE,mBAAmB,GACpC,IAAI;IAYP,OAAO,CACL,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,kCAAkC,GAC1C,CAAC,GAAG,SAAS;CA6DjB;AAgFD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CAM5E;AAaD,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,OAAO,EAAE,SAAS,wBAAwB,CAAC,CAAC,CAAC,EAAE,EAC/C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC1C,YAAY,EAAE,IAAI,GAAG,KAAK,GACzB,CAAC,GAAG,SAAS,CASf"}

package/dist/esm/constructs/resource/resource-type-registry.js

@@ -0,0 +1,156 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+/** Registry for versioned resource-type targets with optional variants. */
+export class ResourceTypeRegistry {
+    #exact = new Map();
+    #highest = new Map();
+    register(resourceType, apiVersion, target, variantSelector) {
+        const selector = variantSelector?.length ? variantSelector : undefined;
+        const exactKey = resourceTypeVersionKey(resourceType, apiVersion);
+        const exactEntry = this.#exact.get(exactKey);
+        const highestEntry = this.#highest.get(resourceType);
+        assertMode(exactEntry, selector, exactKey);
+        assertMode(highestEntry, selector, resourceType);
+        registerExact(this.#exact, exactKey, target, selector);
+        this.#updateHighest(resourceType, apiVersion, target, selector);
+    }
+    resolve(resourceType, apiVersion, state, options) {
+        const exact = resolveEntry(this.#exact.get(resourceTypeVersionKey(resourceType, apiVersion)), state, options.valueKeyedBy);
+        if (exact !== undefined || options.strict)
+            return exact;
+        const fallback = resolveEntry(this.#highest.get(resourceType), state, options.valueKeyedBy);
+        return fallback?.target;
+    }
+    #updateHighest(resourceType, apiVersion, target, selector) {
+        const entry = this.#highest.get(resourceType);
+        const versionedTarget = { apiVersion, target };
+        if (!entry) {
+            this.#highest.set(resourceType, selector
+                ? {
+                    kind: "variants",
+                    variants: [{ selector: [...selector], target: versionedTarget }],
+                }
+                : { kind: "flat", target: versionedTarget });
+            return;
+        }
+        if (entry.kind === "flat") {
+            if (apiVersionCompare(apiVersion, entry.target.apiVersion) > 0) {
+                this.#highest.set(resourceType, {
+                    kind: "flat",
+                    target: versionedTarget,
+                });
+            }
+            return;
+        }
+        const selectorKey = flatVariantSelectorKey(selector);
+        const priorIndex = entry.variants.findIndex((variant) => flatVariantSelectorKey(variant.selector) === selectorKey);
+        const prior = entry.variants[priorIndex];
+        if (!prior) {
+            entry.variants.push({
+                selector: [...selector],
+                target: versionedTarget,
+            });
+        }
+        else if (apiVersionCompare(apiVersion, prior.target.apiVersion) > 0) {
+            entry.variants[priorIndex] = {
+                selector: [...selector],
+                target: versionedTarget,
+            };
+        }
+    }
+}
+function assertMode(entry, selector, key) {
+    if (!entry)
+        return;
+    if (!selector && entry.kind === "variants") {
+        throw new Error(`Cannot register flat target for ${key}: variants are already registered.`);
+    }
+    if (selector && entry.kind === "flat") {
+        throw new Error(`Cannot register variant target for ${key}: a flat target is already registered.`);
+    }
+}
+function registerExact(entries, key, target, selector) {
+    const entry = entries.get(key);
+    if (!entry) {
+        entries.set(key, selector
+            ? {
+                kind: "variants",
+                variants: [{ selector: [...selector], target }],
+            }
+            : { kind: "flat", target });
+        return;
+    }
+    if (entry.kind === "flat") {
+        if (entry.target !== target) {
+            throw new Error(`Conflicting flat target registration for ${key}.`);
+        }
+        return;
+    }
+    const selectorKey = flatVariantSelectorKey(selector);
+    const existing = entry.variants.find((variant) => flatVariantSelectorKey(variant.selector) === selectorKey);
+    if (existing) {
+        if (existing.target !== target) {
+            throw new Error(`Conflicting variant target registration for ${key}@${selectorKey}.`);
+        }
+        return;
+    }
+    entry.variants.push({ selector: [...selector], target });
+}
+function resolveEntry(entry, state, valueKeyedBy) {
+    if (!entry)
+        return undefined;
+    if (entry.kind === "flat")
+        return entry.target;
+    return resolveFlatVariant(entry.variants, state, valueKeyedBy);
+}
+function resourceTypeVersionKey(resourceType, apiVersion) {
+    return `${resourceType}@${apiVersion}`;
+}
+/** Compare ARM API versions for best-effort fallback selection. */
+function apiVersionCompare(left, right) {
+    if (left === right)
+        return 0;
+    if (right.startsWith(`${left}-`))
+        return 1;
+    if (left.startsWith(`${right}-`))
+        return -1;
+    return left < right ? -1 : 1;
+}
+/**
+ * Stable identity for duplicate detection and version indexes.
+ * Pins are sorted in the key because the matched state is flat and selector
+ * matching is a conjunction of discriminator/value pairs, independent of
+ * hierarchy order. The selector itself is not mutated.
+ */
+export function flatVariantSelectorKey(selector) {
+    const pins = selector.map(({ discriminator, value }) => [discriminator.jsName, discriminator.armName, value]);
+    pins.sort(comparePinTuples);
+    return JSON.stringify(pins);
+}
+function comparePinTuples(left, right) {
+    for (let index = 0; index < left.length; index++) {
+        if (left[index] < right[index])
+            return -1;
+        if (left[index] > right[index])
+            return 1;
+    }
+    return 0;
+}
+/** Resolve the first registered selector exactly matched by `state`. */
+export function resolveFlatVariant(entries, state, valueKeyedBy) {
+    if (!state)
+        return undefined;
+    for (const entry of entries) {
+        if (matchesSelector(entry.selector, state, valueKeyedBy)) {
+            return entry.target;
+        }
+    }
+    return undefined;
+}
+function matchesSelector(selector, state, valueKeyedBy) {
+    return selector.every(({ discriminator, value }) => {
+        const key = valueKeyedBy === "js" ? discriminator.jsName : discriminator.armName;
+        return state[key] === value;
+    });
+}
+//# sourceMappingURL=resource-type-registry.js.map

package/dist/esm/constructs/resource/resource-type-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-type-registry.js","sourceRoot":"","sources":["../../../../src/constructs/resource/resource-type-registry.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT License.\n\nimport type { DiscriminatorNames } from \"../../shape/shape.js\";\n\n/** One discriminator pinned to a fixed value by a concrete flat variant. */\nexport interface FlatVariantPin {\n  readonly discriminator: DiscriminatorNames;\n  readonly value: string;\n}\n\n/** Pins selecting one concrete flat variant. */\nexport type FlatVariantSelector = readonly FlatVariantPin[];\n\n/** One concrete variant together with a selector that chooses it. */\nexport interface FlatVariantSelection<T> {\n  readonly variant: T;\n  readonly selector: FlatVariantSelector;\n}\n\n/** One selector-to-target record stored in a variant registry bucket. */\nexport interface FlatVariantRegistryEntry<T> {\n  readonly selector: FlatVariantSelector;\n  readonly target: T;\n}\n\n/** One `(resourceType, apiVersion)` registry bucket. */\nexport type ResourceTypeRegistryEntry<T> =\n  | {\n      readonly kind: \"flat\";\n      readonly target: T;\n    }\n  | {\n      readonly kind: \"variants\";\n      readonly variants: FlatVariantRegistryEntry<T>[];\n    };\n\nexport interface ResourceTypeRegistryResolveOptions {\n  readonly strict: boolean;\n  readonly valueKeyedBy: \"js\" | \"arm\";\n}\n\ninterface VersionedTarget<T> {\n  readonly apiVersion: string;\n  readonly target: T;\n}\n\n/** Registry for versioned resource-type targets with optional variants. */\nexport class ResourceTypeRegistry<T> {\n  readonly #exact = new Map<string, ResourceTypeRegistryEntry<T>>();\n  readonly #highest = new Map<string, ResourceTypeRegistryEntry<VersionedTarget<T>>>();\n\n  register(\n    resourceType: string,\n    apiVersion: string,\n    target: T,\n    variantSelector?: FlatVariantSelector,\n  ): void {\n    const selector = variantSelector?.length ? variantSelector : undefined;\n    const exactKey = resourceTypeVersionKey(resourceType, apiVersion);\n    const exactEntry = this.#exact.get(exactKey);\n    const highestEntry = this.#highest.get(resourceType);\n\n    assertMode(exactEntry, selector, exactKey);\n    assertMode(highestEntry, selector, resourceType);\n    registerExact(this.#exact, exactKey, target, selector);\n    this.#updateHighest(resourceType, apiVersion, target, selector);\n  }\n\n  resolve(\n    resourceType: string,\n    apiVersion: string,\n    state: Record<string, unknown>,\n    options: ResourceTypeRegistryResolveOptions,\n  ): T | undefined {\n    const exact = resolveEntry(\n      this.#exact.get(resourceTypeVersionKey(resourceType, apiVersion)),\n      state,\n      options.valueKeyedBy,\n    );\n    if (exact !== undefined || options.strict) return exact;\n\n    const fallback = resolveEntry(this.#highest.get(resourceType), state, options.valueKeyedBy);\n    return fallback?.target;\n  }\n\n  #updateHighest(\n    resourceType: string,\n    apiVersion: string,\n    target: T,\n    selector: FlatVariantSelector | undefined,\n  ): void {\n    const entry = this.#highest.get(resourceType);\n    const versionedTarget = { apiVersion, target };\n\n    if (!entry) {\n      this.#highest.set(\n        resourceType,\n        selector\n          ? {\n              kind: \"variants\",\n              variants: [{ selector: [...selector], target: versionedTarget }],\n            }\n          : { kind: \"flat\", target: versionedTarget },\n      );\n      return;\n    }\n\n    if (entry.kind === \"flat\") {\n      if (apiVersionCompare(apiVersion, entry.target.apiVersion) > 0) {\n        this.#highest.set(resourceType, {\n          kind: \"flat\",\n          target: versionedTarget,\n        });\n      }\n      return;\n    }\n\n    const selectorKey = flatVariantSelectorKey(selector!);\n    const priorIndex = entry.variants.findIndex(\n      (variant) => flatVariantSelectorKey(variant.selector) === selectorKey,\n    );\n    const prior = entry.variants[priorIndex];\n    if (!prior) {\n      entry.variants.push({\n        selector: [...selector!],\n        target: versionedTarget,\n      });\n    } else if (apiVersionCompare(apiVersion, prior.target.apiVersion) > 0) {\n      entry.variants[priorIndex] = {\n        selector: [...selector!],\n        target: versionedTarget,\n      };\n    }\n  }\n}\n\nfunction assertMode<T>(\n  entry: ResourceTypeRegistryEntry<T> | undefined,\n  selector: FlatVariantSelector | undefined,\n  key: string,\n): void {\n  if (!entry) return;\n  if (!selector && entry.kind === \"variants\") {\n    throw new Error(`Cannot register flat target for ${key}: variants are already registered.`);\n  }\n  if (selector && entry.kind === \"flat\") {\n    throw new Error(\n      `Cannot register variant target for ${key}: a flat target is already registered.`,\n    );\n  }\n}\n\nfunction registerExact<T>(\n  entries: Map<string, ResourceTypeRegistryEntry<T>>,\n  key: string,\n  target: T,\n  selector: FlatVariantSelector | undefined,\n): void {\n  const entry = entries.get(key);\n  if (!entry) {\n    entries.set(\n      key,\n      selector\n        ? {\n            kind: \"variants\",\n            variants: [{ selector: [...selector], target }],\n          }\n        : { kind: \"flat\", target },\n    );\n    return;\n  }\n\n  if (entry.kind === \"flat\") {\n    if (entry.target !== target) {\n      throw new Error(`Conflicting flat target registration for ${key}.`);\n    }\n    return;\n  }\n\n  const selectorKey = flatVariantSelectorKey(selector!);\n  const existing = entry.variants.find(\n    (variant) => flatVariantSelectorKey(variant.selector) === selectorKey,\n  );\n  if (existing) {\n    if (existing.target !== target) {\n      throw new Error(`Conflicting variant target registration for ${key}@${selectorKey}.`);\n    }\n    return;\n  }\n  entry.variants.push({ selector: [...selector!], target });\n}\n\nfunction resolveEntry<T>(\n  entry: ResourceTypeRegistryEntry<T> | undefined,\n  state: Record<string, unknown>,\n  valueKeyedBy: \"js\" | \"arm\",\n): T | undefined {\n  if (!entry) return undefined;\n  if (entry.kind === \"flat\") return entry.target;\n  return resolveFlatVariant(entry.variants, state, valueKeyedBy);\n}\n\nfunction resourceTypeVersionKey(resourceType: string, apiVersion: string): string {\n  return `${resourceType}@${apiVersion}`;\n}\n\n/** Compare ARM API versions for best-effort fallback selection. */\nfunction apiVersionCompare(left: string, right: string): number {\n  if (left === right) return 0;\n  if (right.startsWith(`${left}-`)) return 1;\n  if (left.startsWith(`${right}-`)) return -1;\n  return left < right ? -1 : 1;\n}\n\n/**\n * Stable identity for duplicate detection and version indexes.\n * Pins are sorted in the key because the matched state is flat and selector\n * matching is a conjunction of discriminator/value pairs, independent of\n * hierarchy order. The selector itself is not mutated.\n */\nexport function flatVariantSelectorKey(selector: FlatVariantSelector): string {\n  const pins = selector.map(\n    ({ discriminator, value }) => [discriminator.jsName, discriminator.armName, value] as const,\n  );\n  pins.sort(comparePinTuples);\n  return JSON.stringify(pins);\n}\n\nfunction comparePinTuples(\n  left: readonly [string, string, string],\n  right: readonly [string, string, string],\n): number {\n  for (let index = 0; index < left.length; index++) {\n    if (left[index]! < right[index]!) return -1;\n    if (left[index]! > right[index]!) return 1;\n  }\n  return 0;\n}\n\n/** Resolve the first registered selector exactly matched by `state`. */\nexport function resolveFlatVariant<T>(\n  entries: readonly FlatVariantRegistryEntry<T>[],\n  state: Record<string, unknown> | undefined,\n  valueKeyedBy: \"js\" | \"arm\",\n): T | undefined {\n  if (!state) return undefined;\n\n  for (const entry of entries) {\n    if (matchesSelector(entry.selector, state, valueKeyedBy)) {\n      return entry.target;\n    }\n  }\n  return undefined;\n}\n\nfunction matchesSelector(\n  selector: FlatVariantSelector,\n  state: Record<string, unknown>,\n  valueKeyedBy: \"js\" | \"arm\",\n): boolean {\n  return selector.every(({ discriminator, value }) => {\n    const key = valueKeyedBy === \"js\" ? discriminator.jsName : discriminator.armName;\n    return state[key] === value;\n  });\n}\n"]}

package/dist/esm/constructs/resource/resource-utils.d.ts

@@ -0,0 +1,60 @@
+import type { Resource, ResourceDeclaration, LoopedResource } from "./resource.js";
+import type { ResourceCtor } from "./resource-registry.js";
+/**
+ * Cross-realm-safe brand guards for resource declarations.
+ *
+ * These live in a standalone module — importing only the brand **symbols**
+ * (from `resource-proxy.ts`) and `resource.ts` **types** — so tree-walking
+ * utilities (e.g. the query layer, `ProvisioningComponent`) can identify resources
+ * WITHOUT a runtime import of `resource.ts`, which `extends ProvisioningComponent` and
+ * would otherwise create an eval-time import cycle
+ * (`ProvisioningComponent` → `query` → `resource` → `ProvisioningComponent`).
+ *
+ * The public guard API is these standalone functions (`isResource`,
+ * `isResourceDeclaration`, `isLoopedResource`, `isResourceOf`,
+ * `isLoopedResourceOf`) — there are no class-static guards, so a subclass
+ * like `Secret` never inherits a misleading `Secret.isResource(...)`.
+ */
+/** Is `x` a scalar {@link Resource} (not a looped declaration)? */
+export declare function isResource(x: unknown): x is Resource;
+/**
+ * Is `x` a Bicep resource declaration — either a scalar {@link Resource} or
+ * a {@link LoopedResource}?
+ */
+export declare function isResourceDeclaration(x: unknown): x is ResourceDeclaration;
+/** Is `x` a {@link LoopedResource} (`Ctor.fromLoop(...)`)? */
+export declare function isLoopedResource(x: unknown): x is LoopedResource<Resource>;
+/**
+ * Type guard: is `x` an instance of the resource class `ctor`?
+ * Narrows `x` to the class's instance type, so callers can access
+ * subclass-specific accessors (e.g. `kv.secrets`) inside the guarded
+ * block.
+ *
+ * Accepts any value (`unknown`), like the other brand guards. A
+ * `LoopedResource<T>` is not a `Resource`, so `instanceof ctor` returns
+ * `false` for it — the narrowing is safe. `instanceof` alone is sufficient
+ * (and stricter than a brand + ARM-type-string check: a base-`Resource`
+ * impostor carrying the same `type`/`apiVersion` is correctly rejected), so
+ * no `isResource` pre-check is needed.
+ *
+ * Matches scalar resource **declarations** (from a constructor / query /
+ * collection). It does NOT match a `parent.at(i)` element reference of a
+ * looped declaration: that proxy intentionally keeps `LoopedResource`'s
+ * prototype (no `getPrototypeOf` trap), so `instanceof` is `false` for it
+ * even though its ARM reads work. If we ever need cross-realm subclass
+ * matching (per-subclass `Symbol.for` brands, mirroring the base
+ * `RESOURCE_BRAND`), this is the one place to swap.
+ */
+export declare function isResourceOf<T extends Resource>(x: unknown, ctor: ResourceCtor<T>): x is T;
+/**
+ * Type guard: is `x` a {@link LoopedResource} whose wrapped resource class is
+ * `ctor` (i.e. a `LoopedResource<T>` produced by `T.fromLoop(...)`)? Narrows
+ * `x` to `LoopedResource<T>`, the looped analogue of {@link isResourceOf}.
+ *
+ * Matches on the declaration's `wrappedCtor` identity — the concrete subclass
+ * passed to `fromLoop` — so `isLoopedResourceOf(x, StorageAccount)`
+ * replaces the `x.wrappedCtor === StorageAccount` checks scattered across the
+ * query / collection layers.
+ */
+export declare function isLoopedResourceOf<T extends Resource>(x: unknown, ctor: ResourceCtor<T>): x is LoopedResource<T>;
+//# sourceMappingURL=resource-utils.d.ts.map

package/dist/esm/constructs/resource/resource-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-utils.d.ts","sourceRoot":"","sources":["../../../../src/constructs/resource/resource-utils.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;;;;GAcG;AAEH,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,QAAQ,CAIpD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,mBAAmB,CAM1E;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,cAAc,CAAC,QAAQ,CAAC,CAM1E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAE1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,QAAQ,EACnD,CAAC,EAAE,OAAO,EACV,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GACpB,CAAC,IAAI,cAAc,CAAC,CAAC,CAAC,CAExB"}

package/dist/esm/constructs/resource/resource-utils.js

@@ -0,0 +1,75 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { RESOURCE_BRAND, RESOURCE_DECLARATION_BRAND, LOOPED_RESOURCE_BRAND, } from "./resource-proxy.js";
+/**
+ * Cross-realm-safe brand guards for resource declarations.
+ *
+ * These live in a standalone module — importing only the brand **symbols**
+ * (from `resource-proxy.ts`) and `resource.ts` **types** — so tree-walking
+ * utilities (e.g. the query layer, `ProvisioningComponent`) can identify resources
+ * WITHOUT a runtime import of `resource.ts`, which `extends ProvisioningComponent` and
+ * would otherwise create an eval-time import cycle
+ * (`ProvisioningComponent` → `query` → `resource` → `ProvisioningComponent`).
+ *
+ * The public guard API is these standalone functions (`isResource`,
+ * `isResourceDeclaration`, `isLoopedResource`, `isResourceOf`,
+ * `isLoopedResourceOf`) — there are no class-static guards, so a subclass
+ * like `Secret` never inherits a misleading `Secret.isResource(...)`.
+ */
+/** Is `x` a scalar {@link Resource} (not a looped declaration)? */
+export function isResource(x) {
+    return (typeof x === "object" && x !== null && x[RESOURCE_BRAND] === true);
+}
+/**
+ * Is `x` a Bicep resource declaration — either a scalar {@link Resource} or
+ * a {@link LoopedResource}?
+ */
+export function isResourceDeclaration(x) {
+    return (typeof x === "object" &&
+        x !== null &&
+        x[RESOURCE_DECLARATION_BRAND] === true);
+}
+/** Is `x` a {@link LoopedResource} (`Ctor.fromLoop(...)`)? */
+export function isLoopedResource(x) {
+    return (typeof x === "object" &&
+        x !== null &&
+        x[LOOPED_RESOURCE_BRAND] === true);
+}
+/**
+ * Type guard: is `x` an instance of the resource class `ctor`?
+ * Narrows `x` to the class's instance type, so callers can access
+ * subclass-specific accessors (e.g. `kv.secrets`) inside the guarded
+ * block.
+ *
+ * Accepts any value (`unknown`), like the other brand guards. A
+ * `LoopedResource<T>` is not a `Resource`, so `instanceof ctor` returns
+ * `false` for it — the narrowing is safe. `instanceof` alone is sufficient
+ * (and stricter than a brand + ARM-type-string check: a base-`Resource`
+ * impostor carrying the same `type`/`apiVersion` is correctly rejected), so
+ * no `isResource` pre-check is needed.
+ *
+ * Matches scalar resource **declarations** (from a constructor / query /
+ * collection). It does NOT match a `parent.at(i)` element reference of a
+ * looped declaration: that proxy intentionally keeps `LoopedResource`'s
+ * prototype (no `getPrototypeOf` trap), so `instanceof` is `false` for it
+ * even though its ARM reads work. If we ever need cross-realm subclass
+ * matching (per-subclass `Symbol.for` brands, mirroring the base
+ * `RESOURCE_BRAND`), this is the one place to swap.
+ */
+export function isResourceOf(x, ctor) {
+    return x instanceof ctor;
+}
+/**
+ * Type guard: is `x` a {@link LoopedResource} whose wrapped resource class is
+ * `ctor` (i.e. a `LoopedResource<T>` produced by `T.fromLoop(...)`)? Narrows
+ * `x` to `LoopedResource<T>`, the looped analogue of {@link isResourceOf}.
+ *
+ * Matches on the declaration's `wrappedCtor` identity — the concrete subclass
+ * passed to `fromLoop` — so `isLoopedResourceOf(x, StorageAccount)`
+ * replaces the `x.wrappedCtor === StorageAccount` checks scattered across the
+ * query / collection layers.
+ */
+export function isLoopedResourceOf(x, ctor) {
+    return isLoopedResource(x) && x.wrappedCtor === ctor;
+}
+//# sourceMappingURL=resource-utils.js.map