https://github.com/acrontum/boats-utils
Common boats templating utils
https://github.com/acrontum/boats-utils
internal-development
Last synced: 11 months ago
JSON representation
Common boats templating utils
- Host: GitHub
- URL: https://github.com/acrontum/boats-utils
- Owner: acrontum
- Created: 2022-05-15T07:45:16.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-09-25T12:36:47.000Z (almost 2 years ago)
- Last Synced: 2025-04-24T04:38:12.429Z (about 1 year ago)
- Topics: internal-development
- Language: TypeScript
- Homepage:
- Size: 161 KB
- Stars: 2
- Watchers: 4
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# Boats utils
Collection of useful boats template helpers to be used with [j-d-carmichael/boats](https://github.com/j-d-carmichael/boats).
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
- [Usage](#usage)
- [Modules](#modules)
- [`extend`](#extend)
- [Examples](#examples)
- [`database-entry`](#database-entry)
- [Examples](#examples-1)
- [`pagination`](#pagination)
- [Examples](#examples-2)
## Usage
```bash
npm install @acrontum/boats-utils
````
In your openapi boats project, simply include this module as a helper in your build command:
```json
{
"name": "service-openapi-spec",
"version": "1.0.0",
"description": "Some boats openapi builder",
"scripts": {
"prebuild": "rm -rf build",
"build": "NODE_ENV=test boats --yes -f node_modules/@acrontum/boats-utils/dist -i ./src/index.yml -o ./build/api.yml",
"postbuild": "cp build/api*.yml ./release/$npm_package_name.yml"
},
"keywords": [],
"author": "p-mcgowan",
"devDependencies": {
"boats": "^2.25.0",
"@acrontum/boats-utils": "^1.0.0"
}
}
```
## Modules
### [`extend`](./src/extend.ts)
Extend a base model with additional, omitted, required, and / or optional fields.
```yaml
# model.yml
type: object
properties:
id:
type: string
format: uuid
name:
type: string
email:
type: string
format: email
profilePicture:
type: string
format: uri
# ...
```
```yaml
# postModel.yml
{{
extend('./model.yml', {
omit: [
'properties.id'
],
require: [
'properties.name',
'properties.email'
],
include: [
['properties.username', { type: 'string', 'x-unique': true }]
],
optional: [
'properties.dateOfBirth'
]
})
}}
```
#### Examples
---
Removing fields from the model:
```yaml
# model.yml
type: object
required:
- id
properties:
id:
type: string
format: uuid
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
name:
type: string
email:
type: string
format: email
profilePicture:
type: string
format: uri
```
```yaml
# postModel.yml
{{
extend('./model.yml', {
omit: [
'properties.id',
'properties.createdAt',
'properties.updatedAt'
]
})
}}
```
Would output:
```yaml
type: object
properties:
name:
type: string
email:
type: string
format: email
profilePicture:
type: string
format: uri
```
---
Adding fields to the model:
```yaml
# model.yml
type: object
properties:
name:
type: string
email:
type: string
format: email
profilePicture:
type: string
format: uri
```
```yaml
# postModel.yml
{{
extend('./model.yml', {
include: [
['properties.password', { type: 'string', minLength: 32 }]
]
})
}}
```
Would output:
```yaml
type: object
properties:
name:
type: string
email:
type: string
format: email
profilePicture:
type: string
format: uri
password:
type: string
minLength: 32
```
---
Marking fields as required:
```yaml
# model.yml
type: object
properties:
name:
type: string
email:
type: string
format: email
profilePicture:
type: string
format: uri
```
```yaml
# postModel.yml
{{
extend('./model.yml', {
require: [
'properties.email',
'properties.name'
]
})
}}
```
Would output:
```yaml
type: object
required:
- name
- email
properties:
name:
type: string
email:
type: string
format: email
profilePicture:
type: string
format: uri
```
---
Marking fields as optional:
```yaml
# model.yml
type: object
require:
- name
- email
- profilePicture
properties:
name:
type: string
email:
type: string
format: email
profilePicture:
type: string
format: uri
```
```yaml
# postModel.yml
{{
extend('./model.yml', {
optional: [
'properties.profilePicture'
]
})
}}
```
Would output:
```yaml
type: object
required:
- name
- email
properties:
name:
type: string
email:
type: string
format: email
profilePicture:
type: string
format: uri
```
---
### [`database-entry`](./src/database-entry.ts)
Adds common DB fields to a model.
```yaml
type: object
properties:
{{ databaseentry() }}
otherProps:
type: string
# ...
```
#### Examples
---
With no params:
```yaml
# model.yml
type: object
properties:
{{ databaseentry() }}
name:
type: string
profilePicture:
type: string
format: uri
```
Would output:
```yaml
type: object
properties:
id:
type: string
format: uuid
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
name:
type: string
profilePicture:
type: string
```
---
To specifiy the id type:
```yaml
# model.yml
type: object
properties:
{{ databaseentry({ id: 'string' }) }}
# {{ databaseentry({ id: 'number' }) }}
name:
type: string
profilePicture:
type: string
format: uri
```
Would output:
```yaml
type: object
properties:
id:
type: string
# type: number
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
name:
type: string
profilePicture:
type: string
```
---
With softDeletion:
```yaml
# model.yml
type: object
properties:
{{ databaseentry({ softDeletion: true }) }}
name:
type: string
profilePicture:
type: string
format: uri
```
Would output:
```yaml
type: object
properties:
id:
type: string
format: uuid
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
deletedAt:
type: string
format: date-time
name:
type: string
profilePicture:
type: string
```
### [`pagination`](./src/pagination.ts)
Adds a collection-type pagination model.
```yaml
{{ pagination() }}
```
#### Examples
---
With no params:
```yaml
# components/schemas/user/model.yml
type: object
properties:
name:
type: string
numberOfDogs:
type: number
```
```yaml
# components/schemas/user/models.yml
{{ pagination() }}
```
Would output:
```yaml
type: object
required:
- meta
- data
properties:
meta:
$ref: "#/components/schemas/Meta"
data:
type: array
items:
$ref: "./model.yml"
```
---
To specify another model name:
```yaml
# components/schemas/user/singleUserResponse.yml
type: object
properties:
name:
type: string
numberOfDogs:
type: number
```
```yaml
# components/schemas/user/models.yml
{{ pagination({ path: "./singleUserResponse.yml" }) }}
```
or simply
```yaml
{{ pagination("./singleUserResponse.yml") }}
```
Would output:
```yaml
type: object
required:
- meta
- data
properties:
meta:
$ref: "#/components/schemas/Meta"
data:
type: array
items:
$ref: "./singleUserResponse.yml"
```
---
To specify another pagination model:
```yaml
# components/schemas/user/singleUserResponse.yml
type: object
properties:
name:
type: string
numberOfDogs:
type: number
```
```yaml
# components/schemas/user/models.yml
{{ pagination({ paginationModel: "#/components/schemas/Pagination" }) }}
```
Would output:
```yaml
type: object
required:
- meta
- data
properties:
meta:
$ref: "#/components/schemas/Pagination"
data:
type: array
items:
$ref: "./model.yml"
```
---
To alter or remove required fields:
```yaml
# components/schemas/user/singleUserResponse.yml
type: object
properties:
name:
type: string
numberOfDogs:
type: number
```
```yaml
# components/schemas/user/models.yml
{{ pagination({ required: ['meta'] }) }}
```
Would output:
```yaml
type: object
required:
- meta
properties:
meta:
$ref: "#/components/schemas/Pagination"
data:
type: array
items:
$ref: "./model.yml"
```
```yaml
# components/schemas/user/models.yml
{{ pagination({ required: [] }) }}
```
Would output:
```yaml
type: object
properties:
meta:
$ref: "#/components/schemas/Pagination"
data:
type: array
items:
$ref: "./model.yml"
```