@truelies/osm-dybuf 0.3.0 → 0.3.1

package/README.md

@@ -60,7 +60,7 @@ if (parsed.format === "flat_v1") {
 
 ### Grid helpers (grid_index)
 
-`grid_index.ts` exposes the minimal Gridex helpers (integers, pole triangles) aligned with the exporter:
+`grid_index.mjs` exposes Gridex helpers (integers, pole triangles) aligned with the exporter:
 
 ```ts
 import { GridUnit, Gridex, INT_COORD_SCALE } from "@truelies/osm-dybuf/grid_index";
@@ -68,18 +68,44 @@ import { GridUnit, Gridex, INT_COORD_SCALE } from "@truelies/osm-dybuf/grid_inde
 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
 
 ```bash
 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)
-- `npm publish --access public`: publish to npm (requires the `@truelies` scope). If the scope is not available, rename `package.json` → `"name": "truelies-osm-dybuf"` and publish without a scope.
+- Publish to npm (requires `@truelies` scope):
+  ```bash
+  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
 

package/grid_index.d.ts

@@ -31,6 +31,8 @@ export declare class GridUnit {
   makeGridex(londex: number, latdex: number): GridexAtLv;
   gridexesAt(longitudeInt: number, latitudeInt: number): GridexAtLv[];
   gridexesWithExt(longitudeInt: number, latitudeInt: number, ext?: number): GridexAtLv[];
+  toLowerLevelGridexes(gridex: Gridex): GridexAtLv[];
+  toUpperLevelGridex(gridex: Gridex): GridexAtLv;
   boundsOfGridFine(gridex: Gridex, applyTriangle?: boolean): [number, number, number, number];
   boundsOfGrid(gridex: Gridex, applyTriangle?: boolean): [number, number, number, number];
   gridexRangeForBounds(

package/grid_index.mjs

@@ -158,6 +158,43 @@ export class GridUnit {
     return result;
   }
 
+  toLowerLevelGridexes(gridex) {
+    if (this.level >= MAX_LEVEL) {
+      throw new Error(`No lower level exists for level ${this.level}`);
+    }
+    const lon = gridex.londex;
+    const lat = gridex.latdex;
+    const lonInc = lon > 0 ? -1 : 1;
+    const latInc = lat > 0 ? -1 : 1;
+    const childUnit = new GridUnit(this.level + 1);
+    return [
+      childUnit.makeGridex(lon * 2 + lonInc, lat * 2 + latInc),
+      childUnit.makeGridex(lon * 2 + lonInc, lat * 2),
+      childUnit.makeGridex(lon * 2, lat * 2 + latInc),
+      childUnit.makeGridex(lon * 2, lat * 2),
+    ];
+  }
+
+  toUpperLevelGridex(gridex) {
+    if (this.level <= 0) {
+      throw new Error("No upper level exists for level 0");
+    }
+    const lon = gridex.londex;
+    const lat = gridex.latdex;
+    const lonInc = lon > 0 ? -1 : 1;
+    const latInc = lat > 0 ? -1 : 1;
+    const upperLon =
+      lon > 0
+        ? Math.floor((lon - lonInc) / 2)
+        : Math.ceil((lon - lonInc) / 2);
+    const upperLat =
+      lat > 0
+        ? Math.floor((lat - latInc) / 2)
+        : Math.ceil((lat - latInc) / 2);
+    const upperUnit = new GridUnit(this.level - 1);
+    return upperUnit.makeGridex(upperLon, upperLat);
+  }
+
   boundsOfGridFine(gridex, applyTriangle = false) {
     const { londex, latdex } = gridex;
     const minLonFine = (londex - (londex > 0 ? 1 : 0)) * this.unitFine;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truelies/osm-dybuf",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Gridex OSM DyBuf parser and schema utilities",
   "type": "module",
   "main": "./osm_dybuf.mjs",
@@ -39,6 +39,9 @@
   ],
   "author": "TrueLies",
   "license": "UNLICENSED",
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
   "dependencies": {
     "dybuf": "^0.4.2"
   }