index.js.flow 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113
  1. // @flow
  2. export interface Patch {
  3. op: "replace" | "remove" | "add";
  4. path: (string | number)[];
  5. value?: any;
  6. }
  7. export type PatchListener = (patches: Patch[], inversePatches: Patch[]) => void
  8. type Base = {...} | Array<any>
  9. interface IProduce {
  10. /**
  11. * Immer takes a state, and runs a function against it.
  12. * That function can freely mutate the state, as it will create copies-on-write.
  13. * This means that the original state will stay unchanged, and once the function finishes, the modified state is returned.
  14. *
  15. * If the first argument is a function, this is interpreted as the recipe, and will create a curried function that will execute the recipe
  16. * any time it is called with the current state.
  17. *
  18. * @param currentState - the state to start with
  19. * @param recipe - function that receives a proxy of the current state as first argument and which can be freely modified
  20. * @param initialState - if a curried function is created and this argument was given, it will be used as fallback if the curried function is called with a state of undefined
  21. * @returns The next state: a new state, or the current state if nothing was modified
  22. */
  23. <S: Base>(
  24. currentState: S,
  25. recipe: (draftState: S) => S | void,
  26. patchListener?: PatchListener
  27. ): S;
  28. // curried invocations with inital state
  29. <S: Base, A = void, B = void, C = void>(
  30. recipe: (draftState: S, a: A, b: B, c: C, ...extraArgs: any[]) => S | void,
  31. initialState: S
  32. ): (currentState: S | void, a: A, b: B, c: C, ...extraArgs: any[]) => S;
  33. // curried invocations without inital state
  34. <S: Base, A = void, B = void, C = void>(
  35. recipe: (draftState: S, a: A, b: B, c: C, ...extraArgs: any[]) => S | void
  36. ): (currentState: S, a: A, b: B, c: C, ...extraArgs: any[]) => S;
  37. }
  38. interface IProduceWithPatches {
  39. /**
  40. * Like `produce`, but instead of just returning the new state,
  41. * a tuple is returned with [nextState, patches, inversePatches]
  42. *
  43. * Like produce, this function supports currying
  44. */
  45. <S: Base>(
  46. currentState: S,
  47. recipe: (draftState: S) => S | void
  48. ): [S, Patch[], Patch[]];
  49. // curried invocations with inital state
  50. <S: Base, A = void, B = void, C = void>(
  51. recipe: (draftState: S, a: A, b: B, c: C, ...extraArgs: any[]) => S | void,
  52. initialState: S
  53. ): (currentState: S | void, a: A, b: B, c: C, ...extraArgs: any[]) => [S, Patch[], Patch[]];
  54. // curried invocations without inital state
  55. <S: Base, A = void, B = void, C = void>(
  56. recipe: (draftState: S, a: A, b: B, c: C, ...extraArgs: any[]) => S | void
  57. ): (currentState: S, a: A, b: B, c: C, ...extraArgs: any[]) => [S, Patch[], Patch[]];
  58. }
  59. declare export var produce: IProduce
  60. declare export default IProduce
  61. declare export var produceWithPatches: IProduceWithPatches
  62. declare export var nothing: typeof undefined
  63. declare export var immerable: Symbol
  64. /**
  65. * Automatically freezes any state trees generated by immer.
  66. * This protects against accidental modifications of the state tree outside of an immer function.
  67. * This comes with a performance impact, so it is recommended to disable this option in production.
  68. * By default it is turned on during local development, and turned off in production.
  69. */
  70. declare export function setAutoFreeze(autoFreeze: boolean): void
  71. /**
  72. * Manually override whether proxies should be used.
  73. * By default done by using feature detection
  74. */
  75. declare export function setUseProxies(useProxies: boolean): void
  76. declare export function applyPatches<S>(state: S, patches: Patch[]): S
  77. declare export function original<S>(value: S): S
  78. declare export function current<S>(value: S): S
  79. declare export function isDraft(value: any): boolean
  80. /**
  81. * Creates a mutable draft from an (immutable) object / array.
  82. * The draft can be modified until `finishDraft` is called
  83. */
  84. declare export function createDraft<T>(base: T): T
  85. /**
  86. * Given a draft that was created using `createDraft`,
  87. * finalizes the draft into a new immutable object.
  88. * Optionally a patch-listener can be provided to gather the patches that are needed to construct the object.
  89. */
  90. declare export function finishDraft<T>(base: T, listener?: PatchListener): T
  91. declare export function enableES5(): void
  92. declare export function enableMapSet(): void
  93. declare export function enablePatches(): void
  94. declare export function enableAllPlugins(): void
  95. declare export function freeze<T>(obj: T, freeze?: boolean): T