@truelies/osm-dybuf 0.3.0 → 0.3.2

package/README.md

@@ -4,6 +4,7 @@ Gridex `osm.dybuf` parser utilities shared by the exporter, inspection scripts,
 This package wraps the shared schema tables (`schema_ids`) and exposes a high-level `parseOsmDybuf` helper.  
 It depends on the published [`dybuf`](https://www.npmjs.com/package/dybuf) runtime (≥ 0.4.2).
 Feature IDs are packed as `feature_id = sub_id * 64 + main_id` (both 0–63). Use `schema_ids` to decode feature strings.
+Current road groups are `road_express`, `road_major`, `road_minor`, `road_local`, and `road_trail`.
 
 ## Current Compatibility Status
 
@@ -17,6 +18,12 @@ Support matrix:
 
 `inspect_dybuf.mjs` now prints by detected format.
 
+Current frontend-facing schema notes:
+
+- `admin_boundary` is retained in schema IDs for compatibility, but new exports no longer send boundary lines to the frontend.
+- Administrative naming should come from `place_label`.
+- `road_express` was added for motorway / controlled-access corridors.
+
 ## Usage
 
 ```bash
@@ -60,7 +67,7 @@ if (parsed.format === "flat_v1") {
 
 ### Grid helpers (grid_index)
 
-`grid_index.ts` exposes the minimal Gridex helpers (integers, pole triangles) aligned with the exporter:
+`grid_index.mjs` exposes Gridex helpers (integers, pole triangles) aligned with the exporter:
 
 ```ts
 import { GridUnit, Gridex, INT_COORD_SCALE } from "@truelies/osm-dybuf/grid_index";
@@ -68,18 +75,44 @@ import { GridUnit, Gridex, INT_COORD_SCALE } from "@truelies/osm-dybuf/grid_inde
 const unit = new GridUnit(8); // level 8
 const cell = new Gridex(213, 161);
 const [minLon, minLat, maxLon, maxLat] = unit.boundsOfGrid(cell);
+
+// parent/child conversion (same rules as Python GridUnit)
+const children = unit.toLowerLevelGridexes(cell);   // level 9, 4 cells
+const parent = new GridUnit(9).toUpperLevelGridex(children[0]); // back to level 8
 ```
 
+- `toLowerLevelGridexes(gridex)`:
+  - returns 4 child cells at `level + 1`
+  - throws when current unit is already max level (`16`)
+- `toUpperLevelGridex(gridex)`:
+  - returns the parent cell at `level - 1`
+  - throws when current unit is level `0`
+
 ## Local Development
 
 ```bash
 cd js
 npm install      # installs dybuf runtime for this package
+npm test         # runs unit tests (node:test)
 ```
 
+Unit test example (`tests/grid_index.test.mjs`) covers:
+- `gridexesAt` near axis (no zero index cell)
+- `toLowerLevelGridexes` and `toUpperLevelGridex` roundtrip
+- level boundary errors (`lv0` has no upper level, `lv16` has no lower level)
+
 - `npm pack`: build a tarball so other repos can install via `npm install ./path/to/osm-dybuf-*.tgz`
 - `npm link`: link the package locally (`npm link` here, then `npm link @truelies/osm-dybuf` in the consumer repo)
-- `npm publish --access public`: publish to npm (requires the `@truelies` scope). If the scope is not available, rename `package.json` → `"name": "truelies-osm-dybuf"` and publish without a scope.
+- Publish to npm (requires `@truelies` scope):
+  ```bash
+  cd js
+  npm version <new-version> --no-git-tag-version
+  NPM_CONFIG_CACHE=/tmp/npm-cache npm login --auth-type=web --registry=https://registry.npmjs.org/ --scope=@truelies
+  NPM_CONFIG_CACHE=/tmp/npm-cache npm whoami
+  NPM_CONFIG_CACHE=/tmp/npm-cache npm publish --access public
+  ```
+  - If `~/.npm` has permission issues (root-owned cache/logs), keep using `NPM_CONFIG_CACHE=/tmp/npm-cache`.
+  - If the scope is not available, rename `package.json` → `"name": "truelies-osm-dybuf"` and publish without a scope.
 
 ## Files
 
@@ -88,4 +121,4 @@ npm install      # installs dybuf runtime for this package
 - `region_numeric_codes.json`: latest region ID table (generated via `scripts/dump_region_codes.py`)
 - `inspect_dybuf.mjs`: CLI tool that uses the package locally
 
-When schema IDs or DyBuf layouts change in the exporter, remember to bump the version here and re-publish/install so frontends and tools stay in sync.
+When schema IDs or DyBuf layouts change in the exporter, remember to bump the version here and re-publish/install so frontends and tools stay in sync. Version `0.3.2` adds the `road_express` feature group and aligns the package docs with the current no-`admin_boundary` frontend export policy.

package/grid_index.d.ts

@@ -31,6 +31,8 @@ export declare class GridUnit {
   makeGridex(londex: number, latdex: number): GridexAtLv;
   gridexesAt(longitudeInt: number, latitudeInt: number): GridexAtLv[];
   gridexesWithExt(longitudeInt: number, latitudeInt: number, ext?: number): GridexAtLv[];
+  toLowerLevelGridexes(gridex: Gridex): GridexAtLv[];
+  toUpperLevelGridex(gridex: Gridex): GridexAtLv;
   boundsOfGridFine(gridex: Gridex, applyTriangle?: boolean): [number, number, number, number];
   boundsOfGrid(gridex: Gridex, applyTriangle?: boolean): [number, number, number, number];
   gridexRangeForBounds(

package/grid_index.mjs

@@ -158,6 +158,43 @@ export class GridUnit {
     return result;
   }
 
+  toLowerLevelGridexes(gridex) {
+    if (this.level >= MAX_LEVEL) {
+      throw new Error(`No lower level exists for level ${this.level}`);
+    }
+    const lon = gridex.londex;
+    const lat = gridex.latdex;
+    const lonInc = lon > 0 ? -1 : 1;
+    const latInc = lat > 0 ? -1 : 1;
+    const childUnit = new GridUnit(this.level + 1);
+    return [
+      childUnit.makeGridex(lon * 2 + lonInc, lat * 2 + latInc),
+      childUnit.makeGridex(lon * 2 + lonInc, lat * 2),
+      childUnit.makeGridex(lon * 2, lat * 2 + latInc),
+      childUnit.makeGridex(lon * 2, lat * 2),
+    ];
+  }
+
+  toUpperLevelGridex(gridex) {
+    if (this.level <= 0) {
+      throw new Error("No upper level exists for level 0");
+    }
+    const lon = gridex.londex;
+    const lat = gridex.latdex;
+    const lonInc = lon > 0 ? -1 : 1;
+    const latInc = lat > 0 ? -1 : 1;
+    const upperLon =
+      lon > 0
+        ? Math.floor((lon - lonInc) / 2)
+        : Math.ceil((lon - lonInc) / 2);
+    const upperLat =
+      lat > 0
+        ? Math.floor((lat - latInc) / 2)
+        : Math.ceil((lat - latInc) / 2);
+    const upperUnit = new GridUnit(this.level - 1);
+    return upperUnit.makeGridex(upperLon, upperLat);
+  }
+
   boundsOfGridFine(gridex, applyTriangle = false) {
     const { londex, latdex } = gridex;
     const minLonFine = (londex - (londex > 0 ? 1 : 0)) * this.unitFine;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truelies/osm-dybuf",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Gridex OSM DyBuf parser and schema utilities",
   "type": "module",
   "main": "./osm_dybuf.mjs",
@@ -39,6 +39,9 @@
   ],
   "author": "TrueLies",
   "license": "UNLICENSED",
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
   "dependencies": {
     "dybuf": "^0.4.2"
   }

package/schema_ids.mjs

@@ -44,10 +44,11 @@ const FEATURE_KIND_CODES = Object.freeze({
   waterbody: ["waterbody", 0],
   landuse: ["landuse", 0],
   park: ["park", 0],
-  road_major: ["road", 0],
-  road_minor: ["road", 1],
-  road_local: ["road", 2],
-  road_trail: ["road", 3],
+  road_express: ["road", 0],
+  road_major: ["road", 1],
+  road_minor: ["road", 2],
+  road_local: ["road", 3],
+  road_trail: ["road", 4],
   waterway_major: ["waterway", 0],
   waterway_stream: ["waterway", 1],
   waterway_minor: ["waterway", 2],