boats-cli

boats-cli is the unofficial CLI for johndcarmichael/boats which makes it even easier to quickly setup and scaffold the BOATS files in a project.

Early alpha, docs and functionality will change

Table of Contents generated with DocToc

• Quick Start
• Custom Generator Overrides
• Development

Quick Start

1npx @acrontum/boats-cli --help
2npx @acrontum/boats-cli path --help
3npx @acrontum/boats-cli model --help
4npx @acrontum/boats-cli init --help

For an empty boats project:

1mkdir backend-spec
2
3cd backend-spec
4
5npm init --yes
6# npm i --save-dev boats @acrontum/boats-cli
7
8npx @acrontum/boats-cli \
9  path auth/verify --get \
10  path auth/login --post \
11  path auth/logout --get \
12  path auth/refresh-token --get \
13  path albums/:albumId --post --get --patch --delete --list \
14  path albums/:albumId/songs/:songId -crudl \
15  model jwt \
16  model search --type query
17
18npx boats -i src/index.yml -o build/api.json

optionally, since it's long to type:

1npm i --save-dev @acrontum/boats-cli

then you can just run npx bc model test --dry-run.

Custom Generator Overrides

You can override any of the generators by adding any files or exports to the templates option (--templates <folder_or_lib>).

Boats cli will try to import from the folling:

file	export
boats-rc.js	getBoatsRc
component-index.js	getComponentIndex
create.js	getCreate
delete.js	getDelete
index.js	getIndex
list.js	getList
model.js	getModel
models.js	getModels
pagination-model.js	getPaginationModel
param.js	getParam
path-index.js	getPathIndex
replace.js	getReplace
show.js	getShow
update.js	getUpdate

Multiple invocations of -T, --templates will merge / override the results of the templates, in the order supplied.

A module export might look like:

1exports.getBoatsRc = (opts, file) => { /* ... */ };
2exports.getIndex = (opts, file) => { /* ... */ };
3exports.getComponentIndex = (opts, file) => { /* ... */ };
4exports.getModel = (opts, file) => { /* ... */ };
5exports.getModels = (opts, file) => { /* ... */ };
6exports.getParam = (opts, file) => { /* ... */ };
7exports.getPaginationModel = (opts, file) => { /* ... */ };
8exports.getPathIndex = (opts, file) => { /* ... */ };
9exports.getList = (opts, file) => { /* ... */ };
10exports.getCreate = (opts, file) => { /* ... */ };
11exports.getShow = (opts, file) => { /* ... */ };
12exports.getDelete = (opts, file) => { /* ... */ };
13exports.getUpdate = (opts, file) => { /* ... */ };
14exports.getReplace = (opts, file) => { /* ... */ };

or overriding path <name> --list, a file templates/list.js or module with exports.getList:

1// @ts-check
2const { toYaml } = require('@acrontum/boats-cli/dist/src/lib');
3
4/** @type{import('@acrontum/boats-cli').CustomTemplates['getList']} */
5module.exports = (_globalOptions, file, pluralName, schemaRef, parameters) => {
6  return toYaml({
7    summary: `from ${file}`,
8    description: `pluralName ${pluralName}`,
9    ...(parameters?.length ? { parameters } : {}),
10    responses: {
11      '"200"': {
12        description: 'Success',
13        content: {
14          'application/json': {
15            schema: { $ref: schemaRef },
16          },
17        },
18      },
19    },
20  });
21};
22
23// or exports.getList = (_globalOptions, file, pluralName, schemaRef, parameters) => { ... }

or disabling the default generator and instead creating 2 different files for models (templates/model.yml or exports.getModel):

1// @ts-check
2const { toYaml } = require('@acrontum/boats-cli/dist/src/lib');
3const { writeFile, mkdir } = require('node:fs/promises');
4const { dirname, join } = require('node:path');
5
6/** @type{import('@acrontum/boats-cli').CustomTemplates['getModel']} */
7module.exports = async (globalOptions, file) => {
8  const base = join(globalOptions.output || '.', file.replace('model.yml', 'base.yml'));
9  const extend = join(globalOptions.output || '.', file.replace('model.yml', 'extend.yml'));
10
11  await mkdir(dirname(base), { recursive: true });
12
13  await Promise.all([
14    writeFile(
15      base,
16      toYaml({
17        type: 'object',
18        required: ['name'],
19        properties: {
20          name: { type: 'string' },
21        },
22      }),
23    ),
24    writeFile(
25      extend,
26      toYaml({
27        allOf: [
28          { $ref: './base.yml' },
29          {
30            type: 'object',
31            properties: {
32              id: {
33                type: 'string',
34                format: 'uuid',
35              },
36            },
37          },
38        ],
39      }),
40    ),
41  ]);
42
43  // prevent default generation
44  return '';
45};

see custom-models.spec.ts and the test overrides folder for more examples.

Development

Configure githooks:

1git config core.hooksPath $(git rev-parse --show-toplevel)/githooks/