@exabugs/dynamodb-client 1.1.2 → 1.2.0

package/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-01-02
+
+### Added
+
+- **GeoHash地理空間検索**: MongoDB互換の`$near`オペレータを実装
+  - 自動GeoHash変換: `{latitude, longitude}`オブジェクトを自動検出してシャドウインデックス生成
+  - 9ブロック検索: 中心 + 隣接8方向の合計9ブロックを検索して境界をまたぐ検索漏れを防止
+  - 段階的精度緩和: precision 6→5→4と段階的に検索範囲を拡大
+  - 距離計算・ソート: Haversine公式による正確な距離計算と自動ソート
+  - `__distance`フィールド: 検索地点からの距離（メートル）を自動付与
+  - `__geohash`フィールド: 検出されたGeoHashを自動付与
+  - フィールド名非依存: `location`固定ではなく、任意のフィールド名を自動検出
+  - 透過的実装: クライアントはGeoHashを意識せず、通常のオブジェクトとして扱える
+  - 設定可能なパラメータ: `GeoHashConfig`で精度や反復回数をカスタマイズ可能
+
+- **新しいユーティリティ関数**:
+  - `isGeoCoordinates()`: 地理座標オブジェクトの自動検出
+  - `encodeGeoHash()`: 緯度・経度からGeoHashを生成
+  - `decodeGeoHash()`: GeoHashから緯度・経度を復元
+  - `getNeighborGeoHashes()`: 隣接8方向のGeoHashを取得
+  - `calculateDistance()`: Haversine公式による2点間の距離計算
+  - `extractCoordinatesFromNearQuery()`: $nearクエリから座標を抽出
+  - `extractMaxDistanceFromNearQuery()`: $nearクエリから最大距離を抽出
+  - `extractMinDistanceFromNearQuery()`: $nearクエリから最小距離を抽出
+
+- **新しい型定義**:
+  - `GeoCoordinates`: 地理座標オブジェクト型
+  - `NearQuery`: MongoDB互換の$nearクエリ型（GeoJSON形式と簡易形式をサポート）
+  - `DocumentWithDistance`: 距離情報付きドキュメント型
+  - `GeoHashConfig`: GeoHash検索の設定型
+  - `DEFAULT_GEOHASH_CONFIG`: デフォルト設定定数
+
+### Changed
+
+- **シャドウレコード生成**: `generator.ts`を更新して地理座標の自動検出とGeoHashシャドウレコード生成を追加
+  - シャドウインデックスは8文字精度（±19m）で保存
+  - 検索は6文字精度（±610m）で開始し、段階的に緩和
+  - 既存のシャドウ化機能（文字列フィールド等）と共存
+
+### Dependencies
+
+- **追加**: `ngeohash@^0.6.3` - GeoHashエンコード・デコードライブラリ
+- **追加**: `@types/ngeohash@^0.6.8` - ngeohashの型定義
+
+### Notes
+
+- この機能は後方互換性があります。既存のコードは変更なしで動作します。
+- GeoHash検索を使用するには、`{latitude, longitude}`オブジェクトを持つフィールドを作成するだけです。
+- 詳細な使用方法は [GeoHash Search Guide](./docs/geohash-search.md) を参照してください。
+
 ## [1.1.2] - 2025-01-02
 
 ### Fixed

package/dist/server/handler.cjs

@@ -1,5 +1,5 @@
-// @exabugs/dynamodb-client v1.1.2
-// Built: 2026-01-01T17:49:53.300Z
+// @exabugs/dynamodb-client v1.2.0
+// Built: 2026-01-02T06:28:54.806Z
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -28605,6 +28605,320 @@ var require_dist_cjs66 = __commonJS({
   }
 });
 
+// node_modules/ngeohash/main.js
+var require_main = __commonJS({
+  "node_modules/ngeohash/main.js"(exports2, module2) {
+    var BASE32_CODES = "0123456789bcdefghjkmnpqrstuvwxyz";
+    var BASE32_CODES_DICT = {};
+    for (i4 = 0; i4 < BASE32_CODES.length; i4++) {
+      BASE32_CODES_DICT[BASE32_CODES.charAt(i4)] = i4;
+    }
+    var i4;
+    var ENCODE_AUTO = "auto";
+    var MIN_LAT = -90;
+    var MAX_LAT = 90;
+    var MIN_LON = -180;
+    var MAX_LON = 180;
+    var SIGFIG_HASH_LENGTH = [0, 5, 7, 8, 11, 12, 13, 15, 16, 17, 18];
+    var encode2 = /* @__PURE__ */ __name(function(latitude, longitude, numberOfChars) {
+      if (numberOfChars === ENCODE_AUTO) {
+        if (typeof latitude === "number" || typeof longitude === "number") {
+          throw new Error("string notation required for auto precision.");
+        }
+        var decSigFigsLat = latitude.split(".")[1].length;
+        var decSigFigsLong = longitude.split(".")[1].length;
+        var numberOfSigFigs = Math.max(decSigFigsLat, decSigFigsLong);
+        numberOfChars = SIGFIG_HASH_LENGTH[numberOfSigFigs];
+      } else if (numberOfChars === void 0) {
+        numberOfChars = 9;
+      }
+      var chars = [], bits = 0, bitsTotal = 0, hash_value = 0, maxLat = MAX_LAT, minLat = MIN_LAT, maxLon = MAX_LON, minLon = MIN_LON, mid;
+      while (chars.length < numberOfChars) {
+        if (bitsTotal % 2 === 0) {
+          mid = (maxLon + minLon) / 2;
+          if (longitude > mid) {
+            hash_value = (hash_value << 1) + 1;
+            minLon = mid;
+          } else {
+            hash_value = (hash_value << 1) + 0;
+            maxLon = mid;
+          }
+        } else {
+          mid = (maxLat + minLat) / 2;
+          if (latitude > mid) {
+            hash_value = (hash_value << 1) + 1;
+            minLat = mid;
+          } else {
+            hash_value = (hash_value << 1) + 0;
+            maxLat = mid;
+          }
+        }
+        bits++;
+        bitsTotal++;
+        if (bits === 5) {
+          var code = BASE32_CODES[hash_value];
+          chars.push(code);
+          bits = 0;
+          hash_value = 0;
+        }
+      }
+      return chars.join("");
+    }, "encode");
+    var encode_int = /* @__PURE__ */ __name(function(latitude, longitude, bitDepth) {
+      bitDepth = bitDepth || 52;
+      var bitsTotal = 0, maxLat = MAX_LAT, minLat = MIN_LAT, maxLon = MAX_LON, minLon = MIN_LON, mid, combinedBits = 0;
+      while (bitsTotal < bitDepth) {
+        combinedBits *= 2;
+        if (bitsTotal % 2 === 0) {
+          mid = (maxLon + minLon) / 2;
+          if (longitude > mid) {
+            combinedBits += 1;
+            minLon = mid;
+          } else {
+            maxLon = mid;
+          }
+        } else {
+          mid = (maxLat + minLat) / 2;
+          if (latitude > mid) {
+            combinedBits += 1;
+            minLat = mid;
+          } else {
+            maxLat = mid;
+          }
+        }
+        bitsTotal++;
+      }
+      return combinedBits;
+    }, "encode_int");
+    var decode_bbox = /* @__PURE__ */ __name(function(hash_string) {
+      var isLon = true, maxLat = MAX_LAT, minLat = MIN_LAT, maxLon = MAX_LON, minLon = MIN_LON, mid;
+      var hashValue = 0;
+      for (var i5 = 0, l4 = hash_string.length; i5 < l4; i5++) {
+        var code = hash_string[i5].toLowerCase();
+        hashValue = BASE32_CODES_DICT[code];
+        for (var bits = 4; bits >= 0; bits--) {
+          var bit = hashValue >> bits & 1;
+          if (isLon) {
+            mid = (maxLon + minLon) / 2;
+            if (bit === 1) {
+              minLon = mid;
+            } else {
+              maxLon = mid;
+            }
+          } else {
+            mid = (maxLat + minLat) / 2;
+            if (bit === 1) {
+              minLat = mid;
+            } else {
+              maxLat = mid;
+            }
+          }
+          isLon = !isLon;
+        }
+      }
+      return [minLat, minLon, maxLat, maxLon];
+    }, "decode_bbox");
+    var decode_bbox_int = /* @__PURE__ */ __name(function(hashInt, bitDepth) {
+      bitDepth = bitDepth || 52;
+      var maxLat = MAX_LAT, minLat = MIN_LAT, maxLon = MAX_LON, minLon = MIN_LON;
+      var latBit = 0, lonBit = 0;
+      var step = bitDepth / 2;
+      for (var i5 = 0; i5 < step; i5++) {
+        lonBit = get_bit(hashInt, (step - i5) * 2 - 1);
+        latBit = get_bit(hashInt, (step - i5) * 2 - 2);
+        if (latBit === 0) {
+          maxLat = (maxLat + minLat) / 2;
+        } else {
+          minLat = (maxLat + minLat) / 2;
+        }
+        if (lonBit === 0) {
+          maxLon = (maxLon + minLon) / 2;
+        } else {
+          minLon = (maxLon + minLon) / 2;
+        }
+      }
+      return [minLat, minLon, maxLat, maxLon];
+    }, "decode_bbox_int");
+    function get_bit(bits, position) {
+      return bits / Math.pow(2, position) & 1;
+    }
+    __name(get_bit, "get_bit");
+    var decode2 = /* @__PURE__ */ __name(function(hashString) {
+      var bbox = decode_bbox(hashString);
+      var lat = (bbox[0] + bbox[2]) / 2;
+      var lon = (bbox[1] + bbox[3]) / 2;
+      var latErr = bbox[2] - lat;
+      var lonErr = bbox[3] - lon;
+      return {
+        latitude: lat,
+        longitude: lon,
+        error: { latitude: latErr, longitude: lonErr }
+      };
+    }, "decode");
+    var decode_int = /* @__PURE__ */ __name(function(hash_int, bitDepth) {
+      var bbox = decode_bbox_int(hash_int, bitDepth);
+      var lat = (bbox[0] + bbox[2]) / 2;
+      var lon = (bbox[1] + bbox[3]) / 2;
+      var latErr = bbox[2] - lat;
+      var lonErr = bbox[3] - lon;
+      return {
+        latitude: lat,
+        longitude: lon,
+        error: { latitude: latErr, longitude: lonErr }
+      };
+    }, "decode_int");
+    var neighbor = /* @__PURE__ */ __name(function(hashString, direction) {
+      var lonLat = decode2(hashString);
+      var neighborLat = lonLat.latitude + direction[0] * lonLat.error.latitude * 2;
+      var neighborLon = lonLat.longitude + direction[1] * lonLat.error.longitude * 2;
+      neighborLon = ensure_valid_lon(neighborLon);
+      neighborLat = ensure_valid_lat(neighborLat);
+      return encode2(neighborLat, neighborLon, hashString.length);
+    }, "neighbor");
+    var neighbor_int = /* @__PURE__ */ __name(function(hash_int, direction, bitDepth) {
+      bitDepth = bitDepth || 52;
+      var lonlat = decode_int(hash_int, bitDepth);
+      var neighbor_lat = lonlat.latitude + direction[0] * lonlat.error.latitude * 2;
+      var neighbor_lon = lonlat.longitude + direction[1] * lonlat.error.longitude * 2;
+      neighbor_lon = ensure_valid_lon(neighbor_lon);
+      neighbor_lat = ensure_valid_lat(neighbor_lat);
+      return encode_int(neighbor_lat, neighbor_lon, bitDepth);
+    }, "neighbor_int");
+    var neighbors = /* @__PURE__ */ __name(function(hash_string) {
+      var hashstringLength = hash_string.length;
+      var lonlat = decode2(hash_string);
+      var lat = lonlat.latitude;
+      var lon = lonlat.longitude;
+      var latErr = lonlat.error.latitude * 2;
+      var lonErr = lonlat.error.longitude * 2;
+      var neighbor_lat, neighbor_lon;
+      var neighborHashList = [
+        encodeNeighbor(1, 0),
+        encodeNeighbor(1, 1),
+        encodeNeighbor(0, 1),
+        encodeNeighbor(-1, 1),
+        encodeNeighbor(-1, 0),
+        encodeNeighbor(-1, -1),
+        encodeNeighbor(0, -1),
+        encodeNeighbor(1, -1)
+      ];
+      function encodeNeighbor(neighborLatDir, neighborLonDir) {
+        neighbor_lat = lat + neighborLatDir * latErr;
+        neighbor_lon = lon + neighborLonDir * lonErr;
+        neighbor_lon = ensure_valid_lon(neighbor_lon);
+        neighbor_lat = ensure_valid_lat(neighbor_lat);
+        return encode2(neighbor_lat, neighbor_lon, hashstringLength);
+      }
+      __name(encodeNeighbor, "encodeNeighbor");
+      return neighborHashList;
+    }, "neighbors");
+    var neighbors_int = /* @__PURE__ */ __name(function(hash_int, bitDepth) {
+      bitDepth = bitDepth || 52;
+      var lonlat = decode_int(hash_int, bitDepth);
+      var lat = lonlat.latitude;
+      var lon = lonlat.longitude;
+      var latErr = lonlat.error.latitude * 2;
+      var lonErr = lonlat.error.longitude * 2;
+      var neighbor_lat, neighbor_lon;
+      var neighborHashIntList = [
+        encodeNeighbor_int(1, 0),
+        encodeNeighbor_int(1, 1),
+        encodeNeighbor_int(0, 1),
+        encodeNeighbor_int(-1, 1),
+        encodeNeighbor_int(-1, 0),
+        encodeNeighbor_int(-1, -1),
+        encodeNeighbor_int(0, -1),
+        encodeNeighbor_int(1, -1)
+      ];
+      function encodeNeighbor_int(neighborLatDir, neighborLonDir) {
+        neighbor_lat = lat + neighborLatDir * latErr;
+        neighbor_lon = lon + neighborLonDir * lonErr;
+        neighbor_lon = ensure_valid_lon(neighbor_lon);
+        neighbor_lat = ensure_valid_lat(neighbor_lat);
+        return encode_int(neighbor_lat, neighbor_lon, bitDepth);
+      }
+      __name(encodeNeighbor_int, "encodeNeighbor_int");
+      return neighborHashIntList;
+    }, "neighbors_int");
+    var bboxes = /* @__PURE__ */ __name(function(minLat, minLon, maxLat, maxLon, numberOfChars) {
+      numberOfChars = numberOfChars || 9;
+      var hashSouthWest = encode2(minLat, minLon, numberOfChars);
+      var hashNorthEast = encode2(maxLat, maxLon, numberOfChars);
+      var latLon = decode2(hashSouthWest);
+      var perLat = latLon.error.latitude * 2;
+      var perLon = latLon.error.longitude * 2;
+      var boxSouthWest = decode_bbox(hashSouthWest);
+      var boxNorthEast = decode_bbox(hashNorthEast);
+      var latStep = Math.round((boxNorthEast[0] - boxSouthWest[0]) / perLat);
+      var lonStep = Math.round((boxNorthEast[1] - boxSouthWest[1]) / perLon);
+      var hashList = [];
+      for (var lat = 0; lat <= latStep; lat++) {
+        for (var lon = 0; lon <= lonStep; lon++) {
+          hashList.push(neighbor(hashSouthWest, [lat, lon]));
+        }
+      }
+      return hashList;
+    }, "bboxes");
+    var bboxes_int = /* @__PURE__ */ __name(function(minLat, minLon, maxLat, maxLon, bitDepth) {
+      bitDepth = bitDepth || 52;
+      var hashSouthWest = encode_int(minLat, minLon, bitDepth);
+      var hashNorthEast = encode_int(maxLat, maxLon, bitDepth);
+      var latlon = decode_int(hashSouthWest, bitDepth);
+      var perLat = latlon.error.latitude * 2;
+      var perLon = latlon.error.longitude * 2;
+      var boxSouthWest = decode_bbox_int(hashSouthWest, bitDepth);
+      var boxNorthEast = decode_bbox_int(hashNorthEast, bitDepth);
+      var latStep = Math.round((boxNorthEast[0] - boxSouthWest[0]) / perLat);
+      var lonStep = Math.round((boxNorthEast[1] - boxSouthWest[1]) / perLon);
+      var hashList = [];
+      for (var lat = 0; lat <= latStep; lat++) {
+        for (var lon = 0; lon <= lonStep; lon++) {
+          hashList.push(neighbor_int(hashSouthWest, [lat, lon], bitDepth));
+        }
+      }
+      return hashList;
+    }, "bboxes_int");
+    function ensure_valid_lon(lon) {
+      if (lon > MAX_LON)
+        return MIN_LON + lon % MAX_LON;
+      if (lon < MIN_LON)
+        return MAX_LON + lon % MAX_LON;
+      return lon;
+    }
+    __name(ensure_valid_lon, "ensure_valid_lon");
+    function ensure_valid_lat(lat) {
+      if (lat > MAX_LAT)
+        return MAX_LAT;
+      if (lat < MIN_LAT)
+        return MIN_LAT;
+      return lat;
+    }
+    __name(ensure_valid_lat, "ensure_valid_lat");
+    var geohash = {
+      "ENCODE_AUTO": ENCODE_AUTO,
+      "encode": encode2,
+      "encode_uint64": encode_int,
+      // keeping for backwards compatibility, will deprecate
+      "encode_int": encode_int,
+      "decode": decode2,
+      "decode_int": decode_int,
+      "decode_uint64": decode_int,
+      // keeping for backwards compatibility, will deprecate
+      "decode_bbox": decode_bbox,
+      "decode_bbox_uint64": decode_bbox_int,
+      // keeping for backwards compatibility, will deprecate
+      "decode_bbox_int": decode_bbox_int,
+      "neighbor": neighbor,
+      "neighbor_int": neighbor_int,
+      "neighbors": neighbors,
+      "neighbors_int": neighbors_int,
+      "bboxes": bboxes,
+      "bboxes_int": bboxes_int
+    };
+    module2.exports = geohash;
+  }
+});
+
 // src/server/handler.ts
 var handler_exports = {};
 __export(handler_exports, {
@@ -28890,35 +29204,31 @@ var LAMBDA_MAX_PAYLOAD_SIZE_ASYNC = 256 * 1024;
 var LAMBDA_MAX_RESPONSE_SIZE = 6 * 1024 * 1024;
 var LAMBDA_MAX_ENV_VARS_SIZE = 4 * 1024;
 
-// src/server/operations/deleteMany.ts
-var import_lib_dynamodb2 = __toESM(require_dist_cjs66(), 1);
+// src/shared/geohash/types.ts
+var DEFAULT_GEOHASH_CONFIG = {
+  shadowPrecision: 8,
+  // ±19m（建物レベル）
+  searchPrecision: 6,
+  // ±610m（近隣レベル）
+  minPrecision: 4,
+  // ±20km（大都市レベル）
+  maxIterations: 5,
+  candidateMultiplier: 3
+};
 
-// src/server/shadow/typeInference.ts
-function inferFieldType(value) {
-  if (value === null || value === void 0) {
-    return null;
-  }
-  if (typeof value === "string") {
-    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(value)) {
-      return "datetime";
-    }
-    return "string";
-  }
-  if (typeof value === "number") {
-    return "number";
-  }
-  if (typeof value === "boolean") {
-    return "boolean";
-  }
-  if (Array.isArray(value)) {
-    return "array";
-  }
-  if (typeof value === "object") {
-    return "object";
-  }
-  return null;
+// src/shared/geohash/utils.ts
+var import_ngeohash = __toESM(require_main(), 1);
+function isGeoCoordinates(value) {
+  return typeof value === "object" && value !== null && "latitude" in value && "longitude" in value && typeof value.latitude === "number" && typeof value.longitude === "number" && value.latitude >= -90 && value.latitude <= 90 && value.longitude >= -180 && value.longitude <= 180;
 }
-__name(inferFieldType, "inferFieldType");
+__name(isGeoCoordinates, "isGeoCoordinates");
+function encodeGeoHash(latitude, longitude, precision = 6) {
+  return import_ngeohash.default.encode(latitude, longitude, precision);
+}
+__name(encodeGeoHash, "encodeGeoHash");
+
+// src/server/operations/deleteMany.ts
+var import_lib_dynamodb2 = __toESM(require_dist_cjs66(), 1);
 
 // src/shared/constants/formatting.ts
 var NUMBER_FORMAT = {
@@ -28973,6 +29283,33 @@ function isDiffEmpty(diff) {
 }
 __name(isDiffEmpty, "isDiffEmpty");
 
+// src/server/shadow/typeInference.ts
+function inferFieldType(value) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (typeof value === "string") {
+    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(value)) {
+      return "datetime";
+    }
+    return "string";
+  }
+  if (typeof value === "number") {
+    return "number";
+  }
+  if (typeof value === "boolean") {
+    return "boolean";
+  }
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  if (typeof value === "object") {
+    return "object";
+  }
+  return null;
+}
+__name(inferFieldType, "inferFieldType");
+
 // src/server/shadow/generator.ts
 function normalizeJson(value) {
   if (value === null || value === void 0) return value;
@@ -29074,6 +29411,19 @@ function generateShadowRecords(record, resourceName, config) {
     if (value === null || value === void 0) {
       continue;
     }
+    if (isGeoCoordinates(value)) {
+      const geohash = encodeGeoHash(
+        value.latitude,
+        value.longitude,
+        DEFAULT_GEOHASH_CONFIG.shadowPrecision
+      );
+      const sk2 = `${fieldName}#${geohash}#id#${record.id}`;
+      shadows.push({
+        PK: resourceName,
+        SK: sk2
+      });
+      continue;
+    }
     const type = inferFieldType(value);
     if (!type) {
       continue;