@bomb.sh/router 0.0.1 → 0.7.0

package/esm/lib/bind.js

@@ -0,0 +1,285 @@
+import { Just } from "./maybe.js";
+export function fromCLI(options) {
+    let { param, view, rest } = options;
+    return fromRead(param, param.cli.read(view), rest);
+}
+export function fromValues(options) {
+    let { param, route, rest } = options;
+    let claim = rest.values.claim({
+        route,
+        address: [param.name],
+    });
+    if (!claim.result.exists) {
+        return { exists: false };
+    }
+    return {
+        exists: true,
+        value: {
+            rest: {
+                ...rest,
+                values: claim.rest,
+            },
+            result: validate(param, claim.result.value.value, [param.name]),
+        },
+    };
+}
+export function fromEnv(options) {
+    let { param, route, rest } = options;
+    let claim = rest.envs.claim({
+        route,
+        address: [param.name],
+        key: param.env,
+    });
+    if (!claim.result.exists) {
+        return { exists: false };
+    }
+    let value = claim.result.value.value;
+    let candidates = param.cardinality === "one"
+        ? param.decode(value)
+        : param.decode([value]);
+    return {
+        exists: true,
+        value: {
+            rest: {
+                ...rest,
+                envs: claim.rest,
+            },
+            result: decode(param, value, candidates, [param.name]),
+        },
+    };
+}
+export function bindPhase(options) {
+    let { phase, segment } = options;
+    let rest = options.rest;
+    let params = Object.values(phase.model.params);
+    let pending = new Map(params.map((param) => [param.name, param]));
+    let results = new Map();
+    function settle(param, binding) {
+        rest = binding.rest;
+        results.set(param.name, binding.result);
+        pending.delete(param.name);
+    }
+    function accept(param, attempt) {
+        if (!attempt.exists) {
+            return;
+        }
+        settle(param, attempt.value);
+    }
+    let captures = new Map();
+    // Every pending reader proposes a claim against the same immutable view.
+    // Commit the proposal beginning earliest in argv, then recompute the view.
+    // This lets `--port 9000` outrank a positional claim on `9000` without
+    // attaching binding-policy metadata to either reader.
+    while (true) {
+        let horizon = first(rest.tokens, segment.range);
+        let offer;
+        for (let param of pending.values()) {
+            let view = rest.tokens.view({
+                range: segment.range,
+                through: horizon?.index,
+            });
+            let read = param.cli.read(view);
+            if (read.result.ok && !read.result.value.exists) {
+                continue;
+            }
+            let index = earliest(read.claim.tokens);
+            if (!offer || index < offer.index) {
+                offer = { param, read, index };
+            }
+        }
+        if (!offer) {
+            break;
+        }
+        if (offer.param.cardinality === "many") {
+            rest = {
+                ...rest,
+                tokens: offer.read.claim.rest,
+            };
+            let current = captures.get(offer.param.name) ?? {
+                param: offer.param,
+                values: [],
+                issues: [],
+                failed: false,
+            };
+            current.issues.push(...offer.read.result.issues ?? []);
+            if (offer.read.result.ok && offer.read.result.value.exists) {
+                current.values.push(offer.read.result.value.value);
+            }
+            else {
+                current.failed = true;
+            }
+            captures.set(offer.param.name, current);
+            continue;
+        }
+        accept(offer.param, fromRead(offer.param, offer.read, rest));
+    }
+    // deal wil all multiple
+    for (let capture of captures.values()) {
+        if (capture.failed) {
+            settle(capture.param, {
+                rest,
+                result: { ok: false, issues: capture.issues },
+            });
+        }
+        else {
+            let values = capture.values;
+            let candidates = values.every((value) => typeof value === "string")
+                ? capture.param.decode(values)
+                : [Just(values)];
+            let result = merge(decode(capture.param, values, candidates, [capture.param.name]), capture.issues);
+            settle(capture.param, { result, rest });
+        }
+    }
+    // Address sources have stable visibility once the route is known. They are
+    // tried only after CLI has reached its fixed point so a provisional CLI miss
+    // cannot let a lower-priority source settle the parameter too early.
+    for (let source of [fromEnv, fromValues]) {
+        for (let param of pending.values()) {
+            accept(param, source({
+                param,
+                route: segment.path,
+                rest,
+            }));
+        }
+    }
+    // Only total absence reaches the schema as undefined. This is where required,
+    // optional, and defaulting parameters diverge.
+    for (let param of pending.values()) {
+        results.set(param.name, validate(param, undefined, [param.name]));
+    }
+    let bindings = {};
+    let issues = [];
+    let valid = true;
+    // Collect in declaration order, independent of the source or sweep that
+    // settled each parameter.
+    for (let param of params) {
+        let result = results.get(param.name);
+        issues.push(...result.issues ?? []);
+        if (result.ok) {
+            bindings[param.name] = result.value;
+        }
+        else {
+            valid = false;
+        }
+    }
+    let model = {};
+    for (let step of phase.model.steps) {
+        let result = step(model, bindings);
+        if (!result.ok) {
+            valid = false;
+            issues.push(...result.issues);
+            break;
+        }
+        else {
+            model = result.value;
+        }
+    }
+    return { rest, model, issues, valid };
+}
+function fromRead(param, read, rest) {
+    let path = [param.name];
+    if (!read.result.ok) {
+        return {
+            exists: true,
+            value: {
+                rest: {
+                    ...rest,
+                    tokens: read.claim.rest,
+                },
+                result: read.result,
+            },
+        };
+    }
+    if (!read.result.value.exists) {
+        return { exists: false };
+    }
+    let value = read.result.value.value;
+    let candidates = typeof value === "string"
+        ? param.decode(value)
+        : [Just(value)];
+    let result = merge(decode(param, value, candidates, path), read.result.issues);
+    return {
+        exists: true,
+        value: {
+            rest: {
+                ...rest,
+                tokens: read.claim.rest,
+            },
+            result,
+        },
+    };
+}
+function decode(param, value, candidates, path) {
+    if (candidates.length === 0) {
+        return {
+            ok: false,
+            issues: [{
+                    message: `unable to decode ${JSON.stringify(value)}`,
+                    path,
+                }],
+        };
+    }
+    let issues;
+    let values = candidates.flatMap((candidate) => candidate.exists ? [candidate.value] : []);
+    for (let candidate of values) {
+        let result = validate(param, candidate, path);
+        if (result.ok) {
+            return result;
+        }
+        issues = issues ?? result.issues;
+    }
+    return {
+        ok: false,
+        issues: issues ?? [],
+    };
+}
+function validate(param, value, path) {
+    let validated = param.schema["~standard"].validate(value);
+    if (validated instanceof Promise) {
+        return {
+            ok: false,
+            issues: [{
+                    message: `async schemas are not allowed`,
+                    path,
+                }],
+        };
+    }
+    if (validated.issues) {
+        return {
+            ok: false,
+            issues: validated.issues.map((issue) => ({
+                ...issue,
+                message: issue.message,
+                path,
+            })),
+        };
+    }
+    return {
+        ok: true,
+        issues: [],
+        value: validated.value,
+    };
+}
+function merge(result, issues) {
+    if (!issues || issues.length === 0) {
+        return result;
+    }
+    return {
+        ...result,
+        issues: [...issues, ...(result.issues ?? [])],
+    };
+}
+function first(tokens, range) {
+    for (let token of tokens.view({ range })) {
+        if (token.type === "word") {
+            return token;
+        }
+    }
+}
+function earliest(tokens) {
+    let first = Infinity;
+    for (let token of tokens) {
+        first = Math.min(first, token.index);
+    }
+    return first;
+}

package/esm/lib/checkpoint.d.ts

@@ -0,0 +1,3 @@
+import type { DynamicElement } from "./pipeline.js";
+import { type ValueSource, withValues } from "./values.js";
+export declare function checkpoint(): DynamicElement<ValueSource[], ReturnType<typeof withValues>>;

package/esm/lib/checkpoint.js

@@ -0,0 +1,5 @@
+import { dynamic } from "./dynamic.js";
+import { withValues } from "./values.js";
+export function checkpoint() {
+    return dynamic((values) => withValues(values));
+}

package/esm/lib/command.d.ts

@@ -0,0 +1,6 @@
+import type { Check, Fold, Materialize, Unary } from "./pipeline.js";
+import type { Definition, Done, Route } from "./types.js";
+export type CommandZero<N extends string = string> = Route<N, "help" | "execute", [
+    Done<{}, []>
+]>;
+export declare function command<const N extends string, const E extends readonly Unary[]>(start: Definition<N>, ...elements: E & Check<CommandZero<N>, E>): Materialize<Fold<CommandZero<N>, E>>;

package/esm/lib/command.js

@@ -0,0 +1,16 @@
+export function command(start, ...elements) {
+    let zero = {
+        ...start,
+        methods: ["help", "execute"],
+        phases: [{
+                model: {
+                    params: {},
+                    steps: [],
+                },
+                routes: [],
+                values: [],
+                envs: [],
+            }],
+    };
+    return elements.reduce((value, element) => element(value), zero);
+}

package/esm/lib/dasherize.d.ts

@@ -0,0 +1 @@
+export declare function dasherize(name: string): string;

package/esm/lib/dasherize.js

@@ -0,0 +1,7 @@
+export function dasherize(name) {
+    return name
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+        .replace(/([a-z\d])([A-Z])/g, "$1-$2")
+        .replace(/[\s_]+/g, "-")
+        .toLowerCase();
+}

package/esm/lib/decode.d.ts

@@ -0,0 +1,6 @@
+import { type Maybe } from "./maybe.js";
+export type Decoder<A, B> = (value: A) => Maybe<B>[];
+export declare const number: Decoder<string, number>;
+export declare const scalar: Decoder<string, string | number>;
+export declare const boolean: Decoder<string, boolean>;
+export declare function multiple<A, B>(decoder: Decoder<A, B>): Decoder<A[], B[]>;

package/esm/lib/decode.js

@@ -0,0 +1,46 @@
+import { Just, Nothing } from "./maybe.js";
+export const number = (value) => {
+    if (!numeric.test(value)) {
+        return [Nothing()];
+    }
+    let decoded = Number(value);
+    return Number.isFinite(decoded) ? [Just(decoded)] : [Nothing()];
+};
+export const scalar = (value) => {
+    return [...number(value), Just(value)];
+};
+export const boolean = (value) => {
+    if (value === "true") {
+        return [Just(true)];
+    }
+    if (value === "false") {
+        return [Just(false)];
+    }
+    return [Nothing()];
+};
+export function multiple(decoder) {
+    return (input) => {
+        let decodings = input.map(decoder);
+        let result = [];
+        for (let i = 0; i < decodings.length; i++) {
+            let decoding = decodings[i];
+            for (let j = 0; j < decoding.length; j++) {
+                let row = result[j];
+                if (!row) {
+                    row = result[j] = Just([]);
+                }
+                if (row.exists) {
+                    let candidate = decoding[j];
+                    if (candidate.exists) {
+                        row.value[i] = candidate.value;
+                    }
+                    else {
+                        result[j] = Nothing();
+                    }
+                }
+            }
+        }
+        return result;
+    };
+}
+const numeric = /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/;

package/esm/lib/definition.d.ts

@@ -0,0 +1,4 @@
+import { type IdentityElement } from "./pipeline.js";
+import type { Definition } from "./types.js";
+export declare function name<N extends string>(name: N): Definition<N>;
+export declare function description(description: string): IdentityElement<Definition<string>>;

package/esm/lib/definition.js

@@ -0,0 +1,10 @@
+import { brand } from "./pipeline.js";
+export function name(name) {
+    return { name };
+}
+export function description(description) {
+    return brand((definition) => ({
+        ...definition,
+        description,
+    }));
+}

package/esm/lib/dynamic.d.ts

@@ -0,0 +1,6 @@
+import type { AnyRoute } from "./types.js";
+import { type AnyElement, type DynamicElement } from "./pipeline.js";
+export type { ConjoinPhases, Seed } from "./pipeline.js";
+export type PhaseOf<R extends AnyRoute> = R["phases"][0];
+export type PhasesOf<R extends AnyRoute> = R["phases"];
+export declare function dynamic<Requirement, E>(extension: (requires: Requirement) => E, ..._valid: E extends AnyElement ? [] : [never]): DynamicElement<Requirement, Extract<E, AnyElement>>;

package/esm/lib/dynamic.js

@@ -0,0 +1,21 @@
+import { brand } from "./pipeline.js";
+export function dynamic(extension, ..._valid) {
+    return brand((route) => {
+        let phases = [...route.phases];
+        let phase = phases.pop();
+        phases.push({
+            ...phase,
+            resolver: extension,
+        });
+        phases.push({
+            model: {
+                params: {},
+                steps: [],
+            },
+            routes: [],
+            values: [],
+            envs: [],
+        });
+        return { ...route, phases };
+    });
+}

package/esm/lib/env.d.ts

@@ -0,0 +1,34 @@
+import type { Maybe } from "./maybe.js";
+import type { AnyParam } from "./param.js";
+import { type IdentityElement } from "./pipeline.js";
+import type { AnyRoute, RoutePath } from "./types.js";
+export interface EnvSource {
+    readonly name: string;
+    readonly value: Environment;
+}
+export type Environment = Readonly<Record<string, string | undefined>>;
+export interface EnvClaim {
+    readonly result: Maybe<{
+        readonly source: string;
+        readonly address: readonly string[];
+        readonly key: string;
+        readonly value: string;
+    }>;
+    readonly rest: Envs;
+}
+export interface EnvClaimOptions {
+    readonly route: readonly string[];
+    readonly address: readonly string[];
+    readonly key?: string;
+}
+export declare function env(key: string): IdentityElement<AnyParam>;
+export declare function withEnvs(envs: readonly EnvSource[]): IdentityElement<AnyRoute>;
+export declare class Envs {
+    mounts: Map<RoutePath, EnvSource[]>;
+    claims: Set<ClaimId>;
+    constructor(mounts?: Map<RoutePath, EnvSource[]>, claims?: Set<ClaimId>);
+    mount(path: readonly string[], sources: readonly EnvSource[]): Envs;
+    claim({ route, address, key }: EnvClaimOptions): EnvClaim;
+}
+type ClaimId = string;
+export {};

package/esm/lib/env.js

@@ -0,0 +1,83 @@
+import { brand } from "./pipeline.js";
+export function env(key) {
+    return brand((param) => ({ ...param, env: key }));
+}
+export function withEnvs(envs) {
+    return brand((route) => {
+        let phases = [...route.phases];
+        let phase = phases.pop();
+        phases.push({
+            ...phase,
+            envs: phase.envs.concat(envs),
+        });
+        return {
+            ...route,
+            phases,
+        };
+    });
+}
+export class Envs {
+    mounts;
+    claims;
+    constructor(mounts = new Map(), claims = new Set()) {
+        this.mounts = mounts;
+        this.claims = claims;
+    }
+    mount(path, sources) {
+        if (sources.length === 0) {
+            return this;
+        }
+        let id = routeId(path);
+        return new Envs(new Map([...this.mounts.entries(), [
+                id,
+                (this.mounts.get(id) ?? []).concat(sources),
+            ]]), this.claims);
+    }
+    claim({ route, address, key = envKey([...route, ...address]) }) {
+        let id = claimId([...route, ...address]);
+        let nope = { result: { exists: false }, rest: this };
+        if (this.claims.has(id)) {
+            return nope;
+        }
+        for (let end = route.length; end >= 0; end--) {
+            let mount = routeId(route.slice(0, end));
+            let sources = this.mounts.get(mount) ?? [];
+            for (let { name, value } of sources) {
+                if (!Object.hasOwn(value, key) || typeof value[key] === "undefined") {
+                    continue;
+                }
+                let rest = new Envs(this.mounts, new Set([...this.claims, id]));
+                return {
+                    result: {
+                        exists: true,
+                        value: {
+                            source: name,
+                            address,
+                            key,
+                            value: value[key],
+                        },
+                    },
+                    rest,
+                };
+            }
+        }
+        return nope;
+    }
+}
+function routeId(path) {
+    return `/${path.join("/")}`;
+}
+function claimId(address) {
+    return JSON.stringify(address);
+}
+function envKey(address) {
+    return address.map(normalize).filter(Boolean).join("_");
+}
+function normalize(value) {
+    return value
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+        .replace(/([a-z\d])([A-Z])/g, "$1_$2")
+        .replace(/[^A-Za-z\d]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .toUpperCase();
+}

package/esm/lib/extend.d.ts

@@ -0,0 +1,2 @@
+import { type Extension, type Unary } from "./pipeline.js";
+export declare function extend<const E extends readonly Unary[]>(...elements: E): Extension<E>;

package/esm/lib/extend.js

@@ -0,0 +1,4 @@
+import { brand } from "./pipeline.js";
+export function extend(...elements) {
+    return brand((start) => elements.reduce((value, element) => element(value), start));
+}

package/esm/lib/maybe.d.ts

@@ -0,0 +1,9 @@
+export type Maybe<T> = {
+    readonly exists: false;
+} | {
+    readonly exists: true;
+    readonly value: T;
+};
+export declare function Just(): Maybe<void>;
+export declare function Just<T>(value: T): Maybe<T>;
+export declare function Nothing<T = void>(): Maybe<T>;

package/esm/lib/maybe.js

@@ -0,0 +1,12 @@
+export function Just(value) {
+    if (typeof value === "undefined") {
+        return { exists: true };
+    }
+    else {
+        return { exists: true, value };
+    }
+}
+export function Nothing() {
+    return nothing;
+}
+const nothing = { exists: false };

package/esm/lib/multiple.d.ts

@@ -0,0 +1,8 @@
+import type { Param } from "./param.js";
+import { type Transform, type TransformElement } from "./pipeline.js";
+export declare function multiple(): TransformElement<MultipleTransform>;
+interface MultipleTransform extends Transform {
+    readonly input: Param<string, unknown, "one">;
+    readonly output: this["input"] extends Param<infer K, infer Model, "one"> ? Param<K, Model, "many"> : never;
+}
+export {};

package/esm/lib/multiple.js

@@ -0,0 +1,9 @@
+import { multiple as decode } from "./decode.js";
+import { mark } from "./pipeline.js";
+export function multiple() {
+    return mark((param) => ({
+        ...param,
+        cardinality: "many",
+        decode: decode(param.decode),
+    }));
+}

package/esm/lib/option.d.ts

@@ -0,0 +1,7 @@
+import { type Param, type ParamModel } from "./param.js";
+import { type Check, type Fold, type ModelElement, type Unary } from "./pipeline.js";
+import type { Definition } from "./types.js";
+export declare function option<const N extends string, const E extends readonly Unary[]>(named: Definition<N>, ...elements: E & Check<Zero<N>, E>): ElementOf<N, Fold<Zero<N>, E>>;
+type Zero<N extends string> = Param<N, unknown, "one">;
+type ElementOf<N extends string, P> = P extends Param<N, infer Model, infer _Cardinality> ? ModelElement<ParamModel<N, Model>> : never;
+export {};

package/esm/lib/option.js

@@ -0,0 +1,31 @@
+import { param } from "./param.js";
+import { dasherize } from "./dasherize.js";
+import { brand, } from "./pipeline.js";
+import { cli } from "./read.js";
+export function option(named, ...elements) {
+    const added = elements.reduce((value, element) => element(value), param(named, cli([`--${dasherize(named.name)}`])));
+    return brand((route) => {
+        let phases = [...route.phases];
+        let phase = phases.pop();
+        phases.push({
+            ...phase,
+            model: {
+                params: {
+                    ...phase.model.params,
+                    [added.name]: added,
+                },
+                steps: phase.model.steps.concat((current, bindings) => ({
+                    ok: true,
+                    value: {
+                        ...current,
+                        [added.name]: bindings[added.name],
+                    },
+                })),
+            },
+        });
+        return {
+            ...route,
+            phases,
+        };
+    });
+}

package/esm/lib/param.d.ts

@@ -0,0 +1,26 @@
+import { type Decoder } from "./decode.js";
+import { type Check, type Fold, type ModelPatch, type Transform, type TransformElement, type Unary } from "./pipeline.js";
+import type { CLIBinding } from "./read.js";
+import type { Definition, OutputOf, Schema } from "./types.js";
+export interface Param<K extends string, T, C extends Cardinality> extends Definition<K> {
+    schema: Schema<T>;
+    cardinality: C;
+    cli: CLIBinding;
+    decode: Decoder<Representation<C>, Decoded<C>>;
+    env?: string;
+}
+export type Cardinality = "one" | "many";
+export type AnyParam = Param<string, unknown, "one"> | Param<string, unknown, "many">;
+export type ParamModel<K extends string, V> = ModelPatch<{
+    [P in K]: V;
+}>;
+export type Representation<C extends Cardinality> = C extends "many" ? string[] : string;
+export declare function param<const K extends string, const E extends readonly Unary[]>(start: Definition<K>, ...elements: E & Check<ParamZero<K>, E>): Fold<ParamZero<K>, E>;
+export declare function schema<S extends Schema>(schema: S): TransformElement<SchemaTransform<OutputOf<S>>>;
+interface SchemaTransform<Output> extends Transform {
+    readonly input: AnyParam;
+    readonly output: this["input"] extends Param<infer N, unknown, infer C> ? Param<N, Output, C> : never;
+}
+type ParamZero<K extends string> = Param<K, unknown, "one">;
+type Decoded<C extends Cardinality> = C extends "many" ? unknown[] : unknown;
+export {};