mutate-cow 7.0.1 → 8.1.0

package/README.md

@@ -17,18 +17,11 @@ const newAnimals = mutate(animals)
 
 This module allows you to update an immutable object as if it were mutable. It has copy-on-write semantics, so properties are only changed if you write to them. (In fact, if you perform no writes, the same object is returned back.) This makes it useful in conjuction with libraries like React, where state may be compared by reference.
 
-`mutate-cow` provides useful features that other packages don't:
-
- * All property descriptors from the immutable object are preserved in the copy.
- * All extensibility information from the immutable object is preserved in the copy. Combined with the above point, this means that sealed objects stay sealed and frozen objects stay frozen.
- * Arrays, objects, and class instances are supported for mutation.
- * Flow and TypeScript definitions are provided.
-
 No cows were harmed in the making of this code.
 
 ## API
 
-### const ctx = mutate(source)
+### const ctx = mutate(source, /* strict = */ false)
 
 Returns a "context" object which can modify a copy of `source`.
 
@@ -37,6 +30,12 @@ const foo = deepFreeze({bar: {baz: []}});
 const ctx = mutate(foo);
 ````
 
+By default, you can mutate primitves, arrays, and plain objects. However, if `strict` is set to true, the following features are enabled:
+
+ * All property descriptors from the immutable object are preserved in the copy.
+ * All extensibility information from the immutable object is preserved in the copy. Combined with the above point, this means that sealed objects stay sealed and frozen objects stay frozen.
+ * Class instances are supported for mutation.
+
 ### ctx.read()
 
 Returns the current working copy of the context's `source` object, or just `source` if no changes were made.
@@ -132,10 +131,10 @@ Returns a boolean indicating whether `ctx` has been revoked.
 
 ### ctx.final()
 
-This is the same as `read`, except it also revokes the context and restores all property descriptors and extensibility information. This is what you call to get the final copy.
+This is the same as `read`, except it also revokes the context, and in strict mode restores all property descriptors and extensibility information. This is what you call to get the final copy.
 
 ```js
-const copy = mutate(foo).set('bar', 'baz', 'qux').final();
+const copy = mutate(foo, /* strict = */ true).set('bar', 'baz', 'qux').final();
 Object.isFrozen(copy) === true; // since `foo` was frozen, `copy` will be too
 ````
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mutate-cow",
-  "version": "7.0.1",
+  "version": "8.1.0",
   "description": "Update immutable objects as if they were mutable with copy-on-write",
   "keywords": [
     "immutable",
@@ -18,7 +18,7 @@
   },
   "devDependencies": {
     "benchmark": "2.1.4",
-    "flow-bin": "0.275.0",
+    "flow-bin": "0.290.0",
     "immer": "10.1.1",
     "mutative": "1.2.0",
     "tsd": "0.29.0"

package/src/index.js

@@ -5,10 +5,12 @@
  * in the file named "LICENSE" at the root directory of this distribution.
  */
 
+const EMPTY_OBJECT = Object.freeze({});
+
 const NATIVE_CODE_REGEXP = /^function \w*\(\) \{\s*\[native code\]\s*\}$/m;
 
 const STATUS_NONE = 1;
-const STATUS_CHANGED = 2;
+const STATUS_MUTABLE = 2;
 const STATUS_REVOKED = 3;
 const STATUS_STALE = 4;
 
@@ -20,40 +22,41 @@ function isPrimitive(value) {
   return (type !== 'function' && type !== 'object');
 }
 
-function getCloneableType(value) {
-  if (isPrimitive(value)) {
-    return 1;
-  }
-  if (typeof value !== 'object') {
-    return 0;
+function isCloneableObject(object) {
+  if (typeof object === 'function') {
+    return false;
   }
-  let proto = Object.getPrototypeOf(value);
+  let proto = Object.getPrototypeOf(object);
   while (proto) {
     let ctor = proto.constructor;
-    // A Generator object's constructor is an object.
-    if (ctor && typeof ctor === 'object') {
-      ctor = ctor.constructor;
-    }
-    if (
-      typeof ctor === 'function' &&
-      ctor.name !== 'Array' &&
-      ctor.name !== 'Object' &&
-      NATIVE_CODE_REGEXP.test(Function.prototype.toString.call(ctor))
-    ) {
-      return 0;
+    if (ctor) {
+      // A Generator object's constructor is an object.
+      if (typeof ctor === 'object') {
+        ctor = ctor.constructor;
+      }
+      if (
+        typeof ctor === 'function' &&
+        ctor.name !== 'Array' &&
+        ctor.name !== 'Object' &&
+        NATIVE_CODE_REGEXP.test(Function.prototype.toString.call(ctor))
+      ) {
+        return false;
+      }
     }
     proto = Object.getPrototypeOf(proto);
   }
-  return 2;
+  return true;
 }
 
-function throwIfTypeNotCloneable(cloneableType) {
-  if (cloneableType === 0) {
-    throw new Error(
-      'Only plain objects, arrays, and class instances ' +
-      'can be cloned. Primitives, functions, and built-ins ' +
-      'are unsupported.',
-    );
+function printConstructor(object) {
+  const ctor = object.constructor;
+  switch (typeof ctor) {
+    case 'function':
+      return ctor.name;
+    case 'object':
+      return Object.prototype.toString.call(ctor);
+    default:
+      return '[primitive constructor]';
   }
 }
 
@@ -68,120 +71,50 @@ function restoreDescriptors(copy, changedDescriptors) {
   }
 }
 
-function clone(source, callbacks) {
-  const cloneableType = getCloneableType(source);
-  throwIfTypeNotCloneable(cloneableType);
-  if (cloneableType === 1) {
-    return source;
-  }
-  const proto = Object.getPrototypeOf(source);
-  let changedDescriptors = [];
-  let copy;
-  if (Array.isArray(source)) {
-    copy = Reflect.construct(Array, source, proto.constructor);
-  } else {
-    copy = Object.create(proto);
-  }
-  const ownKeys = Reflect.ownKeys(source);
-  for (let i = 0; i < ownKeys.length; i++) {
-    const key = ownKeys[i];
-    const descriptor = Object.getOwnPropertyDescriptor(source, key);
-    let origDesc;
-    if (descriptor.configurable === false) {
-      descriptor.configurable = true;
-      origDesc = {configurable: false};
-    }
-    if (descriptor.writable === false) {
-      descriptor.writable = true;
-      origDesc = {...origDesc, writable: false};
-    }
-    if (origDesc) {
-      changedDescriptors.push([key, origDesc]);
-    }
-    Reflect.defineProperty(copy, key, descriptor);
-  }
-  if (changedDescriptors.length) {
-    callbacks.push({
-      func: restoreDescriptors,
-      args: [copy, changedDescriptors],
-    });
-  }
-  if (Object.isFrozen(source)) {
-    callbacks.push({
-      func: Object.freeze,
-      args: [copy],
-    });
-  } else if (Object.isSealed(source)) {
-    callbacks.push({
-      func: Object.seal,
-      args: [copy],
-    });
-  } else if (!Object.isExtensible(source)) {
-    callbacks.push({
-      func: Object.preventExtensions,
-      args: [copy],
-    });
-  }
-  return copy;
-}
-
 export class CowContext {
   constructor(source, prop, parent) {
     this._source = source;
     this._prop = prop;
     this._parent = parent;
-    this._callbacks = [];
     this._result = null;
     this._status = STATUS_NONE;
     this._children = null;
   }
 
-  _copyForWrite() {
-    const status = this._status;
-    if (
-      status === STATUS_CHANGED ||
-      status === STATUS_REVOKED
-    ) {
+  _copyForWrite(forceObject) {
+    if (this._status === STATUS_MUTABLE || this._status === STATUS_REVOKED) {
       return;
     }
-    const stack = [];
-    let parent = this;
-    while (parent && parent._status !== STATUS_CHANGED) {
-      stack.push(parent);
-      parent = parent._parent;
-    }
-    for (let i = stack.length - 1; i >= 0; i--) {
-      const context = stack[i];
-      if (!context._result) {
-        context._result = clone(context._getSource(), context._callbacks);
-      }
-      if (context._parent) {
-        context._parent._result[context._prop] = context._result;
+    if (!this._result) {
+      const source = this._getSource();
+      if (isPrimitive(source)) {
+        this._result = forceObject ? {} : source;
+      } else if (!isCloneableObject(source)) {
+        throw new Error(
+          printConstructor(source) +
+          ' objects are not supported for cloning.',
+        );
+      } else {
+        this._result = this._cloneSourceObject(source);
       }
-      context._status = STATUS_CHANGED;
     }
+    const parent = this._parent;
+    if (parent) {
+      parent._copyForWrite(/* forceObject = */ true);
+      parent._result[this._prop] = this._result;
+    }
+    this._status = STATUS_MUTABLE;
   }
 
-  _getPropDescriptor(target, prop) {
-    const descriptor = Reflect.getOwnPropertyDescriptor(target, prop);
-    if (descriptor) {
-      if (descriptor.get) {
-        throw new Error('Getters are unsupported.');
-      }
-      if (descriptor.set) {
-        throw new Error('Setters are unsupported.');
-      }
-      return descriptor;
+  _cloneSourceObject(source) {
+    if (Array.isArray(source)) {
+      return source.slice();
     }
+    return {...source};
   }
 
   _getPropValue(prop) {
-    const target = this.read();
-    const descriptor = this._getPropDescriptor(target, prop);
-    if (descriptor) {
-      return descriptor.value;
-    }
-    return Reflect.get(target, prop);
+    return Reflect.get(this._read() ?? EMPTY_OBJECT, prop);
   }
 
   _getSource() {
@@ -204,14 +137,18 @@ export class CowContext {
     }
   }
 
+  _read() {
+    return this._status === STATUS_MUTABLE ? this._result : this._getSource();
+  }
+
   read() {
     this._throwIfRevoked();
-    return this._status === STATUS_CHANGED ? this._result : this._getSource();
+    return this._read();
   }
 
   write() {
     this._throwIfRevoked();
-    this._copyForWrite();
+    this._copyForWrite(/* forceObject = */ false);
     return this._result;
   }
 
@@ -229,12 +166,13 @@ export class CowContext {
       return child;
     }
 
-    child = new CowContext(value, prop, this);
+    child = new this.constructor(value, prop, this);
     children.set(prop, child);
     return child;
   }
 
   get(...props) {
+    this._throwIfRevoked();
     let ctx = this;
     for (const prop of props) {
       ctx = ctx._get(prop);
@@ -245,45 +183,67 @@ export class CowContext {
   _replace(value) {
     const parent = this._parent;
     if (parent) {
-      parent.set(this._prop, value);
+      parent._setIfChanged(this._prop, value);
     } else {
       this._source = value;
+      this._status = STATUS_NONE;
+      this._result = null;
+      // Child source values must be invalidated, because they can
+      // reference a previous copy we made.
+      this._setAllChildrenAsStale();
     }
   }
 
   _set(prop, newValue) {
-    const descriptor = this._getPropDescriptor(this.read(), prop);
-    if (descriptor === undefined || !Object.is(descriptor.value, newValue)) {
-      this._copyForWrite();
-      this._result[prop] = newValue;
-
-      // Child source values must be invalidated, because they can
-      // reference a previous copy we made.
-      const children = this._children;
-      if (children) {
-        const child = children.get(prop);
-        if (child) {
-          child._source = null;
-          child._callbacks = [];
-          child._result = null;
-          child._status = STATUS_STALE;
-        }
+    this._copyForWrite(/* forceObject = */ true);
+    this._result[prop] = newValue;
+
+    // Child source values must be invalidated, because they can
+    // reference a previous copy we made.
+    const children = this._children;
+    if (children) {
+      const child = children.get(prop);
+      if (child) {
+        child._setStale();
       }
     }
+  }
 
-    return this;
+  _setIfChanged(prop, newValue) {
+    const object = this._read() ?? EMPTY_OBJECT;
+    if (
+      !Object.hasOwn(object, prop) ||
+      !Object.is(Reflect.get(object, prop), newValue)
+    ) {
+      this._set(prop, newValue);
+    }
+  }
+
+  _setStale() {
+    this._source = null;
+    this._result = null;
+    this._status = STATUS_STALE;
+    this._setAllChildrenAsStale();
+  }
+
+  _setAllChildrenAsStale() {
+    const children = this._children;
+    if (children) {
+      for (const child of children.values()) {
+        child._setStale();
+      }
+    }
   }
 
   set(...args) {
-    this._throwIfRevoked();
     const newValue = args.pop();
     const hasProps = args.length > 0;
-    const lastProp = hasProps ? args.pop() : undefined;
-    const ctx = hasProps ? this.get(...args) : this;
     if (hasProps) {
-      ctx._set(lastProp, newValue);
+      const lastProp = args.pop();
+      this.get(...args)._setIfChanged(lastProp, newValue);
     } else {
-      ctx._replace(newValue);
+      this._throwIfRevoked();
+      this._replace(newValue);
     }
     return this;
   }
@@ -294,6 +254,21 @@ export class CowContext {
     return this;
   }
 
+  dangerouslySetAsMutable() {
+    this._throwIfRevoked();
+    const source = this._getSource();
+    // N.B. This may be (dangerously) equal to `source`.
+    const mutableValue = this._read();
+    const parent = this._parent;
+    if (parent) {
+      parent._set(this._prop, mutableValue);
+    }
+    this._source = source;
+    this._result = mutableValue;
+    this._status = STATUS_MUTABLE;
+    this._setAllChildrenAsStale();
+  }
+
   parent() {
     this._throwIfRevoked();
     return this._parent;
@@ -308,27 +283,31 @@ export class CowContext {
     return root;
   }
 
-  revoke() {
+  _revoke(recursive) {
     if (this.isRevoked()) {
       return;
     }
     if (this._parent) {
       this._parent._children.delete(this._prop);
     }
-    if (this._children) {
-      for (const child of this._children.values()) {
-        child.revoke();
+    if (recursive && this._children) {
+      const childrenToRevoke = [...this._children.values()];
+      for (const child of childrenToRevoke) {
+        child._revoke(true);
       }
-      this._children = null;
     }
+    this._children = null;
     this._source = null;
     this._prop = null;
     this._parent = null;
-    this._callbacks = null;
     this._result = null;
     this._status = STATUS_REVOKED;
   }
 
+  revoke() {
+    this._revoke(/* recursive = */ true);
+  }
+
   isRevoked() {
     return this._status === STATUS_REVOKED;
   }
@@ -336,17 +315,13 @@ export class CowContext {
   final() {
     this._throwIfRevoked();
     if (this._children) {
-      for (const child of this._children.values()) {
+      const childrenToFinalize = [...this._children.values()];
+      for (const child of childrenToFinalize) {
         child.final();
       }
     }
-    const result = this.read();
-    const callbacks = this._callbacks;
-    this.revoke();
-    for (let i = 0; i < callbacks.length; i++) {
-      const {func, args} = callbacks[i];
-      func(...args);
-    }
+    const result = this._read();
+    this._revoke(/* recursive = */ false);
     return result;
   }
 
@@ -355,7 +330,106 @@ export class CowContext {
   }
 }
 
-export default function mutate(source) {
-  throwIfTypeNotCloneable(getCloneableType(source));
-  return new CowContext(source, null, null);
+class CowContextStrict extends CowContext {
+  constructor(source, prop, parent) {
+    super(source, prop, parent);
+    this._callbacks = null;
+  }
+
+  _replace(value) {
+    super._replace(value);
+    if (!this._parent) {
+      this._callbacks = null;
+    }
+  }
+
+  _setStale() {
+    super._setStale();
+    this._callbacks = null;
+  }
+
+  _cloneSourceObject(source) {
+    if (!this._callbacks) {
+      this._callbacks = [];
+    }
+    const proto = Object.getPrototypeOf(source);
+    let changedDescriptors = [];
+    let copy;
+    if (Array.isArray(source)) {
+      copy = Reflect.construct(Array, source, proto.constructor);
+    } else {
+      copy = Object.create(proto);
+    }
+    const ownKeys = Reflect.ownKeys(source);
+    for (let i = 0; i < ownKeys.length; i++) {
+      const key = ownKeys[i];
+      const descriptor = Object.getOwnPropertyDescriptor(source, key);
+      let origDesc;
+      if (descriptor.configurable === false) {
+        descriptor.configurable = true;
+        origDesc = {configurable: false};
+      }
+      if (descriptor.writable === false) {
+        descriptor.writable = true;
+        origDesc = {...origDesc, writable: false};
+      }
+      if (origDesc) {
+        changedDescriptors.push([key, origDesc]);
+      }
+      Reflect.defineProperty(copy, key, descriptor);
+    }
+    if (changedDescriptors.length) {
+      this._callbacks.push({
+        func: restoreDescriptors,
+        args: [copy, changedDescriptors],
+      });
+    }
+    if (Object.isFrozen(source)) {
+      this._callbacks.push({
+        func: Object.freeze,
+        args: [copy],
+      });
+    } else if (Object.isSealed(source)) {
+      this._callbacks.push({
+        func: Object.seal,
+        args: [copy],
+      });
+    } else if (!Object.isExtensible(source)) {
+      this._callbacks.push({
+        func: Object.preventExtensions,
+        args: [copy],
+      });
+    }
+    return copy;
+  }
+
+  dangerouslySetAsMutable() {
+    super.dangerouslySetAsMutable();
+    this._callbacks = null;
+  }
+
+  revoke() {
+    super.revoke();
+    this._callbacks = null;
+  }
+
+  final() {
+    const callbacks = this._callbacks;
+    const result = super.final();
+    if (callbacks) {
+      for (let i = 0; i < callbacks.length; i++) {
+        const {func, args} = callbacks[i];
+        func(...args);
+      }
+    }
+    return result;
+  }
+}
+
+export default function mutate(source, strict = false) {
+  if (strict) {
+    return new CowContextStrict(source, null, null);
+  } else {
+    return new CowContext(source, null, null);
+  }
 }

package/src/index.js.flow

@@ -101,6 +101,7 @@ declare export class CowContext<
   update<const K1: KeyType<T>, const K2: KeyType2<T, K1>, const K3: KeyType3<T, K1, K2>, const K4: KeyType4<T, K1, K2, K3>, const K5: KeyType5<T, K1, K2, K3, K4>, const K6: KeyType6<T, K1, K2, K3, K4, K5>>(prop1: K1, prop2: K2, prop3: K3, prop4: K4, prop5: K5, prop6: K6, updater: ($Get6<T, K1, K2, K3, K4, K5, K6, this>) => mixed): this;
   update<const K1: KeyType<T>, const K2: KeyType2<T, K1>, const K3: KeyType3<T, K1, K2>, const K4: KeyType4<T, K1, K2, K3>, const K5: KeyType5<T, K1, K2, K3, K4>, const K6: KeyType6<T, K1, K2, K3, K4, K5>, const K7: KeyType7<T, K1, K2, K3, K4, K5, K6>>(prop1: K1, prop2: K2, prop3: K3, prop4: K4, prop5: K5, prop6: K6, prop7: K7, updater: ($Get7<T, K1, K2, K3, K4, K5, K6, K7, this>) => mixed): this;
   update<const K1: KeyType<T>, const K2: KeyType2<T, K1>, const K3: KeyType3<T, K1, K2>, const K4: KeyType4<T, K1, K2, K3>, const K5: KeyType5<T, K1, K2, K3, K4>, const K6: KeyType6<T, K1, K2, K3, K4, K5>, const K7: KeyType7<T, K1, K2, K3, K4, K5, K6>, const K8: KeyType8<T, K1, K2, K3, K4, K5, K6, K7>>(prop1: K1, prop2: K2, prop3: K3, prop4: K4, prop5: K5, prop6: K6, prop7: K7, prop8: K8, updater: ($Get8<T, K1, K2, K3, K4, K5, K6, K7, K8, this>) => mixed): this;
+  dangerouslySetAsMutable(): void;
   parent(): ParentContext;
   root(): GetCowContextRoot<this>;
   revoke(): void;
@@ -111,4 +112,5 @@ declare export class CowContext<
 
 declare export default function mutate<T>(
   source: T,
+  strict?: boolean,
 ): CowRootContext<T>;

package/types/index.d.ts

@@ -45,6 +45,7 @@ declare class CowContext<
   get<Path extends ReadonlyArray<PropertyKey>>(...path: Path): NestedContext<T, ParentContext, Path>;
   set<Path extends ReadonlyArray<PropertyKey>>(...args: [...Path, NestedProp<T, Path>]): this;
   update<Path extends ReadonlyArray<PropertyKey>>(...args: [...Path, (childContext: NestedContext<T, ParentContext, Path>) => unknown]): this;
+  dangerouslySetAsMutable(): void;
   parent(): ParentContext;
   root(): GetCowContextRoot<this>;
   revoke(): void;
@@ -55,6 +56,7 @@ declare class CowContext<
 
 declare function mutate<T>(
   source: T,
+  strict?: boolean,
 ): CowRootContext<T>;
 
 export {CowRootContext, CowAnyContext, CowContext};