@k8ts/instruments 0.11.3 → 0.12.0

package/src/expressions/quantities/units/{units.ts → built-in.ts}

@@ -1,4 +1,4 @@
-import { SetUnitParser } from "./unit-parser"
+import { UnitDimension } from "./dimension"
 
 export type G = `${number}G`
 export const G = (n: number) => `${n}G` as G
@@ -36,17 +36,24 @@ export const s = (n: number) => `${n}s` as s
 export type ms = `${number}ms`
 export const ms = (n: number) => `${n}ms` as ms
 
-export interface UnitDefinition<Unit extends string> {}
-
-export namespace Unit {
+export namespace Units {
     export type Data = M | G | T | K | Mi | Gi | Ki
     export type Cpu = m
     export type Time = m | h | d | s | ms
     export type Any = Data | Cpu | Time
 
-    export const Cpu = SetUnitParser.make("cpu", new Set(["m"]))
+    export const Cpu = new UnitDimension({
+        name: "cpu",
+        units: ["m"]
+    })
 
-    export const Data = SetUnitParser.make("data", new Set(["M", "G", "T", "K", "Mi", "Gi", "Ki"]))
+    export const Data = new UnitDimension({
+        name: "data",
+        units: ["M", "G", "T", "K", "Mi", "Gi", "Ki"]
+    })
 
-    export const Time = SetUnitParser.make("time", new Set(["m", "h", "d", "s", "ms"]))
+    export const Time = new UnitDimension({
+        name: "time",
+        units: ["m", "h", "d", "s", "ms"]
+    })
 }

package/src/expressions/quantities/units/dimension.ts

@@ -0,0 +1,47 @@
+import { type Parjser } from "parjs"
+import { map } from "parjs/combinators"
+import { K8tsQuantityError } from "../error"
+import { pValueUnit } from "./parser"
+import type { Reqs_sUnitTerm } from "./types"
+import { type Dimension_Validator, getValidator } from "./validator"
+import { UnitValue } from "./value"
+
+export interface Dimension_Props_Any {
+    name: string
+    units: "any"
+}
+
+export interface Dimension_Props_Explicit<Units extends string> {
+    name: string
+    units: [Units, ...Units[]]
+}
+
+export type Dimension_Props<Units extends string = string> =
+    | Dimension_Props_Any
+    | Dimension_Props_Explicit<Units>
+
+export class UnitDimension<const _Units extends string = string> {
+    readonly parser: Parjser<UnitValue<_Units>>
+    private _validate: Dimension_Validator<_Units>
+    constructor(readonly _props: Dimension_Props<_Units>) {
+        this._validate = getValidator(_props)
+        this.parser = pValueUnit.pipe(
+            map(({ value, unit }) => {
+                this._validate(unit)
+
+                return new UnitValue<_Units>(unit as any, value, this._props.name)
+            })
+        )
+    }
+
+    parse(input: Reqs_sUnitTerm<_Units>) {
+        const pUnitValue = this.parser
+        const result = pUnitValue.parse(input)
+        if (result.kind !== "OK") {
+            throw new K8tsQuantityError(`Failed to parse ${this._props}`, {
+                more: result.trace.toString()
+            })
+        }
+        return result.value
+    }
+}

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

@@ -0,0 +1,11 @@
+import { int, letter } from "parjs"
+import { many, map, stringify, then } from "parjs/combinators"
+
+export const pUnit = letter().pipe(many(), stringify())
+export const pValueUnit = int().pipe(
+    then(pUnit),
+    map(arr => {
+        const [value, unit] = arr
+        return { value, unit }
+    })
+)

package/src/expressions/quantities/units/types.ts

@@ -0,0 +1 @@
+export type Reqs_sUnitTerm<_Unit extends string> = `${number}${_Unit}` | "?"

package/src/expressions/quantities/units/validator.ts

@@ -0,0 +1,17 @@
+import { K8tsQuantityError } from "../error"
+import type { Dimension_Props } from "./dimension"
+
+export type Dimension_Validator<Units extends string> = (unit: string) => asserts unit is Units
+export function getValidator<Units extends string>(
+    props: Dimension_Props<Units>
+): Dimension_Validator<Units> {
+    if (props.units === "any") {
+        return (_unit: string) => true
+    }
+    const validUnits = new Set(props.units)
+    return (unit: string) => {
+        if (!validUnits.has(unit as any)) {
+            throw new K8tsQuantityError(`Unit ${unit} is not a valid unit of type ${props.name}`)
+        }
+    }
+}

package/src/expressions/quantities/units/value.ts

@@ -0,0 +1,22 @@
+export class UnitValue<_Unit extends string = string> {
+    constructor(
+        readonly unit: _Unit,
+        readonly value: number,
+        readonly type: string
+    ) {}
+
+    get str() {
+        return `${this.value}${this.unit}`
+    }
+
+    get val() {
+        if (!this.unit) {
+            return +this.value
+        }
+        return this.str
+    }
+
+    toString() {
+        return this.str
+    }
+}

package/src/expressions/quantities/util.ts

@@ -0,0 +1,37 @@
+export interface CdkQuanitity<T extends string | number = string | number> {
+    value: T
+}
+export function isCdkQuanitity<T extends string | number>(input: any): input is CdkQuanitity<T> {
+    return (
+        typeof input === "object" &&
+        input !== null &&
+        "value" in input &&
+        Object.keys(input).length === 1
+    )
+}
+export function toCdkQuantity<T extends string | number | undefined>(
+    input: T
+): T extends undefined ? undefined : CdkQuanitity<Exclude<T, undefined>> {
+    return { value: input } as any
+}
+
+export type SkipUndefinedKeys<R extends Record<string, any>> = {
+    [K in keyof R as R[K] extends undefined ? never : K]: CdkQuanitity<R[K]>
+}
+export type NormEmptyObjectToUndefined<T> = T extends Record<string, never> ? undefined : T
+
+export function toCdkQuantityRecord<R extends Record<string, any>>(
+    input: R
+): NormEmptyObjectToUndefined<SkipUndefinedKeys<R>> {
+    const output: any = {}
+    for (const key in input) {
+        const quantity = toCdkQuantity(input[key])
+        if (quantity !== undefined) {
+            output[key] = quantity
+        }
+    }
+    if (Object.keys(output).length === 0) {
+        return undefined as any
+    }
+    return output
+}

package/src/expressions/workload/cmd/cli-term.ts

@@ -1,8 +1,9 @@
-import { InstrumentsError } from "../../../error"
-import { displayers } from "../../../utils/displayers"
-import type { Cli_Value } from "./types"
+import { K8tsGraphError } from "../../../core/graph/error"
+import { display } from "../../../utils/mixin/display"
+import { K8tsWorkloadToolsError } from "../error"
+import type { CmdLine_Value } from "./types"
 
-export class Cli_Flag {
+export class CmdLine_Term_Flag {
     constructor(readonly key: string) {}
 
     str(joiner: string) {
@@ -18,16 +19,16 @@ export class Cli_Flag {
     }
 }
 
-export type Cli_sTermJoiner = "=" | " "
+export type CmdLine_sTermJoiner = "=" | " "
 
-@displayers({
+@display({
     simple: s => s.str("=")
 })
-export class Cli_OptionValueTerm {
+export class CmdLine_Term_Value {
     constructor(
         private readonly key: string,
         private readonly overrideTermJoiner: string | undefined,
-        private readonly value: Cli_Value
+        private readonly value: CmdLine_Value
     ) {}
 
     get isMissing() {
@@ -36,7 +37,7 @@ export class Cli_OptionValueTerm {
 
     private _valueStr() {
         if (this.value === null) {
-            throw new Error("Shouldn't be here")
+            throw new K8tsWorkloadToolsError("Shouldn't be here")
         }
         if (this.value === "") {
             return `""`
@@ -46,7 +47,7 @@ export class Cli_OptionValueTerm {
 
     str(joiner: string) {
         if (this.value === undefined) {
-            throw new InstrumentsError("CliOptionValue cannot be undefined, use null instead")
+            throw new K8tsGraphError("CliOptionValue cannot be undefined, use null instead")
         }
 
         return [this.key, this._valueStr()].join(this.overrideTermJoiner ?? joiner)
@@ -61,7 +62,7 @@ export class Cli_OptionValueTerm {
     }
 }
 
-export class Cli_VerbatimTerm {
+export class CmdLine_Term_Verbatim {
     constructor(readonly value: string) {}
 
     str(joiner: string) {
@@ -77,4 +78,4 @@ export class Cli_VerbatimTerm {
     }
 }
 
-export type CliTerm = Cli_Flag | Cli_OptionValueTerm | Cli_VerbatimTerm
+export type CmdLine_Term = CmdLine_Term_Flag | CmdLine_Term_Value | CmdLine_Term_Verbatim

package/src/expressions/workload/cmd/cmd-line.ts

@@ -0,0 +1,103 @@
+import { seq } from "doddle"
+import { merge } from "lodash"
+import { display } from "../../../utils/mixin/display"
+import {
+    CmdLine_Term_Flag,
+    CmdLine_Term_Value,
+    CmdLine_Term_Verbatim,
+    type CmdLine_sTermJoiner,
+    type CmdLine_Term
+} from "./cli-term"
+import type { CmdLine_Args, CmdLine_sArg } from "./types"
+
+export interface CmdLine_Options {
+    joiner: CmdLine_sTermJoiner
+}
+export interface Cmd {
+    flag(...flags: CmdLine_sArg[]): Cmd
+    verbatim(...values: string[]): Cmd
+    options(args: CmdLine_Args): Cmd
+    joiner(joiner: CmdLine_sTermJoiner): Cmd
+    toArray(): string[]
+    toString(): string
+}
+
+const defaultOptions: CmdLine_Options = {
+    joiner: " "
+}
+export function Cmd(executable: string) {
+    return new _CmdLine(executable, [], {
+        joiner: " "
+    }) as Cmd
+}
+
+@display({
+    simple: s => s.toString()
+})
+class _CmdLine implements Cmd {
+    constructor(
+        readonly executable: string,
+        private readonly _terms: CmdLine_Term[],
+        private readonly _options: CmdLine_Options
+    ) {}
+
+    private _withArgs(f: (args: CmdLine_Term[]) => CmdLine_Term[]) {
+        return new _CmdLine(this.executable, f(this._terms), this._options)
+    }
+
+    private _withOptions(f: (options: CmdLine_Options) => CmdLine_Options) {
+        return new _CmdLine(this.executable, this._terms, f(this._options))
+    }
+
+    flag(...flags: CmdLine_sArg[]) {
+        const flagTerms = flags.map(flag => new CmdLine_Term_Flag(flag))
+        return this._withArgs(terms => terms.concat(flagTerms))
+    }
+
+    verbatim(...values: string[]) {
+        const verbatimTerms = values.map(value => new CmdLine_Term_Verbatim(value))
+        return this._withArgs(terms => terms.concat(verbatimTerms))
+    }
+
+    options(args: CmdLine_Args) {
+        const map = new Map(Object.entries(args)) as Map<CmdLine_sArg, string>
+        const optionTerms = seq(map)
+            .map(([key, value]) => {
+                let joiner: string | undefined
+                const lastChar = key.at(-1)
+                if (lastChar === "=") {
+                    joiner = "="
+                    key = key.slice(0, -1) as CmdLine_sArg
+                } else if (lastChar === " ") {
+                    joiner = " "
+                    key = key.slice(0, -1) as CmdLine_sArg
+                }
+                return new CmdLine_Term_Value(key, joiner, value)
+            })
+            .toArray()
+            .pull()
+        return this._withArgs(terms => terms.concat(optionTerms))
+    }
+
+    joiner(joiner: CmdLine_sTermJoiner) {
+        return this._withOptions(options => merge({}, options, { joiner: joiner }))
+    }
+
+    toArray() {
+        const terms = seq(this._terms)
+            .filter(x => !x.isMissing)
+            .flatMap(term => {
+                return term.arr(this._options.joiner)
+            })
+            .toArray()
+            .pull()
+        if (this.executable !== "") {
+            terms.unshift(this.executable)
+        }
+        return terms
+    }
+
+    toString() {
+        return this.toArray().join(" ")
+    }
+}

package/src/expressions/workload/cmd/types.ts

@@ -1,4 +1,4 @@
-export type Cli_sFlag = `-${string}` | `--${string}`
-export type Cli_sArgKey = `${Cli_sFlag}=` | `${Cli_sFlag} ` | Cli_sFlag
-export type Cli_Value = string | number | boolean | null | `${string}` | ` ${string}`
-export type Cli_Record_ArgMap = Record<Cli_sArgKey, Cli_Value>
+export type CmdLine_sArg = `-${string}` | `--${string}`
+export type CmdLine_sOption = `${CmdLine_sArg}=` | `${CmdLine_sArg} ` | CmdLine_sArg
+export type CmdLine_Value = string | number | boolean | null | `${string}` | ` ${string}`
+export type CmdLine_Args = Record<CmdLine_sOption, CmdLine_Value>

package/src/expressions/workload/cronjob/parse-type.ts

@@ -0,0 +1,58 @@
+export type Cron_Divisor = number
+export type Cron_Element_Simple = `${number}` | `*`
+export type Cron_Element_Divided = `${Cron_Element_Simple}/${Cron_Divisor}`
+type Cron_Element_RangeItem = Cron_Element_Simple | Cron_Element_Divided
+export type Cron_Element_Range = `${Cron_Element_RangeItem}-${string}` &
+    `${string}-${Cron_Element_RangeItem}`
+type Cron_Element_ListItem = Cron_Element_Simple | Cron_Element_Divided | Cron_Element_Range
+export type Cron_Element_List<Es extends Cron_Element_ListItem[] = Cron_Element_ListItem[]> =
+    Es extends []
+        ? ""
+        : Es extends [
+                infer E extends Cron_Element_ListItem,
+                ...infer Rest extends Cron_Element_ListItem[]
+            ]
+          ? `${E},${Cron_Element_List<Rest>}`
+          : never
+
+export type Cron_Element_Real =
+    | Cron_Element_Simple
+    | Cron_Element_Divided
+    | Cron_Element_Range
+    | Cron_Element_List
+export type Cron_Element = Cron_Element_Real | true | number | false
+export type Cron_Tuple<
+    Minute extends Cron_Element = Cron_Element,
+    Hour extends Cron_Element = Cron_Element,
+    DayOfMonth extends Cron_Element = Cron_Element,
+    Month extends Cron_Element = Cron_Element,
+    DayOfWeek extends Cron_Element = Cron_Element
+> = [minute: Minute, hour: Hour, dayOfMonth: DayOfMonth, month: Month, dayOfWeek: DayOfWeek]
+
+export type Cron_Record<
+    Minute extends Cron_Element = Cron_Element,
+    Hour extends Cron_Element = Cron_Element,
+    DayOfMonth extends Cron_Element = Cron_Element,
+    Month extends Cron_Element = Cron_Element,
+    DayOfWeek extends Cron_Element = Cron_Element
+> = {
+    minute: Minute
+    hour: Hour
+    dayOfMonth: DayOfMonth
+    month: Month
+    dayOfWeek: DayOfWeek
+}
+export type Cron_RecordToTuple<T extends Cron_Record> = Cron_Tuple<
+    T["minute"],
+    T["hour"],
+    T["dayOfMonth"],
+    T["month"],
+    T["dayOfWeek"]
+>
+export type Cron_RecordFromTuple<T extends Cron_Tuple> = {
+    minute: T[0]
+    hour: T[1]
+    dayOfMonth: T[2]
+    month: T[3]
+    dayOfWeek: T[4]
+}

package/src/expressions/workload/cronjob/shorthand.ts

@@ -0,0 +1,37 @@
+import { K8tsGraphError } from "../../../core/graph/error"
+import type { Cron_Record, Cron_RecordFromTuple, Cron_Tuple } from "./parse-type"
+import { CronStanza } from "./stanza"
+
+function shorthand<Tpl extends Cron_Tuple>(...items: Tpl): CronStanza<Cron_RecordFromTuple<Tpl>> {
+    return CronStanza<Cron_RecordFromTuple<Tpl>>({
+        minute: items[0],
+        hour: items[1],
+        dayOfMonth: items[2],
+        month: items[3],
+        dayOfWeek: items[4]
+    })
+}
+
+export namespace Cron {
+    export function from<R extends Cron_Record>(record: R): CronStanza<R> {
+        return CronStanza<R>(record)
+    }
+
+    export const minutely = shorthand(true, true, true, true, true)
+    export const hourly = shorthand(0, true, true, true, true)
+    export const daily = shorthand(0, 0, true, true, true)
+    export const weekly = shorthand(0, 0, true, true, 0)
+    export const monthly = shorthand(0, 0, 1, true, true)
+    export const yearly = shorthand(0, 0, 1, 1, true)
+
+    // TODO: Parse cron strings with type safety
+    // TODO: Write a runtime parser too
+    // TODO: Consider using an existing library for this
+    export function parse(cron: string): CronStanza<Cron_Record> {
+        const parts = cron.split(" ")
+        if (parts.length !== 5) {
+            throw new K8tsGraphError(`Invalid cron string: ${cron}`)
+        }
+        return shorthand(...(parts as any))
+    }
+}

package/src/expressions/workload/cronjob/stanza.ts

@@ -0,0 +1,91 @@
+import { display } from "../../../utils/mixin/display"
+import type { Cron_Element, Cron_Record, Cron_RecordToTuple } from "./parse-type"
+import type { _SetObjectKey } from "./types"
+
+export declare const CRON_STRING: unique symbol
+
+function _convertStanzaElement(X: Cron_Element): string {
+    if (X === true) {
+        return "*"
+    }
+    if (X === false) {
+        return "0"
+    }
+    return `${X}`
+}
+export interface CronStanza<R extends Cron_Record = Cron_Record> {
+    get tuple(): Cron_RecordToTuple<R>
+    toString(): string
+    get string(): string
+    minute<Minute extends Cron_Element>(
+        minute: Minute
+    ): CronStanza<_SetObjectKey<R, "minute", Minute>>
+    hour<Hour extends Cron_Element>(hour: Hour): CronStanza<_SetObjectKey<R, "hour", Hour>>
+    dayOfMonth<DayOfMonth extends Cron_Element>(
+        dayOfMonth: DayOfMonth
+    ): CronStanza<_SetObjectKey<R, "dayOfMonth", DayOfMonth>>
+    month<Month extends Cron_Element>(month: Month): CronStanza<_SetObjectKey<R, "month", Month>>
+    dayOfWeek<DayOfWeek extends Cron_Element>(
+        dayOfWeek: DayOfWeek
+    ): CronStanza<_SetObjectKey<R, "dayOfWeek", DayOfWeek>>
+}
+export function CronStanza<R extends Cron_Record>(record: R) {
+    return new _CronStanza(record) as CronStanza<R>
+}
+@display({
+    simple(self) {
+        return self.string
+    }
+})
+class _CronStanza {
+    constructor(private readonly _parts: Cron_Record) {}
+
+    get tuple() {
+        return [
+            this._parts.minute,
+            this._parts.hour,
+            this._parts.dayOfMonth,
+            this._parts.month,
+            this._parts.dayOfWeek
+        ] as Cron_RecordToTuple<Cron_Record>
+    }
+
+    get string() {
+        return this.tuple.map(_convertStanzaElement).join(" ")
+    }
+
+    minute<Minute extends Cron_Element>(minute: Minute): _CronStanza {
+        return new _CronStanza({
+            ...this._parts,
+            minute
+        } as any)
+    }
+
+    hour<Hour extends Cron_Element>(hour: Hour): _CronStanza {
+        return new _CronStanza({
+            ...this._parts,
+            hour
+        } as any)
+    }
+
+    dayOfMonth<DayOfMonth extends Cron_Element>(dayOfMonth: DayOfMonth): _CronStanza {
+        return new _CronStanza({
+            ...this._parts,
+            dayOfMonth
+        } as any)
+    }
+
+    month<Month extends Cron_Element>(month: Month): _CronStanza {
+        return new _CronStanza({
+            ...this._parts,
+            month
+        } as any)
+    }
+
+    dayOfWeek<DayOfWeek extends Cron_Element>(dayOfWeek: DayOfWeek): _CronStanza {
+        return new _CronStanza({
+            ...this._parts,
+            dayOfWeek
+        } as any)
+    }
+}

package/src/expressions/workload/cronjob/types.ts

@@ -0,0 +1,3 @@
+export type _SetObjectKey<Obj extends object, K extends keyof Obj, V> = {
+    [P in keyof Obj]: P extends K ? V : Obj[P]
+}

package/src/expressions/workload/error.ts

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

package/src/expressions/workload/image/1-host.ts

@@ -0,0 +1,31 @@
+import { ImageNamespace } from "./2-namespace"
+import { ImageRepository } from "./3-repository"
+import type { JoinIfNotEmpty } from "./types"
+
+export interface ImageRegistry<Text extends string = string> {
+    toString(): Text
+    isEmpty: boolean
+    repo<Name extends string = "">(name?: Name): ImageRepository<JoinIfNotEmpty<Text, "/", Name>>
+    namespace<Ns extends string = "">(namespace?: Ns): ImageNamespace<JoinIfNotEmpty<Text, "/", Ns>>
+}
+export function ImageRegistry<Text extends string = "">(registry?: Text) {
+    return new _ImageRegistry(registry ?? "") as ImageRegistry<Text>
+}
+class _ImageRegistry implements ImageRegistry<string> {
+    constructor(readonly _registry: string) {}
+    toString(): any {
+        return this._registry
+    }
+
+    get isEmpty() {
+        return this._registry === ""
+    }
+
+    repo(name?: string) {
+        return ImageRepository<any>(this._registry, "", name ?? "")
+    }
+
+    namespace<Ns extends string = "">(namespace?: Ns) {
+        return ImageNamespace<any>(this._registry, namespace ?? "")
+    }
+}

package/src/expressions/workload/image/2-namespace.ts

@@ -0,0 +1,49 @@
+import { display } from "../../../utils"
+import { ImageRegistry } from "./1-host"
+import { ImageRepository } from "./3-repository"
+import type { JoinIfNotEmpty } from "./types"
+
+export interface ImageNamespace<Text extends string = string> {
+    toString(): Text
+    isEmpty: boolean
+    get registry(): ImageRegistry
+    repo<Name extends string>(name?: Name): ImageRepository<JoinIfNotEmpty<Text, "/", Name>>
+}
+export function ImageNamespace<Text extends string = "">(registry: string, namespace?: Text) {
+    return new _ImageNamespace(registry, namespace ?? "") as ImageNamespace<Text>
+}
+@display({
+    simple: s => s._url
+})
+class _ImageNamespace implements ImageNamespace<any> {
+    private readonly _url: string
+    constructor(
+        private readonly _registry: string,
+        private readonly _namespace: string
+    ) {
+        const parts = []
+        if (!this.registry.isEmpty) {
+            parts.push(this.registry)
+        }
+        if (this._namespace !== "") {
+            parts.push(this._namespace)
+        }
+        this._url = parts.join("/")
+    }
+
+    toString(): any {
+        return this._url
+    }
+
+    get registry() {
+        return ImageRegistry<any>(this._registry)
+    }
+
+    get isEmpty() {
+        return this.registry.isEmpty && this._namespace === ""
+    }
+
+    repo<Repo extends string = "">(name?: Repo): ImageRepository<any> {
+        return ImageRepository(this._registry, this._namespace, name ?? "")
+    }
+}