@bomb.sh/router 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bomb.sh/router",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Configuration for programs",
   "author": "Bombshell Authors (https://github.com/bombshell-dev)",
   "repository": {

package/src/_dnt.polyfills.ts

@@ -1,27 +0,0 @@
-// https://github.com/tc39/proposal-accessible-object-hasownproperty/blob/main/polyfill.js
-if (!Object.hasOwn) {
-  Object.defineProperty(Object, "hasOwn", {
-    value: function (object: any, property: any) {
-      if (object == null) {
-        throw new TypeError("Cannot convert undefined or null to object");
-      }
-      return Object.prototype.hasOwnProperty.call(Object(object), property);
-    },
-    configurable: true,
-    enumerable: false,
-    writable: true,
-  });
-}
-
-declare global {
-  interface Object {
-    /**
-     * Determines whether an object has a property with the specified name.
-     * @param o An object.
-     * @param v A property name.
-     */
-    hasOwn(o: object, v: PropertyKey): boolean;
-  }
-}
-
-export {};

package/src/lib/argument.ts

@@ -1,100 +0,0 @@
-import { type AnyParam, type Param, param, type ParamModel } from "./param.js";
-import {
-  brand,
-  type Check,
-  type Fold,
-  type ModelElement,
-  type Unary,
-} from "./pipeline.js";
-import type { CLIRead, ReadCLI } from "./read.js";
-import type { Word } from "./tokenize.js";
-import type { AnyRoute, Definition } from "./types.js";
-
-export function argument<
-  const N extends string,
-  const E extends readonly Unary[],
->(
-  named: Definition<N>,
-  ...elements: E & Check<Zero<N>, E>
-): ElementOf<N, Fold<Zero<N>, E>> {
-  const added = elements.reduce<unknown>(
-    (value, element) => element(value as never),
-    param(named, positional),
-  ) as AnyParam;
-
-  return brand<ElementOf<N, Fold<Zero<N>, E>>>(
-    (route: AnyRoute) => {
-      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,
-      };
-    },
-  );
-}
-
-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;
-
-function positional<P extends AnyParam>(param: P): P {
-  return {
-    ...param,
-    cli: {
-      read,
-      syntax: {
-        type: "argument",
-        label: `<${param.name.toUpperCase()}>`,
-      },
-    },
-  };
-}
-
-const read: ReadCLI = (tokens): CLIRead => {
-  let claim = tokens.claimOne((token): token is Word => token.type === "word");
-  let [word] = claim.tokens;
-
-  return word
-    ? {
-      claim,
-      result: {
-        ok: true,
-        value: { exists: true, value: word.text },
-        issues: [],
-      },
-    }
-    : nothing(tokens);
-};
-
-function nothing(tokens: Parameters<ReadCLI>[0]): CLIRead {
-  let claim = tokens.claimAll(() => false);
-
-  return {
-    claim,
-    result: {
-      ok: true,
-      value: { exists: false },
-      issues: [],
-    },
-  };
-}

package/src/lib/bind.ts

@@ -1,421 +0,0 @@
-import { Just, type Maybe } from "./maybe.js";
-import type { AnyParam, Param } from "./param.js";
-import type { CLIRead, Symbol } from "./read.js";
-import type { Rest } from "./rest.js";
-import type { Result } from "./result.js";
-import type { Word } from "./tokenize.js";
-import type { TokenInput, Tokenizer, TokenRange } from "./tokenizer.js";
-import type { AnyPhase, Issue, OutputOf, Path } from "./types.js";
-
-export interface Binding<T> {
-  readonly rest: Rest;
-  readonly result: Result<T>;
-}
-
-export interface PhaseBinding {
-  readonly rest: Rest;
-  readonly model: Record<string, unknown>;
-  readonly issues: Issue[];
-  readonly valid: boolean;
-}
-
-export interface PhaseSegment {
-  readonly range: TokenRange;
-  readonly path: Path;
-}
-
-export function fromCLI<P extends Param<string, unknown, "one">>(options: {
-  readonly param: P;
-  readonly view: TokenInput<Symbol>;
-  readonly rest: Rest;
-}): Maybe<Binding<OutputOf<P["schema"]>>> {
-  let { param, view, rest } = options;
-  return fromRead(param, param.cli.read(view), rest);
-}
-
-export function fromValues<P extends AnyParam>(options: {
-  readonly param: P;
-  readonly route: Path;
-  readonly rest: Rest;
-}): Maybe<Binding<OutputOf<P["schema"]>>> {
-  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<P extends AnyParam>(options: {
-  readonly param: P;
-  readonly route: Path;
-  readonly rest: Rest;
-}): Maybe<Binding<OutputOf<P["schema"]>>> {
-  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: {
-  readonly phase: AnyPhase;
-  readonly segment: PhaseSegment;
-  readonly rest: Rest;
-}): PhaseBinding {
-  let { phase, segment } = options;
-  let rest = options.rest;
-  let params = Object.values(phase.model.params) as AnyParam[];
-  let pending = new Map(params.map((param) => [param.name, param]));
-  let results = new Map<string, Result<unknown>>();
-
-  function settle(
-    param: AnyParam,
-    binding: Binding<unknown>,
-  ): void {
-    rest = binding.rest;
-    results.set(param.name, binding.result);
-    pending.delete(param.name);
-  }
-
-  function accept(
-    param: AnyParam,
-    attempt: Maybe<Binding<unknown>>,
-  ): void {
-    if (!attempt.exists) {
-      return;
-    }
-
-    settle(param, attempt.value);
-  }
-
-  let captures = new Map<string, Capture>();
-
-  // 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: {
-      param: AnyParam;
-      read: CLIRead;
-      index: number;
-    } | undefined;
-
-    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: Maybe<unknown[]>[] = values.every(
-          (value): value is string => 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: Record<string, unknown> = {};
-  let issues: Issue[] = [];
-  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<P extends Param<string, unknown, "one">>(
-  param: P,
-  read: CLIRead,
-  rest: Rest,
-): Maybe<Binding<OutputOf<P["schema"]>>> {
-  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<P extends AnyParam>(
-  param: P,
-  value: unknown,
-  candidates: Maybe<unknown>[],
-  path: string[],
-): Result<OutputOf<P["schema"]>> {
-  if (candidates.length === 0) {
-    return {
-      ok: false,
-      issues: [{
-        message: `unable to decode ${JSON.stringify(value)}`,
-        path,
-      }],
-    };
-  }
-
-  let issues: readonly Issue[] | undefined;
-
-  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<P extends AnyParam>(
-  param: P,
-  value: unknown,
-  path: string[],
-): Result<OutputOf<P["schema"]>> {
-  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<T>(
-  result: Result<T>,
-  issues: readonly Issue[] | undefined,
-): Result<T> {
-  if (!issues || issues.length === 0) {
-    return result;
-  }
-
-  return {
-    ...result,
-    issues: [...issues, ...(result.issues ?? [])],
-  };
-}
-
-function first(tokens: Tokenizer<Symbol>, range: TokenRange): Word | undefined {
-  for (let token of tokens.view({ range })) {
-    if (token.type === "word") {
-      return token;
-    }
-  }
-}
-
-function earliest(tokens: readonly Symbol[]): number {
-  let first = Infinity;
-
-  for (let token of tokens) {
-    first = Math.min(first, token.index);
-  }
-
-  return first;
-}
-
-interface Capture {
-  param: Param<string, unknown, "many">;
-  values: (string | boolean)[];
-  issues: Issue[];
-  failed: boolean;
-}

package/src/lib/checkpoint.ts

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

package/src/lib/command.ts

@@ -1,36 +0,0 @@
-// deno-lint-ignore-file ban-types
-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 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>> {
-  let zero: CommandZero<N> = {
-    ...start,
-    methods: ["help", "execute"],
-    phases: [{
-      model: {
-        params: {},
-        steps: [],
-      },
-      routes: [],
-      values: [],
-      envs: [],
-    }],
-  };
-
-  return elements.reduce<unknown>(
-    (value, element) => element(value as never),
-    zero,
-  ) as Materialize<Fold<CommandZero<N>, E>>;
-}

package/src/lib/dasherize.ts

@@ -1,7 +0,0 @@
-export function dasherize(name: string): string {
-  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/src/lib/decode.ts

@@ -1,55 +0,0 @@
-import { Just, type Maybe, Nothing } from "./maybe.js";
-
-export type Decoder<A, B> = (value: A) => Maybe<B>[];
-
-export const number: Decoder<string, number> = (value) => {
-  if (!numeric.test(value)) {
-    return [Nothing()];
-  }
-
-  let decoded = Number(value);
-  return Number.isFinite(decoded) ? [Just(decoded)] : [Nothing()];
-};
-
-export const scalar: Decoder<string, string | number> = (value) => {
-  return [...number(value), Just(value)];
-};
-
-export const boolean: Decoder<string, boolean> = (value) => {
-  if (value === "true") {
-    return [Just(true)];
-  }
-  if (value === "false") {
-    return [Just(false)];
-  }
-  return [Nothing()];
-};
-
-export function multiple<A, B>(decoder: Decoder<A, B>): Decoder<A[], B[]> {
-  return (input: A[]): Maybe<B[]>[] => {
-    let decodings = input.map(decoder);
-
-    let result: Maybe<B[]>[] = [];
-
-    for (let i = 0; i < decodings.length; i++) {
-      let decoding = decodings[i];
-      for (let j = 0; j < decoding.length; j++) {
-        let row: Maybe<B[]> | undefined = 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/src/lib/definition.ts

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