@k8ts/instruments 0.11.3 → 0.12.0

package/src/core/graph/{node.ts → vertex.ts}

@@ -1,16 +1,16 @@
 import { seq, type Seq } from "doddle"
-import { Entity } from "./entity"
+import { EntityBase } from "./entity"
 import { Relation } from "./relation"
-import { FwRef } from "./resource/reference/fw-ref"
+import { ForwardRef } from "./resource/forward/ref"
 /**
- * The {@link Node} is a wrapper around a {@link Entity} that provides traversal, display, and other
- * utilities. Note that the {@link Node} itself is immutable. Changes only happen to the underlying
- * {@link Entity}.
+ * The {@link Vertex} is a wrapper around a {@link EntityBase} that provides traversal, display, and
+ * other utilities. Note that the {@link Vertex} itself is immutable. Changes only happen to the
+ * underlying {@link EntityBase}.
  *
- * Two {@link Node} instances are considered equal if they wrap the same {@link Entity}, even if
+ * Two {@link Vertex} instances are considered equal if they wrap the same {@link EntityBase}, even if
  * they're different instances.
  *
- * Node classes are primarily used for traversal in the graph structure formed by {@link Entity}
+ * Node classes are primarily used for traversal in the graph structure formed by {@link EntityBase}
  * instances. They provide methods to navigate parent-child relationships, access metadata, and
  * explore dependencies between entities.
  *
@@ -19,18 +19,15 @@ import { FwRef } from "./resource/reference/fw-ref"
  *
  * Accessing the `Node` of an `Entity` always forces any `FwRef` instances to resolve.
  */
-export abstract class Node<
-    _Node extends Node<_Node, _Entity> = Node<any, any>,
-    _Entity extends Entity<_Node, _Entity> = Entity<any, any>
+export abstract class Vertex<
+    _Node extends Vertex<_Node, _Entity> = Vertex<any, any>,
+    _Entity extends EntityBase<_Node, _Entity> = EntityBase<any, any>
 > {
     /** The nodes of child entities. */
 
-    private readonly _ID: number
-    constructor(readonly entity: _Entity) {
-        this._ID = this.entity["_ID"]
-    }
+    constructor(readonly entity: _Entity) {}
     get kids() {
-        return seq(this.entity["__kids__"]()).map(x => x.assert(Entity).node as _Node)
+        return seq(this.entity["__kids__"]()).map(x => x.cast(EntityBase).__vertex__ as _Node)
     }
     /** The direct **needs** of this this node's entity. */
     get relations() {
@@ -44,7 +41,7 @@ export abstract class Node<
                         if (t) {
                             yield new Relation<_Node>(
                                 relName,
-                                t.assert(Entity<_Node, _Entity>).node
+                                t.cast(EntityBase<_Node, _Entity>).__vertex__
                             )
                         }
                     }
@@ -52,7 +49,7 @@ export abstract class Node<
                     if (target) {
                         yield new Relation<_Node>(
                             relName,
-                            target.assert(Entity<_Node, _Entity>).node
+                            target.cast(EntityBase<_Node, _Entity>).__vertex__
                         )
                     }
                 }
@@ -62,7 +59,7 @@ export abstract class Node<
 
     /** The node for this node's parent entity. */
     get parent(): _Node | null {
-        return (this.entity["__parent__"]()?.assert(Entity).node as any) ?? null
+        return (this.entity["__parent__"]?.cast(EntityBase).__vertex__ as any) ?? null
     }
 
     /**
@@ -72,9 +69,7 @@ export abstract class Node<
     get root(): _Node {
         return (this.ancestors.at(-1).pull() as any) ?? (this as any)
     }
-    get name() {
-        return this.entity.name
-    }
+
     get isRoot() {
         return this.parent === null
     }
@@ -82,18 +77,18 @@ export abstract class Node<
         if (!other) {
             return false
         }
-        if (FwRef.is(other)) {
+        if (ForwardRef.is(other)) {
             return this.equals(other["__pull__"]())
         }
-        if (other instanceof Node === false) {
+        if (other instanceof Vertex === false) {
             return false
         }
         return this.entity.equals(other.entity)
     }
 
-    readonly ancestors = seq((): Node[] => {
-        const seen = [] as Node[]
-        const recurse = function (from: Node) {
+    readonly ancestors = seq((): Vertex[] => {
+        const seen = [] as Vertex[]
+        const recurse = function (from: Vertex) {
             const parent = from.parent
             if (parent && !seen.find(x => x.equals(parent))) {
                 seen.push(parent)
@@ -104,10 +99,10 @@ export abstract class Node<
         return seen
     }).as<_Node>()
 
-    readonly descendants = seq((): Node[] => {
+    readonly descendants = seq((): Vertex[] => {
         const self = this
-        let seen = [] as Node[]
-        const recurse = function (from: Node) {
+        let seen = [] as Vertex[]
+        const recurse = function (from: Vertex) {
             for (const kid of from.kids) {
                 if (seen.find(x => x.equals(kid))) {
                     continue
@@ -120,36 +115,38 @@ export abstract class Node<
         return seen
     }).as<_Node>()
 
-    isParentOf(other: Node): boolean {
-        if (FwRef.is(other)) {
+    isParentOf(other: Vertex): boolean {
+        if (ForwardRef.is(other)) {
             return other.isChildOf(this)
         }
         return other.equals(this) || other.ancestors.some(x => x.equals(this)).pull()
     }
 
-    isChildOf(other: Node): boolean {
-        if (FwRef.is(other)) {
+    isChildOf(other: Vertex): boolean {
+        if (ForwardRef.is(other)) {
             return other.isParentOf(this)
         }
         return this.equals(other) || this.ancestors.some(x => x.equals(other)).pull()
     }
 
-    hasRelationTo(other: Node): boolean {
+    hasRelationTo(other: Vertex): boolean {
         return this.recursiveRelations.some(x => x.needed.equals(other)).pull()
     }
 
-    readonly recursiveRelationsSubtree = seq((): Seq<Relation<Node>> => {
+    readonly recursiveRelationsSubtree = seq((): Seq<Relation<Vertex>> => {
         const self = this
         return seq(function* () {
-            for (const child of [self, ...self.descendants] as Node[]) {
+            for (const child of [self, ...self.descendants] as Vertex[]) {
                 yield* child.recursiveRelations
             }
         }) as any
     }).as<Relation<_Node>>()
 
     readonly recursiveRelations = seq(() => {
-        let resources = [] as Node[]
-        const recurseIntoDependency = function* (root: Relation<Node>): Iterable<Relation<Node>> {
+        let resources = [] as Vertex[]
+        const recurseIntoDependency = function* (
+            root: Relation<Vertex>
+        ): Iterable<Relation<Vertex>> {
             yield root
             if (resources.find(r => r.equals(root.needed))) {
                 return

package/src/core/manifest/index.ts

@@ -1,12 +1,12 @@
-import { Embedder } from "../../utils/embedder"
-import { Rsc_Entity } from "../graph/resource/entity"
-export interface Manifest_Metadata {
+import { Embedder } from "../../utils/mixin/embedder"
+import { ResourceEntity } from "../graph/resource/resource"
+export interface K8tsManifest_Metadata {
     labels: Record<string, string>
     annotations: Record<string, string>
     name: string
     namespace?: string
 }
-export interface Manifest_Ident {
+export interface K8tsManifest_GVK {
     kind: string
     apiVersion: string
 }
@@ -19,20 +19,9 @@ export type JsonSerializable =
     | JsonSerializable[]
     | { [key: string]: JsonSerializable }
 
-export interface Manifest {
+export interface K8tsManifest extends K8tsManifest_GVK {
     [key: number]: never
-    apiVersion: string
-    kind: string
-    metadata: {
-        name: string
-        namespace?: string
-        labels?: Record<string, string>
-        annotations?: Record<string, string>
-    }
-}
-
-export interface SpecManifest<T extends JsonSerializable> extends Manifest {
-    spec: T
+    metadata?: K8tsManifest_Metadata
 }
 
-export const ManifestSourceEmbedder = new Embedder<object, Rsc_Entity>("ManifestSource")
+export const ManifestSourceEmbedder = new Embedder<object, ResourceEntity>("ManifestSource")

package/src/core/tracing/embedder.ts

@@ -0,0 +1,4 @@
+import { Embedder } from "../../utils/mixin/embedder"
+import { Trace_Source } from "./source"
+
+export const TraceEmbedder = new Embedder<object, Trace_Source>("TRACED")

package/src/core/tracing/git.ts

@@ -1,13 +1,13 @@
-import { Meta } from "@k8ts/metadata"
+import { Metadata } from "@k8ts/metadata"
 import dayjs from "dayjs"
 import simpleGit from "simple-git"
 
-export interface GitTraceOptions {
+export interface Trace_Git_CreateOptions {
     cwd: string
     absolute: boolean
 }
 
-export interface GitTraceProps {
+export interface Trace_Git_Props {
     commit: {
         sha: string
         message: string
@@ -15,16 +15,16 @@ export interface GitTraceProps {
         date: string
     }
 }
-export class GitTrace {
-    private constructor(readonly props: GitTraceProps) {}
+export class Trace_Git {
+    private constructor(readonly props: Trace_Git_Props) {}
 
     get metaFields() {
         const hashPart = this.props.commit.sha.slice(0, 7)
         const shortDate = dayjs(this.props.commit.date).format("YYYY-MM-DD")
-        const shortMessage = this.props.commit.message.split("\n")[0].slice(0, 20)
+        const shortMessage = this.props.commit.message.split("\n")[0].slice(0, 50)
         const author = this.props.commit.author
 
-        return Meta.make({
+        return new Metadata({
             "git.k8ts.org/": {
                 "^sha": hashPart,
                 "^message": shortMessage,
@@ -34,7 +34,7 @@ export class GitTrace {
         })
     }
 
-    static async make(options?: Partial<GitTraceOptions>) {
+    static async create(options?: Partial<Trace_Git_CreateOptions>) {
         options = {
             cwd: ".",
             absolute: false,
@@ -56,7 +56,7 @@ export class GitTrace {
         const l = await sg.log({
             maxCount: 1
         })
-        return new GitTrace({
+        return new Trace_Git({
             commit: {
                 sha: l.latest!.hash,
                 message: l.latest!.message,

package/src/core/tracing/index.ts

@@ -1,3 +1,3 @@
+export * from "./embedder"
 export * from "./git"
-export * from "./trace"
-export * from "./traced"
+export * from "./source"

package/src/core/tracing/{trace.ts → source.ts}

@@ -2,30 +2,30 @@ import { defaults } from "lodash"
 import { relative, resolve } from "path"
 import StackTracey from "stacktracey"
 
-export interface TraceFormatOptions {
+export interface Trace_Source_Options {
     cwd: string
     absolute: boolean
 }
 
-export class Trace {
+export class Trace_Source {
     readonly trace: StackTracey.Entry
     constructor(trace: StackTracey) {
         const findGoodFrame = (e: StackTracey.Entry) => {
             return !e.native && e.file && !e.file.includes("node:")
         }
+        const filtered = trace.filter(x => !!findGoodFrame(x))
         this.trace = trace.filter(x => !!findGoodFrame(x)).at(0)
     }
 
-    format(inOptions?: Partial<TraceFormatOptions>) {
+    format(inOptions?: Partial<Trace_Source_Options>) {
         const e = this.trace
         const options = defaults(inOptions, {
             cwd: ".",
             absolute: false
-        }) as TraceFormatOptions
+        }) as Trace_Source_Options
         options.cwd = resolve(options.cwd)
         const sourcePath = options.absolute ? e.file : relative(options.cwd, e.file)
-        const relativeToCwd = relative(options.cwd, sourcePath)
-        const sourceLocation = `${relativeToCwd}:${e.line}:${e.column}`
+        const sourceLocation = `${sourcePath}:${e.line}:${e.column}`
         return sourceLocation
     }
 }

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

@@ -1,39 +1,21 @@
-import { DataSource_Lazy } from "./base"
+import { doddlify } from "doddle"
+import { K8sDataSourceError } from "./error"
+import type { DataSource_Shape } from "./interface"
 
-/**
- * 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]
-            if (value === undefined) {
-                throw new Error(`Environment variable "${this.name}" is not set`)
-            }
-            return value
-        })
+class DataSource_EnvVar implements DataSource_Shape<string> {
+    constructor(public readonly name: string) {}
+
+    @doddlify
+    pull() {
+        const value = process.env[this.name]
+        if (value === undefined) {
+            throw new K8sDataSourceError(`Environment variable "${this.name}" is not set`)
+        }
+        return value
     }
 }
 
-/**
- * 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) {
+/** Reads from an environment variable in the current process. */
+export function LocalEnvVar(name: string) {
     return new DataSource_EnvVar(name)
 }

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

@@ -0,0 +1,8 @@
+export class K8sDataSourceError extends Error {
+    k8ts = true as const
+    name = "K8sDataSourceError" as const
+    constructor(message: string, fields: Record<string, any> & { cause?: Error } = {}) {
+        super(message)
+        Object.assign(this, fields)
+    }
+}

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

@@ -1,4 +1,4 @@
-export * from "./base"
 export * from "./env-var"
 export * from "./interface"
+export * from "./js-object"
 export * from "./local-file"

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

@@ -1,45 +1,31 @@
 /** Supported data source type names for type-safe data source handling. */
-export type DataSource_Type_Name = "string" | "binary"
+export type DataSource_sFormatName = "text" | "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
+ * @typeParam Name - The type name ("text" or "binary")
+ * @returns String for "text" type, Uint8Array for "binary" type
  */
-export type DataSource_Value<Name extends DataSource_Type_Name> = Name extends "string"
+export type DataSource_Value<Name extends DataSource_sFormatName> = Name extends "text"
     ? string
     : Name extends "binary"
       ? Uint8Array
-      : DataSource_Type_Name
+      : DataSource_sFormatName
 
-/**
- * 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>>
+export interface DataSource_Shape<T = any> {
+    pull(): Promise<T> | T
 }
-
+export type DataSource_Object<TypeName extends DataSource_sFormatName = DataSource_sFormatName> =
+    DataSource_Shape<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> =
+export type DataSource<Only extends DataSource_sFormatName = DataSource_sFormatName> =
     | DataSource_Object<Only>
     | DataSource_Value<Only>
+
+export function isDataSource(obj: any): obj is DataSource_Shape {
+    return obj && typeof obj.pull === "function"
+}

package/src/expressions/data-sources/js-object.ts

@@ -0,0 +1,39 @@
+import { doddlify } from "doddle"
+import yaml from "js-yaml"
+import type { DataSource_Shape } from "./interface"
+export type DataSource_JsObject_sFormatName = "json" | "yaml"
+export interface DataSource_JsObject {
+    to(format: DataSource_JsObject_sFormatName): DataSource_Shape<string>
+}
+
+class _DataSource_JsObject implements DataSource_JsObject {
+    constructor(private readonly _obj: any) {}
+
+    to(format: DataSource_JsObject_sFormatName): DataSource_Shape<string> {
+        if (format === "json") {
+            return new _DataSource_JsObject_Json(this._obj)
+        } else {
+            return new _DataSource_JsObject_Yaml(this._obj)
+        }
+    }
+}
+
+class _DataSource_JsObject_Json implements DataSource_Shape<string> {
+    constructor(private readonly _obj: any) {}
+    @doddlify
+    pull() {
+        return JSON.stringify(this._obj, null, 2)
+    }
+}
+
+class _DataSource_JsObject_Yaml implements DataSource_Shape<string> {
+    constructor(private readonly _obj: any) {}
+    @doddlify
+    pull() {
+        return yaml.dump(this._obj)
+    }
+}
+
+export function LocalObject(obj: object): DataSource_JsObject {
+    return new _DataSource_JsObject(obj)
+}

package/src/expressions/data-sources/local-file.ts

@@ -1,6 +1,8 @@
+import { doddlify } from "doddle"
 import Path from "pathlib-js"
 import StackTracey from "stacktracey"
-import { DataSource_Lazy } from "./base"
+import { display } from "../../utils/mixin/display"
+import type { DataSource_sFormatName, DataSource_Shape } from "./interface"
 
 /** Union type of allowed data source value types. */
 export type DataSource_Allowed = string | Uint8Array
@@ -9,22 +11,7 @@ export type DataSource_Allowed = string | Uint8Array
  * Represents a local file path that can be read as text or binary data. Can be used instead of a
  * primitive in some cases when building Kubernetes manifests.
  */
-class DataSource_LocalFile_Path {
-    readonly path: Path
-
-    /**
-     * Creates a local file path data source.
-     *
-     * @param _cwd - The current working directory
-     * @param relPath - Relative path to the file
-     */
-    constructor(
-        private readonly _cwd: Path,
-        relPath: string
-    ) {
-        this.path = this._cwd.join(relPath)
-    }
-
+export interface DataSource_FromLocalFile {
     /**
      * Creates a lazy data source that reads the file as text.
      *
@@ -32,7 +19,7 @@ class DataSource_LocalFile_Path {
      * @param encoding - Optional text encoding (default: "utf-8")
      * @returns Lazy data source for text content
      */
-    as(mode: "text", encoding?: BufferEncoding): DataSource_Lazy<string>
+    as(mode: "text", encoding?: BufferEncoding): DataSource_Shape<string>
 
     /**
      * Creates a lazy data source that reads the file as binary data.
@@ -40,66 +27,73 @@ class DataSource_LocalFile_Path {
      * @param mode - Must be "binary"
      * @returns Lazy data source for binary content
      */
-    as(mode: "binary"): DataSource_Lazy<Uint8Array>
+    as(mode: "binary"): DataSource_Shape<Uint8Array>
+}
+
+@display({
+    simple(self) {
+        return `LocalFile(${self.path})`
+    }
+})
+class _DataSource_LocalFile_Path implements DataSource_FromLocalFile {
+    readonly path: Path
+
+    constructor(
+        private readonly _cwd: Path,
+        relPath: string
+    ) {
+        this.path = this._cwd.join(relPath)
+    }
 
-    as(mode: "text" | "binary", encoding?: BufferEncoding): DataSource_Lazy {
+    as(mode: DataSource_sFormatName, encoding?: BufferEncoding): DataSource_Shape {
         if (mode === "text") {
-            return new DataSource_LocalFile_Text(this, encoding)
+            return new _DataSource_LocalFile_Text(this, encoding)
         } else {
-            return new DataSource_LocalFile_Binary(this)
+            return new _DataSource_LocalFile_Binary(this)
         }
     }
 }
 
-/** Data source for reading local files as text with specified encoding. */
-class DataSource_LocalFile_Text extends DataSource_Lazy<string> {
-    /**
-     * Creates a text file data source.
-     *
-     * @param _parent - Parent path object
-     * @param encoding - Text encoding (default: "utf-8")
-     */
+@display({
+    simple(self) {
+        return `LocalFileText(${self._parent.path}, ${self.encoding})`
+    }
+})
+class _DataSource_LocalFile_Text implements DataSource_Shape<string> {
     constructor(
-        private readonly _parent: DataSource_LocalFile_Path,
+        private readonly _parent: _DataSource_LocalFile_Path,
         readonly encoding: BufferEncoding = "utf-8"
-    ) {
-        super(async () => {
-            return this._parent.path.readFile(this.encoding)
-        })
+    ) {}
+
+    @doddlify
+    pull() {
+        return this._parent.path.readFile(this.encoding)
     }
 }
 
-/** Data source for reading local files as binary (Uint8Array). */
-class DataSource_LocalFile_Binary extends DataSource_Lazy<Uint8Array> {
-    /**
-     * Creates a binary file data source.
-     *
-     * @param _parent - Parent path object
-     */
-    constructor(private readonly _parent: DataSource_LocalFile_Path) {
-        super(async () => {
-            const x = await this._parent.path.readFile()
-            return new Uint8Array(x)
-        })
+@display({
+    simple(self) {
+        return `LocalFileBinary(${self._parent.path})`
+    }
+})
+class _DataSource_LocalFile_Binary implements DataSource_Shape<Uint8Array> {
+    constructor(private readonly _parent: _DataSource_LocalFile_Path) {}
+
+    @doddlify
+    pull() {
+        return this._parent.path.readFile().then(buf => new Uint8Array(buf))
     }
 }
 
 /**
- * Creates a file path reference relative to the caller's file location. You must call `.as("text")`
- * or `.as("binary")` on the returned object to get a data source.
- *
- * Can be used instead of a primitive in some cases when building Kubernetes manifests.
- *
- * @example
- *     // In /project/src/config.ts:
- *     const data = localRefFile("../data/config.json").as("text")
- *     const content = await data.get() // Reads /project/data/config.json
- *
- * @param path - Relative path to the file from the caller's directory
- * @returns File path object that can be read as text or binary
+ * Creates a file path reference relative to the caller's file location. You must call
+ * `.as("string")` or `.as("binary")` on the returned object to get a data source.
  */
-export function localRefFile(path: string) {
+export function LocalFile(path: string) {
     const trace = new StackTracey().slice(1)
     const callerFile = trace.at(0).file
-    return new DataSource_LocalFile_Path(new Path(callerFile).parent(), path)
+    return new _DataSource_LocalFile_Path(
+        new Path(callerFile).parent(),
+        path
+    ) as DataSource_FromLocalFile
 }

package/src/expressions/network/error.ts

@@ -0,0 +1,7 @@
+export class K8tsNetworkError extends Error {
+    name = "K8tsNetworkError"
+    constructor(message: string, fields: Record<string, any> & { cause?: Error } = {}) {
+        super(message)
+        Object.assign(this, fields)
+    }
+}

package/src/expressions/network/index.ts

@@ -1 +1,5 @@
-export * from "./ports"
+export * from "./ip/ip4"
+export * from "./ip/subnet4"
+export * from "./ports/mapping"
+export * from "./ports/provider"
+export * from "./ports/types"