@truelies/osm-dybuf 0.3.2 → 0.4.0

package/README.md

@@ -3,7 +3,8 @@
 Gridex `osm.dybuf` parser utilities shared by the exporter, inspection scripts, and Next.js frontend.  
 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.
+Feature IDs are packed as `feature_id = sub_id * 64 + main_id` (both 0–63). The parser now returns numeric `featureId`; use `schema_ids` helpers to decode debug strings or subtypes when needed.
+`schema_ids` also exports `packFeatureId(...)`, `unpackFeatureId(...)`, and `labelFeatureId(...)` for subtype-aware features such as future `label` overlays.
 Current road groups are `road_express`, `road_major`, `road_minor`, `road_local`, and `road_trail`.
 
 ## Current Compatibility Status
@@ -21,8 +22,13 @@ Support matrix:
 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.
+- `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.
+- `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`.
 
 ## Usage
 
@@ -35,6 +41,8 @@ npm install @truelies/osm-dybuf
 import { parseOsmDybuf } from "@truelies/osm-dybuf";
 import {
   FEATURE_KIND_IDS,
+  ID_TO_FEATURE_KIND,
+  unpackFeatureId,
   REGION_NUMERIC_CODES,
 } from "@truelies/osm-dybuf/schema_ids";
 
@@ -44,6 +52,9 @@ const parsed = parseOsmDybuf(data, cell);
 
 if (parsed.format === "flat_v1") {
   console.log(parsed.features.length);
+  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));
 } else if (parsed.format === "v2_indexed") {
   console.log(parsed.entries.length);
 } else {
@@ -83,7 +94,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 (`16`)
+  - throws when current unit is already max level (`13`)
 - `toUpperLevelGridex(gridex)`:
   - returns the parent cell at `level - 1`
   - throws when current unit is level `0`
@@ -99,7 +110,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, `lv16` has no lower level)
+- level boundary errors (`lv0` has no upper level, `lv13` 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)
@@ -121,4 +132,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.3.2` adds the `road_express` feature group and aligns the package docs with the current no-`admin_boundary` frontend export policy.
+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.

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 = 16;
+const MAX_LEVEL = 13;
 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/osm_dybuf.d.mts

@@ -24,7 +24,7 @@ export interface GridElement {
 }
 
 export interface GridFeature {
-  featureId: string;
+  featureId: number;
   elements: GridElement[];
 }
 

package/osm_dybuf.mjs

@@ -6,7 +6,6 @@ import {
 } from "dybuf";
 import {
   ID_TO_ENTITY_TYPE,
-  ID_TO_FEATURE_KIND,
   ID_TO_GEOMETRY_KIND,
   ID_TO_SEGMENT_ROLE,
   SEGMENT_ROLE_ID_UNSET,
@@ -194,15 +193,13 @@ function decodePayload(payloadBytes, cell) {
   const features = [];
   for (let i = 0; i < featureCount; i += 1) {
     const featureNumericId = readVarUint(buf);
-    const featureId =
-      ID_TO_FEATURE_KIND[String(featureNumericId)] ?? `feature:${featureNumericId}`;
     const entryCount = readVarUint(buf);
     const elements = [];
     for (let j = 0; j < entryCount; j += 1) {
       const entryBytes = readVarBytes(buf);
       elements.push(decodeGridPayload(entryBytes, cell));
     }
-    features.push({ featureId, elements });
+    features.push({ featureId: featureNumericId, elements });
   }
   if (buf.position() !== buf.limit()) {
     throw new Error(

package/package.json

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

package/schema_ids.d.mts

@@ -3,6 +3,11 @@ export declare const ID_TO_ENTITY_TYPE: Readonly<Record<number, string>>;
 export declare const GEOMETRY_KIND_IDS: Readonly<Record<string, number>>;
 export declare const ID_TO_GEOMETRY_KIND: Readonly<Record<number, string>>;
 export declare const MAIN_FEATURE_IDS: Readonly<Record<string, number>>;
+export declare const LABEL_KIND_SUBTYPE_IDS: Readonly<Record<string, number>>;
+export declare function packFeatureId(mainKey: string, subId: number): number;
+export declare function unpackFeatureId(featureNumericId: number): { mainKey: string; subId: number };
+export declare function labelFeatureId(labelKind?: string): number;
+export declare function labelKindFromFeatureId(featureNumericId: number): string;
 export declare const FEATURE_KIND_IDS: Readonly<Record<string, number>>;
 export declare const ID_TO_FEATURE_KIND: Readonly<Record<number, string>>;
 export declare const REGION_NUMERIC_CODES: Readonly<Record<string, number>>;

package/schema_ids.mjs

@@ -32,6 +32,8 @@ export const MAIN_FEATURE_IDS = Object.freeze({
   road: 7,
   waterway: 8,
   place_label: 9,
+  building: 10,
+  label: 11,
 });
 
 const FEATURE_KIND_CODES = Object.freeze({
@@ -42,6 +44,13 @@ const FEATURE_KIND_CODES = Object.freeze({
   natural_vegetation: ["natural", 1],
   natural_bare: ["natural", 2],
   waterbody: ["waterbody", 0],
+  water_wetland: ["waterbody", 1],
+  building: ["building", 0],
+  label: ["label", 0],
+  label_worship: ["label", 1],
+  label_station: ["label", 2],
+  label_custom: ["label", 3],
+  label_admin: ["label", 4],
   landuse: ["landuse", 0],
   park: ["park", 0],
   road_express: ["road", 0],
@@ -55,11 +64,62 @@ const FEATURE_KIND_CODES = Object.freeze({
   place_label: ["place_label", 0],
 });
 
+export const LABEL_KIND_SUBTYPE_IDS = Object.freeze({
+  generic: 0,
+  worship: 1,
+  station: 2,
+  custom: 3,
+  admin: 4,
+});
+
+export function packFeatureId(mainKey, subId) {
+  const mainId = MAIN_FEATURE_IDS[mainKey];
+  if (mainId === undefined) {
+    throw new Error(`Unknown feature main key: ${mainKey}`);
+  }
+  if (subId < 0 || subId >= 64) {
+    throw new Error(`Feature sub id must be 0-63 (got ${subId})`);
+  }
+  return subId * 64 + mainId;
+}
+
+export function unpackFeatureId(featureNumericId) {
+  const numericId = Number(featureNumericId);
+  const mainId = numericId & 0x3f;
+  const subId = numericId >> 6;
+  const mainKey =
+    Object.entries(MAIN_FEATURE_IDS).find(([, value]) => value === mainId)?.[0] ?? null;
+  if (!mainKey) {
+    throw new Error(`Unknown feature main id ${mainId} in feature id ${numericId}`);
+  }
+  return { mainKey, subId };
+}
+
+export function labelFeatureId(labelKind = "generic") {
+  const normalized = String(labelKind).trim().toLowerCase();
+  const subId = LABEL_KIND_SUBTYPE_IDS[normalized];
+  if (subId === undefined) {
+    throw new Error(`Unknown label kind: ${labelKind}`);
+  }
+  return packFeatureId("label", subId);
+}
+
+export function labelKindFromFeatureId(featureNumericId) {
+  const { mainKey, subId } = unpackFeatureId(featureNumericId);
+  if (mainKey !== "label") {
+    throw new Error(`Feature id ${featureNumericId} is not a label feature`);
+  }
+  return (
+    Object.entries(LABEL_KIND_SUBTYPE_IDS).find(([, value]) => value === subId)?.[0] ??
+    "generic"
+  );
+}
+
 export const FEATURE_KIND_IDS = Object.freeze(
   Object.fromEntries(
     Object.entries(FEATURE_KIND_CODES).map(([kind, [main, sub]]) => [
       kind,
-      sub * 64 + MAIN_FEATURE_IDS[main],
+      packFeatureId(main, sub),
     ])
   )
 );
@@ -67,7 +127,12 @@ export const FEATURE_KIND_IDS = Object.freeze(
 export const REGION_NUMERIC_CODES = Object.freeze(REGION_CODES_RAW);
 
 export const ID_TO_FEATURE_KIND = Object.freeze(
-  Object.fromEntries(Object.entries(FEATURE_KIND_IDS).map(([k, v]) => [String(v), k]))
+  {
+    ...Object.fromEntries(Object.entries(FEATURE_KIND_IDS).map(([k, v]) => [String(v), k])),
+    ...Object.fromEntries(
+      Object.values(LABEL_KIND_SUBTYPE_IDS).map((subId) => [String(packFeatureId("label", subId)), "label"])
+    ),
+  }
 );
 
 export const SEGMENT_ROLE_ID_UNSET = 0x00;