RailJS

A lightweight event bus for building modular JavaScript applications with strict module isolation.

RailJS is a simple, well-tested event emitter that helps you build applications using isolated modules that communicate only through events. Perfect for projects where you want clear boundaries between components without the complexity of a full framework.

Features

Module Isolation: Modules communicate exclusively through events, not direct imports
Data Safety: Automatic deep cloning prevents unintended side effects between modules
Simple API: Familiar event emitter pattern with attach/detach module lifecycle
Hot-swappable: Add or remove modules at runtime without restarting
Universal: Works in Node.js, Deno, and browsers
TypeScript Support: Full type definitions for type-safe development
Testing-friendly: Built-in utilities for testing modules in isolation

Core Concept

Module A ──┐
Module B ──┼─── RAIL (central event bus) ───>
Module C ──┘

- Modules communicate only through events
- All events flow through the central Rail
- Modules can be attached/detached at runtime
- Each module maintains its own state and logic

Quick Start

Installation

npm install railjs-core
# or
yarn add railjs-core

CDN Usage (Browser)

<!-- UMD build (development) -->
<script src="https://unpkg.com/railjs-core/dist/rail.umd.js"></script>

<!-- UMD build (production, minified) -->
<script src="https://unpkg.com/railjs-core/dist/rail.umd.min.js"></script>

<script>
  const rail = new RailJS.Rail({ debug: true });
  // Use rail...
</script>

TypeScript Support

RailJS includes full TypeScript definitions out of the box:

import { Rail, RailModule, RailOptions } from 'railjs';

interface UserData {
	email: string;
	name: string;
}

const rail = new Rail({ debug: true });

// Type-safe event handlers
rail.on<UserData>('user.created', (data) => {
	console.log(data.email); // TypeScript knows data has email property
});

// Type-safe event emission
rail.emit<UserData>('user.created', { email: '[email protected]', name: 'John' });

See example.ts for a complete TypeScript usage example.

Run the Demo

# Node.js
node demo.js

# Deno
deno run --allow-read demo.js

# Browser (serve the files)
python -m http.server 8000
# Then open http://localhost:8000

Example Output

Modules communicating through events:

🚂 [demo-app] Rail started in debug mode
🔗 [demo-app] Attached module 'auth'
🔗 [demo-app] Attached module 'database'
🔗 [demo-app] Attached module 'email'

🔥 [demo-app] Emitting 'user.login': {email: "[email protected]", password: "demo123"}
   ↳ auth handling 'user.login'
🔐 Auth: Processing login attempt...
🔥 [demo-app] Emitting 'auth.success': {token: "jwt-1234", user: {...}}
   ↳ database handling 'auth.success'
   ↳ email handling 'auth.success'
💾 Database: Saving login session...
📧 Email: Sending welcome email...

📂 Project Structure

railjs-starter/
├── README.md           # This file
├── rail.js            # Core Rail implementation
├── demo.js            # Working demo application
├── test.js            # Test suite
└── modules/           # Example modules
    ├── auth.js        # Authentication
    ├── database.js    # Data storage
    ├── email.js       # Email notifications
    ├── logger.js      # Logging system
    └── notifications.js # User notifications

🧩 Creating Your First Module

// my-module.js
export const myModule = {
	name: 'my-module',

	connect(rail) {
		// Listen for events
		rail.on(
			'input.event',
			(data) => {
				console.log('Processing:', data);

				// Do your work here
				const result = processData(data);

				// Emit the result
				rail.emit('output.event', result);
			},
			'my-module'
		);
	},

	disconnect(rail) {
		// Cleanup if needed
	},
};

// Attach to your rail
import { Rail } from './rail.js';
const rail = new Rail({ debug: true });
rail.attach(myModule);

🔥 Core API

Creating a Rail

import { Rail } from './rail.js';

const rail = new Rail({
	name: 'my-app', // Optional: Rail name for debugging
	debug: true, // Optional: Enable debug logging
	clone: true, // Optional: Deep clone event data (default: true)
});

Performance vs Safety:

clone: true (default) - Guarantees data isolation between modules but slower
clone: false - Better performance but modules can modify shared data

Module Pattern

Every module follows this simple pattern:

const module = {
	name: 'module-name', // Required: Unique module name

	connect(rail) {
		// Called when attached
		rail.on('event', handler, 'module-name');
	},

	disconnect(rail) {
		// Called when detached (optional)
		// Cleanup code
	},
};

Event Communication

// Emit events (synchronous)
rail.emit('user.login', { email: '[email protected]', password: 'secret' });

// Emit events (asynchronous) - waits for all handlers to complete
const results = await rail.emitAsync('user.login', {
	email: '[email protected]',
	password: 'secret'
});
// results: [{ module: 'auth', result: {...}, error: null }, ...]

// Listen for events
rail.on(
	'user.login',
	(data) => {
		console.log('Login attempt:', data.email);
	},
	'auth-module'
);

// Listen with async handlers
rail.on(
	'user.login',
	async (data) => {
		const user = await database.findUser(data.email);
		return user; // Return value available in emitAsync results
	},
	'auth-module'
);

// Remove listeners (returns unsubscribe function)
const unsubscribe = rail.on('event', handler);
unsubscribe(); // Stop listening

Module Management

// Attach modules
rail.attach(authModule);
rail.attach(databaseModule);

// Detach modules (safe at any time)
rail.detach('auth-module');

// Get module info
rail.getModules(); // ['database', 'email', 'logger']
rail.getEvents(); // { 'user.login': ['auth'], 'email.send': ['email'] }
rail.getStats(); // { modules: 3, events: 12, totalListeners: 25 }

🧪 Testing Your Modules

RailJS modules are trivially testable:

import { Rail } from './rail.js';

// Test a module in isolation
const rail = new Rail();
rail.attach(myModule);

// Send test events
rail.emit('test.input', { data: 'test' });

// Wait for results
const result = await rail.waitFor('test.output');
console.log('Module output:', result);

Running Tests

# Run tests with Vitest
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Run legacy test suite
npm run test:legacy

Test Coverage:

20 comprehensive test cases
81.75% code coverage
Tests for cloning, async handlers, module lifecycle, error isolation

🎨 Example: Building a Chat App

// chat-room.js
const chatRoomModule = {
	name: 'chat-room',
	rooms: new Map(),

	connect(rail) {
		rail.on(
			'chat.join',
			(data) => {
				const { roomId, userId, username } = data;

				if (!this.rooms.has(roomId)) {
					this.rooms.set(roomId, new Set());
				}

				this.rooms.get(roomId).add({ userId, username });

				rail.emit('chat.user.joined', { roomId, userId, username });
			},
			'chat-room'
		);

		rail.on(
			'chat.message',
			(data) => {
				const { roomId, userId, message } = data;

				rail.emit('chat.message.broadcast', {
					roomId,
					userId,
					message,
					timestamp: new Date(),
				});
			},
			'chat-room'
		);
	},
};

// message-history.js
const messageHistoryModule = {
	name: 'message-history',
	history: new Map(),

	connect(rail) {
		rail.on(
			'chat.message.broadcast',
			(data) => {
				const { roomId } = data;

				if (!this.history.has(roomId)) {
					this.history.set(roomId, []);
				}

				this.history.get(roomId).push(data);

				rail.emit('message.stored', {
					roomId,
					messageId: data.timestamp,
				});
			},
			'message-history'
		);
	},
};

// Connect them
rail.attach(chatRoomModule);
rail.attach(messageHistoryModule);

// Use the system
rail.emit('chat.join', { roomId: 'general', userId: 1, username: 'Alice' });
rail.emit('chat.message', { roomId: 'general', userId: 1, message: 'Hello!' });

Data Isolation

RailJS automatically clones event data to prevent modules from affecting each other:

Preventing Side Effects

const original = { secret: 'password123' };

rail.on('process.data', (data) => {
	data.secret = 'hacked!'; // This won't affect the original
});

rail.emit('process.data', original);
console.log(original.secret); // Still 'password123'

Module Isolation

// ❌ Avoid: Direct module dependencies
import OtherModule from './other-module';
OtherModule.getData();

// ✅ Prefer: Event-based communication
rail.emit('data.request', { type: 'user' });
rail.on('data.response', (data) => { /* handle data */ });

Error Isolation

rail.on(
	'risky.operation',
	() => {
		throw new Error('Module crashed!');
	},
	'broken-module'
);

rail.on(
	'risky.operation',
	() => {
		console.log('I still work!'); // ✅ This still executes
	},
	'good-module'
);

rail.emit('risky.operation'); // Both handlers run, error is contained

🎯 Common Patterns

Request-Response Pattern

// Async request-response (recommended)
rail.on('user.get', async (data) => {
	const user = await database.findUser(data.userId);
	return user; // Return the data directly
}, 'database');

const results = await rail.emitAsync('user.get', { userId: 123 });
const user = results[0].result; // Get result from first handler

// Traditional event-based request-response
rail.emit('user.get', { userId: 123 });

rail.on(
	'user.get',
	(data) => {
		const user = database.findUser(data.userId);
		rail.emit('user.data', { userId: data.userId, user });
	},
	'database'
);

Chain of Processing

// Input validation
rail.on(
	'user.register',
	(data) => {
		if (isValid(data)) {
			rail.emit('user.validated', data);
		} else {
			rail.emit('validation.failed', { errors });
		}
	},
	'validator'
);

// Create user
rail.on(
	'user.validated',
	(data) => {
		const user = createUser(data);
		rail.emit('user.created', user);
	},
	'user-manager'
);

// Send welcome email
rail.on(
	'user.created',
	(user) => {
		rail.emit('email.send', {
			to: user.email,
			template: 'welcome',
			data: user,
		});
	},
	'email'
);

State Management

const stateModule = {
	name: 'state',
	store: new Map(),

	connect(rail) {
		rail.on(
			'state.set',
			(data) => {
				this.store.set(data.key, data.value);
				rail.emit('state.changed', {
					key: data.key,
					value: data.value,
				});
			},
			'state'
		);

		rail.on(
			'state.get',
			(data) => {
				const value = this.store.get(data.key);
				rail.emit('state.value', { key: data.key, value });
			},
			'state'
		);
	},
};

🛠️ Debugging Tools

Debug Mode

const rail = new Rail({ debug: true });

// Shows all events:
// 🔥 [my-app] Emitting 'user.login': {email: "test@example.com"}
//    ↳ auth handling 'user.login'
//    ↳ logger handling 'user.login'

Event History

// Get recent events
const history = rail.getHistory(10);
console.log('Last 10 events:', history);

// Clear history
rail.clearHistory();

Wait for Events (Testing)

// Wait for specific event
const result = await rail.waitFor('auth.success', 5000); // 5 second timeout

// Use in tests
test('login works', async () => {
	rail.emit('user.login', credentials);
	const result = await rail.waitFor('auth.success');
	expect(result.token).toBeDefined();
});

🚀 Next Steps

1. Try the Examples

Run node demo.js to see the full system in action
Modify modules and see how they interact
Try detaching modules while the system runs

2. Build Your Own Modules

Start with the module template above
Follow the single responsibility principle
Use clear event names (noun.verb format)

3. Common Module Ideas

API Gateway: Handle HTTP requests → emit internal events
Rate Limiter: Monitor events → emit rate limit warnings
Cache: Store/retrieve data based on events
Analytics: Track events → emit metrics
Queue: Buffer events → emit when ready to process

4. Architecture Patterns

CQRS: Separate read/write modules
Event Sourcing: Store all events, replay state
Microservices: Each module as a separate service
Plugin System: Dynamically load/unload modules

📖 Event Naming Conventions

Use clear, consistent event names:

// Good event names
'user.login'; // user performs login
'auth.success'; // authentication succeeded
'email.send'; // request to send email
'email.sent'; // email was sent
'payment.process'; // process a payment
'payment.completed'; // payment finished successfully
'data.user.create'; // create user in database
'cache.invalidate'; // clear cache

// Avoid these
'login'; // too vague
'userAuthSuccess'; // not dot-separated
'EMAIL_SEND'; // use lowercase
'handleUserLogin'; // sounds like function name

Use Cases

RailJS works well for:

Modular applications where you want clear component boundaries
Plugin systems that need to add/remove functionality at runtime
Microservices coordination within a single process
Testing complex systems by swapping modules with mocks
Event sourcing architectures
AI-assisted development where isolated contexts help language models understand code

🐛 Troubleshooting

Common Issues

Module not responding to events

// ❌ Wrong: forgot module name
rail.on('event', handler);

// ✅ Correct: include module name
rail.on('event', handler, 'my-module');

Data contamination between modules

// ❌ Wrong: modifying input data
rail.on('process', (data) => {
	data.processed = true; // This affects other modules!
});

// ✅ Correct: don't modify input, emit new data
rail.on('process', (data) => {
	const result = { ...data, processed: true };
	rail.emit('processed', result);
});

Module won't detach cleanly

// ❌ Wrong: anonymous function
rail.on('event', (data) => {
	/* handler */
});

// ✅ Correct: named function for cleanup
const handler = (data) => {
	/* handler */
};
rail.on('event', handler, 'my-module');

Getting Help

Check the console for debug output
Use rail.getStats() to see system status
Run node test.js to verify core functionality
Look at example modules for patterns

Performance Considerations

RailJS deep-clones all event data by default to ensure module isolation. For high-throughput applications where performance is critical and you trust your modules not to mutate shared data, you can disable cloning:

// High-performance mode (no data cloning)
const rail = new Rail({ clone: false });

// Or toggle it at runtime
rail.setClone(false); // Disable cloning
rail.setClone(true);  // Re-enable cloning

Trade-offs:

With cloning (default): Slower, but modules cannot accidentally contaminate each other's data
Without cloning: Faster, but you must ensure modules don't mutate event data

Use clone: false only when:

Performance benchmarks show cloning is a bottleneck
Your modules treat event data as immutable
You're emitting events in tight loops (thousands per second)

Benchmark Results

Run npm run benchmark to see performance on your machine. Typical results:

Event emission (with cloning):     2,444,611 ops/sec
Event emission (without cloning):  3,622,440 ops/sec
Event with 10 listeners (cloning): 1,077,500 ops/sec
Async event emission:                725,016 ops/sec

Key takeaways:

Cloning adds ~30-50% overhead
Still handles millions of events per second
Memory efficient: 1000 modules + 1000 events = ~0.3 MB
For most applications, the default settings are perfectly fine

Browser Compatibility

RailJS uses only standard JavaScript features and works in all modern browsers:

Browser	Minimum Version	Notes
Chrome	90+	Full support
Firefox	88+	Full support
Safari	14+	Full support
Edge	90+	Full support
Node.js	14.0+	Full support
Deno	1.0+	Full support

Requirements:

ES2020 features (Promise, async/await, Map, Set)
ES Modules support (or use UMD build for older environments)

Legacy browsers: Use the UMD build with a transpiler like Babel for IE11 support.

When Not to Use RailJS

Simple applications - Event-driven architecture adds complexity you may not need
Performance-critical real-time systems - Deep cloning overhead may be too high
Tightly coupled logic - Some problems are better solved with direct function calls

License

MIT License - see LICENSE file for details

Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

Built with clarity and simplicity in mind.

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github		.github
examples		examples
modules		modules
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MIGRATION.md		MIGRATION.md
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
SECURITY.md		SECURITY.md
benchmark.js		benchmark.js
build.js		build.js
demo.js		demo.js
example.ts		example.ts
package-lock.json		package-lock.json
package.json		package.json
rail.d.ts		rail.d.ts
rail.js		rail.js
rail.test.js		rail.test.js
test.js		test.js
tsconfig.json		tsconfig.json
type-check.test.ts		type-check.test.ts
vitest.config.js		vitest.config.js

License

PxPerfectMike/RailJS

Folders and files

Latest commit

History

Repository files navigation

RailJS

Features

Core Concept

Quick Start

Installation

CDN Usage (Browser)

TypeScript Support

Run the Demo

Example Output

📂 Project Structure

🧩 Creating Your First Module

🔥 Core API

Creating a Rail

Module Pattern

Event Communication

Module Management

🧪 Testing Your Modules

Running Tests

🎨 Example: Building a Chat App

Data Isolation

Preventing Side Effects

Module Isolation

Error Isolation

🎯 Common Patterns

Request-Response Pattern

Chain of Processing

State Management

🛠️ Debugging Tools

Debug Mode

Event History

Wait for Events (Testing)

🚀 Next Steps

1. Try the Examples

2. Build Your Own Modules

3. Common Module Ideas

4. Architecture Patterns

📖 Event Naming Conventions

Use Cases

🐛 Troubleshooting

Common Issues

Getting Help

Performance Considerations

Benchmark Results

Browser Compatibility

When Not to Use RailJS

License

Contributing

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

Packages