server-function-bridge/README.md

Run server-side Node.js functions directly from client-side JavaScript using WebSockets

# Server Function Bridge

Run Node.js server functions directly from client-side JavaScript using WebSockets - without building an API or setting up endpoints.

## Features

- ✅ Call server-side Node.js functions directly from client code
- ✅ No API endpoints to maintain
- ✅ No build process modifications required
- ✅ Lazy-loading WebSocket connection
- ✅ Works in both development and production environments
- ✅ Secure SSL/TLS communication
- ✅ Detailed logging and error handling

## Installation

```bash
npm install server-function-bridge
```

## Quick Start

### Server-Side Setup

```javascript
// server.js
const express = require('express');
const { setupServerFunctionBridge } = require('server-function-bridge/server');
const path = require('path');

// Create your Express app
const app = express();

// Setup the Server Function Bridge
setupServerFunctionBridge(app, {
  port: 8080, // WebSocket port (default: 8080)
  scriptsDir: path.join(__dirname, 'server-functions'), // Where your functions are stored
  ssl: {
    key: fs.readFileSync('path/to/key.pem'),
    cert: fs.readFileSync('path/to/cert.pem')
  }
});

// Your existing app setup
app.use(express.static('public'));

// Start your server
app.listen(3000, () => {
  console.log('Server running on port 3000');
});
```

### Create Server Functions

Create server-side functions in your `server-functions` directory:

```javascript
// server-functions/helloWorld.js
module.exports = async function helloWorld(name) {
  return {
    message: `Hello, ${name || 'World'}!`,
    timestamp: new Date().toISOString()
  };
};
```

### Client-Side Usage

```javascript
// In your React component or JavaScript file
import { serverCall } from 'server-function-bridge/client';

// Create a server function reference
const helloWorld = serverCall('helloWorld');

// Call it like a normal function
const result = await helloWorld('John');
console.log(result.message); // "Hello, John!"
```

## Detailed Documentation

### Server Configuration Options

The `setupServerFunctionBridge` function accepts the following options:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `port` | Number | `8080` | WebSocket server port |
| `scriptsDir` | String | `path.join(process.cwd(), 'src', 'scripts')` | Directory containing server functions |
| `ssl` | Object | `undefined` | SSL configuration with `key` and `cert` properties |
| `logging` | Boolean/Object | `{ enabled: true, detailed: false }` | Logging configuration |
| `path` | String | `/ws` | WebSocket server path |
| `authFunction` | Function | `undefined` | Optional function for connection authentication |

### Client Configuration Options

The `serverCall` function accepts the following options:

```javascript
// With custom options
const helloWorld = serverCall('helloWorld', {
  timeout: 5000, // 5 second timeout (default: 10000)
  reconnect: true, // Auto-reconnect on disconnection
  debug: true // Verbose logging
});
```

### Advanced Usage

#### Connection Management

```javascript
import { getConnection, closeConnection } from 'server-function-bridge/client';

// Get the WebSocket connection
const connection = getConnection();

// Manually close the connection when done
closeConnection();
```

#### Custom WebSocket URL

```javascript
import { configure, serverCall } from 'server-function-bridge/client';

// Configure custom WebSocket URL
configure({
  url: 'wss://api.example.com/websocket',
  debug: true
});

// Now use serverCall as normal
const helloWorld = serverCall('helloWorld');
```

## Security Considerations

- The WebSocket server accepts connections from any origin by default
- Consider implementing the `authFunction` option for authentication
- Use HTTPS and WSS protocols in production
- Be careful about which server functions you expose

## License

MIT