@k8ts/instruments 0.1.0

package/src/api-kind/index.ts

@@ -0,0 +1,134 @@
+import { hash } from "immutable"
+import { InstrumentsError } from "../error"
+
+export type Kind<
+    Name extends string = string,
+    Version extends Kind.Version = Kind.Version
+> = Kind.Kind<Name, Version>
+export namespace Kind {
+    export type InputVersion = `v${string}`
+
+    export interface IdentParent {
+        text: string
+        name: string
+    }
+
+    export abstract class Identifier<
+        Name extends string = string,
+        Parent extends IdentParent | null = IdentParent | null
+    > implements IdentParent
+    {
+        constructor(
+            readonly name: Name,
+            readonly parent: Parent
+        ) {
+            this.toString = () => this.text
+        }
+        get text(): string {
+            return [this.parent?.text, this.name].filter(Boolean).join("/")
+        }
+
+        abstract child<Name extends string>(name: Name): Identifier<Name, this>
+
+        equals(other: any) {
+            if (typeof other !== "object" || !other) {
+                return false
+            }
+            if (!(other instanceof Identifier)) {
+                return false
+            }
+            return this.text === other.text
+        }
+
+        private hashCode() {
+            return hash(this.text)
+        }
+    }
+
+    export class Group<const Name extends string = string> extends Identifier<Name, null> {
+        constructor(override name: Name) {
+            super(name, null)
+        }
+        version<Version extends InputVersion>(apiVersion: Version) {
+            return new Version(apiVersion, this)
+        }
+
+        child<Name extends string>(name: Name): Version<Name, this> {
+            if (!name.startsWith("v")) {
+                throw new InstrumentsError(
+                    `Invalid version name "${name}". Version name must start with "v".`
+                )
+            }
+            return this.version(name as any)
+        }
+    }
+
+    export class Version<
+        const _Version extends string = string,
+        const _Group extends Group = Group
+    > extends Identifier<_Version, _Group> {
+        kind<Kind extends string>(kind: Kind) {
+            return new Kind(kind, this)
+        }
+
+        get group() {
+            return this.parent
+        }
+
+        child<Name extends string>(name: Name): Kind<Name, this> {
+            return this.kind(name)
+        }
+    }
+
+    export class Kind<
+        const Name extends string = string,
+        const V extends Version = Version
+    > extends Identifier<Name, V> {
+        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)
+        }
+    }
+
+    export class SubKind<
+        _SubKind extends string = string,
+        _Parent extends Kind = Kind
+    > extends Identifier<_SubKind, _Parent> {
+        constructor(name: _SubKind, parent: _Parent) {
+            super(name, parent)
+        }
+
+        subkind<SubKind extends string>(subkind: SubKind): never {
+            throw new InstrumentsError(`SubKind "${this.text}" cannot have subkind "${subkind}".`)
+        }
+
+        child<Name extends string>(name: Name): never {
+            return this.subkind(name)
+        }
+    }
+
+    export function group<ApiGroup extends string>(apiGroup: ApiGroup) {
+        return new Group(apiGroup)
+    }
+
+    export function version<ApiVersion extends InputVersion>(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/cmd/cli-command.ts

@@ -0,0 +1,89 @@
+import { List, Map } from "immutable"
+import { defaultsDeep, merge } from "lodash"
+import {
+    CliFlag,
+    CliOptionValue,
+    VerbatimTerm,
+    type CliTerm,
+    type ValueTermJoiner
+} from "./cli-term"
+import type { CliArgsMapping, CliKey } from "./types"
+
+export interface CliCommandBuilderOptions {
+    joiner: ValueTermJoiner
+}
+
+export class CmdBuilder {
+    protected constructor(
+        readonly executable: string,
+        private readonly _terms: List<CliTerm>,
+        private readonly _options: CliCommandBuilderOptions
+    ) {}
+
+    private _withArgs(f: (args: List<CliTerm>) => List<CliTerm>) {
+        return new CmdBuilder(this.executable, f(this._terms), this._options)
+    }
+
+    private _withOptions(f: (options: CliCommandBuilderOptions) => CliCommandBuilderOptions) {
+        return new CmdBuilder(this.executable, this._terms, f(this._options))
+    }
+
+    flag(...flags: CliKey[]) {
+        const flagTerms = flags.map(flag => new CliFlag(flag))
+        return this._withArgs(terms => terms.concat(flagTerms))
+    }
+
+    verbatim(...values: string[]) {
+        const verbatimTerms = values.map(value => new VerbatimTerm(value))
+        return this._withArgs(terms => terms.concat(verbatimTerms))
+    }
+
+    option(args: CliArgsMapping) {
+        const map = Map(args)
+        const optionTerms = map.entrySeq().map(([key, value]) => {
+            let joiner: string | undefined
+            const lastChar = key.at(-1)
+            if (lastChar === "=") {
+                joiner = "="
+                key = key.slice(0, -1) as CliKey
+            } else if (lastChar === " ") {
+                joiner = " "
+                key = key.slice(0, -1) as CliKey
+            }
+            return new CliOptionValue(key, joiner, value)
+        })
+        return this._withArgs(terms => terms.concat(optionTerms))
+    }
+
+    joiner(joiner: ValueTermJoiner) {
+        return this._withOptions(options => merge({}, options, { joiner: joiner }))
+    }
+
+    toArray() {
+        const terms = this._terms
+            .filter(x => !x.isMissing)
+            .map(term => term.str(this._options.joiner))
+            .toArray()
+        if (this.executable !== "") {
+            terms.unshift(this.executable)
+        }
+        return terms
+    }
+
+    toString() {
+        return this.toArray().join(" ")
+    }
+
+    static make(executable: string, options: CliCommandBuilderOptions) {
+        return new CmdBuilder(executable, List(), options)
+    }
+}
+
+const defaultOptions: CliCommandBuilderOptions = {
+    joiner: " "
+}
+
+export function Cmd(executable: string, options?: Partial<CliCommandBuilderOptions>) {
+    options = defaultsDeep({}, options, defaultOptions)
+    return CmdBuilder.make(executable, options as any)
+}

package/src/cmd/cli-term.ts

@@ -0,0 +1,60 @@
+import { InstrumentsError } from "../error"
+import type { CliValue } from "./types"
+
+export class CliFlag {
+    constructor(readonly key: string) {}
+
+    str(joiner: string) {
+        return this.key
+    }
+
+    get isMissing() {
+        return false
+    }
+}
+
+export type ValueTermJoiner = "=" | " "
+
+export class CliOptionValue {
+    constructor(
+        private readonly key: string,
+        private readonly overrideTermJoiner: string | undefined,
+        private readonly value: CliValue
+    ) {}
+
+    get isMissing() {
+        return this.value === null
+    }
+
+    private _valueStr() {
+        if (this.value === null) {
+            throw new Error("Shouldn't be here")
+        }
+        if (this.value === "") {
+            return `""`
+        }
+        return `${this.value}`
+    }
+
+    str(joiner: string) {
+        if (this.value === undefined) {
+            throw new InstrumentsError("CliOptionValue cannot be undefined, use null instead")
+        }
+
+        return [this.key, this._valueStr()].join(this.overrideTermJoiner ?? joiner)
+    }
+}
+
+export class VerbatimTerm {
+    constructor(readonly value: string) {}
+
+    str(joiner: string) {
+        return this.value
+    }
+
+    get isMissing() {
+        return false
+    }
+}
+
+export type CliTerm = CliFlag | CliOptionValue | VerbatimTerm

package/src/cmd/index.ts

@@ -0,0 +1,2 @@
+export { Cmd, CmdBuilder } from "./cli-command"
+export { CliArgsMapping, CliKey, CliValue } from "./types"

package/src/cmd/types.ts

@@ -0,0 +1,4 @@
+export type CliKey = `-${string}` | `--${string}`
+export type InputCliKey = `${CliKey}=` | `${CliKey} ` | CliKey
+export type CliValue = string | number | boolean | null | `${string}` | ` ${string}`
+export type CliArgsMapping = Record<InputCliKey, CliValue>

package/src/displayers/displayers.ts

@@ -0,0 +1,147 @@
+import chalk from "chalk"
+import { Embedder } from "../_embedder"
+
+export type KnownFormats = "local" | "global" | undefined
+export namespace Displayers {
+    export interface Out {
+        default: (format?: string) => string
+        simple: (format?: KnownFormats | string) => string
+        pretty: (format?: KnownFormats | string) => string
+        prefix?: () => string
+    }
+    export type In<Target extends object = object> = {
+        simple?: (this: Out, self: Target, format?: string) => string | object
+        pretty?: (this: Out, self: Target, format?: string) => string | object
+        prefix?: (this: Out, self: Target) => string
+    }
+    export type Modes = keyof In
+}
+const chalkNoColor = new chalk.Instance({
+    level: 0
+})
+class DisplayerDecorator {
+    private _system = new Embedder<object, Displayers.In>("displayers")
+    private _lastMode: Displayers.Modes = "simple"
+    private _withLastMode(mode: Displayers.Modes, fn: (...args: any[]) => string) {
+        return (...args: any[]) => {
+            const oldMode = this._lastMode
+            this._lastMode = mode
+            const result = fn(...args)
+            this._lastMode = oldMode
+            return result
+        }
+    }
+    implement(ctor: abstract new (...args: any[]) => object, input: Displayers.In) {
+        this._system.set(ctor.prototype, input)
+        const decorator = this
+        Object.defineProperties(ctor.prototype, {
+            [Symbol.toStringTag]: {
+                get() {
+                    const a = decorator.get(this)
+                    return a.default()
+                }
+            },
+            toString: {
+                value() {
+                    return this[Symbol.toStringTag]
+                }
+            }
+        })
+    }
+
+    wrapRecursiveFallback(out: Displayers.Out) {
+        const oAny = out as any
+        const self = this
+        for (const k in out) {
+            const orig = oAny[k]
+            if (typeof orig === "function") {
+                oAny[k] = function (...args: any[]) {
+                    const oldMode = self._lastMode
+                    if (k === "simple" || k === "pretty") {
+                        self._lastMode = k
+                    }
+                    try {
+                        let result = orig.call(oAny, ...args)
+                        if (!Array.isArray(result)) {
+                            result = [result]
+                        }
+                        const terms = result.map((x: any) => {
+                            const sndDisplayers = Displayers.tryGet(x) as any
+                            if (sndDisplayers) {
+                                return sndDisplayers[k].call(sndDisplayers, x, ...args)
+                            }
+                            return x
+                        })
+                        return terms.join(" ")
+                    } finally {
+                        this._lastMode = oldMode
+                    }
+                }
+            }
+        }
+        return out
+    }
+
+    tryGet(target: any): Displayers.Out | undefined {
+        if (typeof target !== "object") {
+            return undefined
+        }
+        const input = this._system.get(target)
+        if (!input) {
+            return undefined
+        }
+        const o: Displayers.Out = {
+            default: (format?: string) => {
+                const lastMode = this._lastMode
+                const result = o[lastMode]?.call(o, format) ?? o.simple(format)
+                return result
+            },
+            simple: format => {
+                const result = input.simple?.call(o, target, format)
+                if (!result) {
+                    const pretty = input.pretty?.call(o, target, format)
+                    if (typeof pretty === "string") {
+                        return chalkNoColor(pretty)
+                    }
+                    return "?!!?"
+                }
+                return result as any
+            },
+            prefix: input.prefix && (() => input.prefix!.call(o, target)),
+            pretty: format => {
+                return (input.pretty?.call(o, target, format) ??
+                    input.simple?.call(o, target, format) ??
+                    "?!?") as any
+            }
+        }
+        return this.wrapRecursiveFallback(o)
+    }
+
+    get(target: object): Displayers.Out {
+        this._system.get(target) // error if not there
+        return this.tryGet(target)!
+    }
+
+    get decorator() {
+        return Object.assign(
+            <
+                Target extends abstract new (...args: any[]) => object,
+                Impl extends Displayers.In<InstanceType<Target>>
+            >(
+                input: Impl
+            ) => {
+                return (ctor: Target) => {
+                    this.implement(ctor, input as any)
+                    return ctor
+                }
+            },
+            {
+                get: (target: object): Displayers.Out => {
+                    return this.get(target)
+                }
+            }
+        )
+    }
+}
+export const Displayers = new DisplayerDecorator()
+export const displayers = Displayers.decorator

package/src/displayers/index.ts

@@ -0,0 +1 @@
+export * from "./displayers"

package/src/env/env.ts

@@ -0,0 +1,74 @@
+import { Map, type MapOf } from "immutable"
+import { InstrumentsError } from "../error"
+import type { InputEnv, InputEnvMapping } from "./types"
+import { isValidEnvVarName } from "./validate-name"
+
+type _EnvBuilderMap = MapOf<InputEnvMapping>
+export class EnvBuilder {
+    constructor(private readonly _env: _EnvBuilderMap) {
+        for (const key of _env.keys()) {
+            if (!isValidEnvVarName(key)) {
+                throw new InstrumentsError("Invalid environment variable name", {
+                    key: key
+                })
+            }
+        }
+    }
+
+    get values() {
+        return this._env
+    }
+
+    private _withEnv(f: (env: _EnvBuilderMap) => _EnvBuilderMap) {
+        return new EnvBuilder(f(this._env))
+    }
+
+    add(name: string, value: string): EnvBuilder
+    add(input: InputEnvMapping): EnvBuilder
+    add(a: any, b?: any) {
+        const pairs: [string, string][] = typeof a === "string" ? [[a, b]] : Object.entries(a)
+        const map = Map(pairs)
+        const existingKeys = map
+            .keySeq()
+            .filter(k => this._env.has(k))
+            .toList()
+        if (existingKeys.size > 0) {
+            throw new InstrumentsError("Cannot overwrite existing keys using add", {
+                keys: existingKeys.toArray()
+            })
+        }
+        return this._withEnv(env => env.merge(map) as any)
+    }
+
+    overwrite(name: string, value: string): EnvBuilder
+    overwrite(input: InputEnvMapping): EnvBuilder
+    overwrite(a: any, b?: any) {
+        if (typeof a === "string") {
+            return this._withEnv(env => env.set(a, b))
+        } else {
+            const map = Map(a as InputEnvMapping) as _EnvBuilderMap
+            return this._withEnv(env => env.merge(map) as any)
+        }
+    }
+
+    toObject() {
+        return this._env
+            .filter(v => v != null)
+            .map(x => `${x}`)
+            .toObject()
+    }
+
+    static make(env?: InputEnv) {
+        if (!env) {
+            return new EnvBuilder(Map({}))
+        }
+        if (env instanceof EnvBuilder) {
+            return env
+        }
+        return new EnvBuilder(Map(env ?? {}).filter(v => v != null) as _EnvBuilderMap)
+    }
+}
+
+export function Env(env?: InputEnvMapping) {
+    return EnvBuilder.make(env)
+}

package/src/env/index.ts

@@ -0,0 +1,2 @@
+export { Env, EnvBuilder } from "./env"
+export { InputEnvMapping } from "./types"

package/src/env/types.ts

@@ -0,0 +1,7 @@
+import type { EnvBuilder } from "./env"
+
+export type InputEnvMapping = Partial<
+    Record<string, string | null | number | boolean | bigint | undefined>
+>
+
+export type InputEnv = EnvBuilder | InputEnvMapping

package/src/env/validate-name.ts

@@ -0,0 +1,10 @@
+import { anyCharOf, digit, letter } from "parjs"
+import { many, or, stringify, then } from "parjs/combinators"
+
+const pEnvVarStartChar = letter().pipe(or(anyCharOf("_")))
+const pEnvVarChar = pEnvVarStartChar.pipe(or(digit()))
+const pEnvVarName = pEnvVarStartChar.pipe(then(pEnvVarChar.pipe(many())), stringify())
+
+export function isValidEnvVarName(x: string) {
+    return pEnvVarName.parse(x).isOk
+}

package/src/error.ts

@@ -0,0 +1,15 @@
+export class InstrumentsError extends Error {
+    override get name() {
+        return this.constructor.name
+    }
+    constructor(message: string, details: Record<string, any> = {}) {
+        super(message)
+        Object.assign(this, details)
+    }
+}
+
+export class ProxyOperationError extends InstrumentsError {
+    constructor(message: string, details: Record<string, any> = {}) {
+        super(message, details)
+    }
+}