aboviq/emigrate
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

docs(reporters): add "json" reporter and rename "default" to "pretty"

Browse source
This commit is contained in:
Joakim Carlstein 2024-02-06 09:17:22 +01:00 • committed by Joakim Carlstein
parent 18382ce961
commit b62c692846
13 changed files with 249 additions and 34 deletions
Download patch file Download diff file Expand all files Collapse all files

5
.changeset/cyan-cows-cheer.md Normal file
View file

@ -0,0 +1,5 @@
---
'@emigrate/docs': minor
---
Add documentation for the built-in "json" reporter

5
.changeset/pink-bobcats-prove.md Normal file
View file

@ -0,0 +1,5 @@
---
'@emigrate/docs': minor
---
The "default" reporter is now named "pretty"

8
docs/astro.config.mjs
View file

@ -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',

3
docs/src/content/docs/commands/list.mdx
View file

@ -86,6 +86,9 @@ In case you have both a `emigrate-storage-somedb` and a `somedb` package install
### `-r`, `--reporter <name>`
**type:** `"pretty" | "json" | string`
**default:** `"pretty"`
The <Link href="/plugins/reporters/">reporter</Link> 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:

3
docs/src/content/docs/commands/new.mdx
View file

@ -101,6 +101,9 @@ In case you have both a `emigrate-plugin-someplugin` and a `someplugin` package
### `-r`, `--reporter <name>`
**type:** `"pretty" | "json" | string`
**default:** `"pretty"`
The <Link href="/plugins/reporters/">reporter</Link> 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:

3
docs/src/content/docs/commands/remove.mdx
View file

@ -95,6 +95,9 @@ In case you have both a `emigrate-storage-somedb` and a `somedb` package install
### `-r`, `--reporter <name>`
**type:** `"pretty" | "json" | string`
**default:** `"pretty"`
The <Link href="/plugins/reporters/">reporter</Link> 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:

3
docs/src/content/docs/commands/up.mdx
View file

@ -147,6 +147,9 @@ In case you have both a `emigrate-plugin-someplugin` and a `someplugin` package
### `-r`, `--reporter <name>`
**type:** `"pretty" | "json" | string`
**default:** `"pretty"`
The <Link href="/plugins/reporters/">reporter</Link> 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:

23
docs/src/content/docs/plugins/reporters/default.mdx
View file

@ -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)
```

5
docs/src/content/docs/plugins/reporters/index.mdx
View file

@ -20,6 +20,7 @@ Or set it up in your configuration file, see <Link href="/reference/configuratio
## Available Reporters
<CardGrid>
<LinkCard title="Default Reporter" href="default/" />
<LinkCard title="Pino Reporter" href="pino/" />
<LinkCard title="Pretty Reporter" description="The default reporter" href="pretty/" />
<LinkCard title="JSON Reporter" description="A built-in reporter for outputing a JSON object" href="json/" />
<LinkCard title="Pino Reporter" description="A reporter package for outputting new line delimited JSON" href="pino/" />
</CardGrid>

102
docs/src/content/docs/plugins/reporters/json.mdx Normal file
View file

@ -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
<Tabs>
<TabItem label="npm">
```bash
npx emigrate <command> --reporter json
```
</TabItem>
<TabItem label="pnpm">
```bash
pnpm emigrate <command> --reporter json
```
</TabItem>
<TabItem label="yarn">
```bash
yarn emigrate <command> --reporter json
```
</TabItem>
<TabItem label="bun">
```bash
bunx --bun emigrate <command> --reporter json
```
</TabItem>
<TabItem label="deno">
```json title="package.json" {3}
{
"scripts": {
"emigrate": "emigrate"
}
}
```
```bash
deno task emigrate <command> --reporter json
```
</TabItem>
</Tabs>
See for instance the <Link href="/commands/up/#-r---reporter-name">Reporter Option</Link> for the `up` command for more information.
### Via configuration file
<Tabs>
<TabItem label="JavaScript">
```js title="emigrate.config.js"
/** @type {import('@emigrate/cli').EmigrateConfig} */
export default {
reporter: 'json',
};
```
</TabItem>
<TabItem label="TypeScript">
```ts title="emigrate.config.ts"
import { type EmigrateConfig } from '@emigrate/cli';
const config: EmigrateConfig = {
reporter: 'json',
};
export default config;
```
</TabItem>
</Tabs>
See <Link href="/reference/configuration/#reporter">Reporter Configuration</Link> 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
}
]
}
```

18
docs/src/content/docs/plugins/reporters/pino.mdx
View file

@ -91,11 +91,27 @@ See for instance the <Link href="/commands/up/#-r---reporter-name">Reporter Opti
### Via configuration file
```js title="emigrate.config.js" {2}
<Tabs>
<TabItem label="JavaScript">
```js title="emigrate.config.js"
/** @type {import('@emigrate/cli').EmigrateConfig} */
export default {
reporter: 'pino',
};
```
</TabItem>
<TabItem label="TypeScript">
```ts title="emigrate.config.ts"
import { type EmigrateConfig } from '@emigrate/cli';
const config: EmigrateConfig = {
reporter: 'pino',
};
export default config;
```
</TabItem>
</Tabs>
See <Link href="/reference/configuration/#reporter">Reporter Configuration</Link> for more information.

90
docs/src/content/docs/plugins/reporters/pretty.mdx Normal file
View file

@ -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 <Link href="/commands/up/#-r---reporter-name">`--reporter`</Link> flag.
<Tabs>
<TabItem label="npm">
```bash
npx emigrate <command> --reporter pretty
```
</TabItem>
<TabItem label="pnpm">
```bash
pnpm emigrate <command> --reporter pretty
```
</TabItem>
<TabItem label="yarn">
```bash
yarn emigrate <command> --reporter pretty
```
</TabItem>
<TabItem label="bun">
```bash
bunx --bun emigrate <command> --reporter pretty
```
</TabItem>
<TabItem label="deno">
```json title="package.json" {3}
{
"scripts": {
"emigrate": "emigrate"
}
}
```
```bash
deno task emigrate <command> --reporter pretty
```
</TabItem>
</Tabs>
Or by setting it in the configuration file.
<Tabs>
<TabItem label="JavaScript">
```js title="emigrate.config.js"
/** @type {import('@emigrate/cli').EmigrateConfig} */
export default {
reporter: 'pretty',
};
```
</TabItem>
<TabItem label="TypeScript">
```ts title="emigrate.config.ts"
import { type EmigrateConfig } from '@emigrate/cli';
const config: EmigrateConfig = {
reporter: 'pretty',
};
export default config;
```
</TabItem>
</Tabs>
See <Link href="/reference/configuration/#reporter">Reporter Configuration</Link> 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)
```

7
docs/src/content/docs/reference/configuration.mdx
View file

@ -45,9 +45,9 @@ Set the directory where your migrations are located, relative to the project roo
### `reporter`
**type:** `string | EmigrateReporter | Promise<EmigrateReporter> | (() => Promise<EmigrateReporter>)`
**type:** `"pretty" | "json" | string | EmigrateReporter | Promise<EmigrateReporter> | (() => Promise<EmigrateReporter>)`
**default:** `"default"` - the default reporter
**default:** `"pretty"` - the default reporter
Set the reporter to use for the different commands. Specifying a <Link href="/plugins/reporters/">reporter</Link> 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
},
};
```