Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lukeed/worktop

The next generation web framework for Cloudflare Workers
https://github.com/lukeed/worktop

Last synced: about 2 months ago
JSON representation

The next generation web framework for Cloudflare Workers

Awesome Lists containing this project

README 

        


  worktop






  

    version

  

  

    CI

  

  

    downloads

  

  

    install size

  




The next generation web framework for Cloudflare Workers



## Features



* Super [lightweight](https://npm.anvaka.com/#/view/2d/worktop)

* First-class TypeScript support

* Custom Middleware Support

* Well-organized submodules for à la carte functionality*

* Includes Router with support for pattern definitions

* Familiar Request-Response handler API

* Supports `async`/`await` handlers

* Fully treeshakable



> *_More to come!_



## Install



```

$ npm install --save worktop

```



## Usage



> Check out [`/examples`](/examples) for a list of working demos!



```ts

import { Router } from 'worktop';

import * as Cache from 'worktop/cache';

import { uid as toUID } from 'worktop/utils';

import { read, write } from 'worktop/kv';

import type { KV } from 'worktop/kv';



declare var DATA: KV.Namespace;



interface Message {

  id: string;

  text: string;

  // ...

}



// Initialize

const API = new Router();



API.add('GET', '/messages/:id', async (req, res) => {

  // Pre-parsed `req.params` object

  const key = `messages::${req.params.id}`;



  // Assumes JSON (can override)

  const message = await read(DATA, key);



  // Alter response headers directly

  res.setHeader('Cache-Control', 'public, max-age=60');



  // Smart `res.send()` helper

  // ~> automatically stringifies JSON objects

  // ~> auto-sets `Content-Type` & `Content-Length` headers

  res.send(200, message);

});



API.add('POST', '/messages', async (req, res) => {

  try {

    // Smart `req.body` helper

    // ~> parses JSON header as JSON

    // ~> parses form-like header as FormData, ...etc

    var input = await req.body();

  } catch (err) {

    return res.send(400, 'Error parsing request body');

  }



  if (!input || !input.text.trim()) {

    return res.send(422, { text: 'required' });

  }



  const value: Message = {

    id: toUID(16),

    text: input.text.trim(),

    // ...

  };



  // Assumes JSON (can override)

  const key = `messages::${value.id}`;

  const success = await write(DATA, key, value);

  //    ^ boolean



  // Alias for `event.waitUntil`

  // ~> queues background task (does NOT delay response)

  req.extend(

    fetch('https://.../logs', {

      method: 'POST',

      headers: { 'content-type': 'application/json '},

      body: JSON.stringify({ success, value })

    })

  );



  if (success) res.send(201, value);

  else res.send(500, 'Error creating record');

});



API.add('GET', '/alive', (req, res) => {

  res.end('OK'); // Node.js-like `res.end`

});



// Attach "fetch" event handler

// ~> use `Cache` for request-matching, when permitted

// ~> store Response in `Cache`, when permitted

Cache.listen(API.run);

```



## API



### Module: `worktop`



> [View `worktop` API documentation](/src/router.d.ts)



The main module – concerned with routing. 
This is core of most applications. Exports the [`Router`](/src/router.d.ts#L66) class.



### Module: `worktop/kv`



> [View `worktop/kv` API documentation](/src/kv.d.ts)



The `worktop/kv` submodule contains all classes and utilities related to [Workers KV](https://www.cloudflare.com/products/workers-kv/).



### Module: `worktop/cache`



> [View `worktop/cache` API documentation](/src/cache.d.ts)



The `worktop/cache` submodule contains all utilities related to [Cloudflare's Cache](https://developers.cloudflare.com/workers/learning/how-the-cache-works).



### Module: `worktop/request`



> [View `worktop/request` API documentation](/src/request.d.ts)



The `worktop/request` submodule contains the [`ServerRequest`](/src/request.d.ts#L117) class, which provides an interface similar to the request instance(s) found in most other Node.js frameworks.



> **Note:** This module is used internally and will (very likely) never be imported by your application.



### Module: `worktop/response`



> [View `worktop/response` API documentation](/src/response.d.ts)



The `worktop/response` submodule contains the [`ServerResponse`](/src/response.d.ts#L6) class, which provides an interface similar to the [`IncomingMessage`](https://nodejs.org/api/http.html#http_class_http_incomingmessage) (aka, "response") object that Node.js provides.



> **Note:** This module is used internally and will (very likely) never be imported by your application.



### Module: `worktop/base64`



> [View `worktop/base64` API documentation](/src/base64.d.ts)



The `worktop/base64` submodule contains a few utilities related to the [Base 64 encoding](https://tools.ietf.org/html/rfc4648#section-4).



### Module: `worktop/cookie`



> [View `worktop/cookie` API documentation](/src/cookie.d.ts)



The `worktop/cookie` submodule contains `parse` and `stringify` utilities for dealing with cookie header(s).



### Module: `worktop/cors`



> [View `worktop/cors` API documentation](/src/cors.d.ts)



The `worktop/cors` submodule offers utilities for dealing with [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) headers.



### Module: `worktop/crypto`



> [View `worktop/crypto` API documentation](/src/crypto.d.ts)



The `worktop/crypto` submodule is a collection of cryptographic functionalities.



### Module: `worktop/utils`



> [View `worktop/utils` API documentation](/src/utils.d.ts)



The `worktop/utils` submodule is a collection of standalone, general-purpose utilities that you may find useful. These may include – but are not limited to – hashing functions and unique identifier generators.



### Module: `worktop/ws`



> [View `worktop/ws` API documentation](/src/ws.d.ts)



The `worktop/ws` submodule contains the [`WebSocket`](/src/ws.d.ts#L18) and [`WebSocketPair`](/src/ws.d.ts#L4) class definitions, as well as two middleware handlers for validating and/or setting up a [`SocketHandler`](/src/ws.d.ts#L38) for the WebSocket connection.



## License



MIT © [Luke Edwards](https://lukeed.com)