s2-streamstore/s2-sdk-typescript

This repo contains the official TypeScript SDK for S2, a serverless data store for streams, built on the service's REST API.
S2 is a managed service that provides unlimited, durable streams.
Streams can be appended to, with all new records added to the tail of the stream. You can read from any portion of a stream – indexing by record sequence number, or timestamp – and follow updates live.
See it in action on the playground.
**Quick links:**
- Runnable examples directory
- Patterns package
- SDK documentation
- S2 REST API documentation
> **Note:** The repository for releases prior to 0.16.x can be found at this link.
Install
Quick start
Want to get up and running? Head to the S2 dashboard to sign-up and grab an access key, and create a new "basin" from the UI.
Then define the following environment variables respectively:
From there, you can run the following snippet (or any of the other examples).
Development
Run examples:
Run tests:
The SDK also ships with a basic browser example, to experiment with using the SDK directly from the web.
Using S2
S2 SDKs, including this TypeScript one, provide high-level abstractions and conveniences over the core REST API.
Account and basin operations
The account and basin APIs allow for CRUD ops on basins (namespaces of streams), streams, granular access tokens, and more.
Data plane (stream) operations
The core SDK verbs are around appending data to streams, reading data from them.
See the examples and documentation for more details.
Below are some high level notes on how to interact with the data plane.
Appends
The atomic unit of append is an AppendInput, which contains a batch of AppendRecords and some optional additional parameters.
Records contain a body and optional headers. After an append completes, each record will be assigned a sequence number (and a timestamp).
Append sessions (ordered, stateful appends)
Use an AppendSession when you want higher throughput and ordering guarantees:
- It is stateful and enforces that the order you submit batches becomes the order on the stream.
- It supports pipelining submissions while still preserving ordering (especially with the s2s transport).
Producer
Streams can support up to 200 appended batches per second (per single stream), but tens of MiB/second.
For throughput, you typically want fewer, but larger batches.
The Producer API simplifies this by connecting an appendSession with an auto-batcher (via BatchTransform), which lingers and accumulates records for a configurable amount of time. This is the recommended path for most high-throughput writers.
Read sessions
Read operations, similarly, can be done via individual read calls, or via a readSession.
Use a session whenever you want:
- to read more than a single response batch (responses larger than 1 MiB),
- to keep a session open and tail for new data (omit stop criteria).
Client configuration
Retries and append retry policy
- appendRetryPolicy: "noSideEffects" only retries appends that are naturally idempotent via matchSeqNum.