mutate-cow 4.1.0 → 5.0.0

package/CowContext.mjs

@@ -0,0 +1,238 @@
+/*
+ * Copyright (c) 2023 Michael Wiencek
+ *
+ * This source code is licensed under the MIT license. A copy can be found
+ * in the file named "LICENSE" at the root directory of this distribution.
+ */
+
+import clone from './clone.mjs';
+import {
+  STATUS_CHANGED,
+  STATUS_NONE,
+  STATUS_REVOKED,
+} from './constants.mjs';
+
+const STALE_VALUE = Object.freeze(Object.create(null));
+
+export default class CowContext {
+  constructor(source, prop, root, parent) {
+    this._source = source;
+    this._prop = prop;
+    this._root = root || this;
+    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
+    ) {
+      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;
+      }
+      context._status = STATUS_CHANGED;
+    }
+  }
+
+  _getPropValue(prop) {
+    const target = this.read();
+    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.value;
+    }
+    return Reflect.get(target, prop);
+  }
+
+  _getSource() {
+    let source = this._source;
+    if (source === STALE_VALUE) {
+      /*
+       * `this._parent` should always be defined here, because we only
+       * ever assign `STALE_VALUE` onto child contexts.
+       */
+      source = this._parent._getPropValue(this._prop);
+      this._source = source;
+    }
+    return source;
+  }
+
+  _throwIfRevoked() {
+    if (this.isRevoked()) {
+      throw new Error(
+        'This context has been revoked and can no longer be used.',
+      );
+    }
+  }
+
+  read() {
+    this._throwIfRevoked();
+    return this._status === STATUS_CHANGED ? this._result : this._getSource();
+  }
+
+  write() {
+    this._throwIfRevoked();
+    this._copyForWrite();
+    return this._result;
+  }
+
+  _get(prop) {
+    const value = this._getPropValue(prop);
+
+    let children = this._children;
+    if (!children) {
+      children = new Map();
+      this._children = children;
+    }
+
+    let child = children.get(prop);
+    if (child) {
+      return child;
+    }
+
+    child = new CowContext(value, prop, this._root, this);
+    children.set(prop, child);
+    return child;
+  }
+
+  get(...props) {
+    let ctx = this;
+    for (const prop of props) {
+      ctx = ctx._get(prop);
+    }
+    return ctx;
+  }
+
+  _replace(value) {
+    const parent = this._parent;
+    if (parent) {
+      parent.set(this._prop, value);
+    } else {
+      this._source = value;
+    }
+  }
+
+  _set(prop, newValue) {
+    const origValue = this._getPropValue(prop);
+
+    if (!Object.is(origValue, 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 = STALE_VALUE;
+          child._callbacks = [];
+          child._result = null;
+          child._status = STATUS_NONE;
+        }
+      }
+    }
+
+    return this;
+  }
+
+  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);
+    } else {
+      ctx._replace(newValue);
+    }
+    return this;
+  }
+
+  update(...args) {
+    const updater = args.pop();
+    updater(this.get(...args));
+    return this;
+  }
+
+  parent() {
+    this._throwIfRevoked();
+    return this._parent;
+  }
+
+  root() {
+    this._throwIfRevoked();
+    return this._root;
+  }
+
+  revoke() {
+    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();
+      }
+      this._children = null;
+    }
+    this._source = null;
+    this._prop = null;
+    this._root = null;
+    this._parent = null;
+    this._callbacks = null;
+    this._result = null;
+    this._status = STATUS_REVOKED;
+  }
+
+  isRevoked() {
+    return this._status === STATUS_REVOKED;
+  }
+
+  final() {
+    this._throwIfRevoked();
+    if (this._children) {
+      for (const child of this._children.values()) {
+        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);
+    }
+    return result;
+  }
+
+  finalRoot() {
+    return this.root().final();
+  }
+}

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2019 Michael Wiencek
+Copyright (c) 2023 Michael Wiencek
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -3,90 +3,141 @@
 ```JavaScript
 import mutate from 'mutate-cow';
 
-const animals = Object.freeze({
-  cats: Object.freeze(['ragamuffin', 'shorthair', 'maine coon']),
+const animals = deepFreeze({
+  cats: ['ragamuffin', 'shorthair', 'maine coon'],
 });
 
-const newAnimals = mutate(animals, copy => {
-  copy.cats.push('bobtail');
-  copy.dogs = Object.freeze(['hound']);
-});
+const newAnimals = mutate(animals)
+  .set('dogs', ['hound'])
+  .update('cats', (ctx) => {
+    ctx.write().push('bobtail');
+  })
+  .final();
 ```
 
-This module allows you to update an immutable object as if it were mutable, inside a callback. 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.
-
-It's implemented using [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) objects, so browser support for that is required.
+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.
 
-While this doesn't appear to have been an original idea, I believe `mutate-cow` provides useful features that other packages don't:
+`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. (Inside the callback, of course, the working copy in unsealed and all properties are writable.)
- * Getters and setters from the immutable object can be used inside the callback, and are preserved in the copy; they aren't converted from accessors to writables.
- * Arrays, objects, and class instances are supported for mutation. Inside the callback, these have the correct identities when passed to `Array.isArray` or `instanceof`.
- * Usable Flow types are provided. (The first type parameter must be a non-read-only variant of the input type.)
-
-For usage, please see [the tests](test.mjs).
+ * 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.
 
-## Caveats
+## API
 
-This module works for mutating plain objects, arrays, and user-defined classes. (Note, however, that class constructors are not called.) Other native, built-in object types are not supported for a variety reasons. For one, many of them can't be proxied correctly, because their methods aren't generic; i.e., they can't be called with a `this` value that's not of the exact object type. Another reason is that we'd need specialized code to clone each different type; they can't be created with `Object.create`, as the constructor must be called to define internal slots. We'd need further specialized code to intercept any methods that can write to any internal slots. That's just not feasible.
+### const ctx = mutate(source)
 
-Note that there's nothing wrong with creating *new* instances of these objects inside the callback and assigning them to properties. It's perfectly fine to clone them yourself. What's unsupported is mutating any existing objects of these types.
+Returns a "context" object which can modify a copy of `source`.
 
-```JavaScript
-const orig = {
-  date: new Date(),
-  string: new String('hello'),
-};
-
-mutate(orig, copy => {
-  // These are unsupported, and will throw TypeErrors.
-  copy.date.setFullYear(1999);
-  copy.date.customProp = 'y';
-  copy.string[0] = 'y';
-
-  // These are fine.
-  const newDate = new Date(orig.date.valueOf());
-  newDate.setFullYear(1999);
-  newDate.customProp = 'y';
-  copy.date = newDate;
-  copy.string = new String('yello');
-});
+```js
+const foo = deepFreeze({bar: {baz: []}});
+const ctx = mutate(foo);
+````
+
+### ctx.read()
+
+Returns the current working copy of the context's `source` object, or just `source` if no changes were made.
+
+```js
+ctx.read() === foo; // no changes
+ctx.set('bar', 'baz', ['qux']);
+ctx.read().bar.baz[0] === 'qux'; // changes
 ```
 
-### Unwrapping proxied values
+### ctx.write()
 
-When you read from a property inside the callback, a `Proxy` is returned that can read from the source object (or working copy) and write to the copy. You may then wonder what happens if you perform `copy.foo = copy.bar`: will this assign a `Proxy`, or the value it targets? The answer in this case is the value it targets, because `mutate-cow` automatically unwraps proxied values on the RHS of assignments. However, suppose you did something like this instead:
+Returns the current working copy of the context's `source` object. Makes a shallow copy of `source` first if no changes were made.
 
-```JavaScript
-const orig = {foo: {value: 1}, bar: {value: 2}};
+You normally don't need to call `write`. It's mainly useful for accessing methods on copied objects (e.g., array methods).
 
-const copy = mutate(orig, copy => {
-  // this will assign an object resembling {value: Proxy}!
-  copy.foo = {...copy.bar};
-});
+```js
+ctx.get('bar', 'baz').write().push('qux');
+ctx.read().bar.baz[0] === 'qux';
 ```
 
-In the above case, `copy.bar.value` is a `Proxy`, but `{...copy.bar}` (the assigned object) is not. `mutate-cow` doesn't *deeply* unwrap values, so you have to do it yourself in this case:
+### ctx.get(...path: [prop1, ...])
 
-```JavaScript
-const orig = {foo: {value: 1}, bar: {value: 2}};
+Returns a child context object for the given `path`.
 
-const copy = mutate(orig, (copy, unwrap) => {
-  copy.foo = {...unwrap(copy.bar)};
-});
+Passing zero arguments returns `ctx`.
+
+```js
+ctx.get() === ctx;
+ctx.get('bar').read() === foo.bar;
+ctx.get('bar', 'baz').read() === '';
 ```
 
-If you don't do this, accessing `copy.foo.value` outside the callback will throw an error, because the `Proxy` will be revoked! An alternative which avoids this situation entirely is to just reference the source object where possible:
+### ctx.set(...path: [prop1, ...], value)
 
-```JavaScript
-const orig = {foo: {value: 1}, bar: {value: 2}};
+Sets the given `path` to `value` on the current working copy. Returns `ctx`.
 
-const copy = mutate(orig, copy => {
-  copy.foo = {...orig.bar};
-});
+Passing zero property names (i.e., only a value) sets the current context's value.
+
+```js
+// these all do the same thing
+ctx.set({bar: {baz: 2}});
+ctx.set('bar', {baz: 2});
+ctx.set('bar', 'baz', 2);
+ctx.get('bar').set({baz: 2});
+ctx.get('bar').set('baz', 2);
+ctx.get('bar', 'baz').set(2);
 ```
 
-In fact, all `unwrap` does is return the underlying data from the source, or the working copy where you've made changes.
+### ctx.update(...path: [prop1, ...], updater)
+
+Calls `updater(ctx.get(...path))` and returns `ctx`.
+
+```js
+const copy = ctx
+  .update('bar', 'baz', (bazCtx) => {
+    bazCtx.write().push('qux');
+  })
+  .final();
+copy.bar.baz[0] === 'qux';
+````
+
+### ctx.parent()
+
+Returns the parent context of `ctx`.
+
+```js
+ctx.parent() === null;
+ctx.get('bar').parent() === ctx;
+ctx.get('bar', 'baz').parent() === ctx.get('bar');
+````
+
+### ctx.root()
+
+Returns the root context of `ctx`.
+
+```js
+ctx.root() === ctx;
+ctx.get('bar').root() === ctx;
+ctx.get('bar', 'baz').root() === ctx;
+````
+
+### ctx.revoke()
+
+Revokes `ctx` so that it can no longer be used. Returns `undefined`.
+
+Attempting to use any method other than `isRevoked` on a revoked context will throw an error. This sets all internal properties to `null` so that there's no longer any reference to the `source` object or copy.
+
+### ctx.isRevoked()
+
+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.
+
+```js
+const copy = mutate(foo).set('bar', 'baz', 'qux').final();
+Object.isFrozen(copy) === true; // since `foo` was frozen, `copy` will be too
+````
+
+### ctx.finalRoot()
+
+Returns `ctx.root().final()`.

package/bench.mjs

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019 Michael Wiencek
+ * Copyright (c) 2023 Michael Wiencek
  *
  * This source code is licensed under the MIT license. A copy can be found
  * in the file named "LICENSE" at the root directory of this distribution.
@@ -15,21 +15,52 @@ for (let i = 65, next = root; i <= 90; i++) {
     prop2: 2,
     prop3: 3,
     prop4: 4,
-    prop4: 5,
+    prop5: 5,
   };
 }
 
-const updater1 = (newRoot) => {
-  newRoot.root = true;
+const updater1 = () => {
+  mutate(root).set('root', true).final();
 };
 
-const updater2 = (newRoot) => {
-  newRoot.A.B.C.D.E.F.G.H.I.J.K.L.M.N.O.P.Q.R.S.T.U.V.W.X.Y.Z.leaf = true;
+const updater2 = () => {
+  mutate(root)
+    .set(
+      'A',
+      'B',
+      'C',
+      'D',
+      'E',
+      'F',
+      'G',
+      'H',
+      'I',
+      'J',
+      'K',
+      'L',
+      'M',
+      'N',
+      'O',
+      'P',
+      'Q',
+      'R',
+      'S',
+      'T',
+      'U',
+      'V',
+      'W',
+      'X',
+      'Y',
+      'Z',
+      'leaf',
+      true,
+    )
+    .final();
 };
 
 function test() {
-  mutate(root, updater1); // shallow update
-  mutate(root, updater2); // deep update
+  updater1(); // shallow update
+  updater2(); // deep update
 }
 
 new Benchmark.Suite()

package/canClone.mjs

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019 Michael Wiencek
+ * Copyright (c) 2023 Michael Wiencek
  *
  * This source code is licensed under the MIT license. A copy can be found
  * in the file named "LICENSE" at the root directory of this distribution.
@@ -9,14 +9,20 @@ const funcToString = Function.prototype.toString;
 
 const nativeCodeRegExp = /^function \w*\(\) \{\s*\[native code\]\s*\}$/m;
 
+export const CANNOT_CLONE_ERROR =
+  'Only plain objects, arrays, and class instances ' +
+  'can be cloned. Primitives, functions, and built-ins ' +
+  'are unsupported.';
+
 export default function canClone(object) {
   if (!object || typeof object !== 'object') {
-    return false;
+    throw new Error(CANNOT_CLONE_ERROR);
   }
 
   let proto = Reflect.getPrototypeOf(object);
+
   while (proto) {
-    const ctor = proto.constructor;
+    let ctor = proto.constructor;
     // A Generator object's constructor is an object.
     if (ctor && typeof ctor === 'object') {
       ctor = ctor.constructor;
@@ -26,11 +32,9 @@ export default function canClone(object) {
         ctor.name !== 'Array' &&
         ctor.name !== 'Object' &&
         nativeCodeRegExp.test(funcToString.call(ctor))) {
-      return false;
+      throw new Error(CANNOT_CLONE_ERROR);
     }
 
     proto = Reflect.getPrototypeOf(proto);
   }
-
-  return true;
 }

package/clone.mjs

@@ -1,28 +1,47 @@
 /*
- * Copyright (c) 2019 Michael Wiencek
+ * Copyright (c) 2023 Michael Wiencek
  *
  * This source code is licensed under the MIT license. A copy can be found
  * in the file named "LICENSE" at the root directory of this distribution.
  */
 
+import canClone from './canClone.mjs';
 import {
   NON_CONFIGURABLE,
   NON_CONFIGURABLE_AND_WRITABLE,
   NON_WRITABLE,
 } from './constants.mjs';
 
+function isPrimitive(value) {
+  switch (typeof value) {
+    case 'bigint':
+    case 'boolean':
+    case 'number':
+    case 'string':
+    case 'symbol':
+    case 'undefined':
+      return true;
+    default:
+      return value === null;
+  }
+}
+
 function restoreDescriptors(copy, changedDescriptors) {
   for (let i = 0; i < changedDescriptors.length; i++) {
     const [name, origDesc] = changedDescriptors[i];
-    const desc = Reflect.getOwnPropertyDescriptor(copy, name);
-    if (desc) {
-      Object.assign(desc, origDesc);
-      Reflect.defineProperty(copy, name, desc);
+    const descriptor = Reflect.getOwnPropertyDescriptor(copy, name);
+    if (descriptor) {
+      Object.assign(descriptor, origDesc);
+      Reflect.defineProperty(copy, name, descriptor);
     }
   }
 }
 
 export default function clone(source, callbacks) {
+  if (isPrimitive(source)) {
+    return source;
+  }
+  canClone(source);
   let changedDescriptors;
   let copy;
   if (Array.isArray(source)) {
@@ -33,15 +52,15 @@ export default function clone(source, callbacks) {
   const ownNames = Object.getOwnPropertyNames(source);
   for (let i = 0; i < ownNames.length; i++) {
     const name = ownNames[i];
-    const desc = Reflect.getOwnPropertyDescriptor(source, name);
-    const nonConfigurable = desc.configurable === false;
+    const descriptor = Reflect.getOwnPropertyDescriptor(source, name);
+    const nonConfigurable = descriptor.configurable === false;
     let origDesc;
     if (nonConfigurable) {
-      desc.configurable = true;
+      descriptor.configurable = true;
       origDesc = NON_CONFIGURABLE;
     }
-    if (desc.writable === false) {
-      desc.writable = true;
+    if (descriptor.writable === false) {
+      descriptor.writable = true;
       origDesc = nonConfigurable
         ? NON_CONFIGURABLE_AND_WRITABLE
         : NON_WRITABLE;
@@ -52,13 +71,29 @@ export default function clone(source, callbacks) {
       }
       changedDescriptors.push([name, origDesc]);
     }
-    Reflect.defineProperty(copy, name, desc);
+    Reflect.defineProperty(copy, name, descriptor);
   }
   if (changedDescriptors) {
-    callbacks.push([restoreDescriptors, copy, changedDescriptors]);
+    callbacks.push({
+      func: restoreDescriptors,
+      args: [copy, changedDescriptors],
+    });
   }
-  if (!Reflect.isExtensible(source)) {
-    callbacks.push([Reflect.preventExtensions, copy]);
+  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 (!Reflect.isExtensible(source)) {
+    callbacks.push({
+      func: Reflect.preventExtensions,
+      args: [copy],
+    });
   }
   return copy;
 }