Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,8 +103,8 @@ Mutative ships patches, `Map`/`Set` support and native array methods built in; I

| Bundle | Immer | Mutative |
| ------------------------------------------- | -----: | -------: |
| `produce` / `create` only | 3.6 kB | 7.8 kB |
| With patches, `Map`/`Set` and array methods | 6.4 kB | 8.4 kB |
| `produce` / `create` only | 3.6 kB | 7.9 kB |
| With patches, `Map`/`Set` and array methods | 6.4 kB | 8.5 kB |

Mutative's `create` includes patches, `Map`/`Set` support and the native array methods even when a recipe does not use them: they are part of `create`, not separate imports, so bundlers cannot drop them. The difference buys the draft fast paths and the native array methods measured in the [performance summary](./perf-testing/reports/SUMMARY.md), which also records the artifact sizes of each measured source. See the [array methods FAQ](#faqs) for the supported fast paths and their contract, and the [Immer regression cases](./test/immer-array-methods.md) for the behavior of its array-method plugin.

Expand Down Expand Up @@ -242,6 +242,8 @@ The recipe can be an async function: `create()` then returns a Promise of the re

> A string path is a JSON Pointer and holds only strings, so it cannot name a Map key that is not a string, or a symbol key: with `pathAsArray: false`, the patch of `draft.set(1, 'b')` would set the key `'1'`. Keep the default array paths for such keys; development builds throw an error when a string path would hold one.

> TypeScript types the result from the type of `enablePatches` in the options passed to `create()` or `makeCreator()`: `true` or an object gives `[state, patches, inversePatches]`, and `boolean` gives either. Options typed `{ enablePatches: true }` that may be `undefined`, such as an optional parameter of a wrapper, or typed `{ enablePatches?: true }` still give the tuple, although `create()` returns the state alone when patches are off; type the flag as `boolean` there. With an explicit state type, TypeScript infers no other type argument, so pass `boolean` as the type argument for `enablePatches` as well, as in `create<State, false, boolean>(base, recipe, options)` or `create<State, [], false, boolean>(recipe, options)`.

- enableAutoFreeze - `boolean`, the default is false.

> Enable autoFreeze, and return frozen state, and enable circular reference checking only in `development` mode.
Expand Down Expand Up @@ -394,6 +396,8 @@ expect(baseState).toEqual({ foo: { bar: "test2" } });

> ⚠️Note: The mutable option cannot be combined with other options. When using mutable option, apply() will return void instead of a new state. As it changes the state in place, it throws for a patch that replaces the root state with another value, such as the patch of a recipe that returns a new state.

> `apply()` throws for a patch path through the `__proto__` or `constructor` of an object or array, or through the `prototype` of a function, so that patches cannot change the prototypes of objects; Map keys of these names are ordinary keys. It reads the other path segments as properties, as Immer does, and does not guard against prototypes that other code has already changed.

> Patches add and remove Set elements by value, also a changed element of a Set that added or removed elements, and `apply()` copies patch values, so inverse patches cannot remove an object that `apply()` added to a Set, as in an undo after a redo. `apply()` also appends the elements that it adds, so such a Set can hold its elements in another order, and the patches of a later recipe, which find Set elements by position, can then change another element. See [Sets of objects](https://mutative.js.org/docs/advanced-guides/pathes#sets-of-objects).

### `current()`
Expand Down Expand Up @@ -801,7 +805,7 @@ Mutative v2 keeps the v1 API. The changes below, made since v1.3.0, can affect e
- `create()` with an explicit state type and an async recipe, such as `create<State>(base, async (draft) => { … })`, returns `Promise<State>`, and so do curried producers; v1 typed the result as `State`.
- `apply()` accepts `enableAutoFreeze: true` and then returns `Immutable<State>`, as `apply<State, true>()` does; v1 rejected the option and typed the frozen result as mutable. With `enableAutoFreeze` typed as `boolean` or optional `true`, the result is `State | Immutable<State>`. With `mutable` typed as `boolean`, optional `boolean`, or optional `true`, `apply()` returns `State | void`.
- A curried producer whose recipe annotates its draft and returns a new state, such as `create((draft: State) => ({ ...draft, count: 0 }))`, returns `State`, or `Promise<State>` for an async recipe. v1 typed such a call as a manual draft, so calling the producer did not compile.
- With an explicit state type, a recipe that may or may not return a Promise, such as one typed `(draft: State) => void | Promise<void>`, gives `State | Promise<State>`, also in curried producers and creators from `makeCreator()`. v1 typed the result as `State`, as this version still does for a primitive state type, such as `number`.
- With an explicit state type, a recipe that may or may not return a Promise, such as one typed `(draft: State) => void | Promise<void>`, gives `State | Promise<State>`, also for a primitive state type, such as `number`, and in curried producers and creators from `makeCreator()`. v1 typed the result as `State`.

### Fixes that change results

Expand Down
10 changes: 5 additions & 5 deletions docs/functions/apply.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

> **apply**\<`T`, `F`, `_A`\>(`state`, `patches`, `applyOptions?`): `ApplyState`\<`T`, `F`, `undefined`\>

Defined in: [apply.ts:62](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/apply.ts#L62)
Defined in: [apply.ts:63](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/apply.ts#L63)

`apply(state, patches)` to apply patches to state

Expand Down Expand Up @@ -68,7 +68,7 @@ expect(state).toEqual(apply(baseState, patches));

> **apply**\<`T`, `F`, `A`\>(`state`, `patches`, `applyOptions`): `ApplyResult`\<`T`, `F`, `A`\>

Defined in: [apply.ts:71](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/apply.ts#L71)
Defined in: [apply.ts:72](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/apply.ts#L72)

`apply(state, patches)` to apply patches to state

Expand Down Expand Up @@ -126,7 +126,7 @@ expect(state).toEqual(apply(baseState, patches));

> **apply**\<`T`, `F`, `A`\>(`state`, `patches`, `applyOptions?`): `ApplyResult`\<`T`, `F`, `undefined` \| `A`\>

Defined in: [apply.ts:78](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/apply.ts#L78)
Defined in: [apply.ts:79](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/apply.ts#L79)

`apply(state, patches)` to apply patches to state

Expand Down Expand Up @@ -184,7 +184,7 @@ expect(state).toEqual(apply(baseState, patches));

> **apply**\<`T`, `F`\>(`state`, `patches`, `applyOptions`): `void`

Defined in: [apply.ts:89](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/apply.ts#L89)
Defined in: [apply.ts:90](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/apply.ts#L90)

`apply(state, patches)` to apply patches to state

Expand Down Expand Up @@ -240,7 +240,7 @@ expect(state).toEqual(apply(baseState, patches));

> **apply**\<`T`, `F`\>(`state`, `patches`, `applyOptions`): `ApplyResult`\<`T`, `F`, `undefined` \| `ApplyMutableOptions`\>

Defined in: [apply.ts:94](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/apply.ts#L94)
Defined in: [apply.ts:95](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/apply.ts#L95)

`apply(state, patches)` to apply patches to state

Expand Down
2 changes: 1 addition & 1 deletion docs/functions/castDraft.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **castDraft**\<`T`\>(`value`): [`Draft`](../type-aliases/Draft.md)\<`T`\>

Defined in: [utils/cast.ts:6](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/utils/cast.ts#L6)
Defined in: [utils/cast.ts:6](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/utils/cast.ts#L6)

Cast a value to an Draft type value.

Expand Down
2 changes: 1 addition & 1 deletion docs/functions/castImmutable.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **castImmutable**\<`T`\>(`value`): [`Immutable`](../type-aliases/Immutable.md)\<`T`\>

Defined in: [utils/cast.ts:13](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/utils/cast.ts#L13)
Defined in: [utils/cast.ts:13](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/utils/cast.ts#L13)

Cast a value to an Immutable type value.

Expand Down
2 changes: 1 addition & 1 deletion docs/functions/castMutable.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **castMutable**\<`T`\>(`draft`): `T`

Defined in: [utils/cast.ts:20](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/utils/cast.ts#L20)
Defined in: [utils/cast.ts:20](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/utils/cast.ts#L20)

Cast a value to an Mutable type value.

Expand Down
4 changes: 2 additions & 2 deletions docs/functions/current.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

> **current**\<`T`\>(`target`): `T`

Defined in: [current.ts:198](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/current.ts#L198)
Defined in: [current.ts:198](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/current.ts#L198)

`current(draft)` to get current state in the draft mutation function.

Expand Down Expand Up @@ -49,7 +49,7 @@ const state = create(

> **current**\<`T`\>(`target`): `T`

Defined in: [current.ts:200](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/current.ts#L200)
Defined in: [current.ts:200](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/current.ts#L200)

### Type Parameters

Expand Down
2 changes: 1 addition & 1 deletion docs/functions/isDraft.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **isDraft**(`target`): `boolean`

Defined in: [utils/draft.ts:33](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/utils/draft.ts#L33)
Defined in: [utils/draft.ts:33](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/utils/draft.ts#L33)

Check if the value is a draft

Expand Down
2 changes: 1 addition & 1 deletion docs/functions/isDraftable.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **isDraftable**(`value`, `options?`): `boolean`

Defined in: [utils/draft.ts:59](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/utils/draft.ts#L59)
Defined in: [utils/draft.ts:59](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/utils/draft.ts#L59)

Check if a value is draftable

Expand Down
2 changes: 1 addition & 1 deletion docs/functions/markSimpleObject.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **markSimpleObject**(`value`): `undefined` \| `"immutable"`

Defined in: [utils/marker.ts:26](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/utils/marker.ts#L26)
Defined in: [utils/marker.ts:26](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/utils/marker.ts#L26)

## Parameters

Expand Down
2 changes: 1 addition & 1 deletion docs/functions/original.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **original**\<`T`\>(`target`): `T`

Defined in: [original.ts:22](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/original.ts#L22)
Defined in: [original.ts:22](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/original.ts#L22)

`original(draft)` to get original state in the draft mutation function.

Expand Down
2 changes: 1 addition & 1 deletion docs/functions/rawReturn.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **rawReturn**\<`T`\>(`value`): `T`

Defined in: [rawReturn.ts:22](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/rawReturn.ts#L22)
Defined in: [rawReturn.ts:22](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/rawReturn.ts#L22)

Use rawReturn() to wrap the return value to skip the draft check and thus improve performance.

Expand Down
2 changes: 1 addition & 1 deletion docs/functions/unsafe.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **unsafe**\<`T`\>(`callback`): `T`

Defined in: [unsafe.ts:57](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/unsafe.ts#L57)
Defined in: [unsafe.ts:57](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/unsafe.ts#L57)

`unsafe(callback)` to access mutable data directly in strict mode.

Expand Down
10 changes: 5 additions & 5 deletions docs/interfaces/Options.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

# Interface: Options\<O, F\>

Defined in: [interface.ts:171](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/interface.ts#L171)
Defined in: [interface.ts:171](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/interface.ts#L171)

## Type Parameters

Expand All @@ -24,7 +24,7 @@ Defined in: [interface.ts:171](https://github.com/unadlib/mutative/blob/8667c30c

> `optional` **enableAutoFreeze**: `F`

Defined in: [interface.ts:184](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/interface.ts#L184)
Defined in: [interface.ts:184](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/interface.ts#L184)

Enable autoFreeze, and return frozen state.

Expand All @@ -34,7 +34,7 @@ Enable autoFreeze, and return frozen state.

> `optional` **enablePatches**: `O`

Defined in: [interface.ts:180](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/interface.ts#L180)
Defined in: [interface.ts:180](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/interface.ts#L180)

Enable patch, and return the patches and inversePatches.

Expand All @@ -44,7 +44,7 @@ Enable patch, and return the patches and inversePatches.

> `optional` **mark**: `Mark`\<`O`, `F`\> \| `Mark`\<`O`, `F`\>[]

Defined in: [interface.ts:189](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/interface.ts#L189)
Defined in: [interface.ts:189](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/interface.ts#L189)

Set a mark to determine if the object is mutable or if an instance is an immutable.
And it can also return a shallow copy function(AutoFreeze and Patches should both be disabled).
Expand All @@ -55,7 +55,7 @@ And it can also return a shallow copy function(AutoFreeze and Patches should bot

> `optional` **strict**: `boolean`

Defined in: [interface.ts:176](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/interface.ts#L176)
Defined in: [interface.ts:176](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/interface.ts#L176)

In strict mode, Forbid accessing non-draftable values and forbid returning a non-draft value.
Development builds also warn once when a recipe leaves 1,000 or more drafts unchanged.
2 changes: 1 addition & 1 deletion docs/type-aliases/Draft.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **Draft**\<`T`\> = `T` *extends* `Primitive` \| `AtomicObject` ? `T` : `T` *extends* `IfAvailable`\<`ReadonlyMap`\<infer K, infer V\>\> ? `DraftedMap`\<`K`, `V`\> : `T` *extends* `IfAvailable`\<`ReadonlySet`\<infer V\>\> ? `DraftedSet`\<`V`\> : `T` *extends* `WeakReferences` ? `T` : `T` *extends* `object` ? [`DraftedObject`](DraftedObject.md)\<`T`\> : `T`

Defined in: [interface.ts:229](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/interface.ts#L229)
Defined in: [interface.ts:229](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/interface.ts#L229)

## Type Parameters

Expand Down
2 changes: 1 addition & 1 deletion docs/type-aliases/DraftedObject.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **DraftedObject**\<`T`\> = `{ -readonly [K in keyof T]: Draft<T[K]> }`

Defined in: [interface.ts:225](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/interface.ts#L225)
Defined in: [interface.ts:225](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/interface.ts#L225)

## Type Parameters

Expand Down
2 changes: 1 addition & 1 deletion docs/type-aliases/Immutable.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **Immutable**\<`T`\> = `T` *extends* `Primitive` \| `AtomicObject` ? `T` : `T` *extends* `IfAvailable`\<`ReadonlyMap`\<infer K, infer V\>\> ? `ImmutableMap`\<`K`, `V`\> : `T` *extends* `IfAvailable`\<`ReadonlySet`\<infer V\>\> ? `ImmutableSet`\<`V`\> : `T` *extends* `WeakReferences` ? `T` : `T` *extends* `object` ? `ImmutableObject`\<`T`\> : `T`

Defined in: [interface.ts:211](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/interface.ts#L211)
Defined in: [interface.ts:211](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/interface.ts#L211)

## Type Parameters

Expand Down
2 changes: 1 addition & 1 deletion docs/type-aliases/Patch.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **Patch**\<`P`\> = `P` *extends* `object` ? `IPatch` & `object` : `P` *extends* `true` \| `object` ? `IPatch` & `object` : `IPatch` & `object`

Defined in: [interface.ts:96](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/interface.ts#L96)
Defined in: [interface.ts:96](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/interface.ts#L96)

## Type Parameters

Expand Down
2 changes: 1 addition & 1 deletion docs/type-aliases/Patches.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **Patches**\<`P`\> = [`Patch`](Patch.md)\<`P`\>[]

Defined in: [interface.ts:110](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/interface.ts#L110)
Defined in: [interface.ts:110](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/interface.ts#L110)

## Type Parameters

Expand Down
2 changes: 1 addition & 1 deletion docs/type-aliases/PatchesOptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> **PatchesOptions** = `boolean` \| \{ `arrayLengthAssignment?`: `boolean`; `pathAsArray?`: `boolean`; \}

Defined in: [interface.ts:18](https://github.com/unadlib/mutative/blob/8667c30c96a236a80844257728eb46826ca6f5d8/src/interface.ts#L18)
Defined in: [interface.ts:18](https://github.com/unadlib/mutative/blob/c2e96282fb77355d4c5f83d86c6d201dee734d45/src/interface.ts#L18)

## Type Declaration

Expand Down
Loading
Loading