@karrotframe/pathfinder

code generator tool for routes by schema

• ✈️ handle routes with schema
• 🛠 enable to switch generator function

This repository is inspired by @daangn/generate-routes(private repository) of juyeong1260

• 한국어

Table of Contents

• Installation
• Usage
• CLI Options
• Entire Schema Definition
• Route Schema Definition
• Entire Schema Example
• Redefine onOpen callback for usage
• Register Schema

Installation

$ yarn add @karrotframe/pathfinder

Usage

$ yarn pathfinder init # create initial files
$ yarn pathfinder generate -s schema.json # generate code file from schema

CLI Option

• -s, --source : load json file defining schema

$ yarn pathfinder generate --source schema.json # load local json file

$ yarn pathfinder generate --source https://example.com/example.json # load remote json file

• -o, --output : Specify directory path to generate result file ( default: __generated__ )

$ yarn pathfinder generate -s schema.json  --output ./result

• -r, --replace : Replace generator function with specific module from npm package

$ yarn pathfinder generate -s schema.json -r custom-generator-name

• -u, --suffix : name to describe result type. First letter will be capitalized automatically ( default: Sdk )

$ yarn pathfinder generate -s schema.json -u result

• -d, --debug : Turn on debug mode to display all messages

$ yarn pathfinder generate -d

.pathfinderrc config file

A config file could be used instead of CLI option. Note that option of config file would be ignored when any same option have been declared from CLI option and from config file both.

• source : path for json schema file.
• output : path for generated result.
• replace : custom generator function with specific module from npm package to replace a basic built-in function.
• suffix : name to describe result type.
• repository : path for a repository to preserve schemas. It is explained at bottom section with more detail.

Entire Schema Definition

Route Schema Definition

queryParams example

{
  "type": "object",
  "properties": {
    "referrer": {
      "type": "string",
      "description": "tracking referrer page",
      "enum": ["guitar"]
    }
  },
  "required": ["referrer"],
  "additionalProperties": false
}

Entire Schema Example

{
  "name": "example",
  "description": "sdk for example route",
  "author": "John Doe",
  "endpoint": "https://example.com",
  "endpoints": {
    "prod": "https://example.prod.com"
  },
  "version": 1,
  "routes": [
    {
      "name": "guitar",
      "path": "/product/guitar/:guitarId",
      "description": "Method to open guitar detail page",
      "queryParams": {
        "additionalProperties": false
      }
    },
    {
      "name": "accessory",
      "path": "/product/accessory/:accessoryId",
      "description": "Method to open accessory detail page",
      "queryParams": {
        "type": "object",
        "properties": {
          "referrer": {
            "type": "string",
            "description": "tracking referrer page",
            "enum": ["guitar"]
          }
        },
        "required": ["referrer"],
        "additionalProperties": false
      }
    }
  ]
}

Redefine onOpen callback for usage

To customize methods, you should redefine onOpen callback.

import customRoute from 'customRoute'
import { makeExampleSdk } from '__generated__'

const { openRouteJobs } = makeExampleSdk({
  onOpen: (endpoint: string, path: string) => {
    const targetPath = endpoint + path
    this.bridge.router.push(targetPath)
  },
})

const handler = () => {
  const params = { newguitarId: 'constant' }
  openExampleGuitar(params)
}

Register Schema

❗ experimental ❗

You could register schema files to your custom repository with register command like below:

$ yarn pathfinder register https://example.com/schema -y https://schema-repository.com/example

You could use -y or --repository option on CLI to indicate an endpoint of schema repository,

or you could declare repository field in the config file.

But you should prepare a back-end system to preserve schemas with the repository.

register command is just a POST request as http method for any concise usage.

Therefore, you could use other commands like CURL instead, if you are already expert for that.