@k8ts/instruments 0.9.3 → 0.11.0

package/src/core/graph/resource/ref-key/ref-key.ts

@@ -1,13 +1,26 @@
-import type { Ref2_Of } from ".."
 import { InstrumentsError } from "../../../../error"
-import type { Kind } from "../api-kind"
-import { External_Base, type External_Props, type External_WithFeatures } from "../external"
-
+import type { Ident_Kind } from "../api-kind"
+import type { External } from "../external"
+import { type External_Props } from "../external"
+import type { Rsc_Ref } from "../reference"
+/** Input type for reference keys. Accepts either a RefKey instance or its string representation. */
 export type RefKey_Input = RefKey | RefKey["string"]
+
+/**
+ * String format template for reference keys.
+ *
+ * @template Kind - The Kubernetes resource kind
+ * @template Name - The resource name
+ */
 export type RefKey_sFormat<Kind extends string, Name extends string> = `${Kind}/${Name}`
+
 const separator = "/"
+
+/** Parsed representation of a reference key string. */
 export interface RefKey_Parsed {
+    /** The Kubernetes resource kind */
     kind: string
+    /** The resource name */
     name: string
 }
 
@@ -19,6 +32,13 @@ export function parse(ref: string) {
     return result
 }
 
+/**
+ * Attempts to parse a reference key string into its kind and name components. Returns undefined if
+ * the string cannot be parsed.
+ *
+ * @param ref - The reference key string to parse (format: "Kind/Name")
+ * @returns The parsed reference key, or undefined if parsing fails
+ */
 export function tryParse(ref: string): RefKey_Parsed | undefined {
     if (typeof ref !== "string") {
         return undefined
@@ -39,16 +59,40 @@ export function tryParse(ref: string): RefKey_Parsed | undefined {
     }
 }
 
-type nsKind = Kind<"", "v1", "Namespace">
+type nsKind = Ident_Kind<"", "v1", "Namespace">
 
+/**
+ * Options for creating a RefKey instance.
+ *
+ * @template Name - The resource name type
+ */
 export interface RefKey_Options<Name extends string = string> {
+    /** The resource name */
     name: Name
-    namespace?: RefKey<nsKind> | string | Ref2_Of<nsKind>
+    /** Optional namespace for namespaced resources. Can be a RefKey, string, or Ref2 */
+    namespace?: RefKey<nsKind> | string | Rsc_Ref<nsKind>
 }
 
-export class RefKey<K extends Kind.IdentParent = Kind.IdentParent, Name extends string = string> {
+/**
+ * A unique identifier for a k8s resource consisting of a Kind, name, and namespace. Used by
+ * resources to reference other resources. Serves as the basis for the {@link External} resource
+ * type.
+ *
+ * Important: This class is ambiguous because it can represent keys for namespaced resources but
+ * ignore the namespace. Needs some kind of refactor.
+ */
+export class RefKey<K extends Ident_Kind = Ident_Kind, Name extends string = string> {
+    /** The resource name */
     readonly name: string
+    /** The optional namespace for namespaced resources */
     readonly namespace: string | undefined
+
+    /**
+     * Creates a new RefKey instance.
+     *
+     * @param kind - The Kubernetes resource kind
+     * @param options - Configuration options including name and optional namespace
+     */
     constructor(
         readonly kind: K,
         options: RefKey_Options<Name>
@@ -58,12 +102,22 @@ export class RefKey<K extends Kind.IdentParent = Kind.IdentParent, Name extends
             typeof options.namespace === "string" ? options.namespace : options.namespace?.name
     }
 
+    /**
+     * Returns the string representation of this reference key. Format: "Kind/Namespace/Name" or
+     * "Kind/Name" for cluster-scoped resources.
+     */
     get string(): RefKey_sFormat<K["name"], Name> {
         return [this.kind.name, this.namespace, this.name]
             .filter(x => !!x)
             .join(separator) as RefKey_sFormat<K["name"], Name>
     }
 
+    /**
+     * Checks if this RefKey is equal to another RefKey by comparing kind, name, and namespace.
+     *
+     * @param other - The RefKey to compare with
+     * @returns True if both RefKeys have the same kind, name, and namespace
+     */
     equals(other: RefKey): boolean {
         if (other == null) {
             return false
@@ -78,13 +132,25 @@ export class RefKey<K extends Kind.IdentParent = Kind.IdentParent, Name extends
         )
     }
 
+    /**
+     * Returns the string representation of this reference key.
+     *
+     * @returns The reference key in string format
+     */
     toString() {
         return this.string
     }
 
-    External<const P extends External_Props<K> = External_Props<K>>(
-        options?: P
-    ): External_WithFeatures<K, P> {
-        return new External_Base(this, options ?? {}) as any
+    /**
+     * Creates an External reference to this resource.
+     *
+     * @template P - The external properties type
+     * @param options - Optional external properties configuration
+     * @returns An External instance with the specified features
+     */
+    External(options?: External_Props<K>): External<K> {
+        const External = require("../external").External
+
+        return new External(this, options ?? {}) as any
     }
 }

package/src/core/graph/resource/reference/fw-ref-exports.ts

@@ -1,27 +1,59 @@
 import { seq } from "doddle"
-import type { Ref2_Of } from "."
-import { FwReference } from "."
-import type { Origin_Exporter } from "../../origin"
+import { Origin_Entity } from "../../origin"
+import type { Origin_Exporter } from "../../origin/exporter"
+import { RefKey } from "../ref-key"
 import { ProxyOperationError } from "./error"
+import { FwRef } from "./fw-ref"
+import type { Rsc_Ref } from "./refable"
 
-export type FwRef_Exports_ByKey<Exports extends Ref2_Of = Ref2_Of> = {
-    [E in Exports as `${E["kind"]["name"]}/${E["name"]}`]: FwReference<E>
+/** Expands the resources exported by an Origin_Exported into a dictionary of name to FwRef. */
+export type FwRef_Exports_ByKey<Exports extends Rsc_Ref = Rsc_Ref> = {
+    [E in Exports as `${E["kind"]["name"]}/${E["name"]}`]: FwRef<E>
 }
-
-export type FwRef_Exports<Exported extends Ref2_Of = Ref2_Of> = FxRef_Exports_Proxied &
+/**
+ * A type describing all resources exported by an {@link Origin_Exporter} as forward references.
+ *
+ * FwRefs can be accessed using a key lookup, using the shorthand of `KindName/name`. For example, a
+ * Deployment named "my-app" can be accessed via `exports["Deployment/my-app"]`.
+ *
+ * This construct is immutable; attempts to modify it will will throw errors.
+ *
+ * The underlying entity can be accessed via the `__entity__()` method.
+ *
+ * During TypeScript compilation, this serves as a type-safe way to reference resources between
+ * entities. During runtime, it provides a dynamic proxy that resolves forward references to the
+ * actual resources when accessed.
+ *
+ * During runtime, this construct can provide references to all resources attached to the Origin,
+ * even if they were not explicitly exported.
+ */
+export type Rsc_FwRef_Exports<Exported extends Rsc_Ref = any> = Rsc_FwRef_Exports_Proxied &
     FwRef_Exports_ByKey<Exported>
 
-export type FwRef_Exports_Brand = FxRef_Exports_Proxied
-
-export function FwRef_Exports<Exported extends Ref2_Of>(
+/**
+ * Creates a forward reference exports construct for the given {@link Origin_Exporter} entity.
+ *
+ * @param entity
+ * @returns
+ */
+export function Rsc_FwRef_Exports<Exported extends Rsc_Ref>(
     entity: Origin_Exporter
-): FwRef_Exports<Exported> {
-    const proxied = new FxRef_Exports_Proxied(entity)
+): Rsc_FwRef_Exports<Exported> {
+    const proxied = new Rsc_FwRef_Exports_Proxied(entity)
     const handler = new FwRef_Exports_Handler(proxied)
     return new Proxy(proxied, handler) as any
 }
+export namespace Rsc_FwRef_Exports {
+    export function is(obj: any): obj is Rsc_FwRef_Exports {
+        return obj instanceof Rsc_FwRef_Exports_Proxied
+    }
+}
 
-export class FxRef_Exports_Proxied {
+/**
+ * A basic core of the {@link Rsc_FwRef_Exports} construct, containing information about the
+ * underlying {@link Origin_Exporter} entity.
+ */
+export class Rsc_FwRef_Exports_Proxied {
     #entity: Origin_Exporter
     constructor(entity: Origin_Exporter) {
         this.#entity = entity
@@ -30,10 +62,27 @@ export class FxRef_Exports_Proxied {
     __entity__(act?: (entity: Origin_Exporter) => any): Origin_Exporter {
         return this.#entity as any
     }
+
+    equals(other: any): boolean {
+        if (!other) {
+            return false
+        }
+        if (Rsc_FwRef_Exports.is(other)) {
+            return this.#entity.equals(other.#entity)
+        }
+        if (other instanceof Origin_Entity) {
+            return other.equals(this.#entity)
+        }
+        return false
+    }
 }
 
+/**
+ * Proxy handler for the {@link Rsc_FwRef_Exports} construct, providing dynamic access to the
+ * resources attached to the underlying {@link Origin_Exporter} entity.
+ */
 class FwRef_Exports_Handler<Entity extends Origin_Exporter> implements ProxyHandler<Entity> {
-    constructor(private readonly _subject: FxRef_Exports_Proxied) {}
+    constructor(private readonly _subject: Rsc_FwRef_Exports_Proxied) {}
 
     get entity() {
         return this._subject["__entity__"]()
@@ -60,8 +109,7 @@ class FwRef_Exports_Handler<Entity extends Origin_Exporter> implements ProxyHand
     }
 
     getPrototypeOf(_: Entity): object | null {
-        const r = Reflect.getPrototypeOf(this.entity)
-        return r
+        return Rsc_FwRef_Exports_Proxied.prototype
     }
 
     get exported() {
@@ -91,13 +139,14 @@ class FwRef_Exports_Handler<Entity extends Origin_Exporter> implements ProxyHand
         if (refKey == null) {
             return undefined
         }
-        return FwReference({
+        return FwRef({
             class: clazz,
-            key: refKey,
+            key: new RefKey(refKey.kind, {
+                name: refKey.name
+            }),
             origin: this.entity,
-            namespace: this.entity.meta.tryGet("namespace"),
             resolver: this.exported
-                .first(exp => exp.node.key.equals(refKey))
+                .first(exp => exp.node.name === refKey.name && exp.node.kind.equals(refKey.kind))
                 .map(x => {
                     if (x == null) {
                         throw new ProxyOperationError(

package/src/core/graph/resource/reference/fw-ref.ts

@@ -1,36 +1,73 @@
 import type { Doddle } from "doddle"
 import type { AnyCtor } from "what-are-you"
-import type { RefKey } from "../ref-key"
+import { RefKey } from "../ref-key"
 import { ProxyOperationError } from "./error"
-import type { Ref2_Of } from "./refable"
+import type { Rsc_Ref } from "./refable"
 
-export type FwReference<T extends Ref2_Of = Ref2_Of> = FwReference_Proxied<T> & T
-export function FwReference<Referenced extends Ref2_Of>(
-    props: FwReference_Props<Referenced>
-): FwReference<Referenced> {
-    const core = new FwReference_Proxied(props)
-    return new Proxy(core, new FwRef_Handler(core)) as FwReference<Referenced>
+/**
+ * The type of a forward reference to a resource.
+ *
+ * Acts as a stand-in for a resource that may not yet be available. Can be used to reference
+ * resources across different Origins while deferring their actual resolution until needed. This
+ * allows for circular references and more flexible resource definitions.
+ *
+ * The base `FwRef` object only has some basic properties about the resource being referenced, such
+ * as its {@link RefKey} and class type. Accessing any other properties or methods on the `FwRef`
+ * will trigger the resolution of the actual resource via a resolver.
+ *
+ * Because the `FwRef` avoids resolving the actual resource until needed, it won't detect missing
+ * resources when the reference is created. Instead, the missing resource will be detected later on,
+ * typically until resources are manifested. This makes it a bit harder to debug such issues.
+ */
+export type FwRef<T extends Rsc_Ref = Rsc_Ref> = FwRef_Proxied<T> & T
+
+/**
+ * Creates a forward reference to a resource, returning a proxy that defers resource resolution
+ * until properties or methods are accessed.
+ *
+ * @param props The properties of the forward reference.
+ * @returns The forward reference proxy.
+ */
+export function FwRef<Referenced extends Rsc_Ref>(
+    props: FwRef_Props<Referenced>
+): FwRef<Referenced> {
+    const core = new FwRef_Proxied(props)
+    return new Proxy(core, new FwRef_Handler(core)) as FwRef<Referenced>
 }
-export namespace FwReference {
-    export function is(obj: any): obj is FwReference {
-        return FwReference_Proxied.is(obj)
+export namespace FwRef {
+    export function is(obj: any): obj is FwRef {
+        return FwRef_Proxied.is(obj)
     }
 }
-export interface FwReference_Props<Referenced extends Ref2_Of> {
+/** Properties for creating a forward reference to a resource. */
+export interface FwRef_Props<Referenced extends Rsc_Ref> {
+    /** The class constructor of the referenced resource. */
     readonly class?: AnyCtor<Referenced>
+    /** The reference key identifying the referenced resource. */
     readonly key: RefKey
-    readonly namespace?: string
     readonly origin: object
     readonly resolver: Doddle<Referenced>
 }
 
-class FwReference_Proxied<To extends Ref2_Of> {
-    readonly #props: FwReference_Props<To>
-    constructor(props: FwReference_Props<To>) {
+class FwRef_Proxied<To extends Rsc_Ref> {
+    readonly #props: FwRef_Props<To>
+    constructor(props: FwRef_Props<To>) {
         this.#props = props
     }
 
-    static is(obj: any): obj is FwReference {
+    get name() {
+        return this.#props.key.name
+    }
+
+    get namespace() {
+        return this.__pull__().namespace // The $props.key won't have a namespace
+    }
+
+    get kind() {
+        return this.#props.key.kind
+    }
+
+    static is(obj: any): obj is FwRef {
         return obj && typeof obj === "object" && "__reference_props__" in obj
     }
 
@@ -41,13 +78,30 @@ class FwReference_Proxied<To extends Ref2_Of> {
     protected __reference_props__() {
         return this.#props
     }
+
+    get key() {
+        return new RefKey(this.kind, {
+            name: this.name,
+            namespace: this.namespace
+        })
+    }
+
+    equals(other: any): boolean {
+        if (!other) {
+            return false
+        }
+        // Resource_Top has a key property, but Resource_Child doesn't
+        // However in that case, the kind will be different anyway
+        // since FwRefs are just for top resources.
+        return this.key.equals(other.key)
+    }
 }
 
-class FwRef_Handler<T extends Ref2_Of> implements ProxyHandler<T> {
+class FwRef_Handler<T extends Rsc_Ref> implements ProxyHandler<T> {
     get _props() {
         return this._subject["__reference_props__"]()
     }
-    constructor(private readonly _subject: FwReference_Proxied<T>) {}
+    constructor(private readonly _subject: FwRef_Proxied<T>) {}
 
     get(target: T, prop: PropertyKey) {
         const { _props, _subject } = this
@@ -65,8 +119,8 @@ class FwRef_Handler<T extends Ref2_Of> implements ProxyHandler<T> {
         return result
     }
     getPrototypeOf(target: T) {
-        const Resource_Top = require("../top").Resource_Top
-        return this._props.class?.prototype ?? Resource_Top.prototype
+        const Rsc_Top = require("../top").Rsc_Top
+        return this._props.class?.prototype ?? Rsc_Top.prototype
     }
     has(target: T, prop: PropertyKey) {
         const { _props, _subject } = this

package/src/core/graph/resource/reference/index.ts

@@ -1,3 +1,3 @@
-export { FwReference } from "./fw-ref"
-export { FwRef_Exports, type FwRef_Exports_Brand } from "./fw-ref-exports"
+export { FwRef } from "./fw-ref"
+export { Rsc_FwRef_Exports } from "./fw-ref-exports"
 export type * from "./refable"

package/src/core/graph/resource/reference/refable.ts

@@ -1,28 +1,23 @@
 import type { AnyCtor } from "what-are-you"
-import type { Kind } from "../api-kind"
-import type { Resource_Entity } from "../entity"
-import type { Resource_Node } from "../node"
-
-export type Resource_Ref_Min<K extends Kind.IdentParent = Kind.IdentParent> = { kind: K }
-export type Resource_Ctor_Of<K extends Kind.IdentParent = Kind.IdentParent> = AnyCtor<
-    Ref2_Of<K>
-> & {
-    prototype: Ref2_Of<K>
+import type { RefLike } from "../../entity"
+import type { Ident_Like } from "../api-kind"
+import type { Rsc_Node } from "../node"
+export type Rsc_Ctor_Of<K extends Ident_Like = Ident_Like> = AnyCtor<Rsc_Ref<K>> & {
+    prototype: Rsc_Ref<K>
 }
-export type Ref2_Of<
-    Kind extends Kind.IdentParent = Kind.IdentParent,
+export type Rsc_Ref<
+    _Kind extends Ident_Like = Ident_Like,
     Name extends string = string
-> = Resource_Ref_Min<Kind> & {
+> = RefLike & {
+    kind: _Kind
     name: Name
+    namespace?: string
+    is<_Kind2 extends Ident_Like>(kind: _Kind2): this is Rsc_Ref<_Kind2>
     equals(other: any): boolean
-    node: Resource_Node
+    node: Rsc_Node
 }
-export type Resource_Ref_Full<
-    _Kind extends Kind.IdentParent = Kind.IdentParent,
-    _Name extends string = string
-> = Ref2_Of<_Kind, _Name> & Resource_Entity<_Name>
 
-export type Resource_Ref_Keys_Of<X extends Resource_Ref_Min, Else = never> = [X] extends [
+export type Rsc_Ref_Keys_Of<X extends Rsc_Ref, Else = never> = [X] extends [
     {
         keys: (infer K extends string)[]
     }

package/src/core/graph/resource/top.ts

@@ -4,16 +4,19 @@ import { type Manifest, type Manifest_Ident, type Manifest_Metadata } from "../.
 import { Trace, TraceEmbedder } from "../../tracing"
 import type { Origin_Entity } from "../origin/entity"
 import { OriginContextTracker } from "../origin/tracker"
-import type { Kind } from "./api-kind"
-import { Resource_Entity } from "./entity"
-export abstract class Resource_Top<
+import type { Ident_Kind } from "./api-kind"
+import { Rsc_Entity } from "./entity"
+export abstract class Rsc_Top<
     Name extends string = string,
     Props extends object = object
-> extends Resource_Entity<Name, Props> {
+> extends Rsc_Entity<Name, Props> {
     private readonly _origin: Origin_Entity
     readonly meta: Meta
-    abstract readonly kind: Kind.IdentParent
+    abstract readonly kind: Ident_Kind
 
+    get key() {
+        return this.kind.refKey({ name: this.name, namespace: this.namespace })
+    }
     get disabled() {
         return this.meta.tryGet("#k8ts.org/disabled", "") !== ""
     }

package/src/core/manifest/index.ts

@@ -1,5 +1,5 @@
 import { Embedder } from "../../utils/embedder"
-import { Resource_Entity } from "../graph/resource/entity"
+import { Rsc_Entity } from "../graph/resource/entity"
 export interface Manifest_Metadata {
     labels: Record<string, string>
     annotations: Record<string, string>
@@ -35,4 +35,4 @@ export interface SpecManifest<T extends JsonSerializable> extends Manifest {
     spec: T
 }
 
-export const ManifestSourceEmbedder = new Embedder<object, Resource_Entity>("ManifestSource")
+export const ManifestSourceEmbedder = new Embedder<object, Rsc_Entity>("ManifestSource")

package/src/expressions/data-sources/base.ts

@@ -1,13 +1,37 @@
 import { doddle, type DoddleAsync } from "doddle"
 
+/** Unique symbol used to identify data source objects. */
 export declare const DATA_SOURCE: unique symbol
 
+/**
+ * Lazy-loading data source that caches the result of a getter function. The getter is executed only
+ * once, and the result is memoized for subsequent calls.
+ *
+ * @example
+ *     const lazy = new DataSource_Lazy(() => expensiveComputation())
+ *     const value1 = await lazy.get() // Computes value
+ *     const value2 = await lazy.get() // Returns cached value
+ *
+ * @typeParam T - The type of data this source provides
+ */
 export class DataSource_Lazy<T = any> {
     private readonly _data: DoddleAsync<T>
+
+    /**
+     * Creates a new lazy data source.
+     *
+     * @param getter - Function that computes or retrieves the value (can be async)
+     */
     constructor(getter: () => T | Promise<T>) {
         this._data = doddle(async () => getter())
     }
 
+    /**
+     * Retrieves the value, computing it on first call and returning cached value on subsequent
+     * calls.
+     *
+     * @returns Promise resolving to the data value
+     */
     get() {
         return this._data.pull()
     }

package/src/expressions/data-sources/env-var.ts

@@ -1,6 +1,17 @@
 import { DataSource_Lazy } from "./base"
 
-export class DataSource_EnvVar extends DataSource_Lazy<string> {
+/**
+ * Data source that retrieves values from environment variables. Throws an error if the environment
+ * variable is not set.
+ *
+ * Can be used instead of a primitive in some cases when building Kubernetes manifests.
+ */
+class DataSource_EnvVar extends DataSource_Lazy<string> {
+    /**
+     * Creates an environment variable data source.
+     *
+     * @param name - The name of the environment variable
+     */
     constructor(public readonly name: string) {
         super(async () => {
             const value = process.env[this.name]
@@ -12,6 +23,17 @@ export class DataSource_EnvVar extends DataSource_Lazy<string> {
     }
 }
 
+/**
+ * Creates a lazy data source that reads from an environment variable.
+ *
+ * @example
+ *     const apiKey = localRefEnvVar("API_KEY")
+ *     const key = await apiKey.get() // Reads from process.env.API_KEY
+ *
+ * @param name - The name of the environment variable to read
+ * @returns A lazy data source for the environment variable
+ * @throws {Error} When the environment variable is not set
+ */
 export function localRefEnvVar(name: string) {
     return new DataSource_EnvVar(name)
 }

package/src/expressions/data-sources/interface.ts

@@ -1,13 +1,45 @@
+/** Supported data source type names for type-safe data source handling. */
 export type DataSource_Type_Name = "string" | "binary"
+
+/**
+ * Maps a data source type name to its corresponding value type.
+ *
+ * @typeParam Name - The type name ("string" or "binary")
+ * @returns String for "string" type, Uint8Array for "binary" type
+ */
 export type DataSource_Value<Name extends DataSource_Type_Name> = Name extends "string"
     ? string
     : Name extends "binary"
       ? Uint8Array
       : DataSource_Type_Name
+
+/**
+ * Interface for objects that provide data source values. Implementations can return values
+ * synchronously or asynchronously.
+ *
+ * @example
+ *     class MySource implements DataSource_Object<"string"> {
+ *         get() {
+ *             return "value"
+ *         }
+ *     }
+ *
+ * @typeParam TypeName - The type of data this source provides
+ */
 export interface DataSource_Object<TypeName extends DataSource_Type_Name = DataSource_Type_Name> {
     get(): DataSource_Value<TypeName> | Promise<DataSource_Value<TypeName>>
 }
 
+/**
+ * A data source can be either a DataSource_Object or a direct value. This allows for flexible API
+ * design where values can be passed directly or lazily loaded.
+ *
+ * @example
+ *     const direct: DataSource<"string"> = "hello"
+ *     const lazy: DataSource<"string"> = { get: () => "hello" }
+ *
+ * @typeParam Only - Constrains the data source to a specific type
+ */
 export type DataSource<Only extends DataSource_Type_Name = DataSource_Type_Name> =
     | DataSource_Object<Only>
     | DataSource_Value<Only>