useCollectionScope

Encapsulates the add/remove side effects of a Cesium-related Collection within the component lifecycle: when the component unmounts, every instance added through add is removed automatically. Mutating a collection (e.g. viewer.entities) by hand often leaves instances behind, causing duplicated entities and resource leaks; unlike the other scoped hooks, this one needs you to describe the real add/remove behavior via addEffect / removeEffect — useEntityScope, usePrimitiveScope and the other scoped hooks are built on top of it, and @vesium/plot consumes them indirectly.

WARNING

This is a basic function that is intended to be called by other lower-level functions (e.g., useEntityScope). It is recommended to use higher-level hooks unless you need to implement custom collection management logic.

Usage

import { Entity } from 'cesium';
import { useCollectionScope, useViewer } from 'vesium';

const viewer = useViewer();
const { add } = useCollectionScope({
  addEffect: e => viewer.value!.entities.add(e),
  removeEffect: e => viewer.value!.entities.remove(e),
});
add(new Entity({ id: 'demo' }));

Return Value

• add(instance, ...args) - Calls addEffect to add the instance and records it in scope; with a Promise, the instance enters the collection after it resolves
• remove(instance, ...args) - Removes the instance from scope first, then calls removeEffect for the real removal
• scope - A readonly reactive Set of added instances; use scope.has(instance) to check whether an instance is still in scope
• removeWhere(predicate, ...args) - Removes every instance matching the predicate
• removeScope(...args) - Clears all instances in the scope (called automatically on unmount)

Notes

• On unmount removeScope(removeScopeArgs ?? []) runs automatically; instances already removed via remove are no longer in scope and won't be processed again.
• With a Promise passed to add, the instance enters the collection and scope only after the Promise resolves.

Type Definitions

import type { ShallowReactive } from 'vue';
export type EffcetRemovePredicate<T> = (instance: T) => boolean;
export interface UseCollectionScopeOptions<T, AddArgs extends any[] = any[], RemoveArgs extends any[] = [], RemoveReturn = any> {
    /**
     * add SideEffect function.  e.g. `entities.add`
     */
    addEffect: (instance: T | Promise<T>, ...args: AddArgs) => T | Promise<T>;
    /**
     * Clean SideEffect function.  eg.`entities.remove`
     */
    removeEffect: (instance: T, ...args: RemoveArgs) => RemoveReturn;
    /**
     * The parameters to pass for `removeScope` triggered when the component is unmounted
     */
    removeScopeArgs?: RemoveArgs;
}
export interface UseCollectionScopeReturn<T, AddArgs extends any[], RemoveArgs extends any[], RemoveReturn = any> {
    /**
     * A `Set` for storing SideEffect instance,
     * which is encapsulated using `ShallowReactive` to provide Vue's reactive functionality
     */
    scope: Readonly<ShallowReactive<Set<T>>>;
    /**
     * Add SideEffect instance
     */
    add: <R extends T | Promise<T>>(instance: R, ...args: AddArgs) => R extends Promise<infer U> ? Promise<U> : T;
    /**
     * Remove specified SideEffect instance
     */
    remove: (instance: T, ...args: RemoveArgs) => RemoveReturn;
    /**
     * Remove all SideEffect instance that meets the specified criteria
     */
    removeWhere: (predicate: EffcetRemovePredicate<T>, ...args: RemoveArgs) => void;
    /**
     * Remove all SideEffect instance within current scope
     */
    removeScope: (...args: RemoveArgs) => void;
}
/**
 * Scope the SideEffects of Cesium-related `Collection` and automatically remove them when unmounted.
 * - note: This is a basic function that is intended to be called by other lower-level function
 * @returns Contains side effect addition and removal functions
 */
export declare function useCollectionScope<T, AddArgs extends any[] = any[], RemoveArgs extends any[] = [], RemoveReturn = any>(options: UseCollectionScopeOptions<T, AddArgs, RemoveArgs, RemoveReturn>): UseCollectionScopeReturn<T, AddArgs, RemoveArgs, RemoveReturn>;