tryReference and isValidReference (#1087)

* implementation

* renamed to tryReference

* updated changelog

* check that reaction can be used to clear invalid references

Author: xaviergonz

API.md

@@ -1019,6 +1019,7 @@ See the [full API docs](API.md) for more details.
 | [`isAlive(node)`](API.md#isalive)                                                                         | Returns `true` if `node` is alive                                                                                                                                                                                                                     |
 | [`isStateTreeNode(value)`](API.md#isstatetreenode)                                                        | Returns `true` if `value` is a node of a mobx-state-tree                                                                                                                                                                                              |
 | [`isProtected(value)`](API.md#isprotected)                                                                | Returns `true` if the given node is protected, see [actions](#actions)                                                                                                                                                                                |
+| [`isValidReference(() => node | null | undefined, checkIfAlive = true)`](API.md#isvalidreference)         | Tests if a reference is valid (pointing to an existing node and optionally if alive) and returns if the check passes or not.                                                                                                                          |
 | [`isRoot(node)`](API.md#isroot)                                                                           | Returns true if `node` has no parents                                                                                                                                                                                                                 |
 | [`joinJsonPath(parts)`](API.md#joinjsonpath)                                                              | Joins and escapes the given path `parts` into a JSON path                                                                                                                                                                                             |
 | [`onAction(node, (actionDescription) => void)`](API.md#onaction)                                          | A built-in middleware that calls the provided callback with an action description upon each invocation. Returns disposer                                                                                                                              |
@@ -1037,6 +1038,7 @@ See the [full API docs](API.md) for more details.
 | [`splitJsonPath(path)`](API.md#splitjsonpath)                                                             | Splits and unescapes the given JSON `path` into path parts                                                                                                                                                                                            |
 | [`typecheck(type, value)`](API.md#typecheck)                                                              | Typechecks a value against a type. Throws on errors. Use this if you need typechecks even in a production build.                                                                                                                                      |
 | [`tryResolve(node, path)`](API.md#tryresolve)                                                             | Like `resolve`, but just returns `null` if resolving fails at any point in the path                                                                                                                                                                   |
+| [`tryReference(() => node | null | undefined, checkIfAlive = true)`](API.md#tryreference)                 | Tests if a reference is valid (pointing to an existing node and optionally if alive) and returns such reference if it the check passes, else it returns undefined.                                                                                    |
 | [`unprotect(node)`](API.md#unprotect)                                                                     | Unprotects `node`, making it possible to directly modify any value in the subtree, without actions                                                                                                                                                    |
 | [`walk(startNode, (node) => void)`](API.md#walk)                                                          | Performs a depth-first walk through a tree                                                                                                                                                                                                            |
 | [`escapeJsonPath(path)`](API.md#escapejsonpath)                                                           | escape special characters in an identifier, according to http://tools.ietf.org/html/rfc6901                                                                                                                                                           |

README.md

@@ -1,3 +1,5 @@
+-   Added `tryReference` and `isValidReference` to use references that might be no longer pointing to any nodes in a safe way through [#1087](https://github.com/mobxjs/mobx-state-tree/pull/1087) by [@xaviergonz](https://github.com/xaviergonz)
+
 # 3.8.1
 
 -   Fixed non-initialized nodes not being destroyed [#1080](https://github.com/mobxjs/mobx-state-tree/issues/1080) through [#1082](https://github.com/mobxjs/mobx-state-tree/pull/1082) by [@k-g-a](https://github.com/k-g-a)

changelog.md

@@ -70,6 +70,8 @@ const METHODS_AND_INTERNAL_TYPES = stringToArray(`
     isReferenceType,
     isRefinementType,
     isUnionType,
+    isValidReference,
+    tryReference,
 
     types
 `)

packages/mobx-state-tree/__tests__/core/api.test.ts

@@ -16,7 +16,11 @@ import {
     SnapshotOrInstance,
     isAlive,
     destroy,
-    castToReferenceSnapshot
+    castToReferenceSnapshot,
+    tryReference,
+    isValidReference,
+    isStateTreeNode,
+    addDisposer
 } from "../../src"
 
 test("it should support prefixed paths in maps", () => {
@@ -48,6 +52,7 @@ test("it should support prefixed paths in maps", () => {
         users: { "17": { id: "17", name: "Michel" }, "18": { id: "18", name: "Noa" } }
     } as SnapshotOut<typeof store>)
 })
+
 test("it should support prefixed paths in arrays", () => {
     const User = types.model({
         id: types.identifier,
@@ -74,6 +79,7 @@ test("it should support prefixed paths in arrays", () => {
         users: [{ id: "17", name: "Michel" }, { id: "18", name: "Noa" }]
     } as SnapshotOut<typeof store>)
 })
+
 if (process.env.NODE_ENV !== "production") {
     test("identifiers are required", () => {
         const Todo = types.model({
@@ -85,6 +91,7 @@ if (process.env.NODE_ENV !== "production") {
             " `undefined` is not assignable to type: `identifier` (Value is not a valid identifier, expected a string)"
         )
     })
+
     test("identifiers cannot be modified", () => {
         const Todo = types.model({
             id: types.identifier
@@ -99,6 +106,7 @@ if (process.env.NODE_ENV !== "production") {
         )
     })
 }
+
 test("it should resolve refs during creation, when using path", () => {
     const values: number[] = []
     const Book = types.model({
@@ -132,6 +140,7 @@ test("it should resolve refs during creation, when using path", () => {
     expect(s.entries.reduce((a, e) => a + e.price, 0)).toBe(8)
     expect(values).toEqual([4, 8])
 })
+
 test("it should resolve refs over late types", () => {
     const Book = types.model({
         id: types.identifier,
@@ -158,6 +167,7 @@ test("it should resolve refs over late types", () => {
     expect(s.entries[0].price).toBe(4)
     expect(s.entries.reduce((a, e) => a + e.price, 0)).toBe(4)
 })
+
 test("it should resolve refs during creation, when using generic reference", () => {
     const values: number[] = []
     const Book = types.model({
@@ -223,6 +233,7 @@ test("string identifiers should not accept numbers", () => {
     expect(F2.is({ id: "4" })).toBe(true)
     expect(F2.is({ id: 4 })).toBe(false)
 })
+
 test("122 - identifiers should support numbers as well", () => {
     const F = types.model({
         id: types.identifierNumber
@@ -237,6 +248,7 @@ test("122 - identifiers should support numbers as well", () => {
     expect(F.is({ id: "4" })).toBe(false)
     expect(F.is({ id: "bla" })).toBe(false)
 })
+
 test("self reference with a late type", () => {
     const Book = types.model("Book", {
         id: types.identifier,
@@ -266,6 +278,7 @@ test("self reference with a late type", () => {
     s.addBook(book2)
     expect((s.books[1].reference as Instance<typeof Book>).genre).toBe("thriller")
 })
+
 test("when applying a snapshot, reference should resolve correctly if value added after", () => {
     const Box = types.model({
         id: types.identifierNumber,
@@ -282,6 +295,7 @@ test("when applying a snapshot, reference should resolve correctly if value adde
         })
     ).not.toThrow()
 })
+
 test("it should fail when reference snapshot is ambiguous", () => {
     const Box = types.model("Box", {
         id: types.identifierNumber,
@@ -324,6 +338,7 @@ test("it should fail when reference snapshot is ambiguous", () => {
         "[mobx-state-tree] Cannot resolve a reference to type '(Box | Arrow)' with id: '1' unambigously, there are multiple candidates: /boxes/0, /arrows/1"
     )
 })
+
 test("it should support array of references", () => {
     const Box = types.model({
         id: types.identifierNumber,
@@ -347,6 +362,7 @@ test("it should support array of references", () => {
     }).not.toThrow()
     expect(getSnapshot(store.selected)).toEqual([1, 2])
 })
+
 test("it should restore array of references from snapshot", () => {
     const Box = types.model({
         id: types.identifierNumber,
@@ -364,6 +380,7 @@ test("it should restore array of references from snapshot", () => {
     expect(store.selected[0] === store.boxes[0]).toEqual(true)
     expect(store.selected[1] === store.boxes[1]).toEqual(true)
 })
+
 test("it should support map of references", () => {
     const Box = types.model({
         id: types.identifierNumber,
@@ -387,6 +404,7 @@ test("it should support map of references", () => {
     }).not.toThrow()
     expect(getSnapshot(store.selected)).toEqual({ from: 1, to: 2 })
 })
+
 test("it should restore map of references from snapshot", () => {
     const Box = types.model({
         id: types.identifierNumber,
@@ -404,6 +422,7 @@ test("it should restore map of references from snapshot", () => {
     expect(store.selected.get("from") === store.boxes[0]).toEqual(true)
     expect(store.selected.get("to") === store.boxes[1]).toEqual(true)
 })
+
 test("it should support relative lookups", () => {
     const Node = types.model({
         id: types.identifierNumber,
@@ -447,6 +466,7 @@ test("it should support relative lookups", () => {
     expect(resolveIdentifier(Node, n5, 4)).toBe(n2.children[0])
     expect(resolveIdentifier(Node, n2.children[0], 5)).toBe(n5)
 })
+
 test("References are non-nullable by default", () => {
     const Todo = types.model({
         id: types.identifierNumber
@@ -489,6 +509,7 @@ test("References are non-nullable by default", () => {
         expect(() => ((store as any).ref = undefined)).toThrow(/Error while converting/)
     }
 })
+
 test("References are described properly", () => {
     const Todo = types.model({
         id: types.identifierNumber
@@ -502,6 +523,7 @@ test("References are described properly", () => {
         "{ todo: ({ id: identifierNumber } | undefined?); ref: reference(AnonymousModel); maybeRef: (reference(AnonymousModel) | undefined?) }"
     )
 })
+
 test("References in recursive structures", () => {
     const Folder = types.model("Folder", {
         id: types.identifierNumber,
@@ -590,6 +612,7 @@ test("References in recursive structures", () => {
     expect(store.objects.get("1")).toBe(store.tree.children[0].data)
     expect(store.objects.get("2")).toBe(store.tree.children[0].children[0].data)
 })
+
 test("it should applyPatch references in array", () => {
     const Item = types.model("Item", {
         id: types.identifier,
@@ -648,6 +671,7 @@ test("it should applyPatch references in array", () => {
         hovers: []
     })
 })
+
 test("it should applySnapshot references in array", () => {
     const Item = types.model("Item", {
         id: types.identifier,
@@ -850,7 +874,7 @@ test("#1052 - Reference returns destroyed model after subtree replacing", () =>
     }
 })
 
-it("#1080 - does not crash trying to resolve a reference to a destroyed+recreated model", () => {
+test("#1080 - does not crash trying to resolve a reference to a destroyed+recreated model", () => {
     const Branch = types.model("Branch", {
         id: types.identifierNumber,
         name: types.string
@@ -928,3 +952,73 @@ it("#1080 - does not crash trying to resolve a reference to a destroyed+recreate
         name: "Branch 2"
     })
 })
+
+test("tryReference / isValidReference", () => {
+    const Todo = types.model({ id: types.identifier })
+
+    const TodoStore = types
+        .model({
+            todos: types.array(Todo),
+            ref1: types.maybe(types.reference(Todo)),
+            ref2: types.maybeNull(types.reference(Todo)),
+            ref3: types.maybe(types.reference(Todo))
+        })
+        .actions(self => ({
+            clearRef3() {
+                self.ref3 = undefined
+            },
+            afterCreate() {
+                addDisposer(
+                    self,
+                    reaction(
+                        () => isValidReference(() => self.ref3),
+                        valid => {
+                            if (!valid) {
+                                this.clearRef3()
+                            }
+                        },
+                        { fireImmediately: true }
+                    )
+                )
+            }
+        }))
+
+    const store = TodoStore.create({
+        todos: [{ id: "1" }, { id: "2" }, { id: "3" }]
+    })
+
+    expect(tryReference(() => store.ref1)).toBeUndefined()
+    expect(tryReference(() => store.ref2)).toBeUndefined()
+    expect(isValidReference(() => store.ref1)).toBe(false)
+    expect(isValidReference(() => store.ref2)).toBe(false)
+
+    unprotect(store)
+    store.ref1 = store.todos[0]
+    store.ref2 = store.todos[1]
+    store.ref3 = store.todos[2]
+
+    expect(isStateTreeNode(store.ref1)).toBe(true)
+    expect(isStateTreeNode(store.ref2)).toBe(true)
+
+    expect(tryReference(() => store.ref1)).toBeDefined()
+    expect(tryReference(() => store.ref2)).toBeDefined()
+    expect(isValidReference(() => store.ref1)).toBe(true)
+    expect(isValidReference(() => store.ref2)).toBe(true)
+
+    store.todos = cast([])
+
+    expect(tryReference(() => store.ref1)).toBeUndefined()
+    expect(tryReference(() => store.ref2)).toBeUndefined()
+    expect(isValidReference(() => store.ref1)).toBe(false)
+    expect(isValidReference(() => store.ref2)).toBe(false)
+
+    // the reaction should have triggered and set this to undefined
+    expect(store.ref3).toBe(undefined)
+
+    expect(() => tryReference(() => 5 as any)).toThrowError(
+        "The reference to be checked is not one of node, null or undefined"
+    )
+    expect(() => isValidReference(() => 5 as any)).toThrowError(
+        "The reference to be checked is not one of node, null or undefined"
+    )
+})

packages/mobx-state-tree/__tests__/core/reference.test.ts

@@ -23,7 +23,8 @@ import {
     isModelType,
     INode,
     ModelPrimitive,
-    ExtractNodeC
+    ExtractNodeC,
+    InvalidReferenceError
 } from "../internal"
 
 export type TypeOrStateTreeNodeToStateTreeNode<
@@ -555,6 +556,71 @@ export function getIdentifier(target: IAnyStateTreeNode): string | null {
     return getStateTreeNode(target).identifier
 }
 
+/**
+ * Tests if a reference is valid (pointing to an existing node and optionally if alive) and returns such reference if it the check passes,
+ * else it returns undefined.
+ *
+ * @export
+ * @template N
+ * @param {(() => N | null | undefined)} getter Function to access the reference.
+ * @param {boolean} [checkIfAlive=true] true to also make sure the referenced node is alive (default), false to skip this check.
+ * @returns {(N | undefined)}
+ */
+export function tryReference<N extends IAnyStateTreeNode>(
+    getter: () => N | null | undefined,
+    checkIfAlive = true
+): N | undefined {
+    try {
+        const node = getter()
+        if (node === undefined || node === null) {
+            return undefined
+        } else if (isStateTreeNode(node)) {
+            if (!checkIfAlive) {
+                return node
+            } else {
+                return isAlive(node) ? node : undefined
+            }
+        } else {
+            return fail("The reference to be checked is not one of node, null or undefined")
+        }
+    } catch (e) {
+        if (e instanceof InvalidReferenceError) {
+            return undefined
+        }
+        throw e
+    }
+}
+
+/**
+ * Tests if a reference is valid (pointing to an existing node and optionally if alive) and returns if the check passes or not.
+ *
+ * @export
+ * @template N
+ * @param {(() => N | null | undefined)} getter Function to access the reference.
+ * @param {boolean} [checkIfAlive=true] true to also make sure the referenced node is alive (default), false to skip this check.
+ * @returns {boolean}
+ */
+export function isValidReference<N extends IAnyStateTreeNode>(
+    getter: () => N | null | undefined,
+    checkIfAlive = true
+): boolean {
+    try {
+        const node = getter()
+        if (node === undefined || node === null) {
+            return false
+        } else if (isStateTreeNode(node)) {
+            return checkIfAlive ? isAlive(node) : true
+        } else {
+            return fail("The reference to be checked is not one of node, null or undefined")
+        }
+    } catch (e) {
+        if (e instanceof InvalidReferenceError) {
+            return false
+        }
+        throw e
+    }
+}
+
 /**
  *
  *

packages/mobx-state-tree/src/core/mst-operations.ts

@@ -179,7 +179,9 @@ import {
     isPrimitiveType,
     isReferenceType,
     isRefinementType,
-    isUnionType
+    isUnionType,
+    tryReference,
+    isValidReference
 } from "./internal"
 
 export {
@@ -301,5 +303,7 @@ export {
     isPrimitiveType,
     isReferenceType,
     isRefinementType,
-    isUnionType
+    isUnionType,
+    tryReference,
+    isValidReference
 }