Adapters

Source: packages/core/src/io/adapters/, packages/adapter-file/, packages/adapter-http/, packages/adapter-stream/, packages/adapter-composite/

Adapters receive events one at a time during generation and route them to their final destination. All adapters implement the OutputAdapter interface.

OutputAdapter

interface OutputAdapter {
  write(event: Event): Promise<void> | void;
  close?(): Promise<void> | void;
}

write() is called for every generated event. close() is called once after all events have been written -- use it for flushing buffers, closing handles, or finalizing connections.

ConsoleAdapter

Writes events to stdout as pretty-printed JSON. Default adapter when none is specified.

import { generate, ConsoleAdapter } from '@synode/core';

await generate(journey, { users: 5, adapter: new ConsoleAdapter() });

InMemoryAdapter

Stores events in an in-memory array. Useful for testing and dry runs.

import { InMemoryAdapter } from '@synode/core';

const adapter = new InMemoryAdapter();
await generate(journey, { users: 10, adapter });
console.log(adapter.events.length);
adapter.clear(); // reset stored events

Properties: events: Event[] (readonly array of captured events).

Methods: clear() -- empties the stored events array.

FileAdapter

Writes events to the local filesystem. Supports JSONL, JSON, and CSV formats with optional daily partitioning.

import { FileAdapter } from '@synode/adapter-file';

const adapter = new FileAdapter({
  path: './out/events.jsonl',
  format: 'jsonl',
});
await generate(journey, { users: 100, adapter });

FileAdapterOptions

interface FileAdapterOptions {
  path: string; // Output file or directory path
  format: 'jsonl' | 'json' | 'csv'; // Serialization format
  partition?: 'daily' | 'none'; // Partitioning strategy (default: 'none')
  filePattern?: string; // Template for partitioned names (default: 'events-{date}.{ext}')
}

Partition placeholders: {date} (YYYY-MM-DD from event timestamp), {ext} (format extension).

HttpAdapter

Sends events to an HTTP endpoint with batching, retry, and exponential backoff.

import { HttpAdapter } from '@synode/adapter-http';

const adapter = new HttpAdapter({
  url: 'https://api.example.com/events',
  batchSize: 10,
  headers: { Authorization: 'Bearer token' },
});
await generate(journey, { users: 50, adapter });
await adapter.close();

HttpAdapterOptions

interface HttpAdapterOptions {
  url: string; // Target endpoint
  method?: 'POST' | 'PUT'; // HTTP method (default: 'POST')
  headers?: Record<string, string>; // Merged with Content-Type: application/json
  batchSize?: number; // Events per request (default: 1)
  flushInterval?: number; // Flush timer in ms (default: 5000)
  maxRetries?: number; // Retries on 5xx/429 (default: 3)
  transform?: (events: Event[]) => unknown; // Custom payload transform
}

Default payload shape: { events: [...] }. Override with transform.

CallbackAdapter

Forwards each event to a user-supplied callback function.

import { CallbackAdapter } from '@synode/core';

const events: Event[] = [];
const adapter = new CallbackAdapter((event) => events.push(event));
await generate(journey, { users: 10, adapter });

Constructor: new CallbackAdapter(callback: (event: Event) => void | Promise<void>).

CompositeAdapter

Fans out events to multiple child adapters in parallel.

import { CompositeAdapter } from '@synode/adapter-composite';
import { FileAdapter } from '@synode/adapter-file';
import { HttpAdapter } from '@synode/adapter-http';

const adapter = new CompositeAdapter([
  new FileAdapter({ path: './out/events.jsonl', format: 'jsonl' }),
  new HttpAdapter({ url: 'https://webhook.example.com/ingest' }),
]);
await generate(journey, { users: 100, adapter });
await adapter.close(); // closes all children

Constructor: new CompositeAdapter(adapters: OutputAdapter[]).

StreamAdapter

Writes events to a Node.js Writable stream.

import { createWriteStream } from 'node:fs';
import { StreamAdapter } from '@synode/adapter-stream';

const stream = createWriteStream('./events.jsonl');
const adapter = new StreamAdapter(stream);
await generate(journey, { users: 10, adapter });
await adapter.close();

StreamAdapterOptions

interface StreamAdapterOptions {
  format?: 'json' | 'jsonl'; // default: 'jsonl'
}

• jsonl: writes each event immediately as a single JSON line
• json: buffers all events, writes a pretty-printed JSON array on close()

Constructor: new StreamAdapter(stream: Writable, options?: StreamAdapterOptions).