70 lines
5.2 KiB
Markdown
70 lines
5.2 KiB
Markdown
# @suaveplan/api-sse - Abstract Server-Sent Events contracts for @suaveplan/api: SseConnection, SseBroker, SseEvent (Zod), ReplayBuffer with Last-Event-Id resume, SseConnectionRegistry, SSE_CODES, and runSseEngineConformance harness. Concrete engines plug behind these contracts.
|
|
|
|
Abstract Server-Sent Events contracts for `@suaveplan/api`. Stage-1 contract package: defines the engine-side `SseConnection`, `SseBroker`, `ReplayBuffer` (Last-Event-Id resume), `SseConnectionRegistry`, the `SSE_CODES` error registry, and the `runSseEngineConformance` harness every concrete engine must pass.
|
|
|
|
This package ships no concrete engine — `@suaveplan/api-sse-bun` (and other transports) land at and plug behind these contracts.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [broker](./src/broker/broker.md) — `SseBroker` is the engine-side publish / subscribe surface for Server-Sent Events. It mirrors the shape of `@suaveplan/…
|
|
- [broker](./src/broker/broker.md) — `SseBroker` is the engine-side publish / subscribe surface for Server-Sent Events. It mirrors the shape of `@suaveplan/…
|
|
- [capability-id](./src/capability-id/capability-id.md) — The `"sse"` `CapabilityId` slot connects this package to the host's `CapabilityMap`. Plugin authors declare `requires:…
|
|
- [capability-id](./src/capability-id/capability-id.md) — The `"sse"` `CapabilityId` slot connects this package to the host's `CapabilityMap`. Plugin authors declare `requires:…
|
|
- [connection](./src/connection/connection.md) — `SseConnection` is the engine-side contract for a single Server-Sent-Events stream. Concrete engines (`api-sse-bun`, `a…
|
|
- [connection](./src/connection/connection.md) — `SseConnection` is the engine-side contract for a single Server-Sent-Events stream. Concrete engines (`api-sse-bun`, `a…
|
|
- [connection-registry](./src/connection-registry/connection-registry.md) — `SseConnectionRegistry` is the multi-index registry for active SSE connections. Engines call `add` on handshake, `remov…
|
|
- [connection-registry](./src/connection-registry/connection-registry.md) — `SseConnectionRegistry` is the multi-index registry for active SSE connections. Engines call `add` on handshake, `remov…
|
|
- [error-codes](./src/error-codes/error-codes.md) — `SSE_CODES` is the stable error-code registry every contract-level failure path in the SSE family raises. Concrete engi…
|
|
- [error-codes](./src/error-codes/error-codes.md) — `SSE_CODES` is the stable error-code registry every contract-level failure path in the SSE family raises. Concrete engi…
|
|
- [production-throws](./src/error-codes/production-throws.md) — `production-throws` exports the canonical factory functions that the host (and concrete SSE engines) invoke at every do…
|
|
- [event](./src/event/event.md) — `SseEvent` is the wire-shape contract for a single Server-Sent-Events field block: `id`, optional `event`, `data`, opti…
|
|
- [event](./src/event/event.md) — `SseEvent` is the wire-shape contract for a single Server-Sent-Events field block: `id`, optional `event`, `data`, opti…
|
|
- [replay-buffer](./src/replay-buffer/replay-buffer.md) — `ReplayBuffer` is the per-`(tenant, topic)` ring buffer that powers the `Last-Event-Id` resume contract. Concrete engin…
|
|
- [replay-buffer](./src/replay-buffer/replay-buffer.md) — `ReplayBuffer` is the per-`(tenant, topic)` ring buffer that powers the `Last-Event-Id` resume contract. Concrete engin…
|
|
- [testing](./src/testing/conformance.md) — `runSseEngineConformance` is the reusable conformance harness every concrete `@suaveplan/api-sse` engine MUST pass. Eng…
|
|
- [conformance](./src/testing/conformance.md) — `runSseEngineConformance` is the reusable conformance harness every concrete `@suaveplan/api-sse` engine MUST pass. Eng…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Install
|
|
|
|
```bash
|
|
bun add @suaveplan/api-sse
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```ts
|
|
import {
|
|
createReplayBuffer,
|
|
createConnectionRegistry,
|
|
SSE_CODES,
|
|
} from "@suaveplan/api-sse";
|
|
|
|
const buffer = createReplayBuffer({ eventBufferSize: 1024 });
|
|
const registry = createConnectionRegistry();
|
|
|
|
buffer.append({ id: "1", data: "hello" });
|
|
const since = buffer.since("0").length; // 0 (unknown ids throw SSE_CODES.LAST_EVENT_ID_UNKNOWN)
|
|
```
|
|
|
|
## Modules
|
|
|
|
- [`connection`](./src/connection/connection.md) — engine-side `SseConnection` interface.
|
|
- [`event`](./src/event/event.md) — `SseEvent` Zod schema + interface.
|
|
- [`broker`](./src/broker/broker.md) — engine-side publish / subscribe surface.
|
|
- [`replay-buffer`](./src/replay-buffer/replay-buffer.md) — per-(tenant, topic) ring buffer powering `Last-Event-Id` resume.
|
|
- [`connection-registry`](./src/connection-registry/connection-registry.md) — multi-index registry for active connections.
|
|
- [`capability-id`](./src/capability-id/capability-id.md) — `"sse"` slot in the host's `CapabilityMap`.
|
|
- [`error-codes`](./src/error-codes/error-codes.md) — `SSE_CODES` registry + `SseError` class.
|
|
- [`error-codes/production-throws`](./src/error-codes/production-throws.md) — canonical throw-site factories.
|
|
- [`testing/conformance`](./src/testing/conformance.md) — `runSseEngineConformance` harness.
|
|
|
|
## Status
|
|
|
|
- Package: `@suaveplan/api-sse`
|
|
- Version: `0.1.0`
|
|
- Stage: 1 of the API plugin system (contracts).
|
|
- Tier: universal — zero browser / Node-only deps; runs everywhere the host runs.
|
|
|