Streamock

A simple data streaming mock server built with Bun + TypeScript.

Prerequisites

• Bun installed on your machine

Installation

You can install Streamock globally using npm:

npm install -g streamock

Or using bun:

bun install -g streamock

Quick Start

Start the server:

streamock start

This will start a server at http://localhost:3001

CLI Commands

Streamock provides a complete set of process management commands:

Basic Commands

# Start server (foreground)
streamock start
streamock start -p 8080              # Custom port

# Start in background (daemon mode)
streamock start -d

# Stop server
streamock stop
streamock stop -p 8080               # Stop specific port

# Restart server
streamock restart

# Check status
streamock status

Auto-Update

Streamock automatically checks for updates when you start the server. The update uses npm for better stability.

Control auto-update behavior:

# Skip version check
export STREAMOCK_SKIP_VERSION_CHECK=true
streamock start

# Force update requirement
export STREAMOCK_FORCE_UPDATE=true
streamock start

# Disable auto-update (check only)
export STREAMOCK_AUTO_UPDATE=false
streamock start

Manual update:

# Recommended: Use npm for stability
npm install -g streamock@latest

# Or use your preferred package manager
bun add -g streamock@latest
pnpm add -g streamock@latest
yarn global add streamock@latest

Examples

# Development: Start in foreground
streamock start

# Production: Start in background
streamock start -d

# View logs
tail -f /tmp/streamock-3001.log

# Restart after updates
streamock restart

Template Variables

Streamock supports template variables in your mock data using {{variable_name}} syntax:

Quick Example

1. Add variables in your data:

data: {"session_id": "{{session_id}}", "query": "{{query}}", "action": "chat"}

2. System auto-detects variables:

• Click "Start Streaming" - auto-generates random values
• Or call API with parameters:

curl -X POST "http://localhost:3001/api/stream" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "test-123", "query": "buy me a tv"}'

Variable Types

• Auto: Automatically extracted from requests or randomly generated
• Fixed: Use fixed values

Auto-Generation Rules

| Variable Name | Generated Value | |---------------|----------------| | Contains id, session | UUID v4 format | | Contains query, text | Random example queries | | Contains user | User ID format | | Others | Generic random values |

Development

1. Clone the repository:

git clone https://github.com/Wangggym/streamock.git
cd streamock

2. Install dependencies:

bun install

3. Start in development mode:

bun run dev

4. Build the project:

bun run build

5. Run tests:

# Run all unit tests
bun test

# Test storage location functionality
bun run test:storage

For detailed testing information, see TESTING.md

Project Structure

streamock/
├── src/
│   ├── server.ts      # Main server implementation
│   ├── cli.ts         # CLI implementation
│   └── devServer.ts  # Server runner
├── dist/              # Compiled JavaScript files
├── index.html         # Web interface
└── package.json       # Project configuration

How it Works

1. The server serves a single HTML page with a form and a results area
2. When the user submits data:
   • The form submission is handled via a POST request to /submit
   • A Server-Sent Events connection is established via /stream
3. The server streams the data back to the client with configurable options:
   • Line combination: Combine multiple lines using specified range
   • Custom separators: Use custom separators between lines
   • Real-time updates: See the streaming data immediately

Features

• Stream data with customizable delay
• Combine multiple lines with custom separator
• Web interface for data input and streaming
• Real-time data updates
• Support for custom separators and line combinations
• Built with Bun for better performance
• Written in TypeScript for type safety
• iCloud sync support for Mac users - automatically sync data across your devices

Data Storage

Mac Users (with iCloud)

Your mock data is automatically stored in iCloud Drive at:

~/Library/Mobile Documents/com~apple~CloudDocs/.streamock-data/

This means:

• ✅ Data syncs automatically across all your Mac devices
• ✅ No manual setup required - just sign in to iCloud
• ✅ Your mock data is always backed up
• 💡 If iCloud is unavailable, it automatically falls back to local storage

Other Systems / Without iCloud

Data is stored locally at:

~/.streamock-data/

Viewing Your Storage Location

When you start the server, it will display the storage location:

streamock start
# Output:
# ✅ Server running at http://localhost:3001
# 💾 Data storage: /Users/yourname/Library/Mobile Documents/com~apple~CloudDocs/.streamock-data
# 💡 Press Ctrl+C to stop the server

API Endpoints

• GET /: Serves the web interface
• POST /submit: Updates the server's data cache
• GET /stream: Streams the data back to the client

Configuration

The server can be configured with the following options:

interface ServerConfig {
  port: number;  // Default: 3001
  // ... other Bun.serve options
}

License

MIT License - see the LICENSE file for details

GitHub Repository

For more information, to report issues, or to contribute, please visit: https://github.com/Wangggym/streamock