@k8ts/instruments 0.6.0 → 0.6.2

package/src/core/graph/origin/kind-map/index.ts

@@ -0,0 +1,171 @@
+import { doddlify, seq, type Seq } from "doddle"
+import type { AnyCtor } from "what-are-you"
+import { InstrumentsError } from "../../../../error"
+
+import type { Resource_Ctor_Of } from "../../resource"
+import { Kind } from "../../resource/api-kind"
+import { RefKey } from "../../resource/ref-key"
+const separator = "/"
+interface NodeEntry {
+    kindName: string
+    class: AnyCtor<any>
+    ident: Kind.IdentParent
+}
+export type KindMapInput<Ks extends Resource_Ctor_Of> = Ks[]
+type LookupKey = string | RefKey | AnyCtor<any> | Kind.IdentParent
+export class KindMap<Kinds extends Resource_Ctor_Of = Resource_Ctor_Of> {
+    __KINDS__!: Kinds["prototype"]["kind"]
+    constructor(private _ownKinds: KindMapInput<Kinds>) {}
+
+    [Symbol.iterator]() {
+        return this._ownKinds[Symbol.iterator]()
+    }
+    child<Ks extends Resource_Ctor_Of = Resource_Ctor_Of>(
+        kinds: KindMapInput<Ks> | KindMap<Ks>
+    ): KindMap<Kinds | Ks> {
+        const ownKinds = kinds instanceof KindMap ? kinds._ownKinds : kinds
+        return new KindMap<Kinds | Ks>([...this._ownKinds, ...ownKinds])
+    }
+
+    @doddlify
+    private get _entriesSeq(): Seq<NodeEntry> {
+        return seq(this._ownKinds).map(klass => {
+            const kind = klass.prototype.kind
+            const entry: NodeEntry = {
+                kindName: kind.name,
+                class: klass,
+                ident: kind
+            }
+            return entry
+        })
+    }
+    @doddlify
+    private get _entriesMap(): Map<LookupKey, NodeEntry> {
+        return seq(this._entriesSeq)
+            .flatMap(entry => {
+                return [
+                    [entry.kindName, entry],
+                    [entry.class, entry],
+                    [entry.ident.text, entry]
+                ] as const
+            })
+            .toMap(x => x)
+            .pull()
+    }
+
+    refKey<Kind extends Kind.IdentParent, Name extends string>(
+        kind: Kind,
+        name: Name
+    ): RefKey<Kind, Name> {
+        const trueKind = this.getKind(kind)
+        return new RefKey(trueKind, name) as any
+    }
+
+    parse(ref: string | RefKey<this["__KINDS__"]>): RefKey<this["__KINDS__"]> {
+        const result = this.tryParse(ref)
+        if (!result) {
+            throw new InstrumentsError(`Could not parse reference key: ${ref}`)
+        }
+        return result as any
+    }
+
+    tryParse(ref: unknown): RefKey<this["__KINDS__"]> | undefined {
+        if (typeof ref !== "string" && typeof ref !== "object") {
+            return undefined
+        }
+        if (ref == null) {
+            return undefined
+        }
+        if (ref instanceof RefKey) {
+            return ref
+        }
+        if (typeof ref === "object") {
+            return undefined
+        }
+        const [kind, name] = ref.split(separator).map(s => s.trim())
+        if (!kind || !name) {
+            return undefined
+        }
+        const ident = this.tryGetKind(kind)
+        if (!ident) {
+            return undefined
+        }
+        return this.refKey(ident, name)
+    }
+
+    get kinds(): Set<string> {
+        return this._entriesSeq
+            .map(x => x.kindName)
+            .toSet()
+            .pull()
+    }
+
+    private _unknownNameError(kind: string) {
+        return new InstrumentsError(`The shorthand name ${kind} is not registered`)
+    }
+    private _unknownIdentError(ident: Kind.Identifier) {
+        return new InstrumentsError(`The kind identifier ${ident} is not registered`)
+    }
+    private _unknownClassError(klass: Function) {
+        return new InstrumentsError(`The class ${klass.name} is not registered`)
+    }
+    private _convert(something: LookupKey | RefKey | Function | Kind.IdentParent) {
+        if (typeof something === "string") {
+            if (something.includes("/")) {
+                return this.parse(something).kind
+            }
+            return something
+        } else if (typeof something === "function") {
+            return something as AnyCtor<any>
+        } else if (something instanceof Kind.Identifier) {
+            return something.text
+        } else if (something instanceof RefKey) {
+            return something.kind.text
+        }
+        throw new InstrumentsError(`Invalid argument ${something}`)
+    }
+    private _getEntry(key: LookupKey) {
+        const entry = this._tryGetEntry(key)
+        if (!entry) {
+            if (typeof key === "string") {
+                throw this._unknownNameError(key)
+            } else if (key instanceof Kind.Identifier) {
+                throw this._unknownIdentError(key)
+            } else if (typeof key === "function") {
+                throw this._unknownClassError(key)
+            }
+        }
+        return entry!
+    }
+    private _tryGetEntry(key: LookupKey): NodeEntry | undefined {
+        const converted = this._convert(key)
+        return this._entriesMap.get(converted)
+    }
+
+    tryGetKind(kindOrIdent: LookupKey): any {
+        return this._tryGetEntry(kindOrIdent)?.ident as Kinds | undefined
+    }
+
+    getKind(kindOrClass: LookupKey): this["__KINDS__"] {
+        return this._getEntry(kindOrClass).ident
+    }
+
+    tryGetClass(kindOrIdent: LookupKey): AnyCtor<any> | undefined {
+        return this._tryGetEntry(kindOrIdent)?.class
+    }
+
+    getClass(refKey: RefKey): AnyCtor<any>
+    getClass<F extends AnyCtor<any>>(klass: F): F
+    getClass(kind: string): AnyCtor<any>
+    getClass(ident: Kind.IdentParent): AnyCtor<any>
+    getClass<T extends AnyCtor<any> | string>(
+        kindOrClass: T
+    ): T extends AnyCtor<any> ? string : AnyCtor<any>
+    getClass(kindOrClass: LookupKey): AnyCtor<any> | string {
+        return this._getEntry(kindOrClass).class
+    }
+
+    has(kindOrClass: LookupKey): boolean {
+        return this._entriesMap.has(kindOrClass as any)
+    }
+}

package/src/core/graph/origin/node.ts

@@ -0,0 +1,75 @@
+import { Meta } from "@k8ts/metadata"
+import chalk from "chalk"
+import { seq, Seq } from "doddle"
+import { displayers } from "../../../utils/displayers"
+import { Node } from "../node"
+import type { Resource_Core_Ref, Resource_Ctor_Of } from "../resource"
+import type { Origin_Entity } from "./entity"
+import { type KindMapInput } from "./kind-map"
+
+@displayers({
+    simple: s => `[${s.shortFqn}]`,
+    prefix: s => {
+        return ""
+    },
+    pretty(origin, format) {
+        const kindName = chalk.greenBright.bold(origin.kind)
+        const resourceName = chalk.cyan(origin.name)
+        const pref = this.prefix!()
+
+        return chalk.underline(`${pref}${kindName}:${resourceName}`)
+    }
+})
+export class OriginNode extends Node<OriginNode, Origin_Entity> {
+    get kids() {
+        return seq(this.entity["__kids__"]()).map(x => x.node)
+    }
+    get meta() {
+        return this.entity.meta
+    }
+    get kind() {
+        return this.entity.kind
+    }
+    get shortFqn() {
+        return `${this.kind}/${this.name}`
+    }
+    get inheritedMeta(): Meta {
+        const self = this
+        return [this, ...this.ancestors]
+            .map(x => x.meta.clone())
+            .reduce((acc, meta) => acc.add(meta), Meta.make())
+    }
+    constructor(entity: Origin_Entity) {
+        super(entity)
+    }
+
+    get resourceKinds() {
+        return this.entity["__resource_kinds__"]()
+    }
+
+    get relations() {
+        return seq([])
+    }
+
+    get resources() {
+        return this.entity.resources
+    }
+    readonly attachedTree: Seq<Resource_Core_Ref> = seq(() => {
+        const self = this
+        const desc = self.descendants
+            .concatTo([this])
+            .map(x => x)
+            .concatMap(function* (x) {
+                yield* self.resources
+                for (const kid of self.kids) {
+                    yield* kid.resources
+                }
+            })
+        return desc
+    }).cache()
+}
+
+export interface Origin_Props<KindedCtors extends Resource_Ctor_Of = Resource_Ctor_Of> {
+    meta?: Meta.Input
+    kinds?: KindMapInput<KindedCtors>
+}

package/src/core/graph/origin/origin-events.ts

@@ -0,0 +1,86 @@
+import { doddle } from "doddle"
+import EventEmitter from "eventemitter3"
+import type { Manifest } from "../../manifest"
+import type { Resource_Entity, Resource_Top } from "../resource"
+import type { Origin_Entity } from "./entity"
+
+export function OriginEventsEmitter() {
+    const em = new EventEmitter<Origin_EventMap>()
+    return em
+}
+
+export function SubscribeFn(self: Origin_Entity, em: EventEmitter<Origin_EventMap>) {
+    function on<EventKey extends keyof Origin_EventMap>(
+        event: EventKey,
+        listener: (data: Origin_EventMap[EventKey]) => void
+    ): void
+    function on(
+        listener: <EventKey extends keyof Origin_EventMap>(
+            event: EventKey,
+            data: Origin_EventMap[EventKey]
+        ) => void
+    ): void
+    function on<
+        K extends keyof Origin_EventMap,
+        HandledMap extends {
+            [key2 in K]: (data: Origin_EventMap[key2]) => void
+        }
+    >(handlers: HandledMap): void
+    function on(a?: any, b?: any) {
+        if (typeof a === "function") {
+            for (const eventName of originEventNames) {
+                em.on(eventName as any, (data: any) => a(eventName as any, data))
+            }
+        } else if (typeof a === "string") {
+            return em.on(a as any, b)
+        } else if (typeof a === "object") {
+            const handlers = a as any
+            for (const key of Object.keys(handlers) as (keyof Origin_EventMap)[]) {
+                em.on(key, handlers[key]!)
+            }
+        }
+    }
+    return on
+}
+export interface Origin_EventMap {
+    "resource/exported": {
+        readonly origin: Origin_Entity
+        readonly resource: Resource_Top
+    }
+    "resource/attached": {
+        readonly origin: Origin_Entity
+        readonly resource: Resource_Entity
+    }
+    "resource/manifested": {
+        readonly origin: Origin_Entity
+        readonly manifest: Manifest
+        readonly resource: Resource_Top
+    }
+    "resource/loaded": {
+        readonly origin: Origin_Entity
+        readonly resource: Resource_Top
+    }
+    "resource/serialized": {
+        readonly origin: Origin_Entity
+        readonly resource: Resource_Top
+        readonly manifest: Manifest
+        content: string
+    }
+    "origin/attached": {
+        readonly origin: Origin_Entity
+        readonly child: Origin_Entity
+    }
+}
+
+export const originEventNames = doddle(() => {
+    // Forces type checking the event names basded on the Origin_EventMap
+    const obj = {
+        "resource/exported": true,
+        "resource/attached": true,
+        "resource/manifested": true,
+        "resource/loaded": true,
+        "resource/serialized": true,
+        "origin/attached": true
+    } satisfies Record<keyof Origin_EventMap, true>
+    return Object.keys(obj) as (keyof Origin_EventMap)[]
+}).pull()

package/src/core/graph/origin/tracker.ts

@@ -0,0 +1,103 @@
+import { AsyncLocalStorage } from "async_hooks"
+import { doddle, pull, type Doddle, type MaybeDoddle } from "doddle"
+import { isIterable } from "what-are-you"
+import type { Origin_Entity } from "./entity"
+
+export interface OriginStackBinder {
+    run<T>(callback: () => T): T
+    bind<F extends (...args: any[]) => any>(fn: F): F
+}
+
+export class _OriginContextTracker {
+    private readonly _store: AsyncLocalStorage<Origin_Entity | undefined>
+    constructor() {
+        this._store = new AsyncLocalStorage<Origin_Entity | undefined>()
+    }
+
+    get current(): Origin_Entity | undefined {
+        return this._store.getStore()
+    }
+
+    disposableOriginModifier(origin: Origin_Entity): Disposable {
+        const curOrigin = this._store.getStore()
+        this._store.enterWith(origin)
+        return {
+            [Symbol.dispose]: () => {
+                this._store.enterWith(curOrigin)
+            }
+        }
+    }
+
+    binder(origin: MaybeDoddle<Origin_Entity>): OriginStackBinder {
+        const runner = this
+        return {
+            run<T>(callback: () => T): T {
+                const orig = doddle.is(origin) ? origin.pull() : origin
+                return runner._run(orig, callback)
+            },
+            bind<F extends (...args: any[]) => any>(fn: F): F {
+                const boundOrigin = origin
+                return runner._bind(boundOrigin as Doddle<Origin_Entity>, fn)
+            }
+        }
+    }
+
+    private _run<T>(origin: Origin_Entity, callback: () => T): T {
+        return this._store.run(origin, callback)
+    }
+
+    private _bindIterator(
+        boundOrigin: Doddle<Origin_Entity> | Origin_Entity,
+        iterator: Iterator<any>
+    ): Iterator<any> {
+        const runner = this
+        return {
+            next() {
+                const origin = doddle.is(boundOrigin) ? boundOrigin.pull() : boundOrigin
+                return runner._run(origin, () => iterator.next())
+            },
+            return(value?: any) {
+                if (iterator.return) {
+                    return iterator.return(value)
+                }
+                return {
+                    done: true,
+                    value
+                }
+            },
+            throw(err?: any) {
+                if (iterator.throw) {
+                    return iterator.throw(err)
+                }
+                throw err
+            }
+        }
+    }
+
+    private _bindIterable<It extends Iterable<any>>(
+        boundOrigin: Doddle<Origin_Entity> | Origin_Entity,
+        iterable: It
+    ) {
+        const iterator = iterable[Symbol.iterator]()
+        const runner = this
+        const boundIterator: Iterable<any> = {
+            [Symbol.iterator]() {
+                return runner._bindIterator(boundOrigin, iterator)
+            }
+        }
+        return boundIterator
+    }
+
+    private _bind<F extends (...args: any[]) => any>(origin: Doddle<Origin_Entity>, fn: F): F {
+        const self = this
+        return function boundRunFunction(this: any, ...args: any[]) {
+            const result = self._run(pull(origin), () => fn.apply(this, args))
+            if (isIterable(result)) {
+                return self._bindIterable(origin, result)
+            }
+            return result
+        } as F
+    }
+}
+
+export const OriginContextTracker = new _OriginContextTracker()

package/src/core/graph/relation.ts

@@ -0,0 +1,17 @@
+import { pretty } from "../../utils/_string"
+import { displayers } from "../../utils/displayers"
+import type { Node } from "./node"
+
+@displayers({
+    simple: s => [s.why, "-->", s.needed],
+    pretty: (dep, format) => {
+        const neededFmt = pretty`${["lowkey", dep.needed]}`
+        return [dep.why, neededFmt].join("➜ ")
+    }
+})
+export class Relation<_Node extends Node<_Node>> {
+    constructor(
+        readonly why: string,
+        readonly needed: _Node
+    ) {}
+}

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

@@ -0,0 +1,176 @@
+import { InstrumentsError } from "../../../../error"
+import { bind_own_methods } from "../../../../utils"
+import { displayers } from "../../../../utils/displayers"
+import { RefKey } from "../ref-key"
+import { pluralize } from "./pluralize"
+
+export type Kind<
+    GroupName extends string = string,
+    Version extends string = string,
+    Name extends string = string
+> = Kind.Kind<GroupName, Version, Name>
+export namespace Kind {
+    export interface IdentParent {
+        text: string
+        name: string
+        dns: string
+        parent: IdentParent | null
+        equals(other: any): boolean
+    }
+    type _alphabeta = "alpha" | "beta" | ""
+    type _subversion = `${_alphabeta}${number}` | ""
+    type _version = `v${number}${_subversion | ""}`
+    @displayers({
+        simple: self => self.text
+    })
+    @bind_own_methods()
+    export abstract class Identifier<
+        Name extends string = string,
+        Parent extends IdentParent | null = IdentParent | null
+    > implements IdentParent
+    {
+        constructor(
+            readonly name: Name,
+            readonly parent: Parent
+        ) {}
+
+        get full(): IdentParent[] {
+            const parts: IdentParent[] = []
+            let curr: IdentParent | null = this
+            while (curr) {
+                parts.unshift(curr)
+                curr = curr.parent
+            }
+            return parts.filter(x => x.name)
+        }
+
+        get text(): string {
+            return this.full.map(p => p.name).join("/") as any
+        }
+
+        get dns(): string {
+            return this.full
+                .map(x => x.name)
+                .filter(Boolean)
+                .join(".")
+        }
+
+        abstract child(name: string): Identifier<
+            string,
+            {
+                name: Name
+            } & IdentParent
+        >
+
+        equals(other: any) {
+            if (typeof other !== "object" || !other) {
+                return false
+            }
+            if (!(other instanceof Identifier)) {
+                return false
+            }
+            return this.text === other.text
+        }
+    }
+    @bind_own_methods()
+    export class Group<const _Group extends string = string> extends Identifier<_Group, null> {
+        constructor(override name: _Group) {
+            super(name, null)
+        }
+        version<Version extends _version>(apiVersion: Version) {
+            return new Version(apiVersion, this)
+        }
+
+        child(name: string): Version<_Group, string> {
+            if (!name.startsWith("v")) {
+                throw new InstrumentsError(
+                    `Invalid version name "${name}". Version name must start with "v".`
+                )
+            }
+            return this.version(name as any) as any
+        }
+    }
+    @bind_own_methods()
+    export class Version<
+        const _Group extends string = string,
+        const _Version extends string = string
+    > extends Identifier<_Version, Kind.Group<_Group>> {
+        kind<_Kind extends string>(kind: _Kind) {
+            return new Kind(kind, this as Version<_Group, _Version>)
+        }
+
+        __FORMAT__!: _Version
+
+        get group() {
+            return this.parent
+        }
+
+        child(name: string): Kind<_Group, _Version, string> {
+            return this.kind(name)
+        }
+    }
+    @bind_own_methods()
+    export class Kind<
+        const _Group extends string = string,
+        const _Version extends string = string,
+        const _Kind extends string = string
+    > extends Identifier<_Kind, Version<_Group, _Version>> {
+        constructor(name: _Kind, parent: Version<_Group, _Version>) {
+            super(name, parent)
+        }
+
+        refKey<Name extends string>(name: Name) {
+            return new RefKey<this, Name>(this as any, name)
+        }
+
+        get plural() {
+            return pluralize(this.name.toLowerCase())
+        }
+        get version() {
+            return this.parent
+        }
+
+        get group() {
+            return this.parent.parent
+        }
+
+        subkind<SubKind extends string>(subkind: SubKind) {
+            return new SubKind(subkind, this)
+        }
+
+        child<Name extends string>(name: Name): SubKind<Name, this> {
+            return this.subkind(name)
+        }
+    }
+
+    @bind_own_methods()
+    export class SubKind<
+        Name extends string = string,
+        Parent extends IdentParent = IdentParent
+    > extends Identifier<Name, Parent> {
+        constructor(name: Name, parent: Parent) {
+            super(name, parent)
+        }
+        subkind<_SubKind2 extends string>(subkind: _SubKind2): SubKind<_SubKind2, this> {
+            return new SubKind(subkind, this)
+        }
+
+        child<Name extends string>(name: Name) {
+            return this.subkind(name)
+        }
+    }
+
+    export function group<ApiGroup extends string>(apiGroup: ApiGroup) {
+        return new Group(apiGroup)
+    }
+
+    export function version<ApiVersion extends _version>(apiVersion: ApiVersion) {
+        return new Version(apiVersion, group(""))
+    }
+}
+export function kinded(kind: Kind.Identifier) {
+    return <T extends abstract new (...args: any[]) => object>(ctor: T) => {
+        ctor.prototype.kind = kind
+        return ctor
+    }
+}

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
+    }
+}