feat: Loggable decorator for piped functions (#17)

`loggable` attaches additional metadata to helper functions for the `.pipe` Command. This includes ensuring the display name of a function regardless of the function being anonymous and also attaches parameters passed.

Example:
```ts
const getProp = loggable('getProp', prop => obj => obj[prop]
cy.wrap({ foo: 'bar'  })
  .pipe(getProp('foo'))
  .should('equal', 'bar')
```

This will show the following in the the Cypress Command Log:
```
WRAP      {foo: bar}
- PIPE    getProp("foo")
- ASSERT  expected bar to equal bar
```

Without using `loggable`, the `PIPE` line would not include arguments passed to `getProp`:
```
- PIPE   getProp
```

Fixes #16

Author: NicholasBoll

README.md

@@ -28,6 +28,31 @@ WRAP       {foo: bar}
 
 If the `pipe` was using a `then`, it would fail immediately and wouldn't show the `getFoo` functions anywhere in the Cypress Command Log.
 
+If you care even more about log output and you have more generic functions that curry other functions, you can use `loggable`. That sounds scary, but you might have a function like `getTodoByName` where the function takes the name of the Todo and returns a function that takes a container. For example:
+
+```ts
+import { loggable } from 'cypress-pipe'
+
+const getProp = loggable('getProp', prop => obj => obj[prop])
+// alternative
+const getProp = loggable(prop => function getProp(obj) { return obj[prop] })
+
+cy.wrap({ foo: 'bar' })
+  .pipe(getProp('foo'))
+  .should('equal', 'bar')
+```
+
+The `loggable` decorator function can either take a `name` as a string, or allow `.pipe` to get it from a named currried function.
+
+The Cypress Log will look like:
+
+```
+WRAP       {foo: bar}
+ - PIPE    getProp("foo")
+ - ASSERT  expected bar to equal bar
+```
+
+
 This library is a proof of concept, but should be stable. The proposal can be found here: https://github.com/cypress-io/cypress/issues/1548
 
 ## Best Practices

cypress/integration/example_spec.js

@@ -1,8 +1,41 @@
 /// <reference types="cypress" />
 /// <reference path="../../index.d.ts" />
 
+const { loggable } = require('../../loggable')
+
 const delay = 100 // delay of some retries. Make this larger if you want to see the UI during these times
 
+describe('loggable', () => {
+  context('when only a function is provided', () => {
+    it('should set __args to equal arguments passed in', () => {
+      const getProp = loggable(prop => obj => obj[prop])
+      const fn = getProp('foo', 1, false)
+      expect(fn.__args).to.deep.equal(['foo', 1, false])
+    })
+
+    it('should set displayName to the name of the function', () => {
+      const getFoo = loggable(function getFoo() {})
+      expect(getFoo.displayName).to.equal('getFoo')
+    })
+  })
+
+  context('when a name is provided', () => {
+    it('should set the displayName of the function', () => {
+      const getFoo = loggable('getFoo', () => 'foo')
+      console.log('getFoo', getFoo)
+      expect(getFoo.displayName).to.equal('getFoo')
+    })
+  })
+
+  context('when a curried function is provided', () => {
+    it('should set the displayName of the curried function', () => {
+      const getFoo = loggable('getFoo', prop => obj => obj[prop])
+      const fn = getFoo('foo')
+      expect(fn.displayName).to.equal('getFoo')
+    })
+  })
+})
+
 describe('pipe()', () => {
 
   context('when passed a synchronous function', () => {
@@ -31,6 +64,26 @@ describe('pipe()', () => {
         .pipe(getFoo)
     })
 
+    it('should show arguments of loggable functions', (done) => {
+      const getProp = loggable('getProp', (prop) => (obj) => obj[prop])
+      const args = ['foo', 1, (foo) => foo, false, [1, 'foo'], { foo: 'bar' }]
+
+      cy.on('log:changed', (attrs, log) => {
+        if (log.get('name') === 'pipe') {
+          cy.removeAllListeners('log:changed')
+
+          expect(log.get('message')).to.eq('getProp("foo", 1, function, false, [1,"foo"], {"foo":"bar"})')
+          expect(log.invoke('consoleProps')).to.have.property('Arguments')
+          expect(log.invoke('consoleProps').Arguments).to.deep.equal(args)
+          done()
+        }
+      })
+
+      cy.wrap({ foo: 'bar' })
+        .pipe(getProp(...args))
+        .should('equal', 'bar')
+    })
+
     it('should retry until assertion passes', () => {
       const obj = { foo: 'bar' }
       setTimeout(() => { obj.foo = 'baz' }, delay)

index.js

@@ -17,6 +17,19 @@ const getElements = $el => {
   }
 }
 
+/**
+ * Format the argument according to its type
+ * @param {any} arg 
+ */
+function formatArg (arg) {
+  switch (typeof arg) {
+    case 'function':
+      return arg.name || 'function'
+    default:
+      return JSON.stringify(arg)
+  }
+}
+
 Cypress.Commands.add('pipe', { prevSubject: true }, (subject, fn, options = { }) => {
 
   const getEl = (value) => isJquery(value) ? value : isJquery(subject) ? subject : undefined
@@ -31,16 +44,17 @@ Cypress.Commands.add('pipe', { prevSubject: true }, (subject, fn, options = { })
 
   if (options.log) {
     options._log = Cypress.log({
-      message: fn.name || undefined,
+      message: (fn.displayName || fn.name || undefined) + (fn.__args ? `(${fn.__args.map(formatArg).join(', ')})` : ''),
       $el: getEl(subject), // start the $el with the subject
     })
   }
 
   const getConsoleProps = (value) => () => ({
     Command: 'pipe',
     Subject: subject,
-    Message: fn.name || undefined,
-    Function: fn.toString(),
+    Function: fn.displayName || fn.name || undefined,
+    Arguments: fn.__args || [],
+    Contents: fn.toString(),
     Yielded: isJquery(value) ? getElements(value) : value,
     Elements: isJquery(value) ? value.length : undefined,
     Duration: performance.now() - now,

loggable.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Decorate a function with meta-data to be used with `cy.pipe`. Adds
+ * a display name and arguments of a function.
+ * @param name The name of the function to be displayed in the Cypress
+ * Command Log. The parameter is only required if the function passed
+ * to `cy.pipe` is anonymous
+ * @param fn Function to decorate
+ * @example
+ * const getProp = loggable('getProp', prop => obj => obj[prop])
+ */
+export function loggable<T extends Function>(name: string, fn: T): T
+
+/**
+ * Decorate a function with meta-data to be used with `cy.pipe`. Adds
+ * arguments of a function.
+ * @param fn Function to decorate
+ * @example
+ * const getProp = loggable(prop => function getProp(obj) { return obj[prop] })
+ */
+export function loggable<T extends Function>(fn: T): T

loggable.js

@@ -0,0 +1,26 @@
+function loggable(arg1, arg2) {
+  if (typeof arg1 === 'string') {
+    arg2.displayName = arg1
+    return loggableFn(arg2)
+  } else if (typeof arg1 === 'function') {
+    return loggableFn(arg1)
+  } else {
+    throw Error('First argument must be a function or string')
+  }
+}
+
+function loggableFn(fn) {
+  const internalFn = function(...args) {
+    const value = fn(...args)
+    if (typeof value === 'function') {
+      value.displayName = fn.displayName || value.name
+      value.__args = args
+    }
+    return value
+  }
+  internalFn.displayName = fn.displayName || fn.name
+
+  return internalFn
+}
+
+module.exports = { loggable }