{"id":23050526,"url":"https://github.com/acrontum/boats-utils","last_synced_at":"2025-07-22T07:34:41.873Z","repository":{"id":38236168,"uuid":"492420648","full_name":"acrontum/boats-utils","owner":"acrontum","description":"Common boats templating utils","archived":false,"fork":false,"pushed_at":"2024-09-25T12:36:47.000Z","size":165,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-24T04:38:12.429Z","etag":null,"topics":["internal-development"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acrontum.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-15T07:45:16.000Z","updated_at":"2024-09-25T12:25:07.000Z","dependencies_parsed_at":"2024-12-15T23:33:31.691Z","dependency_job_id":"a1e42e6e-fdb9-48b4-9eb1-bfa61b2cbe4a","html_url":"https://github.com/acrontum/boats-utils","commit_stats":{"total_commits":9,"total_committers":2,"mean_commits":4.5,"dds":0.2222222222222222,"last_synced_commit":"8021f301275cce65b5fb08bc00296b716a471392"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/acrontum/boats-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acrontum%2Fboats-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acrontum%2Fboats-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acrontum%2Fboats-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acrontum%2Fboats-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acrontum","download_url":"https://codeload.github.com/acrontum/boats-utils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acrontum%2Fboats-utils/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266448499,"owners_count":23930222,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["internal-development"],"created_at":"2024-12-15T23:33:24.200Z","updated_at":"2025-07-22T07:34:41.850Z","avatar_url":"https://github.com/acrontum.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Boats utils\n\nCollection of useful boats template helpers to be used with [j-d-carmichael/boats](https://github.com/j-d-carmichael/boats).\n\n\u003c!--\nnpx doctoc --github readme.md\n--\u003e\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n- [Usage](#usage)\n- [Modules](#modules)\n  - [`extend`](#extend)\n    - [Examples](#examples)\n  - [`database-entry`](#database-entry)\n    - [Examples](#examples-1)\n  - [`pagination`](#pagination)\n    - [Examples](#examples-2)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Usage\n\n```bash\nnpm install @acrontum/boats-utils\n````\n\nIn your openapi boats project, simply include this module as a helper in your build command:\n\n```json\n{\n  \"name\": \"service-openapi-spec\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Some boats openapi builder\",\n  \"scripts\": {\n    \"prebuild\": \"rm -rf build\",\n    \"build\": \"NODE_ENV=test boats --yes -f node_modules/@acrontum/boats-utils/dist -i ./src/index.yml -o ./build/api.yml\",\n    \"postbuild\": \"cp build/api*.yml ./release/$npm_package_name.yml\"\n  },\n  \"keywords\": [],\n  \"author\": \"p-mcgowan\",\n  \"devDependencies\": {\n    \"boats\": \"^2.25.0\",\n    \"@acrontum/boats-utils\": \"^1.0.0\"\n  }\n}\n```\n\n## Modules\n\n\n### [`extend`](./src/extend.ts)\n\nExtend a base model with additional, omitted, required, and / or optional fields.\n\n```yaml\n# model.yml\n\ntype: object\nproperties:\n  id:\n    type: string\n    format: uuid\n  name:\n    type: string\n  email:\n    type: string\n    format: email\n  profilePicture:\n    type: string\n    format: uri\n  # ...\n```\n\n```yaml\n# postModel.yml\n\n{{\n  extend('./model.yml', {\n    omit: [\n      'properties.id'\n    ],\n    require: [\n      'properties.name',\n      'properties.email'\n    ],\n    include: [\n      ['properties.username', { type: 'string', 'x-unique': true }]\n    ],\n    optional: [\n      'properties.dateOfBirth'\n    ]\n  })\n}}\n```\n\n#### Examples\n---\n\nRemoving fields from the model:\n\n```yaml\n# model.yml\n\ntype: object\nrequired:\n  - id\nproperties:\n  id:\n    type: string\n    format: uuid\n  createdAt:\n    type: string\n    format: date-time\n  updatedAt:\n    type: string\n    format: date-time\n  name:\n    type: string\n  email:\n    type: string\n    format: email\n  profilePicture:\n    type: string\n    format: uri\n```\n\n```yaml\n# postModel.yml\n\n{{\n  extend('./model.yml', {\n    omit: [\n      'properties.id',\n      'properties.createdAt',\n      'properties.updatedAt'\n    ]\n  })\n}}\n```\n\nWould output:\n```yaml\ntype: object\nproperties:\n  name:\n    type: string\n  email:\n    type: string\n    format: email\n  profilePicture:\n    type: string\n    format: uri\n```\n---\n\nAdding fields to the model:\n\n```yaml\n# model.yml\n\ntype: object\nproperties:\n  name:\n    type: string\n  email:\n    type: string\n    format: email\n  profilePicture:\n    type: string\n    format: uri\n```\n\n```yaml\n# postModel.yml\n{{\n  extend('./model.yml', {\n    include: [\n      ['properties.password', { type: 'string', minLength: 32 }]\n    ]\n  })\n}}\n```\n\nWould output:\n```yaml\ntype: object\nproperties:\n  name:\n    type: string\n  email:\n    type: string\n    format: email\n  profilePicture:\n    type: string\n    format: uri\n  password:\n    type: string\n    minLength: 32\n```\n---\n\nMarking fields as required:\n\n```yaml\n# model.yml\n\ntype: object\nproperties:\n  name:\n    type: string\n  email:\n    type: string\n    format: email\n  profilePicture:\n    type: string\n    format: uri\n```\n\n```yaml\n# postModel.yml\n\n{{\n  extend('./model.yml', {\n    require: [\n      'properties.email',\n      'properties.name'\n    ]\n  })\n}}\n```\n\nWould output:\n```yaml\ntype: object\nrequired:\n  - name\n  - email\nproperties:\n  name:\n    type: string\n  email:\n    type: string\n    format: email\n  profilePicture:\n    type: string\n    format: uri\n```\n---\n\nMarking fields as optional:\n\n```yaml\n# model.yml\n\ntype: object\nrequire:\n  - name\n  - email\n  - profilePicture\nproperties:\n  name:\n    type: string\n  email:\n    type: string\n    format: email\n  profilePicture:\n    type: string\n    format: uri\n```\n\n```yaml\n# postModel.yml\n\n{{\n  extend('./model.yml', {\n    optional: [\n      'properties.profilePicture'\n    ]\n  })\n}}\n```\n\nWould output:\n```yaml\ntype: object\nrequired:\n  - name\n  - email\nproperties:\n  name:\n    type: string\n  email:\n    type: string\n    format: email\n  profilePicture:\n    type: string\n    format: uri\n```\n---\n\n### [`database-entry`](./src/database-entry.ts)\n\nAdds common DB fields to a model.\n\n```yaml\ntype: object\nproperties:\n  {{ databaseentry(\u003coptions\u003e) }}\n  otherProps:\n    type: string\n  # ...\n```\n\n#### Examples\n---\n\nWith no params:\n\n```yaml\n# model.yml\n\ntype: object\nproperties:\n  {{ databaseentry() }}\n  name:\n    type: string\n  profilePicture:\n    type: string\n    format: uri\n```\n\nWould output:\n```yaml\ntype: object\nproperties:\n  id:\n    type: string\n    format: uuid\n  createdAt:\n    type: string\n    format: date-time\n  updatedAt:\n    type: string\n    format: date-time\n  name:\n    type: string\n  profilePicture:\n    type: string\n```\n---\n\nTo specifiy the id type:\n\n```yaml\n# model.yml\n\ntype: object\nproperties:\n  {{ databaseentry({ id: 'string' }) }}\n# {{ databaseentry({ id: 'number' }) }}\n  name:\n    type: string\n  profilePicture:\n    type: string\n    format: uri\n```\n\nWould output:\n```yaml\ntype: object\nproperties:\n  id:\n    type: string\n#   type: number\n  createdAt:\n    type: string\n    format: date-time\n  updatedAt:\n    type: string\n    format: date-time\n  name:\n    type: string\n  profilePicture:\n    type: string\n```\n\n---\n\nWith softDeletion:\n\n```yaml\n# model.yml\n\ntype: object\nproperties:\n  {{ databaseentry({ softDeletion: true }) }}\n  name:\n    type: string\n  profilePicture:\n    type: string\n    format: uri\n```\n\nWould output:\n```yaml\ntype: object\nproperties:\n  id:\n    type: string\n    format: uuid\n  createdAt:\n    type: string\n    format: date-time\n  updatedAt:\n    type: string\n    format: date-time\n  deletedAt:\n    type: string\n    format: date-time\n  name:\n    type: string\n  profilePicture:\n    type: string\n```\n\n### [`pagination`](./src/pagination.ts)\n\nAdds a collection-type pagination model.\n\n```yaml\n{{ pagination(\u003cpath_or_options\u003e) }}\n```\n\n#### Examples\n---\n\nWith no params:\n\n```yaml\n# components/schemas/user/model.yml\n\ntype: object\nproperties:\n  name:\n    type: string\n  numberOfDogs:\n    type: number\n```\n\n```yaml\n# components/schemas/user/models.yml\n\n{{ pagination() }}\n```\n\nWould output:\n```yaml\ntype: object\nrequired:\n  - meta\n  - data\nproperties:\n  meta:\n    $ref: \"#/components/schemas/Meta\"\n  data:\n    type: array\n    items: \n      $ref: \"./model.yml\"\n```\n\n---\n\nTo specify another model name:\n\n```yaml\n# components/schemas/user/singleUserResponse.yml\n\ntype: object\nproperties:\n  name:\n    type: string\n  numberOfDogs:\n    type: number\n```\n\n```yaml\n# components/schemas/user/models.yml\n\n{{ pagination({ path: \"./singleUserResponse.yml\" }) }}\n```\nor simply\n```yaml\n{{ pagination(\"./singleUserResponse.yml\") }}\n```\n\nWould output:\n```yaml\ntype: object\nrequired:\n  - meta\n  - data\nproperties:\n  meta:\n    $ref: \"#/components/schemas/Meta\"\n  data:\n    type: array\n    items: \n      $ref: \"./singleUserResponse.yml\"\n```\n\n---\n\nTo specify another pagination model:\n\n```yaml\n# components/schemas/user/singleUserResponse.yml\n\ntype: object\nproperties:\n  name:\n    type: string\n  numberOfDogs:\n    type: number\n```\n\n```yaml\n# components/schemas/user/models.yml\n\n{{ pagination({ paginationModel: \"#/components/schemas/Pagination\" }) }}\n```\n\nWould output:\n```yaml\ntype: object\nrequired:\n  - meta\n  - data\nproperties:\n  meta:\n    $ref: \"#/components/schemas/Pagination\"\n  data:\n    type: array\n    items: \n      $ref: \"./model.yml\"\n```\n\n---\n\nTo alter or remove required fields:\n\n```yaml\n# components/schemas/user/singleUserResponse.yml\n\ntype: object\nproperties:\n  name:\n    type: string\n  numberOfDogs:\n    type: number\n```\n\n```yaml\n# components/schemas/user/models.yml\n\n{{ pagination({ required: ['meta'] }) }}\n```\n\nWould output:\n```yaml\ntype: object\nrequired:\n  - meta\nproperties:\n  meta:\n    $ref: \"#/components/schemas/Pagination\"\n  data:\n    type: array\n    items: \n      $ref: \"./model.yml\"\n```\n\n```yaml\n# components/schemas/user/models.yml\n\n{{ pagination({ required: [] }) }}\n```\n\nWould output:\n```yaml\ntype: object\nproperties:\n  meta:\n    $ref: \"#/components/schemas/Pagination\"\n  data:\n    type: array\n    items: \n      $ref: \"./model.yml\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facrontum%2Fboats-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facrontum%2Fboats-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facrontum%2Fboats-utils/lists"}