@truelies/osm-dybuf 0.4.3 → 0.4.5

package/README.md

@@ -92,13 +92,17 @@ import {
   GridUnit,
   Gridex,
   INT_COORD_SCALE,
-  GRID16_LEVEL,
-  GRID16_LON_MAG_BITS,
-  GRID16_LAT_MAG_BITS,
-  grid16CodesFromLonLat,
-  buildGrid16LonLatRangeForLevelCell,
-  encodeSignedGridIndex,
-  decodeSignedGridIndex,
+  CANONICAL_CODE_LEVEL,
+  gridexAtLonLat,
+  gridCodeAtLonLat,
+  gridCodeComponentsAtLonLat,
+  lonCodeFromLondex,
+  latCodeFromLatdex,
+  londexPrefixCodeFromLonCode,
+  lonLatCodeRangeForGridex,
+  encodeAxisCode,
+  decodeAxisCode,
+  lonCodeMagnitudeBits,
 } from "@truelies/osm-dybuf/grid_index";
 
 const unit = new GridUnit(8); // level 8
@@ -109,17 +113,27 @@ const [minLon, minLat, maxLon, maxLat] = unit.boundsOfGrid(cell);
 const children = unit.toLowerLevelGridexes(cell);   // level 9, 4 cells
 const parent = new GridUnit(9).toUpperLevelGridex(children[0]); // back to level 8
 
-// canonical lv16 codes for Firestore / Redis
-const codes = grid16CodesFromLonLat(121.56, 25.03);
-console.log(codes.grid16LonCode, codes.grid16LatCode);
-
-// query a lv15 cell by expanding it into a lv16 numeric range
-const range = buildGrid16LonLatRangeForLevelCell(15, -3, 4);
-console.log(range.lon.from, range.lon.to, range.lat.from, range.lat.to);
-
-// signed code roundtrip
-const lonCode = encodeSignedGridIndex(-123, GRID16_LON_MAG_BITS);
-console.log(decodeSignedGridIndex(lonCode, GRID16_LON_MAG_BITS)); // -123
+// GPS -> gridex / lonCode / latCode / gridCode
+const gridex = gridexAtLonLat(16, 121.56, 25.03);
+const parts = gridCodeComponentsAtLonLat(16, 121.56, 25.03);
+console.log(gridex.londex, gridex.latdex);
+console.log(parts.lonCode, parts.latCode, parts.gridCode);
+
+// gridex <-> code
+const lonCode = lonCodeFromLondex(16, -123);
+const latCode = latCodeFromLatdex(16, 456);
+console.log(lonCode, latCode);
+console.log(gridCodeAtLonLat(16, 121.56, 25.03));
+
+// canonical prefix / range for coarser level query
+const lonPrefix = londexPrefixCodeFromLonCode(15, lonCode, CANONICAL_CODE_LEVEL);
+const range = lonLatCodeRangeForGridex(15, -3, 4, CANONICAL_CODE_LEVEL);
+console.log(lonPrefix, range.lonCode.from, range.lonCode.to);
+
+// axis code roundtrip
+const lonBits = lonCodeMagnitudeBits(CANONICAL_CODE_LEVEL);
+const axisCode = encodeAxisCode(-123, lonBits);
+console.log(decodeAxisCode(axisCode, lonBits)); // -123
 ```
 
 - `toLowerLevelGridexes(gridex)`:
@@ -128,15 +142,20 @@ console.log(decodeSignedGridIndex(lonCode, GRID16_LON_MAG_BITS)); // -123
 - `toUpperLevelGridex(gridex)`:
   - returns the parent cell at `level - 1`
   - throws when current unit is level `0`
-- `grid16CodesFromLonLat(lon, lat)`:
-  - converts GPS directly to canonical `lv16` codes
-  - returns `{ grid16LonCode, grid16LatCode, londex16, latdex16 }`
-- `buildGrid16LonLatRangeForLevelCell(level, londex, latdex)`:
-  - converts any `lv <= 16` cell into the corresponding `lv16` prefix range
-  - intended for Firestore numeric range query / Redis derived bucket lookup
-- `encodeSignedGridIndex(index, magnitudeBits)` / `decodeSignedGridIndex(code, magnitudeBits)`:
+- `gridexAtLonLat(level, lon, lat)`:
+  - converts GPS directly to a `Gridex`
+- `gridCodeComponentsAtLonLat(level, lon, lat)`:
+  - returns `{ gridex, lonCode, latCode, gridCode }`
+- `lonCodeFromLondex(level, londex)` / `latCodeFromLatdex(level, latdex)`:
+  - converts axis indices to canonical axis codes
+- `londexPrefixCodeFromLonCode(targetLevel, lonCode, sourceLevel?)`:
+  - trims a finer `lonCode` into a coarser-level prefix view
+- `lonLatCodeRangeForGridex(level, londex, latdex, sourceLevel?)`:
+  - expands any `lv <= sourceLevel` cell into the corresponding canonical axis-code range
+- `gridCodeAtLonLat(level, lon, lat)` / `gridCodeFromGridex(level, gridex)`:
+  - returns the packed `gridCode`
+- `encodeAxisCode(index, magnitudeBits)` / `decodeAxisCode(code, magnitudeBits)`:
   - encodes grid index as `sign bit + (abs(index) - 1)`
-  - for `lv16`, use `GRID16_LON_MAG_BITS = 19` and `GRID16_LAT_MAG_BITS = 18`
 
 ## Local Development
 
@@ -150,9 +169,9 @@ 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)
-- canonical signed grid index encode/decode roundtrip
-- GPS -> `lv16` code conversion
-- `lv15` cell -> `lv16` range expansion correctness
+- canonical axis-code encode/decode roundtrip
+- GPS -> `gridex / lonCode / latCode / gridCode`
+- `lv15` cell -> canonical code range expansion correctness
 
 - `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)
@@ -174,4 +193,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.3` aligns the package with the current `lv0~13` export range, the current frontend feature set (`water_wetland`, `building`, derived `label_*`, no exported `place_label`), the numeric `featureId` parser contract, and the new `lv16` canonical grid code helpers for Firestore / Redis indexing.
+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.3` aligns the package with the current `lv0~13` export range, the current frontend feature set (`water_wetland`, `building`, derived `label_*`, no exported `place_label`), the numeric `featureId` parser contract, and the canonical grid conversion helpers shared by Firestore / Redis / frontend indexing.

package/grid_index.d.ts

@@ -2,9 +2,7 @@ export declare const INT_COORD_SCALE: number;
 export declare const GRID_FINE_RES: number;
 export declare const GRID_LV0_UNIT: number;
 export declare const MAX_LEVEL: number;
-export declare const GRID16_LEVEL: number;
-export declare const GRID16_LON_MAG_BITS: number;
-export declare const GRID16_LAT_MAG_BITS: number;
+export declare const CANONICAL_CODE_LEVEL: number;
 export declare class Gridex {
   readonly londex: number;
   readonly latdex: number;
@@ -53,36 +51,65 @@ export declare class GridUnit {
 }
 export declare function gridexAtLonLat(level: number, longitude: number, latitude: number): GridexAtLv;
 export declare function gridexStringAtLonLat(level: number, longitude: number, latitude: number): string;
-export declare function encodeSignedGridIndex(index: number, magnitudeBits: number): number;
-export declare function decodeSignedGridIndex(code: number, magnitudeBits: number): number;
-export declare function grid16CodesFromLonLat(
-  longitude: number,
-  latitude: number
+export declare function lonCodeMagnitudeBits(level: number): number;
+export declare function latCodeMagnitudeBits(level: number): number;
+export declare function encodeAxisCode(index: number, magnitudeBits: number): number;
+export declare function decodeAxisCode(code: number, magnitudeBits: number): number;
+export declare function lonCodeFromLondex(level: number, londex: number): number;
+export declare function latCodeFromLatdex(level: number, latdex: number): number;
+export declare function londexFromLonCode(level: number, lonCode: number): number;
+export declare function latdexFromLatCode(level: number, latCode: number): number;
+export declare function londexPrefixCodeFromLonCode(targetLevel: number, lonCode: number, sourceLevel?: number): number;
+export declare function latdexPrefixCodeFromLatCode(targetLevel: number, latCode: number, sourceLevel?: number): number;
+export declare function lonCodeRangeForLondex(
+  level: number,
+  londex: number,
+  sourceLevel?: number
 ): {
-  grid16LonCode: number;
-  grid16LatCode: number;
-  londex16: number;
-  latdex16: number;
+  from: number;
+  to: number;
 };
-export declare function buildGrid16RangeForLevelIndex(
+export declare function latCodeRangeForLatdex(
   level: number,
-  index: number,
-  magnitudeBits: number
+  latdex: number,
+  sourceLevel?: number
 ): {
   from: number;
   to: number;
 };
-export declare function buildGrid16LonLatRangeForLevelCell(
+export declare function lonLatCodeRangeForGridex(
   level: number,
   londex: number,
-  latdex: number
+  latdex: number,
+  sourceLevel?: number
 ): {
-  lon: {
+  lonCode: {
     from: number;
     to: number;
   };
-  lat: {
+  latCode: {
     from: number;
     to: number;
   };
 };
+export declare function gridCodeFromLonLatCodes(level: number, lonCode: number, latCode: number): number;
+export declare function lonLatCodesFromGridCode(
+  level: number,
+  gridCode: number
+): {
+  lonCode: number;
+  latCode: number;
+};
+export declare function gridCodeFromGridex(level: number, gridex: Gridex | number, latdex?: number): number;
+export declare function gridexFromGridCode(level: number, gridCode: number): GridexAtLv;
+export declare function gridCodeAtLonLat(level: number, longitude: number, latitude: number): number;
+export declare function gridCodeComponentsAtLonLat(
+  level: number,
+  longitude: number,
+  latitude: number
+): {
+  gridex: GridexAtLv;
+  lonCode: number;
+  latCode: number;
+  gridCode: number;
+};

package/grid_index.mjs

@@ -11,9 +11,7 @@ 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;
 const MIN_LATITUDE_FINE = -MAX_LATITUDE_FINE;
-export const GRID16_LEVEL = 16;
-export const GRID16_LON_MAG_BITS = 19;
-export const GRID16_LAT_MAG_BITS = 18;
+export const CANONICAL_CODE_LEVEL = MAX_LEVEL;
 
 export class Gridex {
   constructor(londex, latdex) {
@@ -266,7 +264,17 @@ export function gridexStringAtLonLat(level, longitude, latitude) {
   return `${gridex.londex},${gridex.latdex}`;
 }
 
-export function encodeSignedGridIndex(index, magnitudeBits) {
+export function lonCodeMagnitudeBits(level) {
+  const unit = new GridUnit(level);
+  return Math.ceil(Math.log2(unit.maxLondex));
+}
+
+export function latCodeMagnitudeBits(level) {
+  const unit = new GridUnit(level);
+  return Math.ceil(Math.log2(unit.maxLatdex));
+}
+
+export function encodeAxisCode(index, magnitudeBits) {
   if (!Number.isInteger(index) || index === 0) {
     throw new Error(`Grid index must be a non-zero integer: ${index}`);
   }
@@ -279,7 +287,7 @@ export function encodeSignedGridIndex(index, magnitudeBits) {
   return (signBit << magnitudeBits) | magnitude;
 }
 
-export function decodeSignedGridIndex(code, magnitudeBits) {
+export function decodeAxisCode(code, magnitudeBits) {
   if (!Number.isInteger(code) || code < 0) {
     throw new Error(`Grid code must be a non-negative integer: ${code}`);
   }
@@ -289,41 +297,142 @@ export function decodeSignedGridIndex(code, magnitudeBits) {
   return (magnitude + 1) * (signBit === 1 ? 1 : -1);
 }
 
-export function grid16CodesFromLonLat(longitude, latitude) {
-  const gridex16 = gridexAtLonLat(GRID16_LEVEL, longitude, latitude);
-  return {
-    grid16LonCode: encodeSignedGridIndex(gridex16.londex, GRID16_LON_MAG_BITS),
-    grid16LatCode: encodeSignedGridIndex(gridex16.latdex, GRID16_LAT_MAG_BITS),
-    londex16: gridex16.londex,
-    latdex16: gridex16.latdex,
-  };
+export function lonCodeFromLondex(level, londex) {
+  return encodeAxisCode(londex, lonCodeMagnitudeBits(level));
+}
+
+export function latCodeFromLatdex(level, latdex) {
+  return encodeAxisCode(latdex, latCodeMagnitudeBits(level));
 }
 
-export function buildGrid16RangeForLevelIndex(level, index, magnitudeBits) {
-  if (!Number.isInteger(level) || level < 0 || level > GRID16_LEVEL) {
-    throw new Error(`Level must be an integer between 0 and ${GRID16_LEVEL}: ${level}`);
+export function londexFromLonCode(level, lonCode) {
+  return decodeAxisCode(lonCode, lonCodeMagnitudeBits(level));
+}
+
+export function latdexFromLatCode(level, latCode) {
+  return decodeAxisCode(latCode, latCodeMagnitudeBits(level));
+}
+
+function axisCodePrefixFromCode(targetLevel, axisCode, sourceLevel, magnitudeBits) {
+  if (!Number.isInteger(targetLevel) || targetLevel < 0 || targetLevel > sourceLevel) {
+    throw new Error(`targetLevel must be an integer between 0 and ${sourceLevel}: ${targetLevel}`);
+  }
+  const signBase = 2 ** magnitudeBits;
+  const signBit = Math.floor(axisCode / signBase);
+  const magnitude = axisCode % signBase;
+  const shift = sourceLevel - targetLevel;
+  const prefixMagnitude = shift === 0 ? magnitude : Math.floor(magnitude / (2 ** shift)) * (2 ** shift);
+  return signBit * signBase + prefixMagnitude;
+}
+
+export function londexPrefixCodeFromLonCode(targetLevel, lonCode, sourceLevel = CANONICAL_CODE_LEVEL) {
+  return axisCodePrefixFromCode(targetLevel, lonCode, sourceLevel, lonCodeMagnitudeBits(sourceLevel));
+}
+
+export function latdexPrefixCodeFromLatCode(targetLevel, latCode, sourceLevel = CANONICAL_CODE_LEVEL) {
+  return axisCodePrefixFromCode(targetLevel, latCode, sourceLevel, latCodeMagnitudeBits(sourceLevel));
+}
+
+function axisCodeRangeForIndex(targetLevel, index, sourceLevel, magnitudeBits) {
+  if (!Number.isInteger(sourceLevel) || sourceLevel < 0 || sourceLevel > MAX_LEVEL) {
+    throw new Error(`sourceLevel must be an integer between 0 and ${MAX_LEVEL}: ${sourceLevel}`);
+  }
+  if (!Number.isInteger(targetLevel) || targetLevel < 0 || targetLevel > sourceLevel) {
+    throw new Error(`targetLevel must be an integer between 0 and ${sourceLevel}: ${targetLevel}`);
   }
   if (!Number.isInteger(index) || index === 0) {
     throw new Error(`Grid index must be a non-zero integer: ${index}`);
   }
   const signBit = index > 0 ? 1 : 0;
-  const shift = GRID16_LEVEL - level;
+  const shift = sourceLevel - targetLevel;
   const magnitude = Math.abs(index) - 1;
   const fromMagnitude = magnitude << shift;
   const toMagnitude = ((magnitude + 1) << shift) - 1;
-  const maxMagnitude = (1 << magnitudeBits) - 1;
+  const maxMagnitude = (2 ** magnitudeBits) - 1;
   if (toMagnitude > maxMagnitude) {
-    throw new Error(`Grid index ${index} at level ${level} exceeds lv16 range`);
+    throw new Error(`Grid index ${index} at level ${targetLevel} exceeds source level ${sourceLevel} range`);
+  }
+  const signBase = 2 ** magnitudeBits;
+  return {
+    from: signBit * signBase + fromMagnitude,
+    to: signBit * signBase + toMagnitude,
+  };
+}
+
+export function lonCodeRangeForLondex(level, londex, sourceLevel = CANONICAL_CODE_LEVEL) {
+  return axisCodeRangeForIndex(level, londex, sourceLevel, lonCodeMagnitudeBits(sourceLevel));
+}
+
+export function latCodeRangeForLatdex(level, latdex, sourceLevel = CANONICAL_CODE_LEVEL) {
+  return axisCodeRangeForIndex(level, latdex, sourceLevel, latCodeMagnitudeBits(sourceLevel));
+}
+
+export function lonLatCodeRangeForGridex(level, londex, latdex, sourceLevel = CANONICAL_CODE_LEVEL) {
+  return {
+    lonCode: lonCodeRangeForLondex(level, londex, sourceLevel),
+    latCode: latCodeRangeForLatdex(level, latdex, sourceLevel),
+  };
+}
+
+export function gridCodeFromLonLatCodes(level, lonCode, latCode) {
+  const latCodeWidth = latCodeMagnitudeBits(level) + 1;
+  const latCodeSpan = 2 ** latCodeWidth;
+  if (!Number.isInteger(lonCode) || lonCode < 0) {
+    throw new Error(`lonCode must be a non-negative integer: ${lonCode}`);
+  }
+  if (!Number.isInteger(latCode) || latCode < 0 || latCode >= latCodeSpan) {
+    throw new Error(`latCode out of range for level ${level}: ${latCode}`);
   }
+  return lonCode * latCodeSpan + latCode;
+}
+
+export function lonLatCodesFromGridCode(level, gridCode) {
+  if (!Number.isInteger(gridCode) || gridCode < 0) {
+    throw new Error(`gridCode must be a non-negative integer: ${gridCode}`);
+  }
+  const latCodeWidth = latCodeMagnitudeBits(level) + 1;
+  const latCodeSpan = 2 ** latCodeWidth;
   return {
-    from: (signBit << magnitudeBits) | fromMagnitude,
-    to: (signBit << magnitudeBits) | toMagnitude,
+    lonCode: Math.floor(gridCode / latCodeSpan),
+    latCode: gridCode % latCodeSpan,
   };
 }
 
-export function buildGrid16LonLatRangeForLevelCell(level, londex, latdex) {
+export function gridCodeFromGridex(level, gridex, latdex) {
+  const londex = typeof gridex === "object" ? gridex.londex : gridex;
+  const resolvedLatdex = typeof gridex === "object" ? gridex.latdex : latdex;
+  if (!Number.isInteger(londex) || !Number.isInteger(resolvedLatdex)) {
+    throw new Error("gridCodeFromGridex expects londex/latdex integers or a Gridex-like object");
+  }
+  return gridCodeFromLonLatCodes(
+    level,
+    lonCodeFromLondex(level, londex),
+    latCodeFromLatdex(level, resolvedLatdex),
+  );
+}
+
+export function gridexFromGridCode(level, gridCode) {
+  const { lonCode, latCode } = lonLatCodesFromGridCode(level, gridCode);
+  const unit = new GridUnit(level);
+  return unit.makeGridex(
+    londexFromLonCode(level, lonCode),
+    latdexFromLatCode(level, latCode),
+  );
+}
+
+export function gridCodeAtLonLat(level, longitude, latitude) {
+  const gridex = gridexAtLonLat(level, longitude, latitude);
+  return gridCodeFromGridex(level, gridex);
+}
+
+export function gridCodeComponentsAtLonLat(level, longitude, latitude) {
+  const gridex = gridexAtLonLat(level, longitude, latitude);
+  const lonCode = lonCodeFromLondex(level, gridex.londex);
+  const latCode = latCodeFromLatdex(level, gridex.latdex);
   return {
-    lon: buildGrid16RangeForLevelIndex(level, londex, GRID16_LON_MAG_BITS),
-    lat: buildGrid16RangeForLevelIndex(level, latdex, GRID16_LAT_MAG_BITS),
+    gridex,
+    lonCode,
+    latCode,
+    gridCode: gridCodeFromLonLatCodes(level, lonCode, latCode),
   };
 }

package/package.json

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