mobx-keystone 1.24.1 → 2.0.0

package/src/patch/applyPatches.ts

@@ -3,10 +3,11 @@ import { BuiltInAction } from "../action/builtInActions"
 import { ActionContextActionType } from "../action/context"
 import { wrapInAction } from "../action/wrapInAction"
 import { modelToDataNode } from "../parent/core"
-import type { PathElement } from "../parent/pathTypes"
 import type { Patch } from "../patch/Patch"
+import { internalApplySnapshot } from "../snapshot/applySnapshot"
 import { reconcileSnapshot } from "../snapshot/reconcileSnapshot"
 import { assertTweakedObject } from "../tweaker/core"
+import { withTypeCheckingBatch } from "../tweaker/typeChecking"
 import { failure, inDevMode, isArray, lazy } from "../utils"
 import { runWithErrorDiagnosticsContext, withErrorPathSegments } from "../utils/errorDiagnostics"
 import { ModelPool } from "../utils/ModelPool"
@@ -14,6 +15,8 @@ import { setIfDifferent } from "../utils/setIfDifferent"
 
 /**
  * Applies the given patches to the given target object.
+ * Automatic type checking validates the completed batch, including nested lists.
+ * A rejected batch is rolled back with compensating patches.
  *
  * @param node Target object.
  * @param patches List of patches to apply.
@@ -45,33 +48,35 @@ export function internalApplyPatches(
     const obj = this
     const modelPool = new ModelPool(obj)
 
-    if (reverse) {
-      let i = patches.length
-      while (i--) {
-        const p = patches[i]
-        if (isArray(p)) {
-          let j = p.length
-          while (j--) {
-            applySinglePatchWithPath(obj, p[j], modelPool)
+    withTypeCheckingBatch(() => {
+      if (reverse) {
+        let i = patches.length
+        while (i--) {
+          const p = patches[i]
+          if (isArray(p)) {
+            let j = p.length
+            while (j--) {
+              applySinglePatchWithPath(obj, p[j], modelPool)
+            }
+          } else {
+            applySinglePatchWithPath(obj, p as Patch, modelPool)
           }
-        } else {
-          applySinglePatchWithPath(obj, p as Patch, modelPool)
         }
-      }
-    } else {
-      const len = patches.length
-      for (let i = 0; i < len; i++) {
-        const p = patches[i]
-        if (isArray(p)) {
-          const len2 = p.length
-          for (let j = 0; j < len2; j++) {
-            applySinglePatchWithPath(obj, p[j], modelPool)
+      } else {
+        const len = patches.length
+        for (let i = 0; i < len; i++) {
+          const p = patches[i]
+          if (isArray(p)) {
+            const len2 = p.length
+            for (let j = 0; j < len2; j++) {
+              applySinglePatchWithPath(obj, p[j], modelPool)
+            }
+          } else {
+            applySinglePatchWithPath(obj, p as Patch, modelPool)
           }
-        } else {
-          applySinglePatchWithPath(obj, p as Patch, modelPool)
         }
       }
-    }
+    })
   })
 }
 
@@ -84,16 +89,38 @@ const wrappedInternalApplyPatches = lazy(() =>
 )
 
 function applySinglePatch(obj: object, patch: Patch, modelPool: ModelPool): void {
-  const { target, prop } = pathArrayToObjectAndProp(obj, patch.path)
+  const path = patch.path
+  if (inDevMode && !isArray(path)) {
+    throw failure(`invalid path: ${path}`)
+  }
+
+  if (path.length === 0) {
+    if (patch.op === "add" || patch.op === "replace") {
+      internalApplySnapshot.call(obj, patch.value)
+      return
+    }
+    throw failure("a patch cannot remove the root node")
+  }
+
+  let target: any = modelToDataNode(obj)
+  for (let i = 0; i < path.length - 1; i++) {
+    target = modelToDataNode(target[path[i]])
+  }
+  const prop = path[path.length - 1]
 
   if (isArray(target)) {
+    if (patch.op === "replace" && prop === "length") {
+      target.length = patch.value
+      return
+    }
+
+    const index = getPatchArrayIndex(prop, target.length, patch.op)
     switch (patch.op) {
       case "add": {
-        const index = +prop!
         // reconcile from the pool if possible
         const newValue = reconcileSnapshot(undefined, patch.value, modelPool, target)
         if (index < 0) {
-          // extension needed by mobx-keystone-yjs
+          // non-standard extension: a negative index appends, just like "-"
           target.push(newValue)
         } else {
           target.splice(index, 0, newValue)
@@ -102,21 +129,15 @@ function applySinglePatch(obj: object, patch: Patch, modelPool: ModelPool): void
       }
 
       case "remove": {
-        const index = +prop!
         // no reconciliation, removing
         target.splice(index, 1)
         break
       }
 
       case "replace": {
-        if (prop === "length") {
-          target.length = patch.value
-        } else {
-          const index = +prop!
-          // try to reconcile
-          const newValue = reconcileSnapshot(target[index], patch.value, modelPool, target)
-          setIfDifferent(target, index as any, newValue)
-        }
+        // try to reconcile
+        const newValue = reconcileSnapshot(target[index], patch.value, modelPool, target)
+        setIfDifferent(target, index as any, newValue)
         break
       }
 
@@ -152,36 +173,30 @@ function applySinglePatch(obj: object, patch: Patch, modelPool: ModelPool): void
   }
 }
 
-function applySinglePatchWithPath(obj: object, patch: Patch, modelPool: ModelPool): void {
-  withErrorPathSegments(patch.path, () => {
-    applySinglePatch(obj, patch, modelPool)
-  })
-}
+// canonical decimal integers only, so "01", "1.0" or "1e0" are not mistaken for indexes
+const patchArrayIndexPattern = /^(?:0|-?[1-9]\d*)$/
 
-function pathArrayToObjectAndProp(
-  obj: object,
-  path: Patch["path"]
-): { target: any; prop?: PathElement } {
-  if (inDevMode) {
-    if (!isArray(path)) {
-      throw failure(`invalid path: ${path}`)
-    }
+function getPatchArrayIndex(prop: string | number, length: number, op: Patch["op"]): number {
+  // JSON Patch spells "at the end of the array" as "-", which only makes sense when adding
+  if (prop === "-" && op === "add") {
+    return length
   }
 
-  let target: any = modelToDataNode(obj)
+  const index =
+    typeof prop === "string" && !patchArrayIndexPattern.test(prop) ? Number.NaN : Number(prop)
 
-  if (path.length === 0) {
-    return {
-      target,
-    }
+  // additions may also target the end of the array, plus negative indexes as an append extension
+  const valid =
+    Number.isInteger(index) && (op === "add" ? index <= length : index >= 0 && index < length)
+  if (!valid) {
+    throw failure(`invalid array index '${String(prop)}' for '${op}' patch`)
   }
 
-  for (let i = 0; i <= path.length - 2; i++) {
-    target = modelToDataNode(target[path[i]])
-  }
+  return index
+}
 
-  return {
-    target,
-    prop: path[path.length - 1],
-  }
+function applySinglePatchWithPath(obj: object, patch: Patch, modelPool: ModelPool): void {
+  withErrorPathSegments(patch.path, () => {
+    applySinglePatch(obj, patch, modelPool)
+  })
 }

package/src/patch/emitPatch.ts

@@ -5,6 +5,7 @@ import type { PathElement } from "../parent/pathTypes"
 import { freezeInternalSnapshot, getInternalSnapshot } from "../snapshot/internal"
 import { assertTweakedObject } from "../tweaker/core"
 import { assertIsFunction, deleteFromArray, isPrimitive } from "../utils"
+import { forEachWithDelayedThrow } from "../utils/forEachWithDelayedThrow"
 import type { Patch } from "./Patch"
 
 const emptyPatchArray: Patch[] = []
@@ -31,12 +32,34 @@ export class InternalPatchRecorder {
     // empty arrays and must not trigger ancestor type checking.
     this.hasChanges = this.patches.length > 0 || this.invPatches.length > 0
   }
+}
 
-  emit(obj: object) {
-    if (this.patches.length > 0) {
-      emitPatches(obj, this.patches, this.invPatches)
-    }
-    this.reset()
+const runNotification = (notify: () => void) => notify()
+
+let patchEmissionDepth = 0
+let emittingPendingPatches = false
+const pendingPatchNotifications: (() => void)[] = []
+
+/** @internal */
+export function beginPatchEmission(): void {
+  patchEmissionDepth++
+}
+
+/** @internal */
+export function endPatchEmission(): void {
+  patchEmissionDepth--
+  flushPendingPatches()
+}
+
+function flushPendingPatches(): void {
+  if (patchEmissionDepth > 0 || emittingPendingPatches || pendingPatchNotifications.length === 0)
+    return
+  emittingPendingPatches = true
+  try {
+    forEachWithDelayedThrow(pendingPatchNotifications, (notify) => notify())
+  } finally {
+    pendingPatchNotifications.length = 0
+    emittingPendingPatches = false
   }
 }
 
@@ -44,11 +67,22 @@ export class InternalPatchRecorder {
  * @internal
  */
 export function emitPatches(obj: object, patches: Patch[], invPatches: Patch[]): void {
-  if (patches.length > 0) {
-    emitGlobalPatch(obj, patches, invPatches)
+  if (patches.length > 0 && (globalPatchListeners.length > 0 || patchListenerCount > 0)) {
+    const synchronousNotifications: (() => void)[] = []
+    if (globalPatchListeners.length > 0) {
+      emitGlobalPatch(obj, patches, invPatches, synchronousNotifications)
+    }
     if (patchListenerCount > 0) {
-      emitPatch(obj, patches, invPatches)
+      emitPatch(obj, patches, invPatches, synchronousNotifications)
     }
+    // Reserve every public notification and its path before recorder callbacks
+    // can cause further mutations. Recorders must run within the mutation's
+    // action / withoutUndo scope, even while public delivery is deferred.
+    // A throwing recorder must not stop the ones registered on ancestor nodes,
+    // nor swallow the deferred public delivery, so the flush is just one more
+    // step of the same delayed-throw delivery.
+    synchronousNotifications.push(flushPendingPatches)
+    forEachWithDelayedThrow(synchronousNotifications, runNotification)
   }
 }
 
@@ -71,8 +105,14 @@ export type OnGlobalPatchesListener = (
  */
 export type OnPatchesDisposer = () => void
 
-const patchListeners = new WeakMap<object, OnPatchesListener[]>()
-const globalPatchListeners: OnGlobalPatchesListener[] = []
+interface PatchSubscription<Listener> {
+  listener: Listener
+  synchronous: boolean
+  active: boolean
+}
+
+const patchListeners = new WeakMap<object, PatchSubscription<OnPatchesListener>[]>()
+const globalPatchListeners: PatchSubscription<OnGlobalPatchesListener>[] = []
 let patchListenerCount = 0
 
 /**
@@ -113,6 +153,15 @@ export function hasPatchListenersFor(target: object): boolean {
  * @returns A disposer to stop listening to patches.
  */
 export function onPatches(subtreeRoot: object, listener: OnPatchesListener): OnPatchesDisposer {
+  return internalOnPatches(subtreeRoot, listener, false)
+}
+
+/** @internal */
+export function internalOnPatches(
+  subtreeRoot: object,
+  listener: OnPatchesListener,
+  synchronous: boolean
+): OnPatchesDisposer {
   assertTweakedObject(subtreeRoot, "subtreeRoot")
   assertIsFunction(listener, "listener")
 
@@ -126,10 +175,12 @@ export function onPatches(subtreeRoot: object, listener: OnPatchesListener): OnP
     patchListeners.set(subtreeRoot, listenersForObject)
   }
 
-  listenersForObject.push(listener)
+  const subscription = { listener, synchronous, active: true }
+  listenersForObject.push(subscription)
   patchListenerCount++
   return () => {
-    if (deleteFromArray(listenersForObject, listener)) {
+    subscription.active = false
+    if (deleteFromArray(listenersForObject, subscription)) {
       patchListenerCount--
     }
   }
@@ -143,25 +194,81 @@ export function onPatches(subtreeRoot: object, listener: OnPatchesListener): OnP
  * @returns A disposer to stop listening to patches.
  */
 export function onGlobalPatches(listener: OnGlobalPatchesListener): OnPatchesDisposer {
+  return internalOnGlobalPatches(listener, false)
+}
+
+/** @internal */
+export function internalOnGlobalPatches(
+  listener: OnGlobalPatchesListener,
+  synchronous: boolean
+): OnPatchesDisposer {
   assertIsFunction(listener, "listener")
 
   if (!isAction(listener)) {
     listener = action(listener.name || "onGlobalPatchesListener", listener)
   }
 
-  globalPatchListeners.push(listener)
+  const subscription = { listener, synchronous, active: true }
+  globalPatchListeners.push(subscription)
   return () => {
-    deleteFromArray(globalPatchListeners, listener)
+    subscription.active = false
+    deleteFromArray(globalPatchListeners, subscription)
   }
 }
 
-function emitGlobalPatch(obj: object, patches: Patch[], inversePatches: Patch[]): void {
-  for (let i = 0; i < globalPatchListeners.length; i++) {
-    const listener = globalPatchListeners[i]
-    listener(obj, patches, inversePatches)
+function notifyPatchSubscriptions<Args extends unknown[]>(
+  subscriptions: PatchSubscription<(...args: Args) => void>[],
+  args: Args,
+  synchronous: boolean
+): void {
+  forEachWithDelayedThrow(subscriptions, (subscription) => {
+    if (subscription.active && subscription.synchronous === synchronous) {
+      subscription.listener(...args)
+    }
+  })
+}
+
+function reservePatchNotifications<Args extends unknown[]>(
+  subscriptions: PatchSubscription<(...args: Args) => void>[],
+  args: Args,
+  synchronousNotifications: (() => void)[]
+): void {
+  let hasSynchronous = false
+  let hasDeferred = false
+  for (let i = 0; i < subscriptions.length; i++) {
+    if (subscriptions[i].synchronous) {
+      hasSynchronous = true
+    } else {
+      hasDeferred = true
+    }
+  }
+  if (!hasSynchronous && !hasDeferred) {
+    return
+  }
+
+  // A listener installed by a reentrant action must not receive earlier patches.
+  const current = subscriptions.slice()
+  if (hasDeferred) {
+    pendingPatchNotifications.push(() => notifyPatchSubscriptions(current, args, false))
+  }
+  if (hasSynchronous) {
+    synchronousNotifications.push(() => notifyPatchSubscriptions(current, args, true))
   }
 }
 
+function emitGlobalPatch(
+  obj: object,
+  patches: Patch[],
+  inversePatches: Patch[],
+  synchronousNotifications: (() => void)[]
+): void {
+  reservePatchNotifications(
+    globalPatchListeners,
+    [obj, patches, inversePatches],
+    synchronousNotifications
+  )
+}
+
 // `reversedPrefix` holds the path segments from the changed node up to (but not
 // including) the current target, in child-to-root order. The prefix to prepend to
 // a patch is that slice reversed (root-to-child); `prefixCount` is how many of the
@@ -171,7 +278,8 @@ function emitPatchForTarget(
   patches: Patch[],
   inversePatches: Patch[],
   reversedPrefix: readonly PathElement[],
-  prefixCount: number
+  prefixCount: number,
+  synchronousNotifications: (() => void)[]
 ): void {
   const listenersForObject = patchListeners.get(obj)
 
@@ -184,19 +292,26 @@ function emitPatchForTarget(
   const invPatchesWithPathPrefix =
     prefixCount > 0 ? prefixPatches(inversePatches, reversedPrefix, prefixCount) : inversePatches
 
-  for (let i = 0; i < listenersForObject.length; i++) {
-    const listener = listenersForObject[i]
-    listener(patchesWithPathPrefix, invPatchesWithPathPrefix)
-  }
+  // Capture mutation-time paths before a deep-change listener can move nodes.
+  reservePatchNotifications(
+    listenersForObject,
+    [patchesWithPathPrefix, invPatchesWithPathPrefix],
+    synchronousNotifications
+  )
 }
 
-function emitPatch(obj: object, patches: Patch[], inversePatches: Patch[]): void {
+function emitPatch(
+  obj: object,
+  patches: Patch[],
+  inversePatches: Patch[],
+  synchronousNotifications: (() => void)[]
+): void {
   // Segments are pushed in child-to-root order (O(1) each) rather than unshifted
   // at the front (O(depth) each), keeping the whole walk O(depth) instead of
   // O(depth^2) on deep trees.
   const reversedPrefix: PathElement[] = []
 
-  emitPatchForTarget(obj, patches, inversePatches, reversedPrefix, 0)
+  emitPatchForTarget(obj, patches, inversePatches, reversedPrefix, 0, synchronousNotifications)
 
   // and also emit subtree listeners all the way to the root
   let parentPath = fastGetParentPath(obj, false)
@@ -207,7 +322,8 @@ function emitPatch(obj: object, patches: Patch[], inversePatches: Patch[]): void
       patches,
       inversePatches,
       reversedPrefix,
-      reversedPrefix.length
+      reversedPrefix.length,
+      synchronousNotifications
     )
 
     parentPath = fastGetParentPath(parentPath.parent, false)

package/src/patch/jsonPatch.ts

@@ -41,6 +41,8 @@ function escapePathComponent(path: string | number): string {
   return path.replace(/~/g, "~0").replace(/\//g, "~1")
 }
 
+const invalidPointerEscape = /~(?:[^01]|$)/
+
 /**
  * Unescapes a json pointer path.
  *
@@ -48,6 +50,9 @@ function escapePathComponent(path: string | number): string {
  * @return The unescaped path
  */
 function unescapePathComponent(path: string): string {
+  if (invalidPointerEscape.test(path)) {
+    throw failure("invalid JSON pointer escape: expected ~0 or ~1")
+  }
   return path.replace(/~1/g, "/").replace(/~0/g, "~")
 }
 

package/src/patch/patchRecorder.ts

@@ -1,10 +1,10 @@
 import { observable } from "mobx"
 import { assertTweakedObject } from "../tweaker/core"
 import {
+  internalOnGlobalPatches,
+  internalOnPatches,
   type OnPatchesDisposer,
   type OnPatchesListener,
-  onGlobalPatches,
-  onPatches,
 } from "./emitPatch"
 import type { Patch } from "./Patch"
 
@@ -111,18 +111,22 @@ export function internalPatchRecorder(
   let onPatchesDisposer: OnPatchesDisposer
 
   if (subtreeRoot) {
-    onPatchesDisposer = onPatches(subtreeRoot, (p, invP) => {
-      if (recording && filter(p, invP)) {
-        events.push({
-          target: subtreeRoot,
-          patches: p,
-          inversePatches: invP,
-        })
-        opts?.onPatches?.(p, invP)
-      }
-    })
+    onPatchesDisposer = internalOnPatches(
+      subtreeRoot,
+      (p, invP) => {
+        if (recording && filter(p, invP)) {
+          events.push({
+            target: subtreeRoot,
+            patches: p,
+            inversePatches: invP,
+          })
+          opts?.onPatches?.(p, invP)
+        }
+      },
+      true
+    )
   } else {
-    onPatchesDisposer = onGlobalPatches((target, p, invP) => {
+    onPatchesDisposer = internalOnGlobalPatches((target, p, invP) => {
       if (recording && filter(p, invP)) {
         events.push({
           target,
@@ -131,7 +135,7 @@ export function internalPatchRecorder(
         })
         opts?.onPatches?.(p, invP)
       }
-    })
+    }, true)
   }
 
   return {

package/src/redux/connectReduxDevTools.ts

@@ -33,6 +33,7 @@ export interface ConnectReduxDevToolsOptions {
  * @param remotedevConnection The result of a connect method from the remotedev package (usually the result of `remoteDev.connectViaExtension(...)`).
  * @param target Object to use as root.
  * @param [options] Optional options object.
+ * @returns An idempotent disposer that stops logging and unsubscribes from monitor messages.
  */
 export function connectReduxDevTools(
   remotedevPackage: any,
@@ -42,37 +43,35 @@ export function connectReduxDevTools(
 ) {
   assertTweakedObject(target, "target")
 
-  const opts = {
-    logArgsNearName: true,
-    logChildActions: true,
-    ...options,
-  }
+  const { logArgsNearName = true, logChildActions = true } = options ?? {}
 
+  let disposed = false
   let handlingMonitorAction = 0
 
+  let initialState = getSnapshot(target)
+  let lastLoggedSnapshot = initialState
+  remotedevConnection.init(initialState)
+
   // subscribe to change state (if need more than just logging)
-  remotedevConnection.subscribe((message: any) => {
-    if (message.type === "DISPATCH") {
+  const unsubscribe = remotedevConnection.subscribe((message: any) => {
+    if (!disposed && message.type === "DISPATCH") {
       handleMonitorActions(remotedevConnection, target, message)
     }
   })
 
-  const initialState = getSnapshot(target)
-  remotedevConnection.init(initialState)
-
   let currentActionId = 0
   const actionIdSymbol = Symbol("actionId")
 
-  actionTrackingMiddleware(target, {
+  const disposeMiddleware = actionTrackingMiddleware(target, {
     filter(ctx) {
-      return opts.logChildActions || !hasDevToolsTrackedParentContext(ctx)
+      return logChildActions || !hasDevToolsTrackedParentContext(ctx)
     },
     onStart(ctx) {
       ctx.data[actionIdSymbol] = currentActionId++
     },
     onResume(ctx) {
       // give a chance to the parent to log its own changes before the child starts
-      if (opts.logChildActions && ctx.parentContext) {
+      if (logChildActions && ctx.parentContext) {
         log(ctx.parentContext, undefined)
       }
       log(ctx, undefined)
@@ -85,6 +84,13 @@ export function connectReduxDevTools(
     },
   })
 
+  return () => {
+    if (disposed) return
+    disposed = true
+    disposeMiddleware()
+    if (typeof unsubscribe === "function") unsubscribe()
+  }
+
   function handleMonitorActions(remotedev2: any, target2: any, message: any) {
     try {
       handlingMonitorAction++
@@ -96,7 +102,8 @@ export function connectReduxDevTools(
         }
 
         case "COMMIT":
-          return remotedev2.init(getSnapshot(target2))
+          initialState = getSnapshot(target2)
+          return remotedev2.init(initialState)
 
         case "ROLLBACK": {
           const state = remotedevPackage.extractState(message)
@@ -122,13 +129,12 @@ export function connectReduxDevTools(
       }
     } finally {
       handlingMonitorAction--
+      lastLoggedSnapshot = getSnapshot(target2)
     }
   }
 
-  let lastLoggedSnapshot = initialState
-
   function log(ctx: SimpleActionContext, result: ActionTrackingResult | undefined) {
-    if (handlingMonitorAction) {
+    if (disposed || handlingMonitorAction) {
       return
     }
 
@@ -160,7 +166,7 @@ export function connectReduxDevTools(
     const pathStr = "[/" + rootPath.path.join("/") + "] "
     let name = pathStr + ctx.actionName
 
-    if (opts.logArgsNearName) {
+    if (logArgsNearName) {
       let args = ctx.args
         .map((a) => {
           try {

package/src/redux/redux.ts

@@ -83,7 +83,7 @@ export function asReduxStore<T extends object>(
       return getSnapshot(target)
     },
     dispatch(action) {
-      return runMiddlewares(action, runners, defaultDispatch)
+      return dispatch(action)
     },
     subscribe(listener) {
       return onSnapshot(target, listener)
@@ -91,25 +91,9 @@ export function asReduxStore<T extends object>(
   }
 
   const runners = middlewares.map((mw) => mw(store))
-
-  return store
-}
-
-function runMiddlewares<T>(
-  initialAction: ReduxAction,
-  runners: ReadonlyArray<ReduxRunner<T>>,
-  next: ReduxStore<T>["dispatch"]
-): ReduxAction {
-  let i = 0
-
-  function runNextMiddleware(action: ReduxAction): ReduxAction {
-    if (i < runners.length) {
-      const runner = runners[i]
-      i++
-      return runner(runNextMiddleware)(action)
-    }
-    return next(action)
+  let dispatch = defaultDispatch
+  for (let i = runners.length - 1; i >= 0; i--) {
+    dispatch = runners[i](dispatch)
   }
-
-  return runNextMiddleware(initialAction)
+  return store
 }