@tilda-geo/bicycle-infrastructure 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,87 @@
1
+ # `@tilda-geo/bicycle-infrastructure`
2
+
3
+ [npmx](https://npmx.dev/package/@tilda-geo/bicycle-infrastructure) · [npm](https://www.npmjs.com/package/@tilda-geo/bicycle-infrastructure) · [GitHub](https://github.com/FixMyBerlin/tilda-schemas/tree/main/packages/bicycle-infrastructure)
4
+
5
+ > **Role:** the **public TypeScript library** (ESM-only). Given plain OSM tags (e.g. from Overpass), it produces the same bicycle-infrastructure features TILDA’s LUA pipeline would — so QA tools and apps can classify live data without running osm2pgsql.
6
+
7
+ Part of the [tilda-schemas](https://github.com/FixMyBerlin/tilda-schemas) monorepo. Schemas (vocabularies + fixtures) live under [`schemas/`](../../schemas/); this package **implements** them.
8
+
9
+ ```bash
10
+ npm install @tilda-geo/bicycle-infrastructure
11
+ ```
12
+
13
+ ---
14
+
15
+ ## What it does
16
+
17
+ 1. Takes one OSM way’s tags (`Record<string, string>`).
18
+ 2. Applies the same transforms as TILDA LUA (lifecycle, side splitting for `cycleway:left/right` / sidewalks, sanitizers).
19
+ 3. Returns **1..N features** (centerline `self` plus transformed `left`/`right` sides), each with:
20
+ - **`category`** — `Radinfrastrukturkategorie` (primary focus; see [`schemas/bicycle-infrastructure-category`](../../schemas/bicycle-infrastructure-category/))
21
+ - plus surface, smoothness, oneway, separation / buffer / marking, traffic_mode, traffic_sign, surface_color, width
22
+
23
+ Disallowed sanitizer values become `null`, matching TILDA’s GeoJSON export.
24
+
25
+ ```ts
26
+ import { processBikelanes } from '@tilda-geo/bicycle-infrastructure'
27
+
28
+ const features = processBikelanes({
29
+ highway: 'secondary',
30
+ 'cycleway:right': 'lane',
31
+ 'cycleway:right:lane': 'exclusive',
32
+ surface: 'asphalt',
33
+ })
34
+ // → [{ _side: 'right', _prefix: 'cycleway', category: 'cyclewayOnHighway_exclusive',
35
+ // oneway: 'implicit_yes', surface: 'asphalt', ... }, ...]
36
+ ```
37
+
38
+ ---
39
+
40
+ ## How it relates to the rest of the monorepo
41
+
42
+ | Piece | Relationship |
43
+ | --- | --- |
44
+ | [`schemas/bicycle-infrastructure-category`](../../schemas/bicycle-infrastructure-category/) | Source of truth for allowed `category` values + fixtures |
45
+ | [`schemas/bicycle-infrastructure-attributes`](../../schemas/bicycle-infrastructure-attributes/) | Draft vocabularies for non-category fields (fixtures used in tests) |
46
+ | [`bicycle-infrastructure-reconciliation`](../bicycle-infrastructure-reconciliation/) | **Internal** tooling that proves this library ≡ TILDA LUA on a Berlin corpus |
47
+
48
+ ---
49
+
50
+ ## Map to TILDA LUA
51
+
52
+ Ported module-for-module from `tilda-geo` → `processing/topics/roads_bikelanes`:
53
+
54
+ | This package | LUA |
55
+ | --- | --- |
56
+ | `transform/prepare-tags.ts` | `helper/transform_tags/*` |
57
+ | `transform/transformations.ts` | `bikelanes/transformations.lua` |
58
+ | `categories/*` | `bikelanes/bikelane_categories.lua` (+ decision view, sidepath) |
59
+ | `sanitize/*`, `derive/*` | `helper/sanitize_*`, `derive_*` |
60
+ | `index.ts` → `processBikelanes` | `bikelanes/bikelanes.lua` |
61
+
62
+ ---
63
+
64
+ ## Develop / test
65
+
66
+ From the monorepo root:
67
+
68
+ ```bash
69
+ bun install
70
+ bun run build
71
+ bun run --filter '@tilda-geo/bicycle-infrastructure' test
72
+ bun run check-exports
73
+ ```
74
+
75
+ - `test/spec.test.ts` — conformance against `schemas/**/fixtures` (via `test/load-spec.ts`)
76
+ - `test/categories.smoke.test.ts` — cases ported from LUA `__tests__`
77
+
78
+ Berlin corpus check (category agreement ~100%): see the **internal** [reconciliation](../bicycle-infrastructure-reconciliation/) package.
79
+
80
+ Releases use [changesets](https://github.com/changesets/changesets) — see the root README **Release** section (manual publish, same as the smoothness packages).
81
+
82
+ ---
83
+
84
+ ## Known limitations
85
+
86
+ - `_adjoining` / `_isolated` / `_adjoiningOrIsolated` use the raw OSM `is_sidepath` tag (same as LUA categorization). TILDA’s `_is_sidepath` CSV estimate is export-only and does not affect category.
87
+ - `highway=construction` lifecycle is handled; the geometry crossing-length filter (>100 m) is skipped when `_length` is absent (typical for live Overpass tags).
@@ -0,0 +1,274 @@
1
+ /**
2
+ * Raw OSM tags: a plain string→string map. Tag values are `string | undefined`.
3
+ * Internal transformation fields (underscore-prefixed, mirroring the LUA) carry
4
+ * non-string payloads (`_parent` object, `_length` number); they are typed `any` so they
5
+ * stay compatible with the string index signature without polluting tag-value types.
6
+ */
7
+ interface OsmTags {
8
+ [key: string]: string | undefined;
9
+ _side?: 'self' | 'left' | 'right';
10
+ _prefix?: string;
11
+ _infix?: string;
12
+ _parent?: any;
13
+ _parent_highway?: string;
14
+ _length?: any;
15
+ }
16
+ type ImplicitOneWayConfidence = 'high' | 'medium' | 'low' | 'not_applicable';
17
+ interface BikelaneCategory {
18
+ id: string;
19
+ infrastructureExists: boolean;
20
+ implicitOneWay: boolean;
21
+ implicitOneWayConfidence: ImplicitOneWayConfidence;
22
+ copySurfaceSmoothnessFromParent: boolean;
23
+ /** Receives a decision-view of the tags; returns truthy when the category matches. */
24
+ condition: (tags: OsmTags) => boolean | undefined;
25
+ /** Optional post-match mutation of the tags (mirrors LUA `process`). */
26
+ process?: (tags: OsmTags) => void;
27
+ }
28
+ /** One processed bikelane feature (subset of Tilda's exported properties). */
29
+ interface BikelaneResult {
30
+ _side: 'self' | 'left' | 'right';
31
+ _prefix: string | null;
32
+ _infrastructureExists: boolean;
33
+ category: string;
34
+ oneway?: string;
35
+ surface?: string | null;
36
+ surface_source?: string | null;
37
+ surface_confidence?: string | null;
38
+ smoothness?: string | null;
39
+ smoothness_source?: string | null;
40
+ smoothness_confidence?: string | null;
41
+ separation_left?: string | null;
42
+ separation_right?: string | null;
43
+ buffer_left?: number | null;
44
+ buffer_right?: number | null;
45
+ marking_left?: string | null;
46
+ marking_right?: string | null;
47
+ traffic_mode_left?: string | null;
48
+ traffic_mode_right?: string | null;
49
+ surface_color?: string | null;
50
+ traffic_sign?: string | null;
51
+ width?: number | null;
52
+ }
53
+
54
+ /** Port of topics/roads_bikelanes/bikelanes/bikelane_categories.lua — compiled from declarative specs. */
55
+
56
+ declare const CATEGORY_DEFINITIONS: BikelaneCategory[];
57
+ /** First category whose condition matches; runs its `process` on the raw tags. */
58
+ declare function categorizeBikelane(tags: OsmTags): BikelaneCategory | null;
59
+
60
+ /**
61
+ * Analyze which discriminating tags are missing for incomplete bikelane categories.
62
+ * Derived from the same declarative specs used for classification.
63
+ */
64
+
65
+ interface CategoryGap {
66
+ key: string;
67
+ values: string[];
68
+ unlocksCategory?: string;
69
+ reason: string;
70
+ }
71
+ interface CategoryGapResult {
72
+ category: string;
73
+ _side: BikelaneResult['_side'];
74
+ incomplete: boolean;
75
+ missing: CategoryGap[];
76
+ }
77
+ declare function analyzeCategoryGaps(wayTags: OsmTags, results: BikelaneResult[]): CategoryGapResult[];
78
+
79
+ /**
80
+ * Plan OSM tag adds/changes to reach a target bikelane category.
81
+ * Works in transformed tag space internally; returns nested OSM keys for left/right
82
+ * cycleway (and sidewalk) sides, bare keys for self.
83
+ */
84
+
85
+ interface TagPlanEntry {
86
+ key: string;
87
+ value: string;
88
+ reason: string;
89
+ }
90
+ interface TagChangeEntry {
91
+ key: string;
92
+ from: string;
93
+ to: string;
94
+ reason: string;
95
+ }
96
+ interface TagConflictEntry {
97
+ key: string;
98
+ value: string;
99
+ reason: string;
100
+ }
101
+ interface CategoryTagPlan {
102
+ targetCategoryId: string;
103
+ currentCategoryId: string | null;
104
+ aligned: boolean;
105
+ add: TagPlanEntry[];
106
+ change: TagChangeEntry[];
107
+ conflicts: TagConflictEntry[];
108
+ }
109
+ interface ListTargetCategoriesOptions {
110
+ /** Current category id — unlock candidates from its gapDiscriminators are listed first. */
111
+ fromCategory?: string;
112
+ /** When true with `fromCategory`, treat it as incomplete even if the id looks complete. */
113
+ fromIncomplete?: boolean;
114
+ }
115
+ /**
116
+ * Map a transformed tag key back to OSM way tags for writing.
117
+ * Left/right cycleway (and sidewalk) sub-objects use nested keys (`cycleway:right:lane`).
118
+ */
119
+ declare function writeKeyForSide(transformedKey: string, side: BikelaneResult['_side'], prefix: string | null): string;
120
+ declare function listTargetCategories(options?: ListTargetCategoriesOptions): string[];
121
+ interface PlanTagsForCategoryOptions {
122
+ side?: BikelaneResult['_side'];
123
+ }
124
+ declare class UnknownTargetCategoryError extends Error {
125
+ readonly targetCategoryId: string;
126
+ constructor(targetCategoryId: string);
127
+ }
128
+ /**
129
+ * Plan tag adds/changes to reach `targetCategoryId` for the given way and side.
130
+ *
131
+ * Returned keys use nested OSM form for left/right cycleway (and sidewalk) sides
132
+ * (`cycleway:right:lane`); bare keys for self-side objects.
133
+ *
134
+ * Predicate macros (`cycleway_on_highway_*`, `needs_clarification`, etc.) are not
135
+ * inverted — plans rely on simple eq/in atoms and gap discriminators.
136
+ */
137
+ declare function planTagsForCategory(wayTags: OsmTags, targetCategoryId: string, options?: PlanTagsForCategoryOptions): CategoryTagPlan;
138
+
139
+ /** Small predicate AST for declarative category specs (OSMnexus-inspired). */
140
+
141
+ type TagPredicate = {
142
+ op: 'eq';
143
+ key: string;
144
+ value: string;
145
+ } | {
146
+ op: 'neq';
147
+ key: string;
148
+ value: string;
149
+ } | {
150
+ op: 'in';
151
+ key: string;
152
+ values: string[];
153
+ } | {
154
+ op: 'notIn';
155
+ key: string;
156
+ values: string[];
157
+ } | {
158
+ op: 'exists';
159
+ key: string;
160
+ } | {
161
+ op: 'notExists';
162
+ key: string;
163
+ } | {
164
+ op: 'includes';
165
+ key: string;
166
+ substring: string;
167
+ } | {
168
+ op: 'hasPrefix';
169
+ key: string;
170
+ prefix: string;
171
+ } | {
172
+ op: 'hasSuffix';
173
+ key: string;
174
+ suffix: string;
175
+ } | {
176
+ op: 'hasTagWithPrefix';
177
+ prefix: string;
178
+ } | {
179
+ op: 'and';
180
+ predicates: TagPredicate[];
181
+ } | {
182
+ op: 'or';
183
+ predicates: TagPredicate[];
184
+ } | {
185
+ op: 'not';
186
+ predicate: TagPredicate;
187
+ } | {
188
+ op: 'macro';
189
+ name: string;
190
+ } | {
191
+ op: 'literal';
192
+ value: boolean;
193
+ };
194
+
195
+ /**
196
+ * Declarative category specs — single source of truth for match rules and gap analysis.
197
+ * OSMnexus-inspired: base `match` + nested `refining` for subcategories.
198
+ */
199
+
200
+ interface GapDiscriminator {
201
+ key: string;
202
+ values: string[];
203
+ unlocksCategory?: string;
204
+ reason: string;
205
+ }
206
+ interface RefiningChild {
207
+ idSuffix: string;
208
+ match: TagPredicate;
209
+ implicitOneWayConfidence?: ImplicitOneWayConfidence;
210
+ }
211
+ interface CategorySpec {
212
+ id: string;
213
+ infrastructureExists: boolean;
214
+ implicitOneWay: boolean;
215
+ implicitOneWayConfidence: ImplicitOneWayConfidence;
216
+ copySurfaceSmoothnessFromParent: boolean;
217
+ match?: TagPredicate;
218
+ excludes?: TagPredicate[];
219
+ refining?: RefiningChild[];
220
+ gapDiscriminators?: GapDiscriminator[];
221
+ process?: (tags: OsmTags) => void;
222
+ }
223
+ declare const CATEGORY_SPECS: CategorySpec[];
224
+ declare function isIncompleteCategoryId(categoryId: string): boolean;
225
+ /** Specs with gap discriminators — for tests syncing analyzer output with declarative data. */
226
+ declare function specsWithGapDiscriminators(): CategorySpec[];
227
+
228
+ /** Port of topics/roads_bikelanes/bikelanes/transformations.lua */
229
+
230
+ interface CenterLineTransformation {
231
+ highway: string;
232
+ prefix: string;
233
+ direction_reference: 'self' | 'parent';
234
+ filter: (tags: OsmTags) => boolean;
235
+ }
236
+ /** Returns transformed objects in order: [self, left, right, ...]. */
237
+ declare function getTransformedObjects(tags: OsmTags, transformations: CenterLineTransformation[]): OsmTags[];
238
+ /** The transformations used by the bikelanes pipeline (cycleway + sidewalk). */
239
+ declare const BIKELANE_TRANSFORMATIONS: CenterLineTransformation[];
240
+
241
+ /**
242
+ * Pre-categorization tag transforms, ported from tilda-geo
243
+ * (processing/topics/roads_bikelanes/helper/transform_tags/*). These mutate the raw way
244
+ * tags in-place BEFORE `getTransformedObjects`, exactly as `roads_bikelanes.lua` does.
245
+ */
246
+
247
+ /** Apply all pre-transforms in the same order as roads_bikelanes.lua. */
248
+ declare function prepareTags(tags: OsmTags): void;
249
+
250
+ /** Port of topics/helper/highway_classes.lua */
251
+ declare const TRUNK_MOTORWAY_CLASSES: readonly ["motorway", "motorway_link", "trunk", "trunk_link"];
252
+ declare const MAJOR_ROAD_CLASSES: readonly ["primary", "primary_link", "secondary", "secondary_link", "tertiary", "tertiary_link"];
253
+ declare const MINOR_ROAD_CLASSES: readonly ["unclassified", "residential", "road", "living_street", "pedestrian", "service"];
254
+ declare const PATH_CLASSES: readonly ["track", "path", "footway", "cycleway", "steps"];
255
+ /** Path-like for sidepath / transformation logic: PathClasses + pedestrian. */
256
+ declare const SIDEPATH_HIGHWAY_CLASSES: Set<string>;
257
+ declare const ALLOWED_HIGHWAYS: Set<string>;
258
+
259
+ /**
260
+ * TypeScript port of Tilda's LUA bicycle-infrastructure processing.
261
+ *
262
+ * `processBikelanes(tags)` mirrors `bikelanes.lua`: it transforms one OSM way into its
263
+ * self + side geometries, categorizes each, and derives the key result fields.
264
+ * Only the category + a focused set of fields (surface, smoothness, oneway, separation,
265
+ * buffer, marking, traffic_mode, traffic_sign, surface_color, width) are produced — these
266
+ * cover the project's focus (Radinfrastrukturkategorie + Oberfläche + Protektion).
267
+ *
268
+ * Input is a plain OSM tag object (e.g. one Overpass `way.tags`). Disallowed sanitizer
269
+ * values are normalized to `null` to match Tilda's exported GeoJSON.
270
+ */
271
+
272
+ declare function processBikelanes(objectTags: OsmTags): BikelaneResult[];
273
+
274
+ export { ALLOWED_HIGHWAYS, BIKELANE_TRANSFORMATIONS, type BikelaneResult, CATEGORY_DEFINITIONS, CATEGORY_SPECS, type CategoryGap, type CategoryGapResult, type CategorySpec, type CategoryTagPlan, type GapDiscriminator, type ListTargetCategoriesOptions, MAJOR_ROAD_CLASSES, MINOR_ROAD_CLASSES, type OsmTags, PATH_CLASSES, type PlanTagsForCategoryOptions, SIDEPATH_HIGHWAY_CLASSES, TRUNK_MOTORWAY_CLASSES, type TagChangeEntry, type TagConflictEntry, type TagPlanEntry, UnknownTargetCategoryError, analyzeCategoryGaps, categorizeBikelane, getTransformedObjects, isIncompleteCategoryId, listTargetCategories, planTagsForCategory, prepareTags, processBikelanes, specsWithGapDiscriminators, writeKeyForSide };