@mark1russell7/highways 0.8.1 → 0.9.0

package/src/strategies/options.ts

@@ -26,6 +26,11 @@ export interface NumberOption extends OptionBase {
   readonly special?: readonly number[];
   /** These values are the notable values of the option: the default and the values of the sweeps of the benchmark. */
   readonly marks?: readonly number[];
+  /**
+   * These values are the only valid values of the option, in the order of a control. A control shows them as a list, and a sweep gives them.
+   * Without them, each value on the range is valid.
+   */
+  readonly values?: readonly number[];
   /** The strategy uses this value when the caller and `defaults` give no value. */
   readonly default?: number;
 }
@@ -42,6 +47,11 @@ export interface EnumOption<V extends string = string> extends OptionBase {
   readonly type: "enum";
   /** The values of the option, in the order of a control. */
   readonly values: readonly V[];
+  /**
+   * With `function`, the option also takes a rule of the caller in place of a name. A control sets only the names.
+   * Each name is a known rule of the strategy.
+   */
+  readonly custom?: "function";
   /** The strategy uses this value when the caller and `defaults` give no value. */
   readonly default?: V;
 }
@@ -61,8 +71,19 @@ export interface ValueOption<V = unknown> extends OptionBase {
 /** The declaration of one option of any type. */
 export type AnyOption = NumberOption | BooleanOption | EnumOption | ValueOption;
 
-/** The declaration that fits the type of an option value: numbers, booleans, string unions or other values. */
-export type OptionDeclaration<V> = [V] extends [number] ? NumberOption : [V] extends [boolean] ? BooleanOption : [V] extends [string] ? EnumOption<V> : ValueOption<V>;
+/**
+ * The declaration that fits the type of an option value: numbers, booleans, string unions or other values.
+ * A union of strings and other values takes an enum of the strings or a value declaration. An example is a rule or the name of a rule.
+ */
+export type OptionDeclaration<V> = [V] extends [number]
+  ? NumberOption
+  : [V] extends [boolean]
+    ? BooleanOption
+    : [V] extends [string]
+      ? EnumOption<V>
+      : [Extract<V, string>] extends [never]
+        ? ValueOption<V>
+        : EnumOption<Extract<V, string>> | ValueOption<V>;
 
 /** The declarations of the options of a strategy. The schema has one declaration for each key of the options type, and no other key. */
 export type OptionSchema<O> = { readonly [K in keyof O]-?: OptionDeclaration<NonNullable<O[K]>> };
@@ -139,6 +160,7 @@ function issueOf(key: string, value: unknown, d: AnyOption): OptionIssue | undef
     case "integer": {
       if (typeof value !== "number" || Number.isNaN(value)) return issue("type", `The option "${key}" takes a number.`);
       if (isSpecial(d, value)) return undefined;
+      if (d.values !== undefined && !d.values.includes(value)) return issue("value", `The option "${key}" takes ${d.values.join(", ")}, not ${value}.`);
       if (value < d.min || value > d.max) return issue("range", `The option "${key}" is ${value}, out of the range ${d.min} to ${d.max}.`);
       if (d.type === "integer" && !Number.isInteger(value)) return issue("integer", `The option "${key}" takes a whole number, not ${value}.`);
       return undefined;
@@ -146,6 +168,7 @@ function issueOf(key: string, value: unknown, d: AnyOption): OptionIssue | undef
     case "boolean":
       return typeof value === "boolean" ? undefined : issue("type", `The option "${key}" takes true or false.`);
     case "enum":
+      if (d.custom === "function" && typeof value === "function") return undefined;
       return d.values.includes(value as string) ? undefined : issue("value", `The option "${key}" takes ${d.values.join(", ")}, not ${String(value)}.`);
     case "function":
       return typeof value === "function" ? undefined : issue("type", `The option "${key}" takes a function.`);
@@ -176,7 +199,7 @@ export function checkOptions<S extends Step, O extends object>(strategy: Strateg
 
 /**
  * This function moves each number option into the range of its declaration, for a control. An integer option gets the nearest whole number.
- * A special value stays. The function keeps each other value as it is. `checkOptions` reports the values that this function cannot correct.
+ * An option with a list of `values` gets the nearest value of the list. A special value stays. The function keeps each other value as it is. `checkOptions` reports the values that this function cannot correct.
  */
 export function clampOptions<S extends Step, O extends object>(strategy: Strategy<S, O>, options: Partial<O>): Partial<O> {
   const schema = schemaOf(strategy);
@@ -184,6 +207,10 @@ export function clampOptions<S extends Step, O extends object>(strategy: Strateg
   for (const [key, value] of Object.entries(options)) {
     const d = schema[key];
     if (!d || (d.type !== "number" && d.type !== "integer") || typeof value !== "number" || Number.isNaN(value) || isSpecial(d, value)) continue;
+    if (d.values !== undefined && d.values.length > 0) {
+      out[key] = d.values.reduce((best, v) => (Math.abs(v - value) < Math.abs(best - value) ? v : best));
+      continue;
+    }
     const v = Math.min(d.max, Math.max(d.min, value));
     out[key] = d.type === "integer" ? Math.min(d.max, Math.max(d.min, Math.round(v))) : v;
   }
@@ -211,7 +238,7 @@ function rangeValues(d: NumberOption, count: number): number[] {
 
 /**
  * This function gives the values of a sweep of one option declaration.
- * A number option gives its `marks`, or `count` values on its range and its scale. A boolean gives `false` and `true`. An enum gives its values.
+ * A number option gives its `marks`, or its list of `values`, or `count` values on its range and its scale. A boolean gives `false` and `true`. An enum gives its values.
  * An option of another type has no sweep, so the function throws an error.
  */
 export function sweepValues(declaration: AnyOption, options: SweepOptions = {}): unknown[] {
@@ -219,6 +246,7 @@ export function sweepValues(declaration: AnyOption, options: SweepOptions = {}):
     case "number":
     case "integer": {
       if (options.count === undefined && declaration.marks !== undefined) return [...declaration.marks];
+      if (declaration.values !== undefined) return [...declaration.values];
       const values = rangeValues(declaration, options.count ?? SWEEP_COUNT);
       return options.special ? [...values, ...(declaration.special ?? []).filter((s) => !values.includes(s))] : values;
     }
@@ -268,6 +296,10 @@ function declarationIssues(key: string, d: AnyOption): string[] {
     if (d.type === "integer" && (!Number.isInteger(d.min) || !Number.isInteger(d.max))) out.push(`The integer option "${key}" has a range that is not whole.`);
     if (d.step !== undefined && !(d.step > 0)) out.push(`The option "${key}" has the step ${d.step}. A step is more than 0.`);
     if (d.scale === "log" && !(d.min > 0)) out.push(`The option "${key}" has the scale log and the min ${d.min}. The scale log needs a min above 0.`);
+    if (d.values !== undefined && d.values.length === 0) out.push(`The number option "${key}" has an empty list of values.`);
+    for (const v of d.values ?? []) {
+      if (v < d.min || v > d.max || (d.type === "integer" && !Number.isInteger(v))) out.push(`The value ${v} of the option "${key}" is not on its range ${d.min} to ${d.max}.`);
+    }
     for (const v of [...(d.marks ?? []), ...(d.default === undefined ? [] : [d.default])]) {
       const issue = issueOf(key, v, d);
       if (issue) out.push(issue.message);

package/src/strategies/schemas.ts

@@ -49,12 +49,15 @@ import type { TraclusOptions } from "../highways/traclus/index.ts";
 import type { WeiszfeldOptions } from "../highways/weiszfeld/index.ts";
 import type { WspdOptions } from "../highways/wspd/index.ts";
 import type { ZipperOptions } from "../highways/zipper/index.ts";
+import type { LaneStretchOptions } from "../lane-orders/stretch/index.ts";
+import type { DepthLevelOptions } from "../levels/depths/index.ts";
 import type { CornersOptions } from "../routers/corners.ts";
 import type { SectionsOptions } from "../routers/sections.ts";
 import type { SharedOptions } from "../routers/shared.ts";
-import type { TrunksOptions } from "../routers/trunks.ts";
+import { GROUP_RULE_NAMES, type GroupRuleName, type TrunksOptions } from "../routers/trunks.ts";
 import type { SectionOptions } from "../sections.ts";
 import type { WayOptions } from "../ways.ts";
+import type { PipelineOptions } from "../whole/pipeline/index.ts";
 import type { RunOrder } from "../segments.ts";
 import type { ClothoidStrategyOptions, HighwayStrategyOptions, LevelRoomPreset, RadiusOptions, RoomPreset, RouterPreset, SmoothStrategyOptions, TensionOptions } from "./builtins.ts";
 import type { EnumOption, NumberOption, OptionSchema } from "./options.ts";
@@ -69,6 +72,24 @@ const WAY_SCHEMA: OptionSchema<WayOptions> = {
   smooth: { type: "boolean", default: false, describe: "With `true`, a way in clear view uses the inflection rule, and the other ways get round corners." },
 };
 
+/** The declarations of the options of the stretch order (LANE-STRETCH): the method and the passes of `sifting`. A generator can list each value. */
+export const LANE_STRETCH_SCHEMA: OptionSchema<LaneStretchOptions> = {
+  method: {
+    type: "enum",
+    values: ["none", "consensus", "periphery", "sifting"],
+    default: "sifting",
+    describe: "The order of each stretch: the order of each run alone, the order of the pair relation, the order of the largest run, or the order of the pair relation after sifting.",
+  },
+  passes: { type: "integer", min: 1, max: 4, step: 1, default: 2, describe: "The number of passes of the method `sifting`. In each pass, each edge moves to its best place." },
+};
+
+/**
+ * The declaration of the grouping rule of the edges: a name of `GROUP_RULE_NAMES`. A new name of the list needs no change here.
+ * The option also takes a rule of the caller (`custom`), so the old value form stays valid.
+ * The `defaults` of a strategy keep the rule `byCollection`, and the declaration gives its name `collection` as its `default`.
+ */
+const EDGE_RULE: EnumOption<GroupRuleName> = { type: "enum", values: GROUP_RULE_NAMES, custom: "function", describe: "The grouping rule." };
+
 /** The declaration of the lane order of the shared ways of the routers `trunks` and `shared`. */
 const LANE_ORDER: EnumOption<RunOrder> = {
   type: "enum",
@@ -97,12 +118,14 @@ export const CORNERS_SCHEMA: OptionSchema<RouterPreset<CornersOptions>> = {
     default: 0,
     describe: "With a gap above 0, the free plugs of a side keep their order and at least this gap (WILD-002). 0 keeps each plug where it is.",
   },
+  plug: { type: "strategy", step: "plugs", describe: "The plug rule: a strategy of the step `plugs`. Without it, the option `plugs` places the plugs." },
+  plugOptions: { type: "object", describe: "The options of the strategy `plug`." },
 };
 
 /** The declarations of the options of the router `trunks`. */
 export const TRUNKS_SCHEMA: OptionSchema<RouterPreset<TrunksOptions>> = {
   ...WAY_SCHEMA,
-  rule: { type: "function", describe: "The grouping rule. The edges from one plug with one key share a trunk." },
+  rule: { ...EDGE_RULE, default: "collection", describe: "The grouping rule. The edges from one plug with one key share a trunk. With `all`, each edge has one key." },
   split: { type: "number", min: 0.1, max: 0.9, step: 0.05, default: 0.5, describe: "The split point is at this share of the way to the center of the targets." },
   minSize: { type: "integer", min: 1, max: 8, step: 1, default: 2, describe: "A group with fewer edges stays unbundled." },
   laneOrder: LANE_ORDER,
@@ -128,10 +151,10 @@ export const TRUNKS_SCHEMA: OptionSchema<RouterPreset<TrunksOptions>> = {
   bf: { type: "number", min: 0, max: 1, step: 0.05, default: 0.4, describe: "The balancing factor of the fan `tree`. 0 gives the least ink, and a larger factor gives more direct routes." },
 };
 
-/** The declarations of the options of the routers `shared` and `shared-all`. */
+/** The declarations of the options of the router `shared` and of the highway strategy `shared-ways`. */
 export const SHARED_SCHEMA: OptionSchema<RouterPreset<SharedOptions>> = {
   ...WAY_SCHEMA,
-  rule: { type: "function", describe: "The edges with one key share their ways. Without a rule, all edges share." },
+  rule: { ...EDGE_RULE, default: "collection", describe: "The edges with one key share their ways. With `collection`, the key is `data.collection`. With `all`, all edges share." },
   discount: {
     type: "number",
     min: 0.05,
@@ -179,6 +202,18 @@ export const SHARED_SCHEMA: OptionSchema<RouterPreset<SharedOptions>> = {
     default: "corner",
     describe: "With `corner`, a route joins a run at a corner of the graph. With `snell`, it joins at the angle `acos(d)` (NAT-035).",
   },
+  stretchOrder: {
+    ...LANE_STRETCH_SCHEMA.method,
+    default: "none",
+    describe: "With `none`, each run gets its lane order alone. With the other values, the runs that follow each other share one order (LANE-STRETCH).",
+  },
+  siftPasses: LANE_STRETCH_SCHEMA.passes,
+};
+
+/** The declarations of the options of the router `shared-all`. It sets no rule, so all edges share. Thus its rule has no `default`. */
+export const SHARED_ALL_SCHEMA: OptionSchema<RouterPreset<SharedOptions>> = {
+  ...SHARED_SCHEMA,
+  rule: { ...EDGE_RULE, describe: "The edges with one key share their ways. Without a rule, or with `all`, all edges share. With `collection`, the key is `data.collection`." },
 };
 
 /** The declarations of the options of the highway strategy `corridors` (HWY-031). */
@@ -248,6 +283,8 @@ export const SECTIONS_SCHEMA: OptionSchema<RouterPreset<SectionsOptions>> = {
   group: { type: "strategy", step: "group", describe: "The grouping rule: a strategy of the step `group`. Without it, the router uses the quadtree." },
   groupOptions: { type: "object", describe: "The options of the strategy `group`." },
   levels: { type: "list", describe: "The depths of the tree that get a level with groups. Without it, each depth gets a level." },
+  level: { type: "strategy", step: "levels", describe: "The level rule: a strategy of the step `levels`. Without it, the router uses the strategy `depths`." },
+  levelOptions: { type: "object", describe: "The options of the strategy `level`. They go over the level options of the router." },
   laneOrder: RUN_LANE_ORDER,
 };
 
@@ -553,7 +590,7 @@ export const EDGE_PATH_SCHEMA: OptionSchema<EdgePathOptions> = {
 
 /** The declarations of the options of the highway strategy `soft-keys` (HWY-019). */
 export const SOFT_KEY_SCHEMA: OptionSchema<SoftKeyOptions> = {
-  rule: { type: "function", describe: "The rule that gives the key of each edge. Two different keys add the distance `lambda`." },
+  rule: { ...EDGE_RULE, default: "collection", describe: "The rule that gives the key of each edge. Two different keys add the distance `lambda`. With `all`, the keys add no distance." },
   lambda: { type: "number", min: 0, max: 2, step: 0.05, marks: [0, 0.25, 1], default: 0.25, describe: "The distance that two different keys add. A very large value keeps the keys apart." },
   tau: { type: "number", min: 0.1, max: 1.5, step: 0.05, marks: [0.3, 0.5, 1], default: 0.5, describe: "Two clusters join while their distance is this value or less." },
   attributes: { type: "list", default: [], describe: "The names of number fields of `data` that add a distance." },
@@ -862,3 +899,29 @@ export const SCALE_SPACE_SCHEMA: OptionSchema<ScaleSpaceOptions> = {
   minSize: { type: "integer", min: 2, max: 16, step: 1, default: 2, describe: "A cluster with this number of edges or more gets highways." },
   spine: GROUP_SPINE,
 };
+
+/** The declarations of the options of the level strategy `depths`: the limits of the level links, and the depths that get a level. */
+export const DEPTHS_SCHEMA: OptionSchema<DepthLevelOptions> = {
+  margin: WAY_SCHEMA.margin,
+  k: WAY_SCHEMA.k,
+  tightMargin: SECTIONS_SCHEMA.tightMargin,
+  plugInset: SECTIONS_SCHEMA.plugInset,
+  throughCost: SECTIONS_SCHEMA.throughCost,
+  levels: SECTIONS_SCHEMA.levels,
+};
+
+/** The declarations of the options of the whole strategy `pipeline`. */
+export const PIPELINE_SCHEMA: OptionSchema<PipelineOptions> = {
+  router: { type: "strategy", step: "router", describe: "The router. A highway plan takes its place." },
+  routerOptions: { type: "object", describe: "The options of the router." },
+  highway: { type: "strategy", step: "highway", describe: "The highway strategy. With it, the plan and `follow` give the routes. Without it, the router routes." },
+  highwayOptions: { type: "object", describe: "The options of the highway strategy." },
+  group: { type: "strategy", step: "group", describe: "The grouping rule of a router that reads one, for example `sections`." },
+  groupOptions: { type: "object", describe: "The options of the grouping rule." },
+  plugs: { type: "strategy", step: "plugs", describe: "The plug rule of a router that reads one, for example `corners`." },
+  plugOptions: { type: "object", describe: "The options of the plug rule." },
+  levels: { type: "strategy", step: "levels", describe: "The level rule of a router that reads one, for example `sections`." },
+  levelOptions: { type: "object", describe: "The options of the level rule." },
+  room: { type: "strategy", step: "room", describe: "The room strategy. With it, the gaps of the board open before the routes. Without it, the board stays." },
+  roomOptions: { type: "object", describe: "The options of the room strategy." },
+};

package/src/whole/pipeline/index.ts

@@ -0,0 +1,66 @@
+import { highwayRouterStrategy } from "../../highways/router.ts";
+import type { Graph } from "../../model.ts";
+import { openGaps, roomLinks } from "../../room/index.ts";
+import { asRouter, type Step, type Strategy, type WholeOutput } from "../../strategies/model.ts";
+import { listOptions } from "../../strategies/options.ts";
+
+/**
+ * The options of the whole strategy `pipeline`: one strategy of each step, and the options of each one.
+ * A rule of the steps `group`, `plugs` and `levels` acts only on a router that reads a rule of that step (`strategyKey`).
+ */
+export interface PipelineOptions {
+  /** The router. A highway plan takes its place. */
+  readonly router: Strategy<"router">;
+  /** The options of the router. */
+  readonly routerOptions?: object;
+  /** The highway strategy. With it, the plan of the strategy and `follow` give the routes, not the router. */
+  readonly highway?: Strategy<"highway">;
+  /** The options of the highway strategy. */
+  readonly highwayOptions?: object;
+  /** The grouping rule of a router that reads one, for example `sections`. */
+  readonly group?: Strategy<"group">;
+  /** The options of the grouping rule. */
+  readonly groupOptions?: object;
+  /** The plug rule of a router that reads one, for example `corners`. */
+  readonly plugs?: Strategy<"plugs">;
+  /** The options of the plug rule. */
+  readonly plugOptions?: object;
+  /** The level rule of a router that reads one, for example `sections`. */
+  readonly levels?: Strategy<"levels">;
+  /** The options of the level rule. */
+  readonly levelOptions?: object;
+  /** The room strategy. With it, the pipeline opens the gaps of the board before the routes (`openGaps`). */
+  readonly room?: Strategy<"room">;
+  /** The options of the room strategy. */
+  readonly roomOptions?: object;
+}
+
+/**
+ * This function gives the key of the option of a router that takes a strategy of one step.
+ * It gives `undefined` when the router has no such option.
+ * The schema of the router declares the option with the type `strategy` and the step. The options of that strategy have the key `<key>Options`.
+ */
+export function strategyKey(router: Strategy<"router">, step: Step): string | undefined {
+  return listOptions(router).find((o) => o.declaration.type === "strategy" && o.declaration.step === step)?.key;
+}
+
+/**
+ * This function runs the whole strategy `pipeline` on one graph. The room strategy opens the gaps of the board first.
+ * A highway strategy makes its plan, and `follow` routes the plan. Otherwise the router routes, with each rule of the steps `group`, `plugs` and `levels` that it reads.
+ * The output has the board and the routes. The function does not examine the `maxNodes` of the router.
+ */
+export function runPipeline(graph: Graph, options: PipelineOptions): WholeOutput {
+  const board = options.room ? { nodes: openGaps(graph.nodes, options.room.run({ items: graph.nodes, links: roomLinks(graph) }, options.roomOptions)), edges: graph.edges } : graph;
+  if (options.highway) return { graph: board, result: asRouter(highwayRouterStrategy(options.highway) as Strategy<"router">, options.highwayOptions).route(board) };
+  let routerOptions = options.routerOptions;
+  const rules: readonly [Step, Strategy<Step> | undefined, object | undefined][] = [
+    ["group", options.group, options.groupOptions],
+    ["plugs", options.plugs, options.plugOptions],
+    ["levels", options.levels, options.levelOptions],
+  ];
+  for (const [step, rule, own] of rules) {
+    const key = rule && strategyKey(options.router, step);
+    if (key) routerOptions = { ...routerOptions, [key]: rule, [`${key}Options`]: own };
+  }
+  return { graph: board, result: asRouter(options.router, routerOptions).route(board) };
+}