From a8314a680cd3d113b1cdeadcd544ac256aedf420 Mon Sep 17 00:00:00 2001 From: John Pangalos Date: Sat, 10 Jun 2023 21:08:35 +0200 Subject: [PATCH 1/4] Setting up docs --- .gitattributes | 1 + packages/little-router/src/plugin.ts | 10 ++++---- packages/little-router/src/router.ts | 24 ++++++++++++++++++++ pnpm-lock.yaml | 34 ++++++++++++++++++++++++++++ tools/config/.eslintrc.cjs | 3 ++- tools/config/package.json | 7 +++--- 6 files changed, 70 insertions(+), 9 deletions(-) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..58f2839 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +pnpm-lock.yaml -diff diff --git a/packages/little-router/src/plugin.ts b/packages/little-router/src/plugin.ts index 4d43e1e..9df9e89 100644 --- a/packages/little-router/src/plugin.ts +++ b/packages/little-router/src/plugin.ts @@ -14,13 +14,15 @@ export type PluginContext< readonly params: Record; /** * This is only used for adding typing hints to requests - * @private */ + * + * @private + */ readonly __hint?: HINT; }; /** - * _hint is for giving hints to the consumer making the request - * regarding the request init and any possible search params - * */ + * _hint is for giving hints to the consumer making the request regarding the + * request init and any possible search params + */ export type Plugin = ( { request, url, params }: PluginContext, ...rest: REST_ARGS diff --git a/packages/little-router/src/router.ts b/packages/little-router/src/router.ts index 6015676..a0a9a70 100644 --- a/packages/little-router/src/router.ts +++ b/packages/little-router/src/router.ts @@ -3,6 +3,30 @@ import { HasOverlap } from "./overlap.js"; import { Plugin, PluginContext } from "./plugin.js"; import { FetchDefinition, Queries } from "./fetch.js"; +/** + * Returns an instance of RouteBuilder that you can use to build your routing + * structure. + * + * @typeParam REST_ARGS - Used to type Env and ExecutionContext from cloudflare + * workers. More info in [cloudflare workers docs]( https://developers.cloudflare.com/workers/platform/environment-variables/). + * + * The returned RouteBuilder can be build upon by using the method function, + * with names corresponding to http request methods. + * + * {@link Method | Availible Methods} + * + * @example + * ```ts + * type Env = { + * MY_ENV_VAR: string; + * MY_SECRET: string; + * myKVNamespace: KVNamespace; + * }; + * const router = Router + * ``` + * + * More on cloudflare worker types in [their documentation](https://github.com/cloudflare/workerd/tree/main/npm/workers-types#using-bindings). + */ export const Router = (): RouteBuilder< REST_ARGS, never diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 0dda9ec..a29bf36 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -220,6 +220,9 @@ importers: eslint: specifier: ^8.42.0 version: 8.42.0 + eslint-plugin-tsdoc: + specifier: ^0.2.17 + version: 0.2.17 prettier: specifier: ^2.8.8 version: 2.8.8 @@ -1000,6 +1003,19 @@ packages: read-yaml-file: 1.1.0 dev: true + /@microsoft/tsdoc-config@0.16.2: + resolution: {integrity: sha512-OGiIzzoBLgWWR0UdRJX98oYO+XKGf7tiK4Zk6tQ/E4IJqGCe7dvkTvgDZV5cFJUzLGDOjeAXrnZoA6QkVySuxw==} + dependencies: + '@microsoft/tsdoc': 0.14.2 + ajv: 6.12.6 + jju: 1.4.0 + resolve: 1.19.0 + dev: true + + /@microsoft/tsdoc@0.14.2: + resolution: {integrity: sha512-9b8mPpKrfeGRuhFH5iO1iwCLeIIsV6+H1sRfxbkoGXIyQE2BTsPd9zqSqQJ+pv5sJ/hT5M1zvOFL02MnEezFug==} + dev: true + /@nodelib/fs.scandir@2.1.5: resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==} engines: {node: '>= 8'} @@ -1909,6 +1925,13 @@ packages: engines: {node: '>=10'} dev: true + /eslint-plugin-tsdoc@0.2.17: + resolution: {integrity: sha512-xRmVi7Zx44lOBuYqG8vzTXuL6IdGOeF9nHX17bjJ8+VE6fsxpdGem0/SBTmAwgYMKYB1WBkqRJVQ+n8GK041pA==} + dependencies: + '@microsoft/tsdoc': 0.14.2 + '@microsoft/tsdoc-config': 0.16.2 + dev: true + /eslint-scope@5.1.1: resolution: {integrity: sha512-2NxwbF/hZ0KpepYN0cNbo+FN6XoK7GaHlQhgx/hIZl6Va0bF45RQOOwhLIy8lQDbuCiadSLCBnH2CFYquit5bw==} engines: {node: '>=8.0.0'} @@ -2592,6 +2615,10 @@ packages: resolution: {integrity: sha512-nO6jcEfZWQXDhOiBtG2KvKyEptz7RVbpGP4vTD2hLBdmNQSsCiicO2Ioinv6UI4y9ukqnBpy+XZ9H6uLNgJTlw==} dev: true + /jju@1.4.0: + resolution: {integrity: sha512-8wb9Yw966OSxApiCt0K3yNJL8pnNeIv+OEq2YMidz4FKP6nonSRoOXc80iXY4JaN2FC11B9qsNmDsm+ZOfMROA==} + dev: true + /js-string-escape@1.0.1: resolution: {integrity: sha512-Smw4xcfIQ5LVjAOuJCvN/zIodzA/BBSsluuoSykP+lUvScIi4U6RJLfwHet5cxFnCswUjISV8oAXaqaJDY3chg==} engines: {node: '>= 0.8'} @@ -3291,6 +3318,13 @@ packages: engines: {node: '>=8'} dev: true + /resolve@1.19.0: + resolution: {integrity: sha512-rArEXAgsBG4UgRGcynxWIWKFvh/XZCcS8UJdHhwy91zwAvCZIbcs+vAbflgBnNjYMs/i/i+/Ux6IZhML1yPvxg==} + dependencies: + is-core-module: 2.12.0 + path-parse: 1.0.7 + dev: true + /resolve@1.22.2: resolution: {integrity: sha512-Sb+mjNHOULsBv818T40qSPeRiuWLyaGMa5ewydRLFimneixmVy2zdivRl+AF6jaYPC8ERxGDmFSiqui6SfPd+g==} hasBin: true diff --git a/tools/config/.eslintrc.cjs b/tools/config/.eslintrc.cjs index 16febdc..3fe4e53 100644 --- a/tools/config/.eslintrc.cjs +++ b/tools/config/.eslintrc.cjs @@ -2,9 +2,10 @@ module.exports = { extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended"], parser: "@typescript-eslint/parser", - plugins: ["@typescript-eslint"], + plugins: ["@typescript-eslint", "eslint-plugin-tsdoc"], root: true, rules: { + "tsdoc/syntax": "warn", "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }], "@typescript-eslint/no-explicit-any": "off", }, diff --git a/tools/config/package.json b/tools/config/package.json index 184240a..8f846ac 100644 --- a/tools/config/package.json +++ b/tools/config/package.json @@ -3,10 +3,7 @@ "private": true, "version": "0.0.10", "description": "", - "files": [ - "tsconfig.json", - ".eslintrc.cjs" - ], + "files": ["tsconfig.json", ".eslintrc.cjs"], "scripts": {}, "keywords": [], "author": "", @@ -15,6 +12,7 @@ "@typescript-eslint/eslint-plugin": "^5.59.9", "@typescript-eslint/parser": "^5.59.9", "eslint": "^8.42.0", + "eslint-plugin-tsdoc": "^0.2.17", "prettier": "^2.8.8", "typescript": "^5.1.3" }, @@ -22,6 +20,7 @@ "@typescript-eslint/eslint-plugin": "^5.59.1", "@typescript-eslint/parser": "^5.59.1", "eslint": "^8.39.0", + "eslint-plugin-tsdoc": "^0.2.17", "prettier": "^2.8.8", "typescript": "^5.0.4" } From 2f9d9487c0f9ed793859948536a6e44d4cb3468d Mon Sep 17 00:00:00 2001 From: John Pangalos Date: Tue, 13 Jun 2023 08:44:00 +0200 Subject: [PATCH 2/4] Add different methods with comments This is not ideal --- packages/little-router/package.json | 5 +- packages/little-router/src/router.test.ts | 4 +- packages/little-router/src/router.ts | 45 +++++++++++++++- pnpm-lock.yaml | 65 +++++++++++++++++++++-- 4 files changed, 111 insertions(+), 8 deletions(-) diff --git a/packages/little-router/package.json b/packages/little-router/package.json index 1b8e4c8..4d285b8 100644 --- a/packages/little-router/package.json +++ b/packages/little-router/package.json @@ -27,5 +27,8 @@ "typescript": "^5.1.3", "vitest": "^0.32.0" }, - "sideEffects": false + "sideEffects": false, + "dependencies": { + "typedoc": "^0.24.8" + } } diff --git a/packages/little-router/src/router.test.ts b/packages/little-router/src/router.test.ts index ff9d1c3..0cf6cac 100644 --- a/packages/little-router/src/router.test.ts +++ b/packages/little-router/src/router.test.ts @@ -215,8 +215,8 @@ describe("Router with plugins", () => { const router = Router<[string]>().get( "/extra-plugin", [extra_], - async ({ value }) => { - return ok(`Plugin: ${value}`); + async () => { + return ok(200); } ); diff --git a/packages/little-router/src/router.ts b/packages/little-router/src/router.ts index a0a9a70..9d6f4c7 100644 --- a/packages/little-router/src/router.ts +++ b/packages/little-router/src/router.ts @@ -226,8 +226,49 @@ export type RouteBuilder< REST_ARGS extends unknown[], ROUTES extends FetchDefinition > = { - [METHOD in Method]: RouteProxy; -} & { + /** + * @param route - The route to match for this http method handler + * @param pluginArray - A list of plugins to be applied to this route + * @param handler - A function to run when the path has been matched + * @returns an instance of RouteBuilder + */ + get: RouteProxy<"get", ROUTES, REST_ARGS>; + /** + * @param route - The route to match for this http method handler + * @param pluginArray - A list of plugins to be applied to this route + * @param handler - A function to run when the path has been matched + * @returns an instance of RouteBuilder + */ + post: RouteProxy<"post", ROUTES, REST_ARGS>; + /** + * @param route - The route to match for this http method handler + * @param pluginArray - A list of plugins to be applied to this route + * @param handler - A function to run when the path has been matched + * @returns an instance of RouteBuilder + */ + put: RouteProxy<"put", ROUTES, REST_ARGS>; + /** + * @param route - The route to match for this http method handler + * @param pluginArray - A list of plugins to be applied to this route + * @param handler - A function to run when the path has been matched + * @returns an instance of RouteBuilder + */ + delete: RouteProxy<"delete", ROUTES, REST_ARGS>; + /** + * @param route - The route to match for this http method handler + * @param pluginArray - A list of plugins to be applied to this route + * @param handler - A function to run when the path has been matched + * @returns an instance of RouteBuilder + */ + patch: RouteProxy<"patch", ROUTES, REST_ARGS>; + /** + * @param route - The route to match for this http method handler + * @param pluginArray - A list of plugins to be applied to this route + * @param handler - A function to run when the path has been matched + * @returns an instance of RouteBuilder + */ + options: RouteProxy<"options", ROUTES, REST_ARGS>; + all: RouteProxy<"all", ROUTES, REST_ARGS>; handle: ( request: Request, ...rest: REST_ARGS diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index a29bf36..d53833f 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -122,6 +122,10 @@ importers: version: 0.32.0 packages/little-router: + dependencies: + typedoc: + specifier: ^0.24.8 + version: 0.24.8(typescript@5.1.3) devDependencies: '@mewhhaha/config': specifier: workspace:^ @@ -1288,6 +1292,10 @@ packages: engines: {node: '>=8'} dev: true + /ansi-sequence-parser@1.1.0: + resolution: {integrity: sha512-lEm8mt52to2fT8GhciPCGeCXACSz2UwIN4X2e2LJSnZ5uAbn2/dsYdOmUXq0AtWS5cpAupysIneExOgH0Vd2TQ==} + dev: false + /ansi-styles@3.2.1: resolution: {integrity: sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==} engines: {node: '>=4'} @@ -1373,7 +1381,6 @@ packages: /balanced-match@1.0.2: resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==} - dev: true /base64-js@1.5.1: resolution: {integrity: sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==} @@ -1428,6 +1435,12 @@ packages: concat-map: 0.0.1 dev: true + /brace-expansion@2.0.1: + resolution: {integrity: sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==} + dependencies: + balanced-match: 1.0.2 + dev: false + /braces@3.0.2: resolution: {integrity: sha512-b8um+L1RzM3WDSzvhm6gIz1yfTbBt6YTlcEKAvsmqCZZFw46z626lVj9j1yEPW33H5H+lBQpZMP1k8l+78Ha0A==} engines: {node: '>=8'} @@ -2665,7 +2678,6 @@ packages: /jsonc-parser@3.2.0: resolution: {integrity: sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==} - dev: true /jsonfile@4.0.0: resolution: {integrity: sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==} @@ -2756,6 +2768,10 @@ packages: yallist: 4.0.0 dev: true + /lunr@2.3.9: + resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==} + dev: false + /magic-string@0.25.9: resolution: {integrity: sha512-RmF0AsMzgt25qzqqLc1+MbHmhdx0ojF2Fvs4XnOqz2ZOBXzzkEwc/dJQZCYHAn7v1jbVOjAZfK8msRn4BxO4VQ==} dependencies: @@ -2779,6 +2795,12 @@ packages: engines: {node: '>=8'} dev: true + /marked@4.3.0: + resolution: {integrity: sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==} + engines: {node: '>= 12'} + hasBin: true + dev: false + /md5-hex@3.0.1: resolution: {integrity: sha512-BUiRtTtV39LIJwinWBjqVsU9xhdnz7/i889V859IBFpuqGAj6LuOvHv5XLbgZ2R7ptJoJaEcxkv88/h25T7Ciw==} engines: {node: '>=8'} @@ -2863,6 +2885,13 @@ packages: brace-expansion: 1.1.11 dev: true + /minimatch@9.0.1: + resolution: {integrity: sha512-0jWhJpD/MdhPXwPuiRkCbfYfSKp2qnn2eOc279qI7f+osl/l+prKSrvhg157zSYvx/1nmgn2NqdT6k2Z7zSH9w==} + engines: {node: '>=16 || 14 >=14.17'} + dependencies: + brace-expansion: 2.0.1 + dev: false + /minimist-options@4.1.0: resolution: {integrity: sha512-Q4r8ghd80yhO/0j1O3B2BjweX3fiHg9cdOwjJd2J76Q135c+NDxGCqdYKQ1SKBuFfgWbAUzBfvYjPUEeNgqN1A==} engines: {node: '>= 6'} @@ -3445,6 +3474,15 @@ packages: engines: {node: '>=8'} dev: true + /shiki@0.14.2: + resolution: {integrity: sha512-ltSZlSLOuSY0M0Y75KA+ieRaZ0Trf5Wl3gutE7jzLuIcWxLp5i/uEnLoQWNvgKXQ5OMpGkJnVMRLAuzjc0LJ2A==} + dependencies: + ansi-sequence-parser: 1.1.0 + jsonc-parser: 3.2.0 + vscode-oniguruma: 1.7.0 + vscode-textmate: 8.0.0 + dev: false + /side-channel@1.0.4: resolution: {integrity: sha512-q5XPytqFEIKHkGdiMIrY10mvLRvnQh42/+GoBlFW3b2LXLE2xxJpZFdm94we0BaoV3RwJyGqg5wS7epxTv0Zvw==} dependencies: @@ -3882,11 +3920,24 @@ packages: is-typed-array: 1.1.10 dev: true + /typedoc@0.24.8(typescript@5.1.3): + resolution: {integrity: sha512-ahJ6Cpcvxwaxfu4KtjA8qZNqS43wYt6JL27wYiIgl1vd38WW/KWX11YuAeZhuz9v+ttrutSsgK+XO1CjL1kA3w==} + engines: {node: '>= 14.14'} + hasBin: true + peerDependencies: + typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x + dependencies: + lunr: 2.3.9 + marked: 4.3.0 + minimatch: 9.0.1 + shiki: 0.14.2 + typescript: 5.1.3 + dev: false + /typescript@5.1.3: resolution: {integrity: sha512-XH627E9vkeqhlZFQuL+UsyAXEnibT0kWR2FWONlr4sTjvxyJYnyefgrkyECLzM5NenmKzRAy2rR/OlYLA1HkZw==} engines: {node: '>=14.17'} hasBin: true - dev: true /ufo@1.1.2: resolution: {integrity: sha512-TrY6DsjTQQgyS3E3dBaOXf0TpPD8u9FVrVYmKVegJuFw51n/YB9XPt+U6ydzFG5ZIN7+DIjPbNmXoBj9esYhgQ==} @@ -4049,6 +4100,14 @@ packages: - terser dev: true + /vscode-oniguruma@1.7.0: + resolution: {integrity: sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==} + dev: false + + /vscode-textmate@8.0.0: + resolution: {integrity: sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==} + dev: false + /wcwidth@1.0.1: resolution: {integrity: sha512-XHPEwS0q6TaxcvG85+8EYkbiCux2XtWG2mkc47Ng2A77BQu9+DqIOJldST4HgPkuea7dvKSj5VgX3P1d4rW8Tg==} dependencies: From d2e0d77e74f48306f8b501e14d9ff8046601c349 Mon Sep 17 00:00:00 2001 From: John Pangalos Date: Tue, 13 Jun 2023 08:44:50 +0200 Subject: [PATCH 3/4] Update packages/little-router/src/router.ts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jacob Torrång --- packages/little-router/src/router.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/little-router/src/router.ts b/packages/little-router/src/router.ts index 9d6f4c7..4a26ddf 100644 --- a/packages/little-router/src/router.ts +++ b/packages/little-router/src/router.ts @@ -13,7 +13,7 @@ import { FetchDefinition, Queries } from "./fetch.js"; * The returned RouteBuilder can be build upon by using the method function, * with names corresponding to http request methods. * - * {@link Method | Availible Methods} + * {@link Method | Available Methods} * * @example * ```ts From 12d3a3ae03f2bf8a7f3909b99e0767c127a3688b Mon Sep 17 00:00:00 2001 From: John Pangalos Date: Tue, 13 Jun 2023 08:44:56 +0200 Subject: [PATCH 4/4] Update packages/little-router/src/router.ts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jacob Torrång --- packages/little-router/src/router.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/little-router/src/router.ts b/packages/little-router/src/router.ts index 4a26ddf..a835951 100644 --- a/packages/little-router/src/router.ts +++ b/packages/little-router/src/router.ts @@ -22,7 +22,7 @@ import { FetchDefinition, Queries } from "./fetch.js"; * MY_SECRET: string; * myKVNamespace: KVNamespace; * }; - * const router = Router + * const router = Router<[Env, ExecutionContext]> * ``` * * More on cloudflare worker types in [their documentation](https://github.com/cloudflare/workerd/tree/main/npm/workers-types#using-bindings).