@k8ts/instruments 0.9.3 → 0.11.0

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

@@ -1,10 +1,23 @@
 import Path from "pathlib-js"
 import StackTracey from "stacktracey"
-import type { TypedArray } from "what-are-you"
 import { DataSource_Lazy } from "./base"
-export type DataSource_Allowed = string | Uint8Array | TypedArray
-export class DataSource_LocalFile_Path {
+
+/** Union type of allowed data source value types. */
+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
@@ -12,8 +25,23 @@ export class DataSource_LocalFile_Path {
         this.path = this._cwd.join(relPath)
     }
 
+    /**
+     * Creates a lazy data source that reads the file as text.
+     *
+     * @param mode - Must be "text"
+     * @param encoding - Optional text encoding (default: "utf-8")
+     * @returns Lazy data source for text content
+     */
     as(mode: "text", encoding?: BufferEncoding): DataSource_Lazy<string>
+
+    /**
+     * Creates a lazy data source that reads the file as binary data.
+     *
+     * @param mode - Must be "binary"
+     * @returns Lazy data source for binary content
+     */
     as(mode: "binary"): DataSource_Lazy<Uint8Array>
+
     as(mode: "text" | "binary", encoding?: BufferEncoding): DataSource_Lazy {
         if (mode === "text") {
             return new DataSource_LocalFile_Text(this, encoding)
@@ -22,7 +50,15 @@ export class DataSource_LocalFile_Path {
         }
     }
 }
+
+/** 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")
+     */
     constructor(
         private readonly _parent: DataSource_LocalFile_Path,
         readonly encoding: BufferEncoding = "utf-8"
@@ -33,7 +69,13 @@ class DataSource_LocalFile_Text extends DataSource_Lazy<string> {
     }
 }
 
+/** 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()
@@ -42,6 +84,20 @@ class DataSource_LocalFile_Binary extends DataSource_Lazy<Uint8Array> {
     }
 }
 
+/**
+ * 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
+ */
 export function localRefFile(path: string) {
     const trace = new StackTracey().slice(1)
     const callerFile = trace.at(0).file

package/src/expressions/network/ports/index.ts

@@ -1,8 +1,8 @@
-import { PortSet } from "./set"
-import type { InputPortSetRecord } from "./types"
-export { PortMap } from "./map"
-export { PortSet } from "./set"
-export type { InputPortMapping, InputPortSetRecord, PortMapEntry, PortSetEntry } from "./types"
-export function ports<Names extends string>(input: InputPortSetRecord<Names>): PortSet<Names> {
-    return PortSet.make(input)
+import type { Port_Exports_Input } from "./set"
+import { Port_Exports } from "./set"
+export { Port_Map, type PortMapping_Input } from "./map"
+export { Port_Exports, type Port_Exports_Input } from "./set"
+export type { Port_Full, Port_Mapping_Entry } from "./types"
+export function ports<Names extends string>(input: Port_Exports_Input<Names>): Port_Exports<Names> {
+    return Port_Exports.make(input)
 }

package/src/expressions/network/ports/map.ts

@@ -1,23 +1,47 @@
 import { filterMap, mapValues } from "@k8ts/metadata/util"
 import { PortError } from "./error"
-import type { PortMapEntry } from "./types"
-export class PortMap<Names extends string> {
-    constructor(private readonly _map: Map<string, PortMapEntry>) {}
+import type { Port_Mapping_Entry } from "./types"
 
-    private _apply(f: (map: Map<string, PortMapEntry>) => Map<string, PortMapEntry>): PortMap<any> {
-        return new PortMap(f(this._map))
+/**
+ * Represents an immutable mapping of named ports to their frontend/backend configuration.
+ *
+ * Used to define how container ports are exposed through services, mapping backend container ports
+ * to frontend service ports.
+ *
+ * @template Names The union type of all port names in the map.
+ */
+export class Port_Map<Names extends string> {
+    constructor(private readonly _map: Map<string, Port_Mapping_Entry>) {}
+
+    private _apply(
+        f: (map: Map<string, Port_Mapping_Entry>) => Map<string, Port_Mapping_Entry>
+    ): Port_Map<any> {
+        return new Port_Map(f(this._map))
     }
 
-    pick<InNames extends Names>(...name: InNames[]): PortMap<InNames> {
+    /**
+     * Creates a new Port_Map containing only the specified port names.
+     *
+     * @param name The port names to include in the new map.
+     * @returns A new Port_Map with only the selected ports.
+     */
+    pick<InNames extends Names>(...name: InNames[]): Port_Map<InNames> {
         return this._apply(map => filterMap(map, (_, key) => name.includes(key as InNames)))
     }
 
+    /** The underlying map of port names to their mapping entries. */
     get values() {
         return this._map
     }
 
-    map(mapping: Record<Names, number>): PortMap<Names> {
-        return new PortMap(
+    /**
+     * Remaps the frontend ports to new values.
+     *
+     * @param mapping A record mapping port names to their new frontend port numbers.
+     * @returns A new Port_Map with updated frontend ports.
+     */
+    map(mapping: Record<Names, number>): Port_Map<Names> {
+        return new Port_Map(
             mapValues(this._map, entry => {
                 return {
                     ...entry,
@@ -27,14 +51,38 @@ export class PortMap<Names extends string> {
         )
     }
 
-    get(name: Names): PortMapEntry {
+    /**
+     * Retrieves a port mapping entry by name.
+     *
+     * @param name The name of the port to retrieve.
+     * @returns The port mapping entry.
+     * @throws {PortError} If the port name is not found in the map.
+     */
+    get(name: Names): Port_Mapping_Entry {
         if (!this._map.has(name)) {
             throw new PortError(`Port ${name} not found`)
         }
-        return this._map.get(name) as PortMapEntry
+        return this._map.get(name) as Port_Mapping_Entry
     }
 
+    /** Converts this Port_Map to a standard Map. */
     toMap() {
         return this._map
     }
 }
+
+/**
+ * Input type for creating port mappings.
+ *
+ * Each port name maps to either:
+ *
+ * - A number specifying the frontend port
+ * - `true` to use the same port number as the backend
+ *
+ * @template Names The union type of port names.
+ */
+export type PortMapping_Input<Names extends string = string> = [Names] extends [never]
+    ? never
+    : {
+          [K in Names]: number | true
+      }

package/src/expressions/network/ports/set.ts

@@ -2,39 +2,70 @@ import { Meta } from "@k8ts/metadata"
 import { filterMap, mapValues, merge } from "@k8ts/metadata/util"
 import { seq } from "doddle"
 import { PortError } from "./error"
-import { PortMap } from "./map"
+import { Port_Map, PortMapping_Input } from "./map"
 import { parsePortInput, portRecordInput } from "./tools/entry"
 import type {
-    InputPort,
-    InputPortMapping,
-    InputPortSetEntry,
-    InputPortSetRecord,
-    InputProtocol,
-    PortSetEntry
+    Port_Basic_Input,
+    Port_Full,
+    Port_Full_Input,
+    Port_Input,
+    Port_Protocol_Input
 } from "./types"
 
-declare const __NAMES__: unique symbol
-export class PortSet<Names extends string = never> {
-    constructor(private readonly _map: Map<Names, PortSetEntry> = new Map()) {
+/**
+ * An immutable dictionary of named network ports exported by a container. Each port also has an
+ * attached configuration.
+ *
+ * @template Names All exported port names.
+ */
+export class Port_Exports<Names extends string = never> {
+    constructor(private readonly _map: Map<Names, Port_Full> = new Map()) {
         for (const entry of _map.values()) {
             Meta._checkNameValue(`container port '${entry.name}' (${entry.port})`, entry.name)
         }
     }
 
-    private _apply(f: (map: Map<string, PortSetEntry>) => Map<string, PortSetEntry>) {
-        return new PortSet(f(this._map))
+    private _apply(f: (map: Map<string, Port_Full>) => Map<string, Port_Full>) {
+        return new Port_Exports(f(this._map))
     }
 
-    union<InNames extends string>(other: PortSet<InNames>): PortSet<Names | InNames> {
-        return new PortSet(merge(this._map, other._map))
+    /**
+     * Creates a new Port_Exports that is the union of this and another Port_Exports.
+     *
+     * @param other The other Port_Exports to merge with.
+     * @returns A new Port_Exports containing ports from both dictionaries. The 2nd dictionary's
+     *   ports will overwrite any with the same name from the first.
+     */
+    union<InNames extends string>(other: Port_Exports<InNames>): Port_Exports<Names | InNames> {
+        return new Port_Exports(merge(this._map, other._map))
     }
+
+    /**
+     * Adds a port with explicit name, port number, and protocol.
+     *
+     * @param name The unique name for the port.
+     * @param port The port number.
+     * @param protocol The protocol (TCP or UDP).
+     */
     add<Name extends string>(
         name: Name,
-        port: InputPort,
-        protocol: InputProtocol
-    ): PortSet<Names | Name>
-    add<Name extends string>(name: Name, entry: InputPortSetEntry): PortSet<Names | Name>
-    add<InNames extends string>(input?: InputPortSetRecord<InNames>): PortSet<Names | InNames>
+        port: Port_Basic_Input,
+        protocol: Port_Protocol_Input
+    ): Port_Exports<Names | Name>
+    /**
+     * Adds a port with a name and full port configuration.
+     *
+     * @param name The unique name for the port.
+     * @param entry The port configuration including number and protocol, and optional host
+     *   settings.
+     */
+    add<Name extends string>(name: Name, entry: Port_Full_Input): Port_Exports<Names | Name>
+    /**
+     * Adds multiple ports from a record of port configurations.
+     *
+     * @param input A record mapping port names to their configurations.
+     */
+    add<InNames extends string>(input?: Port_Exports_Input<InNames>): Port_Exports<Names | InNames>
     add(a: any, b?: any, c?: any): any {
         if (!a) {
             return this
@@ -51,27 +82,50 @@ export class PortSet<Names extends string = never> {
         })
     }
 
-    pick<InNames extends Names>(...name: InNames[]): PortSet<InNames> {
+    /**
+     * Creates a new Port_Exports containing only the specified port names.
+     *
+     * @param name The port names to include.
+     * @returns A new Port_Exports with only the selected ports.
+     */
+    pick<InNames extends Names>(...name: InNames[]): Port_Exports<InNames> {
         return this._apply(map => filterMap(map, (_, key) => name.includes(key as InNames))) as any
     }
 
+    /** An array of all port names in this set. */
     get names() {
         return seq(this._map.keys()).toArray().pull() as Names[]
     }
 
-    get(name: Names): PortSetEntry {
+    /**
+     * Retrieves a port by name.
+     *
+     * @param name The name of the port to retrieve.
+     * @returns The full port configuration.
+     * @throws {PortError} If the port name is not found.
+     */
+    get(name: Names): Port_Full {
         if (!this._map.has(name)) {
             throw new PortError(`Port ${name} not found`)
         }
         return this._map.get(name)!
     }
 
+    /** The underlying map of port names to their full configurations. */
     get values() {
         return this._map
     }
 
-    map(mapping: InputPortMapping<Names>): PortMap<Names> {
-        return new PortMap(
+    /**
+     * Creates a Port_Map by mapping each port to a frontend port number.
+     *
+     * @param mapping A record where each port name maps to either a frontend port number or `true`
+     *   to use the backend port.
+     * @returns A new Port_Map with the specified frontend mappings.
+     * @throws {PortError} If a port name is missing from the mapping or has an invalid value.
+     */
+    map(mapping: PortMapping_Input<Names>): Port_Map<Names> {
+        return new Port_Map(
             mapValues(this._map, entry => {
                 if (!(entry.name in mapping)) {
                     throw new PortError(`Port ${entry.name} not found in mapping`)
@@ -97,7 +151,28 @@ export class PortSet<Names extends string = never> {
         )
     }
 
-    static make<Names extends string>(input?: InputPortSetRecord<Names>) {
-        return new PortSet().add(input)
+    /**
+     * Creates a new Port_Exports from a record of port configurations.
+     *
+     * @param input A record mapping port names to their configurations.
+     * @returns A new Port_Exports containing the specified ports.
+     */
+    static make<Names extends string>(input?: Port_Exports_Input<Names>) {
+        return new Port_Exports().add(input)
     }
 }
+
+/**
+ * Input type for creating Port_Exports.
+ *
+ * A record mapping port names to their configurations, which can be:
+ *
+ * - A port number (uses TCP by default)
+ * - A tuple of `[port, protocol]`
+ * - A full port configuration object
+ *
+ * @template Names The union type of port names.
+ */
+export type Port_Exports_Input<Names extends string = string> = {
+    [K in Names]: Port_Input
+}

package/src/expressions/network/ports/tools/entry.ts

@@ -1,26 +1,21 @@
 import { seq } from "doddle"
 import { Ip4 } from "../../ip"
-import { PortSet } from "../set"
-import type {
-    InputPortSetEntry,
-    InputPortSetRecord,
-    InputPortSetSpec,
-    PortSetEntry,
-    Protocol
-} from "../types"
+import type { Port_Exports_Input } from "../set"
+import { Port_Exports } from "../set"
+import type { Port_Full, Port_Full_Input, Port_Input, Port_Protocol } from "../types"
 import { parsePortSpec } from "./parse"
 
-function portSetEntry(name: string, value: InputPortSetEntry): PortSetEntry {
+function portSetEntry(name: string, value: Port_Full_Input): Port_Full {
     return {
         name,
         port: value.port,
-        protocol: value.protocol.toUpperCase() as Protocol,
+        protocol: value.protocol.toUpperCase() as Port_Protocol,
         hostIp: value.hostIp ? new Ip4(value.hostIp) : undefined,
         hostPort: value.hostPort
     }
 }
 
-export function parsePortInput(name: string, input: InputPortSetSpec): PortSetEntry {
+export function parsePortInput(name: string, input: Port_Input): Port_Full {
     if (typeof input === "string") {
         return portSetEntry(name, parsePortSpec(name, input))
     }
@@ -34,9 +29,9 @@ export function parsePortInput(name: string, input: InputPortSetSpec): PortSetEn
 }
 
 export function portRecordInput(
-    record: InputPortSetRecord<string> | PortSet<string>
-): Map<string, PortSetEntry> {
-    if (record instanceof PortSet) {
+    record: Port_Exports_Input<string> | Port_Exports<string>
+): Map<string, Port_Full> {
+    if (record instanceof Port_Exports) {
         return record.values
     }
     const inputMap = seq(Object.entries(record))

package/src/expressions/network/ports/tools/parse.ts

@@ -1,7 +1,7 @@
 import { anyStringOf, int, string } from "parjs"
 import { map, maybe, must, qthen, then } from "parjs/combinators"
 import { PortError } from "../error"
-import type { InputPortSetEntry, Protocol } from "../types"
+import type { Port_Full_Input, Port_Protocol } from "../types"
 
 function validatePort(port: number) {
     if (port < 0 || port > 65535) {
@@ -13,7 +13,7 @@ function validatePort(port: number) {
     return true
 }
 const pProtocol = anyStringOf("tcp", "udp", "TCP", "UDP").pipe(
-    map(s => s.toUpperCase() as Protocol)
+    map(s => s.toUpperCase() as Port_Protocol)
 )
 
 const pPort = int().pipe(must(validatePort))
@@ -25,7 +25,7 @@ const pPortSpec = pPort.pipe(
         return {
             port,
             protocol: protocol?.toUpperCase() ?? "TCP"
-        } as InputPortSetEntry
+        } as Port_Full_Input
     })
 )
 

package/src/expressions/network/ports/types.ts

@@ -1,43 +1,29 @@
 import type { Ip4, Ip4_String } from "../ip"
 
-export interface PortSpecObj {
-    port: Port
-    protocol: Protocol
-}
-
-export type Port = number
-export type InputPort = Port | `${Port}`
-export type InputProtocol = Protocol | Lowercase<Protocol>
-export type Protocol = "TCP" | "UDP"
-export type InputPortProto = `${Port}/${InputProtocol}`
-export interface PortMapEntry {
+type Port = number
+export type Port_Basic_Input = Port | `${Port}`
+export type Port_Protocol_Input = Port_Protocol | Lowercase<Port_Protocol>
+export type Port_Protocol = "TCP" | "UDP"
+export type Port_WithProto_Input = `${Port}/${Port_Protocol_Input}`
+export interface Port_Mapping_Entry {
     name: string
-    protocol: Protocol
+    protocol: Port_Protocol
     frontend: number
 }
 
-export interface PortSetEntry {
+export interface Port_Full {
     name: string
     port: number
-    protocol: Protocol
+    protocol: Port_Protocol
     hostIp?: Ip4
     hostPort?: number
 }
 
-export interface InputPortSetEntry {
+export interface Port_Full_Input {
     port: Port
-    protocol: InputProtocol
+    protocol: Port_Protocol_Input
     hostIp?: Ip4_String
     hostPort?: Port
 }
 
-export type InputPortSetSpec = InputPortSetEntry | InputPort | InputPortProto
-
-export type InputPortSetRecord<Names extends string = string> = {
-    [K in Names]: InputPortSetSpec
-}
-export type InputPortMapping<Names extends string = string> = [Names] extends [never]
-    ? never
-    : {
-          [K in Names]: number | true
-      }
+export type Port_Input = Port_Full_Input | Port_Basic_Input | Port_WithProto_Input

package/src/expressions/quantities/reqlem/objects.ts

@@ -9,7 +9,7 @@ import { AnyUnitParser } from "../units/unit-parser"
 import { createResourceParser } from "./parser"
 import type { ReqLimit, Resources_ReqLimits_Trait, Resources_UnitMap_Trait } from "./types"
 
-export class Resources_Map<const RM extends Resources_UnitMap_Trait<RM>> {
+export class Resources_UnitMap<const RM extends Resources_UnitMap_Trait<RM>> {
     constructor(private _map: Map<string, ReqLimit>) {}
 
     toObject() {
@@ -65,7 +65,7 @@ export class ResourcesSpec<const RM extends Resources_UnitMap_Trait<RM>> {
     }
     __INPUT__!: Resources_ReqLimits_Trait<RM>
 
-    parse<const R extends Resources_ReqLimits_Trait<RM>>(input: R): Resources_Map<RM> {
+    parse<const R extends Resources_ReqLimits_Trait<RM>>(input: R): Resources_UnitMap<RM> {
         const allKeys = new Set([...Object.keys(input), ...this._unitParsers.keys()])
         const map = seq(allKeys)
             .toMap(key => {
@@ -96,7 +96,7 @@ export class ResourcesSpec<const RM extends Resources_UnitMap_Trait<RM>> {
                 return [key, getVal()] as const
             })
             .pull()
-        return new Resources_Map(map as Map<string, ReqLimit>)
+        return new Resources_UnitMap(map as Map<string, ReqLimit>)
     }
 
     static make<const RM extends Resources_UnitMap_Trait<RM>>(unitMap: {

package/src/expressions/quantities/units/unit-parser.ts

@@ -10,7 +10,6 @@ const pValueUnit = int().pipe(
         return { value, unit }
     })
 )
-// TODO: Simplify unit parser to allow for arbitrary resources/units
 export class UnitValue<Unit extends string = string> {
     constructor(
         readonly unit: Unit,