nodes2ts 4.0.0 → 4.0.2

package/dist/export.cjs

@@ -3350,6 +3350,13 @@ var UINT64_MAX = 0xFFFFFFFFFFFFFFFFn;
 
 // src/S2Projections.ts
 var _S2Projections = class _S2Projections {
+  /**
+   * The maximum value of an si- or ti-coordinate. The range of valid (si,ti) values is
+   * [0..MAX_SiTi].
+   */
+  static get MAX_SITI() {
+    return 1n << BigInt(_S2Projections.MAX_LEVEL + 1);
+  }
   static getUNorm(face, u) {
     switch (face) {
       case 0:
@@ -3590,24 +3597,38 @@ _S2Projections.XYZ_TRANSFORMS = [
     }
   }
 ];
-/**
- * The maximum value of an si- or ti-coordinate. The range of valid (si,ti) values is
- * [0..MAX_SiTi].
- */
-_S2Projections.MAX_SITI = 1n << BigInt(_S2Projections.MAX_LEVEL + 1);
 var S2Projections = _S2Projections;
 
 // src/S2CellId.ts
 var _S2CellId = class _S2CellId {
   /**
-   * Construct an S2CellId from a bigint or decimal string.
+   * Construct an S2CellId from a bigint, decimal string, or number.
    *
    * The string may be signed ("-6533045114107854848") or unsigned
    * ("11913698959601696768"); both are handled via BigInt.asUintN(64, ...).
+   *
+   * Numbers must be finite integers within the safe-integer range
+   * (|n| ≤ Number.MAX_SAFE_INTEGER = 2^53 − 1). Values outside that range
+   * may have silently lost precision in JS before reaching this constructor,
+   * so a RangeError is thrown. Use a bigint literal for large cell IDs
+   * (e.g. `-9182983676231680000n`).
+   *
+   * @throws {TypeError}  if `id` is a non-integer or non-finite number.
+   * @throws {RangeError} if `id` exceeds safe-integer precision (> 2^53 − 1).
    */
   constructor(id) {
     if (typeof id === "string") {
       this.id = BigInt.asUintN(64, BigInt(id));
+    } else if (typeof id === "number") {
+      if (!Number.isInteger(id) || !isFinite(id)) {
+        throw new TypeError(`S2CellId: non-integer or non-finite number: ${id}`);
+      }
+      if (!Number.isSafeInteger(id)) {
+        throw new RangeError(
+          `S2CellId: number ${id} exceeds safe integer precision (> 2^53). Use a bigint literal instead, e.g. ${BigInt(id)}n`
+        );
+      }
+      this.id = BigInt.asUintN(64, BigInt(id));
     } else {
       this.id = BigInt.asUintN(64, id);
     }
@@ -4191,7 +4212,7 @@ var _S2CellId = class _S2CellId {
    * Binary search in a sorted S2CellId array.
    * Returns index if found, or -(insertionPoint+1) if not found.
    *
-   * v4: `_id` accepts bigint, string, or S2CellId (was Long, string, or S2CellId).
+   * v4: `_id` accepts bigint, string, number, or S2CellId (was Long, string, or S2CellId).
    */
   static binarySearch(ids, _id, low = 0) {
     let id;
@@ -4223,10 +4244,20 @@ _S2CellId.FACE_BITS = 3;
 _S2CellId.NUM_FACES = 6;
 _S2CellId.MAX_LEVEL = 30;
 // Valid levels: 0..MAX_LEVEL
-_S2CellId.POS_BITS = 2 * _S2CellId.MAX_LEVEL + 1;
-// 61
-_S2CellId.MAX_SIZE = 1 << _S2CellId.MAX_LEVEL;
-// 2^30
+/**
+ * The number of bits used by a position along the Hilbert curve over all
+ * faces (range 1..2*MAX_LEVEL+1). This is a fixed constant encoding the
+ * canonical 64-bit S2 cell ID layout; it must NEVER be derived from a
+ * mutable MAX_LEVEL.
+ */
+_S2CellId.POS_BITS = 2 * 30 + 1;
+// = 61
+/**
+ * The maximum coordinate value for an (i,j) cell index. Equal to 2^30.
+ * Fixed constant matching the 30-level S2 grid.
+ */
+_S2CellId.MAX_SIZE = 1 << 30;
+// = 1073741824
 /** Maximum unsigned 64-bit value (sentinel). */
 _S2CellId.MAX_UNSIGNED = UINT64_MAX;
 // The following lookup tables are used to convert efficiently between an
@@ -4250,6 +4281,10 @@ _S2CellId.LOOKUP_IJ = [];
  * This is the offset required to wrap around from the beginning of the
  * Hilbert curve to the end or vice versa; see next_wrap() and prev_wrap().
  */
+/**
+ * Precomputed wrap offset. Fixed constant; must not be derived from a
+ * mutable POS_BITS.
+ */
 _S2CellId.WRAP_OFFSET = BigInt(_S2CellId.NUM_FACES) << BigInt(_S2CellId.POS_BITS);
 var S2CellId = _S2CellId;
 function initLookupCell(level, i, j, origOrientation, pos, orientation) {
@@ -4314,6 +4349,9 @@ var _S2Cell = class _S2Cell {
       this.init(cellID);
     }
   }
+  static get MAX_CELL_SIZE() {
+    return 1 << S2CellId.MAX_LEVEL;
+  }
   get id() {
     return this.cellID;
   }
@@ -4603,7 +4641,6 @@ var _S2Cell = class _S2Cell {
     };
   }
 };
-_S2Cell.MAX_CELL_SIZE = 1 << S2CellId.MAX_LEVEL;
 // We grow the bounds slightly to make sure that the bounding rectangle
 // also contains the normalized versions of the vertices. Note that the
 // maximum result magnitude is Pi, with a floating-point exponent of 1.
@@ -4628,7 +4665,7 @@ var S2CellUnion = class {
    * Populates a cell union with the given S2CellIds or 64-bit cell ids, and
    * then calls Normalize().
    *
-   * v4: `cellIds` accepts `bigint[] | string[]` (was `Long[] | string[]`).
+   * v4: `cellIds` accepts `bigint[] | string[] | number[]` (was `Long[] | string[]`).
    */
   initFromIds(cellIds) {
     this.initRawIds(cellIds);
@@ -5283,6 +5320,41 @@ var QueueEntry = class {
 
 // src/export.ts
 var Utils = class {
+  /**
+   * Atomically updates the maximum cell level across all S2 classes.
+   *
+   * This sets the `MAX_LEVEL` field on `S2`, `S2CellId`, and `S2Projections`
+   * in one call, keeping them in sync.
+   *
+   * **What changes:**
+   * - `S2Cell.MAX_CELL_SIZE` (derived via getter from `S2CellId.MAX_LEVEL`)
+   * - `S2Projections.MAX_SITI` (derived via getter)
+   * - `S2CellId.getSizeIJ()` / `S2CellId.getSizeST()` size calculations
+   * - Default max-level caps in `S2RegionCoverer` and `S2Metric`
+   * - `S2CellId.isLeaf()` / `level()` detection of the leaf level
+   *
+   * **What does NOT change:**
+   * - `S2CellId.POS_BITS` (always 61) — the 64-bit S2 cell ID bit layout is
+   *   a fixed canonical format; changing it breaks encoding/decoding.
+   * - `S2CellId.MAX_SIZE` (always 2^30) — the Hilbert-curve grid resolution.
+   * - `S2CellId.WRAP_OFFSET` — derived from the fixed `POS_BITS`.
+   *
+   * For shorter cell tokens, use `parentL(desiredLevel)` or set
+   * `S2RegionCoverer.maxLevel`; `toToken()` naturally produces compact hex
+   * strings for lower-level cells (e.g. level 10 → 6 hex chars).
+   *
+   * @param level — integer in [1, 30]
+   */
+  static setMaxLevel(level) {
+    if (!Number.isInteger(level) || level < 1 || level > 30) {
+      throw new RangeError(
+        `MAX_LEVEL must be an integer in [1, 30], got ${level}`
+      );
+    }
+    S2.MAX_LEVEL = level;
+    S2CellId.MAX_LEVEL = level;
+    S2Projections.MAX_LEVEL = level;
+  }
   /**
    * Calculates a region covering a circle
    * NOTE: The current implementation uses S2Cap while S2Loop would be better (S2Loop is not implemented yet)