Skip to content

Commit b05ac6c

Browse files
feat(utils): add isModified helper to check whether a draft was modified (#1328)
Co-authored-by: Saad Abdullah <saadkhantareen@users.noreply.github.com>
1 parent d7c3ec9 commit b05ac6c

5 files changed

Lines changed: 145 additions & 0 deletions

File tree

‎__tests__/isModified.js‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
import {
2+
produce,
3+
createDraft,
4+
finishDraft,
5+
isModified,
6+
enableMapSet
7+
} from "../src/immer"
8+
9+
enableMapSet()
10+
11+
describe("isModified", () => {
12+
it("returns false for values that are not drafts", () => {
13+
expect(isModified({})).toBe(false)
14+
expect(isModified([])).toBe(false)
15+
expect(isModified(null)).toBe(false)
16+
expect(isModified(undefined)).toBe(false)
17+
expect(isModified(42)).toBe(false)
18+
expect(isModified("draft")).toBe(false)
19+
const next = produce({x: 1}, draft => {
20+
draft.x = 2
21+
})
22+
expect(isModified(next)).toBe(false)
23+
})
24+
25+
it("returns false for an unmodified draft", () => {
26+
produce({item: {count: 1}}, draft => {
27+
expect(isModified(draft)).toBe(false)
28+
expect(isModified(draft.item)).toBe(false)
29+
})
30+
})
31+
32+
it("returns true after a direct modification", () => {
33+
produce({x: 1}, draft => {
34+
draft.x = 2
35+
expect(isModified(draft)).toBe(true)
36+
})
37+
})
38+
39+
it("returns true after adding or deleting a property", () => {
40+
produce({x: 1}, draft => {
41+
draft.y = 2
42+
expect(isModified(draft)).toBe(true)
43+
})
44+
produce({x: 1}, draft => {
45+
delete draft.x
46+
expect(isModified(draft)).toBe(true)
47+
})
48+
})
49+
50+
it("returns false when the same value is assigned back", () => {
51+
produce({x: 1}, draft => {
52+
draft.x = 1
53+
expect(isModified(draft)).toBe(false)
54+
})
55+
})
56+
57+
it("tracks nested drafts and their parents, but not untouched siblings", () => {
58+
const base = {
59+
item: {count: 1},
60+
other: {count: 10}
61+
}
62+
produce(base, draft => {
63+
draft.item.count = 2
64+
expect(isModified(draft.item)).toBe(true)
65+
// modifications propagate to parent drafts
66+
expect(isModified(draft)).toBe(true)
67+
expect(isModified(draft.other)).toBe(false)
68+
})
69+
})
70+
71+
it("tracks array modifications", () => {
72+
produce([1, 2, 3], draft => {
73+
expect(isModified(draft)).toBe(false)
74+
draft.push(4)
75+
expect(isModified(draft)).toBe(true)
76+
})
77+
produce({list: [1, 2, 3]}, draft => {
78+
draft.list[0] = 99
79+
expect(isModified(draft.list)).toBe(true)
80+
expect(isModified(draft)).toBe(true)
81+
})
82+
})
83+
84+
it("works with manually created drafts", () => {
85+
const draft = createDraft({item: {count: 1}})
86+
expect(isModified(draft)).toBe(false)
87+
expect(isModified(draft.item)).toBe(false)
88+
draft.item.count = 2
89+
expect(isModified(draft.item)).toBe(true)
90+
expect(isModified(draft)).toBe(true)
91+
const next = finishDraft(draft)
92+
expect(next.item.count).toBe(2)
93+
})
94+
95+
it("tracks Map and Set drafts", () => {
96+
const base = {
97+
map: new Map([["a", 1]]),
98+
set: new Set([1])
99+
}
100+
produce(base, draft => {
101+
expect(isModified(draft.map)).toBe(false)
102+
draft.map.set("b", 2)
103+
expect(isModified(draft.map)).toBe(true)
104+
expect(isModified(draft)).toBe(true)
105+
expect(isModified(draft.set)).toBe(false)
106+
draft.set.add(2)
107+
expect(isModified(draft.set)).toBe(true)
108+
})
109+
})
110+
111+
it("supports the derived-data use case from the proposal", () => {
112+
const base = {item: {count: 1, modifiedOn: null}}
113+
const next = produce(base, draft => {
114+
draft.item.count++
115+
if (isModified(draft.item)) {
116+
draft.item.modifiedOn = "now"
117+
}
118+
})
119+
expect(next.item.modifiedOn).toBe("now")
120+
121+
const untouched = produce(base, draft => {
122+
if (isModified(draft.item)) {
123+
draft.item.modifiedOn = "now"
124+
}
125+
})
126+
expect(untouched).toBe(base)
127+
})
128+
})

‎src/immer.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ export {
1717
current,
1818
isDraft,
1919
isDraftable,
20+
isModified,
2021
NOTHING as nothing,
2122
DRAFTABLE as immerable,
2223
freeze,

‎src/types/index.js.flow‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,8 @@ declare export function current<S>(value: S): S
106106

107107
declare export function isDraft(value: any): boolean
108108

109+
declare export function isModified(value: any): boolean
110+
109111
/**
110112
* Creates a mutable draft from an (immutable) object / array.
111113
* The draft can be modified until `finishDraft` is called

‎src/utils/common.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,19 @@ export const VALUE = "value"
2828
/*#__PURE__*/
2929
export let isDraft = (value: any): boolean => !!value && !!value[DRAFT_STATE]
3030

31+
/**
32+
* Returns true if the given value is an Immer draft that has been modified,
33+
* either directly or through one of its nested drafts. Modifications made to
34+
* a nested draft mark all of its parent drafts as modified as well, so this
35+
* also reports modifications that happened anywhere inside the given draft.
36+
* Returns false for values that are not drafts.
37+
*/
38+
/*#__PURE__*/
39+
export function isModified(value: any): boolean {
40+
if (!isDraft(value)) return false
41+
return value[DRAFT_STATE].modified_
42+
}
43+
3144
/** Returns true if the given value can be drafted by Immer */
3245
/*#__PURE__*/
3346
export function isDraftable(value: any): boolean {

‎website/docs/api.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ title: API overview
2525
| `immerable` | Symbol that can be added to a constructor or prototype, to indicate that Immer should treat the class as something that can be safely drafted | [Classes](./complex-objects.md) |
2626
| `Immutable<T>` | Exposed TypeScript type to convert mutable types to immutable types | |
2727
| `isDraft` | Returns true if the given object is a draft object | |
28+
| `isModified` | Returns true if the given object is a draft object that has been modified, either directly or through one of its nested drafts. Returns false for values that are not drafts | |
2829
| `isDraftable` | Returns true if Immer is capable of turning this object into a draft. Which is true for: arrays, objects without prototype, objects with `Object` as their prototype, objects that have the `immerable` symbol on their constructor or prototype | |
2930
| `nothing` | Value that can be returned from a recipe, to indicate that the value `undefined` should be produced | [Return](./return.mdx) |
3031
| `original` | Given a draft object (doesn't have to be a tree root), returns the original object at the same path in the original state tree, if present | [Original](./original.md) |

0 commit comments

Comments
 (0)