@occultist/occultist
v0.0.12
Published
A koa inspired web framework with first class support for request caching and content negotiation
Readme
Occultist
Occultist is an under-development, Koa-inspired backend web framework for Node or Deno, adding structure to less-supported HTTP features.
Features
Auth middleware
All endpoints require that they are marked public or private simplifying future auditing processes. When marked public they and can optionally have auth middleware provided to identify the requester. Private endpoints require a auth middleware is provided.
Request url and body input processing
Request bodies, route parameters and query string values can be fully described to
Occultist allowing it to unpack multipart/form-data, application/json requests
producing a single typescript typed ctx.payload object with all inputs merged together.
Failed requests automatically support responding with
application/problem+json responses.
Content negotiation
Endpoints can have multiple handlers defined responding with different content types. Occultist automatically routes the request to the correct handler based off the request's accept header, or the first handler if no accept handler is set.
Caching middleware
Use caching providers to store representations using the provided auth information request's URL's parameters and resulting content type provided by the other special case middlewares.
Advanced features
Occultist is being built to complement the also under-development frontend framework Octiron which is built to consume JSON-ld APIs and build complex forms using actions in the schema.org/Action style. This relationship will be better explained as the two frameworks stablize.
Occultist is in flux at the moment but you can try it now. Endpoints can be created with most url and body processing features working for application/json requests and content negotiation works for the response's content. The auth and cache features described here are yet to be implemented.
Installation
npm install @occultist/occultist
deno add jsr:@occultist/occultistExample
import { Registry } from '@occultist/occultist';
// TODO
const auth = new AuthProvider();
// TODO
const cache = new CacheProvider();
const registry = new Registry({
root: 'https://example.com',
});
registry.http.get('list-cats', '/cats')
// Endpoints are marked public and can optionally have
// auth middleware identify the requester, or they are
// marked private and the auth check is required.
.public(auth.optional())
// resulting representation cache keys would vary based
// on the an auth key that is unique to the user that the above
// middleware provides, other parameters can further vary the
// cache and control http cache headers.
.cache(cache.etag())
// define handlers to respond with supported content types.
.handle('text/html', (ctx) => {
ctx.body = `
<!doctype>
<html>
<body>
<h1>Hello, World!</h1>
</body>
</html>
`;
})
.handle('application/json', (ctx) => {
ctx.body = `{
"message": "Hello, World!",
}`;
});
// The same method and path combination can be re-used for endpoints
// which have different middleware requirements. The accept header
// can be used by requests to pull an alternative representation.
registry.http.get('get-cat', '/cats')
.public()
.handle('application/xml', (ctx) => { ... })
registry.http.post('create-cat', '/cats')
.private(auth.hasPermission('create-cats'))
// With a body payload defined any requests with
// application/json or multipart/form-data bodies
// are automatically pre-processed into the `ctx.payload`.
.define({
spec: {
name: {
dataType: 'string',
minValueLength: 2,
valueRequired: true,
},
hasStripes: {
dataType: 'boolean',
valueRequired: true,
},
image: {
// you would want to use form-data for a large file upload
// but data uris can be sent via json
dataType: 'blob',
},
},
})
.handle('text/html', async (ctx) => {
const cat = await storage.createCat({
name: ctx.payload.name,
hasStripes: ctx.payload.hasStripes,
image: ctx.payload.image,
});
ctx.status = 303;
ctx.headers.set('Location', `https://example.com/cats/${cat.id}`);
});
// required before requests are handled
registry.finalize();
const server = createServer();
// for Node, Deno and probably Bun.
server.on('request', (req, res) => registry.handleRequest(req, res));
server.listen(3000);