Endpoint-builder NPM

Endpoint-builder

A simple tool for creating a typesafe .js file with an object that holds endpoints.

npm bundle size

About

Endpoint builder creates a .js file and .d.ts file of endpoints based on user config options. Endpoints can be strings or typesafe functions. Can read folder dirs for endpoints or paths can be added manually.

Built with maintaining endpoints across several apps in mind (fx frontend <-> backend)

Installation

npm i endpoint-builder

Add to your package.json scripts:

"scripts": {
    "build-endpoints": "endpoint-builder-init"
    ...
}

Run npm run build-endpoints

The first run will create a config file at the root of your project (i.e. the first folder to include node_modules) (endpoint.config.json). Run again after config to build files.

Usage

import ENDPOINTS from "endpoint-builder";

Output example

Typescript file which is compiled to js

type Example =
  | "an example of prefixing the file with additional types"
  | string;

const ENDPOINTS = {
  BACKEND: {
    GET: {
      AUTHOR: "/:id/:type",
      USER: "/:id/:type",
      POST: "/:id/:type",
    },
  },
  FRONTEND: {
    GET: {
      AUTHOR: (id: number, type: Example) => "author" + "/" + id + "/" + type,
      USER: (id: number, type: Example) => "user" + "/" + id + "/" + type,
      POST: (id: number, type: Example) => "post" + "/" + id + "/" + type,
    },
  },
};

export default ENDPOINTS;

Config options

Option	Description	Defaults	Type	Required
`const-name`	The name of the endpoint object.	`ENDPOINTS`	string	no
`file-prefixes`	Add any additional information to add to the beginning of the endpoints file such as types or imports	`""`	string[]	no
`slug-type`	The slug identifier that is used when endpoint suffixes are typed. *Must contain `slug`.*	`:idslug`	string	no
`include-path-name`	Include the path name in the endpoint. Can be overriden by parents	`false`	boolean	no
`copy-to-current-directory`	Will copy created files to the current writing directory paths.	`false`	boolean	no
`path-type`	The type of path the endpoint should return — function	`"string"`	"string" OR "function"	no
`parents`	Nests all paths under parent keys. Useful if you need a distinction between an `ENDPOINT.FRONTEND` and an `ENDPOINT.BACKEND`. More info here	`null`	Object	no
`paths`	Manually add endpoint paths as string array	`null`	string[]	no
`folders`	Read a directory to get path names. Will automatically remove file extensions. More info here.	`null`	Object	no
`endpoints`	The endpoint keys More info here.	Object	`null`	yes

For autocomplete help there is a json schema which can be found here: node_modules/endpoint-builder/endpoint.schema.json. Add as below to your endpoint.config.json file.

"$schema": "node_modules/endpoint-builder/endpoint.schema.json",

Endpoint options

Option	Description	Defaults	Type	Required
`excludeAll`	Will exclude all paths.	`false`	boolean	no
`exclude`	Will exclude paths.	`[]`	string[]	no
`include`	Will include paths.	`[]`	string[]	no
`suffix`	Suffixes to be added at the end of the path. Supports types IF followed by a colon: 'id:number', 'type:string', 'custom-suffix'	`""`	string[]	no
`custom`	Custom paths. Will include key name as uri-path. Accepts string array of suffixes	`null`	string[]	no

Folders options

Option	Description	Defaults	Type	Required
`path`	The path to the folder relative to the config file	`""`	string	no
`exclude`	The dir items to exclude	`[]`	string[]	no
`include`	The dir items to include	`[]`	string[]	no

Parents options

Option	Description	Defaults	Type	Required
`path-type`	The type of path the endpoint should return.	include-path-name (see above)	`"string" OR "function"`	no
`include-path-name`	Include the path name in the endpoint.	include-path-name (see above)	`boolean`	no

Example endpoint.json.config

{
  "$schema": "node_modules/endpoint-builder/endpoint.schema.json",
  "slug-type": ":*slug*",
  "include-path-name": false,
  "include-base-paths": true,
  "path-type": "string",
  "const-name": "ENDPOINTS",
  "endpoints": {
    "GET": {
      "suffix": ["id:number", "type:Example"]
    },
    "GET_ALL": {}
  },
  "file-prefixes": [
    "type Example = \"an example of prefixing the file with additional types\" | string"
  ],
  "folders": {
    "SRC": {
      "path": "backend/src"
    }
  },
  "parents": {
    "BACKEND": {
      "path-type": "string",
      "include-path-name": false
    },
    "FRONTEND": {
      "path-type": "function",
      "include-path-name": true
    }
  },
  "paths": ["user", "post"]
}

endpoints uri typescript

typescript

@infinitebrahmanuniverse/nolb-end @everything-registry/sub-chunk-1585

2 years ago

2 years ago

2 years ago

2 years ago