docs: enhance documentation: summary new version

imjuni · Feb 6, 2024 · 658eab0 · 658eab0
1 parent 9de5a98
commit 658eab0
Show file tree

Hide file tree

Showing 5 changed files with 70 additions and 64 deletions.
diff --git a/README.md b/README.md
@@ -14,12 +14,13 @@
 
 Why `fast-maker`?
 
-fastify.js already have auto route mechanics using [fastify-autoload](https://github.com/fastify/fastify-autoload). But why you have to use `fast-maker`?
+fastify.js already have excellent auto route mechanics using [fastify-autoload](https://github.com/fastify/fastify-autoload). But why you have to use `fast-maker`?
 
+1. Zero cost in Run-Time.
 1. [Static analysis](https://en.wikipedia.org/wiki/Static_program_analysis): `fast-maker` generate TypeScript source code. Because it help to find error in compile-time, not runtime
-2. Complex Variable: You can use like that: `/person/[kind]-[id]/`. It help to get id and kind of id, for example serial-number and id or db-pk and id
-3. Next.js: `fast-maker` use the same mechanics as [Next.js](https://nextjs.org/docs/routing/introduction)
-4. `fast-maker` support a beautiful cli-interface
+1. Flexable Routing: You can use like that: `/person/[kind]-[id]/`. It help to get id and kind of id, for example serial-number and id or db-pk and id, even if you can use regular expression.
+1. Unifying how route paths are built: `fast-maker` use the same mechanics as [Next.js](https://nextjs.org/docs/routing/introduction). Route paths using file-system cannot be developer-specific
+1. `fast-maker` support a beautiful cli-interface
 
 ## Table of Contents <!-- omit in toc -->
 
@@ -88,9 +89,6 @@ npx fast-maker --help
 # display help for route commands
 npx fast-maker route --help
 
-# display help for watch commands
-npx fast-maker watch --help
-
 # display help for init commands
 npx fast-maker init --help
 ```
@@ -107,26 +105,29 @@ use file-system.
 
 ```text
 handlers/
-├─ get/
-│  ├─ hero/
-│  │  ├─ [name].ts
-├─ post/
-│  ├─ hero.ts
-├─ put/
-│  ├─ hero/
-│  │  ├─ [name].ts
-├─ delete/
-│  ├─ hero/
-│  │  ├─ [name].ts
+├─ superheros/
+│  ├─ [id]/
+│  │  ├─ powers/
+│  │  │  ├─ [id]/
+│  │  │  │  ├─ delete.ts
+│  │  │  │  ├─ get.ts
+│  │  │  │  ├─ put.ts
+│  │  │  ├─ post.ts
+│  │  ├─ delete.ts
+│  │  ├─ get.ts
+│  │  ├─ put.ts
+│  ├─ get.ts
+│  ├─ post.ts
 ```
 
-`get`, `post`, `put`, `delete` directory represent _HTTP Method_. Also you can use `options`, `patch`, `head`, `all` directory.
+`get`, `post`, `put`, `delete` filename represent _HTTP Method_. Also you can use `options`, `patch`, `head`, `all` filename.
 
 ### Route options
 
 You can pass `RouteShorthandOptions` option like that,
 
 ```ts
+// When not using a `fastify` instance, you can declare it as a variable like this
 export const option: RouteShorthandOptions = {
   schema: {
     querystring: schema.properties?.Querystring,
@@ -135,6 +136,22 @@ export const option: RouteShorthandOptions = {
 };
 ```
 
+```ts
+// When using the `fastify` instance, you can declare it as a function like this
+export const option = (fastify: FastifyInstance): RouteShorthandOptions => {
+  return {
+    schema: {
+      querystring: schema.properties?.Querystring,
+      body: schema.properties?.Body,
+    },
+     preHandler: fastify.auth([
+      fastify.allowAnonymous,
+      fastify.verifyBearerAuth
+    ]),
+  };
+};
+```
+
 You have to `named export` and variable name must be a `option`.
 
 ### Route handler
@@ -145,7 +162,7 @@ You can pass route handler function like that,
 import { FastifyRequest } from 'fastify';
 import type { IReqSearchPokemonQuerystring, IReqSearchPokemonParams } from '../../interface/IReqSearchPokemon';
 
-export default async function (
+export async function handler(
   req: FastifyRequest<{ Querystring: IReqSearchPokemonQuerystring; Params: IReqSearchPokemonParams }>,
 ) {
   console.debug(req.query);
@@ -155,26 +172,27 @@ export default async function (
 }
 ```
 
-You have to `non-named export` (aka default export). Also you can use arrow function and you can use any name under TypeScript function name rule, as well as type arguments perfectly applied on route configuration
+You have to `named export` and variable name must be a `handler`. Also you can use arrow function and you can use any name under TypeScript function name rule, as well as type arguments perfectly applied on route configuration
 
 ### Variable in Route Path
 
 File or Directory name surrounded square bracket like that,
 
 ```text
 handlers/
-├─ get/
-│  ├─ hero/
-│  │  ├─ [name].ts
+├─ superheros/
+│  ├─ [id]/
+│  │  ├─ get.ts
+│  │  ├─ put.ts
 ```
 
-Complex variable, No problem.
+Multiple variable, No problem.
 
 ```text
 handlers/
-├─ get/
-│  ├─ hero/
-│  │  ├─ [affiliation]-[name].ts
+├─ superheros/
+│  ├─ [kind]-[id]/
+│  │  ├─ get.ts
 ```
 
 This route path access like that: `curl http://localhost:8080/hero/marvel-ironman`
@@ -192,10 +210,10 @@ A complete example of using `fast-maker` can be found at [Ma-eum](https://github
 
 ## Roadmaps
 
-- [ ] display each route path in cli-table
+- [x] display each route path in cli-table
 - [ ] add new option silent
 - [ ] documentation site
-- [ ] add more test
+- [x] add more test
 
 ## License
 

diff --git a/docs/advance.md b/docs/advance.md
@@ -47,8 +47,8 @@ Hash create by resolved full-directory. And hash use crypto.createHmac function.
 fast-maker support FastifyRequest type argument. see below.
 
 ```ts
-// get/poke/world.ts
-const world = async (
+// poke/world/get.ts
+export const handler = async (
   req: FastifyRequest<
     {
       Querystring: IReqPokeHello['Querystring'];
@@ -77,11 +77,9 @@ const world = async (
 };
 
 // generated code
-fastify.get<{
-  // if IReqPokeHello interface in your typescript project, fast-maker append postfix hash.
-  // Because error prevent raise by same name interface import
-  Querystring: IReqPokeHello_052A3A1D6C6D4FFC835C4EB7F39FE90E['Querystring'];
-  Body: IReqPokeHello_052A3A1D6C6D4FFC835C4EB7F39FE90E['Body'];
+fastify.route<{
+  Querystring: IReqPokeHello['Querystring'];
+  Body: IReqPokeHello['Body'];
   Headers: {
     'access-token': string;
     'refresh-token': string;
@@ -94,14 +92,18 @@ fastify.get<{
       };
     };
   };
-}>('/po-ke/world', option_nPZHxkE1fH4b3EascyCyIFc8UqLca2bc, world_nPZHxkE1fH4b3EascyCyIFc8UqLca2bc);
+}>({
+  ...option_nPZHxkE1fH4b3EascyCyIFc8UqLca2bc, 
+  url: '/po-ke/world',
+  handler: world_nPZHxkE1fH4b3EascyCyIFc8UqLca2bc,
+});
 ```
 
 Don't worry about request type arguments, detail type declare and error prevent!
 
 ## RouteShorthandOptions
 
-Named export `option` variable use to RouteShorthandOptions. I recommand using [simple-tjscli](https://www.npmjs.com/package/simple-tjscli). or [crate-ts-json-schema](https://github.com/imjuni/create-ts-json-schema). simple-tjscli, create-ts-json-schema can transfile TypeScript interface to JSONSchema. So you can pass like that.
+Named export `option` variable use to RouteShorthandOptions. I recommand using [simple-tjscli](https://www.npmjs.com/package/simple-tjscli). or [schema-nozzle](https://github.com/imjuni/schema-nozzle). simple-tjscli, schema-nozzle can transfile TypeScript interface to JSONSchema. So you can pass like that.
 
 ```ts
 // simple-tjscli

diff --git a/docs/options.md b/docs/options.md
@@ -4,7 +4,6 @@
 
 - [command list](#command-list)
 - [`route`, `r` Option](#route-r-option)
-- [`watch`, `w` Option](#watch-w-option)
 
 ## command list
 
@@ -23,26 +22,11 @@
 | --config              |          |  -c   | configuration file path                                                                                       |
 | --output              |          |  -o   | route.ts file generate on output directory. Default value is route handler directory(--handler option passed) |
 | --skip-error          |          |       | skip compile error on project source file                                                                     |
+| --templates           |          |       | path of the template files                                                                                    |
+| --ext-kind            |          |       | module, route file extensions processing style in route.ts                                                    |
 | --cli-logo            |          |       | display cli logo                                                                                              |
 | --route-map           |          |       | create route-map source file                                                                                  |
-| --max-workers         |          |       | max worker count                                                                                              |
-| --worker-timeout      |          |       | route code generation worker timeout: default 90 seconds                                                      |
 | --use-default-export  |          |       | route function in output file that use default export                                                         |
 | --route-function-name |          |       | rotue function name                                                                                           |
 
-## `watch`, `w` Option
-
-| name                  | required | alias | desc.                                                                                                         |
-| :-------------------- | :------: | :---: | :------------------------------------------------------------------------------------------------------------ |
-| --handler             | required |  -a   | API handler path                                                                                              |
-| --project             | required |  -p   | tsconfig path                                                                                                 |
-| --config              |          |  -c   | configuration file path                                                                                       |
-| --output              |          |  -o   | route.ts file generate on output directory. Default value is route handler directory(--handler option passed) |
-| --skip-error          |          |       | skip compile error on project source file                                                                     |
-| --cli-logo            |          |       | display cli logo                                                                                              |
-| --route-map           |          |       | create route-map source file                                                                                  |
-| --max-workers         |          |       | max worker count                                                                                              |
-| --worker-timeout      |          |       | route code generation worker timeout: default 90 seconds                                                      |
-| --use-default-export  |          |       | route function in output file that use default export                                                         |
-| --route-function-name |          |       | rotue function name                                                                                           |
-| --debounce-time       |          |       | watch file debounceTime. unit use milliseconds                                                                |
+---
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "fast-maker",
-  "version": "4.0.0-beta01",
+  "version": "4.0.0",
   "description": "create route file on specific directory",
   "engines": {
     "node": ">=18"

diff --git a/src/configs/interfaces/IBaseOption.ts b/src/configs/interfaces/IBaseOption.ts
@@ -13,7 +13,7 @@ export interface IBaseOption {
   /** path of the tsconfig file. Because fast-maker use typescript compiler api. */
   project: string;
 
-  /** path of the tsconfig file. Because fast-maker use typescript compiler api. */
+  /** path of the template files. */
   templates: string;
 
   /** module, route file extensions processing style in route.ts */
@@ -29,14 +29,16 @@ export interface IBaseOption {
   routeMap: boolean;
 
   /**
-   * index.ts 파일을 생성할 때 사용할 파일의 목록입니다. 만약 아무런 값을 설정하지 않는다면
-   * tsconfig.json 파일에 설정된 include 설정 값을 사용합니다
+   * A list of files to use when generating the index.ts file.
+   * If no value is set, the value of the include setting
+   * set in the tsconfig.json file will be used
    */
   include: string[];
 
   /**
-   * index.ts 파일을 생성할 때 제외할 파일의 목록입니다. 만약 아무런 값을 설정하지 않는다면
-   * tsconfig.json 파일에 설정된 exclude 설정 값을 사용합니다
+   * A list of files to exclude when generating the index.ts file.
+   * If no value is set, the Use the value of the exclude setting
+   * set in the tsconfig.json file
    */
   exclude: string[];