diff --git a/.changeset/cyan-cows-cheer.md b/.changeset/cyan-cows-cheer.md new file mode 100644 index 0000000..ed85812 --- /dev/null +++ b/.changeset/cyan-cows-cheer.md @@ -0,0 +1,5 @@ +--- +'@emigrate/docs': minor +--- + +Add documentation for the built-in "json" reporter diff --git a/.changeset/pink-bobcats-prove.md b/.changeset/pink-bobcats-prove.md new file mode 100644 index 0000000..fbefd77 --- /dev/null +++ b/.changeset/pink-bobcats-prove.md @@ -0,0 +1,5 @@ +--- +'@emigrate/docs': minor +--- + +The "default" reporter is now named "pretty" diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 679de7d..d4df70c 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -171,8 +171,12 @@ export default defineConfig({ link: '/plugins/reporters/', }, { - label: 'Default Reporter', - link: '/plugins/reporters/default/', + label: 'Pretty Reporter (default)', + link: '/plugins/reporters/pretty/', + }, + { + label: 'JSON Reporter', + link: '/plugins/reporters/json/', }, { label: 'Pino Reporter', diff --git a/docs/src/content/docs/commands/list.mdx b/docs/src/content/docs/commands/list.mdx index 8e1fb92..059bf8e 100644 --- a/docs/src/content/docs/commands/list.mdx +++ b/docs/src/content/docs/commands/list.mdx @@ -86,6 +86,9 @@ In case you have both a `emigrate-storage-somedb` and a `somedb` package install ### `-r`, `--reporter ` +**type:** `"pretty" | "json" | string` +**default:** `"pretty"` + The reporter to use for listing the migrations. The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order: diff --git a/docs/src/content/docs/commands/new.mdx b/docs/src/content/docs/commands/new.mdx index 671b918..cb89f33 100644 --- a/docs/src/content/docs/commands/new.mdx +++ b/docs/src/content/docs/commands/new.mdx @@ -101,6 +101,9 @@ In case you have both a `emigrate-plugin-someplugin` and a `someplugin` package ### `-r`, `--reporter ` +**type:** `"pretty" | "json" | string` +**default:** `"pretty"` + The reporter to use for listing the migrations. The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order: diff --git a/docs/src/content/docs/commands/remove.mdx b/docs/src/content/docs/commands/remove.mdx index fde9919..d6adb9f 100644 --- a/docs/src/content/docs/commands/remove.mdx +++ b/docs/src/content/docs/commands/remove.mdx @@ -95,6 +95,9 @@ In case you have both a `emigrate-storage-somedb` and a `somedb` package install ### `-r`, `--reporter ` +**type:** `"pretty" | "json" | string` +**default:** `"pretty"` + The reporter to use for listing the migrations. The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order: diff --git a/docs/src/content/docs/commands/up.mdx b/docs/src/content/docs/commands/up.mdx index cc12ad1..3829882 100644 --- a/docs/src/content/docs/commands/up.mdx +++ b/docs/src/content/docs/commands/up.mdx @@ -147,6 +147,9 @@ In case you have both a `emigrate-plugin-someplugin` and a `someplugin` package ### `-r`, `--reporter ` +**type:** `"pretty" | "json" | string` +**default:** `"pretty"` + The reporter to use for reporting the migration progress. The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order: diff --git a/docs/src/content/docs/plugins/reporters/default.mdx b/docs/src/content/docs/plugins/reporters/default.mdx deleted file mode 100644 index 8a76ff2..0000000 --- a/docs/src/content/docs/plugins/reporters/default.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Default Reporter ---- - -Emigrate's default reporter. The default reporter recognizes if the current terminal is an interactive shell (or if it's a CI environment), if that's the case _no_ animations will be shown. - -## Usage - -By default, Emigrate uses the default reporter. - -## Example output - -```bash - -Emigrate up v0.10.0 /Users/joakim/dev/@aboviq/test-emigrate (dry run) - - 1 pending migrations to run - - › migration-folder/20231218135441244_create_some_table.sql (pending) - - 1 pending (1 total) - -``` diff --git a/docs/src/content/docs/plugins/reporters/index.mdx b/docs/src/content/docs/plugins/reporters/index.mdx index be0a1ec..bdc8aca 100644 --- a/docs/src/content/docs/plugins/reporters/index.mdx +++ b/docs/src/content/docs/plugins/reporters/index.mdx @@ -20,6 +20,7 @@ Or set it up in your configuration file, see - + + + diff --git a/docs/src/content/docs/plugins/reporters/json.mdx b/docs/src/content/docs/plugins/reporters/json.mdx new file mode 100644 index 0000000..a1118fd --- /dev/null +++ b/docs/src/content/docs/plugins/reporters/json.mdx @@ -0,0 +1,102 @@ +--- +title: JSON Reporter +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; +import Link from '@components/Link.astro'; + +An Emigrate reporter that outputs a JSON object. + +The reporter is included by default and does not need to be installed separately. + +## Usage + +### Via CLI + + + + ```bash + npx emigrate --reporter json + ``` + + + ```bash + pnpm emigrate --reporter json + ``` + + + ```bash + yarn emigrate --reporter json + ``` + + + ```bash + bunx --bun emigrate --reporter json + ``` + + + ```json title="package.json" {3} + { + "scripts": { + "emigrate": "emigrate" + } + } + ``` + + ```bash + deno task emigrate --reporter json + ``` + + + +See for instance the Reporter Option for the `up` command for more information. + +### Via configuration file + + + + ```js title="emigrate.config.js" + /** @type {import('@emigrate/cli').EmigrateConfig} */ + export default { + reporter: 'json', + }; + ``` + + + ```ts title="emigrate.config.ts" + import { type EmigrateConfig } from '@emigrate/cli'; + + const config: EmigrateConfig = { + reporter: 'json', + }; + + export default config; + ``` + + + +See Reporter Configuration for more information. + +## Example output + +```json +{ + "command": "up", + "version": "0.17.2", + "numberTotalMigrations": 1, + "numberDoneMigrations": 0, + "numberSkippedMigrations": 0, + "numberFailedMigrations": 0, + "numberPendingMigrations": 1, + "success": true, + "startTime": 1707206599968, + "endTime": 1707206600005, + "migrations": [ + { + "name": "/your/project/migrations/20240206075446123_some_other_table.sql", + "status": "pending", + "duration": 0 + } + ] +} +``` diff --git a/docs/src/content/docs/plugins/reporters/pino.mdx b/docs/src/content/docs/plugins/reporters/pino.mdx index 2ee3c19..e76d6ff 100644 --- a/docs/src/content/docs/plugins/reporters/pino.mdx +++ b/docs/src/content/docs/plugins/reporters/pino.mdx @@ -91,11 +91,27 @@ See for instance the Reporter Opti ### Via configuration file -```js title="emigrate.config.js" {2} -export default { - reporter: 'pino', -}; -``` + + + ```js title="emigrate.config.js" + /** @type {import('@emigrate/cli').EmigrateConfig} */ + export default { + reporter: 'pino', + }; + ``` + + + ```ts title="emigrate.config.ts" + import { type EmigrateConfig } from '@emigrate/cli'; + + const config: EmigrateConfig = { + reporter: 'pino', + }; + + export default config; + ``` + + See Reporter Configuration for more information. diff --git a/docs/src/content/docs/plugins/reporters/pretty.mdx b/docs/src/content/docs/plugins/reporters/pretty.mdx new file mode 100644 index 0000000..1f0cbe0 --- /dev/null +++ b/docs/src/content/docs/plugins/reporters/pretty.mdx @@ -0,0 +1,90 @@ +--- +title: Pretty Reporter (default) +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; +import Link from '@components/Link.astro'; + +Emigrate's default reporter. It recognizes if the current terminal is an interactive shell (or if it's a CI environment), if that's the case _no_ animations will be shown. + +The reporter is included by default and does not need to be installed separately. + +## Usage + +By default, Emigrate uses the "pretty" reporter, but it can also be explicitly set by using the `--reporter` flag. + + + + ```bash + npx emigrate --reporter pretty + ``` + + + ```bash + pnpm emigrate --reporter pretty + ``` + + + ```bash + yarn emigrate --reporter pretty + ``` + + + ```bash + bunx --bun emigrate --reporter pretty + ``` + + + ```json title="package.json" {3} + { + "scripts": { + "emigrate": "emigrate" + } + } + ``` + + ```bash + deno task emigrate --reporter pretty + ``` + + + +Or by setting it in the configuration file. + + + + ```js title="emigrate.config.js" + /** @type {import('@emigrate/cli').EmigrateConfig} */ + export default { + reporter: 'pretty', + }; + ``` + + + ```ts title="emigrate.config.ts" + import { type EmigrateConfig } from '@emigrate/cli'; + + const config: EmigrateConfig = { + reporter: 'pretty', + }; + + export default config; + ``` + + + +See Reporter Configuration for more information. + +## Example output + +```bash + +Emigrate up v0.17.2 /your/working/directory (dry run) + + 1 pending migrations to run + + › migration-folder/20231218135441244_create_some_table.sql (pending) + + 1 pending (1 total) + +``` diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx index 524e4d9..1f48e0f 100644 --- a/docs/src/content/docs/reference/configuration.mdx +++ b/docs/src/content/docs/reference/configuration.mdx @@ -45,9 +45,9 @@ Set the directory where your migrations are located, relative to the project roo ### `reporter` -**type:** `string | EmigrateReporter | Promise | (() => Promise)` +**type:** `"pretty" | "json" | string | EmigrateReporter | Promise | (() => Promise)` -**default:** `"default"` - the default reporter +**default:** `"pretty"` - the default reporter Set the reporter to use for the different commands. Specifying a reporter is most useful in a CI or production environment where you either ship logs or want to have a machine-readable format. @@ -64,6 +64,9 @@ export default { up: { reporter: 'json', }, + new: { + reporter: 'pretty', // Not really necessary, as it's the default + }, }; ```