refactor: rename createPublicDraft/finishPublicDraft for consistency

src/es5.js

@@ -28,7 +28,7 @@ export function willFinalize(scope, result, isReplaced) {
     }
 }
 
-export function createDraft(base, parent) {
+export function createProxy(base, parent) {
     const isArray = Array.isArray(base)
     const draft = clonePotentialDraft(base)
     each(draft, prop => {
@@ -70,7 +70,7 @@ function get(state, prop) {
     // Drafts are only created for proxyable values that exist in the base state.
     if (!state.finalizing && value === state.base[prop] && isDraftable(value)) {
         prepareCopy(state)
-        return (state.copy[prop] = createDraft(value, state))
+        return (state.copy[prop] = createProxy(value, state))
     }
     return value
 }

src/immer.d.ts

@@ -155,15 +155,18 @@ export function setUseProxies(useProxies: boolean): void
 export function applyPatches<S>(base: S, patches: Patch[]): S
 
 /**
- * Creates a mutable draft from an (immutable) object / array.
- * The draft can be modified until `finishDraft` is called
+ * Create an Immer draft from the given base state, which may be a draft itself.
+ * The draft can be modified until you finalize it with the `finishDraft` function.
  */
 export function createDraft<T>(base: T): Draft<T>
 
 /**
- * Given a draft that was created using `createDraft`,
- * finalizes the draft into a new immutable object.
- * Optionally a patch-listener can be provided to gather the patches that are needed to construct the object.
+ * Finalize an Immer draft from a `createDraft` call, returning the base state
+ * (if no changes were made) or a modified copy. The draft must __not__ be
+ * mutated afterwards.
+ *
+ * Pass a function as the 2nd argument to generate Immer patches based on the
+ * changes that were made.
  */
 export function finishDraft<T>(base: Draft<T>, listener?: PatchListener): T
 

src/immer.js

@@ -56,10 +56,10 @@ export class Immer {
         // Only plain objects, arrays, and "immerable classes" are drafted.
         if (isDraftable(base)) {
             const scope = ImmerScope.enter()
-            const baseDraft = this.createDraft(base)
+            const proxy = this.createProxy(base)
             let hasError = true
             try {
-                result = recipe.call(baseDraft, baseDraft)
+                result = recipe.call(proxy, proxy)
                 hasError = false
             } finally {
                 // finally instead of catch + rethrow better preserves original stack
@@ -86,15 +86,15 @@ export class Immer {
             return result !== NOTHING ? result : undefined
         }
     }
-    createPublicDraft(value) {
-        if (!isDraftable(value)) throw new Error("First argument to createDraft should be a plain-, or immerable object, or array.") // prettier-ignore
+    createDraft(base) {
+        if (!isDraftable(base)) throw new Error("First argument to createDraft should be a plain object, an array, or an immerable object.") // prettier-ignore
         const scope = ImmerScope.enter()
-        const draft = this.createDraft(value)
+        const proxy = this.createProxy(base)
         scope.leave()
-        return draft
+        return proxy
     }
-    finishPublicDraft(draft, patchListener) {
-        if (!isDraft(draft)) throw new Error("First argument to finishDraft should be an object created with createDraft.") // prettier-ignore
+    finishDraft(draft, patchListener) {
+        if (!isDraft(draft)) throw new Error("First argument to finishDraft should be an object from createDraft.") // prettier-ignore
         const {scope} = draft[DRAFT_STATE]
         scope.usePatches(patchListener)
         return this.processResult(undefined, scope)

src/index.js

@@ -46,9 +46,21 @@ export const setUseProxies = immer.setUseProxies.bind(immer)
  */
 export const applyPatches = immer.applyPatches.bind(immer)
 
-export const createDraft = immer.createPublicDraft.bind(immer)
+/**
+ * Create an Immer draft from the given base state, which may be a draft itself.
+ * The draft can be modified until you finalize it with the `finishDraft` function.
+ */
+export const createDraft = immer.createDraft.bind(immer)
 
-export const finishDraft = immer.finishPublicDraft.bind(immer)
+/**
+ * Finalize an Immer draft from a `createDraft` call, returning the base state
+ * (if no changes were made) or a modified copy. The draft must __not__ be
+ * mutated afterwards.
+ *
+ * Pass a function as the 2nd argument to generate Immer patches based on the
+ * changes that were made.
+ */
+export const finishDraft = immer.finishDraft.bind(immer)
 
 export {
     original,

src/proxy.js

@@ -14,7 +14,7 @@ import {ImmerScope} from "./scope"
 // Do nothing before being finalized.
 export function willFinalize() {}
 
-export function createDraft(base, parent) {
+export function createProxy(base, parent) {
     const scope = parent ? parent.scope : ImmerScope.current
     const state = {
         // Track which produce call this is associated with.
@@ -119,7 +119,7 @@ function get(state, prop) {
         drafts = state.copy
     }
 
-    return (drafts[prop] = createDraft(value, state))
+    return (drafts[prop] = createProxy(value, state))
 }
 
 function set(state, prop, value) {