typekro 0.4.0 → 0.7.0

package/dist/core/metadata/resource-metadata.js

@@ -0,0 +1,217 @@
+/**
+ * Resource Metadata Store
+ *
+ * Central WeakMap-based metadata store for resource objects. Replaces the
+ * non-enumerable `Object.defineProperty` pattern that was prone to silent
+ * data loss during spread, `JSON.parse(JSON.stringify())`, and `structuredClone`.
+ *
+ * WeakMap is invisible to serialization by design — no data can leak into
+ * YAML, JSON, or `Object.keys()` output. Metadata is automatically garbage
+ * collected when the resource object is no longer referenced.
+ *
+ * @module
+ * @see ROADMAP.md Phase 2.6
+ */
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+/**
+ * The single global WeakMap that holds all resource metadata.
+ *
+ * Using `WeakRef`-compatible keys means metadata is garbage-collected
+ * when the resource object is no longer reachable.
+ */
+const store = new WeakMap();
+// ---------------------------------------------------------------------------
+// Core accessors
+// ---------------------------------------------------------------------------
+/**
+ * Get the full metadata record for a resource, or `undefined` if none is set.
+ */
+export function getResourceMetadata(resource) {
+    return store.get(resource);
+}
+/**
+ * Get a single metadata field for a resource.
+ */
+export function getMetadataField(resource, key) {
+    return store.get(resource)?.[key];
+}
+/**
+ * Set (merge) metadata fields on a resource. Creates the metadata record if
+ * it doesn't exist yet; otherwise merges the new fields into the existing record.
+ *
+ * @returns The merged metadata record.
+ */
+export function setResourceMetadata(resource, metadata) {
+    const existing = store.get(resource) ?? {};
+    const merged = { ...existing, ...metadata };
+    store.set(resource, merged);
+    return merged;
+}
+/**
+ * Set a single metadata field on a resource.
+ */
+export function setMetadataField(resource, key, value) {
+    const existing = store.get(resource) ?? {};
+    existing[key] = value;
+    store.set(resource, existing);
+}
+/**
+ * Legacy non-enumerable property names that may still exist on objects
+ * during the migration period. These are checked and migrated to the
+ * WeakMap store when encountered.
+ */
+const LEGACY_NONENUM_PROPS = [
+    'readinessEvaluator',
+    '__resourceId',
+    'includeWhen',
+    'readyWhen',
+    'forEach',
+    '__templateOverrides',
+];
+/** Map legacy property names to their ResourceMetadata field names */
+const LEGACY_TO_METADATA = {
+    readinessEvaluator: 'readinessEvaluator',
+    __resourceId: 'resourceId',
+    includeWhen: 'includeWhen',
+    readyWhen: 'readyWhen',
+    forEach: 'forEach',
+    __templateOverrides: 'templateOverrides',
+};
+/**
+ * Copy ALL metadata from one resource to another. This replaces the old
+ * `preserveNonEnumerableProperties` helper for resource-to-resource copies
+ * (e.g., after a `{...spread}` operation).
+ *
+ * Also migrates any legacy non-enumerable properties found on the source
+ * into the WeakMap store on the target.
+ *
+ * @returns `true` if metadata was copied, `false` if source had no metadata
+ *          and no legacy properties were found.
+ */
+export function copyResourceMetadata(source, target) {
+    let copied = false;
+    // Copy existing WeakMap metadata
+    const metadata = store.get(source);
+    if (metadata) {
+        store.set(target, { ...metadata });
+        copied = true;
+    }
+    // Also migrate legacy non-enumerable properties from source to target's WeakMap
+    if (typeof source === 'object' && source !== null) {
+        for (const prop of LEGACY_NONENUM_PROPS) {
+            const desc = Object.getOwnPropertyDescriptor(source, prop);
+            if (desc && desc.value !== undefined) {
+                // Validate type before storing: readinessEvaluator must be a function
+                if (prop === 'readinessEvaluator' && typeof desc.value !== 'function')
+                    continue;
+                const metaKey = LEGACY_TO_METADATA[prop];
+                if (metaKey) {
+                    setMetadataField(target, metaKey, desc.value);
+                    copied = true;
+                }
+            }
+        }
+    }
+    return copied;
+}
+/**
+ * Check if a resource has any metadata at all.
+ */
+export function hasResourceMetadata(resource) {
+    return store.has(resource);
+}
+/**
+ * Delete all metadata for a resource. Rarely needed since WeakMap handles
+ * garbage collection automatically, but useful in tests.
+ */
+export function clearResourceMetadata(resource) {
+    return store.delete(resource);
+}
+// ---------------------------------------------------------------------------
+// Convenience: resourceId
+// ---------------------------------------------------------------------------
+/** Get the resource ID (previously `__resourceId`). */
+export function getResourceId(resource) {
+    // Check WeakMap store first
+    const fromStore = store.get(resource)?.resourceId;
+    if (fromStore)
+        return fromStore;
+    // Fallback: check for legacy `__resourceId` property on the object itself.
+    // This handles plain objects that haven't been migrated to WeakMap metadata,
+    // or objects created externally with `__resourceId` set as a property.
+    // IMPORTANT: Use Object.getOwnPropertyDescriptor to avoid triggering proxy get traps,
+    // which would cause infinite recursion when called from within a proxy get handler.
+    if (typeof resource === 'object' && resource !== null) {
+        const desc = Object.getOwnPropertyDescriptor(resource, '__resourceId');
+        if (desc && typeof desc.value === 'string')
+            return desc.value;
+    }
+    return undefined;
+}
+/** Set the resource ID (previously `__resourceId`). */
+export function setResourceId(resource, id) {
+    setMetadataField(resource, 'resourceId', id);
+}
+// ---------------------------------------------------------------------------
+// Convenience: readinessEvaluator
+// ---------------------------------------------------------------------------
+/** Get the readiness evaluator function. */
+export function getReadinessEvaluator(resource) {
+    // Check WeakMap store first
+    const fromStore = store.get(resource)?.readinessEvaluator;
+    if (fromStore)
+        return fromStore;
+    // Fallback: check for legacy `readinessEvaluator` property on the object itself.
+    // This handles plain objects with readinessEvaluator set via Object.defineProperty
+    // that haven't been migrated to WeakMap metadata.
+    // IMPORTANT: Use Object.getOwnPropertyDescriptor to avoid triggering proxy get traps,
+    // which would cause infinite recursion when called from within a proxy get handler.
+    if (typeof resource === 'object' && resource !== null) {
+        const desc = Object.getOwnPropertyDescriptor(resource, 'readinessEvaluator');
+        if (desc && typeof desc.value === 'function')
+            return desc.value;
+    }
+    return undefined;
+}
+/** Set the readiness evaluator function. */
+export function setReadinessEvaluator(resource, evaluator) {
+    setMetadataField(resource, 'readinessEvaluator', evaluator);
+}
+// ---------------------------------------------------------------------------
+// Convenience: conditional metadata
+// ---------------------------------------------------------------------------
+/** Get the includeWhen conditions. */
+export function getIncludeWhen(resource) {
+    return store.get(resource)?.includeWhen;
+}
+/** Set (replace) the includeWhen conditions. */
+export function setIncludeWhen(resource, conditions) {
+    setMetadataField(resource, 'includeWhen', conditions);
+}
+/** Get the readyWhen conditions. */
+export function getReadyWhen(resource) {
+    return store.get(resource)?.readyWhen;
+}
+/** Set (replace) the readyWhen conditions. */
+export function setReadyWhen(resource, conditions) {
+    setMetadataField(resource, 'readyWhen', conditions);
+}
+/** Get the forEach dimensions. */
+export function getForEach(resource) {
+    return store.get(resource)?.forEach;
+}
+/** Set (replace) the forEach dimensions. */
+export function setForEach(resource, dimensions) {
+    setMetadataField(resource, 'forEach', dimensions);
+}
+/** Get the template overrides. */
+export function getTemplateOverrides(resource) {
+    return store.get(resource)?.templateOverrides;
+}
+/** Set (replace) the template overrides. */
+export function setTemplateOverrides(resource, overrides) {
+    setMetadataField(resource, 'templateOverrides', overrides);
+}
+//# sourceMappingURL=resource-metadata.js.map

package/dist/core/metadata/resource-metadata.js.map

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

package/dist/core/proxy/create-resource.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Core Proxy Engine & createResource Factory
+ *
+ * This module implements the magic proxy system that enables TypeScript-native
+ * Kubernetes resource composition.  It is the **single source of truth** for:
+ *
+ * - `createRefFactory` — KubernetesRef proxy builder
+ * - `createPropertyProxy` — spec/status property proxy
+ * - `createGenericProxyResource` — top-level Enhanced proxy
+ * - `createResource` — the public factory function
+ *
+ * The module lives in `core/` because it is foundational infrastructure used
+ * by both `core/references/external-refs.ts` and every factory in
+ * `factories/`.  `factories/shared.ts` re-exports `createResource` for
+ * backward compatibility.
+ */
+import type { Enhanced, KubernetesResource } from '../types.js';
+/**
+ * Options for createResource function
+ */
+export interface CreateResourceOptions {
+    /**
+     * Kubernetes scope of the resource
+     * - 'namespaced': Resource must exist within a namespace
+     * - 'cluster': Resource is cluster-scoped and cannot have a namespace
+     */
+    scope?: 'namespaced' | 'cluster';
+}
+/**
+ * Create an Enhanced proxy resource from a plain Kubernetes resource definition.
+ *
+ * This is the foundational factory function used by all TypeKro factories.
+ * It wraps a resource in the magic proxy system that enables:
+ * - Automatic KubernetesRef generation for spec/status property access
+ * - Deterministic resource ID generation for Kro
+ * - Composition context registration
+ * - Readiness evaluator attachment
+ *
+ * @example
+ * ```typescript
+ * const deploy = createResource<V1DeploymentSpec, V1DeploymentStatus>({
+ *   apiVersion: 'apps/v1',
+ *   kind: 'Deployment',
+ *   metadata: { name: 'my-app' },
+ *   spec: { replicas: 3, ... },
+ * });
+ * ```
+ */
+export declare function createResource<TSpec extends object, TStatus extends object>(resource: KubernetesResource<TSpec, TStatus>, options?: CreateResourceOptions): Enhanced<TSpec, TStatus>;
+//# sourceMappingURL=create-resource.d.ts.map

package/dist/core/proxy/create-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-resource.d.ts","sourceRoot":"","sources":["../../../src/core/proxy/create-resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAkBH,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAkC,MAAM,aAAa,CAAC;AAiXhG;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,MAAM,EAAE,OAAO,SAAS,MAAM,EACzE,QAAQ,EAAE,kBAAkB,CAAC,KAAK,EAAE,OAAO,CAAC,EAC5C,OAAO,CAAC,EAAE,qBAAqB,GAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAgH1B"}