Cairn.js

A minimal Node.js/TypeScript backend framework. A route's shape, validation, and handler live in one call: give it a schema, get a typed context and a runtime check. Handlers are async functions that take a typed context and return a plain value, which becomes the JSON response. No req/res/next, no external HTTP library, no validation library just node:http and a small hand-rolled validator.

Install

npm install @cairnjs/core

Quick start

import{cairn}from'@cairnjs/core';constapp=cairn();app.route('GET /users/:id',{params: {id: 'string'},handler: ({ params })=>({id: params.id,name: 'Ada Lovelace'}),});app.route('POST /users',{body: {name: 'string',age: 'number?'},handler: ({ body })=>({created: true, ...body}),});app.listen(3000);

API

cairn()

Returns an app instance.

app.route(pattern, def)

pattern is "METHOD /path/:param", e.g. "GET /users/:id".

def:

field	type	description
params	schema	validated + coerced from URL params
query	schema	validated + coerced from query string
body	schema	validated from parsed JSON body
before	BeforeHook | BeforeHook[]	route-scoped hooks, run before validation
handler	(ctx) => value | Promise<value>	return value becomes the JSON response

The schema mini-language is 'string' | 'number' | 'boolean', with a trailing ? for optional. The same schema drives the TypeScript type of ctx.params / ctx.query / ctx.body.

app.use(plugin)

Plugins are functions that receive the app instance:

app.use((app)=>{app.before((ctx)=>{console.log(`${ctx.method}${ctx.path}`);});});

app.before(fn)

Register a global hook that runs before the handler, receiving a mutable ctx. A hook may return an "after" callback that runs once the handler completes.

app.error(status, message)

Returns a typed error. Throw it in a handler or hook to produce a JSON error response with that status:

throwapp.error(404,'not found');

app.redirect(url)

Returns a redirect value. Return it from a handler to respond with a 302 + Location header.

app.listen(port)

Starts a node:http server. Returns the server.

Plugins

• @cairnjs/plugin-example logger. app.use(loggerPlugin()).
• @cairnjs/plugin-auth route-scoped auth guard. before: [authGuard({ key })].

Examples

• examples/basic-api minimal CRUD-ish app with the logger plugin.
• examples/url-shortener a URL shortener dogfooding the framework, with a friction log.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT. See LICENSE.