mutate-cow 7.0.0 → 8.0.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.0",
+  "version": "8.0.0",
   "description": "Update immutable objects as if they were mutable with copy-on-write",
   "keywords": [
     "immutable",

package/src/index.js

@@ -8,7 +8,7 @@
 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,18 +20,18 @@ function isPrimitive(value) {
   return (type !== 'function' && type !== 'object');
 }
 
-function getCloneableType(value) {
-  if (isPrimitive(value)) {
-    return 1;
+function isCloneableObject(object) {
+  if (typeof object === 'function') {
+    return false;
   }
-  if (typeof value !== 'object') {
-    return 0;
-  }
-  let proto = Object.getPrototypeOf(value);
+  let proto = Object.getPrototypeOf(object);
   while (proto) {
     let ctor = proto.constructor;
+    if (!ctor) {
+      continue;
+    }
     // A Generator object's constructor is an object.
-    if (ctor && typeof ctor === 'object') {
+    if (typeof ctor === 'object') {
       ctor = ctor.constructor;
     }
     if (
@@ -40,20 +40,22 @@ function getCloneableType(value) {
       ctor.name !== 'Object' &&
       NATIVE_CODE_REGEXP.test(Function.prototype.toString.call(ctor))
     ) {
-      return 0;
+      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 '';
   }
 }
 
@@ -68,12 +70,34 @@ function restoreDescriptors(copy, changedDescriptors) {
   }
 }
 
-function clone(source, callbacks) {
-  const cloneableType = getCloneableType(source);
-  throwIfTypeNotCloneable(cloneableType);
-  if (cloneableType === 1) {
+function clone(context) {
+  const source = context._getSource();
+  if (isPrimitive(source)) {
     return source;
   }
+  if (!isCloneableObject(source)) {
+    throw new Error(
+      printConstructor(source) +
+      ' objects are not supported for cloning.',
+    );
+  }
+  if (context._strict) {
+    return cloneObjectStrict(source, context);
+  }
+  return cloneObjectLoose(source);
+}
+
+function cloneObjectLoose(source) {
+  if (Array.isArray(source)) {
+    return source.slice();
+  }
+  return {...source};
+}
+
+function cloneObjectStrict(source, context) {
+  if (!context._callbacks) {
+    context._callbacks = [];
+  }
   const proto = Object.getPrototypeOf(source);
   let changedDescriptors = [];
   let copy;
@@ -101,23 +125,23 @@ function clone(source, callbacks) {
     Reflect.defineProperty(copy, key, descriptor);
   }
   if (changedDescriptors.length) {
-    callbacks.push({
+    context._callbacks.push({
       func: restoreDescriptors,
       args: [copy, changedDescriptors],
     });
   }
   if (Object.isFrozen(source)) {
-    callbacks.push({
+    context._callbacks.push({
       func: Object.freeze,
       args: [copy],
     });
   } else if (Object.isSealed(source)) {
-    callbacks.push({
+    context._callbacks.push({
       func: Object.seal,
       args: [copy],
     });
   } else if (!Object.isExtensible(source)) {
-    callbacks.push({
+    context._callbacks.push({
       func: Object.preventExtensions,
       args: [copy],
     });
@@ -126,62 +150,45 @@ function clone(source, callbacks) {
 }
 
 export class CowContext {
-  constructor(source, prop, parent) {
+  constructor(source, prop, parent, strict = false) {
     this._source = source;
     this._prop = prop;
     this._parent = parent;
-    this._callbacks = [];
+    this._callbacks = null;
     this._result = null;
     this._status = STATUS_NONE;
     this._children = null;
+    this._strict = strict;
   }
 
   _copyForWrite() {
     const status = this._status;
     if (
-      status === STATUS_CHANGED ||
+      status === STATUS_MUTABLE ||
       status === STATUS_REVOKED
     ) {
       return;
     }
     const stack = [];
     let parent = this;
-    while (parent && parent._status !== STATUS_CHANGED) {
+    while (parent && parent._status !== STATUS_MUTABLE) {
       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);
+        context._result = clone(context);
       }
       if (context._parent) {
         context._parent._result[context._prop] = context._result;
       }
-      context._status = STATUS_CHANGED;
-    }
-  }
-
-  _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;
+      context._status = STATUS_MUTABLE;
     }
   }
 
   _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(), prop);
   }
 
   _getSource() {
@@ -204,9 +211,13 @@ 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() {
@@ -229,12 +240,13 @@ export class CowContext {
       return child;
     }
 
-    child = new CowContext(value, prop, this);
+    child = new CowContext(value, prop, this, this._strict);
     children.set(prop, child);
     return child;
   }
 
   get(...props) {
+    this._throwIfRevoked();
     let ctx = this;
     for (const prop of props) {
       ctx = ctx._get(prop);
@@ -245,45 +257,68 @@ 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._callbacks = null;
+      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();
+    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) {
+    if (
+      !Object.hasOwn(this._read(), prop) ||
+      !Object.is(this._getPropValue(prop), newValue)
+    ) {
+      this._set(prop, newValue);
+    }
+  }
+
+  _setStale() {
+    this._source = null;
+    this._callbacks = 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 +329,22 @@ 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._callbacks = null;
+    this._setAllChildrenAsStale();
+  }
+
   parent() {
     this._throwIfRevoked();
     return this._parent;
@@ -340,12 +391,14 @@ export class CowContext {
         child.final();
       }
     }
-    const result = this.read();
+    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);
+    if (callbacks) {
+      for (let i = 0; i < callbacks.length; i++) {
+        const {func, args} = callbacks[i];
+        func(...args);
+      }
     }
     return result;
   }
@@ -355,7 +408,6 @@ export class CowContext {
   }
 }
 
-export default function mutate(source) {
-  throwIfTypeNotCloneable(getCloneableType(source));
-  return new CowContext(source, null, null);
+export default function mutate(source, strict = false) {
+  return new CowContext(source, null, null, strict);
 }

package/src/index.js.flow

@@ -68,7 +68,7 @@ export type GetCowContextRoot<+C> =
     ? (P extends null ? C : GetCowContextRoot<P>)
     : empty;
 
-declare class CowContext<
+declare export class CowContext<
  +T,
  +ParentContext: CowAnyContext | null = CowAnyContext | null,
 >{
@@ -101,6 +101,7 @@ declare 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 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};