@xplane/core 0.9.2 → 0.11.0

package/dist/index.js

@@ -1,682 +0,0 @@
-// src/core/index.ts
-import { Construct as Construct3 } from "constructs";
-
-// src/core/composition.ts
-import { Construct } from "constructs";
-
-// src/tracking/dependency-graph.ts
-var DependencyGraph = class {
-  /** adjacency list: resource id → set of resource ids it depends on */
-  _deps = /* @__PURE__ */ new Map();
-  /** all registered resource refs by id */
-  _resources = /* @__PURE__ */ new Map();
-  /** raw edges for introspection */
-  _edges = [];
-  /** Register a resource node in the graph. */
-  addResource(ref) {
-    this._resources.set(ref.id, ref);
-    if (!this._deps.has(ref.id)) {
-      this._deps.set(ref.id, /* @__PURE__ */ new Set());
-    }
-  }
-  /** Add dependency edges from the collector. */
-  addEdges(edges) {
-    for (const edge of edges) {
-      this.addResource(edge.from);
-      this.addResource(edge.to);
-      const deps = this._deps.get(edge.to.id);
-      if (deps) {
-        deps.add(edge.from.id);
-      }
-      this._edges.push(edge);
-    }
-  }
-  /** Add an explicit dependency: `dependent` depends on `dependency`. */
-  addExplicitDependency(dependent, dependency) {
-    this.addResource(dependent);
-    this.addResource(dependency);
-    const deps = this._deps.get(dependent.id);
-    if (deps) {
-      deps.add(dependency.id);
-    }
-  }
-  /** Get all resource IDs that `resourceId` directly depends on. */
-  getDependencies(resourceId) {
-    return this._deps.get(resourceId) ?? /* @__PURE__ */ new Set();
-  }
-  /** Get all registered resource IDs. */
-  get resourceIds() {
-    return [...this._resources.keys()];
-  }
-  /** Get all raw edges. */
-  get edges() {
-    return this._edges;
-  }
-  /**
-   * Returns resource IDs in topological order (dependencies first).
-   * Throws if the graph contains cycles.
-   */
-  topologicalSort() {
-    const visited = /* @__PURE__ */ new Set();
-    const visiting = /* @__PURE__ */ new Set();
-    const sorted = [];
-    const visit = (id) => {
-      if (visited.has(id)) return;
-      if (visiting.has(id)) {
-        const cycle = [...visiting, id].join(" \u2192 ");
-        throw new Error(`Dependency cycle detected: ${cycle}`);
-      }
-      visiting.add(id);
-      const deps = this._deps.get(id);
-      if (deps) {
-        for (const depId of deps) {
-          visit(depId);
-        }
-      }
-      visiting.delete(id);
-      visited.add(id);
-      sorted.push(id);
-    };
-    for (const id of this._resources.keys()) {
-      visit(id);
-    }
-    return sorted;
-  }
-};
-
-// src/tracking/types.ts
-var TRACKING_META = /* @__PURE__ */ Symbol.for("xplane.tracking.meta");
-var IS_TRACKED = /* @__PURE__ */ Symbol.for("xplane.tracking.isTracked");
-
-// src/tracking/proxy.ts
-var DependencyCollector = class {
-  _edges = [];
-  addEdge(edge) {
-    const exists = this._edges.some(
-      (e) => e.from.id === edge.from.id && e.fromPath === edge.fromPath && e.to.id === edge.to.id && e.toPath === edge.toPath
-    );
-    if (!exists) {
-      this._edges.push(edge);
-    }
-  }
-  get edges() {
-    return this._edges;
-  }
-  clear() {
-    this._edges.length = 0;
-  }
-};
-function isTracked(value) {
-  return typeof value === "object" && value !== null && value[IS_TRACKED] === true;
-}
-function getTrackingMeta(value) {
-  if (isTracked(value)) {
-    return value[TRACKING_META];
-  }
-  return void 0;
-}
-function createTrackedProxy(target, opts) {
-  const meta = {
-    owner: opts.owner,
-    path: opts.path,
-    observed: opts.observed
-  };
-  return new Proxy(target, {
-    get(obj, prop, receiver) {
-      if (prop === TRACKING_META) return meta;
-      if (prop === IS_TRACKED) return true;
-      if (prop === Symbol.toPrimitive) {
-        if (opts.observed && Object.keys(obj).length === 0) {
-          return () => {
-            throw new Error(
-              `Cannot coerce XR path '${opts.path}' to a primitive \u2014 the field does not exist in the composite resource`
-            );
-          };
-        }
-        return Reflect.get(obj, prop, receiver);
-      }
-      if (typeof prop === "symbol") {
-        return Reflect.get(obj, prop, receiver);
-      }
-      if (prop === "toJSON") {
-        return () => obj;
-      }
-      const existing = Reflect.get(obj, prop, receiver);
-      if (isTracked(existing)) {
-        return existing;
-      }
-      if (typeof existing === "object" && existing !== null) {
-        const wrapped2 = createTrackedProxy(existing, {
-          owner: opts.owner,
-          path: opts.path ? `${opts.path}.${prop}` : String(prop),
-          observed: opts.observed,
-          collector: opts.collector
-        });
-        Reflect.set(obj, prop, wrapped2);
-        return wrapped2;
-      }
-      if (existing !== void 0 || prop in obj) {
-        return existing;
-      }
-      if (opts.observed) {
-        const placeholder = {};
-        const wrapped2 = createTrackedProxy(placeholder, {
-          owner: opts.owner,
-          path: opts.path ? `${opts.path}.${prop}` : String(prop),
-          observed: true,
-          collector: opts.collector
-        });
-        return wrapped2;
-      }
-      const autoCreated = {};
-      const wrapped = createTrackedProxy(autoCreated, {
-        owner: opts.owner,
-        path: opts.path ? `${opts.path}.${prop}` : String(prop),
-        observed: false,
-        collector: opts.collector
-      });
-      Reflect.set(obj, prop, wrapped);
-      return wrapped;
-    },
-    set(obj, prop, value) {
-      if (typeof prop === "symbol") {
-        return Reflect.set(obj, prop, value);
-      }
-      const targetPath = opts.path ? `${opts.path}.${prop}` : String(prop);
-      if (isTracked(value)) {
-        const sourceMeta = getTrackingMeta(value);
-        if (sourceMeta && sourceMeta.owner.id === "__xr__") {
-          const concrete2 = resolveTrackedValue(value);
-          return Reflect.set(obj, prop, concrete2 === UNRESOLVED ? void 0 : concrete2);
-        }
-        if (sourceMeta && sourceMeta.owner.id !== opts.owner.id) {
-          opts.collector.addEdge({
-            from: sourceMeta.owner,
-            fromPath: sourceMeta.path,
-            to: opts.owner,
-            toPath: targetPath
-          });
-        }
-        const concrete = resolveTrackedValue(value);
-        return Reflect.set(obj, prop, concrete);
-      }
-      if (typeof value === "object" && value !== null && !isTracked(value)) {
-        const wrapped = createTrackedProxy(value, {
-          owner: opts.owner,
-          path: targetPath,
-          observed: opts.observed,
-          collector: opts.collector
-        });
-        return Reflect.set(obj, prop, wrapped);
-      }
-      return Reflect.set(obj, prop, value);
-    },
-    ownKeys(obj) {
-      return Reflect.ownKeys(obj).filter((k) => typeof k === "string");
-    },
-    getOwnPropertyDescriptor(obj, prop) {
-      const desc = Reflect.getOwnPropertyDescriptor(obj, prop);
-      if (desc) return { ...desc, configurable: true, enumerable: true };
-      if (opts.observed && typeof prop === "string") {
-        return { configurable: true, enumerable: true, writable: true, value: void 0 };
-      }
-      return void 0;
-    },
-    has(obj, prop) {
-      if (prop === IS_TRACKED || prop === TRACKING_META) return true;
-      return Reflect.has(obj, prop);
-    }
-  });
-}
-var UNRESOLVED = /* @__PURE__ */ Symbol.for("xplane.unresolved");
-function resolveTrackedValue(tracked) {
-  if (!isTracked(tracked)) return tracked;
-  const obj = unwrapProxy(tracked);
-  const keys = Object.keys(obj);
-  const meta = getTrackingMeta(tracked);
-  if (keys.length === 0 && meta?.observed) {
-    return UNRESOLVED;
-  }
-  return obj;
-}
-function unwrapProxy(tracked) {
-  const result = {};
-  for (const key of Object.keys(tracked)) {
-    result[key] = tracked[key];
-  }
-  return result;
-}
-
-// src/core/construct.ts
-var CONTEXT_COLLECTOR = "xplane:collector";
-var CONTEXT_GRAPH = "xplane:graph";
-var CONTEXT_XR_META = "xplane:xr-meta";
-
-// src/core/composition.ts
-var Composition = class _Composition extends Construct {
-  /**
-   * Pending XR data, set by the framework before instantiation.
-   * @internal
-   */
-  static _pendingXR;
-  /**
-   * Pending environment data, set by the framework before instantiation.
-   * Populated from the Crossplane context key `apiextensions.crossplane.io/environment`.
-   * @internal
-   */
-  static _pendingEnvironment;
-  /** The composite resource (XR) — proxy-wrapped for tracking. */
-  xr;
-  /** Environment data from function-environment-configs or other pipeline steps. */
-  environment;
-  /** Raw name from the XR metadata (not proxy-tracked). */
-  xrName;
-  /** Raw namespace from the XR metadata (not proxy-tracked). */
-  xrNamespace;
-  /** Dependency collector shared across all resources. */
-  collector;
-  /** Dependency graph built during compose(). */
-  graph;
-  /** Registered status output function. @internal */
-  _statusFn;
-  constructor() {
-    super(void 0, "");
-    this.collector = new DependencyCollector();
-    this.graph = new DependencyGraph();
-    this.node.setContext(CONTEXT_COLLECTOR, this.collector);
-    this.node.setContext(CONTEXT_GRAPH, this.graph);
-    const xrData = _Composition._pendingXR ?? {};
-    _Composition._pendingXR = void 0;
-    const envData = _Composition._pendingEnvironment ?? {};
-    _Composition._pendingEnvironment = void 0;
-    const xrMeta = xrData.metadata ?? {};
-    this.xrName = typeof xrMeta.name === "string" ? xrMeta.name : void 0;
-    this.xrNamespace = typeof xrMeta.namespace === "string" ? xrMeta.namespace : void 0;
-    this.node.setContext(CONTEXT_XR_META, { name: this.xrName, namespace: this.xrNamespace });
-    this.xr = createTrackedProxy(xrData, {
-      owner: { id: "__xr__" },
-      path: "",
-      observed: true,
-      collector: this.collector
-    });
-    this.environment = envData;
-  }
-  /**
-   * 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) {
-    this._statusFn = fn;
-  }
-  /**
-   * Compute and return the desired status output.
-   * Returns an empty object if no status function was registered.
-   * @internal
-   */
-  computeStatusOutput() {
-    return this._statusFn?.() ?? {};
-  }
-  /**
-   * Walk up the construct tree and return the root Composition.
-   * Throws if the scope is not within a Composition.
-   */
-  static of(scope) {
-    let current = scope;
-    while (current !== void 0) {
-      if (current instanceof _Composition) return current;
-      current = current.node.scope;
-    }
-    throw new Error(
-      "No Composition found in the scope chain. Ensure constructs are created within a Composition."
-    );
-  }
-  /** Get all registered resources keyed by construct path. */
-  get resources() {
-    const map = /* @__PURE__ */ new Map();
-    for (const construct of this.node.findAll()) {
-      if (isResource(construct)) {
-        map.set(construct.node.path, construct);
-      }
-    }
-    return map;
-  }
-};
-function isResource(construct) {
-  return construct !== null && typeof construct === "object" && "apiVersion" in construct && "kind" in construct && "resourceRef" in construct;
-}
-
-// src/core/resource.ts
-import { Construct as Construct2 } from "constructs";
-var Resource = class extends Construct2 {
-  apiVersion;
-  kind;
-  resourceRef;
-  /** Proxy-wrapped desired spec — writes are tracked. */
-  spec;
-  /** Proxy-wrapped observed status — reads create dependency tracking. */
-  status;
-  /** Proxy-wrapped desired metadata. */
-  metadata;
-  /** Whether auto-ready is enabled for this resource. */
-  autoReady;
-  /** Extra top-level fields (e.g. data/stringData for Secret). Not proxy-tracked. */
-  _extra;
-  /** Observed state populated by the bridge before construction. */
-  _observed;
-  /** Backing object for the status proxy — populated by setObserved(). */
-  _statusTarget;
-  /** Backing object for the metadata proxy — populated by setObserved(). */
-  _metaTarget;
-  /** Keys the user explicitly declared in constructor metadata props. */
-  _desiredMetaKeys;
-  /** Explicit dependency refs. */
-  _explicitDeps = [];
-  /** @internal */
-  _graph;
-  constructor(scope, id, props, options) {
-    super(scope, id);
-    this.apiVersion = props.apiVersion;
-    this.kind = props.kind;
-    this.autoReady = options?.autoReady ?? true;
-    const collector = this.node.tryGetContext(CONTEXT_COLLECTOR);
-    const graph = this.node.tryGetContext(CONTEXT_GRAPH);
-    if (!collector || !graph) {
-      throw new Error("Resource must be created within a Composition tree");
-    }
-    this.resourceRef = { id: this.node.path };
-    graph.addResource(this.resourceRef);
-    const KNOWN_KEYS = /* @__PURE__ */ new Set(["apiVersion", "kind", "metadata", "spec"]);
-    this._extra = {};
-    for (const [k, v] of Object.entries(props)) {
-      if (!KNOWN_KEYS.has(k)) this._extra[k] = v;
-    }
-    const specTarget = props.spec ?? {};
-    resolveTrackedRefs(specTarget, this.resourceRef, "spec", collector);
-    this.spec = createTrackedProxy(specTarget, {
-      owner: this.resourceRef,
-      path: "spec",
-      observed: false,
-      collector
-    });
-    this._metaTarget = props.metadata ?? {};
-    this._desiredMetaKeys = new Set(Object.keys(this._metaTarget));
-    this.metadata = createTrackedProxy(this._metaTarget, {
-      owner: this.resourceRef,
-      path: "metadata",
-      observed: true,
-      collector
-    });
-    this._statusTarget = {};
-    this.status = createTrackedProxy(this._statusTarget, {
-      owner: this.resourceRef,
-      path: "status",
-      observed: true,
-      collector
-    });
-    this._graph = graph;
-  }
-  /** Fully qualified path in the construct tree. */
-  get path() {
-    return this.node.path;
-  }
-  /** Add an explicit dependency on another resource. */
-  addDependency(other) {
-    this._explicitDeps.push(other.resourceRef);
-    this._graph.addExplicitDependency(this.resourceRef, other.resourceRef);
-  }
-  /** Get explicit dependency refs. */
-  get explicitDependencies() {
-    return this._explicitDeps;
-  }
-  /** Set observed state (called by the bridge before compose). */
-  setObserved(observed) {
-    this._observed = observed;
-    for (const key of Object.keys(this._metaTarget)) {
-      this._desiredMetaKeys.add(key);
-    }
-    if (observed.metadata && typeof observed.metadata === "object") {
-      Object.assign(this._metaTarget, observed.metadata);
-    }
-    if (observed.status && typeof observed.status === "object") {
-      Object.assign(this._statusTarget, observed.status);
-    }
-  }
-  /** Get observed state. */
-  get observed() {
-    return this._observed;
-  }
-  /**
-   * 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, options = {}) {
-    const maxLength = options.maxLength ?? 63;
-    const separator = options.separator ?? "-";
-    const allowedPattern = options.allowedPattern ?? /[^a-zA-Z0-9]/g;
-    const escapedSep = separator.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const collapseRe = new RegExp(`${escapedSep}+`, "g");
-    const clean = (s) => s.replace(/\s+/g, "").replace(allowedPattern, separator).replace(collapseRe, separator).replace(new RegExp(`^${escapedSep}|${escapedSep}$`, "g"), "");
-    const xrMeta = scope.node.tryGetContext(CONTEXT_XR_META);
-    const xrName = xrMeta?.name;
-    const xrNamespace = xrMeta?.namespace;
-    const parts = [];
-    if (xrNamespace) parts.push(clean(xrNamespace));
-    if (xrName) parts.push(clean(xrName));
-    for (const s of scope.node.scopes.slice(1)) {
-      const c = clean(s.node.id);
-      if (c) parts.push(c);
-    }
-    if (options.extra) {
-      const c = clean(options.extra);
-      if (c) parts.push(c);
-    }
-    const full = parts.join(separator);
-    const hash = shortHash(full);
-    const withHash = `${full}${separator}${hash}`;
-    if (withHash.length <= maxLength) return withHash;
-    const prefix = full.slice(0, maxLength - hash.length - separator.length);
-    return `${prefix}${separator}${hash}`;
-  }
-  /**
-   * 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() {
-    const fullMeta = JSON.parse(JSON.stringify(this.metadata));
-    const desiredMeta = {};
-    for (const key of this._desiredMetaKeys) {
-      if (key in fullMeta) {
-        desiredMeta[key] = fullMeta[key];
-      }
-    }
-    const cleanMeta = stripUnresolved(desiredMeta);
-    const desired = {
-      // Spread extra top-level fields first so spec/metadata take precedence
-      ...this._extra,
-      apiVersion: this.apiVersion,
-      kind: this.kind,
-      metadata: cleanMeta,
-      spec: stripUnresolved(JSON.parse(JSON.stringify(this.spec)))
-    };
-    if (desired.spec && typeof desired.spec === "object" && Object.keys(desired.spec).length === 0) {
-      delete desired.spec;
-    }
-    return desired;
-  }
-};
-function shortHash(s) {
-  let h = 5381;
-  for (let i = 0; i < s.length; i++) {
-    h = (h << 5) + h ^ s.charCodeAt(i);
-    h = h >>> 0;
-  }
-  return h.toString(16).padStart(8, "0");
-}
-function stripUnresolved(obj) {
-  if (obj === null || obj === void 0) return obj;
-  if (typeof obj === "symbol" && obj === UNRESOLVED) return void 0;
-  if (Array.isArray(obj)) {
-    return obj.map(stripUnresolved);
-  }
-  if (typeof obj === "object") {
-    const result = {};
-    for (const [key, value] of Object.entries(obj)) {
-      const cleaned = stripUnresolved(value);
-      if (cleaned !== void 0) {
-        result[key] = cleaned;
-      }
-    }
-    return result;
-  }
-  return obj;
-}
-function resolveTrackedRefs(obj, owner, basePath, collector) {
-  for (const [key, value] of Object.entries(obj)) {
-    const path = basePath ? `${basePath}.${key}` : key;
-    if (isTracked(value)) {
-      const sourceMeta = getTrackingMeta(value);
-      if (sourceMeta && sourceMeta.owner.id !== owner.id) {
-        collector.addEdge({
-          from: sourceMeta.owner,
-          fromPath: sourceMeta.path,
-          to: owner,
-          toPath: path
-        });
-        obj[key] = UNRESOLVED;
-      }
-      continue;
-    }
-    if (Array.isArray(value)) {
-      for (let i = 0; i < value.length; i++) {
-        const item = value[i];
-        if (isTracked(item)) {
-          const sourceMeta = getTrackingMeta(item);
-          if (sourceMeta && sourceMeta.owner.id !== owner.id) {
-            collector.addEdge({
-              from: sourceMeta.owner,
-              fromPath: sourceMeta.path,
-              to: owner,
-              toPath: `${path}[${i}]`
-            });
-            value[i] = UNRESOLVED;
-          }
-        } else if (typeof item === "object" && item !== null) {
-          resolveTrackedRefs(item, owner, `${path}[${i}]`, collector);
-        }
-      }
-      continue;
-    }
-    if (typeof value === "object" && value !== null) {
-      resolveTrackedRefs(value, owner, path, collector);
-    }
-  }
-}
-
-// src/ready/auto-ready.ts
-function isResourceReady(observed) {
-  if (!observed) return false;
-  const conditions = observed.status?.conditions;
-  if (!Array.isArray(conditions) || conditions.length === 0) return true;
-  const readyCondition = conditions.find((c) => c.type === "Ready");
-  if (!readyCondition) return true;
-  return readyCondition.status === "True";
-}
-function getReadyCondition(observed) {
-  if (!observed?.status) return void 0;
-  const conditions = observed.status.conditions;
-  if (!Array.isArray(conditions)) return void 0;
-  return conditions.find((c) => c.type === "Ready");
-}
-
-// src/sequencing/resolver.ts
-function resolveSequencing(resources, graph, observedResources) {
-  const order = graph.topologicalSort();
-  const emit = [];
-  const blocked = [];
-  for (const resourceId of order) {
-    const resource = findResourceByRef(resources, resourceId);
-    if (!resource) continue;
-    const deps = graph.getDependencies(resourceId);
-    let allDepsReady = true;
-    for (const depId of deps) {
-      const depResource = findResourceByRef(resources, depId);
-      if (!depResource) {
-        allDepsReady = false;
-        continue;
-      }
-      const observed = observedResources.get(depResource.path);
-      if (!observed) {
-        allDepsReady = false;
-      }
-    }
-    if (allDepsReady && hasUnresolvedFields(resource)) {
-      allDepsReady = false;
-    }
-    if (allDepsReady) {
-      emit.push(resource);
-    } else {
-      blocked.push(resource);
-    }
-  }
-  return { emit, blocked, order };
-}
-function hasUnresolvedFields(resource) {
-  return containsUnresolved(resource.spec) || containsUnresolved(resource.metadata);
-}
-function containsUnresolved(obj) {
-  if (obj === UNRESOLVED) return true;
-  if (obj === null || obj === void 0) return false;
-  if (Array.isArray(obj)) {
-    return obj.some(containsUnresolved);
-  }
-  if (typeof obj === "object") {
-    return Object.values(obj).some(containsUnresolved);
-  }
-  return false;
-}
-function findResourceByRef(resources, refId) {
-  return resources.get(refId);
-}
-export {
-  Composition,
-  Construct3 as Construct,
-  DependencyCollector,
-  DependencyGraph,
-  IS_TRACKED,
-  Resource,
-  TRACKING_META,
-  UNRESOLVED,
-  createTrackedProxy,
-  getReadyCondition,
-  getTrackingMeta,
-  isResourceReady,
-  isTracked,
-  resolveSequencing
-};
-//# sourceMappingURL=index.js.map