MicroCAP JavaScript Library

A TypeScript implementation of the Collaborative Application Platform (CAP) for building distributed, message-based applications. This framework provides robust distributed communication capabilities for scalable, resilient systems.

Description

MicroCap is a distributed agent communication framework designed for building scalable, message-based systems. It implements the Collaborative Application Platform (CAP) to enable reliable communication between distributed components while maintaining loose coupling and high flexibility.

Installation

The package is not yet published to npm. To install directly from GitHub:

# Clone the repository
git clone https://github.com/rajan-chari/microcap.git

# Navigate to the TypeScript directory
cd microcap/typescript

# Install dependencies
npm install

# Build the project
npm run build

To use as a dependency in another project, you can add it to your package.json:

{
  "dependencies": {
    "rc-microcap": "github:rajan-chari/microcap#main"
  }
}

Features

• Distributed actor-based architecture
• Flexible message-based communication
• Publish-subscribe pattern support
• Built-in service discovery
• Scalable broker-based messaging
• Type-safe message handling
• Asynchronous communication
• Error handling and recovery

Available Scripts

# Build the TypeScript project
npm run build

# Run tests
npm run test

# Generate Protocol Buffer TypeScript definitions
npm run generate-proto

# Run examples:
npm run example          # Simple ping pong example
npm run simple-actor    # Simple actor demo
npm run multi-agent     # Multi-agent demo
npm run logger-demo     # Logger demonstration
npm run debug-messages  # Message debug listener
npm run broker          # Standalone broker
npm run directory       # Standalone directory service

Core Components

RuntimeFactory

The RuntimeFactory provides a centralized way to create and manage different runtime implementations:

import { RuntimeFactory } from 'microcap-js';

// Get the default runtime
const runtime = RuntimeFactory.getRuntime();

// Create a runtime with specific configuration
const customConfig = {
  pub_url: 'tcp://localhost:6666',
  sub_url: 'tcp://localhost:6667',
};
const customRuntime = RuntimeFactory.createRuntime('default', customConfig);

// Register a custom runtime implementation
class MyCustomRuntime implements IRuntime {
  // Your custom implementation
}
RuntimeFactory.registerRuntime('custom', new MyCustomRuntime());
const myRuntime = RuntimeFactory.getRuntime('custom');

Actor

Actors are the basic building blocks of the system:

import { Actor, RuntimeFactory } from 'microcap-js';

// Create an actor
const actor = new Actor('MyActor', 'My actor description');

// Register with a runtime
const runtime = RuntimeFactory.getRuntime();
runtime.register(actor);

// Connect to the network
await runtime.connect();

Utility Functions

The library also includes utility functions for working with arrays and objects:

• groupBy: Group array items by a specified key
• chunk: Split arrays into smaller chunks of specified size
• uniqueBy: Remove duplicates from an array based on a key
• keyBy: Create an object from an array using a specified key

Examples

See the examples directory for complete usage examples.

Development

# Install dependencies
npm install

# Run tests
npm test

# Build the library
npm run build

Dependencies

Core dependencies:

• typescript (^5.3.3) - TypeScript compiler and language
• protobufjs (^7.2.6) - Protocol Buffers for message serialization
• uuid (^9.0.1) - UUID generation
• debug (^4.3.4) - Debug logging utility

Development dependencies remain unchanged.

For a complete list of dependencies, see DEPENDENCIES.md

License

MIT