@openknot-ts/knot-pubsub
v0.0.6-preview
Published
In-memory pub/sub delivery for OpenKnot topic and broadcast ports.
Readme
@openknot-ts/knot-pubsub
Local delivery for Flow's topic() and broadcast() contracts over an EventEmitter the application provides. Each subscription is a native bounded ReadableStream. Flow owns admission and recipients; this package owns subscription resources and delivery.
Usage
import { inMemoryBroadcast, inMemoryTopic } from "@openknot-ts/knot-pubsub";
import { plug, resource, unit } from "@openknot-ts/wire";
import { EventEmitter } from "node:events";
const events = unit({ factory: () => new EventEmitter() });
const roleDelivery = resource({
requirements: { events },
initialize: ({ events }) =>
inMemoryTopic<RoleAudience, RoleEvent>({
events,
event: (key) => `roles:${JSON.stringify([key.userId, key.roleId])}`,
capacity: 64,
}),
});
const logDelivery = resource({
requirements: { events },
initialize: ({ events }) => inMemoryBroadcast<LogEvent>({ events, event: "logs" }),
});
const roleBinding = plug({ port: roleTopic, requirements: { roleDelivery }, bind: ({ roleDelivery }) => roleDelivery });
const logBinding = plug({ port: logBroadcast, requirements: { logDelivery }, bind: ({ logDelivery }) => logDelivery });List them through providePlugs(); Wire acquires the deliveries as resources. examples/topics.ts shows the full composition with guarded subscriptions.
API
| Export | Description |
| --- | --- |
| inMemoryTopic<Key, Message>({ events, event, capacity? }) | A topic. event(key) encodes a key to a native event name (NodeEventName): equal names share a route. Exposes keys(), subscriberCount(key) and interrupt(reason). |
| inMemoryBroadcast<Message>({ events, event, capacity? }) | A broadcast. Exposes subscriberCount() and interrupt(reason). |
| SlowSubscriberError | Ends a subscription whose queue is full. |
| InMemoryTopic, InMemoryTopicOptions, InMemoryBroadcast, InMemoryBroadcastOptions, InMemoryPubSubOptions | Types. |
interrupt(reason) ends every active subscription with reason and discards its queue; later subscriptions open as usual. A delivery that loses its source, such as @openknot-ts/redis-pubsub, uses it.
keys() is a current view of active routes. To let Flow choose recipients, expose it through an ordinary reader plug:
plug({ port: roleRecipients, bind: () => (roleId) => roleDelivery.keys().filter((key) => key.roleId === roleId) });With tRPC
Subscription procedures return the native iterable; access is the port's named guard input.
roles: trpc.procedure.input(roleAudienceSchema).subscription(({ input, ctx, signal }) =>
roleTopic.subscribe({ input, access: ctx.token, signal: AbortSignal.any([ctx.signal, signal ?? ctx.signal]) }),
),Flow runs the guards in a short scope before opening delivery, and releases admission resources before the stream is consumed.
Delivery
- A subscription registers immediately: publications after
subscribe()returns are queued before the firstnext(). - Each queue holds
capacitymessages (default 64). A full queue ends that subscriber withSlowSubscriberError; others continue. - Iterator return,
break, the lifetime signal and resource release remove native listeners and discard queued messages. - Publication emits synchronously to current listeners and does not wait for receipt.
- Transient and in-process: no history, replay, acknowledgment or cross-process delivery. The emitter and its listener limit stay application-owned.
Example and tests
pnpm build
pnpm --filter @openknot-ts/knot-pubsub example
pnpm --filter @openknot-ts/knot-pubsub testThe tests cover routing, recipient inspection, overflow, cancellation, Flow admission, commit staging and real tRPC WebSockets (test/trpc.test.ts).
