S2 Sdk Typescript

What s2-streamstore/s2-sdk-typescript does

The repository contains S2's official TypeScript SDK for its serverless stream platform. S2 organizes streams inside basins, which act as namespaces for stream-level and account-level operations. Applications can create and manage basins and streams, then use stream clients to write and read records.

Records are durable, ordered entries with assigned sequence numbers and timestamps. The SDK accepts both text and binary payloads, along with optional headers. Reads can begin at a sequence number or timestamp and can be bounded by limits such as a record count. Stream consumers can also follow new data as it arrives.

The package is published as @s2-dev/streamstore and provides higher-level abstractions over the S2 REST API.

How it works

Create an S2 client with the S2 environment configuration and an access token. Selecting a basin produces a basin client for namespace-level operations; selecting a stream from that basin produces a stream client for data-plane work.

A direct append accepts an AppendInput containing one or more AppendRecord values. The append acknowledgement identifies the range of records and resolves once the data is durable. Records can be constructed from strings or byte arrays, so a single batch may contain mixed payload types.

For ordered, pipelined writes, an AppendSession keeps submitted batches in order while allowing multiple pending submissions. Its inflight-byte limit provides backpressure, and returned tickets can be used to wait for durability. The Producer API combines an append session with a configurable batch transform that collects records before submission. This is intended for writers that need larger batches and higher throughput.

Read operations can be issued individually or through read sessions when consuming more than one response batch.

Setup and configuration

Install the package with npm, Yarn, or Bun:

npm add @s2-dev/streamstore

Create an S2 account, obtain an access key from the dashboard, and create a basin. Set the credentials before running an application:

export S2_ACCESS_TOKEN="<token>"
export S2_BASIN="<basin>"

Examples may also use S2_STREAM to select a stream. The repository includes runnable examples and a browser example for experimenting with the SDK directly from a web page. Tests run with bun run test.

Tools and capabilities

• Create and manage basins, streams, and granular access tokens through account and basin APIs.
• Append batches containing text or binary records with optional headers.
• Read records using sequence-number or timestamp coordinates.
• Follow stream updates and consume data through read sessions.
• Preserve append ordering with pipelined append sessions.
• Batch records automatically with configurable linger time and maximum record counts.
• Inspect durability acknowledgements, sequence numbers, and append ranges.