Use scoping terminology in code to increase consistency

packages/arbor-react/tests/matchers/index.ts

@@ -1 +1 @@
-import "./toBeTrackedNode"
+import "./toBeScopedNode"

packages/arbor-react/tests/matchers/toBeTrackedNode.ts → packages/arbor-react/tests/matchers/toBeScopedNode.ts

@@ -2,13 +2,13 @@ import { expect } from "vitest"
 
 expect.extend({
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  toBeTrackedNode(received: any) {
-    const isTracked = received.$tracked === true
+  toBeScopedNode(received: any) {
+    const isScoped = received.$scoped === true
     return {
-      pass: isTracked,
+      pass: isScoped,
       actual: received,
       message: () =>
-        `Received value is ${isTracked ? "" : "not"} a tracked Arbor node`,
+        `Received value is ${isScoped ? "" : "not"} a tracked Arbor node`,
     }
   },
 })

packages/arbor-react/tests/useArbor.test.ts

@@ -16,10 +16,10 @@ describe("useArbor", () => {
 
     const { result } = renderHook(() => useArbor(store))
 
-    expect(result.current).toBeTrackedNode()
-    expect(result.current[0]).toBeTrackedNode()
-    expect(result.current[1]).toBeTrackedNode()
-    expect(result.current[2]).toBeTrackedNode()
+    expect(result.current).toBeScopedNode()
+    expect(result.current[0]).toBeScopedNode()
+    expect(result.current[1]).toBeScopedNode()
+    expect(result.current[2]).toBeScopedNode()
   })
 
   it("returns the current state of the store", () => {

packages/arbor-react/tests/vitest.d.ts

@@ -4,7 +4,7 @@ declare module "vitest" {
   interface Assertion<T> {
     toBeDetached: () => T
     toBeArborNode: () => T
-    toBeTrackedNode: () => T
+    toBeScopedNode: () => T
     toBeProxiedExactlyOnce: () => T
     toBeNodeOf: (expected: unknown) => T
     toHaveNodeFor: (expected: unknown) => T

packages/arbor-store/src/handlers/default.ts

@@ -40,6 +40,17 @@ export class DefaultHandler<T extends object = object>
     return true
   }
 
+  // TODO: expose seed value via a getter so user-defined data can have access to it.
+  // Example:
+  // get $seed() { return Seed.from(this) }
+  //
+  // User-defined classes could then:
+  //
+  // @proxiable
+  // class MyNode {
+  //   $seed: number
+  // }
+
   $getChildNode<C extends object>(link: Link): Node<C> {
     return this[link]
   }

packages/arbor-store/src/scoping/scope.ts

@@ -4,36 +4,36 @@ import { Seed } from "../path"
 import { ArborNode, Link, MutationEvent, Node } from "../types"
 import { isGetter, recursivelyUnwrap } from "../utilities"
 
-export type Tracked<T extends object = object> = T & {
-  $tracked?: boolean
+export type Scoped<T extends object = object> = T & {
+  $scoped?: boolean
 }
 
 export class Scope<T extends object> {
   private readonly bindings = new WeakMap<object, WeakMap<object, object>>()
-  private readonly cache = new WeakMap<ArborNode, Tracked>()
-  private tracking = new WeakMap<Seed, Set<string>>()
+  private readonly cache = new WeakMap<ArborNode, Scoped>()
+  private scopes = new WeakMap<Seed, Set<string>>()
 
-  getOrCache(node: ArborNode): Tracked {
+  getOrCache(node: ArborNode): Scoped {
     if (!this.cache.has(node)) {
       this.cache.set(node, this.wrap(node))
     }
 
     return this.cache.get(node)
   }
 
-  isTracking(node: ArborNode, prop: string) {
+  toBeScoping(node: ArborNode, prop: string) {
     const seed = Seed.from(node)
-    const tracked = this.tracking.get(seed)
+    const scoped = this.scopes.get(seed)
 
-    if (!tracked) {
+    if (!scoped) {
       return false
     }
 
-    return tracked.has(prop)
+    return scoped.has(prop)
   }
 
   reset() {
-    this.tracking = new WeakMap<Seed, Set<string>>()
+    this.scopes = new WeakMap<Seed, Set<string>>()
   }
 
   // NOTE: Something to consider in the future as new node handler types
@@ -84,28 +84,28 @@ export class Scope<T extends object> {
 
     const rootSeed = Seed.from(event.state)
     const targetSeed = event.mutationPath.seeds.at(-1)
-    const tracked = this.tracking.get(targetSeed || rootSeed)
+    const scoped = this.scopes.get(targetSeed || rootSeed)
 
-    // If the affected node is not being tracked, then no need to notify
+    // If the affected node is not being scoped, then no need to notify
     // any subscribers.
-    if (!tracked) {
+    if (!scoped) {
       return false
     }
 
     // Lastly, subscribers will be notified if any of the mutated props are
-    // being tracked.
-    return event.metadata.props.some((prop) => tracked.has(prop as string))
+    // being scoped.
+    return event.metadata.props.some((prop) => scoped.has(prop as string))
   }
 
   track(value: object, prop?: string) {
     const seed = Seed.from(value)
 
-    if (!this.tracking.has(seed)) {
-      this.tracking.set(seed, new Set())
+    if (!this.scopes.has(seed)) {
+      this.scopes.set(seed, new Set())
     }
 
     if (prop != null) {
-      this.tracking.get(seed).add(prop)
+      this.scopes.get(seed).add(prop)
     }
   }
 
@@ -116,8 +116,8 @@ export class Scope<T extends object> {
 
     return new Proxy(node, {
       get(target: Node, prop, proxy) {
-        // TODO: Rename $tracked to Symbol.for("ArborScoped")
-        if (prop === "$tracked") {
+        // TODO: Rename $scoped to Symbol.for("ArborScoped")
+        if (prop === "$scoped") {
           return true
         }
 

packages/arbor-store/tests/matchers/index.ts

@@ -3,8 +3,8 @@ import "./toBeDetached"
 import "./toBeNodeOf"
 import "./toBeProxiedExactlyOnce"
 import "./toBeSeeded"
-import "./toBeTrackedNode"
-import "./toBeTracking"
+import "./toBeScopedNode"
+import "./toBeScoping"
 import "./toHaveLink"
 import "./toHaveLinkFor"
 import "./toHaveNodeFor"

packages/arbor-store/tests/matchers/toBeScopedNode.ts

@@ -0,0 +1,15 @@
+import { expect } from "vitest"
+
+import { Scoped } from "../../src/scoping/scope"
+
+expect.extend({
+  toBeScopedNode(received) {
+    const isScoped = (received as Scoped)?.$scoped === true
+    return {
+      pass: isScoped,
+      actual: received,
+      message: () =>
+        `Received value is ${isScoped ? "" : "not"} a scoped Arbor node`,
+    }
+  },
+})

packages/arbor-store/tests/matchers/toBeTracking.ts → packages/arbor-store/tests/matchers/toBeScoping.ts

@@ -1,10 +1,10 @@
 import { expect } from "vitest"
 
 import { ArborError, isNode, NotAnArborNodeError, ScopedStore } from "../../src"
-import { Tracked } from "../../src/scoping/scope"
+import { Scoped } from "../../src/scoping/scope"
 
 expect.extend({
-  toBeTracking(scopedStore, node, prop) {
+  toBeScoping(scopedStore, node, prop) {
     if (!(scopedStore instanceof ScopedStore)) {
       throw new ArborError("received value is not an instance of ScopedStore")
     }
@@ -13,17 +13,17 @@ expect.extend({
       throw new NotAnArborNodeError()
     }
 
-    const isTrackedNode = (node as Tracked)?.$tracked === true
-    const isTrackingNodeProp =
-      isTrackedNode && scopedStore.scope.isTracking(node, prop)
+    const isScopedNode = (node as Scoped)?.$scoped === true
+    const toBeScopingNodeProp =
+      isScopedNode && scopedStore.scope.toBeScoping(node, prop)
 
     return {
-      pass: isTrackingNodeProp,
+      pass: toBeScopingNodeProp,
       actual: scopedStore,
       message: () =>
         `ScopedStore is ${
-          isTrackingNodeProp ? "" : "not"
-        } tracking prop ${prop} for node ${node}`,
+          toBeScopingNodeProp ? "" : "not"
+        } scoping updates to ${prop}`,
     }
   },
 })

packages/arbor-store/tests/scoping/array.test.ts

@@ -384,7 +384,7 @@ describe("Array", () => {
       delete scoped.state.todos[1]
       delete scoped.state.todos[1]
 
-      expect(scoped).not.toBeTracking(scoped.state.todos, 1)
+      expect(scoped).not.toBeScoping(scoped.state.todos, 1)
 
       expect(subscriber).toHaveBeenCalledTimes(2)
     })

packages/arbor-store/tests/scoping/map.test.ts

@@ -22,8 +22,8 @@ describe("map", () => {
 
       expect(unwrap(scopedNode1)).toBeNodeOf(alice)
       expect(unwrap(scopedNode2)).toBeNodeOf(bob)
-      expect(scopedNode1).toBeTrackedNode()
-      expect(scopedNode2).toBeTrackedNode()
+      expect(scopedNode1).toBeScopedNode()
+      expect(scopedNode2).toBeScopedNode()
     })
   })
 
@@ -62,8 +62,8 @@ describe("map", () => {
 
       expect(unwrap(list[0][1])).toBeNodeOf(alice)
       expect(unwrap(list[1][1])).toBeNodeOf(bob)
-      expect(list[0][1]).toBeTrackedNode()
-      expect(list[1][1]).toBeTrackedNode()
+      expect(list[0][1]).toBeScopedNode()
+      expect(list[1][1]).toBeScopedNode()
     })
   })
 })