alfy 2.0.0 → 3.0.0

package/index.d.ts

@@ -36,6 +36,8 @@ export type CacheConfSetOptions = {
 	readonly maxAge?: number;
 };
 
+// TODO: Rename this in the next major version.
+
 export type CacheConf<T extends Record<string, any> = Record<string, unknown>> = {
 	isExpired: (key: keyof T) => boolean;
 
@@ -363,9 +365,9 @@ export type Alfy = {
 	/**
 	Log value to the Alfred workflow debugger.
 
-	@param text
+	@param value
 	*/
-	log: (text: string) => void;
+	log: (value: unknown) => void;
 
 	/**
 	Display an error or error message in Alfred.

package/index.js

@@ -3,18 +3,20 @@ import process from 'node:process';
 import {createRequire} from 'node:module';
 import Conf from 'conf';
 import got from 'got';
-import {hookStderr} from 'hook-std';
 import loudRejection from 'loud-rejection';
 import cleanStack from 'clean-stack';
 import {getProperty} from 'dot-prop';
 import AlfredConfig from 'alfred-config';
-import updateNotification from './lib/update-notification.js'; // eslint-disable-line import/order
+import updateNotification from './lib/update-notification.js'; // eslint-disable-line import-x/order
 
 const require = createRequire(import.meta.url);
 const CacheConf = require('cache-conf');
 
 const alfy = {};
 
+// Track if output has been generated to avoid empty JSON
+let hasOutput = false;
+
 updateNotification();
 
 const getIcon = name => `/System/Library/CoreServices/CoreTypes.bundle/Contents/Resources/${name}.icns`;
@@ -42,6 +44,7 @@ alfy.alfred = {
 alfy.input = process.argv[2];
 
 alfy.output = (items, {rerunInterval} = {}) => {
+	hasOutput = true;
 	console.log(JSON.stringify({items, rerun: rerunInterval}, null, '\t'));
 };
 
@@ -73,6 +76,7 @@ alfy.log = text => {
 
 alfy.error = error => {
 	const stack = cleanStack(error.stack || error);
+	const title = error.stack ? `${error.name}: ${error.message}` : String(error);
 
 	const copy = `
 \`\`\`
@@ -86,7 +90,7 @@ ${process.platform} ${os.release()}
 	`.trim();
 
 	alfy.output([{
-		title: error.stack ? `${error.name}: ${error.message}` : error,
+		title,
 		subtitle: 'Press ⌘L to see the full error and ⌘C to copy it.',
 		valid: false,
 		text: {
@@ -97,6 +101,9 @@ ${process.platform} ${os.release()}
 			path: alfy.icon.error,
 		},
 	}]);
+
+	// Also output to stderr for the debugger (as requested in issue #86)
+	console.error(stack);
 };
 
 alfy.config = new Conf({
@@ -118,11 +125,6 @@ alfy.fetch = async (url, options) => {
 		...options,
 	};
 
-	// TODO: Remove this in 2024.
-	if (options.query) {
-		throw new Error('The `query` option was renamed to `searchParams`.');
-	}
-
 	if (typeof url !== 'string') {
 		throw new TypeError(`Expected \`url\` to be a \`string\`, got \`${typeof url}\``);
 	}
@@ -138,7 +140,7 @@ alfy.fetch = async (url, options) => {
 	delete options.transform;
 	delete options.maxAge;
 
-	const key = rawKey.replaceAll('.', '\\.');
+	const key = rawKey.replaceAll('.', String.raw`\.`);
 	const cachedResponse = alfy.cache.get(key, {ignoreMaxAge: true});
 
 	if (cachedResponse && !alfy.cache.isExpired(key)) {
@@ -186,6 +188,12 @@ alfy.icon = {
 
 loudRejection(alfy.error);
 process.on('uncaughtException', alfy.error);
-hookStderr(alfy.error);
+
+// Ensure valid JSON output even if user forgets to call alfy.output() (fixes #82)
+process.on('beforeExit', () => {
+	if (!hasOutput) {
+		alfy.output([]);
+	}
+});
 
 export default alfy;

package/lib/update-notification.js

@@ -2,8 +2,8 @@ import {readPackageUp} from 'read-package-up';
 import alfredNotifier from 'alfred-notifier';
 
 export default async function updateNotification() {
-	const {package: pkg} = await readPackageUp();
-	const alfy = (pkg || {}).alfy || {};
+	const {package: package_} = (await readPackageUp()) ?? {};
+	const alfy = package_?.alfy ?? {};
 
 	if (alfy.updateNotification !== false) {
 		alfredNotifier();

package/package.json

@@ -1,9 +1,10 @@
 {
 	"name": "alfy",
-	"version": "2.0.0",
+	"version": "3.0.0",
 	"description": "Create Alfred workflows with ease",
 	"license": "MIT",
 	"repository": "sindresorhus/alfy",
+	"funding": "https://github.com/sponsors/sindresorhus",
 	"type": "module",
 	"bin": {
 		"run-node": "./run-node.sh",
@@ -14,8 +15,9 @@
 		"types": "./index.d.ts",
 		"default": "./index.js"
 	},
+	"sideEffects": false,
 	"engines": {
-		"node": ">=18"
+		"node": ">=20"
 	},
 	"scripts": {
 		"test": "xo && ava && tsd"
@@ -45,21 +47,21 @@
 		"alfred-notifier": "^0.2.3",
 		"cache-conf": "^0.6.0",
 		"clean-stack": "^5.2.0",
-		"conf": "^12.0.0",
-		"dot-prop": "^8.0.2",
-		"execa": "^8.0.1",
-		"got": "^13.0.0",
-		"hook-std": "^3.0.0",
+		"conf": "^14.0.0",
+		"dot-prop": "^10.0.0",
+		"execa": "^9.6.0",
+		"got": "^14.4.8",
+		"hook-std": "^4.0.0",
 		"loud-rejection": "^2.2.0",
 		"read-package-up": "^11.0.0"
 	},
 	"devDependencies": {
-		"ava": "^5.3.1",
+		"ava": "^6.4.1",
 		"delay": "^6.0.0",
-		"nock": "^13.3.8",
+		"nock": "^14.0.10",
 		"tempfile": "^5.0.0",
-		"tsd": "^0.29.0",
-		"xo": "^0.56.0"
+		"tsd": "^0.33.0",
+		"xo": "^1.2.2"
 	},
 	"tsd": {
 		"compilerOptions": {

package/readme.md

@@ -103,7 +103,7 @@ By adding `alfy-init` as `postinstall` and `alfy-cleanup` as `preuninstall` scri
 	"author": {
 		"name": "Sindre Sorhus",
 		"email": "sindresorhus@gmail.com",
-		"url": "sindresorhus.com"
+		"url": "https://sindresorhus.com"
 	},
 	"scripts": {
 		"postinstall": "alfy-init",
@@ -151,13 +151,16 @@ test('main', async t => {
 
 ## Debugging
 
-When developing your workflow it can be useful to be able to debug it when something is not working. This is when the [workflow debugger](https://www.alfredapp.com/help/workflows/advanced/debugger/) comes in handy. You can find it in your workflow view in Alfred. Press the insect icon to open it. It will show you the plain text output of `alfy.output()` and anything you log with `alfy.log()`:
+When developing your workflow it can be useful to be able to debug it when something is not working. This is when the [workflow debugger](https://www.alfredapp.com/help/workflows/advanced/debugger/) comes in handy. You can find it in your workflow view in Alfred. Press the insect icon to open it. It will show you the plain text output of `alfy.output()` and anything you log with `alfy.log()` or `console.error()`:
 
 ```js
 import alfy from 'alfy';
 
 const unicorn = getUnicorn();
 alfy.log(unicorn);
+
+// You can also use console.error() for debugging
+console.error('Debug info:', {data: someData});
 ```
 
 ## Environment variables
@@ -237,7 +240,7 @@ Log `value` to the [Alfred workflow debugger](https://www.alfredapp.com/help/wor
 
 #### matches(input, list, item?)
 
-Returns an `string[]` of items in `list` that case-insensitively contains `input`.
+Returns a `string[]` of items in `list` that case-insensitively contains `input`.
 
 ```js
 import alfy from 'alfy';
@@ -323,6 +326,29 @@ alfy.matches('Foo', list, (item, input) => item === input);
 
 Same as `matches()`, but with `alfy.input` as `input`.
 
+If you want to match against multiple items, you must define your own matching function ([as shown here](#item)). Let’s extend the [example from the beginning](#example) to search for a keyword that appears either within the `title` or `body` property or both.
+
+```js
+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)
 
 Display an error or error message in Alfred.