Immer: Api name

[mweststrate]

I am not too excited about immer as function name as it is undescriptive. What should the idiomatic name be?

Transform? Update? withMutations? Make?

[mweststrate]

Produce? Next? Mutate? Modify?

[Gregjarvez]

I was thinking about it too. Since it was designed primarily with redux in mind. i think the idiomatic name should contain redux-
maybe redux-musc, musc , musk. This package abstracts (musks) aways immutability lol

[AriaFallah]

@Gregjarvez this isn't coupled to redux though. It's for anything that you need to update immutably. For example, I've used it in just plain setState.

Regarding the actual name, I think "Create the next immutable state" from the README really captures the essence of what immer does. Thus, if verbosity wasn't an issue, then createNextStateImmutably would perfectly describe it. However, I do think that's a bit wordy so I maybe something like create, createNext, or nextState would work.

@mweststrate Of your suggestions, I like transform and make the most. Not a fan of update, mutate, or modify because those clash with the immutable nature of the library.

[benbraou]

I likewithMutations because it is familiar (immutable.js)
next and produce also convey the puropose of the library

[hex13]

I named similar function transform in my transmutable library.
https://github.com/hex13/enter-ghost/tree/master/packages/transmutable
I think it's kind of have sense - we're transforming the state by giving recipe of "how to transform"

On the other side redux.* would be horrible name - what if somebody would like to use this library out of Redux context? Coupling is bad, even in naming.

next would look good in context of Redux reducers, but it would look weird in anywhere else.

I think update, mutate, or modify are also good.

I came up also with run name (something like controlled running - here a state, run some code in context of this state and return result).

Or commit (because we "commit" mutations - like in Vuex).

two or more words would be probably too verbose for helper library.

[alexkrolick]

Some ideas:

• finalize
• finalizeDraft
• applyDraftChanges
• applyDiffFromDraft
• applyDiff
• newStateFromDraft

I like having draft in there because it makes it clear that the function is doing work with the return value of the 2nd argument.

[mweststrate]

Or just

import ✏ from "immer"

function insertItem(array, action) {
    return ✏(array, draft => {
        draft.splice(action.index, 0, action.item)
    })
}

:)

_edit_: that doesn't compile. Too bad, would be sooo cool.

[mweststrate]

I'm thinking about transform(state, recipe: draft => {}), it is short, makes quite clear that it produces a next state from the current one, and makes it nicely explainable:

"_transform_ the current _state_ to produce the next state according to this _recipe_ that expresses how a _draft_ state should be changed"

[alexkrolick]

"Transform" implies mutations, to me.

nextState(currentState, transform)

🤔

[Gregjarvez]

if the draft eventually becomes the next state

function insertItem(array, action) {
    return draft(array, nextState=> {
        nextState.splice(action.index, 0, action.item)
    })
}

:)

[mweststrate]

I think @alexkrolick brings up a good point, transform might imply modification existing data for many. _produce_ probably makes it clearer something new is created

function insertItem(array, action) {
    return produce(array, draft => {
        draft.splice(action.index, 0, action.item)
    })
}

[AjaxSolutions]

Definitely not immer.

The Urban Dictionary defines immer as someone who IMs a lot.

[hex13]

two ideas:

1. swap parameters (recipe, state) instead of other way around. It could be counterintuitive but it could help with partial application and reusing transformations.
2. allow for passing additional parameters to recipe function

const immer = require('immer').default;
const {createStore} = require('redux');

// proposal: if immer api look this way (fn, state, ...args):
const transform = (fn, state, ...args) => immer(state, draft => fn(draft, ...args));

//-----------------------------------------------
const initialState = {
    animals: ['cat', 'dog']
};

const addAnimal = (state, action) => {
    state.animals.push(action.animal);
};

const reducer = transform.bind(null, (state,  action) => {
    switch (action.type) {
        case 'add':
            addAnimal(state, action);
            break;
    }
});

const store = createStore(reducer, initialState);
store.subscribe(() => {
    console.log("STATE", store.getState())
});

store.dispatch({type: 'add', animal: 'monkey'});
store.dispatch({type: 'add', animal: 'chicken'});

though this is one liner but having such things in library out-of-the-box could be nice. Or it could use curry instead of partial application

(related: integration with Redux https://github.com/mweststrate/immer/issues/31
https://github.com/mweststrate/immer/issues/26 )

(but this is not only Redux related. This pattern could be helpful in many things, where we would like to store some recipe for transform for later use).

[alexkrolick]

@hex13 file a new issue for that? A separate thread would be nice.

[mweststrate]

@hex13 indeed, deserves separate issue :) also see #31, quite related

[mweststrate]

produce it will be. It allows for the concept of _producers_ which nicely rhymes with _reducers_ :). Will soon update. Or if someone beats me to it that is fine as well ;-). (make sure to claim the issue)

[mweststrate]

Done