@osm-editor-kit/osm-way-chain 0.1.0-alpha.0 → 0.1.0-alpha.2

package/README.md

@@ -1,12 +1,16 @@
 # `@osm-editor-kit/osm-way-chain`
 
-**Status:** First npm **alpha** (`0.1.0-alpha.0`). Publish with `bun run packages:release -- --publish-only` after `npm login`.
+> [!NOTE]
+> This package is an **alpha** release and still under active development. APIs may change; install with the npm `alpha` dist-tag.
 
 ## What it does
 
-Bidirectional OSM way-chain traversal for lane editors: walk connected highway ways from a center segment, score neighbor candidates (same kind, name, ref), surface ambiguous junctions, and orient geometry plus directional tags when a way is reversed.
-
-Includes `mirrorTags` for flipping digitization direction (left/right, forward/backward, oneway, lane pipes, placement), road-like highway predicates (`public` vs `inclusive` inclusion style, Overpass selectors), and a session adapter over in-memory `ParsedOsmData` from `@osm-editor-kit/osm-data`.
+- Walk connected highway ways left and right from a center segment
+- Rank neighbor candidates (same road kind, name, ref)
+- Flag junctions where more than one neighbor is equally good
+- Flip geometry and directional tags when a way is digitized the “wrong” way
+- Compile and match **app-owned** way-selection policies (Overpass + in-memory tags)
+- Adapter for in-memory session data from `@osm-editor-kit/osm-data`
 
 ## Usage
 
@@ -14,11 +18,21 @@ Includes `mirrorTags` for flipping digitization direction (left/right, forward/b
 import type { ParsedOsmData } from '@osm-editor-kit/osm-data'
 import {
   buildChain,
+  buildWaysOverpassQuery,
   createSessionGraphAdapter,
-  isEditableRoadLikeSegment,
-  overpassRoadLikeSelector,
+  matchesOsmWaySelectionSegment,
+  tag,
+  type OsmWaySelectionPolicy,
 } from '@osm-editor-kit/osm-way-chain'
 
+/** App-owned contract — which ways to download / chain. Not package defaults. */
+const wayPolicy: OsmWaySelectionPolicy = {
+  include: [
+    { all: [tag.oneOf('highway', ['residential', 'cycleway', 'path', 'footway', 'steps'])] },
+  ],
+  globalAll: [tag.neq('access', 'private'), tag.neq('access', 'no')],
+}
+
 const graph: ParsedOsmData = /* loaded viewport data */
 const adapter = createSessionGraphAdapter(graph)
 
@@ -26,14 +40,14 @@ const { chain, pendingJunctions } = await buildChain(adapter, {
   centerWayId: 123456,
   maxPerSide: 5,
   candidateFilter: (candidate, from) =>
-    isEditableRoadLikeSegment(candidate) && isEditableRoadLikeSegment(from),
+    matchesOsmWaySelectionSegment(candidate, wayPolicy) &&
+    matchesOsmWaySelectionSegment(from, wayPolicy),
 })
 
-// chain.segments: predecessors, center, successors (ordered)
-// pendingJunctions: nodes where multiple equally good neighbors need a user pick
-
-// Overpass fragment for lane-mode downloads:
-overpassRoadLikeSelector('public')
+// Overpass download for the same policy:
+buildWaysOverpassQuery(wayPolicy, '52.5,13.4,52.51,13.41')
 ```
 
 Implement `OsmDataAdapter` (`getWay`, `getWaysForNode`) for other data sources. Use `extendChainAtJunction` and `recenterChain` to continue after resolving a junction choice.
+
+Legacy `overpassRoadLikeSelector` / `HighwayInclusionStyle` helpers remain as deprecated shims for street-space-editor.

package/dist/highway-filter.d.ts

@@ -1,30 +1,36 @@
 import type { OsmTags } from '@osm-editor-kit/osm-data';
 import type { Segment } from './domain/types';
+import { type OsmWaySelectionPolicy } from './way-selection-policy';
 /**
- * Base highway values used for lane-mode street chain traversal.
- * Link variants (`*_link`) and `highway=busway` are handled separately.
- */
-export declare const ROAD_LIKE_HIGHWAY_BASE_REGEX: RegExp;
-/**
- * How broadly the editor includes low-priority access roads in the map.
- *
- * - `public` (default): skip private access, driveways, emergency access, and parking aisles
- * - `inclusive`: include those ways (previous editor behavior)
+ * @deprecated App-owned concept. Prefer {@link OsmWaySelectionPolicy} defined in the app.
+ * Kept temporarily for street-space-editor call sites.
  */
 export type HighwayInclusionStyle = 'public' | 'inclusive';
+/** @deprecated Prefer app-owned policies. */
 export declare const DEFAULT_HIGHWAY_INCLUSION_STYLE: HighwayInclusionStyle;
+/**
+ * @deprecated Prefer app-owned {@link OsmWaySelectionPolicy}.
+ * Legacy lane-mode car/road selection (incl. `*_link` and `busway`).
+ */
+export declare function createLegacyStreetRoadWayPolicy(style?: HighwayInclusionStyle): OsmWaySelectionPolicy;
+/** @deprecated Prefer matching against an app policy. */
+export declare const ROAD_LIKE_HIGHWAY_BASE_REGEX: RegExp;
+/** @deprecated Prefer policy `globalAll`. */
 export declare const OVERPASS_PUBLIC_ROAD_FILTERS = "[service!=emergency_access][service!=parking_aisle][service!=driveway][access!=private]";
-/** Overpass selector for road-like ways under the given inclusion style. */
+/**
+ * @deprecated Prefer {@link compileOverpassWaySelector} with an app policy.
+ * Returns the legacy fragment expected by `way[${tag}]` callers (no leading `[`).
+ */
 export declare function overpassRoadLikeSelector(style?: HighwayInclusionStyle): string;
-/** Ways that are usually noise in street-space editing (private driveways, etc.). */
+/** @deprecated Prefer app policy + {@link matchesOsmWaySelection}. */
 export declare function isClutterAccessWay(tags: OsmTags): boolean;
-/** Whether a way should be shown/edited under the chosen inclusion style. */
+/** @deprecated Prefer app policy + {@link matchesOsmWaySelection}. */
 export declare function matchesHighwayInclusionStyle(tags: OsmTags, style?: HighwayInclusionStyle): boolean;
-/** Whether OSM tags describe a road-like highway suitable for lane-mode chaining. */
+/** @deprecated Prefer app policy + {@link matchesOsmWaySelection}. */
 export declare function isRoadLikeHighway(tags: OsmTags): boolean;
-/** Road-like highways that pass the active inclusion style. */
+/** @deprecated Prefer app policy + {@link matchesOsmWaySelection}. */
 export declare function isEditableRoadLikeHighway(tags: OsmTags, style?: HighwayInclusionStyle): boolean;
-/** Segment-level predicate for `buildChain` / `filterNeighborCandidates`. */
+/** @deprecated Prefer app policy + {@link matchesOsmWaySelectionSegment}. */
 export declare function isRoadLikeSegment(segment: Segment): boolean;
-/** Segment-level predicate that also applies the editor inclusion style. */
+/** @deprecated Prefer app policy + {@link matchesOsmWaySelectionSegment}. */
 export declare function isEditableRoadLikeSegment(segment: Segment, style?: HighwayInclusionStyle): boolean;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export type { JunctionChoice, NeighborDirection, OsmTags, Segment, SegmentChain, } from './domain/types';
-export { DEFAULT_HIGHWAY_INCLUSION_STYLE, isClutterAccessWay, isEditableRoadLikeHighway, isEditableRoadLikeSegment, isRoadLikeHighway, isRoadLikeSegment, matchesHighwayInclusionStyle, overpassRoadLikeSelector, ROAD_LIKE_HIGHWAY_BASE_REGEX, OVERPASS_PUBLIC_ROAD_FILTERS, type HighwayInclusionStyle, } from './highway-filter';
+export { createLegacyStreetRoadWayPolicy, DEFAULT_HIGHWAY_INCLUSION_STYLE, isClutterAccessWay, isEditableRoadLikeHighway, isEditableRoadLikeSegment, isRoadLikeHighway, isRoadLikeSegment, matchesHighwayInclusionStyle, overpassRoadLikeSelector, ROAD_LIKE_HIGHWAY_BASE_REGEX, OVERPASS_PUBLIC_ROAD_FILTERS, type HighwayInclusionStyle, } from './highway-filter';
+export { buildWaysOverpassQuery, compileOverpassWaySelector, compileOverpassWaySelectors, matchesOsmWaySelection, matchesOsmWaySelectionSegment, tag, type OsmTagPredicate, type OsmWayFilterClause, type OsmWaySelectionPolicy, } from './way-selection-policy';
 export type { OsmDataAdapter } from './ports/OsmDataAdapter';
 export { createSessionGraphAdapter, osmWayToSegment } from './session-graph-adapter';
 export { buildChain, extendChainAtJunction, getOtherEndpointNodeId, getSharedNodeBetween, recenterChain, type BuildChainOptions, type BuildChainResult, } from './traversal/buildChain';

package/dist/index.js

@@ -1,31 +1,147 @@
+// src/way-selection-policy.ts
+var tag = {
+  eq: (key, value) => ({ key, op: "eq", value }),
+  neq: (key, value) => ({ key, op: "neq", value }),
+  oneOf: (key, values) => ({
+    key,
+    op: "in",
+    values
+  }),
+  noneOf: (key, values) => ({
+    key,
+    op: "nin",
+    values
+  }),
+  regex: (key, pattern) => ({ key, op: "regex", pattern }),
+  nregex: (key, pattern) => ({ key, op: "nregex", pattern }),
+  present: (key) => ({ key, op: "present" }),
+  absent: (key) => ({ key, op: "absent" })
+};
+function escapeRegexAlternation(values) {
+  return values.map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+}
+function quoteOverpassValue(value) {
+  if (/^[A-Za-z0-9_:-]+$/.test(value)) return value;
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function escapeOverpassRegex(pattern) {
+  return pattern.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function compileTagPredicate(predicate) {
+  switch (predicate.op) {
+    case "eq":
+      return `[${predicate.key}=${quoteOverpassValue(predicate.value)}]`;
+    case "neq":
+      return `[${predicate.key}!=${quoteOverpassValue(predicate.value)}]`;
+    case "in":
+      return `[${predicate.key}~"^(${escapeRegexAlternation(predicate.values)})$"]`;
+    case "nin":
+      return `[${predicate.key}!~"^(${escapeRegexAlternation(predicate.values)})$"]`;
+    case "regex":
+      return `[${predicate.key}~"${escapeOverpassRegex(predicate.pattern)}"]`;
+    case "nregex":
+      return `[${predicate.key}!~"${escapeOverpassRegex(predicate.pattern)}"]`;
+    case "present":
+      return `[${predicate.key}]`;
+    case "absent":
+      return `[!${predicate.key}]`;
+  }
+}
+function clausePredicates(policy, clause) {
+  return [...clause.all, ...policy.globalAll ?? []];
+}
+function compileOverpassWaySelectors(policy) {
+  if (policy.include.length === 0) {
+    throw new Error("OsmWaySelectionPolicy.include must contain at least one clause");
+  }
+  return policy.include.map(
+    (clause) => clausePredicates(policy, clause).map(compileTagPredicate).join("")
+  );
+}
+function compileOverpassWaySelector(policy) {
+  const selectors = compileOverpassWaySelectors(policy);
+  if (selectors.length !== 1) {
+    throw new Error(
+      `compileOverpassWaySelector expects exactly one include clause, got ${selectors.length}`
+    );
+  }
+  return selectors[0];
+}
+function matchesTagPredicate(tags, predicate) {
+  const raw = tags[predicate.key];
+  switch (predicate.op) {
+    case "eq":
+      return raw === predicate.value;
+    case "neq":
+      return raw !== predicate.value;
+    case "in":
+      return raw != null && predicate.values.includes(raw);
+    case "nin":
+      return raw == null || !predicate.values.includes(raw);
+    case "regex":
+      return raw != null && new RegExp(predicate.pattern).test(raw);
+    case "nregex":
+      return raw == null || !new RegExp(predicate.pattern).test(raw);
+    case "present":
+      return raw != null && raw !== "";
+    case "absent":
+      return raw == null || raw === "";
+  }
+}
+function matchesClause(tags, predicates) {
+  return predicates.every((predicate) => matchesTagPredicate(tags, predicate));
+}
+function matchesOsmWaySelection(tags, policy) {
+  return policy.include.some((clause) => matchesClause(tags, clausePredicates(policy, clause)));
+}
+function matchesOsmWaySelectionSegment(segment, policy) {
+  return matchesOsmWaySelection(segment.tags, policy);
+}
+function buildWaysOverpassQuery(policy, bbox, options) {
+  const selectors = compileOverpassWaySelectors(policy);
+  const timeout = options?.timeoutSeconds ?? 60;
+  const out = options?.out ?? "meta";
+  const union = selectors.map((selector) => `way${selector}(${bbox});`).join("");
+  return `[out:xml][timeout:${timeout}];(${union});(._;>;);out ${out};`;
+}
+
 // src/highway-filter.ts
-var ROAD_LIKE_HIGHWAY_BASE_REGEX = /^motorway|trunk|primary|secondary|tertiary|unclassified|residential|living_street|service/;
 var DEFAULT_HIGHWAY_INCLUSION_STYLE = "public";
-var CLUTTER_SERVICE_VALUES = /* @__PURE__ */ new Set(["driveway", "emergency_access", "parking_aisle"]);
+function createLegacyStreetRoadWayPolicy(style = DEFAULT_HIGHWAY_INCLUSION_STYLE) {
+  const highway = tag.regex(
+    "highway",
+    "^(motorway|trunk|primary|secondary|tertiary|unclassified|residential|living_street|service)(_link)?$|^busway$"
+  );
+  if (style === "inclusive") {
+    return { include: [{ all: [highway] }] };
+  }
+  return {
+    include: [{ all: [highway] }],
+    globalAll: [
+      tag.neq("access", "private"),
+      tag.noneOf("service", ["emergency_access", "parking_aisle", "driveway"])
+    ]
+  };
+}
+var ROAD_LIKE_HIGHWAY_BASE_REGEX = /^motorway|trunk|primary|secondary|tertiary|unclassified|residential|living_street|service/;
 var OVERPASS_PUBLIC_ROAD_FILTERS = "[service!=emergency_access][service!=parking_aisle][service!=driveway][access!=private]";
 function overpassRoadLikeSelector(style = DEFAULT_HIGHWAY_INCLUSION_STYLE) {
-  const base = 'highway~"^motorway|trunk|primary|secondary|tertiary|unclassified|residential|service|living_street"';
-  if (style === "inclusive") return base;
-  return base + OVERPASS_PUBLIC_ROAD_FILTERS;
+  return compileOverpassWaySelector(createLegacyStreetRoadWayPolicy(style)).slice(1);
 }
 function isClutterAccessWay(tags) {
   if (tags.access === "private") return true;
   const service = tags.service;
-  return service != null && CLUTTER_SERVICE_VALUES.has(service);
+  return service === "driveway" || service === "emergency_access" || service === "parking_aisle";
 }
 function matchesHighwayInclusionStyle(tags, style = DEFAULT_HIGHWAY_INCLUSION_STYLE) {
   if (style === "inclusive") return true;
   return !isClutterAccessWay(tags);
 }
 function isRoadLikeHighway(tags) {
-  const highway = tags.highway;
-  if (!highway) return false;
-  if (highway === "busway") return true;
-  const base = highway.endsWith("_link") ? highway.slice(0, -"_link".length) : highway;
-  return ROAD_LIKE_HIGHWAY_BASE_REGEX.test(base);
+  return matchesOsmWaySelection(tags, createLegacyStreetRoadWayPolicy("inclusive"));
 }
 function isEditableRoadLikeHighway(tags, style = DEFAULT_HIGHWAY_INCLUSION_STYLE) {
-  return isRoadLikeHighway(tags) && matchesHighwayInclusionStyle(tags, style);
+  return matchesOsmWaySelection(tags, createLegacyStreetRoadWayPolicy(style));
 }
 function isRoadLikeSegment(segment) {
   return isRoadLikeHighway(segment.tags);
@@ -396,4 +512,4 @@ function getSharedNodeBetween(a, b) {
   return void 0;
 }
 
-export { DEFAULT_HIGHWAY_INCLUSION_STYLE, OVERPASS_PUBLIC_ROAD_FILTERS, ROAD_LIKE_HIGHWAY_BASE_REGEX, buildChain, createSessionGraphAdapter, extendChainAtJunction, filterNeighborCandidates, getEndpointNodeId, getKindKey, getOtherEndpointNodeId, getSharedNodeBetween, isClutterAccessWay, isEditableRoadLikeHighway, isEditableRoadLikeSegment, isReversedAtNode, isRoadLikeHighway, isRoadLikeSegment, matchesHighwayInclusionStyle, mirrorTags, normalizeTagsForDirection, orientNeighbor, osmWayToSegment, overpassRoadLikeSelector, pickBestNeighbor, recenterChain, sameKind, scoreNeighborCandidate, swapLeftRightKey };
+export { DEFAULT_HIGHWAY_INCLUSION_STYLE, OVERPASS_PUBLIC_ROAD_FILTERS, ROAD_LIKE_HIGHWAY_BASE_REGEX, buildChain, buildWaysOverpassQuery, compileOverpassWaySelector, compileOverpassWaySelectors, createLegacyStreetRoadWayPolicy, createSessionGraphAdapter, extendChainAtJunction, filterNeighborCandidates, getEndpointNodeId, getKindKey, getOtherEndpointNodeId, getSharedNodeBetween, isClutterAccessWay, isEditableRoadLikeHighway, isEditableRoadLikeSegment, isReversedAtNode, isRoadLikeHighway, isRoadLikeSegment, matchesHighwayInclusionStyle, matchesOsmWaySelection, matchesOsmWaySelectionSegment, mirrorTags, normalizeTagsForDirection, orientNeighbor, osmWayToSegment, overpassRoadLikeSelector, pickBestNeighbor, recenterChain, sameKind, scoreNeighborCandidate, swapLeftRightKey, tag };

package/dist/way-selection-policy.d.ts

@@ -0,0 +1,64 @@
+import type { OsmTags } from '@osm-editor-kit/osm-data';
+import type { Segment } from './domain/types';
+/**
+ * Atomic tag predicate. Compiles 1:1 to Overpass filter syntax and the same
+ * semantics when matching in-memory `OsmTags` (missing tag matches `neq` / `nin`
+ * / `absent`, same as Overpass).
+ */
+export type OsmTagPredicate = {
+    readonly key: string;
+    readonly op: 'eq' | 'neq';
+    readonly value: string;
+} | {
+    readonly key: string;
+    readonly op: 'in' | 'nin';
+    readonly values: readonly string[];
+} | {
+    readonly key: string;
+    readonly op: 'regex' | 'nregex';
+    readonly pattern: string;
+} | {
+    readonly key: string;
+    readonly op: 'present' | 'absent';
+};
+/** One AND-group of tag predicates — one `way[...]` branch in Overpass. */
+export type OsmWayFilterClause = {
+    readonly all: readonly OsmTagPredicate[];
+};
+/**
+ * Declarative way-selection policy (app-owned contract).
+ *
+ * - `include`: OR — union of Overpass `way[...](bbox)` statements
+ * - `globalAll`: AND — appended to every include clause (e.g. access exclusions)
+ */
+export type OsmWaySelectionPolicy = {
+    readonly include: readonly OsmWayFilterClause[];
+    readonly globalAll?: readonly OsmTagPredicate[];
+};
+/** Ergonomic constructors for {@link OsmTagPredicate}. */
+export declare const tag: {
+    readonly eq: (key: string, value: string) => OsmTagPredicate;
+    readonly neq: (key: string, value: string) => OsmTagPredicate;
+    readonly oneOf: (key: string, values: readonly string[]) => OsmTagPredicate;
+    readonly noneOf: (key: string, values: readonly string[]) => OsmTagPredicate;
+    readonly regex: (key: string, pattern: string) => OsmTagPredicate;
+    readonly nregex: (key: string, pattern: string) => OsmTagPredicate;
+    readonly present: (key: string) => OsmTagPredicate;
+    readonly absent: (key: string) => OsmTagPredicate;
+};
+/**
+ * Compiles each include clause to an Overpass way-filter suffix, e.g.
+ * `[highway=cycleway][access!=private]`.
+ * Callers wrap these in `way…(bbox)` union statements.
+ */
+export declare function compileOverpassWaySelectors(policy: OsmWaySelectionPolicy): string[];
+/** Single selector when the policy has exactly one include clause; otherwise throws. */
+export declare function compileOverpassWaySelector(policy: OsmWaySelectionPolicy): string;
+/** Whether OSM tags match the policy (OR of include clauses, each with globalAll). */
+export declare function matchesOsmWaySelection(tags: OsmTags, policy: OsmWaySelectionPolicy): boolean;
+export declare function matchesOsmWaySelectionSegment(segment: Segment, policy: OsmWaySelectionPolicy): boolean;
+/** Builds Overpass QL that downloads matching ways (+ their nodes) for a bbox string. */
+export declare function buildWaysOverpassQuery(policy: OsmWaySelectionPolicy, bbox: string, options?: {
+    readonly timeoutSeconds?: number;
+    readonly out?: 'meta' | 'body';
+}): string;

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@osm-editor-kit/osm-way-chain",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "description": "Traverse and orient connected OSM highway ways for multi-segment editing sessions.",
+  "homepage": "https://github.com/osmberlin/street-space-editor/tree/main/packages/osm-way-chain",
   "license": "MIT",
   "author": "Tobias Jordans",
   "repository": {
@@ -9,11 +10,11 @@
     "url": "git+https://github.com/osmberlin/street-space-editor.git",
     "directory": "packages/osm-way-chain"
   },
-  "type": "module",
-  "sideEffects": false,
   "files": [
     "dist"
   ],
+  "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",