kitajs/kitajs

🌷 Performant & type safe fastify router — end-to-end safety with ZERO abstraction cost!

Using this package? Please consider donating to support my open source work ❤️
^{Help kitajs grow! Star and share this amazing repository with your friends and co-workers!}

🌷 KitaJS

KitaJS is a routing meta framework.

🎉 Kita is officially Stable! Try it out today!

Star History

All Thanks To Our Contributors:

kitajs's Issues

Improve documentation.

Currently, lack of documentation is the major problem of Kita.

• Finish all sections
  • Routing
  • Learn By building
    • setup
    • api routes
    • frontend
  • Learn by example
    • file uploads
    • authentication
    • logging
  • Guide
  • Templating (Should we have this? Probably fit better in kitajs/html)
  • Integrations
    • auth
    • (what more?)

---

I wrote the entire kita.js.org documentation alone. I'm 100% sure there will be grammar mistakes that can be easily fixed.

Site: https://kita.js.org
Documentation: https://github.com/kitajs/docs

• Have at least 3 grammar revisors.
  • 1. @titi-lima
  • 2. ?
  • 3. ?

Cannot find module '@kitajs/html/jsx-runtime' or its corresponding type declarations on NodeJS

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Versions

@kitajs/html: 4.1.0

Description

When using kitajs as JSX to string transformer in AdonisJS I get the error Cannot find module '@kitajs/html/jsx-runtime' or its corresponding type declarations.

It worked before, with the tsconfig:

{
  // ...
  "compilerOptions": {
   // ...
   "jsx": "react",
   "jsxFactory": "Html.createElement",
   "jsxFragmentFactory": "Html.Fragment",
   "plugins": [{ "name": "@kitajs/ts-html-plugin" }]
  }
}

And adding import '@kitajs/html/register.js' to bin/server.ts . But it was complaining about being a deprecated method, so I tried to get the new method to work, but was not able to.

The new method seems not to work with compilerOptions: { module: NodeNext }. Is this library not supported on NodeJS?

Steps to Reproduce

Install AdonisJS, install @kitajs/html & @kitajs/ts-html-plugin.

Create a tsx file:

import router from '@adonisjs/core/services/router'

router.get('/', () => <div>foo</div>);

Set tsconfig.json to

{
  "extends": "@adonisjs/tsconfig/tsconfig.app.json",
  "compilerOptions": {
    "rootDir": "./",
    "outDir": "./build",
    "jsx": "react-jsx",
    "jsxImportSource": "@kitajs/html",
    "plugins": [
      {
        "name": "@kitajs/ts-html-plugin"
      }
    ]
  },
}

@adonisjs/tsconfig/tsconfig.app.json:

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "declaration": false,
    "sourceMap": true,
    "emitDecoratorMetadata": true,
  }
}

@adonisjs/tsconfig/tsconfig.base.json:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "NodeNext",
    "lib": ["ESNext"],
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "isolatedModules": true,
    "removeComments": true,
    "esModuleInterop": true,
    "strictNullChecks": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true,
    "strictPropertyInitialization": true,
    "experimentalDecorators": true,
    "noImplicitAny": true,
    "strictBindCallApply": true,
    "strictFunctionTypes": true,
    "noImplicitThis": true,
    "skipLibCheck": false
  },
  "ts-node": {
    "swc": true
  }
}

Expected Behavior

It does not give error Cannot find module '@kitajs/html/jsx-runtime' or its corresponding type declarations when using the new way of setting the JSX transformer up.

Support all fastify methods.

https://github.com/fastify/fastify/blob/main/lib/httpMethods.js

@fastify/cookie is not listed as a direct dependency of runtime

Bake route URL inside the generated runtime

A getIndexUrl = '/index' string constant should be exported. Additionally a getIndexMethod = 'GET' could also be generated.

Refactor Errors to have `cause`

Re-export light-my-request calls and direct controller binds

Direct controller binds causes #152 and multiple other issues, we should only export the light my request typings and let the user extract reusable logic into services.

Add Elysia as a Fastify alternative

Maybe add Elysia?
Elysia is a bun web framework with great prefomance and DX!

Type only generation to fix cyclic routes type generation

Add a type only generation step to prevent unknown types when a route return type depends on.

Add uWebSockets.js as a fastify alternative.

https://github.com/uNetworking/uWebSockets.js

A uWebSockts.js kindly needs an abstraction to write routes and kita would be a awesome fit.

Awaited should be used defined in the controller response type.

export type ControllerResponse = ReturnType<typeof controller>;

export declare function controllerHandler(
  req: FastifyRequest,
  reply: FastifyReply
): Promise<Awaited<ControllerResponse>>;

should be

export type ControllerResponse = Awaited<ReturnType<typeof controller>>;

export declare function controllerHandler(
  req: FastifyRequest,
  reply: FastifyReply
): Promise<ControllerResponse>;

Otherwise using ControllerResponse is impractical without adding Awaited everywhere.

`Environment` provider

Add a /providers/environment.ts specific provider which should only default export a interface which its json schema should be parsed by env-schema.

// providers/environment.ts

export default interface Environment {
  /**
   * My description
   *
   * @default '...'
   * @minLength 32
   * @maxLength 64
   */
  MY_ENV: string;
}

export const options: EnvSchemaOpt = {
  dotenv: true
};

Private routes with `@internal` still leaks return type.

Routes with @internal still shows their return type in Schemas.

Support for exporting arrow keys instead of only function declarations.

We should be able to use all of the example below to register provider hooks, schema transformers, routes and everything else:

export const get = () => {}
export const get = function () {}
export let get = () => {}
export let get = function () {}
export function get() {}

Provide a custom schema compiler

https://backend.cafe/how-to-unlock-the-fastest-fastify-server-startup

Multipart support

Needs integration with @fastify/multipart should also be done. MultipartFile and SavedMultipartFile.

Convert JSON Schemas to OpenApi

Use https://www.npmjs.com/package/@openapi-contrib/json-schema-to-openapi-schema to convert schemas, probably somewhere in this class:

kitajs/packages/parser/src/schema/builder.ts

Line 30 in beb5892

export class SchemaBuilder {

`default` export should not be allowed inside file routes.

Currently, you can use:

export default function get() {
  return 'Hello!'
}

and kita will try to import it normally, default functions should emit a parsing error.

Improve route parameters

• Req and Res should change to the defaults FastifyRequest and FastifyResponse
• Simplify Query type, we shouldn't break types when runtime execution works.
• Remove this parameter usage, it gets messy when calling routes programatically. This resolves to void, which doesn't impact on calling the routes manually
• Add tests and type tests for every parameter type.

Automatically add properties to all required plugins.

Having the end user to manually register plugins like the following example is bad:

// Register fastify sensible to allow error handling
app.register(fastifySensible, {
  sharedSchemaId: "HttpError",
});

// Registers fastify's swagger support
app.register(fastifySwagger);
app.register(fastifySwaggerUi);

// Registers the generated kita plugin
app.register(Kita);

Every plugin kita needs, depending on providers/parameters usage, we should add the typings and the object as properties, like the following example:

app.register(Kita, {
  swagger: {},
  swaggerUi: {},
  sensible: {},

  // If other parameters like websocket are used, a `websocket` property should be added in case
  // the user wants to change some configuration. We should also consider good defaults.
  // websocket: {}
})

Warn on file without routes

KitaJS should emit warnings on files inside routes that does not exports any route method and/or exported functions that does not represent any routes.

Fallback to untyped responses when return type cannot be resolved.

Unusual providers registration order

Currently, providers must be prefixed with number like 1z.ts and a.ts when a.ts used z.ts as parameter, otherwise a.ts would throw because z was not registered yet.

Node engine 20.0.0 does not support built-in .env file

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Versions

@kitajs/cli: 1.1.31

Description

When using node 20.0.0 version, the server does not start.
Using the dev command it does not throw, which makes the issue a little bit harder to detect. When using the start command it throws, making it clear that the issue is about the .env file.

Steps to Reproduce

1. Set the node version to 20.0.0;
   • When using nvm you can run nvm install 20.0.0 and then run nvm use 20.0.0.
2. Run npm start;
3. Check the error;
4. Set the node version to 20.6.x (in the video I use 20.6.1 but 20.6.0 works as well);
5. Run npm start;
6. Check the server runs normally.

Record reproduction:

Screen.Recording.2024-06-24.at.13.05.17.mov

Expected Behavior

The required node engine should be higher than 20.6.0

Migrate to ESM and Move `generated` into a `.kita` folder

.kita folder would follow the dotfolder convention like many other frameworks, e.g .next and .astro. This would solve many other problems related to files inside node_modules and the generated reference.

Validate transformSchema function

The transform schema function should also be validated at compile time.

`kita create` command needs a test suite.

After #365 (a bug that only happened on windows), its clear that it requires a full test suite across all 3 operating systems.

Our only problem is to ensure a copy of @kitajs/runtime instead of linking, otherwise the generated folder will get updated and break all other packages tests.

Support for wildcard routes

Using [...].ts should work as a fastify wildcard route. Currently this is the only hacky way to do it:

/**
 * @url /api/a/*
 */
export function get({ url, params }: FastifyRequest) {
  return { url, params };
}

returns = {
  "params": {
    "*": "asdasd/asd"
  },
  "url": "/api/a/asdasd/asd"
}

The Path parameter should also validate when its being used outside a /[named]/ route and a variant of it should be defined to get the request.params['*'] when the route is wildcard.

@url jsdoc is not working

/** @url /users */
export function get() {}

generates the following schema:

{
  "openapi": "3.1.0",
  "info": {
    "title": "API Reference",
    "description": "Powered by [Scalar](https://scalar.com/) & Generated by [KitaJS](https://kita.js.org/)",
    "version": "1.1.22"
  },
  "components": { "schemas": {} },
  "paths": {
    "/users": {
      "get": {
        "operationId": "getIndex",
        "responses": {
          "2XX": {
            "description": "Default Response",
            "content": {
              "application/json": { "schema": { "type": "boolean" } }
            }
          }
        }
      }
    }
  }
}

Only register helper plugins if they are not yet registered.

A fastify.hasPlugin() call should be made before registering plugins like @fastify/sensible...

Migrate to biomejs.dev

https://biomejs.dev/

Better HTTP error detection

The same way a HTTP route can read throw clauses to add errors, providers should also include throw clauses it the route they are used.

Maybe custom errors should also be added by inferring their type

Force `async` routes

Libraries like prisma may extend the promise return type, e.g PrismaPromise and it cannot be unwrapped into a real promise, making the return type incorrect.

Error: `gyp` failed with exit code: 1 no module named 'distutils'

node_modules/.pnpm/[email protected]/node_modules/deasync: Running install script, failed in 341ms
.../[email protected]/node_modules/deasync install$ node ./build.js
│ gyp info it worked if it ends with ok
│ gyp info using [email protected]
│ gyp info using [email protected] | darwin | arm64
│ gyp info find Python using Python version 3.12.2 found at "/opt/homebrew/opt/[email protected]/bin/python3.12"
│ gyp info spawn /opt/homebrew/opt/[email protected]/bin/python3.12
│ gyp info spawn args [
│ gyp info spawn args   '/usr/local/lib/node_modules/pnpm/dist/node_modules/node-gyp/gyp/gyp_main.py',
│ gyp info spawn args   'binding.gyp',
│ gyp info spawn args   '-f',
│ gyp info spawn args   'make',
│ gyp info spawn args   '-I',
│ gyp info spawn args   '/Users/griffith/www/kita-app/node_modules/.pnpm/[email protected]/node_modules/deasync/build/confi…
│ gyp info spawn args   '-I',
│ gyp info spawn args   '/usr/local/lib/node_modules/pnpm/dist/node_modules/node-gyp/addon.gypi',
│ gyp info spawn args   '-I',
│ gyp info spawn args   '/Users/griffith/Library/Caches/node-gyp/21.7.3/include/node/common.gypi',
│ gyp info spawn args   '-Dlibrary=shared_library',
│ gyp info spawn args   '-Dvisibility=default',
│ gyp info spawn args   '-Dnode_root_dir=/Users/griffith/Library/Caches/node-gyp/21.7.3',
│ gyp info spawn args   '-Dnode_gyp_dir=/usr/local/lib/node_modules/pnpm/dist/node_modules/node-gyp',
│ gyp info spawn args   '-Dnode_lib_file=/Users/griffith/Library/Caches/node-gyp/21.7.3/<(target_arch)/node.lib',
│ gyp info spawn args   '-Dmodule_root_dir=/Users/griffith/www/kita-app/node_modules/.pnpm/[email protected]/node_modules/d…
│ gyp info spawn args   '-Dnode_engine=v8',
│ gyp info spawn args   '--depth=.',
│ gyp info spawn args   '--no-parallel',
│ gyp info spawn args   '--generator-output',
│ gyp info spawn args   'build',
│ gyp info spawn args   '-Goutput_dir=.'
│ gyp info spawn args ]
│ Traceback (most recent call last):
│   File "/usr/local/lib/node_modules/pnpm/dist/node_modules/node-gyp/gyp/gyp_main.py", line 42, in <module>
│     import gyp  # noqa: E402
│     ^^^^^^^^^^
│   File "/usr/local/lib/node_modules/pnpm/dist/node_modules/node-gyp/gyp/pylib/gyp/__init__.py", line 9, in <module>
│     import gyp.input
│   File "/usr/local/lib/node_modules/pnpm/dist/node_modules/node-gyp/gyp/pylib/gyp/input.py", line 19, in <module>
│     from distutils.version import StrictVersion
│ ModuleNotFoundError: No module named 'distutils'
│ gyp ERR! configure error 
│ gyp ERR! stack Error: `gyp` failed with exit code: 1
│ gyp ERR! stack     at ChildProcess.onCpExit (/usr/local/lib/node_modules/pnpm/dist/node_modules/node-gyp/lib/configure…
│ gyp ERR! stack     at ChildProcess.emit (node:events:519:28)
│ gyp ERR! stack     at ChildProcess._handle.onexit (node:internal/child_process:294:12)
│ gyp ERR! System Darwin 23.4.0
│ gyp ERR! command "/usr/local/bin/node" "/usr/local/lib/node_modules/pnpm/dist/node_modules/node-gyp/bin/node-gyp.js" "…
│ gyp ERR! cwd /Users/griffith/www/kita-app/node_modules/.pnpm/[email protected]/node_modules/deasync
│ gyp ERR! node -v v21.7.3
│ gyp ERR! node-gyp -v v9.4.1
│ gyp ERR! not ok 
│ Build failed
└─ Failed in 341ms at /Users/griffith/www/kita-app/node_modules/.pnpm/[email protected]/node_modules/deasync

Provider hooks

We should be able to use application hooks like the following:

// providers/test.ts

export default function() : Data {
}

// Registered as the fastify onRouteHandler
export function onRoute() {

}

// ... So on for 'onRegister', 'onReady', 'onListen', 'onClose', 'preClose'

ts-plugin does not recognizes .tsx providers

Providers created with .tsx extension aren't recognized.

Ensure multiple route parameters in the same path works

Routes like /users/[userid]-[userage] should work, not only /users/[userid]/[userage].

Routes without return must be async or throw error

Fastify either requires done() call or return promise.

Provider Parameters

Providers should have the hability to provide generic parameters.

export function get(a: MyGenericProvider<'a', 2, true, {a:1}>) {}

Should have this definition:

export default function (params: ProviderParameters) {
  console.log(params) // ['a', '2', 'true', '{a:1}']
}

If possible, parsed JSON values should be cool.

export default function (params: ProviderParameters) {
  console.log(params) // ['a', 2, true, { a: 1 }]
}

Update all packages README's to include documentation url

Currently, some packages have docs, others have a "documentation yet to be written" message.

All packages should remove this message and have a single link to our official documentation.