@truelies/osm-dybuf 0.3.3 → 0.4.1

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
@@ -22,7 +23,10 @@ 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.
 - `place_label` remains in schema IDs for compatibility, but current exports no longer emit place-name labels to the frontend.
-- `road_express` was added for motorway / controlled-access corridors.
+- `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.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`.
 
@@ -37,6 +41,9 @@ npm install @truelies/osm-dybuf
 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";
 
@@ -46,6 +53,10 @@ 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));
+  console.log((parsed.features[0].featureId & 0x3f) === MAIN_FEATURE_IDS.label);
 } else if (parsed.format === "v2_indexed") {
   console.log(parsed.entries.length);
 } else {
@@ -67,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:
@@ -123,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.3.3` aligns the package with the current `lv0~13` export range and the frontend feature set (`water_wetland`, `building`, no exported `place_label`).
+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.1` 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/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.3",
+  "version": "0.4.1",
   "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

@@ -33,6 +33,7 @@ export const MAIN_FEATURE_IDS = Object.freeze({
   waterway: 8,
   place_label: 9,
   building: 10,
+  label: 11,
 });
 
 const FEATURE_KIND_CODES = Object.freeze({
@@ -45,6 +46,11 @@ const FEATURE_KIND_CODES = Object.freeze({
   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],
@@ -58,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),
     ])
   )
 );
@@ -70,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;