feat: useSeek composable

src/composables/index.ts

@@ -6,3 +6,4 @@ export * from './useTexture'
 export * from './useTres'
 export * from './useRaycaster'
 export * from './useLogger'
+export * from './useSeek'

src/composables/useSeek/index.ts

@@ -0,0 +1,62 @@
+import { useLogger } from '/@/composables'
+
+/**
+ * Seek composable return type
+ *
+ * @export
+ * @interface UseSeekReturn
+ */
+export interface UseSeekReturn {
+  seek: (parent: THREE.Scene | THREE.Object3D, property: string, value: string) => THREE.Object3D | null
+  seekByName: (parent: THREE.Scene | THREE.Object3D, value: string) => THREE.Object3D | null
+}
+
+/**
+ * Composable that provides utilities to easily traverse and navigate through complex scenes and object children graphs
+ *
+ * @export
+ * @return {*}  {UseSeekReturn}
+ */
+export function useSeek(): UseSeekReturn {
+  const { logWarning } = useLogger()
+
+  /**
+   * Returns a child object of the parent given a property
+   *
+   * @param {(THREE.Scene | THREE.Object3D)} parent
+   * @param {string} property
+   * @param {string} value
+   * @return {*}  {(THREE.Object3D | null)}
+   */
+  function seek(parent: THREE.Scene | THREE.Object3D, property: string, value: string): THREE.Object3D | null {
+    let foundChild: THREE.Object3D | null = null
+
+    parent.traverse(child => {
+      if ((child as any)[property] === value) {
+        foundChild = child
+      }
+    })
+
+    if (!foundChild) {
+      logWarning(`Child with ${property} '${value}' not found.`)
+    }
+
+    return foundChild
+  }
+
+  /**
+   * Returns a child object of the parent given a child.name
+   *
+   * @param {(THREE.Scene | THREE.Object3D)} parent
+   * @param {string} value
+   * @return {*}  {(THREE.Object3D | null)}
+   */
+  function seekByName(parent: THREE.Scene | THREE.Object3D, value: string): THREE.Object3D | null {
+    return seek(parent, 'name', value)
+  }
+
+  return {
+    seek,
+    seekByName,
+  }
+}

src/composables/useSeek/useSeek.test.ts

@@ -0,0 +1,31 @@
+import { Object3D } from 'three'
+import { useSeek } from '.'
+import { withSetup } from '/@/utils/test-utils'
+
+const [composable, app] = withSetup(() => useSeek())
+
+describe('useRaycaster', () => {
+  afterEach(() => {
+    app.unmount()
+  })
+  test('should find a child by a property', () => {
+    const { seek } = composable
+    const parent = new Object3D()
+    const child = new Object3D()
+    ;(child as any).customProperty = 'customValue'
+    parent.add(child)
+
+    const result = seek(parent, 'customProperty', 'customValue')
+    expect(result).toBe(child)
+  })
+  test('should find a child by a property', () => {
+    const { seekByName } = composable
+    const parent = new Object3D()
+    const child = new Object3D()
+    child.name = 'testChild'
+    parent.add(child)
+
+    const result = seekByName(parent, 'testChild')
+    expect(result).toBe(child)
+  })
+})