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

npx @acrontum/boats-cli --help
npx @acrontum/boats-cli path --help
npx @acrontum/boats-cli model --help
npx @acrontum/boats-cli init --help

For an empty boats project:

mkdir backend-spec

cd backend-spec

npm init --yes
# npm i --save-dev boats @acrontum/boats-cli

npx @acrontum/boats-cli \
  path auth/verify --get \
  path auth/login --post \
  path auth/logout --get \
  path auth/refresh-token --get \
  path albums/:albumId --post --get --patch --delete --list \
  path albums/:albumId/songs/:songId -crudl \
  model jwt \
  model search --type query

npx boats -i src/index.yml -o build/api.json

optionally, since it's long to type:

npm 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:

exports.getBoatsRc = (opts, file) => { /* ... */ };
exports.getIndex = (opts, file) => { /* ... */ };
exports.getComponentIndex = (opts, file) => { /* ... */ };
exports.getModel = (opts, file) => { /* ... */ };
exports.getModels = (opts, file) => { /* ... */ };
exports.getParam = (opts, file) => { /* ... */ };
exports.getPaginationModel = (opts, file) => { /* ... */ };
exports.getPathIndex = (opts, file) => { /* ... */ };
exports.getList = (opts, file) => { /* ... */ };
exports.getCreate = (opts, file) => { /* ... */ };
exports.getShow = (opts, file) => { /* ... */ };
exports.getDelete = (opts, file) => { /* ... */ };
exports.getUpdate = (opts, file) => { /* ... */ };
exports.getReplace = (opts, file) => { /* ... */ };

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

// @ts-check
const { toYaml } = require('@acrontum/boats-cli/dist/src/lib');

/** @type{import('@acrontum/boats-cli').CustomTemplates['getList']} */
module.exports = (_globalOptions, file, pluralName, schemaRef, parameters) => {
  return toYaml({
    summary: `from ${file}`,
    description: `pluralName ${pluralName}`,
    ...(parameters?.length ? { parameters } : {}),
    responses: {
      '"200"': {
        description: 'Success',
        content: {
          'application/json': {
            schema: { $ref: schemaRef },
          },
        },
      },
    },
  });
};

// or exports.getList = (_globalOptions, file, pluralName, schemaRef, parameters) => { ... }

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

// @ts-check
const { toYaml } = require('@acrontum/boats-cli/dist/src/lib');
const { writeFile, mkdir } = require('node:fs/promises');
const { dirname, join } = require('node:path');

/** @type{import('@acrontum/boats-cli').CustomTemplates['getModel']} */
module.exports = async (globalOptions, file) => {
  const base = join(globalOptions.output || '.', file.replace('model.yml', 'base.yml'));
  const extend = join(globalOptions.output || '.', file.replace('model.yml', 'extend.yml'));

  await mkdir(dirname(base), { recursive: true });

  await Promise.all([
    writeFile(
      base,
      toYaml({
        type: 'object',
        required: ['name'],
        properties: {
          name: { type: 'string' },
        },
      }),
    ),
    writeFile(
      extend,
      toYaml({
        allOf: [
          { $ref: './base.yml' },
          {
            type: 'object',
            properties: {
              id: {
                type: 'string',
                format: 'uuid',
              },
            },
          },
        ],
      }),
    ),
  ]);

  // prevent default generation
  return '';
};

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

Development

Configure githooks:

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