@xplane/core 0.9.2 → 0.10.0

package/dist/index.d.mts

@@ -0,0 +1,370 @@
+import { Construct, Construct as Construct$1 } from "constructs";
+
+//#region src/tracking/types.d.ts
+/**
+ * Symbols used to access tracking metadata on proxy-wrapped values.
+ * These are not enumerable and won't leak into serialized output.
+ */
+declare const TRACKING_META: unique symbol;
+declare const IS_TRACKED: unique symbol;
+/** Identifies which resource a tracked value belongs to. */
+interface ResourceRef {
+  readonly id: string;
+}
+/** A single dependency edge between two resource fields. */
+interface DependencyEdge {
+  /** Resource whose field is being read (the dependency). */
+  readonly from: ResourceRef;
+  /** Dot-separated path on the source resource. */
+  readonly fromPath: string;
+  /** Resource whose field is being set (the dependent). */
+  readonly to: ResourceRef;
+  /** Dot-separated path on the target resource. */
+  readonly toPath: string;
+}
+/** Metadata attached to every tracked proxy. */
+interface TrackingMeta {
+  /** The resource this value belongs to. */
+  readonly owner: ResourceRef;
+  /** The dot-separated path from root of the resource object. */
+  readonly path: string;
+  /** Whether this value originates from observed state (read-only). */
+  readonly observed: boolean;
+}
+//#endregion
+//#region src/tracking/dependency-graph.d.ts
+/**
+ * Directed acyclic graph of resource dependencies.
+ * Supports topological sorting to determine resource creation order
+ * and cycle detection to surface configuration errors.
+ */
+declare class DependencyGraph {
+  /** adjacency list: resource id → set of resource ids it depends on */
+  private readonly _deps;
+  /** all registered resource refs by id */
+  private readonly _resources;
+  /** raw edges for introspection */
+  private readonly _edges;
+  /** Register a resource node in the graph. */
+  addResource(ref: ResourceRef): void;
+  /** Add dependency edges from the collector. */
+  addEdges(edges: ReadonlyArray<DependencyEdge>): void;
+  /** Add an explicit dependency: `dependent` depends on `dependency`. */
+  addExplicitDependency(dependent: ResourceRef, dependency: ResourceRef): void;
+  /** Get all resource IDs that `resourceId` directly depends on. */
+  getDependencies(resourceId: string): ReadonlySet<string>;
+  /** Get all registered resource IDs. */
+  get resourceIds(): ReadonlyArray<string>;
+  /** Get all raw edges. */
+  get edges(): ReadonlyArray<DependencyEdge>;
+  /**
+   * Returns resource IDs in topological order (dependencies first).
+   * Throws if the graph contains cycles.
+   */
+  topologicalSort(): string[];
+}
+//#endregion
+//#region src/tracking/proxy.d.ts
+/**
+ * Registry that collects dependency edges discovered during proxy access.
+ * Shared across all tracked values within a single composition run.
+ */
+declare class DependencyCollector {
+  private readonly _edges;
+  addEdge(edge: DependencyEdge): void;
+  get edges(): ReadonlyArray<DependencyEdge>;
+  clear(): void;
+}
+/** Options for creating a tracked proxy. */
+interface TrackedProxyOptions {
+  /** Which resource this value belongs to. */
+  owner: ResourceRef;
+  /** Dot-path from the resource root (e.g. "spec.forProvider.region"). */
+  path: string;
+  /** Whether this originates from observed state. */
+  observed: boolean;
+  /** Shared collector for discovered dependencies. */
+  collector: DependencyCollector;
+}
+/**
+ * Returns true if `value` is a tracked proxy created by `createTrackedProxy`.
+ */
+declare function isTracked(value: unknown): value is object & {
+  [TRACKING_META]: TrackingMeta;
+};
+/**
+ * Retrieves the tracking metadata from a tracked proxy.
+ * Returns undefined if the value is not tracked.
+ */
+declare function getTrackingMeta(value: unknown): TrackingMeta | undefined;
+/**
+ * Creates a proxy around `target` that:
+ * 1. Returns nested proxies for property access (building up dot-paths).
+ * 2. On set: if the assigned value is itself a tracked proxy from a *different*
+ *    resource, records a DependencyEdge in the collector.
+ * 3. Stores concrete values normally so the underlying object is populated.
+ *
+ * For "observed" proxies, property reads on missing keys return a nested
+ * tracked proxy (representing an "unknown" value) rather than undefined.
+ * This lets `vpc.status.atProvider.vpcId` work even before the VPC exists.
+ */
+declare function createTrackedProxy<T extends object>(target: T, opts: TrackedProxyOptions): T;
+/**
+ * Sentinel value used when a tracked reference cannot be resolved yet
+ * (the source resource hasn't been observed).
+ */
+declare const UNRESOLVED: unique symbol;
+//#endregion
+//#region src/core/resource.d.ts
+/**
+ * Recursive type that allows arbitrary deep property access without undefined.
+ * Uses a known-key mapped type to bypass noUncheckedIndexedAccess.
+ * Used as the default for untyped Resource spec/status so that
+ * `resource.spec.forProvider.vpcId` compiles without casts.
+ */
+type AnyFields = Record<string, any>;
+/** Minimal Kubernetes resource shape. */
+interface KubernetesResource {
+  apiVersion: string;
+  kind: string;
+  metadata?: {
+    name?: string;
+    namespace?: string;
+    labels?: Record<string, string>;
+    annotations?: Record<string, string>;
+    [key: string]: unknown;
+  };
+  spec?: Record<string, unknown>;
+  status?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+/** Props for constructing a Resource. */
+interface ResourceProps {
+  apiVersion: string;
+  kind: string;
+  metadata?: {
+    name?: string;
+    namespace?: string;
+    labels?: Record<string, string>;
+    annotations?: Record<string, string>;
+    [key: string]: unknown;
+  };
+  spec?: Record<string, unknown>;
+  /** Top-level extra fields for resources that don't use spec (e.g. Secret's data/stringData/type). */
+  [key: string]: unknown;
+}
+/** Configuration options for a resource. */
+interface ResourceOptions {
+  /** Whether auto-ready detection is enabled for this resource. Default: true. */
+  autoReady?: boolean;
+}
+/**
+ * A Construct that represents a single Crossplane managed/composed resource.
+ *
+ * The `spec` and `status` properties are proxy-wrapped for automatic
+ * dependency tracking. Assigning a value from another resource's status
+ * to this resource's spec automatically records a dependency edge.
+ */
+declare class Resource<TSpec extends object = AnyFields, TStatus extends object = AnyFields> extends Construct$1 {
+  readonly apiVersion: string;
+  readonly kind: string;
+  readonly resourceRef: ResourceRef;
+  /** Proxy-wrapped desired spec — writes are tracked. */
+  readonly spec: TSpec;
+  /** Proxy-wrapped observed status — reads create dependency tracking. */
+  readonly status: TStatus;
+  /** Proxy-wrapped desired metadata. */
+  readonly metadata: NonNullable<KubernetesResource["metadata"]>;
+  /** Whether auto-ready is enabled for this resource. */
+  autoReady: boolean;
+  /** Extra top-level fields (e.g. data/stringData for Secret). Not proxy-tracked. */
+  private readonly _extra;
+  /** Observed state populated by the bridge before construction. */
+  private _observed;
+  /** Backing object for the status proxy — populated by setObserved(). */
+  private readonly _statusTarget;
+  /** Backing object for the metadata proxy — populated by setObserved(). */
+  private readonly _metaTarget;
+  /** Keys the user explicitly declared in constructor metadata props. */
+  private readonly _desiredMetaKeys;
+  /** Explicit dependency refs. */
+  private readonly _explicitDeps;
+  /** @internal */
+  private readonly _graph;
+  constructor(scope: Construct$1, id: string, props: ResourceProps, options?: ResourceOptions);
+  /** Fully qualified path in the construct tree. */
+  get path(): string;
+  /** Add an explicit dependency on another resource. */
+  addDependency(other: Resource): void;
+  /** Get explicit dependency refs. */
+  get explicitDependencies(): ReadonlyArray<ResourceRef>;
+  /** Set observed state (called by the bridge before compose). */
+  setObserved(observed: KubernetesResource): void;
+  /** Get observed state. */
+  get observed(): KubernetesResource | undefined;
+  /**
+   * Compute a unique name for a resource based on its construct node path,
+   * similar to `cdk.Names.uniqueResourceName`.
+   *
+   * The name is structured as:
+   *   `[namespace-]claimName-PathSegments[-extra]-hash8`
+   *
+   * - XR namespace (if present) and XR name are always prepended.
+   * - Path segments (construct tree, root skipped) are appended next.
+   * - An optional `extra` string is appended after the path.
+   * - An 8-char hash of the full untruncated string is always appended for uniqueness.
+   * - Whitespace in each segment is stripped (CDK convention).
+   * - Disallowed characters are replaced by the separator; consecutive separators are collapsed.
+   * - The result is truncated to `maxLength` while keeping the hash suffix.
+   *
+   * @param scope    - The construct whose node path is used.
+   * @param options  - Optional tuning.
+   */
+  static uniqueName(scope: Construct$1, options?: {
+    /** Maximum length of the resulting name. Default: 63. */maxLength?: number; /** Separator inserted between path segments (also replaces disallowed chars). Default: "-". */
+    separator?: string; /** Regex of characters to keep. Anything else is replaced by the separator. Default: /[^a-zA-Z0-9]/g */
+    allowedPattern?: RegExp; /** Extra string appended after the path segments and before the hash. */
+    extra?: string;
+  }): string;
+  /**
+   * Serialize to a plain Kubernetes resource object for the desired state.
+   * Strips proxy wrappers, UNRESOLVED sentinels, and server-managed metadata
+   * fields (uid, resourceVersion, etc.) that must not appear in desired state.
+   */
+  toDesired(): KubernetesResource;
+}
+//#endregion
+//#region src/core/composition.d.ts
+/**
+ * A Composition is the root Construct for a Crossplane composition function.
+ * Like CDK's `App` or cdk8s's `Chart`, it is the root of the construct tree.
+ * Resources and constructs are created in the constructor.
+ *
+ * Usage:
+ * ```ts
+ * class MyComposition extends Composition {
+ *   constructor() {
+ *     super();
+ *     const vpc = new aws.ec2.VPC(this, 'vpc', { ... });
+ *     const subnet = new aws.ec2.Subnet(this, 'subnet', {
+ *       spec: { forProvider: { vpcId: vpc.status.atProvider.vpcId } }
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare class Composition extends Construct$1 {
+  /**
+   * Pending XR data, set by the framework before instantiation.
+   * @internal
+   */
+  static _pendingXR: Record<string, unknown> | undefined;
+  /**
+   * Pending environment data, set by the framework before instantiation.
+   * Populated from the Crossplane context key `apiextensions.crossplane.io/environment`.
+   * @internal
+   */
+  static _pendingEnvironment: Record<string, unknown> | undefined;
+  /** The composite resource (XR) — proxy-wrapped for tracking. */
+  readonly xr: AnyFields;
+  /** Environment data from function-environment-configs or other pipeline steps. */
+  readonly environment: AnyFields;
+  /** Raw name from the XR metadata (not proxy-tracked). */
+  readonly xrName: string | undefined;
+  /** Raw namespace from the XR metadata (not proxy-tracked). */
+  readonly xrNamespace: string | undefined;
+  /** Dependency collector shared across all resources. */
+  readonly collector: DependencyCollector;
+  /** Dependency graph built during compose(). */
+  readonly graph: DependencyGraph;
+  /** Registered status output function. @internal */
+  private _statusFn?;
+  constructor();
+  /**
+   * Register a function that computes the desired XR status output.
+   *
+   * The function is called by the framework **after** observed state has been
+   * fed into all resources, so `resource.observed` contains real data.
+   *
+   * @example
+   * ```ts
+   * this.setStatusOutput(() => ({
+   *   config: {
+   *     projectHostedZoneId: hostedZone.observed?.status?.atProvider?.id,
+   *   },
+   * }));
+   * ```
+   */
+  setStatusOutput(fn: () => Record<string, unknown>): void;
+  /**
+   * Compute and return the desired status output.
+   * Returns an empty object if no status function was registered.
+   * @internal
+   */
+  computeStatusOutput(): Record<string, unknown>;
+  /**
+   * Walk up the construct tree and return the root Composition.
+   * Throws if the scope is not within a Composition.
+   */
+  static of(scope: Construct$1): Composition;
+  /** Get all registered resources keyed by construct path. */
+  get resources(): ReadonlyMap<string, Resource>;
+}
+//#endregion
+//#region src/ready/auto-ready.d.ts
+/** Condition from a Kubernetes resource's status.conditions array. */
+interface StatusCondition {
+  type: string;
+  status: string;
+  reason?: string;
+  message?: string;
+}
+/**
+ * Determines if a Crossplane managed resource is ready based on its
+ * observed status conditions.
+ *
+ * - If the resource has a `Ready: True` condition → ready.
+ * - If the resource has a `Ready: False` condition → not ready.
+ * - If the resource exists but has no `Ready` condition at all (e.g. Namespace,
+ *   ProviderConfig) → considered ready (the resource exists and is functional).
+ * - If not yet observed → not ready.
+ */
+declare function isResourceReady(observed: KubernetesResource | undefined): boolean;
+/**
+ * Gets the Ready condition from a resource, if present.
+ */
+declare function getReadyCondition(observed: KubernetesResource | undefined): StatusCondition | undefined;
+//#endregion
+//#region src/sequencing/resolver.d.ts
+/** Result of dependency resolution for a single resource. */
+interface ResolutionResult {
+  /** The resource. */
+  resource: Resource;
+  /** Whether all dependencies are satisfied and the resource can be emitted. */
+  ready: boolean;
+  /** Paths that are still unresolved (waiting on upstream). */
+  unresolvedPaths: string[];
+}
+/** Result of resolving all resources in a composition. */
+interface SequencingResult {
+  /** Resources in dependency order that are ready to emit. */
+  emit: Resource[];
+  /** Resources blocked on unresolved dependencies. */
+  blocked: Resource[];
+  /** Topologically sorted resource IDs. */
+  order: string[];
+}
+/**
+ * Resolves resource dependencies and determines which resources can be
+ * emitted in the current pass.
+ *
+ * Algorithm:
+ * 1. Topologically sort resources using the dependency graph.
+ * 2. For each resource (in order), check if upstream dependencies have
+ *    resolved values in observed state.
+ * 3. If all deps resolved → emit. If any dep unresolved → block.
+ */
+declare function resolveSequencing(resources: ReadonlyMap<string, Resource>, graph: DependencyGraph, observedResources: ReadonlyMap<string, KubernetesResource>): SequencingResult;
+//#endregion
+export { type AnyFields, Composition, Construct, DependencyCollector, type DependencyEdge, DependencyGraph, IS_TRACKED, type KubernetesResource, type ResolutionResult, Resource, type ResourceOptions, type ResourceProps, type ResourceRef, type SequencingResult, TRACKING_META, type TrackingMeta, UNRESOLVED, createTrackedProxy, getReadyCondition, getTrackingMeta, isResourceReady, isTracked, resolveSequencing };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/tracking/types.ts","../src/tracking/dependency-graph.ts","../src/tracking/proxy.ts","../src/core/resource.ts","../src/core/composition.ts","../src/ready/auto-ready.ts","../src/sequencing/resolver.ts"],"mappings":"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"}