ZeroCore Redis Streams Provider Plugin

@zero.core/api-framework-redis-streams-plugin registers a Redis Streams provider with the @zero.core/api-framework pub/sub bus.

Implemented Scope

• RedisStreamsPubSubProvider
• RedisStreamsPubSubPlugin
• RedisStreamsProviderOptions
• RedisStreamsProviderErrorContext
• RedisStreamsProviderErrorHandler
• structural RedisStreamsClient, RedisStreamsReadRequest, and RedisStreamsMessage contracts

This package does not bundle a Redis client. Pass node-redis, ioredis, or a thin adapter that implements RedisStreamsClient.

Installation

yarn add @zero.core/api-framework @zero.core/api-framework-redis-streams-plugin

Usage

import { ApiRouter, MemoryPubSubProvider, PubSubBus, ServiceContainer } from "@zero.core/api-framework";
import { RedisStreamsPubSubPlugin } from "@zero.core/api-framework-redis-streams-plugin";

const services = new ServiceContainer();
const pubSub = new PubSubBus(new MemoryPubSubProvider("local"), registrations, {
  defaultProvider: "redis-streams",
  services
});

services.addInstance(PubSubBus, pubSub);

new ApiRouter(app, controllers, {
  services,
  plugins: [
    new RedisStreamsPubSubPlugin(redisStreamsClient, {
      streamPrefix: "zerocore",
      consumerGroup: "api",
      consumerName: "api-1",
      onError: (error, context) => {
        logger.error({ error, context }, "Redis Streams pub/sub delivery failed");
      }
    })
  ]
}).register();

await pubSub.start();

Use provider: "redis-streams" in @Subscribe() or pubSub.publish() options to select this provider explicitly.

Verification Stages

yarn typecheck
yarn test:contracts
yarn test:unit
yarn build

Run the full gate:

yarn verify:full
yarn pack:check

Stage meaning:

• typecheck verifies provider and plugin contracts.
• test:contracts verifies package metadata, legal files, npm payload intent, stream polling/ack behavior, handler failure behavior, and plugin registration errors.
• test:unit verifies focused provider writes and plugin registration behavior.
• build emits the publishable dist package.
• pack:check builds and runs npm pack --dry-run so the payload can be reviewed before publish.

Production Notes

• Your adapter owns Redis stream/group creation and any pending-message recovery behavior.
• Set explicit consumerGroup and consumerName in multi-instance deployments.
• Handler, deserialization, acknowledgement, and read-loop failures are reported through onError; failed messages are not acknowledged, and the polling loop continues.
• If the onError hook itself throws, the provider keeps the stream consumer alive and ignores that hook failure.
• Keep PubSubBus registered in the framework DI container before ApiRouter.register() so RedisStreamsPubSubPlugin can add the provider.
• The npm package publishes compiled dist output plus README.md, LICENSE, and NOTICE; TypeScript source and tests stay out of the npm payload.