@k8ts/instruments 0.11.3 → 0.12.0

package/src/core/graph/resource/{reference/fw-ref-exports.ts → forward/exports.ts}

@@ -1,17 +1,17 @@
 import { seq } from "doddle"
-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"
-
-/** 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>
+import { OriginEntity } from "../../origin"
+import type { ExporterOrigin } from "../../origin/exporter"
+import { ResourceIdent } from "../ident"
+import type { ResourceRef } from "../ref"
+import { K8tsProxyError } from "./error"
+import { ForwardRef } from "./ref"
+
+/** Expands the resources exported by an OriginExported into a dictionary of name to FwRef. */
+export type ForwardExports_ByKey<Exports extends ResourceRef = ResourceRef> = {
+    [E in Exports as `${E["kind"]["value"]}/${E["ident"]["name"]}`]: ForwardRef<E>
 }
 /**
- * A type describing all resources exported by an {@link Origin_Exporter} as forward references.
+ * A type describing all resources exported by an {@link ExporterOrigin} 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"]`.
@@ -27,39 +27,39 @@ export type FwRef_Exports_ByKey<Exports extends Rsc_Ref = Rsc_Ref> = {
  * 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 ForwardExports<Exported extends ResourceRef = any> = ForwardExports_Proxied &
+    ForwardExports_ByKey<Exported>
 
 /**
- * Creates a forward reference exports construct for the given {@link Origin_Exporter} entity.
+ * Creates a forward reference exports construct for the given {@link ExporterOrigin} entity.
  *
  * @param entity
  * @returns
  */
-export function Rsc_FwRef_Exports<Exported extends Rsc_Ref>(
-    entity: Origin_Exporter
-): Rsc_FwRef_Exports<Exported> {
-    const proxied = new Rsc_FwRef_Exports_Proxied(entity)
-    const handler = new FwRef_Exports_Handler(proxied)
+export function ForwardExports<Exported extends ResourceRef>(
+    entity: ExporterOrigin
+): ForwardExports<Exported> {
+    const proxied = new ForwardExports_Proxied(entity)
+    const handler = new ForwardExports_ProxyHandler(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 namespace ForwardExports {
+    export function is(obj: any): obj is ForwardExports {
+        return obj instanceof ForwardExports_Proxied
     }
 }
 
 /**
- * A basic core of the {@link Rsc_FwRef_Exports} construct, containing information about the
- * underlying {@link Origin_Exporter} entity.
+ * A basic core of the {@link ForwardExports} construct, containing information about the underlying
+ * {@link ExporterOrigin} entity.
  */
-export class Rsc_FwRef_Exports_Proxied {
-    #entity: Origin_Exporter
-    constructor(entity: Origin_Exporter) {
+export class ForwardExports_Proxied {
+    #entity: ExporterOrigin
+    constructor(entity: ExporterOrigin) {
         this.#entity = entity
     }
 
-    __entity__(act?: (entity: Origin_Exporter) => any): Origin_Exporter {
+    __entity__(act?: (entity: ExporterOrigin) => any): ExporterOrigin {
         return this.#entity as any
     }
 
@@ -67,10 +67,10 @@ export class Rsc_FwRef_Exports_Proxied {
         if (!other) {
             return false
         }
-        if (Rsc_FwRef_Exports.is(other)) {
+        if (ForwardExports.is(other)) {
             return this.#entity.equals(other.#entity)
         }
-        if (other instanceof Origin_Entity) {
+        if (other instanceof OriginEntity) {
             return other.equals(this.#entity)
         }
         return false
@@ -78,24 +78,24 @@ export class Rsc_FwRef_Exports_Proxied {
 }
 
 /**
- * Proxy handler for the {@link Rsc_FwRef_Exports} construct, providing dynamic access to the
- * resources attached to the underlying {@link Origin_Exporter} entity.
+ * Proxy handler for the {@link ForwardExports} construct, providing dynamic access to the resources
+ * attached to the underlying {@link ExporterOrigin} entity.
  */
-class FwRef_Exports_Handler<Entity extends Origin_Exporter> implements ProxyHandler<Entity> {
-    constructor(private readonly _subject: Rsc_FwRef_Exports_Proxied) {}
+class ForwardExports_ProxyHandler<Entity extends ExporterOrigin> implements ProxyHandler<Entity> {
+    constructor(private readonly _subject: ForwardExports_Proxied) {}
 
     get entity() {
         return this._subject["__entity__"]()
     }
     get node() {
-        return this.entity.node
+        return this.entity.__vertex__
     }
     get resourceKinds() {
         return this.node.resourceKinds
     }
 
     #createImmutableError(action: string) {
-        return new ProxyOperationError(
+        return new K8tsProxyError(
             `Tried to ${action} an the exports constructs of ${this.entity}, but it is immutable.`
         )
     }
@@ -109,7 +109,7 @@ class FwRef_Exports_Handler<Entity extends Origin_Exporter> implements ProxyHand
     }
 
     getPrototypeOf(_: Entity): object | null {
-        return Rsc_FwRef_Exports_Proxied.prototype
+        return ForwardExports_Proxied.prototype
     }
 
     get exported() {
@@ -135,21 +135,26 @@ class FwRef_Exports_Handler<Entity extends Origin_Exporter> implements ProxyHand
 
         const resourceKinds = this.resourceKinds
         const refKey = resourceKinds.tryParse(key)
-        const clazz = resourceKinds.tryGetClass(key)
         if (refKey == null) {
             return undefined
         }
-        return FwRef({
+        const clazz = resourceKinds.getClass(key)
+
+        return ForwardRef({
             class: clazz,
-            key: new RefKey(refKey.kind, {
+            ident: new ResourceIdent(refKey.kind, {
                 name: refKey.name
             }),
             origin: this.entity,
             resolver: this.exported
-                .first(exp => exp.node.name === refKey.name && exp.node.kind.equals(refKey.kind))
+                .first(
+                    exp =>
+                        exp.__vertex__.name === refKey.name &&
+                        exp.__vertex__.kind.equals(refKey.kind)
+                )
                 .map(x => {
                     if (x == null) {
-                        throw new ProxyOperationError(
+                        throw new K8tsProxyError(
                             `Failed to resolve forward reference to ${refKey} in ${this.entity}.`
                         )
                     }
@@ -177,7 +182,7 @@ class FwRef_Exports_Handler<Entity extends Origin_Exporter> implements ProxyHand
     }
 
     ownKeys(target: Entity): ArrayLike<string | symbol> {
-        throw new ProxyOperationError(
+        throw new K8tsProxyError(
             `Cannot list all keys of a dynamic exports construct for ${this.entity}.`
         )
     }

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

@@ -0,0 +1,2 @@
+export { ForwardExports } from "./exports"
+export { ForwardRef } from "./ref"

package/src/core/graph/resource/{reference/fw-ref.ts → forward/ref.ts}

@@ -1,8 +1,10 @@
-import type { Doddle } from "doddle"
-import type { AnyCtor } from "what-are-you"
-import { RefKey } from "../ref-key"
-import { ProxyOperationError } from "./error"
-import type { Rsc_Ref } from "./refable"
+import { seq, type Doddle } from "doddle"
+import { mapValues } from "lodash"
+import { getNiceClassName } from "what-are-you"
+import { K8tsGraphError } from "../../error"
+import { ResourceIdent } from "../ident"
+import type { ResourceRef, ResourceRef_Constructor_For } from "../ref"
+import { K8tsProxyError } from "./error"
 
 /**
  * The type of a forward reference to a resource.
@@ -12,14 +14,14 @@ import type { Rsc_Ref } from "./refable"
  * 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.
+ * as its {@link ResourceIdent} 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
+export type ForwardRef<T extends ResourceRef = ResourceRef> = ForwardRef_Proxied<T> & T
 
 /**
  * Creates a forward reference to a resource, returning a proxy that defers resource resolution
@@ -28,46 +30,71 @@ export type FwRef<T extends Rsc_Ref = Rsc_Ref> = FwRef_Proxied<T> & T
  * @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 function ForwardRef<Referenced extends ResourceRef>(
+    props: ForwardRef_Props<Referenced>
+): ForwardRef<Referenced> {
+    const core = new ForwardRef_Proxied(props)
+    return new Proxy(core, new ForwardRef_ProxyHandler(core)) as ForwardRef<Referenced>
 }
-export namespace FwRef {
-    export function is(obj: any): obj is FwRef {
-        return FwRef_Proxied.is(obj)
+export namespace ForwardRef {
+    export function is(obj: any): obj is ForwardRef {
+        return ForwardRef_Proxied.is(obj)
     }
 }
 /** Properties for creating a forward reference to a resource. */
-export interface FwRef_Props<Referenced extends Rsc_Ref> {
+export interface ForwardRef_Props<Referenced extends ResourceRef> {
     /** The class constructor of the referenced resource. */
-    readonly class?: AnyCtor<Referenced>
+    readonly class?: ResourceRef_Constructor_For<Referenced>
     /** The reference key identifying the referenced resource. */
-    readonly key: RefKey
+    readonly ident: ResourceIdent
     readonly origin: object
     readonly resolver: Doddle<Referenced>
 }
-
-class FwRef_Proxied<To extends Rsc_Ref> {
-    readonly #props: FwRef_Props<To>
-    constructor(props: FwRef_Props<To>) {
+const hiddenProperties = {
+    is(this: ForwardRef_Proxied, clsOrKind: any): boolean {
+        if (typeof clsOrKind === "function") {
+            return this.clazz.prototype instanceof clsOrKind || this instanceof clsOrKind
+        }
+        return this.kind.equals(clsOrKind)
+    },
+    assert(this: ForwardRef_Proxied, cls: abstract new (...args: any[]) => any): any {
+        if (hiddenProperties.is.call(this, cls)) {
+            return this as any
+        }
+        throw new K8tsGraphError(
+            `This Resource ${this} is not compatible with the class ${getNiceClassName(cls)}.`
+        )
+    }
+}
+class ForwardRef_Proxied<To extends ResourceRef = ResourceRef> {
+    readonly #props: ForwardRef_Props<To>
+    constructor(props: ForwardRef_Props<To>) {
         this.#props = props
+        Object.defineProperties(
+            this,
+            mapValues(hiddenProperties, prop => ({ value: prop }))
+        )
     }
 
     get name() {
-        return this.#props.key.name
+        return this.#props.ident.name
+    }
+
+    get clazz() {
+        return (
+            this.#props.class ?? (require("../top").ResourceTop as ResourceRef_Constructor_For<To>)
+        )
     }
 
     get namespace() {
-        return this.__pull__().namespace // The $props.key won't have a namespace
+        return this.__pull__().ident.namespace // The $props.ident won't have a namespace
     }
 
     get kind() {
-        return this.#props.key.kind
+        return this.#props.ident.kind
     }
 
-    static is(obj: any): obj is FwRef {
+    static is(obj: any): obj is ForwardRef {
         return obj && typeof obj === "object" && "__reference_props__" in obj
     }
 
@@ -80,7 +107,7 @@ class FwRef_Proxied<To extends Rsc_Ref> {
     }
 
     get key() {
-        return new RefKey(this.kind, {
+        return new ResourceIdent(this.kind, {
             name: this.name,
             namespace: this.namespace
         })
@@ -90,27 +117,29 @@ class FwRef_Proxied<To extends Rsc_Ref> {
         if (!other) {
             return false
         }
-        // Resource_Top has a key property, but Resource_Child doesn't
+        // ResourceTop has a key property, but ResourceChild 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 Rsc_Ref> implements ProxyHandler<T> {
+class ForwardRef_ProxyHandler<T extends ResourceRef> implements ProxyHandler<T> {
     get _props() {
         return this._subject["__reference_props__"]()
     }
-    constructor(private readonly _subject: FwRef_Proxied<T>) {}
+    constructor(private readonly _subject: ForwardRef_Proxied<T>) {}
 
     get(target: T, prop: PropertyKey) {
         const { _props, _subject } = this
         if (prop === "constructor") {
             return this._props.class
         }
+
         if (Reflect.has(_subject, prop)) {
             return Reflect.get(_subject, prop)
         }
+
         const resource = _subject["__pull__"]() as any
         const result = Reflect.get(resource, prop)
         if (typeof result === "function") {
@@ -119,8 +148,8 @@ class FwRef_Handler<T extends Rsc_Ref> implements ProxyHandler<T> {
         return result
     }
     getPrototypeOf(target: T) {
-        const Rsc_Top = require("../top").Rsc_Top
-        return this._props.class?.prototype ?? Rsc_Top.prototype
+        const RscTop = require("../top").ResourceTop
+        return this._props.class?.prototype ?? RscTop.prototype
     }
     has(target: T, prop: PropertyKey) {
         const { _props, _subject } = this
@@ -142,19 +171,21 @@ class FwRef_Handler<T extends Rsc_Ref> implements ProxyHandler<T> {
         return resourceDesc
     }
     get referant() {
-        return this._subject["__reference_props__"]().key.string
+        return this._subject["__reference_props__"]().ident.string
     }
     #createImmutableError(action: string) {
-        return new ProxyOperationError(
+        return new K8tsProxyError(
             `Tried to ${action} a forward reference to ${this.referant}, but it cannot be modified.`
         )
     }
 
     defineProperty(_: any, property: string | symbol, desc: PropertyDescriptor): boolean {
-        throw this.#createImmutableError(`define property ${String(property)} on`)
+        const pulled = this._props.resolver.pull() as any
+        return Reflect.defineProperty(pulled, property, desc)
     }
     deleteProperty(_: T, p: string | symbol): boolean {
-        throw this.#createImmutableError(`delete property ${String(p)} from`)
+        const pulled = this._props.resolver.pull() as any
+        return Reflect.deleteProperty(pulled, p)
     }
     preventExtensions(): boolean {
         return true
@@ -163,13 +194,18 @@ class FwRef_Handler<T extends Rsc_Ref> implements ProxyHandler<T> {
         return false
     }
     set(_: T, p: string | symbol): boolean {
-        throw this.#createImmutableError(`set property ${String(p)} on`)
+        const pulled = this._props.resolver.pull() as any
+        return Reflect.set(pulled, p, (_ as any)[p])
     }
     ownKeys(): ArrayLike<string | symbol> {
         const pulled = this._props.resolver.pull() as any
-        return [...Reflect.ownKeys(this._subject), ...Reflect.ownKeys(pulled)]
+        const keys1 = Reflect.ownKeys(this._subject)
+        const keys2 = Reflect.ownKeys(pulled)
+        const uniq = seq(keys1).concat(keys2).uniq().toArray()
+        return uniq.pull()
     }
     setPrototypeOf(): boolean {
-        throw this.#createImmutableError(`set the prototype of`)
+        const pulled = this._props.resolver.pull() as any
+        return Reflect.setPrototypeOf(pulled, pulled)
     }
 }

package/src/core/graph/resource/gvk/0-base.ts

@@ -0,0 +1,37 @@
+export interface GVK_Like {
+    readonly value: string
+    readonly url: string
+    readonly dns: string
+    readonly parent: GVK_Like | null
+    equals(other: any): boolean
+}
+export abstract class Gvk_Base<Url extends string = string> implements GVK_Like {
+    constructor(readonly url: Url) {}
+    abstract get value(): string
+    abstract get parent(): Gvk_Base | null
+    get parts(): Gvk_Base[] {
+        const parts: Gvk_Base[] = []
+        let curr: Gvk_Base | null = this
+        while (curr) {
+            parts.unshift(curr)
+            curr = curr.parent
+        }
+        return parts
+    }
+    get dns() {
+        return this.parts
+            .map(p => p.value)
+            .filter(Boolean)
+            .join(".")
+    }
+
+    equals(other: any) {
+        if (other instanceof Gvk_Base) {
+            return this.url === other.url
+        }
+        if (typeof other === "string") {
+            return this.url === other
+        }
+        return false
+    }
+}

package/src/core/graph/resource/gvk/1-group.ts

@@ -0,0 +1,23 @@
+import type { JoinIfNotEmpty } from "../../../../expressions"
+import { Gvk_Base } from "./0-base"
+import { Gvk_Version } from "./2=version"
+import type { GVK_sVersion } from "./strings"
+export class Gvk_Group<Group extends string = string> extends Gvk_Base<Group> {
+    get parts() {
+        return [this]
+    }
+    get parent() {
+        return null
+    }
+    get value(): Group {
+        return this.url
+    }
+
+    version<Version extends GVK_sVersion>(version: Version) {
+        const newUrl = [this.url, version].filter(Boolean).join("/")
+        return new Gvk_Version(newUrl as JoinIfNotEmpty<Group, "/", Version>)
+    }
+}
+export function group<ApiGroup extends string>(apiGroup: ApiGroup) {
+    return new Gvk_Group(apiGroup)
+}

package/src/core/graph/resource/gvk/2=version.ts

@@ -0,0 +1,21 @@
+import { Gvk_Base } from "./0-base"
+import { group, Gvk_Group } from "./1-group"
+import { Gvk } from "./3-gvk"
+import type { GVK_sVersion } from "./strings"
+
+export class Gvk_Version<Url extends string> extends Gvk_Base<Url> {
+    get parent() {
+        return new Gvk_Group(this.url.split("/")[0] as string)
+    }
+
+    get value(): Url extends `${string}/${infer V}` ? V : Url extends `v${string}` ? Url : never {
+        return this.url.split("/")[1] as any
+    }
+
+    kind<Kind extends string>(kind: Kind, customPlural?: string) {
+        return new Gvk(`${this.url}/${kind}` as `${Url}/${Kind}`, customPlural)
+    }
+}
+export function version<ApiVersion extends GVK_sVersion>(apiVersion: ApiVersion) {
+    return group("").version(apiVersion)
+}

package/src/core/graph/resource/gvk/3-gvk.ts

@@ -0,0 +1,56 @@
+import { ResourceIdent, type ResourceIdent_Options } from "../ident"
+import { Gvk_Base } from "./0-base"
+import { Gvk_Version } from "./2=version"
+import { Gvk_SubKind } from "./4-subkind"
+
+export class Gvk<Url extends string = string> extends Gvk_Base<Url> {
+    constructor(
+        url: Url,
+        private _customPlural?: string
+    ) {
+        super(url)
+    }
+    get parent() {
+        const stringParts = this.url.split("/").slice(0, -1)
+        return new Gvk_Version<string>(stringParts.join("/") as string)
+    }
+
+    get plural() {
+        return this._customPlural ?? pluralize(this.value)
+    }
+
+    refKey<Name extends string>(options: ResourceIdent_Options<Name>) {
+        return new ResourceIdent<this, Name>(this as any, options)
+    }
+
+    get dns() {
+        const parents = this.parent.parts.map(x => x.value)
+        parents.push(this.plural)
+        return parents.join(".")
+    }
+
+    get value(): Url extends `${string}/${string}/${infer K}`
+        ? K
+        : Url extends `v${string}/${infer K}`
+          ? K
+          : never {
+        return this.url.split("/").at(-1) as any
+    }
+
+    subkind<SubKind extends string>(subKind: SubKind) {
+        return new Gvk_SubKind<`${Url}.${SubKind}`>(`${this.url}.${subKind}` as `${Url}.${SubKind}`)
+    }
+}
+
+export function pluralize(word: string): string {
+    if (["s", "sh", "ch", "x", "z", "ro"].some(suffix => word.endsWith(suffix))) {
+        return `${word}es`
+    }
+    if (["ay", "ey", "iy", "oy", "uy"].some(suffix => word.endsWith(suffix))) {
+        return `${word}s`
+    }
+    if (word.endsWith("y")) {
+        return `${word.slice(0, -1)}ies`
+    }
+    return `${word}s`
+}

package/src/core/graph/resource/gvk/4-subkind.ts

@@ -0,0 +1,19 @@
+import { Gvk_Base } from "./0-base"
+import { Gvk } from "./3-gvk"
+
+export class Gvk_SubKind<Url extends string = string> extends Gvk_Base<Url> {
+    get parent() {
+        const [group, version, kind] = this.url.split("/")
+        return new Gvk<`${string}/${string}`>(
+            `${group}/${version}/${kind}` as `${string}/${string}`
+        )
+    }
+
+    get value(): Url extends `${string}.${infer Sk}` ? Sk : never {
+        return this.url.split("/").at(-1) as any
+    }
+
+    subkind<SubKind extends string>(subKind: SubKind) {
+        return new Gvk_SubKind<`${Url}.${SubKind}`>(`${this.url}.${subKind}` as `${Url}.${SubKind}`)
+    }
+}

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

@@ -0,0 +1,5 @@
+export * from "./0-base"
+export * from "./1-group"
+export * from "./2=version"
+export * from "./3-gvk"
+export * from "./4-subkind"

package/src/core/graph/resource/gvk/strings.ts

@@ -0,0 +1,3 @@
+export type GVK_sGreek = "alpha" | "beta"
+export type GVK_sVersion_Trailer = `${GVK_sGreek}${number}`
+export type GVK_sVersion = `v${number}${GVK_sVersion_Trailer | ""}`