https://github.com/jacob-ebey/turbo-stream
A streaming data transport format that aims to support built-in features such as Promises, Dates, RegExps, Maps, Sets and more.
https://github.com/jacob-ebey/turbo-stream
Last synced: about 1 year ago
JSON representation
A streaming data transport format that aims to support built-in features such as Promises, Dates, RegExps, Maps, Sets and more.
- Host: GitHub
- URL: https://github.com/jacob-ebey/turbo-stream
- Owner: jacob-ebey
- License: mit
- Created: 2023-10-23T03:54:07.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-02-12T21:30:31.000Z (over 1 year ago)
- Last Synced: 2025-04-06T05:05:30.894Z (about 1 year ago)
- Language: TypeScript
- Homepage: https://turbo-stream.pages.dev/
- Size: 93.8 KB
- Stars: 274
- Watchers: 4
- Forks: 18
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Turbo Stream
[](https://bundlejs.com/?q=turbo-stream)
Streaming data transport format that supports:
- Streaming promises
- `undefined`, `null`, `Boolean`, `String`
- `Bigint`, `Set`, `Map`, `URL`, `RegExp`, `Error`
- `Number`, including `+Infinity`, `-Infinity` and `NaN`, `-0`
- Circular references, repeated references
- `Date`, including invalid dates
- `Symbol` (`Symbol.from()`)
- Objects with `toJSON` methods
- Iterables, AsyncIterable
- `Buffer`, `ArrayBuffer`, `DataView`, TypedArrays
- `File`, `Blob`, `FormData`, `ReadableStream`
Uses `ReadableStream` as the transport interface for encoding and decoding.
Decode runtime size: [](https://bundlejs.com/?q=turbo-stream&treeshake=%5B%7B+decode+%7D%5D)
## Installation
```bash
npm install turbo-stream
```
## Usage
```js
import { decode, encode } from "turbo-stream";
const encodedStream = encode(Promise.resolve(42));
const decoded = await decode(encodedStream);
console.log(decoded); // 42
```
## Benchmarks
Run them yourself with `pnpm bench`
```
• realistic payload
------------------------------------------- -------------------------------
JSON 2.80 µs/iter 2.71 µs █▆
(2.59 µs … 5.61 µs) 5.55 µs ██
( 2.91 kb … 2.91 kb) 2.91 kb ██▁▂▁▁▁▁▁▂▁▁▁▁▁▁▁▁▁▁▂
turbo encode 16.71 µs/iter 16.47 µs █
(16.04 µs … 19.47 µs) 18.38 µs ███
( 2.80 kb … 2.81 kb) 2.80 kb ██████▁▁▁▁▁▁▁▁▁▁▁▁▁▁█
turbo full 35.30 µs/iter 36.33 µs █
(31.38 µs … 202.79 µs) 52.50 µs █▃ ▄
( 2.47 kb … 454.32 kb) 104.44 kb ▂██▃▅█▂▂▂▂▁▁▁▁▁▁▁▁▁▁▁
┌ ┐
┬ ╷
JSON │──┤
┴ ╵
┌┬╷
turbo encode ││┤
└┴╵
╷┌─┬┐ ╷
turbo full ├┤ │├──────────────┤
╵└─┴┘ ╵
└ ┘
2.59 µs 27.55 µs 52.50 µs
summary
turbo encode
5.97x slower than JSON
2.11x faster than turbo full
```
## Legacy
Shout out to Rich Harris and his https://github.com/rich-harris/devalue project. Devalue has heavily influenced this project and portions of the original code was directly lifted from it. I highly recommend checking it out if you need something more cusomizable or without streaming support. This new version has been re-written from the ground up and no longer resembles devalue.