feat: add types for Immer class

src/index.d.ts

@@ -55,61 +55,121 @@ export type PatchListener = (patches: Patch[], inversePatches: Patch[]) => void
 
 export interface IProduce {
     /**
-     * Immer takes a state, and runs a function against it.
-     * That function can freely mutate the state, as it will create copies-on-write.
-     * This means that the original state will stay unchanged, and once the function finishes, the modified state is returned.
+     * The `produce` function takes a value and a "recipe function" (whose
+     * return value often depends on the base state). The recipe function is
+     * free to mutate its first argument however it wants. All mutations are
+     * only ever applied to a __copy__ of the base state.
      *
-     * If the first argument is a function, this is interpreted as the recipe, and will create a curried function that will execute the recipe
-     * any time it is called with the current state.
+     * Pass only a function to create a "curried producer" which relieves you
+     * from passing the recipe function every time.
      *
-     * @param currentState - the state to start with
-     * @param recipe - function that receives a proxy of the current state as first argument and which can be freely modified
-     * @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
-     * @returns The next state: a new state, or the current state if nothing was modified
+     * Only plain objects and arrays are made mutable. All other objects are
+     * considered uncopyable.
+     *
+     * Note: This function is __bound__ to its `Immer` instance.
+     *
+     * @param {any} base - the initial state
+     * @param {Function} producer - function that receives a proxy of the base state as first argument and which can be freely modified
+     * @param {Function} patchListener - optional function that will be called with all the patches produced here
+     * @returns {any} a new state, or the initial state if nothing was modified
      */
     <S = any, R = never>(
         currentState: S,
-        recipe: (this: Draft<S>, draftState: Draft<S>) => void | R,
+        recipe: (this: Draft<S>, draft: Draft<S>) => void | R,
         listener?: PatchListener
     ): R
 
     /** Curried producer with an initial state */
     <S = any, R = never>(
-        recipe: (this: Draft<S>, draftState: Draft<S>) => void | R,
-        initialState: S
-    ): (currentState: S | undefined) => R
+        recipe: (this: Draft<S>, draft: Draft<S>) => void | R,
+        defaultBase: S
+    ): (base: S | undefined) => R
 
     /** Curried producer with no initial state */
     <S = any, R = never, Args extends any[] = any[]>(
         recipe: (
             this: Draft<S>,
-            draftState: Draft<S>,
+            draft: Draft<S>,
             ...extraArgs: Args
         ) => void | R
-    ): (currentState: S, ...extraArgs: Args) => R
+    ): (base: S, ...extraArgs: Args) => R
 }
 
 export const produce: IProduce
 export default produce
 
+/**
+ * The sentinel value returned by producers to replace the draft with undefined.
+ */
 export const nothing: undefined
 
 /**
- * Automatically freezes any state trees generated by immer.
- * This protects against accidental modifications of the state tree outside of an immer function.
- * This comes with a performance impact, so it is recommended to disable this option in production.
- * It is by default enabled.
+ * Pass true to automatically freeze all copies created by Immer.
+ *
+ * By default, auto-freezing is disabled in production.
  */
 export function setAutoFreeze(autoFreeze: boolean): void
 
 /**
- * Manually override whether proxies should be used.
- * By default done by using feature detection
+ * Pass true to use the ES2015 `Proxy` class when creating drafts, which is
+ * always faster than using ES5 proxies.
+ *
+ * By default, feature detection is used, so calling this is rarely necessary.
  */
 export function setUseProxies(useProxies: boolean): void
 
-export function applyPatches<S>(state: S, patches: Patch[]): S
+/**
+ * Apply an array of Immer patches to the first argument.
+ *
+ * This function is a producer, which means copy-on-write is in effect.
+ */
+export function applyPatches<S>(base: S, patches: Patch[]): S
 
 export function original<T>(value: T): T | void
 
 export function isDraft(value: any): boolean
+
+export class Immer {
+    constructor(config: {useProxies?: boolean; autoFreeze?: boolean})
+    /**
+     * The `produce` function takes a value and a "recipe function" (whose
+     * return value often depends on the base state). The recipe function is
+     * free to mutate its first argument however it wants. All mutations are
+     * only ever applied to a __copy__ of the base state.
+     *
+     * Pass only a function to create a "curried producer" which relieves you
+     * from passing the recipe function every time.
+     *
+     * Only plain objects and arrays are made mutable. All other objects are
+     * considered uncopyable.
+     *
+     * Note: This function is __bound__ to its `Immer` instance.
+     *
+     * @param {any} base - the initial state
+     * @param {Function} producer - function that receives a proxy of the base state as first argument and which can be freely modified
+     * @param {Function} patchListener - optional function that will be called with all the patches produced here
+     * @returns {any} a new state, or the initial state if nothing was modified
+     */
+    produce: IProduce
+    /**
+     * When true, `produce` will freeze the copies it creates.
+     */
+    readonly autoFreeze: boolean
+    /**
+     * When true, drafts are ES2015 proxies.
+     */
+    readonly useProxies: boolean
+    /**
+     * Pass true to automatically freeze all copies created by Immer.
+     *
+     * By default, auto-freezing is disabled in production.
+     */
+    setAutoFreeze(autoFreeze: boolean): void
+    /**
+     * Pass true to use the ES2015 `Proxy` class when creating drafts, which is
+     * always faster than using ES5 proxies.
+     *
+     * By default, feature detection is used, so calling this is rarely necessary.
+     */
+    setUseProxies(useProxies: boolean): void
+}