mobx-keystone 2.0.0 → 2.1.0

package/src/parent/arrayPaths.ts

@@ -0,0 +1,242 @@
+import { createAtom, type IAtom } from "mobx"
+import { treeNodeMetadata } from "../tweaker/treeNodeMetadata"
+import { isPrimitive } from "../utils"
+import { ChunkedSequence, chunkSize, type SequenceChunk } from "../utils/chunks"
+import { reportParentPathChanged } from "./core"
+import type { ParentPath } from "./path"
+
+/** Arrays whose splices would reindex more children than this switch to lazy indexes. */
+const lazyIndexesThreshold = 1024
+
+class PathChunk implements SequenceChunk<LazyArrayParentPath | undefined> {
+  /** Path of each item, or undefined for primitives. */
+  items: (LazyArrayParentPath | undefined)[]
+  offset = 0
+  /**
+   * Changed when the index of any of its items changes, or when items move
+   * out of it, so observers of their paths follow them to their new chunk.
+   */
+  readonly atom: IAtom = createAtom("arrayPathChunk")
+  readonly owner: ArrayPaths
+
+  constructor(owner: ArrayPaths, items: (LazyArrayParentPath | undefined)[]) {
+    this.owner = owner
+    this.items = items
+  }
+}
+
+/**
+ * Parent path of an item of a large array. Its index is the offset of its chunk
+ * plus its position within it, so a splice only renumbers one chunk and moves
+ * the offsets of the chunks after it, instead of reindexing every item after it.
+ * Once removed, it keeps the index it had.
+ *
+ * @internal
+ */
+export class LazyArrayParentPath implements ParentPath<object> {
+  // declared rather than defined fields: there are as many instances as array
+  // items, and defined fields compile to an Object.defineProperty call each
+  declare readonly parent: object
+  /** Undefined once removed from the array. */
+  declare chunk: PathChunk | undefined
+  /** Position within the chunk, or the final index once removed. */
+  declare local: number
+
+  constructor(parent: object, chunk: PathChunk, local: number) {
+    this.parent = parent
+    this.chunk = chunk
+    this.local = local
+  }
+
+  get path(): number {
+    const chunk = this.chunk
+    if (!chunk) {
+      return this.local
+    }
+    chunk.owner.updateOffsets()
+    return chunk.offset + this.local
+  }
+
+  /**
+   * An immutable copy for callers outside the library, which may keep it,
+   * reused while the index stays the same.
+   */
+  toParentPath(): ParentPath<object> {
+    const path = this.path
+    let publicPath = publicPaths.get(this)
+    if (publicPath?.path !== path) {
+      publicPath = { parent: this.parent, path }
+      publicPaths.set(this, publicPath)
+    }
+    return publicPath
+  }
+
+  /** Makes observers of this path also react to index changes. */
+  reportObserved(): void {
+    this.chunk?.atom.reportObserved()
+  }
+}
+
+// kept apart, since few paths are ever handed out
+const publicPaths = new WeakMap<LazyArrayParentPath, ParentPath<object>>()
+
+class ArrayPaths extends ChunkedSequence<LazyArrayParentPath | undefined, PathChunk> {
+  readonly array: readonly unknown[]
+  private offsetsDirty = false
+
+  constructor(array: readonly unknown[]) {
+    super()
+    this.array = array
+    const length = array.length
+    for (let start = 0; start < length; start += chunkSize) {
+      // a slice is much faster than indexed reads through an observable array
+      const items = array.slice(start, start + chunkSize)
+      const chunk = new PathChunk(this, new Array(items.length))
+      for (let i = 0; i < items.length; i++) {
+        const item = items[i]
+        if (!isPrimitive(item)) {
+          const entry = new LazyArrayParentPath(array, chunk, i)
+          chunk.items[i] = entry
+          treeNodeMetadata.get(item as object)!.parentPath = entry
+          // current observers of its path do not observe its chunk yet
+          reportParentPathChanged(item as object)
+        }
+      }
+      this.chunks.push(chunk)
+    }
+    this.offsetsDirty = true
+  }
+
+  updateOffsets(): void {
+    if (!this.offsetsDirty) {
+      return
+    }
+    this.offsetsDirty = false
+    let offset = 0
+    for (const chunk of this.chunks) {
+      chunk.offset = offset
+      offset += chunk.items.length
+    }
+  }
+
+  /**
+   * Paths for values to be inserted at an index, undefined for primitives. They
+   * already resolve to their final index, but are only added by `splice`, so
+   * attaching the values can fail without leaving them behind.
+   */
+  createPaths(index: number, values: readonly unknown[]): (LazyArrayParentPath | undefined)[] {
+    this.updateOffsets()
+    if (this.chunks.length === 0) {
+      this.chunks.push(this.createChunk([]))
+    }
+    const [c, start] = this.locate(index)
+    const chunk = this.chunks[c]
+    const paths: (LazyArrayParentPath | undefined)[] = new Array(values.length)
+    for (let i = 0; i < values.length; i++) {
+      if (!isPrimitive(values[i])) {
+        paths[i] = new LazyArrayParentPath(this.array, chunk, start + i)
+      }
+    }
+    return paths
+  }
+
+  /** Applies a splice, freezing the removed paths and adding ones from `createPaths`. */
+  applySplice(
+    index: number,
+    removedCount: number,
+    addedPaths: (LazyArrayParentPath | undefined)[]
+  ): void {
+    this.updateOffsets()
+    this.splice(index, removedCount, addedPaths, freezeRemovedPath)
+    this.offsetsDirty = true
+  }
+
+  /** Replaces the path of an updated item, freezing the old one. */
+  set(index: number, value: unknown): LazyArrayParentPath | undefined {
+    this.updateOffsets()
+    const [c, local] = this.locate(index)
+    const chunk = this.chunks[c]
+    const old = chunk.items[local]
+    if (old) {
+      freezeRemovedPath(old, chunk, local)
+    }
+    const entry = isPrimitive(value) ? undefined : new LazyArrayParentPath(this.array, chunk, local)
+    chunk.items[local] = entry
+    return entry
+  }
+
+  protected createChunk(items: (LazyArrayParentPath | undefined)[]): PathChunk {
+    return new PathChunk(this, items)
+  }
+
+  protected onSpliced(chunk: PathChunk, from: number): void {
+    // the items after the splice moved within the chunk, and may move to other
+    // chunks when it is resized, where observers will follow them
+    renumber(chunk, from)
+    chunk.atom.reportChanged()
+  }
+
+  protected onItemsMoved(chunk: PathChunk, from: number): void {
+    renumber(chunk, from)
+  }
+
+  protected onShifted(chunk: PathChunk): void {
+    // the index of every item after the splice changed
+    chunk.atom.reportChanged()
+  }
+}
+
+function freezeRemovedPath(
+  entry: LazyArrayParentPath | undefined,
+  chunk: PathChunk,
+  local: number
+): void {
+  if (entry) {
+    entry.local = chunk.offset + local
+    entry.chunk = undefined
+  }
+}
+
+function renumber(chunk: PathChunk, from: number): void {
+  const items = chunk.items
+  for (let i = from; i < items.length; i++) {
+    const entry = items[i]
+    if (entry) {
+      entry.chunk = chunk
+      entry.local = i
+    }
+  }
+}
+
+const arrayPaths = new WeakMap<object, ArrayPaths>()
+
+/**
+ * Lazy indexes of an array, created once a splice would reindex many of its
+ * items.
+ *
+ * @internal
+ */
+export function getArrayPaths(
+  array: readonly unknown[],
+  reindexedCount: number
+): ArrayPaths | undefined {
+  let paths = arrayPaths.get(array)
+  if (!paths && reindexedCount > lazyIndexesThreshold) {
+    paths = new ArrayPaths(array)
+    arrayPaths.set(array, paths)
+  }
+  return paths
+}
+
+/**
+ * Makes an attached value use its lazy path, even if it was attached with an
+ * equal one.
+ *
+ * @internal
+ */
+export function setLazyArrayParentPath(entry: LazyArrayParentPath, node: object): void {
+  const metadata = treeNodeMetadata.get(node)!
+  if (metadata.parentPath !== entry) {
+    metadata.parentPath = entry
+  }
+}

package/src/parent/coreObjectChildren.ts

@@ -1,12 +1,10 @@
-import { action, createAtom, type IAtom } from "mobx"
+import { action, createAtom, type IAtom, untracked } from "mobx"
 import { addMutationBatchFinisher, isMutationBatchActive } from "../action/mutationBatch"
-import { getOrCreateTreeNodeMetadata } from "../tweaker/treeNodeMetadata"
+import { getOrCreateTreeNodeMetadata, treeNodeMetadata } from "../tweaker/treeNodeMetadata"
 import { fastGetParent } from "./path"
 
 interface DeepObjectChildren {
   deep: Set<object>
-
-  extensionsData: Map<object, unknown> | undefined
 }
 
 /** @internal */
@@ -16,6 +14,22 @@ export interface ObjectChildrenData extends DeepObjectChildren {
 
   deepDirty: boolean
   deepAtom: IAtom | undefined // will be created when first observed
+
+  extensions: Map<DeepObjectChildrenExtension<any>, ExtensionState<any>> | undefined
+
+  listeners: Set<ObjectChildrenListener> | undefined
+}
+
+/**
+ * Told about the nodes that may have been attached to or detached from the
+ * children of a node: its direct children, or all of its descendants when
+ * `deep`. Called inside the action making the change.
+ *
+ * @internal
+ */
+export interface ObjectChildrenListener {
+  readonly deep: boolean
+  onChildrenChanged(nodes: readonly object[]): void
 }
 
 interface DeepChildrenInvalidationEntry {
@@ -64,6 +78,10 @@ function getOrCreateDeepChildrenMutationTransaction(): DeepChildrenMutationTrans
   return transaction
 }
 
+// shared by all nodes whose deep children were never built (it is never mutated,
+// but replaced when they are built), so each node does not allocate an empty set
+const unbuiltDeepChildren = new Set<object>()
+
 function getObjectChildrenObject(node: object) {
   const metadata = getOrCreateTreeNodeMetadata(node)
   let obj = metadata.objectChildren
@@ -73,11 +91,13 @@ function getObjectChildrenObject(node: object) {
       shallow: new Set(),
       shallowAtom: undefined, // will be created when first observed
 
-      deep: new Set(),
+      deep: unbuiltDeepChildren,
       deepDirty: true,
       deepAtom: undefined, // will be created when first observed
 
-      extensionsData: initExtensionsData(),
+      extensions: undefined,
+
+      listeners: undefined,
     }
     metadata.objectChildren = obj
   }
@@ -97,6 +117,14 @@ export function getObjectChildren(node: object): ObjectChildrenData["shallow"] {
   return obj.shallow
 }
 
+/**
+ * Like `getObjectChildren(node).size > 0`, but without observing or allocating anything.
+ * @internal
+ */
+export function hasObjectChildren(node: object): boolean {
+  return (treeNodeMetadata.get(node)?.objectChildren?.shallow.size ?? 0) > 0
+}
+
 /**
  * @internal
  */
@@ -107,19 +135,16 @@ export function getDeepObjectChildren(node: object): DeepObjectChildren {
     updateDeepObjectChildren(node)
   }
 
-  if (!obj.deepAtom) {
-    obj.deepAtom = createAtom("deepChildrenAtom")
-  }
-  obj.deepAtom.reportObserved()
+  reportDeepObserved(obj)
 
   return obj
 }
 
-function addNodeToDeepLists(node: any, data: DeepObjectChildren) {
-  data.deep.add(node)
-  data.extensionsData?.forEach((extensionData, dataSymbol) => {
-    extensions.get(dataSymbol)!.addNode(node, extensionData)
-  })
+function reportDeepObserved(obj: ObjectChildrenData) {
+  if (!obj.deepAtom) {
+    obj.deepAtom = createAtom("deepChildrenAtom")
+  }
+  obj.deepAtom.reportObserved()
 }
 
 const updateDeepObjectChildren = action((node: object): DeepObjectChildren => {
@@ -147,19 +172,19 @@ function updateDeepObjectChildrenRecursive(node: object): DeepObjectChildren {
     }
   }
 
-  obj.deep = new Set()
-  obj.extensionsData = initExtensionsData(obj.extensionsData)
+  const deep = new Set<object>()
+  obj.deep = deep
 
   const childrenIterator = obj.shallow.values()
   let childrenIteratorResult = childrenIterator.next()
   while (!childrenIteratorResult.done) {
-    addNodeToDeepLists(childrenIteratorResult.value, obj)
+    deep.add(childrenIteratorResult.value)
 
     const childDeepChildren = updateDeepObjectChildrenRecursive(childrenIteratorResult.value).deep
     const childDeepChildrenIterator = childDeepChildren.values()
     let childDeepChildrenIteratorResult = childDeepChildrenIterator.next()
     while (!childDeepChildrenIteratorResult.done) {
-      addNodeToDeepLists(childDeepChildrenIteratorResult.value, obj)
+      deep.add(childDeepChildrenIteratorResult.value)
       childDeepChildrenIteratorResult = childDeepChildrenIterator.next()
     }
 
@@ -172,6 +197,8 @@ function updateDeepObjectChildrenRecursive(node: object): DeepObjectChildren {
   return obj
 }
 
+let lastAttachOrder = 0
+
 /**
  * Must run inside the action-wrapped `setParent`, its only source caller.
  *
@@ -185,6 +212,7 @@ export function addObjectChild(node: object, child: object): void {
   if (shallow.size === previousShallowSize) {
     return
   }
+  getOrCreateTreeNodeMetadata(child).attachOrder = ++lastAttachOrder
 
   onShallowChildrenChanged(node, obj, child, true)
 }
@@ -218,7 +246,9 @@ function onShallowChildrenChanged(
     node,
     obj,
     transaction,
-    recordDirectChildrenMutation(transaction, node, child, added)
+    recordDirectChildrenMutation(transaction, node, child, added),
+    child,
+    added
   )
 }
 
@@ -258,12 +288,35 @@ function invalidateDeepChildren(
   node: object,
   obj: ObjectChildrenData,
   transaction: DeepChildrenMutationTransaction | undefined,
-  mutation: DirectChildrenMutationEntry | undefined
+  mutation: DirectChildrenMutationEntry | undefined,
+  child: object,
+  added: boolean
 ) {
   let currentNode: object | undefined = node
   let currentObj = obj
+  let extensionChange: ExtensionChange | undefined
+  let subtree: readonly object[] | undefined
 
   while (currentNode) {
+    if (currentObj.extensions) {
+      extensionChange ??= new ExtensionChange(
+        () => (subtree ??= collectSubtree(child)),
+        added,
+        false
+      )
+      extensionChange.applyTo(currentObj.extensions)
+    }
+
+    if (currentObj.listeners) {
+      for (const listener of currentObj.listeners) {
+        if (listener.deep) {
+          listener.onChildrenChanged((subtree ??= collectSubtree(child)))
+        } else if (currentNode === node) {
+          listener.onChildrenChanged([child])
+        }
+      }
+    }
+
     if (transaction) {
       let entry = transaction.invalidatedNodes?.get(currentNode)
       if (!entry && !currentObj.deepDirty) {
@@ -334,45 +387,244 @@ function finishDeepChildrenMutationTransaction(transaction: DeepChildrenMutation
   })
 }
 
-const extensions = new Map<object, DeepObjectChildrenExtension<any>>()
-
-interface DeepObjectChildrenExtension<D> {
+/**
+ * Derived data kept per node about its deep children (e.g. an index of them).
+ * It is built from the deep children the first time it is needed and then kept
+ * up to date as descendants are attached and detached.
+ *
+ * @internal
+ */
+export interface DeepObjectChildrenExtension<D> {
   initData(): D
-  addNode(node: any, data: D): void
+  /** Adds a node while building the data from scratch, in deep children order. */
+  addNode(node: object, data: D): void
+  /**
+   * Adds a node attached after the data was built. Returns false when the data
+   * must be rebuilt instead. Defaults to `addNode`.
+   */
+  addNodeIncrementally?(node: object, data: D): boolean
+  /** Removes a detached node. Returns false when the data must be rebuilt instead. */
+  removeNode(node: object, data: D): boolean
+  /** Whether the data must be updated when a descendant model's id changes. */
+  dependsOnModelIds?: boolean
+}
+
+interface PendingExtensionChange {
+  readonly nodes: readonly object[]
+  readonly added: boolean
+}
+
+interface ExtensionState<D> {
+  readonly data: D
+  /** Data that could not be updated and must be rebuilt. */
+  dirty: boolean
+  /** Readers that need the data frozen; changes are queued meanwhile. */
+  pins: number
+  pending: PendingExtensionChange[] | undefined
 }
 
 /**
+ * Data of an extension frozen until released; changes made meanwhile are
+ * applied on release.
+ *
  * @internal
  */
-export function registerDeepObjectChildrenExtension<D>(extension: DeepObjectChildrenExtension<D>) {
-  const dataSymbol = {}
-  extensions.set(dataSymbol, extension)
-
-  return (data: DeepObjectChildren): D => {
-    let extensionsData = data.extensionsData
-    let extensionData = extensionsData?.get(dataSymbol) as D | undefined
-    if (!extensionsData?.has(dataSymbol)) {
-      extensionsData = data.extensionsData ??= new Map()
-      extensionData = extension.initData()
-      extensionsData.set(dataSymbol, extensionData)
-      data.deep.forEach((node) => {
-        extension.addNode(node, extensionData!)
-      })
+export interface PinnedDeepObjectChildrenExtensionData<D> {
+  readonly data: D
+  release(): void
+}
+
+/**
+ * @internal
+ */
+export interface DeepObjectChildrenExtensionAccessor<D> {
+  /**
+   * Gets the data. By default any change of the deep children is observed as a
+   * change of the data; pass `observeDeepChildren` false when the extension
+   * reports its own finer-grained changes.
+   */
+  get(node: object, observeDeepChildren?: boolean): D
+  pin(node: object): PinnedDeepObjectChildrenExtensionData<D>
+}
+
+/**
+ * @internal
+ */
+export function registerDeepObjectChildrenExtension<D>(
+  extension: DeepObjectChildrenExtension<D>
+): DeepObjectChildrenExtensionAccessor<D> {
+  const getState = (node: object, observeDeepChildren: boolean): ExtensionState<D> => {
+    const obj = getObjectChildrenObject(node)
+    let state = obj.extensions?.get(extension) as ExtensionState<D> | undefined
+    // changes queued while pinned make the data stale for anybody else
+    if (!state || state.dirty || state.pending) {
+      // building reads the nodes, which must not become dependencies
+      state = untracked(() => buildExtensionState(extension, node))
     }
-    return extensionData!
+    if (observeDeepChildren) {
+      reportDeepObserved(obj)
+    }
+    return state
+  }
+
+  return {
+    get(node, observeDeepChildren = true) {
+      return getState(node, observeDeepChildren).data
+    },
+
+    pin(node) {
+      const state = getState(node, false)
+      state.pins++
+      let released = false
+      return {
+        data: state.data,
+        release() {
+          if (released) return
+          released = true
+          state.pins--
+          if (state.pins === 0 && state.pending) {
+            const pending = state.pending
+            state.pending = undefined
+            for (const change of pending) {
+              applyExtensionChange(extension, state, change.nodes, change.added)
+            }
+          }
+        },
+      }
+    },
   }
 }
 
-function initExtensionsData(previousData?: ReadonlyMap<object, unknown>) {
-  if (previousData === undefined || previousData.size === 0) {
-    return undefined
+function buildExtensionState<D>(
+  extension: DeepObjectChildrenExtension<D>,
+  node: object
+): ExtensionState<D> {
+  const data = extension.initData()
+  getDeepObjectChildren(node).deep.forEach((n) => {
+    extension.addNode(n, data)
+  })
+
+  const state: ExtensionState<D> = {
+    data,
+    dirty: false,
+    pins: 0,
+    pending: undefined,
   }
+  const obj = getObjectChildrenObject(node)
+  ;(obj.extensions ??= new Map()).set(extension, state)
+  return state
+}
 
-  const extensionsData = new Map<object, unknown>()
+function applyExtensionChange(
+  extension: DeepObjectChildrenExtension<any>,
+  state: ExtensionState<any>,
+  nodes: readonly object[],
+  added: boolean
+) {
+  if (state.dirty) {
+    return
+  }
+  for (const n of nodes) {
+    let ok: boolean
+    if (!added) {
+      ok = extension.removeNode(n, state.data)
+    } else if (extension.addNodeIncrementally) {
+      ok = extension.addNodeIncrementally(n, state.data)
+    } else {
+      extension.addNode(n, state.data)
+      ok = true
+    }
+    if (!ok) {
+      state.dirty = true
+      return
+    }
+  }
+}
 
-  previousData?.forEach((_, dataSymbol) => {
-    extensionsData.set(dataSymbol, extensions.get(dataSymbol)!.initData())
-  })
+/**
+ * A membership change of some deep children, applied to the extension data of
+ * each ancestor of the changed parent.
+ */
+class ExtensionChange {
+  private nodes: readonly object[] | undefined
+  private readonly getNodes: () => readonly object[]
+  private readonly added: boolean
+  private readonly onlyModelIdDependent: boolean
+
+  constructor(getNodes: () => readonly object[], added: boolean, onlyModelIdDependent: boolean) {
+    this.getNodes = getNodes
+    this.added = added
+    this.onlyModelIdDependent = onlyModelIdDependent
+  }
 
-  return extensionsData
+  applyTo(extensions: NonNullable<ObjectChildrenData["extensions"]>) {
+    extensions.forEach((state, extension) => {
+      if (state.dirty || (this.onlyModelIdDependent && !extension.dependsOnModelIds)) {
+        return
+      }
+      this.nodes ??= this.getNodes()
+      if (state.pins > 0) {
+        ;(state.pending ??= []).push({ nodes: this.nodes, added: this.added })
+      } else {
+        applyExtensionChange(extension, state, this.nodes, this.added)
+      }
+    })
+  }
+}
+
+/** The node and its descendants, parents first. */
+function collectSubtree(root: object): object[] {
+  const nodes: object[] = []
+  const stack = [root]
+  while (stack.length > 0) {
+    const node = stack.pop()!
+    nodes.push(node)
+    const shallow = treeNodeMetadata.get(node)?.objectChildren?.shallow
+    shallow?.forEach((child) => {
+      stack.push(child)
+    })
+  }
+  return nodes
+}
+
+/**
+ * @internal
+ */
+export function addObjectChildrenListener(node: object, listener: ObjectChildrenListener): void {
+  ;(getObjectChildrenObject(node).listeners ??= new Set()).add(listener)
+}
+
+/**
+ * @internal
+ */
+export function removeObjectChildrenListener(node: object, listener: ObjectChildrenListener): void {
+  const obj = treeNodeMetadata.get(node)?.objectChildren
+  if (obj?.listeners?.delete(listener) && obj.listeners.size === 0) {
+    obj.listeners = undefined
+  }
+}
+
+/**
+ * Must be called after the id of a model changes.
+ *
+ * @internal
+ */
+export function onModelIdChanged(model: object): void {
+  const parent = fastGetParent(model, false)
+  if (!parent) {
+    return
+  }
+  // re-index the model under its new id
+  const nodes = [model]
+  const removal = new ExtensionChange(() => nodes, false, true)
+  const addition = new ExtensionChange(() => nodes, true, true)
+  let currentNode: object | undefined = parent
+  while (currentNode) {
+    const extensions = treeNodeMetadata.get(currentNode)?.objectChildren?.extensions
+    if (extensions) {
+      removal.applyTo(extensions)
+      addition.applyTo(extensions)
+    }
+    currentNode = fastGetParent(currentNode, false)
+  }
 }