diff --git a/docs/.vitepress/sidebar.config.mts b/docs/.vitepress/sidebar.config.mts index 88fd4ae..8197b39 100755 --- a/docs/.vitepress/sidebar.config.mts +++ b/docs/.vitepress/sidebar.config.mts @@ -20,8 +20,8 @@ export const SIDEBAR: DefaultTheme.Sidebar = [ link: 'workflow-metadata', }, { - text: 'Versioning 🔄', - link: 'versioning', + text: 'Versioning & Bundling 📦', + link: 'versioning-bundling', }, ], }, diff --git a/docs/app/ci/semantic-release.md b/docs/app/ci/semantic-release.md index 633957b..157a47b 100644 --- a/docs/app/ci/semantic-release.md +++ b/docs/app/ci/semantic-release.md @@ -9,6 +9,8 @@ next: false `fast-alfred` CI / CD template recommends you work with [`semantic-release`](https://github.com/semantic-release/semantic-release). +At the end of this process, you'd be able to publish your Workflow into GitHub Releases, with a versioning system based on your commits. + ## Installation ```bash diff --git a/docs/app/client/client.md b/docs/app/client/client.md index 02f7bf2..6d45914 100644 --- a/docs/app/client/client.md +++ b/docs/app/client/client.md @@ -5,4 +5,121 @@ next: false # `fast-alfred` Client - +`fast-alfred` provides a lean and optimized client to interact with the Alfred workflow system. + +### Intro + +Your script should look like that: + +```typescript +import { FastAlfred } from 'fast-alfred' + +;(() => { + const alfredClient = new FastAlfred() + + // ... Rest of your script +})() +``` + +# Available Options + +::: tip Note :zap: +`fast-alfred` client should contain all JSDocs types and descriptions, so you can use your IDE to explore the available options. +::: + +See the available options below: + +## `output` + +Outputs the script filter object to interact with Alfred. +Allows you to show a list of items in Alfred, with all Alfred interaction options. + +## `log` + +Logs errors for debugging purposes. + +## `matches` + +Searches for a query in a list of items. The search can be case sensitive or not, default is false. + +## `inputMatches` + +Searches for a query in the workflow input. The search can be case sensitive or not, default is false. + +::: info NOTE 📝 +This function has the same behavior as `matches`, but it searches in the input. +::: + +## `error` + +Shows an error message in Alfred UI. + +## `alfredInfo` + +Service to get Alfred's environment variables. You can find all Alfred & Workflow metadata in here. + +## `userConfig` + +Get and set dedicated configuration for the Workflow. +You can use it to store and retrieve data saved about the user. + +## `icons` + +Get icons from the system. +You can use it to get the icon path for a specific icon. + +#### Example + +```typescript +alfredClient.output({ + items: [ + { + title: 'Some Error', + icon: { + path: alfredClient.icons.getIcon('error'), // Get the error icon + }, + }, + ], +}) +``` + +## `config` + +Get and set dedicated configuration for the Workflow. +You can use it to store and retrieve data saved about the user. + +## `env` + +Get Environment variables. +All Workflow user configuration would be injected in here. + +::: info NOTE 📝 +When inserting data into the `Configure Workflow...` on Alfred UI, it will be available in the `env` service. +::: + +#### Example + +```typescript +const someVariable: number = alfredClient.env.getEnv(Variables.SOME_VARIABLE, { defaultValue: 10, parser: Number }) +``` + +## `cache` + +Get and set dedicated cache for your Workflow. You can leverage it to optimize your Workflow performance. +Use the `setWithTTL` in order to set a cache with a time to live. + +::: info NOTE 📝 +The TTL is in milliseconds, so you can set it to 1000 for 1 second, 60000 for 1 minute, and so on +::: + +#### Example + +```typescript +const data: SomeType[] = alfredClient.cache.get(SOME_DATA_KEY) ?? (await fetchData()) + +alfredClient.cache.setWithTTL(SOME_DATA_KEY, data, { maxAge: CACHE_TTL }) +``` + +## `input: string` + +Get the input passed into the script filter (by `$1` or `{query}`). diff --git a/docs/app/quick-start.md b/docs/app/quick-start.md index b2fe43b..4dd4a81 100755 --- a/docs/app/quick-start.md +++ b/docs/app/quick-start.md @@ -27,10 +27,21 @@ module.exports = {} ### Build Your First Workflow 1. Create a Workflow via Alfred UI, or use an existing one -1. Open the Workflow directory, copy relevant files -1. Create a new directory for your Workflow - -1. Use `fast-alfred` client utilities to manage your Workflow +1. Open the Workflow directory, copy relevant files (icons, `info.plist`, `prefs.plist`, etc) to your project +1. Create a source directory for your Workflow scripts + +```bash +mkdir -p src/main +``` + +::: warning Caution :warning: +By default, your production scripts should be located under `src/main`. +You can import every external script from this directory regularly. +See more [here](./setup/bundler-options#productionscripts) +::: + +4. Use [`fast-alfred` client](./client/client.md) utilities to manage your Workflow +1. Follow the [bundling guidelines](./setup/versioning-bundling) to bundle your scripts 1. Call your scripts using [`fast-alfred` runtime](./setup/runtime-explain)
diff --git a/docs/app/setup/runtime-explain.md b/docs/app/setup/runtime-explain.md index 17feac4..7f11b70 100644 --- a/docs/app/setup/runtime-explain.md +++ b/docs/app/setup/runtime-explain.md @@ -21,5 +21,9 @@ The code below is an example of how to trigger your Node.js script in an Alfred ::: ```bash -./esbuild/assets/run-node.sh esbuild/bookmarks.js "$1" +./esbuild/assets/run-node.sh esbuild/your-script-under-main.js "$1" ``` + +#### DEMO + +![Runtime Example](/runtime-example.jpeg) diff --git a/docs/app/setup/versioning.md b/docs/app/setup/versioning-bundling.md similarity index 88% rename from docs/app/setup/versioning.md rename to docs/app/setup/versioning-bundling.md index edc11fe..2b54042 100644 --- a/docs/app/setup/versioning.md +++ b/docs/app/setup/versioning-bundling.md @@ -3,7 +3,7 @@ prev: true next: false --- -# Versioning :package: +# Versioning & Bundling :package: `fast-alfred` provides a way to manage your workflow version automatically. @@ -11,7 +11,7 @@ In order to sync the version across `package.json` and `info.plist`, just pass i `fast-alfred` the version you want to use: ```bash -npx fast-alfred -t 1.2.3 # This will set the version to 1.2.3 +npx fast-alfred -t 1.2.3 # Set the version to 1.2.3, creating a .alfredworkflow file ``` ## Versioning By Commits Using `semantic-release` :arrows_counterclockwise: diff --git a/docs/index.md b/docs/index.md index df6f13f..75c7a38 100755 --- a/docs/index.md +++ b/docs/index.md @@ -28,7 +28,11 @@ features: link: '/app/ci/github-actions' details: A CI/CD template to automate your workflow deployment. icon: '🐙' - - title: Bundle Management + - title: Version Management & Bundling + link: '/app/setup/versioning-bundling' + details: Automatically manage your workflow version, both in `package.json` and `info.plist`. + icon: '💯' + - title: Bundler Options link: '/app/setup/bundler-options' details: Automatically bundle your workflow into a `.alfredworkflow` file. icon: '👨‍💻' @@ -36,8 +40,4 @@ features: link: 'app/setup/workflow-metadata' details: Automatically generate Alfred workflow metadata. icon: '🔨' - - title: Version Management - link: '/app/setup/versioning' - details: Automatically manage your workflow version, both in `package.json` and `info.plist`. - icon: '💯' --- diff --git a/docs/public/runtime-example.jpeg b/docs/public/runtime-example.jpeg new file mode 100644 index 0000000..ead1244 Binary files /dev/null and b/docs/public/runtime-example.jpeg differ diff --git a/src/core/fast-alfred.client.ts b/src/core/fast-alfred.client.ts index e0e01d0..534f99d 100644 --- a/src/core/fast-alfred.client.ts +++ b/src/core/fast-alfred.client.ts @@ -27,15 +27,15 @@ export class FastAlfred { * * @example * ```typescript - * alfredClient.output({ - * items: [ - * { - * title: 'Some Error', - * icon: { - * path: alfredClient.icons.getIcon('error'), - * }, - * }, - * ], + * alfredClient.output({ + * items: [ + * { + * title: 'Some Error', + * icon: { + * path: alfredClient.icons.getIcon('error'), + * }, + * }, + * ], * }) * ``` */