madapes
Repositories
7
 Projects Packages

@aurora/runtime-eventlog (0.3.3)

Published 2025-12-27 10:44:48 +00:00 by vlad

Installation

@aurora:registry=
npm install @aurora/runtime-eventlog@0.3.3
"@aurora/runtime-eventlog": "0.3.3"

About this package

@aurora/runtime-eventlog

NATS JetStream integration for Aurora event logging.

Overview

This package provides a durable, high-performance event log implementation using NATS JetStream. Events are stored reliably and can be consumed as Effect-based Streams.

Features

  • Durable event storage via NATS JetStream
  • Effect-based API for appending events
  • Stream-based consumption for projection workers
  • Automatic stream/consumer management
  • Tenant-based subject routing
  • Reconnection handling

Installation

bun add @aurora/runtime-eventlog

Usage

Create an EventLog

import { createJetStreamEventLog } from "@aurora/runtime-eventlog";
import { run } from "@aurora/runtime-effect";

const config = {
  servers: "localhost:4222",
  streamName: "aurora-events",
  subjectPrefix: "aurora.events",
};

const eventLog = await run(createJetStreamEventLog(config), {});

Append Events

const result = await run(
  eventLog.append(
    "TaskCreated",
    1,
    { taskId: "task_123", title: "My Task" },
    "tenant_1",
    { traceId: "trace_xyz" }
  ),
  {}
);

console.log(`Event stored at sequence: ${result.sequence}`);

Subscribe to Events

import { collect } from "@aurora/runtime-effect";

const stream = eventLog.subscribe({
  name: "my-consumer",
  deliverPolicy: "all",
  ackPolicy: "explicit",
});

// Process events
for await (const event of collect(stream, {})) {
  console.log(`Received event: ${event.type}`);
  // Process event and update projections
}

Configuration

EventLogConfig

interface EventLogConfig {
  servers: string | string[];      // NATS server URLs
  streamName: string;               // JetStream stream name
  subjectPrefix: string;            // Subject prefix for events
  auth?: {
    user?: string;
    pass?: string;
    token?: string;
  };
  connection?: {
    name?: string;
    timeout?: number;
    reconnect?: boolean;
    maxReconnectAttempts?: number;
  };
}

ConsumerConfig

interface ConsumerConfig {
  name: string;                     // Consumer name
  group?: string;                   // Consumer group for load balancing
  filterSubjects?: string[];        // Filter specific subjects
  deliverPolicy?: "all" | "last" | "new" | "by_start_sequence" | "by_start_time";
  ackPolicy?: "none" | "all" | "explicit";
  maxAckPending?: number;           // Max outstanding acks
}

Subject Routing

Events are published to subjects following this pattern:

{subjectPrefix}.{tenantId}.{eventType}

For example:

  • aurora.events.tenant1.TaskCreated
  • aurora.events.tenant2.TaskStatusChanged

This enables:

  • Tenant isolation - Each tenant's events on separate subjects
  • Selective subscription - Workers can filter by tenant or event type
  • Efficient routing - NATS routes only relevant events to consumers

Stream Configuration

The JetStream stream is automatically created with:

  • Retention: Interest-based (deleted when no consumers are subscribed)
  • Storage: File-based for durability
  • Subjects: {subjectPrefix}.> (all events under the prefix)

Error Handling

All operations return Effect types with proper error handling:

import { catch as catchEffect } from "@aurora/runtime-effect";

const appendEffect = eventLog.append(...);

const withErrorHandling = catchEffect(appendEffect, (error) => {
  console.error("Failed to append event:", error);
  return succeed({ sequence: 0, timestamp: new Date(), duplicate: false });
});

Testing

# Unit tests
bun test

# Integration tests (requires NATS)
podman-compose up -d nats
bun test

Example

See examples/tasks-app for a complete example of using EventLog with projections.

License

[Your License]

Dependencies

Dependencies

ID Version
@aurora/runtime-effect 0.3.3
@aurora/runtime-observability 0.3.3
@aurora/runtime-projection-state 0.3.3
nats ^2.28.2
Details
npm
2025-12-27 10:44:48 +00:00
13
latest
7.5 KiB
Assets (1)
runtime-eventlog-0.3.3.tgz 7.5 KiB
Versions (3) View all
0.3.3 2025-12-27
0.3.2 2025-12-27
0.3.1 2025-12-27