Merge branch 'master' into issue/1-improve-documentation

.travis.yml

@@ -3,7 +3,11 @@ node_js:
   - "10"
   - node
 
-script: echo "Running tests against $(node -v)..."
+script:
+  - echo "Running tests against $(node -v)..."
+  - npm test
+
+install: npm install
 
 jobs:
   include:

CONTRIBUTING.md

@@ -11,7 +11,7 @@ Adding a new Shortcut action is relatively straightforward.
 3. Move it into a `/shortcuts` directory in the root of this project.
 4. Run `node scripts/parse.js` and select your Shortcut and action. This will log out the parsed Shortcut data.
 5. Copy this data into a new file in `src/actions`, optionally using an existing action as a template. The file (and action) you're creating should be the name of the action as it appears in the Shortcuts app, camelCased. For example, if you were adding the 'Run Home Scene' action, the file would be named `runHomeScene.ts` and it would export a function named `runHomeScene`. If in any doubt, use the already implemented actions as guides.
-6. Connect up all Shortcut options to the function parameters. Try to be as thorough as possible and make sure you cover all possible options. You'll likely need to add some new types to `src/interfaces/WF` and `src/interfaces/WF/WFWorkflowActionParameters.ts`. You'll also want to check whether or not the action can be used as a 'Magic Variable'. If it can, don't forget to wrap the exported function with the `withUUID` function (see `src/actions/number.ts` as an example).
+6. Connect up all Shortcut options to the function parameters. Try to be as thorough as possible and make sure you cover all possible options. You'll likely need to add some new types to `src/interfaces/WF` and `src/interfaces/WF/WFWorkflowActionParameters.ts`. You'll also want to check whether or not the action can be used as a 'Magic Variable'. If it can, don't forget to wrap the exported function with the `withActionOutput` function (see `src/actions/number.ts` as an example).
 7. Export the new file from `src/actions/index.ts`.
 8. Add tests for the new action to `__tests__/actions`. Again, try to be as thorough as possible and use another action's tests as a starting point.
 9. Make sure all tests pass, and that the new action is documented with JSDoc in the same way all other actions are.

README.md

@@ -12,7 +12,7 @@ A Node.js iOS 12 Shortcuts creator.
 
 [@joshfarrant/shortcuts-js](https://www.npmjs.com/package/@joshfarrant/shortcuts-js) on npm.
 
-[NPM](https://www.npmjs.com/package/@joshfarrant/shortcuts-js) | [Documentation](https://shortcuts.fun/module-actions.html) | [Contributing](https://github.com/joshfarrant/shortcuts-js/blob/master/CONTRIBUTING.md) | [Medium](https://medium.com/@JoshFarrant/creating-ios-12-shortcuts-with-javascript-and-shortcuts-js-942420ca9904)
+[NPM](https://www.npmjs.com/package/@joshfarrant/shortcuts-js) | [Documentation](https://docs.shortcuts.fun) | [Contributing](https://github.com/joshfarrant/shortcuts-js/blob/master/CONTRIBUTING.md) | [Medium](https://medium.com/@JoshFarrant/creating-ios-12-shortcuts-with-javascript-and-shortcuts-js-942420ca9904)
 
 See [this issue](https://github.com/joshfarrant/shortcuts-js/issues/6) for a complete list of all Actions implemented so far.
 
@@ -33,6 +33,7 @@ npm install @joshfarrant/shortcuts-js
 const fs = require('fs');
 
 const {
+  actionOutput,
   buildShortcut,
   withVariables,
 } = require('@joshfarrant/shortcuts-js');
@@ -44,7 +45,7 @@ const {
 } = require('@joshfarrant/shortcuts-js/actions');
 
 // We'll use this later to reference the output of a calculation
-let calcId;
+const calcVar = actionOutput();
 
 // Define our list of actions
 const actions = [
@@ -57,16 +58,13 @@ const actions = [
   calculate({
     operand: 3,
     operation: '/',
-  }, (id) => {
-    // We'll use this again in a moment
-    calcId = id;
-  }),
+  }, calcVar),
   showResult({
     /**
      * We can use the result of the calculation in this Shortcuts's input
      * by passing the string to the 'withVariables' tag function
      */
-    text: withVariables`Total is ${calcId}!`,
+    text: withVariables`Total is ${calcVar}!`,
   }),
 ];
 
@@ -98,6 +96,7 @@ For brevity, these examples omit the code for writing the file to disk and just
 
 ```js
 const {
+  actionOutput,
   buildShortcut,
   withVariables,
 } = require('@joshfarrant/shortcuts-js');
@@ -108,12 +107,10 @@ const {
   showResult,
 } = require('@joshfarrant/shortcuts-js/actions');
 
-let batteryLevel;
+const batteryLevel = actionOutput();
 
 const actions = [
-  getBatteryLevel({}, (id) => {
-    batteryLevel = id;
-  }),
+  getBatteryLevel({}, batteryLevel),
   conditional({
     input: '<',
     value: 20,

__tests__/actions/addToVariable.spec.ts

@@ -1,21 +1,27 @@
 import { addToVariable } from '../../src/actions';
+import { variable } from '../../src/utils';
 
 describe('addToVariable function', () => {
 
   it('is a function', () => {
     expect(typeof addToVariable).toBe('function');
   });
 
-  it('builds a addToVariable action when a name is passed', () => {
-    const name = 'Test Variable';
+  it('builds a addToVariable action when a variable is passed', () => {
+    const name = variable('Test Variable');
+
     const expected = {
       WFWorkflowActionIdentifier: 'is.workflow.actions.appendvariable',
       WFWorkflowActionParameters: {
-        WFVariableName: name,
+        WFVariableName: name.VariableName,
       },
     };
-    const actual = addToVariable({ name });
+
+    const actual = addToVariable({
+      variable: name,
+    });
 
     expect(actual).toEqual(expected);
   });
+
 });

__tests__/actions/getVariable.spec.ts

@@ -1,81 +1,53 @@
 import { getVariable } from '../../src/actions';
-
-import WFSerialization from '../../src/interfaces/WF/WFSerialization';
+import {
+  actionOutput,
+  variable,
+} from '../../src/utils';
 
 describe('getVariable function', () => {
 
   it('is a function', () => {
     expect(typeof getVariable).toBe('function');
   });
 
-  it('builds a getVariable action when a variable name is passed', () => {
-    const name = 'variable';
+  it('builds a getVariable action when a variable is passed', () => {
+    const namedVar = variable('variable');
 
     const expected = {
       WFWorkflowActionIdentifier: 'is.workflow.actions.getvariable',
       WFWorkflowActionParameters: {
         WFVariable: {
-          Value: {
-            Type: 'Variable',
-            VariableName: name,
-          },
+          Value: namedVar,
           WFSerializationType: 'WFTextTokenAttachment',
         },
       },
     };
 
-    const actual = getVariable({ variable: name });
+    const actual = getVariable({ variable: namedVar });
 
     expect(actual).toEqual(expected);
   });
 
-  it('builds a getVariable action when a variable UUID is passed', () => {
-    const uuid = 'b74c81a8-192a-463f-a0a6-2d327963714f';
+  it('builds a getVariable action when a magic variable is passed', () => {
+    const magic = actionOutput();
+    magic.OutputUUID = 'b74c81a8-192a-463f-a0a6-2d327963714f';
 
     const expected = {
       WFWorkflowActionIdentifier: 'is.workflow.actions.getvariable',
       WFWorkflowActionParameters: {
         WFVariable: {
           Value: {
-            OutputUUID: uuid,
+            OutputUUID: magic.OutputUUID,
             Type: 'ActionOutput',
           },
           WFSerializationType: 'WFTextTokenAttachment',
         },
       },
     };
 
-    const actual = getVariable({ variable: uuid });
+    const actual = getVariable({ variable: magic });
 
     expect(actual).toEqual(expected);
   });
 
-  it('builds a getVariable action when a variable object is passed', () => {
-    const uuid = 'b74c81a8-192a-463f-a0a6-2d327963714f';
-
-    const variableObject: WFSerialization = {
-      Value: {
-        OutputUUID: uuid,
-        Type: 'ActionOutput',
-      },
-      WFSerializationType: 'WFTextTokenAttachment',
-    };
-
-    const expected = {
-      WFWorkflowActionIdentifier: 'is.workflow.actions.getvariable',
-      WFWorkflowActionParameters: {
-        WFVariable: {
-          Value: {
-            OutputUUID: uuid,
-            Type: 'ActionOutput',
-          },
-          WFSerializationType: 'WFTextTokenAttachment',
-        },
-      },
-    };
-
-    const actual = getVariable({ variable: variableObject });
-
-    expect(actual).toEqual(expected);
-  });
 });

__tests__/actions/runScriptOverSSH.spec.ts

@@ -33,4 +33,5 @@ describe('runScriptOverSSH function', () => {
 
     expect(actual).toEqual(expected);
   });
+
 });

__tests__/actions/setVariable.spec.ts

@@ -1,20 +1,25 @@
 import { setVariable } from '../../src/actions';
+import { variable } from '../../src/utils';
 
 describe('setVariable function', () => {
 
   it('is a function', () => {
     expect(typeof setVariable).toBe('function');
   });
 
-  it('builds a setVariable action when a name is passed', () => {
-    const name = 'Test Variable';
+  it('builds a setVariable action when a variable is passed', () => {
+    const name = variable('Test Variable');
+
     const expected = {
       WFWorkflowActionIdentifier: 'is.workflow.actions.setvariable',
       WFWorkflowActionParameters: {
-        WFVariableName: name,
+        WFVariableName: name.VariableName,
       },
     };
-    const actual = setVariable({ name });
+
+    const actual = setVariable({
+      variable: name,
+    });
 
     expect(actual).toEqual(expected);
   });

__tests__/index.spec.ts

@@ -1,14 +1,27 @@
 import {
+  actionOutput,
   buildShortcut,
+  variable,
   withVariables,
 } from '../src';
 
 import {
+  actionOutput as actionOutputUtil,
   buildShortcut as buildShortcutUtil,
+  variable as variableUtil,
   withVariables as withVariablesUtil,
 } from '../src/utils';
 
 describe('main index.ts file', () => {
+
+  it('exports actionOutput as a named function', () => {
+
+    const actual = actionOutput.toString();
+    const expected = actionOutputUtil.toString();
+
+    expect(actual).toEqual(expected);
+  });
+
   it('exports buildShortcut as a named function', () => {
 
     const actual = buildShortcut.toString();
@@ -17,11 +30,20 @@ describe('main index.ts file', () => {
     expect(actual).toEqual(expected);
   });
 
+  it('exports variable as a named function', () => {
+
+    const actual = variable.toString();
+    const expected = variableUtil.toString();
+
+    expect(actual).toEqual(expected);
+  });
+
   it('exports withVariables as a named function', () => {
 
     const actual = withVariables.toString();
     const expected = withVariablesUtil.toString();
 
     expect(actual).toEqual(expected);
   });
+
 });

__tests__/utils/actionOutput.spec.ts

@@ -0,0 +1,39 @@
+import Attachment from '../../src/interfaces/WF/Attachment';
+import { actionOutput } from '../../src/utils';
+
+describe('actionOutput function', () => {
+
+  it('is a function', () => {
+    expect(typeof actionOutput).toBe('function');
+  });
+
+  it('returns an ActionOutput attachment object when passed nothing', () => {
+    const uuid = '70a08121-f08d-46e4-a41f-102912750b11';
+
+    const actual = actionOutput();
+    actual.OutputUUID = uuid;
+
+    const expected: Attachment = {
+      OutputUUID: uuid,
+      Type: 'ActionOutput',
+    };
+
+    expect(actual).toEqual(expected);
+  });
+
+  it('returns a custom named ActionOutput attachment object when passed a string', () => {
+    const uuid = 'dd05b2e3-6069-4c4a-900a-79ae837795d6';
+
+    const actual = actionOutput('My Result');
+    actual.OutputUUID = uuid;
+
+    const expected: Attachment = {
+      OutputName: 'My Result',
+      OutputUUID: uuid,
+      Type: 'ActionOutput',
+    };
+
+    expect(actual).toEqual(expected);
+  });
+
+});

__tests__/utils/getItemType.spec.ts

@@ -41,4 +41,5 @@ describe('getItemType function', () => {
     const actual = () => getItemType(null as any);
     expect(actual).toThrow('Invalid itemType');
   });
+
 });