@k8ts/instruments 0.5.3 → 0.6.2

package/src/core/graph/resource/api-kind/pluralize.ts

@@ -0,0 +1,32 @@
+type _Alpha_Beta = "alpha" | "beta"
+type _Sub_Version = `${_Alpha_Beta}${number}`
+type Version = `v${number}${_Sub_Version | ""}`
+
+export type _Group = string
+export type _Slash<A extends string, B extends string> = `${A}/${B}`
+export type _Group_Version<Group extends string = string, Vers extends string = string> =
+    | _Slash<Group, Vers>
+    | Version
+
+type _Word_Plural_Map = {
+    y: "ies"
+    s: "es"
+    ch: "ches"
+    sh: "es"
+    z: "zes"
+    ro: "es"
+    x: "es"
+}
+
+export type Pluralize<S extends string> = S extends `${infer K extends keyof _Word_Plural_Map}`
+    ? `${K}${_Word_Plural_Map[K]}`
+    : `${S}s`
+export function pluralize<S extends string>(word: S): Pluralize<S> {
+    if (["s", "sh", "ch", "x", "z", "ro"].some(suffix => word.endsWith(suffix))) {
+        return `${word}es` as Pluralize<S>
+    }
+    if (word.endsWith("y")) {
+        return `${word.slice(0, -1)}ies` as Pluralize<S>
+    }
+    return `${word}s` as Pluralize<S>
+}

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

@@ -0,0 +1,26 @@
+import { Resource_Entity } from "./entity"
+
+export abstract class Resource_Child<Props extends object = object> extends Resource_Entity<
+    string,
+    Props
+> {
+    #parent: Resource_Entity
+    constructor(parent: Resource_Entity, name: string, props: Props) {
+        super(name, props)
+        this.#parent = parent
+    }
+
+    protected __parent__(): Resource_Entity {
+        return this.#parent
+    }
+
+    protected __origin__() {
+        return this.__parent__()["__origin__"]()
+    }
+
+    protected abstract __submanifest__(): object
+
+    get namespace(): string | undefined {
+        return this.__parent__()?.namespace
+    }
+}

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

@@ -0,0 +1,58 @@
+import { getDeepPropertyDescriptor } from "@k8ts/metadata/util"
+import { getNiceClassName } from "what-are-you"
+import { displayers } from "../../../utils"
+import { Entity } from "../entity"
+import type { Origin_Entity } from "../origin"
+import type { Kind } from "./api-kind"
+import { Resource_Node } from "./node"
+
+@displayers({
+    simple: s => s.node,
+    pretty: s => s.node
+})
+export abstract class Resource_Entity<
+    Name extends string = string,
+    Props extends object = object
+> extends Entity<Resource_Node, Resource_Entity> {
+    abstract get kind(): Kind.IdentParent
+
+    with(callback: (self: this) => void) {
+        callback(this)
+        return this
+    }
+
+    abstract readonly namespace: string | undefined
+
+    ref() {
+        return {
+            kind: this.kind.name,
+            name: this.name,
+            namespace: this.namespace
+        }
+    }
+    protected constructor(
+        readonly name: Name,
+        readonly props: Props
+    ) {
+        super()
+
+        this.name = name
+        const desc = getDeepPropertyDescriptor(this, "kind")
+        if (!desc || !desc.get) {
+            throw new Error(
+                `ResourceEntity subclass ${getNiceClassName(this)} must implement the 'kind' property as a getter, but it's missing or not a getter.`
+            )
+        }
+    }
+
+    protected abstract __origin__(): Origin_Entity
+    get node(): Resource_Node {
+        return new Resource_Node(this.__origin__().node, this)
+    }
+
+    get shortFqn() {
+        return [this.node.origin.name, [this.kind.name, this.name].filter(Boolean).join("/")].join(
+            ":"
+        )
+    }
+}

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

@@ -0,0 +1,7 @@
+export * from "./api-kind"
+export * from "./child"
+export * from "./entity"
+export * from "./node"
+export * from "./ref-key"
+export * from "./reference"
+export * from "./top"

package/src/{graph/resource-node.ts → core/graph/resource/node.ts}

@@ -1,13 +1,15 @@
-import { MutableMeta } from "@k8ts/metadata"
+import { Meta } from "@k8ts/metadata"
 import chalk from "chalk"
 import { seq } from "doddle"
-import { Kind } from "../api-kind"
-import { Displayers, displayers, PrivateCtor } from "../displayers"
-import { RefKey } from "../ref-key"
-import { TraceEmbedder } from "../tracing"
-import { BaseEntity, BaseNode, Formats } from "./base-node"
-import { Origin } from "./origin-node"
-import { Relations } from "./relations"
+import { type AnyCtor } from "what-are-you"
+import { Displayers, displayers } from "../../../utils/displayers"
+import { TraceEmbedder } from "../../tracing"
+import { Formats } from "../entity"
+import { Node } from "../node"
+import { OriginNode } from "../origin/node"
+import type { Kind } from "./api-kind"
+import type { Resource_Entity } from "./entity"
+import { RefKey } from "./ref-key"
 
 @displayers({
     simple: s => `[${s.shortFqn}]`,
@@ -33,21 +35,23 @@ import { Relations } from "./relations"
         return text
     }
 })
-export class ResourceNode extends BaseNode<ResourceNode, ResourceEntity> {
-    get relations() {
-        return seq(this._relations.needs)
-    }
-
+export class Resource_Node extends Node<Resource_Node, Resource_Entity> {
     get fullFqn() {
         return [this.kind.dns, this.namespace, this.name].filter(Boolean).join("/")
     }
+    get key(): RefKey {
+        return new RefKey(this.kind, this.name)
+    }
+    get kind() {
+        return this.entity.kind
+    }
 
     get namespace() {
         return this.meta?.tryGet("namespace")
     }
 
     get trace() {
-        return TraceEmbedder.get(this)
+        return TraceEmbedder.get(this.entity)
     }
 
     get isExported() {
@@ -55,25 +59,25 @@ export class ResourceNode extends BaseNode<ResourceNode, ResourceEntity> {
     }
 
     get meta() {
-        return "meta" in this._entity ? (this._entity.meta as MutableMeta) : undefined
+        return "meta" in this.entity ? (this.entity.meta as Meta) : undefined
     }
 
     get isExternal() {
         return this.origins.some(x => x.name === "EXTERNAL").pull()
     }
 
-    when<EntityType extends ResourceEntity>(
-        type: PrivateCtor<EntityType>,
+    when<EntityType extends Resource_Entity>(
+        type: AnyCtor<EntityType>,
         fn: (entity: EntityType) => void
     ) {
-        const entity = this._entity as EntityType
+        const entity = this.entity as EntityType
         if (entity instanceof type) {
             fn(entity)
         }
     }
 
-    as<EntityType extends ResourceEntity>(type: PrivateCtor<EntityType>) {
-        const entity = this._entity as EntityType
+    as<EntityType extends Resource_Entity>(type: AnyCtor<EntityType>) {
+        const entity = this.entity as EntityType
         if (entity instanceof type) {
             return entity
         }
@@ -85,7 +89,7 @@ export class ResourceNode extends BaseNode<ResourceNode, ResourceEntity> {
     get origins() {
         const self = this
         return seq(function* () {
-            let current: Origin | null = self.origin
+            let current: OriginNode | null = self.origin
             while (current) {
                 yield current
                 current = current.parent
@@ -93,15 +97,7 @@ export class ResourceNode extends BaseNode<ResourceNode, ResourceEntity> {
         })
     }
 
-    get kids() {
-        return seq(this._relations.kids)
-    }
-
-    get parent() {
-        return this._relations.parent()
-    }
-
-    override get shortFqn() {
+    get shortFqn() {
         return `${this.origin.name}:${this.key}`
     }
 
@@ -112,22 +108,14 @@ export class ResourceNode extends BaseNode<ResourceNode, ResourceEntity> {
     format(format: Formats) {
         return Displayers.get(this).pretty(format)
     }
-    private get _relations() {
-        return Relations.get(this._entity)
-    }
 
     hasKind(kind: Kind.Identifier) {
         return this.kind.equals(kind)
     }
     constructor(
-        readonly origin: Origin,
-        readonly entity: ResourceEntity,
-        readonly key: RefKey
+        readonly origin: OriginNode,
+        readonly entity: Resource_Entity
     ) {
         super(entity)
     }
 }
-export interface MetadataEntity extends BaseEntity<ResourceNode> {
-    meta: MutableMeta
-}
-export interface ResourceEntity extends BaseEntity<ResourceNode> {}

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

@@ -0,0 +1,62 @@
+import { InstrumentsError } from "../../../../error"
+import type { Kind } from "../api-kind"
+
+export type RefKey_Input = RefKey | RefKey["string"]
+export type RefKey_sFormat<Kind extends string, Name extends string> = `${Kind}/${Name}`
+const separator = "/"
+export interface RefKey_Parsed {
+    kind: string
+    name: string
+}
+
+export function parse(ref: string) {
+    const result = tryParse(ref)
+    if (!result) {
+        throw new InstrumentsError(`Could not parse reference key: ${ref}`)
+    }
+    return result
+}
+
+export function tryParse(ref: string): RefKey_Parsed | undefined {
+    if (typeof ref !== "string") {
+        return undefined
+    }
+    if (ref == null) {
+        return undefined
+    }
+    if (typeof ref === "object") {
+        return undefined
+    }
+    const [kind, name] = ref.split(separator).map(s => s.trim())
+    if (!kind || !name) {
+        return undefined
+    }
+    return {
+        kind,
+        name
+    }
+}
+export class RefKey<K extends Kind.IdentParent = Kind.IdentParent, Name extends string = string> {
+    constructor(
+        readonly kind: K,
+        readonly name: Name
+    ) {}
+
+    get string(): RefKey_sFormat<K["name"], Name> {
+        return [this.kind.name, this.name].join(separator) as RefKey_sFormat<K["name"], Name>
+    }
+
+    equals(other: RefKey): boolean {
+        if (other == null) {
+            return false
+        }
+        if (typeof other !== "object") {
+            return false
+        }
+        return this.kind.equals(other.kind) && this.name === other.name
+    }
+
+    toString() {
+        return this.string
+    }
+}

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

@@ -0,0 +1,7 @@
+import { InstrumentsError } from "../../../../error"
+
+export class ProxyOperationError extends InstrumentsError {
+    constructor(message: string, details: Record<string, any> = {}) {
+        super(message, details)
+    }
+}

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

@@ -0,0 +1,164 @@
+import { seq } from "doddle"
+import type { Resource_Core_Ref } from "."
+import { FwReference } from "."
+import type { Origin_Exporter } from "../../origin"
+import { ProxyOperationError } from "./error"
+
+export type FwRef_Exports_ByKey<Exports extends Resource_Core_Ref = Resource_Core_Ref> = {
+    [E in Exports as `${E["kind"]["name"]}/${E["name"]}`]: FwReference<E>
+}
+
+export type FwRef_Exports<Exported extends Resource_Core_Ref = Resource_Core_Ref> =
+    FxRef_Exports_Proxied & FwRef_Exports_ByKey<Exported>
+
+export type FwRef_Exports_Brand = FxRef_Exports_Proxied
+
+export function FwRef_Exports<Exported extends Resource_Core_Ref>(
+    entity: Origin_Exporter
+): FwRef_Exports<Exported> {
+    const proxied = new FxRef_Exports_Proxied(entity)
+    const handler = new FwRef_Exports_Handler(proxied)
+    return new Proxy(proxied, handler) as any
+}
+
+export class FxRef_Exports_Proxied {
+    #entity: Origin_Exporter
+    constructor(entity: Origin_Exporter) {
+        this.#entity = entity
+    }
+
+    __entity__(act?: (entity: Origin_Exporter) => any): Origin_Exporter {
+        return this.#entity as any
+    }
+}
+
+class FwRef_Exports_Handler<Entity extends Origin_Exporter> implements ProxyHandler<Entity> {
+    constructor(private readonly _subject: FxRef_Exports_Proxied) {}
+
+    get entity() {
+        return this._subject["__entity__"]()
+    }
+    get node() {
+        return this.entity.node
+    }
+    get resourceKinds() {
+        return this.node.resourceKinds
+    }
+
+    #createImmutableError(action: string) {
+        return new ProxyOperationError(
+            `Tried to ${action} an the exports constructs of ${this.entity}, but it is immutable.`
+        )
+    }
+
+    defineProperty(_: object, property: string | symbol, __: PropertyDescriptor): boolean {
+        throw this.#createImmutableError(`define property ${String(property)} on`)
+    }
+
+    deleteProperty(_: object, property: string | symbol): boolean {
+        throw this.#createImmutableError(`delete property ${String(property)} from`)
+    }
+
+    getPrototypeOf(_: Entity): object | null {
+        const r = Reflect.getPrototypeOf(this.entity)
+        return r
+    }
+
+    get exported() {
+        return seq(this.entity.resources)
+    }
+
+    #isValidReferant(prop: PropertyKey) {
+        return this.resourceKinds.tryParse(prop as string) != null
+    }
+
+    get(target: any, property: string | symbol): any {
+        const key = property as string
+        if (key === "constructor") {
+            return this._subject.__entity__().constructor
+        }
+        if (Reflect.has(this._subject, key)) {
+            const x = Reflect.get(this._subject, property)
+            if (typeof x === "function") {
+                return x.bind(this._subject)
+            }
+            return x
+        }
+
+        const resourceKinds = this.resourceKinds
+        const refKey = resourceKinds.tryParse(key)
+        const clazz = resourceKinds.tryGetClass(key)
+        if (refKey == null) {
+            return undefined
+        }
+        return FwReference({
+            class: clazz,
+            key: refKey,
+            origin: this.entity,
+            namespace: this.entity.meta.tryGet("namespace"),
+            resolver: this.exported
+                .first(exp => exp.node.key.equals(refKey))
+                .map(x => {
+                    if (x == null) {
+                        throw new ProxyOperationError(
+                            `Failed to resolve forward reference to ${refKey} in ${this.entity}.`
+                        )
+                    }
+                    return x
+                })
+        })
+    }
+
+    has(_: Entity, p: string | symbol): boolean {
+        if (Reflect.has(this.entity, p)) {
+            return true
+        }
+        if (!this.#isValidReferant(p)) {
+            return false
+        }
+        return true
+    }
+
+    isExtensible(target: Entity): boolean {
+        return false
+    }
+
+    preventExtensions(target: Entity): boolean {
+        return true
+    }
+
+    ownKeys(target: Entity): ArrayLike<string | symbol> {
+        throw new ProxyOperationError(
+            `Cannot list all keys of a dynamic exports construct for ${this.entity}.`
+        )
+    }
+
+    set(target: Entity, p: string | symbol, newValue: any, receiver: any): boolean {
+        throw this.#createImmutableError(`set property ${String(p)} on`)
+    }
+
+    setPrototypeOf(target: Entity, v: any): boolean {
+        throw this.#createImmutableError(`set prototype of`)
+    }
+
+    _tryTargetDescriptor(p: PropertyKey) {
+        return Object.getOwnPropertyDescriptor(this.entity, p)
+    }
+
+    getOwnPropertyDescriptor(target: Entity, p: string | symbol): PropertyDescriptor | undefined {
+        const desc = this._tryTargetDescriptor(p)
+        if (desc) {
+            return desc
+        }
+        const value = this.get(this.entity, p)
+        if (value == null) {
+            return undefined
+        }
+        return {
+            configurable: false,
+            enumerable: true,
+            value,
+            writable: false
+        }
+    }
+}

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

@@ -0,0 +1,122 @@
+import type { Doddle } from "doddle"
+import type { AnyCtor } from "what-are-you"
+import type { RefKey } from "../ref-key"
+import { ProxyOperationError } from "./error"
+import type { Resource_Core_Ref } from "./refable"
+
+export type FwReference<T extends Resource_Core_Ref = Resource_Core_Ref> = FwReference_Proxied<T> &
+    T
+export function FwReference<Referenced extends Resource_Core_Ref>(
+    props: FwReference_Props<Referenced>
+): FwReference<Referenced> {
+    const core = new FwReference_Proxied(props)
+    return new Proxy(core, new FwRef_Handler(core)) as FwReference<Referenced>
+}
+export namespace FwReference {
+    export function is(obj: any): obj is FwReference {
+        return FwReference_Proxied.is(obj)
+    }
+}
+export interface FwReference_Props<Referenced extends Resource_Core_Ref> {
+    readonly class?: AnyCtor<Referenced>
+    readonly key: RefKey
+    readonly namespace?: string
+    readonly origin: object
+    readonly resolver: Doddle<Referenced>
+}
+
+class FwReference_Proxied<To extends Resource_Core_Ref> {
+    readonly #props: FwReference_Props<To>
+    constructor(props: FwReference_Props<To>) {
+        this.#props = props
+    }
+
+    static is(obj: any): obj is FwReference {
+        return obj && typeof obj === "object" && "__reference_props__" in obj
+    }
+
+    protected __pull__() {
+        return this.#props.resolver.pull()
+    }
+
+    protected __reference_props__() {
+        return this.#props
+    }
+}
+
+class FwRef_Handler<T extends Resource_Core_Ref> implements ProxyHandler<T> {
+    get _props() {
+        return this._subject["__reference_props__"]()
+    }
+    constructor(private readonly _subject: FwReference_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") {
+            return result.bind(resource)
+        }
+        return result
+    }
+    getPrototypeOf(target: T) {
+        const Resource_Top = require("../top").Resource_Top
+        return this._props.class?.prototype ?? Resource_Top.prototype
+    }
+    has(target: T, prop: PropertyKey) {
+        const { _props, _subject } = this
+        if (Reflect.has(_subject, prop)) {
+            return true
+        }
+        const resource = _props.resolver.pull() as any
+        return Reflect.has(resource, prop)
+    }
+    getOwnPropertyDescriptor(_: T, p: string | symbol): PropertyDescriptor | undefined {
+        const { _subject, _props } = this
+        const desc = Object.getOwnPropertyDescriptor(_subject, p)
+        if (desc) {
+            desc.configurable = false
+            return desc
+        }
+        const resource = _props.resolver.pull() as any
+        const resourceDesc = Object.getOwnPropertyDescriptor(resource, p)
+        return resourceDesc
+    }
+    get referant() {
+        return this._subject["__reference_props__"]().key.string
+    }
+    #createImmutableError(action: string) {
+        return new ProxyOperationError(
+            `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`)
+    }
+    deleteProperty(_: T, p: string | symbol): boolean {
+        throw this.#createImmutableError(`delete property ${String(p)} from`)
+    }
+    preventExtensions(): boolean {
+        return true
+    }
+    isExtensible(): boolean {
+        return false
+    }
+    set(_: T, p: string | symbol): boolean {
+        throw this.#createImmutableError(`set property ${String(p)} on`)
+    }
+    ownKeys(): ArrayLike<string | symbol> {
+        const pulled = this._props.resolver.pull() as any
+        return [...Reflect.ownKeys(this._subject), ...Reflect.ownKeys(pulled)]
+    }
+    setPrototypeOf(): boolean {
+        throw this.#createImmutableError(`set the prototype of`)
+    }
+}

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

@@ -0,0 +1,8 @@
+export { FwReference } from "./fw-ref"
+export { FwRef_Exports, type FwRef_Exports_Brand } from "./fw-ref-exports"
+export type {
+    Resource_Core_Ref,
+    Resource_Ctor_Of,
+    Resource_Full_Ref,
+    Resource_Min_Ref
+} from "./refable"

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

@@ -0,0 +1,24 @@
+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_Min_Ref<K extends Kind.IdentParent = Kind.IdentParent> = { kind: K }
+export type Resource_Ctor_Of<K extends Kind.IdentParent = Kind.IdentParent> = AnyCtor<
+    Resource_Core_Ref<K>
+> & {
+    prototype: Resource_Core_Ref<K>
+}
+export type Resource_Core_Ref<
+    Kind extends Kind.IdentParent = Kind.IdentParent,
+    Name extends string = string
+> = Resource_Min_Ref<Kind> & {
+    name: Name
+    equals(other: any): boolean
+    node: Resource_Node
+}
+
+export type Resource_Full_Ref<
+    _Kind extends Kind.IdentParent = Kind.IdentParent,
+    _Name extends string = string
+> = Resource_Core_Ref<_Kind, _Name> & Resource_Entity<_Name>