lib-workflow.md

Workflow Example

Here we fetch some JSON from a placeholder API and present matching items to the user:

const arvish = require('arvish');

const data = await arvish.fetch('https://jsonplaceholder.typicode.com/posts');

const items = arvish
	.inputMatches(data, 'title')
	.map(element => ({
		title: element.title,
		subtitle: element.body,
		arg: element.id
	}));

arvish.output(items);

API

input

Type: string

Input from Arvis. What the user wrote in the input box.

output(list, options?)

Return output to Arvis

list

Type: object[]

List of object with any of the supported properties.

Example:

arvish.output([
	{
		title: 'Unicorn'
	},
	{
		title: 'Rainbow'
	}
]);

options

Type: object

rerunInterval

Type: number (seconds)
Values: 0.1...5.0

A script can be set to re-run automatically after some interval. The script will only be re-run if the script filter is still active and the user hasn't changed the state of the filter by typing and triggering a re-run.

For example, it could be used to update the progress of a particular task:

arvish.output(
	[
		{
			title: 'Downloading Unicorns…',
			subtitle: `${progress}%`,
		}
	],
	{
		// Re-run and update progress every 3 seconds.
		rerunInterval: 3
	}
);

log(value)

Log value to the debugger

matches(input, list, item?)

Returns an string[] of items in list that case-insensitively contains input.

arvish.matches('Corn', ['foo', 'unicorn']);
//=> ['unicorn']

input

Type: string

Text to match against the list items.

list

Type: string[]

List to be matched against.

item

Type: string | Function

By default, it will match against the list items.

Specify a string to match against an object property:

const list = [
	{
		title: 'foo'
	},
	{
		title: 'bar'
	}
];

arvish.matches('foo', list, 'title');
//=> [{title: 'foo'}]

Or nested property:

const list = [
	{
		name: {
			first: 'John',
			last: 'Doe'
		}
	},
	{
		name: {
			first: 'Gil-dong',
			last: 'Hong'
		}
	}
];

arvish.matches('gil-dong', list, 'name.first');
//=> [{name: {first: 'Gil-dong', last: 'Hong'}}]

Specify a function to handle the matching yourself. The function receives the list item and input, both lowercased, as arguments, and is expected to return a boolean of whether it matches:

const list = ['foo', 'bar'];

// Here we do an exact match.
// `Foo` matches the item since it's lowercased for you.
arvish.matches('Foo', list, (item, input) => item === input);
//=> ['foo']

inputMatches(list, item?)

Same as matches(), but with arvish.input as input.

error(error)

Display an error or error message in debugger.

Note: You don't need to .catch() promises. Arvish handles that for you.

error

Type: Error | string

Error or error message to be displayed.

fetch(url, options?)

Returns a Promise that returns the body of the response.

url

Type: string

URL to fetch.

options

Type: object

Any of the got options.

json

Type: boolean
Default: true

Parse response body with JSON.parse and set accept header to application/json.

maxAge

Type: number

Number of milliseconds this request should be cached.

transform

Type: Function

Transform the response before it gets cached.

await arvish.fetch('https://api.foo.com', {
	transform: body => {
		body.foo = 'bar';
		return body;
	}
})

You can also return a Promise.

const xml2js = require('xml2js');
const pify = require('pify');

const parseString = pify(xml2js.parseString);

await arvish.fetch('https://api.foo.com', {
	transform: body => parseString(body)
})

icon

Type: object
Keys: 'info' | 'warning' | 'error' | 'alert' | 'like' | 'delete'

Get various default system icons.

The most useful ones are included as keys.

config

Type: object

Persist config data.

Exports a conf instance with the correct config path set.

Example:

arvish.config.set('unicorn', '🦄');

arvish.config.get('unicorn');
//=> '🦄'

cache

Type: object

Persist cache data.

Exports a modified conf instance with the correct cache path set.

Example:

arvish.cache.set('unicorn', '🦄');

arvish.cache.get('unicorn');
//=> '🦄'

maxAge

The set method of this instance accepts an optional third argument where you can provide a maxAge option. maxAge is the number of milliseconds the value is valid in the cache.

Example:

const delay = require('delay');

arvish.cache.set('foo', 'bar', {maxAge: 5000});

arvish.cache.get('foo');
//=> 'bar'

// Wait 5 seconds
await delay(5000);

arvish.cache.get('foo');
//=> undefined

meta

Type: object

Example:

{
	name: 'some_extension_name',
	version: '0.0.1',
	bundleId: 'some_extension_bundleId',
	type: 'workflow'
}

env

data

Recommended location for non-volatile data. Just use arvish.config which uses this path.

cache

Recommended location for volatile data. Just use arvish.cache which uses this path.

history

Path for saving the action logs and query logs.

platform

home

User's home directory.

crashDumps

Directory where crash dumps are stored.

desktop

The current user's Desktop directory.

documents

Directory for a user's "My Documents".

downloads

Directory for a user's "Downloads".

currentExe

The current executable file.

music

Directory for a user's music.

pictures

Directory for a user's pictures.

temp

Temporary directory

userData

The directory for storing your app's configuration files, which by default it is the appData directory appended with your app's name.

appData

Per-user application data directory, which by default points to