@ws-kit/plugins

@ws-kit/plugins

Core plugins for WS-Kit routers — framework features that add capabilities via composition.

Plugins

• withMessaging() — Fire-and-forget unicast messaging (ctx.send())
• withRpc() — Request-response with streaming (ctx.reply(), ctx.progress())
• withPubSub(options) — Topic-based broadcasting (ctx.publish(), ctx.topics)

Installation

bun add @ws-kit/plugins

Quick Start

import { createRouter, withZod } from "@ws-kit/zod";
import { withPubSub, withRpc } from "@ws-kit/plugins";
import { memoryPubSub } from "@ws-kit/memory";

const router = createRouter()
  .plugin(withZod()) // Validation
  .plugin(withRpc()) // Request-response
  .plugin(
    withPubSub({
      adapter: memoryPubSub(), // In-memory pub/sub (dev)
    }),
  );

// Handlers now have:
// - ctx.send() — fire-and-forget
// - ctx.publish() — broadcast to topic
// - ctx.reply(), ctx.progress() — RPC responses

Architecture

Plugins define framework features; adapters provide backend implementations:

• Memory (in @ws-kit/memory) — For development and testing
• Redis (in @ws-kit/redis) — For distributed deployments
• Cloudflare (in @ws-kit/cloudflare) — For Cloudflare Workers

Swap adapters without changing your code:

// Development
.plugin(withPubSub({ adapter: memoryPubSub() }))

// Production
.plugin(withPubSub({ adapter: redisPubSub(redis) }))

Convenience Re-exports

For convenience, validator packages re-export these plugins:

// ✅ Convenient (recommended)
import { withPubSub, withRpc } from "@ws-kit/zod";

// ✅ Also works (explicit)
import { withPubSub, withRpc } from "@ws-kit/plugins";

Documentation

• docs/specs/plugins.md — Complete plugin documentation
• ADR-031: Plugin-Adapter Architecture — Design rationale
• docs/specs/context-methods.md — Context method API reference

TypeScript

All plugins are fully typed. The type system enforces that:

• Methods only appear after their plugin is registered
• Context is properly enhanced with plugin methods
• Payloads match schema types

License

MIT