@truelies/osm-dybuf 0.4.0 → 0.4.2

package/README.md

@@ -25,10 +25,10 @@ Current frontend-facing schema notes:
 - `place_label` remains in schema IDs for compatibility, but current exports no longer emit place-name labels to the frontend.
 - `label` main feature ID is now reserved for future overlay labels; `sub_id` is intended to carry `label kind` (`worship`, `station`, `custom`, etc.).
 - Current exporter-oriented subtypes are `label_worship` and `label_station`, both derived from existing `building` tasks. Consumers should group all future `label_*` subtypes by `unpackFeatureId(featureId).mainKey === "label"` if they want a single overlay layer.
-- Breaking change in `0.4.0`: `GridFeature.featureId` is numeric. Consumers should map it with `ID_TO_FEATURE_KIND[String(featureId)]` or `unpackFeatureId(featureId)` when string/debug output is needed.
+- Breaking change in `0.4.x`: `GridFeature.featureId` is numeric. Consumers should map it with `ID_TO_FEATURE_KIND[String(featureId)]` or `unpackFeatureId(featureId)` when string/debug output is needed.
 - `road_express` covers motorway corridors plus `trunk` ways tagged with `motorroad=yes` (for example many Taiwan expressway mainlines).
 - `water_wetland` separates marsh / bog / fen / wetland polygons from deeper open water.
-- Current project max level is `13`; newer exports no longer emit `lv14~16`.
+- Geometry payload exports currently stop at `lv13`, but Gridex/index helpers remain valid through `lv16` for higher-detail indexing metadata.
 
 ## Usage
 
@@ -42,6 +42,7 @@ import { parseOsmDybuf } from "@truelies/osm-dybuf";
 import {
   FEATURE_KIND_IDS,
   ID_TO_FEATURE_KIND,
+  MAIN_FEATURE_IDS,
   unpackFeatureId,
   REGION_NUMERIC_CODES,
 } from "@truelies/osm-dybuf/schema_ids";
@@ -55,6 +56,7 @@ if (parsed.format === "flat_v1") {
   console.log(parsed.features[0].featureId); // numeric feature id
   console.log(ID_TO_FEATURE_KIND[String(parsed.features[0].featureId)]);
   console.log(unpackFeatureId(parsed.features[0].featureId));
+  console.log((parsed.features[0].featureId & 0x3f) === MAIN_FEATURE_IDS.label);
 } else if (parsed.format === "v2_indexed") {
   console.log(parsed.entries.length);
 } else {
@@ -76,6 +78,11 @@ if (parsed.format === "flat_v1") {
       --level 8 --londex 213 --latdex 161 --limit 5
   ```
 
+Feature ID usage notes:
+- Use `FEATURE_KIND_IDS.*` for exact feature comparison, for example `featureId === FEATURE_KIND_IDS.waterbody`.
+- Use `MAIN_FEATURE_IDS.*` with `featureId & 0x3f` when you want to group all subtypes under the same main feature, for example `(featureId & 0x3f) === MAIN_FEATURE_IDS.label`.
+- Use `unpackFeatureId(featureId)` for debug output or subtype-aware logic where readability matters more than raw hot-path comparisons.
+
 ### Grid helpers (grid_index)
 
 `grid_index.mjs` exposes Gridex helpers (integers, pole triangles) aligned with the exporter:
@@ -94,7 +101,7 @@ const parent = new GridUnit(9).toUpperLevelGridex(children[0]); // back to level
 
 - `toLowerLevelGridexes(gridex)`:
   - returns 4 child cells at `level + 1`
-  - throws when current unit is already max level (`13`)
+  - 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`
@@ -110,7 +117,7 @@ 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, `lv13` has no lower level)
+- 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)
@@ -132,4 +139,4 @@ Unit test example (`tests/grid_index.test.mjs`) covers:
 - `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. Version `0.4.0` aligns the package with the current `lv0~13` export range, the current frontend feature set (`water_wetland`, `building`, no exported `place_label`), and the numeric `featureId` parser contract.
+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.4.2` aligns the package with the current `lv0~13` export range, the current frontend feature set (`water_wetland`, `building`, derived `label_*`, no exported `place_label`), and the numeric `featureId` parser contract.

package/grid_index.mjs

@@ -6,7 +6,7 @@ export const GRID_LV0_UNIT = 30 * INT_COORD_SCALE;
 const GRID_LV0_UNIT_FINE = GRID_LV0_UNIT * GRID_FINE_RES;
 const GRID_LV0_LONDEX = 6;
 const GRID_LV0_LATDEX = 3;
-const MAX_LEVEL = 13;
+const MAX_LEVEL = 16;
 const MAX_LONGITUDE_FINE = 180 * INT_COORD_SCALE * GRID_FINE_RES;
 const MIN_LONGITUDE_FINE = -MAX_LONGITUDE_FINE;
 const MAX_LATITUDE_FINE = 90 * INT_COORD_SCALE * GRID_FINE_RES;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truelies/osm-dybuf",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Gridex OSM DyBuf parser and schema utilities",
   "type": "module",
   "main": "./osm_dybuf.mjs",