Overloaded API (#9)

Version 2.1.0:

* Alternative single-reference don't-make-me-think API, fixes #8
* Fix docs

README.md

@@ -6,23 +6,56 @@ Throw your rose-tinted [lenses](https://medium.com/javascript-inside/an-introduc
 
 # What
 
-Patchinko exposes 3 functions: `P`, `S`, & `PS`.
+Patchinko exposes 4 granular APIs: `P`, `S`, `PS`, & `D`.
 
 `P` is like `Object.assign`: given `P(target, input1, input2, etc)`, it consumes inputs left to right and copies their properties onto the supplied target
 
 *…except that…*
 
-If any target properties are instances of `S(function)`, it will supply the scoped function with the target property for that key, and assign the result back to the target; if any target properties are `D`, it will delete the property of the same key on the target.
+If any target properties are instances of `S(function)`, it will supply the scoped function with the target property for that key, and assign the result back to the target.
+
+If any target properties are `D`, it will delete the property of the same key on the target.
 
 `PS([ target, ] input)` is a composition of `P` & `S`, for when you need to patch recursively. If you supply a `target`, the original value will be left untouched (useful for immutable patching).
 
-# How
+***
 
-The kitchen sink example:
+Patchinko also comes with a don't-make-me-think single-reference overloaded API - useful when the essential patching operations are intuitive but the different API invocations are cognitively overbearing to determine or noisy to read.
+
+`O` is an overloaded API that subsumes the above (with the exception of the n-ary immutable `PS` overload):
+
+1. No arguments stands in for `D`.
+2. A function argument stands in for `S`.
+3. A non-function single argument stands in for `PS`.
+4. …otherwise, `P`.
+
+# Where
+
+Supplied in CommonJS module format & as unscoped top-level references. Available on [npm](https://npmjs.org/package/patchinko) & [UNPKG cdn](https://unpkg.com/patchinko).
+
+In Node:
 
 ```js
 const {P, S, PS, D} = require('patchinko')
+// or
+const O = require('patchinko/overloaded')
+```
+
+In the browser:
 
+```html
+<script src=//unpkg.com/patchinko></script>
+<script>console.log({P, S, PS, D})</script>
+<!-- or -->
+<script src=//unpkg.com/patchinko/overloaded></script>
+<script>console.log({O})</script>
+```
+
+# How
+
+The kitchen sink example:
+
+```js
 // Some arbitrary structure
 const thing = {
   foo: 'bar',
@@ -35,7 +68,7 @@ const thing = {
     mean: (...set) =>
       set.reduce((a, b) => a + b) / set.length,
 
-    fibonacci: function(x) {
+    fibonacci(x){
       return x <= 1 ? x : this.fibonacci(x - 1) + this.fibonacci(x - 2)
     },
   },
@@ -55,14 +88,14 @@ P(thing, {
   bish: D, // Delete property `bish`
 
   utils: PS({ // We want to patch a level deeper
-    fibonacci: S(function closure(definition){ // Memoize `fibonacci`
-      var cache = {}
+    fibonacci: S(fibonacci => { // Memoize `fibonacci`
+      const cache = {}
 
-      return function override(x){
+      return function(x){
         return (
           x in cache
           ? cache[x]
-          : cache[x] = definition.apply(this, arguments)
+          : cache[x] = fibonacci.call(this, x)
         )
       }
     })
@@ -90,6 +123,46 @@ Observe that:
 
 `stupidly.deep.stucture` & `utils.fibonacci` show that any kind of structure can be modified or replaced at any kind of depth: `P` is geared towards the common case of objects, but `S` can deal with any type in whatever way necessary. You get closures for free so gnarly patch logic can be isolated at the point where it makes the most sense.
 
+***
+
+Using the overloaded API, the same results are achieved as follows:
+
+```js
+const O = require('patchinko/overloaded')
+
+O(thing, {
+  foo: 'baz',
+
+  bish: O,
+
+  utils: O({
+    fibonacci: O(fibonacci => {
+      const cache = {}
+
+      return function(x){
+        return (
+          x in cache
+          ? cache[x]
+          : cache[x] = fibonacci.call(this, x)
+        )
+      }
+    })
+  }),
+
+  stupidly: O({
+    deep: O({
+      structure: O(structure =>
+        structure.concat('roflmao')
+      )
+    }),
+    with: O(structure =>
+      O([], structure, {1: 'copy'}) // [1]
+    )
+  })
+})
+```
+
+[1️] The single-API overload forbids the immutable `PS` overload because more than 1 argument will necessarily fork to `P`. Thus immutable nested structure patching with `O` requires 2 invocations, 1 forking to `S` and the 2nd to `P`.
 
 # Why
 

index.js

@@ -2,7 +2,7 @@ function P(target){
   for(var i = 1; i < arguments.length; i++)
     for(var key in arguments[i])
       if(arguments[i].hasOwnProperty(key))
-        arguments[i][key] == D
+        arguments[i][key] === D
         ? delete target[key]
         : target[key] =
           arguments[i][key] instanceof S
@@ -35,6 +35,16 @@ function PS(target, input){
 
 function D(){}
 
+function O(x){
+  return arguments.length
+    ? 1 < arguments.length
+      ? P.apply(arguments)
+      : typeof x === 'function'
+        ? new S(x)
+        : PS(x)
+    : D
+}
+
 try {
-  module.exports = {P: P, S: S, PS: PS, D: D}
+  module.exports = {P: P, S: S, PS: PS, D: D, O: O}
 } catch(e) {}

overloaded.js

@@ -0,0 +1,34 @@
+function O(a, b){
+  if(arguments.length == 1)
+    if(typeof a == 'function')
+      if(!(this instanceof O))
+        return new O(a)
+
+      else
+        this.apply = function(c){
+          return a(c)
+        }
+
+    else
+      return new O(function(c){
+        return O(c, a)
+      })
+
+  else {
+    for(var i = 1; i < arguments.length; i++, b = arguments[i])
+      for(var key in b)
+        if(b.hasOwnProperty(key))
+          b[key] == O
+          ? delete a[key]
+          : a[key] =
+            b[key] instanceof O
+            ? b[key].apply(a[key])
+            : b[key]
+
+    return a
+  }
+}
+
+try {
+  module.exports = O
+} catch(e) {}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchinko",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Concise monkey-patching utility",
   "main": "index.js",
   "repository": "git@github.com:barneycarroll/patchinko.git",

tests/index.js

@@ -30,8 +30,8 @@ o.spec('`P`', () => {
 
   o('is equivalent to `Object.assign` in the absence of `S`', () => {
     const [factoryA, factoryB] = [
-      () => ({a:'foo', b:2, d: {bar:  'z'}, f: [3, 4]}),
-      () => ({a:'baz', c:3, d: {fizz: 'z'}, f: 'buzz'}),
+      () => ({a: 'foo', b: 2, d: {bar:  'z'}, f: [3, 4]}),
+      () => ({a: 'baz', c: 3, d: {fizz: 'z'}, f: 'buzz'}),
     ]
 
     const [a, b] = [factoryA(), factoryB()]
@@ -52,7 +52,7 @@ o.spec('`P`', () => {
   })
 
   o.spec('with `S`', () => {
-    o('supplies the target\'s property value to the scoped function', () => {
+    o("supplies the target's property value to the scoped function", () => {
       const unique = Symbol('unicum')
 
       let interception
@@ -75,58 +75,35 @@ o.spec('`P`', () => {
 
       o(
         P(
-          { a: unique1 },
+          { a: unique1 }, 
           { a: S(I) }
         ).a
       ).equals(
         unique1
-        )
+      )
 
       o(
         P(
-          { a: unique1 },
+          { a: unique1 }, 
           { a: S(() => unique2) }
         ).a
       ).equals(
         unique2
-        )
+      )
     })
   })
 
   o.spec('with `D`', () => {
     o('deletes the target property with the same key', () => {
       o(
         P(
-          { a: 1, b: 2 },
+          { a: 1, b: 2 }, 
           { a: D }
         )
       ).deepEquals(
         { b: 2 }
       )
     })
-
-    o('assigns the product of any scoped closures to the target properties', () => {
-      const unique1 = Symbol('unicum1')
-      const unique2 = Symbol('unicum2')
-
-      o(
-        P(
-          { a: unique1 },
-          { a: S(I) }
-        ).a
-      ).equals(
-        unique1
-        )
-
-      o(
-        P(
-          { a: unique1 },
-          { a: S(() => unique2) }
-        ).a
-      ).equals(
-        unique2
-        )
-    })
   })
 })
 
@@ -155,17 +132,17 @@ o.spec('`PS`', () => {
           })
         }
       )
-    )
-      .deepEquals(
-        {
-          a: {
-            b: two
-          }
+    ).deepEquals(
+      {
+        a: {
+          b: two
         }
-      )
+      }
+    )
 
     o(interception).equals(one)
   })
+
   o('accepts a custom target', () => {
     o(
       P(
@@ -174,7 +151,7 @@ o.spec('`PS`', () => {
         },
         {
           a: PS(
-            [],
+            [], 
             {
               1: 3
             }