magicdef

MagicDef 🪄

Create and execute remote functions in a peer-to-peer network

MagicDef is a JavaScript library that allows you to share and execute functions in a distributed manner on a peer-to-peer network using Hyperswarm. With MagicDef, you can create applications where multiple nodes can share their functions and execute them remotely without needing a central server.

Features

• 🔗 Peer-to-Peer: Direct communication between nodes without central server
• 🚀 Remote Execution: Execute functions on other peers in the network
• 🔍 Auto Discovery: Automatically find available functions
• ⚡ Real Time: Instant communication between peers
• 🛡️ No External Dependencies: Only requires Hyperswarm for networking
• 📦 Easy to Use: Simple and intuitive API

Installation

Requirements

• Node.js 16.0 or higher

Install

npm install magicdef

Basic Usage

1. Create Instance and Connect

ES Modules (Also supports CommonJS):

import MagicDef from 'magicdef'

// Create instance for a specific room
const md = new MagicDef()

// Connect to P2P network
await md.connect('my-function-room')

2. Export Functions

// Define functions to share
function add(a, b) {
  return a + b
}

function greet(name) {
  return `Hello, ${name}!`
}

// Export functions to the network
md.export(add, greet)

3. Execute Functions

async function callFunctions(){
  // Execute local or remote function (automatic)
  const result = await md.add(5, 3)
  console.log(result) // 8

  const greeting = await md.greet('World')
  console.log(greeting) // "Hello, World!"
}
callFunctions()

4. Multiple Instances (Optional)

// Create multiple instances for different rooms
const room1 = new MagicDef()
const room2 = new MagicDef()

await room1.connect('chat-room')
await room2.connect('work-room')

// Each instance is independent
room1.export(chatFunction)
room2.export(workFunction)

5. Example: Peer 1 vs Peer 2

Peer 1 - Chat room:

// Peer 1 - Chat room
const chatRoom = new MagicDef()
await chatRoom.connect('chat')

function greet(name) {
  return `Hello ${name}!`
}

chatRoom.export(greet)

// Use function from Peer 2
async function results(){
  const result = await chatRoom.calculate(5, 3)
  console.log(result) // 8
}
results()

Peer 2 - Same chat room:

// Peer 2 - Same chat room
const chatRoom = new MagicDef()
await chatRoom.connect('chat')

function calculate(a, b) {
  return a + b
}

chatRoom.export(calculate)

// Use function from Peer 1
async function results(){
  const greeting = await chatRoom.greet('World')
  console.log(greeting) // "Hello World!"
}
results()

⚠️ Error Handling

When a remote function cannot be executed, MagicDef returns an error object instead of throwing an exception:

const result = await md.nonExistentFunction(1, 2)

if (result.error) {
  console.log('Error:', result.message)
  console.log('Type:', result.type)
}

Error Types:

• NO_PEERS: No peers connected to the network
• NO_FUNCTIONS: There are peers but they haven't shared functions
• FUNCTION_NOT_FOUND: The function doesn't exist in any peer
• TIMEOUT: The function didn't respond within 5 seconds

⚠️ Security Considerations

• Code execution: MagicDef executes code received from other peers
• Trust: Only execute functions from peers you trust
• Validation: Consider validating parameters before executing functions
• Private networks: Use unique topics for private networks

Advantages of using MagicDef

Simplified Networks

• Automatic configuration - Just write your room name and you're done
• Works anywhere - Home, office, cloud, no additional configuration needed
• No complex infrastructure - No servers, ports or DNS needed
• Direct connection - Peers find each other automatically
• Built-in encryption - Automatic security without configuration
• Natural scalability - More peers = more capacity automatically

Transparent Execution

• No configuration - Works locally and remotely automatically
• Smart proxy - Call functions as if they were local
• Error handling - Clear responses when something fails

Flexible Architecture

• Multiple instances - Each instance is independent
• Multiple rooms - Different networks for different purposes
• Scalability - Works with 2 or 200 peers

Ideal Use Cases

• Distributed microservices - No need for API Gateway
• Distributed computing - Share processing functions
• Collaborative chatbots - Shared AI functions
• Multiplayer games - Distributed game logic
• Development tools - Share utilities between teams

Why MagicDef?

• No VPN needed - Connect peers directly without tunnels
• No Tailscale needed - Automatic discovery without configuration
• No servers needed - P2P communication without infrastructure
• No APIs needed - Call functions directly as if they were local
• No WebSockets needed - Automatic and persistent connections
• No gRPC needed - Simple and transparent protocol

🔗 Related Links

• Hyperswarm - Peer discovery and communication
• Holepunch - P2P networking tools