⚡ Features

• Lightweight — Does not include any dependencies see.

• Familiar — plugs into any node:http or workers based environment.

• Incredible DX — passing only an AsyncIterable | Iterable.

⚙️ Install

npm add piecemeal

🚀 Usage

Visit /examples for more info!

Workers

import * as Piecemeal from 'piecemeal/worker';

// Some sort of data access
// ~> here we read from KV, but can be anything
async function* get_data(binding: KV.Namespace) {
  const list = await DATA.list();

  for await (let item of list.keys) {
    yield await DATA.get(item);
  }
}

// A handler you'd typically give a Module or Service Worker
const handler = (request, env, context) => {
  // Notice we're not awaiting or spreading this iterable
  const data = get_data(context.bindings.DATA);

  // Sets up our stream and constructs the Response
  const { pipe, response } = Piecemeal.stream(data);

  // Defers the execution of the iterable, so we respond super quick
  context.waitUntil(pipe());

  return response;
};

Node

import { createServer } from 'node:http';

import * as Piecemeal from 'piecemeal/node';

// An example of some method to retreive some database data
async function* get_data() {
  const keys = await db.fetchAllKeys();

  for await (let key of keys) {
    yield await db.read(key);
  }
}

createServer((req, res) => {
  // Notice we're not awaiting or spreading this iterable
  const data = get_data();

  // Creates a streams — and kicks off the iterable.
  // assumes JSON (can override)
  const stream = Piecemeal.stream(data);

  // Pipes the stream directly to a ServerResponse
  stream.pipe(res);
}).listen(8080);

🔎 API

Module: piecemeal/worker

The main module used by Cloudflare Workers — or any Service Worker API.

Example over at /examples/workers

Module: piecemeal/node

The main module used for a node runtime and plugs directly into node:http modules.

Example over at /examples/polka

Module: piecemeal/message

A module used to construct messages. Messages are the partial bits-of-data flushed in increments.

Module: piecemeal

A main module one can use to build out custom runtimes — exposes all the building blocks to generate a stream supplying the Iterable and a write method.

🙊 Caveats

• Workers doesn't abort any iterables if connection is dropped. 😔

Related

• meros — makes reading multipart responses simple

License

MIT © Marais Rossouw