@juun-roh/cesium-utils 0.0.3 → 0.0.5

package/dist/collection/index.d.ts

@@ -0,0 +1,363 @@
+import { BillboardCollection, DataSourceCollection, EntityCollection, ImageryLayerCollection, LabelCollection, PointPrimitiveCollection, PolylineCollection, PrimitiveCollection, Billboard, DataSource, Entity, ImageryLayer, Label, PointPrimitive, Polyline, Primitive, Cesium3DTileset, GroundPrimitive } from 'cesium';
+
+type CesiumCollection = BillboardCollection | DataSourceCollection | EntityCollection | ImageryLayerCollection | LabelCollection | PointPrimitiveCollection | PolylineCollection | PrimitiveCollection;
+type Primitives = Primitive | Cesium3DTileset | GroundPrimitive;
+type CesiumCollectionItem = Billboard | DataSource | Entity | ImageryLayer | Label | PointPrimitive | Polyline | Primitives;
+type Tag = string | number;
+interface WithTag {
+    [key: symbol]: Tag;
+}
+/**
+ * Collection event types
+ */
+type CollectionEventType = 'add' | 'remove' | 'update' | 'clear';
+/**
+ * Event handler function type
+ */
+type EventHandler<I> = (event: {
+    type: CollectionEventType;
+    items?: I[];
+    tag?: Tag;
+}) => void;
+
+/**
+ * @class
+ * Abstract class that enhances Cesium collection objects with tagging functionality.
+ * This class provides a consistent API for working with different types of Cesium collections
+ * and allows grouping and manipulating collection items by custom tags.
+ *
+ * @template C - The type of Cesium collection (e.g., EntityCollection, PrimitiveCollection)
+ * @template I - The type of items in the collection (e.g., Entity, Primitive)
+ *
+ * @example
+ * // Creating a specialized collection for entities
+ * class MyEntities extends Collection<EntityCollection, Entity> {
+ *   constructor(viewer) {
+ *     super({ collection: viewer.entities, tag: 'myEntities' });
+ *   }
+ *
+ *   get values() {
+ *     return this.collection.values;
+ *   }
+ * }
+ *
+ * const entities = new MyEntities(viewer);
+ * entities.add(new Entity({ ... }), 'buildings');
+ * entities.add(new Entity({ ... }), 'roads');
+ *
+ * // Later, show only buildings
+ * entities.show('buildings');
+ * entities.hide('roads');
+ */
+declare class Collection<C extends CesiumCollection, I extends CesiumCollectionItem> {
+    /**
+     * Symbol used as a property key to store tags on collection items.
+     * Using a Symbol ensures no property naming conflicts with the item's own properties.
+     * @readonly
+     */
+    static readonly symbol: unique symbol;
+    /**
+     * Default tag used when adding items without specifying a tag.
+     * @protected
+     */
+    protected tag: Tag;
+    /**
+     * The underlying Cesium collection being wrapped.
+     * @protected
+     */
+    protected collection: C;
+    /**
+     * Cache for values array to improve performance
+     * @private
+     */
+    private _valuesCache;
+    /**
+     * Tag to items map for faster lookups
+     * @private
+     */
+    private _tagMap;
+    /**
+     * Event listeners
+     * @private
+     */
+    private _eventListeners;
+    /**
+     * Creates a new Collection instance.
+     *
+     * @param options - Configuration options
+     * @param options.collection - The Cesium collection to wrap
+     * @param options.tag - The default tag to use for items (defaults to 'default')
+     */
+    constructor({ collection, tag }: {
+        collection: C;
+        tag?: Tag;
+    });
+    /**
+     * Emits an event to all registered listeners.
+     *
+     * @private
+     * @param type - The event type
+     * @param data - Additional event data
+     */
+    private _emit;
+    /**
+     * Adds an item to the internal tag map for quick lookups.
+     *
+     * @private
+     * @param item - The item to add
+     * @param tag - The tag to associate with the item
+     */
+    private _addToTagMap;
+    /**
+     * Removes an item from the internal tag map.
+     *
+     * @private
+     * @param item - The item to remove
+     */
+    private _removeFromTagMap;
+    /**
+     * Invalidates the values cache when collection changes.
+     *
+     * @private
+     */
+    private _invalidateCache;
+    /**
+     * Registers an event listener for collection events.
+     *
+     * @param type - The event type to listen for
+     * @param handler - The callback function
+     * @returns The collection instance for method chaining
+     */
+    addEventListener(type: CollectionEventType, handler: EventHandler<I>): this;
+    /**
+     * Removes an event listener.
+     *
+     * @param type - The event type
+     * @param handler - The callback function to remove
+     * @returns The collection instance for method chaining
+     */
+    removeEventListener(type: CollectionEventType, handler: EventHandler<I>): this;
+    /**
+     * Adds a single item with a tag to the collection.
+     *
+     * @param item - The item to add to the collection
+     * @param tag - Tag to associate with this item (defaults to the collection's default tag)
+     * @param index - The index to add the item at (if supported by the collection)
+     * @returns The added item for chaining
+     *
+     * @example
+     * const entity = collection.add(new Entity({ ... }), 'landmarks');
+     */
+    add(item: I, tag?: Tag, index?: number): I;
+    /**
+     * Adds multiple items with the same tag to the collection.
+     *
+     * @param items - The array of items to add to the collection
+     * @param tag - Tag to associate with this item (defaults to the collection's default tag)
+     * @returns The array of added items
+     *
+     * @example
+     * // Add multiple entities with the same tag
+     * const entities = [new Entity({ ... }), new Entity({ ... })];
+     * const addedEntities = collection.add(entities, 'buildings');
+     */
+    add(items: I[], tag?: Tag): I[];
+    /**
+     * Returns true if the provided item is in this collection, false otherwise.
+     *
+     * @param item - The item to check for
+     * @returns True if the item is in the collection, false otherwise
+     */
+    contains(item: I): boolean;
+    /**
+     * Removes an item from the collection.
+     *
+     * @param item - The item to remove
+     * @returns True if the item was removed, false if it wasn't found
+     */
+    remove(item: I): boolean;
+    /**
+     * Removes all items from the collection.
+     */
+    removeAll(): void;
+    /**
+     * Gets all item instances in the collection.
+     * This array should not be modified directly.
+     *
+     * @returns An array of all items in the collection
+     */
+    get values(): I[];
+    /**
+     * Gets the number of items in the collection.
+     *
+     * @returns The item count
+     */
+    get length(): number;
+    /**
+     * Gets all items with the specified tag from the collection.
+     * Uses an optimized internal map for faster lookups.
+     *
+     * @param tag - The tag to filter by
+     * @returns An array of items with the specified tag, or an empty array if none found
+     *
+     * @example
+     * // Get all buildings
+     * const buildings = collection.getByTag('buildings');
+     */
+    getByTag(tag: Tag): I[];
+    /**
+     * Gets the first item matching the tag. More efficient than getByTag when
+     * you only need one item, especially for large collections.
+     *
+     * @param tag - The tag to search for
+     * @returns The first matching item or undefined if none found
+     *
+     * @example
+     * // Get the first building
+     * const firstBuilding = collection.getFirstByTag('buildings');
+     */
+    getFirstByTag(tag: Tag): I | undefined;
+    /**
+     * Gets all unique tags currently in use in the collection.
+     *
+     * @returns An array of all unique tags
+     *
+     * @example
+     * // Get all tags
+     * const tags = collection.getTags();
+     * console.log(`Collection has these tags: ${tags.join(', ')}`);
+     */
+    getTags(): Tag[];
+    /**
+     * Checks if the collection has any items with the specified tag.
+     *
+     * @param tag - The tag to check for
+     * @returns True if items with the tag exist, false otherwise
+     *
+     * @example
+     * if (collection.hasTag('temporary')) {
+     *   console.log('Temporary items exist');
+     * }
+     */
+    hasTag(tag: Tag): boolean;
+    /**
+     * Updates the tag for all items with the specified tag.
+     *
+     * @param oldTag - The tag to replace
+     * @param newTag - The new tag to assign
+     * @returns The number of items updated
+     *
+     * @example
+     * // Rename a tag
+     * const count = collection.updateTag('temp', 'temporary');
+     * console.log(`Updated ${count} items`);
+     */
+    updateTag(oldTag: Tag, newTag: Tag): number;
+    /**
+     * Removes all items with the specified tag from the collection.
+     *
+     * @param tag - The tag identifying which items to remove
+     * @returns The number of items removed
+     *
+     * @example
+     * // Remove all temporary markers
+     * const count = collection.removeByTag('temporary');
+     * console.log(`Removed ${count} items`);
+     */
+    removeByTag(tag: Tag): number;
+    /**
+     * Removes all items with the array of tags from the collection.
+     *
+     * @param tag - The tags identifying which items to remove
+     * @returns The number of items removed
+     *
+     * @example
+     * // Remove all items containing tags
+     * const count = collection.removeByTag('temporary', 'default', 'tag');
+     * console.log(`Removed ${count} items`);
+     */
+    removeByTag(tag: Tag[]): number;
+    /**
+     * Makes all items with the specified tag visible.
+     * Only affects items that have a 'show' property.
+     *
+     * @param tag - The tag identifying which items to show
+     * @returns The number of items affected
+     *
+     * @example
+     * // Show all buildings
+     * collection.show('buildings');
+     */
+    show(tag: Tag): number;
+    /**
+     * Hides all items with the specified tag.
+     * Only affects items that have a 'show' property.
+     *
+     * @param tag - The tag identifying which items to hide
+     * @returns The number of items affected
+     *
+     * @example
+     * // Hide all buildings
+     * collection.hide('buildings');
+     */
+    hide(tag: Tag): number;
+    /**
+     * Toggles visibility of all items with the specified tag.
+     * Only affects items that have a 'show' property.
+     *
+     * @param tag - The tag identifying which items to toggle
+     * @returns The number of items affected
+     *
+     * @example
+     * // Toggle visibility of all buildings
+     * collection.toggle('buildings');
+     */
+    toggle(tag: Tag): number;
+    /**
+     * Sets a property value on all items with the specified tag.
+     *
+     * @param tag - The tag identifying which items to update
+     * @param property - The property name to set
+     * @param value - The value to set
+     * @returns The number of items updated
+     *
+     * @example
+     * // Change color of all buildings to red
+     * collection.setProperty('buildings', 'color', Color.RED);
+     */
+    setProperty<K extends string, V>(tag: Tag, property: K, value: V): number;
+    /**
+     * Filters items in the collection based on a predicate function.
+     * Optionally only filters items with a specific tag.
+     *
+     * @param predicate - Function that tests each item
+     * @param tag - Optional tag to filter by before applying the predicate
+     * @returns Array of items that pass the test
+     *
+     * @example
+     * // Get all buildings taller than 100 meters
+     * const tallBuildings = collection.filter(
+     *   entity => entity.properties?.height?.getValue() > 100,
+     *   'buildings'
+     * );
+     */
+    filter(predicate: (item: I) => boolean, tag?: Tag): I[];
+    /**
+     * Executes a callback function for each item in the collection.
+     * Optionally filters items by tag before execution.
+     *
+     * @param callback - Function to execute for each item
+     * @param tag - Optional tag to filter items (if not provided, processes all items)
+     *
+     * @example
+     * // Highlight all buildings
+     * collection.forEach((entity) => {
+     *   if (entity.polygon) {
+     *     entity.polygon.material = new ColorMaterialProperty(Color.YELLOW);
+     *   }
+     * }, 'buildings');
+     */
+    forEach(callback: (item: I, index: number) => void, tag?: Tag): void;
+}
+
+export { type CesiumCollection, type CesiumCollectionItem, Collection, type CollectionEventType, type EventHandler, type Primitives, type Tag, type WithTag };

package/dist/collection/index.js

@@ -0,0 +1 @@
+import{a as o}from"../chunk-CNYZN4AC.js";export{o as Collection};