alfy

轻松创建 Alfred 工作流

亮点

简单的输入↔输出。
内置配置和缓存处理。
获取远程文件，可选缓存。
将你的工作流发布到 npm。
自动更新通知。
轻松测试工作流。
查找 node 二进制文件。
支持顶层 await。
向用户呈现未捕获的异常和未处理的 Promise 拒绝。
无需手动 .catch() 顶层 Promise。

前提条件

你需要 Node.js 18+ 和 Alfred 4 或更高版本，并购买 Powerpack 升级。

安装

npm install alfy

使用方法

重要： 你的脚本将作为 ESM 运行。

创建一个新的空白 Alfred 工作流。
添加一个 Script Filter（右键单击画布 → Inputs → Script Filter），将 Language 设置为 /bin/bash，并添加以下脚本：

./node_modules/.bin/run-node index.js "$1"

我们不能直接调用 node，因为 macOS 上的 GUI 应用不会继承 $PATH。

提示：你可以使用 generator-alfred 来搭建基于 alfy 的工作流框架。如果这样做，你可以跳过剩余步骤，直接转到 index.js 开始你的工作。

设置你想要调用工作流的 Keyword。
进入你的新工作流目录（在侧边栏中右键单击工作流 → Open in Finder）。
使用 npm init 初始化一个仓库。
在 package.json 中添加 "type": "module"。
使用 npm install alfy 安装 Alfy。
在工作流目录中，创建一个 index.js 文件，导入 alfy，然后开始你的工作。

示例

这里我们从一个占位 API 获取一些 JSON 数据，并向用户呈现匹配的项目：

import alfy from 'alfy';

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

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

alfy.output(items);

一些实际使用的例子：alfred-npms、alfred-emoj、alfred-ng。

更新通知

Alfy 在后台使用 alfred-notifier 来显示工作流有可用更新时的通知。

缓存

Alfy 提供了缓存数据的可能性，可以通过 fetch 或直接通过 cache 对象进行。

需要注意的一个重要点是，当你更新工作流时，缓存的数据会自动失效。这为开发者提供了灵活性，可以在工作流之间更改缓存数据的结构，而不必担心无效的旧数据。

发布到 npm

通过添加 alfy-init 作为 postinstall 脚本和 alfy-cleanup 作为 preuninstall 脚本，你可以将你的包发布到 npm 而不是 Packal。这样，你的包只需一个简单的 npm install 命令就可以安装。

{
	"name": "alfred-unicorn",
	"version": "1.0.0",
	"description": "我的超棒独角兽工作流",
	"author": {
		"name": "Sindre Sorhus",
		"email": "sindresorhus@gmail.com",
		"url": "https://sindresorhus.com"
	},
	"scripts": {
		"postinstall": "alfy-init",
		"preuninstall": "alfy-cleanup"
	},
	"dependencies": {
		"alfy": "*"
	}
}

提示：给你的工作流加上 alfred- 前缀，使它们在 npm 上更容易被搜索到。

你可以从 info.plist 文件中删除这些属性，因为它们会在安装时自动添加。

将你的工作流发布到 npm 后，你的用户可以轻松地安装或更新工作流。

npm install --global alfred-unicorn

提示：不要手动更新每个工作流，使用 alfred-updater 工作流来为你完成这项工作。

测试

可以使用 alfy-test 轻松测试工作流。以下是一个简单的示例。

import test from 'ava';
import alfyTest from 'alfy-test';

test('main', async t => {
	const alfy = alfyTest();

	const result = await alfy('workflow input');

	t.deepEqual(result, [
		{
			title: 'foo',
			subtitle: 'bar'
		}
	]);
});

调试

在开发工作流时，当遇到问题时能够进行调试是很有用的。这时工作流调试器就派上用场了。你可以在 Alfred 的工作流视图中找到它。点击昆虫图标打开它。它会显示 alfy.output() 的纯文本输出以及你用 alfy.log() 记录的任何内容：

import alfy from 'alfy';

const unicorn = getUnicorn();
alfy.log(unicorn);

环境变量

Alfred 允许用户为工作流设置环境变量，然后该工作流可以使用这些变量。如果你需要用户为某个服务指定 API 令牌，这可能会很有用。你可以通过 process.env 访问工作流环境变量。例如 process.env.apiToken。

API

input

类型：string

来自 Alfred 的输入。用户在输入框中输入的内容。

output(list, options?)

向 Alfred 返回输出。

list

类型：object[]

包含任何支持属性的 object 列表。

示例：

import alfy from 'alfy';

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

options

类型：object

rerunInterval

类型：number (秒)
值：0.1...5.0

可以设置脚本在一段时间间隔后自动重新运行。只有在脚本过滤器仍然活跃且用户没有通过输入触发重新运行来改变过滤器状态时，脚本才会重新运行。更多信息。

例如，可以用来更新特定任务的进度：

import alfy from 'alfy';

alfy.output(
	[
		{
			title: '正在下载独角兽…',
			subtitle: `${progress}%`,
		}
	],
	{
		// 每3秒重新运行并更新进度。
		rerunInterval: 3
	}
);

log(value)

将 value 记录到 Alfred 工作流调试器。

matches(input, list, item?)

返回 list 中包含 input 的项目（不区分大小写）的 string[]。

import alfy from 'alfy';

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

input

类型：string

用于匹配 list 项目的文本。

list

类型：string[]

要匹配的列表。

item

类型：string | Function

默认情况下，它会匹配 list 项目。

指定一个字符串来匹配对象属性：

import alfy from 'alfy';

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

alfy.matches('Unicorn', list, 'title');
//=> [{title: 'unicorn'}]

或嵌套属性：

import alfy from 'alfy';

const list = [
	{
		name: {
			first: 'John',
			last: 'Doe'
		}
	},
	{
		name: {
			first: 'Sindre',
			last: 'Sorhus'
		}
	}
];

alfy.matches('sindre', list, 'name.first');
//=> [{name: {first: 'Sindre', last: 'Sorhus'}}]

指定一个函数来自行处理匹配。该函数接收列表项和输入（都已转为小写）作为参数，并期望返回一个布尔值表示是否匹配：

import alfy from 'alfy';

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

// 这里我们进行精确匹配。
// `Foo` 匹配该项，因为它已为你转为小写。
alfy.matches('Foo', list, (item, input) => item === input);
//=> ['foo']

inputMatches(list, item?)

与 matches() 相同，但使用 alfy.input 作为 input。如果你想匹配多个项目，你必须定义自己的匹配函数（如此处所示）。让我们扩展开头的例子，以搜索出现在title或body属性或两者中的关键词。

import alfy from 'alfy';

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

const items = alfy
	.inputMatches(
		data,
		(item, input) =>
			item.title?.toLowerCase().includes(input) ||
			item.body?.toLowerCase().includes(input)
	)
	.map((element) => ({
		title: element.title,
		subtitle: element.body,
		arg: element.id,
	}));

alfy.output(items);

error(error)

在Alfred中显示错误或错误消息。

**注意：**你不需要对顶层promise使用.catch()。Alfy会为你处理这个问题。

error

类型：Error | string

要显示的错误或错误消息。

fetch(url, options?)

返回一个Promise，该Promise返回响应的主体。

url

类型：string

要获取的URL。

options

类型：object

任何got选项以及以下选项。

json

类型：boolean
默认值：true

使用JSON.parse解析响应主体并将accept头设置为application/json。

maxAge

类型：number

此请求应被缓存的毫秒数。

resolveBodyOnly

类型：boolean
默认值：true

是否只解析主体还是解析完整响应。

import alfy from 'alfy';

await alfy.fetch('https://api.foo.com');
//=> {foo: 'bar'}

await alfy.fetch('https://api.foo.com', {
	resolveBodyOnly: false 
});
/*
{
	body: {
		foo: 'bar'
	},
	headers: {
		'content-type': 'application/json'
	}
}
*/

transform

类型：Function

在响应主体被缓存之前对其进行转换。

import alfy from 'alfy';

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

转换响应。

import alfy from 'alfy';

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

你也可以返回一个Promise。

import alfy from 'alfy';
import xml2js from 'xml2js';
import pify from 'pify';

const parseString = pify(xml2js.parseString);

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

config

类型：object

持久化配置数据。

导出一个设置了正确配置路径的conf实例。

示例：

import alfy from 'alfy';

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

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

userConfig

类型：Map

导出一个包含用户工作流配置的Map。工作流配置允许你的用户为工作流提供配置信息。例如，如果你正在开发一个GitHub工作流，你可以让你的用户提供他们自己的API令牌。

更多详情请参见alfred-config。

示例：

import alfy from 'alfy';

alfy.userConfig.get('apiKey');
//=> '16811cad1b8547478b3e53eae2e0f083'

cache

类型：object

持久化缓存数据。

导出一个设置了正确缓存路径的修改版conf实例。

示例：

import alfy from 'alfy';

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

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

maxAge

此实例的set方法接受一个可选的第三个参数，你可以在其中提供maxAge选项。maxAge是值在缓存中有效的毫秒数。

示例：

import alfy from 'alfy';
import delay from 'delay';

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

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

// 等待5秒
await delay(5000);

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

debug

类型：boolean

用户当前是否打开了工作流调试器。

icon

获取各种默认系统图标。最有用的图标已作为键值包含在内。其余的可以通过 icon.get() 获取。在访达中前往 /System/Library/CoreServices/CoreTypes.bundle/Contents/Resources 可以查看所有图标。

示例：

import alfy from 'alfy';

console.log(alfy.icon.error);
//=> '/System/Library/CoreServices/CoreTypes.bundle/Contents/Resources/AlertStopIcon.icns'

console.log(alfy.icon.get('Clock'));
//=> '/System/Library/CoreServices/CoreTypes.bundle/Contents/Resources/Clock.icns'