streamock-core

Core streaming mock engine - runtime agnostic.

A lightweight library for creating streaming mock data with template variable support. Works in Node.js, Bun, Deno, and browsers.

Installation

npm install streamock-core

Quick Start

import { StreamEngine, createStreamConfig } from 'streamock-core';

// Create a stream config
const config = createStreamConfig({
  data: `data: {"message": "Hello {{name}}!"}
data: {"message": "How are you?"}
data: [DONE]`,
  variables: [
    { name: 'name', source: 'auto' }
  ]
});

// Create engine and stream
const engine = new StreamEngine(config, {
  delay: 100,
  variables: { name: 'Alice' }
});

// Option 1: Use async iterator
for await (const result of engine.stream()) {
  console.log(result.line);
}

// Option 2: Get SSE Response (for HTTP servers)
const response = engine.createSSEResponse();

// Option 3: Get ReadableStream
const stream = engine.createReadableStream();

Features

Template Variables

Support {{variable}} syntax for dynamic data:

const config = createStreamConfig({
  data: 'Session: {{session_id}}, Query: {{query}}',
  variables: [
    { name: 'session_id', source: 'auto' },      // Auto-generated UUID
    { name: 'query', source: 'fixed', value: 'default' }  // Fixed value
  ]
});

Auto-generation rules:

• Variables containing id or session → UUID v4
• Variables containing query or text → Random text
• Variables containing user → User ID format
• Variables containing time or date → ISO timestamp
• Others → Random string

Line Combination

Combine multiple lines with custom separator:

const config = createStreamConfig({
  data: 'line1\nline2\nline3\nline4',
  combineLine: '2-3',     // Combine lines 2-3
  separator: '|||'        // Use ||| as separator
});
// Output: line1, line2|||line3, line4

Storage Interface

Implement IStorageAdapter for custom storage backends:

import type { IStorageAdapter, StreamConfig } from 'streamock-core';

class MyStorageAdapter implements IStorageAdapter {
  async init() { /* ... */ }
  async save(userId: string, config: StreamConfig) { /* ... */ }
  async get(userId: string, configId: string) { /* ... */ }
  async list(userId: string) { /* ... */ }
  async delete(userId: string, configId: string) { /* ... */ }
  async count(userId: string) { /* ... */ }
}

API Reference

StreamEngine

new StreamEngine(config: StreamConfig, options?: StreamOptions)

Options:

• delay?: number - Delay between lines (ms), default: 100
• variables?: Record<string, string> - Variable values
• stopOnDone?: boolean - Stop on [DONE] marker, default: true

Methods:

• stream() - Returns async iterator
• createReadableStream() - Returns ReadableStream
• createSSEResponse() - Returns Response with SSE headers
• getFullOutput() - Returns complete output as string

Utility Functions

// Template engine
extractTemplateVariables(text: string): string[]
replaceTemplateVariables(text: string, variables: Record<string, string>): string
generateDefaultVariables(variableNames: string[]): Record<string, string>

// Separator
unescapeSeparator(str: string): string
escapeSeparator(str: string): string

// Stream parser
parseStreamData(streamData: string): ParsedStreamData | null
isSSEDataLine(line: string): boolean
isSSEDone(line: string): boolean

// Storage
validateConfigSize(config: StreamConfig, maxSize: number): ValidationResult
createStreamConfig(data: Partial<StreamConfig>): StreamConfig
generateConfigId(): string

Storage Limits

Default limits (can be customized):

import { DEFAULT_STORAGE_LIMITS } from 'streamock-core';

// {
//   maxConfigsPerUser: 50,
//   maxConfigSize: 10 * 1024 * 1024,  // 10MB
//   ttlSeconds: 365 * 24 * 60 * 60,   // 1 year
// }

License

MIT