@mint-ui/map 1.2.0-test.34 → 1.2.0-test.36

package/dist/components/mint-map/core/advanced/shared/performance.d.ts

@@ -1,79 +1,34 @@
 /**
- * 공간 인덱스 그리드 셀 크기 (px)
+ * 공간 인덱스 그리드 셀 크기 (픽셀 단위)
  *
- * 최적값 계산:
- * - 목표: 클릭 시 셀당 10~30개 항목만 체크 (빠른 Hit Test)
- * - 화면 크기: 1920×1080 기준
- * - 30,000개 항목 → 50px 셀 크기 = 약 800개 셀 = 셀당 ~37개
- *
- * 성능 비교 (30,000개 기준):
- * - 200px: 셀당 ~577개 → Hit Test O(577) ❌ 느림
- * - 50px:  셀당 ~37개  → Hit Test O(37)  ✅ 15배 빠름!
- *
- * 트레이드오프:
- * - 작을수록: Hit Test 빠름, 메모리 사용량 증가
- * - 클수록: 메모리 효율적, Hit Test 느림
+ * @default 50
  */
 export declare const SPATIAL_GRID_CELL_SIZE = 50;
 /**
- * 뷰포트 컬링 여유 공간 (px)
+ * 뷰포트 컬링 여유 공간 (픽셀 단위)
  *
- * 화면 밖 100px까지 렌더링하여 스크롤 시 부드러운 전환
- * 30,000개 중 실제 렌더링: 화면에 보이는 1,000~3,000개만
+ * @default 100
  */
 export declare const DEFAULT_CULLING_MARGIN = 100;
 /**
  * LRU 캐시 최대 항목 수
  *
- * 좌표 변환 결과 캐싱 (positionToOffset 연산 비용 절약)
- *
- * 최적값 계산:
- * - 전체 항목: 30,000개
- * - 캐시 크기: 30,000개 → 100% 히트율 (메모리: ~2.4MB)
- *
- * 메모리 사용량 (항목당 ~80 bytes):
- * - 10,000개: ~800KB  → 캐시 히트율 33% ❌
- * - 30,000개: ~2.4MB  → 캐시 히트율 100% ✅
- *
- * zoom/pan 시 어차피 clear() 호출되므로 메모리 누적 없음
+ * @default 30000
  */
 export declare const DEFAULT_MAX_CACHE_SIZE = 30000;
 /**
- * LRU (Least Recently Used) Cache
- * 메모리 제한을 위한 캐시 구현 (최적화 버전)
+ * LRU Cache (Least Recently Used)
+ *
+ * 좌표 변환 결과를 캐싱하기 위한 캐시 구현
  *
- * 개선 사항:
- * 1. get() 성능 향상: 접근 빈도 추적 없이 단순 조회만 수행 (delete+set 제거)
- * 2. set() 버그 수정: 기존 키 업데이트 시 maxSize 체크 로직 개선
- * 3. 메모리 효율: 단순 FIFO 캐시로 동작하여 오버헤드 최소화
+ * @template K 캐시 키 타입
+ * @template V 캐시 값 타입
  */
 export declare class LRUCache<K, V> {
     private cache;
     private maxSize;
     constructor(maxSize?: number);
-    /**
-     * 캐시에서 값 조회
-     *
-     * 최적화: delete+set 제거
-     * - 이전: 매번 delete+set으로 LRU 갱신 (해시 재계산 비용)
-     * - 현재: 단순 조회만 수행 (O(1) 해시 조회)
-     *
-     * 트레이드오프:
-     * - 장점: 읽기 성능 대폭 향상 (10,000번 get → 이전보다 2배 빠름)
-     * - 단점: 접근 빈도가 아닌 삽입 순서 기반 eviction (FIFO)
-     *
-     * WoongCanvasMarker 사용 사례에 최적:
-     * - 좌표 변환 결과는 zoom/pan 시 어차피 전체 초기화
-     * - 접근 빈도 추적보다 빠른 조회가 더 중요
-     */
     get(key: K): V | undefined;
-    /**
-     * 캐시에 값 저장 (버그 수정 + 최적화)
-     *
-     * 수정 사항:
-     * 1. 기존 키 업데이트 시 크기 체크 누락 버그 수정
-     * 2. 로직 명확화: 기존 항목/신규 항목 분리 처리
-     */
     set(key: K, value: V): void;
     clear(): void;
     size(): number;
@@ -81,78 +36,25 @@ export declare class LRUCache<K, V> {
 }
 /**
  * Spatial Hash Grid (공간 해시 그리드)
- * 공간 인덱싱을 위한 그리드 기반 자료구조 (개선 버전)
  *
- * 개선 사항:
- * 1. 중복 삽입 방지: 같은 항목을 여러 번 insert 해도 안전
- * 2. 메모리 누수 방지: 기존 항목 자동 제거
- * 3. 성능 최적화: 불필요한 배열 생성 최소화
+ * 빠른 Hit Test를 위한 그리드 기반 공간 인덱싱 자료구조
  *
- * 사용 사례:
- * - 빠른 Hit Test (마우스 클릭 시 어떤 마커/폴리곤인지 찾기)
- * - 30,000개 항목 → 클릭 위치 주변 ~10개만 체크 (3,000배 빠름)
+ * @template T 인덱싱할 항목 타입
  */
 export declare class SpatialHashGrid<T> {
     private cellSize;
     private grid;
     private itemToCells;
     constructor(cellSize?: number);
-    /**
-     * 셀 키 생성 (x, y 좌표 → 그리드 셀 ID)
-     */
     private getCellKey;
-    /**
-     * 바운딩 박스가 걸치는 모든 셀 키 배열 반환
-     */
     private getCellsForBounds;
-    /**
-     * 항목 추가 (바운딩 박스 기반)
-     *
-     * 개선 사항:
-     * - 중복 삽입 방지: 기존 항목이 있으면 먼저 제거 후 재삽입
-     * - 메모리 누수 방지: 이전 셀 참조 완전 제거
-     */
     insert(item: T, minX: number, minY: number, maxX: number, maxY: number): void;
-    /**
-     * 항목 제거
-     *
-     * 추가된 메서드: 메모리 누수 방지 및 업데이트 지원
-     */
     remove(item: T): void;
-    /**
-     * 항목 위치 업데이트
-     *
-     * 추가된 메서드: remove + insert의 편의 함수
-     */
     update(item: T, minX: number, minY: number, maxX: number, maxY: number): void;
-    /**
-     * 점 주변의 항목 조회 (1개 셀만)
-     *
-     * 성능: O(해당 셀의 항목 수) - 보통 ~10개
-     */
     queryPoint(x: number, y: number): T[];
-    /**
-     * 영역 내 항목 조회
-     *
-     * 성능: O(셀 개수 × 셀당 평균 항목 수)
-     * Set으로 중복 제거 보장
-     */
     queryBounds(minX: number, minY: number, maxX: number, maxY: number): T[];
-    /**
-     * 항목 존재 여부 확인
-     *
-     * 추가된 메서드: 빠른 존재 여부 체크
-     */
     has(item: T): boolean;
-    /**
-     * 전체 초기화
-     */
     clear(): void;
-    /**
-     * 통계 정보
-     *
-     * 개선: totalItems는 실제 고유 항목 수를 정확히 반환
-     */
     stats(): {
         totalCells: number;
         totalItems: number;

package/dist/components/mint-map/core/advanced/shared/performance.js

@@ -2,60 +2,33 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-// ============================================================================
-// 성능 최적화 상수 (30,000개 마커/폴리곤 기준 최적화)
-// ============================================================================
-
 /**
- * 공간 인덱스 그리드 셀 크기 (px)
- *
- * 최적값 계산:
- * - 목표: 클릭 시 셀당 10~30개 항목만 체크 (빠른 Hit Test)
- * - 화면 크기: 1920×1080 기준
- * - 30,000개 항목 → 50px 셀 크기 = 약 800개 셀 = 셀당 ~37개
- *
- * 성능 비교 (30,000개 기준):
- * - 200px: 셀당 ~577개 → Hit Test O(577) ❌ 느림
- * - 50px:  셀당 ~37개  → Hit Test O(37)  ✅ 15배 빠름!
+ * 공간 인덱스 그리드 셀 크기 (픽셀 단위)
  *
- * 트레이드오프:
- * - 작을수록: Hit Test 빠름, 메모리 사용량 증가
- * - 클수록: 메모리 효율적, Hit Test 느림
+ * @default 50
  */
 var SPATIAL_GRID_CELL_SIZE = 50;
 /**
- * 뷰포트 컬링 여유 공간 (px)
+ * 뷰포트 컬링 여유 공간 (픽셀 단위)
  *
- * 화면 밖 100px까지 렌더링하여 스크롤 시 부드러운 전환
- * 30,000개 중 실제 렌더링: 화면에 보이는 1,000~3,000개만
+ * @default 100
  */
 
 var DEFAULT_CULLING_MARGIN = 100;
 /**
  * LRU 캐시 최대 항목 수
  *
- * 좌표 변환 결과 캐싱 (positionToOffset 연산 비용 절약)
- *
- * 최적값 계산:
- * - 전체 항목: 30,000개
- * - 캐시 크기: 30,000개 → 100% 히트율 (메모리: ~2.4MB)
- *
- * 메모리 사용량 (항목당 ~80 bytes):
- * - 10,000개: ~800KB  → 캐시 히트율 33% ❌
- * - 30,000개: ~2.4MB  → 캐시 히트율 100% ✅
- *
- * zoom/pan 시 어차피 clear() 호출되므로 메모리 누적 없음
+ * @default 30000
  */
 
 var DEFAULT_MAX_CACHE_SIZE = 30000;
 /**
- * LRU (Least Recently Used) Cache
- * 메모리 제한을 위한 캐시 구현 (최적화 버전)
+ * LRU Cache (Least Recently Used)
+ *
+ * 좌표 변환 결과를 캐싱하기 위한 캐시 구현
  *
- * 개선 사항:
- * 1. get() 성능 향상: 접근 빈도 추적 없이 단순 조회만 수행 (delete+set 제거)
- * 2. set() 버그 수정: 기존 키 업데이트 시 maxSize 체크 로직 개선
- * 3. 메모리 효율: 단순 FIFO 캐시로 동작하여 오버헤드 최소화
+ * @template K 캐시 키 타입
+ * @template V 캐시 값 타입
  */
 
 var LRUCache =
@@ -68,64 +41,43 @@ function () {
 
     this.cache = new Map();
     this.maxSize = maxSize;
-  }
-  /**
-   * 캐시에서 값 조회
-   *
-   * 최적화: delete+set 제거
-   * - 이전: 매번 delete+set으로 LRU 갱신 (해시 재계산 비용)
-   * - 현재: 단순 조회만 수행 (O(1) 해시 조회)
-   *
-   * 트레이드오프:
-   * - 장점: 읽기 성능 대폭 향상 (10,000번 get → 이전보다 2배 빠름)
-   * - 단점: 접근 빈도가 아닌 삽입 순서 기반 eviction (FIFO)
-   *
-   * WoongCanvasMarker 사용 사례에 최적:
-   * - 좌표 변환 결과는 zoom/pan 시 어차피 전체 초기화
-   * - 접근 빈도 추적보다 빠른 조회가 더 중요
-   */
+  } // 캐시에서 값 조회
 
 
   LRUCache.prototype.get = function (key) {
     return this.cache.get(key);
-  };
-  /**
-   * 캐시에 값 저장 (버그 수정 + 최적화)
-   *
-   * 수정 사항:
-   * 1. 기존 키 업데이트 시 크기 체크 누락 버그 수정
-   * 2. 로직 명확화: 기존 항목/신규 항목 분리 처리
-   */
+  }; // 캐시에 값 저장 (FIFO eviction)
 
 
   LRUCache.prototype.set = function (key, value) {
     var exists = this.cache.has(key);
 
     if (exists) {
-      // 기존 항목 업데이트: 단순 덮어쓰기 (크기 변화 없음)
       this.cache.set(key, value);
-    } else {
-      // 신규 항목 추가: 크기 체크 필요
-      if (this.cache.size >= this.maxSize) {
-        // 가장 오래된 항목 제거 (Map의 첫 번째 항목)
-        var firstKey = this.cache.keys().next().value;
-
-        if (firstKey !== undefined) {
-          this.cache.delete(firstKey);
-        }
-      }
+      return;
+    }
 
-      this.cache.set(key, value);
+    if (this.cache.size >= this.maxSize) {
+      var firstKey = this.cache.keys().next().value;
+
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey);
+      }
     }
-  };
+
+    this.cache.set(key, value);
+  }; // 캐시 초기화
+
 
   LRUCache.prototype.clear = function () {
     this.cache.clear();
-  };
+  }; // 캐시 크기 반환
+
 
   LRUCache.prototype.size = function () {
     return this.cache.size;
-  };
+  }; // 키 존재 여부 확인
+
 
   LRUCache.prototype.has = function (key) {
     return this.cache.has(key);
@@ -135,16 +87,10 @@ function () {
 }();
 /**
  * Spatial Hash Grid (공간 해시 그리드)
- * 공간 인덱싱을 위한 그리드 기반 자료구조 (개선 버전)
  *
- * 개선 사항:
- * 1. 중복 삽입 방지: 같은 항목을 여러 번 insert 해도 안전
- * 2. 메모리 누수 방지: 기존 항목 자동 제거
- * 3. 성능 최적화: 불필요한 배열 생성 최소화
+ * 빠른 Hit Test를 위한 그리드 기반 공간 인덱싱 자료구조
  *
- * 사용 사례:
- * - 빠른 Hit Test (마우스 클릭 시 어떤 마커/폴리곤인지 찾기)
- * - 30,000개 항목 → 클릭 위치 주변 ~10개만 체크 (3,000배 빠름)
+ * @template T 인덱싱할 항목 타입
  */
 
 var SpatialHashGrid =
@@ -158,28 +104,24 @@ function () {
     this.cellSize = cellSize;
     this.grid = new Map();
     this.itemToCells = new Map();
-  }
-  /**
-   * 셀 키 생성 (x, y 좌표 → 그리드 셀 ID)
-   */
+  } // 셀 키 생성 (x, y 좌표 → 그리드 셀 ID)
 
 
   SpatialHashGrid.prototype.getCellKey = function (x, y) {
+    // 좌표를 셀 크기로 나눈 몫으로 셀 인덱스 계산
     var cellX = Math.floor(x / this.cellSize);
     var cellY = Math.floor(y / this.cellSize);
     return "".concat(cellX, ",").concat(cellY);
-  };
-  /**
-   * 바운딩 박스가 걸치는 모든 셀 키 배열 반환
-   */
+  }; // 바운딩 박스가 걸치는 모든 셀 키 배열 반환
 
 
   SpatialHashGrid.prototype.getCellsForBounds = function (minX, minY, maxX, maxY) {
-    var cells = [];
+    var cells = []; // 바운딩 박스가 걸치는 셀 범위 계산
+
     var startCellX = Math.floor(minX / this.cellSize);
     var startCellY = Math.floor(minY / this.cellSize);
     var endCellX = Math.floor(maxX / this.cellSize);
-    var endCellY = Math.floor(maxY / this.cellSize);
+    var endCellY = Math.floor(maxY / this.cellSize); // 바운딩 박스가 걸치는 모든 셀을 배열에 추가
 
     for (var x = startCellX; x <= endCellX; x++) {
       for (var y = startCellY; y <= endCellY; y++) {
@@ -188,22 +130,15 @@ function () {
     }
 
     return cells;
-  };
-  /**
-   * 항목 추가 (바운딩 박스 기반)
-   *
-   * 개선 사항:
-   * - 중복 삽입 방지: 기존 항목이 있으면 먼저 제거 후 재삽입
-   * - 메모리 누수 방지: 이전 셀 참조 완전 제거
-   */
+  }; // 항목 추가 (바운딩 박스 기반, 중복 삽입 방지)
 
 
   SpatialHashGrid.prototype.insert = function (item, minX, minY, maxX, maxY) {
-    // 1. 기존 항목 제거 (중복 방지)
-    this.remove(item); // 2. 새 위치에 삽입
+    // 기존 항목 제거 (중복 삽입 방지: 같은 항목을 여러 번 insert 해도 안전)
+    this.remove(item); // 바운딩 박스가 걸치는 모든 셀에 항목 등록
 
     var cells = this.getCellsForBounds(minX, minY, maxX, maxY);
-    this.itemToCells.set(item, cells);
+    this.itemToCells.set(item, cells); // 항목과 셀의 매핑 저장 (제거 시 필요)
 
     for (var _i = 0, cells_1 = cells; _i < cells_1.length; _i++) {
       var cell = cells_1[_i];
@@ -214,17 +149,12 @@ function () {
 
       this.grid.get(cell).push(item);
     }
-  };
-  /**
-   * 항목 제거
-   *
-   * 추가된 메서드: 메모리 누수 방지 및 업데이트 지원
-   */
+  }; // 항목 제거 (모든 셀에서 참조 제거)
 
 
   SpatialHashGrid.prototype.remove = function (item) {
     var prevCells = this.itemToCells.get(item);
-    if (!prevCells) return; // 각 셀에서 항목 제거
+    if (!prevCells) return; // 항목이 등록된 모든 셀에서 참조 제거 (메모리 누수 방지)
 
     for (var _i = 0, prevCells_1 = prevCells; _i < prevCells_1.length; _i++) {
       var cell = prevCells_1[_i];
@@ -235,51 +165,39 @@ function () {
 
         if (index !== -1) {
           cellItems.splice(index, 1);
-        } // 빈 셀 정리 (메모리 효율)
+        } // 빈 셀 정리 (메모리 효율: 사용하지 않는 셀 제거)
 
 
         if (cellItems.length === 0) {
           this.grid.delete(cell);
         }
       }
-    }
+    } // 항목과 셀의 매핑 제거
+
 
     this.itemToCells.delete(item);
-  };
-  /**
-   * 항목 위치 업데이트
-   *
-   * 추가된 메서드: remove + insert의 편의 함수
-   */
+  }; // 항목 위치 업데이트 (remove + insert)
 
 
   SpatialHashGrid.prototype.update = function (item, minX, minY, maxX, maxY) {
     this.insert(item, minX, minY, maxX, maxY);
-  };
-  /**
-   * 점 주변의 항목 조회 (1개 셀만)
-   *
-   * 성능: O(해당 셀의 항목 수) - 보통 ~10개
-   */
+  }; // 점 주변의 항목 조회 (Hit Test용)
 
 
   SpatialHashGrid.prototype.queryPoint = function (x, y) {
+    // 클릭 위치가 속한 셀의 모든 항목 조회 (O(1) 수준의 빠른 조회)
     var cellKey = this.getCellKey(x, y);
     var items = this.grid.get(cellKey); // 빈 배열 재사용 (메모리 할당 최소화)
 
     return items || [];
-  };
-  /**
-   * 영역 내 항목 조회
-   *
-   * 성능: O(셀 개수 × 셀당 평균 항목 수)
-   * Set으로 중복 제거 보장
-   */
+  }; // 영역 내 항목 조회 (Viewport Culling용)
 
 
   SpatialHashGrid.prototype.queryBounds = function (minX, minY, maxX, maxY) {
+    // 영역이 걸치는 모든 셀 찾기
     var cells = this.getCellsForBounds(minX, minY, maxX, maxY);
-    var results = new Set();
+    var results = new Set(); // 중복 제거를 위해 Set 사용
+    // 각 셀의 모든 항목을 결과에 추가
 
     for (var _i = 0, cells_2 = cells; _i < cells_2.length; _i++) {
       var cell = cells_2[_i];
@@ -288,37 +206,24 @@ function () {
       if (items) {
         for (var _a = 0, items_1 = items; _a < items_1.length; _a++) {
           var item = items_1[_a];
-          results.add(item);
+          results.add(item); // Set이므로 중복 자동 제거
         }
       }
     }
 
     return Array.from(results);
-  };
-  /**
-   * 항목 존재 여부 확인
-   *
-   * 추가된 메서드: 빠른 존재 여부 체크
-   */
+  }; // 항목 존재 여부 확인
 
 
   SpatialHashGrid.prototype.has = function (item) {
     return this.itemToCells.has(item);
-  };
-  /**
-   * 전체 초기화
-   */
+  }; // 전체 초기화
 
 
   SpatialHashGrid.prototype.clear = function () {
     this.grid.clear();
     this.itemToCells.clear();
-  };
-  /**
-   * 통계 정보
-   *
-   * 개선: totalItems는 실제 고유 항목 수를 정확히 반환
-   */
+  }; // 통계 정보 반환
 
 
   SpatialHashGrid.prototype.stats = function () {