@truelies/osm-dybuf

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 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 Compatibility Status

parseOsmDybuf now supports the current cloud formats and keeps a legacy fallback.

Support matrix:

• Flat V1 cell file (osm.dybuf): version + payload -> supported (format="flat_v1")
• V2 overview/bundle (overview.dybuf, bundle.dybuf): version=2 + index entries -> supported (format="v2_indexed")
• Legacy V1 with region chunks: version + [region_id + region_payload]... -> supported as fallback (format="legacy_v1_regions")

inspect_dybuf.mjs now prints by detected format.

Usage

# from another project (Next.js, Node, etc.)
npm install @truelies/osm-dybuf

import { parseOsmDybuf } from "@truelies/osm-dybuf";
import {
  FEATURE_KIND_IDS,
  REGION_NUMERIC_CODES,
} from "@truelies/osm-dybuf/schema_ids";

const data = await fetch("/tiles/08/213/161/osm.dybuf").then((res) => res.arrayBuffer());
const cell = { level: 8, londex: 213, latdex: 161 };
const parsed = parseOsmDybuf(data, cell);

if (parsed.format === "flat_v1") {
  console.log(parsed.features.length);
} else if (parsed.format === "v2_indexed") {
  console.log(parsed.entries.length);
} else {
  console.log(parsed.regions.length);
}

• CLI inspection (development only):

  # Preferred: only provide file path.
  # For v1 osm.dybuf, the tool auto-infers level/londex/latdex from .../<lv>/<x>/<y>/osm.dybuf
  node js/inspect_dybuf.mjs \
      --file /path/to/osm.dybuf \
      --limit 5
  
  # Optional fallback when path does not contain cell coordinates (needed for v1):
  node js/inspect_dybuf.mjs \
      --file /path/to/osm.dybuf \
      --level 8 --londex 213 --latdex 161 --limit 5

Grid helpers (grid_index)

grid_index.mjs exposes Gridex helpers (integers, pole triangles) aligned with the exporter:

import { GridUnit, Gridex, INT_COORD_SCALE } from "@truelies/osm-dybuf/grid_index";

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

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)

• Publish to npm (requires @truelies scope):

  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

• osm_dybuf.mjs / .d.mts: DyBuf parser entry points
• schema_ids.mjs / .d.mts: shared identifiers (geometry, feature, region, segment roles)
• 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.