Added call to Transforms (#503)

* Added call method to Transforms to enable calling of custom transforms

* Fixed spacing

src/transforms/call.js

@@ -0,0 +1,31 @@
+/**
+ * Convenience method to call a custom transform function using easier to read
+ * syntax. A custom transform is a JavaScript function that takes a Transform
+ * instance as the first argument. Any additional arguments passed to the `call`
+ * method after the Transform instance are passed to the custom transform function.
+ *
+ * These are equivalent but the second is easier to read:
+ *
+ * ```js
+ * const transform = state.transform()
+ * myTransform(transform, 0, 1)
+ * return transform.insertText('hello').apply()
+ * ```
+ *
+ * and
+ *
+ * ```js
+ * state.transform()
+ *   .call(myTransform, 0, 1)
+ *   .insertText('hello')
+ *   .apply()
+ * ```
+ *
+ * @param {Transform} transform
+ * @param {Mixed} ...args
+ */
+
+export default function call(transform, fn, ...args) {
+  fn(transform, ...args)
+  return
+}

src/transforms/index.js

@@ -7,6 +7,12 @@ import {
   applyOperation,
 } from './apply-operation'
 
+/**
+ * Call external transform.
+ */
+
+import call from './call'
+
 /**
  * Operations.
  */
@@ -184,6 +190,12 @@ export default {
 
   applyOperation,
 
+  /**
+   * Call external transform.
+   */
+
+  call,
+
   /**
    * Operations.
    */

test/transforms/fixtures/call/call-no-arguments/index.js

@@ -0,0 +1,15 @@
+
+import { Block } from '../../../../..'
+
+export default function (state) {
+  const { document, selection } = state
+
+  function insertCustomBlock(transform, blockType) {
+    transform.insertBlock('turkey')
+  }
+
+  return state
+    .transform()
+    .call(insertCustomBlock)
+    .apply()
+}

test/transforms/fixtures/call/call-no-arguments/input.yaml

@@ -0,0 +1,12 @@
+
+nodes:
+  - kind: block
+    type: paragraph
+    nodes:
+      - kind: text
+        text: one
+  - kind: block
+    type: paragraph
+    nodes:
+      - kind: text
+        text: two

test/transforms/fixtures/call/call-no-arguments/output.yaml

@@ -0,0 +1,17 @@
+
+nodes:
+  - kind: block
+    type: turkey
+    nodes:
+      - kind: text
+        text: ""
+  - kind: block
+    type: paragraph
+    nodes:
+      - kind: text
+        text: one
+  - kind: block
+    type: paragraph
+    nodes:
+      - kind: text
+        text: two

test/transforms/fixtures/call/call-with-arguments/index.js

@@ -0,0 +1,15 @@
+
+import { Block } from '../../../../..'
+
+export default function (state) {
+  const { document, selection } = state
+
+  function insertCustomBlock(transform, blockType) {
+    transform.insertBlock(blockType)
+  }
+
+  return state
+    .transform()
+    .call(insertCustomBlock, 'crystal')
+    .apply()
+}

test/transforms/fixtures/call/call-with-arguments/input.yaml

@@ -0,0 +1,12 @@
+
+nodes:
+  - kind: block
+    type: paragraph
+    nodes:
+      - kind: text
+        text: one
+  - kind: block
+    type: paragraph
+    nodes:
+      - kind: text
+        text: two

test/transforms/fixtures/call/call-with-arguments/output.yaml

@@ -0,0 +1,17 @@
+
+nodes:
+  - kind: block
+    type: crystal
+    nodes:
+      - kind: text
+        text: ""
+  - kind: block
+    type: paragraph
+    nodes:
+      - kind: text
+        text: one
+  - kind: block
+    type: paragraph
+    nodes:
+      - kind: text
+        text: two

test/transforms/index.js

@@ -157,4 +157,24 @@ describe('transforms', async () => {
       })
     }
   })
+
+  describe('call', () => {
+    const dir = resolve(__dirname, './fixtures/call')
+    const tests = fs.readdirSync(dir)
+    for (const test of tests) {
+      if (test[0] == '.') continue
+
+      it(test, async () => {
+        const testDir = resolve(dir, test)
+        const fn = require(testDir).default
+        const input = await readYaml(resolve(testDir, 'input.yaml'))
+        const expected = await readYaml(resolve(testDir, 'output.yaml'))
+
+        let state = Raw.deserialize(input, { terse: true })
+        state = fn(state)
+        const output = Raw.serialize(state, { terse: true })
+        strictEqual(strip(output), strip(expected))
+      })
+    }
+  })
 })