@truelies/osm-dybuf 0.1.0

package/osm_dybuf.d.mts

@@ -0,0 +1,43 @@
+export interface GridCellRef {
+  level: number;
+  londex: number;
+  latdex: number;
+}
+
+export interface GeometryCoordinate {
+  lon: number;
+  lat: number;
+}
+
+export interface GeometrySegment {
+  role: string;
+  coordinates: GeometryCoordinate[];
+}
+
+export interface GridElement {
+  entityType: string;
+  entityId: number;
+  entityRef: string;
+  geometryType: string;
+  tags: Record<string, string>;
+  segments: GeometrySegment[];
+}
+
+export interface GridFeature {
+  featureId: string;
+  elements: GridElement[];
+}
+
+export interface RegionChunk {
+  id: number;
+  name: string;
+  features: GridFeature[];
+}
+
+export interface OsmDybuf {
+  version: number;
+  regions: RegionChunk[];
+}
+
+export declare function parseOsmDybuf(data: ArrayBuffer | ArrayBufferView, cell: GridCellRef): OsmDybuf;
+export declare function decodeRegionPayload(payload: ArrayBuffer, cell: GridCellRef): GridFeature[];

package/osm_dybuf.mjs

@@ -0,0 +1,237 @@
+import {
+  DyBuf,
+  TYPDEX_TYP_BOOL,
+  TYPDEX_TYP_INT,
+  TYPDEX_TYP_UINT,
+  TYPDEX_TYP_STRING,
+  TYPDEX_TYP_BYTES,
+  TYPDEX_TYP_ARRAY,
+  TYPDEX_TYP_MAP,
+} from "dybuf";
+import {
+  ID_TO_ENTITY_TYPE,
+  ID_TO_FEATURE_KIND,
+  ID_TO_GEOMETRY_KIND,
+  ID_TO_SEGMENT_ROLE,
+  SEGMENT_ROLE_ID_UNSET,
+  SEGMENT_ROLE_ID_UNSUPPORTED,
+  REGION_NUMERIC_CODES,
+} from "./schema_ids.mjs";
+
+const GRID_FINE_RES = 64;
+const INT_COORD_SCALE = 1_000_000_000;
+const GRID_LV0_UNIT = 30 * INT_COORD_SCALE;
+
+const GRID_VALUE_FIELD = {
+  ENTITY_TYPE: 0,
+  ENTITY_ID: 1,
+  GEOMETRY_TYPE: 2,
+  GEOMETRY_DATA: 3,
+  TAGS: 4,
+};
+
+const REGION_ID_TO_NAME = Object.freeze(
+  Object.fromEntries(
+    Object.entries(REGION_NUMERIC_CODES).map(([name, id]) => [String(id), name])
+  )
+);
+
+/**
+ * Normalize Node.js Buffer/View inputs into an ArrayBuffer slice.
+ * @param {ArrayBuffer | ArrayBufferView} data
+ * @returns {ArrayBuffer}
+ */
+function toArrayBuffer(data) {
+  if (data instanceof ArrayBuffer) {
+    return data;
+  }
+  if (ArrayBuffer.isView(data)) {
+    const { buffer, byteOffset, byteLength } = data;
+    return buffer.slice(byteOffset, byteOffset + byteLength);
+  }
+  throw new TypeError("Expected ArrayBuffer or typed array input");
+}
+
+function unitFineForLevel(level) {
+  return (GRID_LV0_UNIT * GRID_FINE_RES) / (1 << level);
+}
+
+function gridBounds(level, londex, latdex) {
+  const unitFine = unitFineForLevel(level);
+  const minLonFine = (londex - (londex > 0 ? 1 : 0)) * unitFine;
+  const minLatFine = (latdex - (latdex > 0 ? 1 : 0)) * unitFine;
+  const maxLonFine = (londex + (londex > 0 ? 0 : 1)) * unitFine;
+  const maxLatFine = (latdex + (latdex > 0 ? 0 : 1)) * unitFine;
+  return {
+    minLon: minLonFine / GRID_FINE_RES,
+    minLat: minLatFine / GRID_FINE_RES,
+    maxLon: maxLonFine / GRID_FINE_RES,
+    maxLat: maxLatFine / GRID_FINE_RES,
+  };
+}
+
+function readVarUint(buf) {
+  return Number(buf.getVarULong());
+}
+
+function readVarInt(buf) {
+  return Number(buf.getVarLong());
+}
+
+const textDecoder = new TextDecoder("utf-8");
+
+function readVarString(buf) {
+  const raw = buf.getVarString();
+  if (typeof raw === "string") {
+    return raw;
+  }
+  if (raw == null) {
+    return "";
+  }
+  return textDecoder.decode(raw);
+}
+
+function readVarBytes(buf) {
+  return buf.getBytesWithVarLength();
+}
+
+function decodeGeometrySegments(bytes, cell) {
+  const buf = new DyBuf(bytes, false);
+  const version = buf.getByte();
+  if (version !== 1) {
+    throw new Error(`Unsupported geometry blob version ${version}`);
+  }
+  const bounds = gridBounds(cell.level, cell.londex, cell.latdex);
+  const segments = [];
+  const segmentCount = readVarUint(buf);
+  for (let i = 0; i < segmentCount; i += 1) {
+    const roleId = buf.getByte();
+    let role = "";
+    if (roleId === SEGMENT_ROLE_ID_UNSUPPORTED) {
+      role = "<unsupported>";
+    } else if (roleId !== SEGMENT_ROLE_ID_UNSET) {
+      role = ID_TO_SEGMENT_ROLE[String(roleId)] ?? "";
+    }
+    const pointCount = readVarUint(buf);
+    const points = [];
+    let prevX;
+    let prevY;
+    for (let j = 0; j < pointCount; j += 1) {
+      const dx = readVarInt(buf);
+      const dy = readVarInt(buf);
+      const x = prevX === undefined ? bounds.minLon + dx : prevX + dx;
+      const y = prevY === undefined ? bounds.minLat + dy : prevY + dy;
+      points.push({ lon: x, lat: y });
+      prevX = x;
+      prevY = y;
+    }
+    segments.push({ role, coordinates: points });
+  }
+  return segments;
+}
+
+function decodeGridPayload(bytes, cell) {
+  const buf = new DyBuf(bytes, false);
+  const version = buf.getByte();
+  if (version !== 1) {
+    throw new Error(`Unsupported grid payload version ${version}`);
+  }
+
+  let entityTypeId;
+  let entityId;
+  let geometryType;
+  let geometryBlob;
+  const tags = {};
+
+  while (buf.position() < buf.limit()) {
+    const { type, index } = buf.getTypdex();
+    if (index === GRID_VALUE_FIELD.ENTITY_TYPE && type === TYPDEX_TYP_UINT) {
+      entityTypeId = readVarUint(buf);
+    } else if (index === GRID_VALUE_FIELD.ENTITY_ID && type === TYPDEX_TYP_UINT) {
+      entityId = readVarUint(buf);
+    } else if (index === GRID_VALUE_FIELD.GEOMETRY_TYPE && type === TYPDEX_TYP_UINT) {
+      const geometryNumeric = readVarUint(buf);
+      geometryType =
+        ID_TO_GEOMETRY_KIND[String(geometryNumeric)] ?? `geometry:${geometryNumeric}`;
+    } else if (index === GRID_VALUE_FIELD.GEOMETRY_DATA && type === TYPDEX_TYP_BYTES) {
+      geometryBlob = readVarBytes(buf);
+    } else if (index === GRID_VALUE_FIELD.TAGS && type === TYPDEX_TYP_MAP) {
+      const count = readVarUint(buf);
+      for (let i = 0; i < count; i += 1) {
+        const key = readVarString(buf);
+        const value = readVarString(buf);
+        tags[key] = value;
+      }
+    } else {
+      throw new Error(`Unsupported typdex field: index=${index} type=${type}`);
+    }
+  }
+
+  if (
+    entityTypeId === undefined ||
+    entityId === undefined ||
+    !geometryType ||
+    !geometryBlob
+  ) {
+    throw new Error("Grid payload missing required fields");
+  }
+
+  const entityType = ID_TO_ENTITY_TYPE[String(entityTypeId)];
+  if (!entityType) {
+    throw new Error(`Unknown entity type id ${entityTypeId}`);
+  }
+
+  const segments = decodeGeometrySegments(geometryBlob, cell);
+  return {
+    entityType,
+    entityId,
+    entityRef: `${entityType}:${entityId}`,
+    geometryType,
+    tags,
+    segments,
+  };
+}
+
+function decodeRegionPayload(payloadBytes, cell) {
+  const buf = new DyBuf(payloadBytes, false);
+  const featureCount = readVarUint(buf);
+  const features = [];
+  for (let i = 0; i < featureCount; i += 1) {
+    const featureNumericId = readVarUint(buf);
+    const featureId =
+      ID_TO_FEATURE_KIND[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 });
+  }
+  return features;
+}
+
+/**
+ * Parse a single cell's osm.dybuf payload.
+ * @param {ArrayBuffer | ArrayBufferView} data
+ * @param {{level: number, londex: number, latdex: number}} cell
+ */
+export function parseOsmDybuf(data, cell) {
+  if (!cell || typeof cell.level !== "number" || typeof cell.londex !== "number" || typeof cell.latdex !== "number") {
+    throw new TypeError("Cell metadata (level, londex, latdex) is required");
+  }
+  const buffer = toArrayBuffer(data);
+  const buf = new DyBuf(buffer, false);
+  const version = buf.getByte();
+  const regions = [];
+  while (buf.position() < buf.limit()) {
+    const regionId = readVarUint(buf);
+    const regionName = REGION_ID_TO_NAME[String(regionId)] ?? `region:${regionId}`;
+    const regionPayload = readVarBytes(buf);
+    const features = decodeRegionPayload(regionPayload, cell);
+    regions.push({ id: regionId, name: regionName, features });
+  }
+  return { version, regions };
+}
+
+export { decodeRegionPayload, decodeGridPayload };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@truelies/osm-dybuf",
+  "version": "0.1.0",
+  "description": "Gridex OSM DyBuf parser and schema utilities",
+  "type": "module",
+  "main": "./osm_dybuf.mjs",
+  "module": "./osm_dybuf.mjs",
+  "types": "./osm_dybuf.d.mts",
+  "exports": {
+    ".": {
+      "import": "./osm_dybuf.mjs",
+      "types": "./osm_dybuf.d.mts"
+    },
+    "./schema_ids": {
+      "import": "./schema_ids.mjs",
+      "types": "./schema_ids.d.mts"
+    },
+    "./region_numeric_codes.json": "./region_numeric_codes.json"
+  },
+  "files": [
+    "osm_dybuf.mjs",
+    "osm_dybuf.d.mts",
+    "schema_ids.mjs",
+    "schema_ids.d.mts",
+    "region_numeric_codes.json"
+  ],
+  "keywords": [
+    "dybuf",
+    "osm",
+    "gridex",
+    "parser"
+  ],
+  "author": "TrueLies",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "dybuf": "^0.4.2"
+  }
+}

package/region_numeric_codes.json

@@ -0,0 +1,254 @@
+{
+  "ad": 300,
+  "ae": 400,
+  "af": 500,
+  "ag": 600,
+  "ai": 800,
+  "al": 1100,
+  "am": 1200,
+  "ao": 1400,
+  "aq": 1600,
+  "ar": 1700,
+  "as": 1800,
+  "at": 1900,
+  "au": 2000,
+  "aw": 2200,
+  "ax": 2300,
+  "az": 2500,
+  "ba": 2600,
+  "bb": 2700,
+  "bd": 2900,
+  "be": 3000,
+  "bf": 3100,
+  "bg": 3200,
+  "bh": 3300,
+  "bi": 3400,
+  "bj": 3500,
+  "bl": 3700,
+  "bm": 3800,
+  "bn": 3900,
+  "bo": 4000,
+  "bq": 4200,
+  "br": 4300,
+  "bs": 4400,
+  "bt": 4500,
+  "bv": 4700,
+  "bw": 4800,
+  "by": 5000,
+  "bz": 5100,
+  "ca": 5200,
+  "cc": 5400,
+  "cd": 5500,
+  "cf": 5700,
+  "cg": 5800,
+  "ch": 5900,
+  "ci": 6000,
+  "ck": 6200,
+  "cl": 6300,
+  "cm": 6400,
+  "cn": 6500,
+  "co": 6600,
+  "country_land": 0,
+  "cr": 6900,
+  "cu": 7200,
+  "cv": 7300,
+  "cw": 7400,
+  "cx": 7500,
+  "cy": 7600,
+  "cz": 7700,
+  "de": 8200,
+  "dj": 8700,
+  "dk": 8800,
+  "dm": 9000,
+  "do": 9200,
+  "dz": 10300,
+  "ec": 10600,
+  "ee": 10800,
+  "eg": 11000,
+  "eh": 11100,
+  "er": 12100,
+  "es": 12200,
+  "et": 12300,
+  "fi": 13800,
+  "fj": 13900,
+  "fk": 14000,
+  "fm": 14200,
+  "fo": 14400,
+  "fr": 14700,
+  "ga": 15600,
+  "gb": 15700,
+  "gd": 15900,
+  "ge": 16000,
+  "gf": 16100,
+  "gg": 16200,
+  "gh": 16300,
+  "gi": 16400,
+  "gl": 16700,
+  "gm": 16800,
+  "gn": 16900,
+  "gp": 17100,
+  "gq": 17200,
+  "gr": 17300,
+  "gs": 17400,
+  "gt": 17500,
+  "gu": 17600,
+  "gw": 17800,
+  "gy": 18000,
+  "hk": 19200,
+  "hm": 19400,
+  "hn": 19500,
+  "hr": 19900,
+  "ht": 20100,
+  "hu": 20200,
+  "id": 21100,
+  "ie": 21200,
+  "il": 21900,
+  "im": 22000,
+  "in": 22100,
+  "io": 22200,
+  "iq": 22400,
+  "ir": 22500,
+  "is": 22600,
+  "it": 22700,
+  "je": 23800,
+  "jm": 24600,
+  "jo": 24800,
+  "jp": 24900,
+  "jp-hokkaido": 24901,
+  "ke": 26400,
+  "kg": 26600,
+  "kh": 26700,
+  "ki": 26800,
+  "km": 27200,
+  "kn": 27300,
+  "kp": 27500,
+  "kr": 27700,
+  "kw": 28200,
+  "ky": 28400,
+  "kz": 28500,
+  "la": 28600,
+  "lb": 28700,
+  "lc": 28800,
+  "li": 29400,
+  "lk": 29600,
+  "lr": 30300,
+  "ls": 30400,
+  "lt": 30500,
+  "lu": 30600,
+  "lv": 30700,
+  "ly": 31000,
+  "ma": 31200,
+  "mc": 31400,
+  "md": 31500,
+  "me": 31600,
+  "mf": 31700,
+  "mg": 31800,
+  "mh": 31900,
+  "mk": 32200,
+  "ml": 32300,
+  "mm": 32400,
+  "mn": 32500,
+  "mo": 32600,
+  "mp": 32700,
+  "mq": 32800,
+  "mr": 32900,
+  "ms": 33000,
+  "mt": 33100,
+  "mu": 33200,
+  "mv": 33300,
+  "mw": 33400,
+  "mx": 33500,
+  "my": 33600,
+  "mz": 33700,
+  "na": 33800,
+  "nc": 34000,
+  "ne": 34200,
+  "nf": 34300,
+  "ng": 34400,
+  "ni": 34600,
+  "nl": 34900,
+  "no": 35200,
+  "np": 35300,
+  "nr": 35500,
+  "nu": 35800,
+  "nz": 36300,
+  "om": 37600,
+  "pa": 39000,
+  "pe": 39400,
+  "pf": 39500,
+  "pg": 39600,
+  "ph": 39700,
+  "pk": 40000,
+  "pl": 40100,
+  "pm": 40200,
+  "pn": 40300,
+  "pr": 40700,
+  "ps": 40800,
+  "pt": 40900,
+  "pw": 41200,
+  "py": 41400,
+  "qa": 41600,
+  "re": 44600,
+  "ro": 45600,
+  "rs": 46000,
+  "ru": 46200,
+  "rw": 46400,
+  "sa": 46800,
+  "sb": 46900,
+  "sc": 47000,
+  "sd": 47100,
+  "se": 47200,
+  "sg": 47400,
+  "sh": 47500,
+  "si": 47600,
+  "sj": 47700,
+  "sk": 47800,
+  "sl": 47900,
+  "sm": 48000,
+  "sn": 48100,
+  "so": 48200,
+  "sr": 48500,
+  "ss": 48600,
+  "st": 48700,
+  "sv": 48900,
+  "sx": 49100,
+  "sy": 49200,
+  "sz": 49300,
+  "tc": 49600,
+  "td": 49700,
+  "tf": 49900,
+  "tg": 50000,
+  "th": 50100,
+  "tj": 50300,
+  "tk": 50400,
+  "tl": 50500,
+  "tm": 50600,
+  "tn": 50700,
+  "to": 50800,
+  "tr": 51100,
+  "tt": 51300,
+  "tv": 51500,
+  "tw": 51600,
+  "tz": 51900,
+  "ua": 52000,
+  "ug": 52600,
+  "um": 53200,
+  "us": 53800,
+  "uy": 54400,
+  "uz": 54500,
+  "va": 54600,
+  "vc": 54800,
+  "ve": 55000,
+  "vg": 55200,
+  "vi": 55400,
+  "vn": 55900,
+  "vu": 56600,
+  "wf": 57700,
+  "ws": 59000,
+  "xk": 60800,
+  "ye": 62800,
+  "yt": 64300,
+  "za": 65000,
+  "zm": 66200,
+  "zw": 67200
+}

package/schema_ids.d.mts

@@ -0,0 +1,11 @@
+export declare const ENTITY_TYPE_IDS: Readonly<Record<string, number>>;
+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 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>>;
+export declare const SEGMENT_ROLE_IDS: Readonly<Record<string, number>>;
+export declare const SEGMENT_ROLE_ID_UNSET: number;
+export declare const SEGMENT_ROLE_ID_UNSUPPORTED: number;
+export declare const ID_TO_SEGMENT_ROLE: Readonly<Record<number, string>>;

package/schema_ids.mjs

@@ -0,0 +1,73 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const REGION_CODES_RAW = require("./region_numeric_codes.json");
+
+export const ENTITY_TYPE_IDS = Object.freeze({
+  c: 0,
+  n: 1,
+  w: 2,
+  r: 3,
+});
+
+export const ID_TO_ENTITY_TYPE = Object.freeze(
+  Object.fromEntries(Object.entries(ENTITY_TYPE_IDS).map(([k, v]) => [String(v), k]))
+);
+
+export const GEOMETRY_KIND_IDS = Object.freeze({
+  point: 0,
+  polyline: 1,
+  polygon: 2,
+  grid_fill: 3,
+});
+
+export const ID_TO_GEOMETRY_KIND = Object.freeze(
+  Object.fromEntries(Object.entries(GEOMETRY_KIND_IDS).map(([k, v]) => [String(v), k]))
+);
+export const FEATURE_KIND_IDS = Object.freeze({
+  country_land: 0,
+  admin_boundary: 100,
+  coastline: 200,
+  natural_area: 210,
+  waterbody: 220,
+  landuse: 230,
+  park: 240,
+  road_major: 300,
+  road_minor: 301,
+  waterway: 400,
+  place_label: 500,
+});
+
+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]))
+);
+
+export const SEGMENT_ROLE_ID_UNSET = 0x00;
+export const SEGMENT_ROLE_ID_UNSUPPORTED = 0x0f;
+
+export const SEGMENT_ROLE_IDS = Object.freeze({
+  "": SEGMENT_ROLE_ID_UNSET,
+  outer: 0x10,
+  inner: 0x11,
+  forward: 0x12,
+  backward: 0x13,
+  from: 0x14,
+  via: 0x15,
+  to: 0x16,
+  label: 0x17,
+  perimeter: 0x18,
+  main_stream: 0x19,
+  side_stream: 0x1a,
+  anabranch: 0x1b,
+  spring: 0x1c,
+  mouth: 0x1d,
+});
+
+export const ID_TO_SEGMENT_ROLE = Object.freeze({
+  ...Object.fromEntries(
+    Object.entries(SEGMENT_ROLE_IDS).map(([role, id]) => [String(id), role])
+  ),
+  [String(SEGMENT_ROLE_ID_UNSUPPORTED)]: "<unsupported>",
+});