nano-invoke/README.md

Simple IPC client for Nano Framework applications

# nano-invoke

Simple, clean IPC client for Nano Framework applications. Connect your frontend to your Rust backend with minimal setup.

## Installation

```bash
npm install nano-invoke
```

## Quick Start

```typescript
import { invoke, configure } from 'nano-invoke';

// Optional: Configure the client
configure({
  debug: true,
  timeout: 5000
});

// Call any registered nano function
const result = await invoke('greet', { name: 'World' });
console.log(result); // "Hello, World!"

// Call external system functions
const calculation = await invoke('calculate', {
  operation: 'add',
  values: [10, 20, 30]
});
console.log(calculation.result); // 60
```

## Features

- 🚀 **Simple API** - Just `invoke(functionName, args)`
- 📡 **WebSocket Events** - Real-time communication support
- 🔧 **TypeScript** - Full type safety with IntelliSense
- ⚡ **Lightweight** - Zero dependencies
- 🛠️ **Configurable** - Timeout, debug mode, custom URLs
- 🔄 **Auto-reconnect** - WebSocket reconnection handling

## API Reference

### `invoke(cmd, args)`

Call a Rust function registered in your Nano application.

```typescript
import { invoke } from 'nano-invoke';

// Simple function call
const greeting = await invoke('greet', { name: 'Alice' });

// With typed response
interface UserData {
  id: number;
  name: string;
  email: string;
}

const user = await invoke<UserData>('get_user', { id: 123 });
```

### `configure(options)`

Configure the client behavior.

```typescript
import { configure } from 'nano-invoke';

configure({
  baseUrl: 'http://localhost:3030',  // Custom server URL
  debug: true,                       // Enable debug logging
  timeout: 10000                     // Request timeout in ms
});
```

### Event System

Listen to real-time events from your Rust backend.

```typescript
import { events } from 'nano-invoke';

// Connect to WebSocket
await events.connect();

// Listen for events
events.on('notification', (data) => {
  console.log('Received notification:', data);
});

// Send messages
events.send({ type: 'ping' });

// Clean up
events.off('notification', listener);
events.disconnect();
```

### Utilities

Built-in utility functions.

```typescript
import { Utils } from 'nano-invoke';

// Check if server is running
const isOnline = await Utils.isServerRunning();

// Ping the server
const pong = await Utils.ping();

// Get system information
const sysInfo = await Utils.getSystemInfo();
```

## Type Definitions

Common command types are provided for convenience:

```typescript
import { Commands } from 'nano-invoke';

// System information
const sysInfo = await invoke<Commands.SystemInfo>('get_system_info');

// File operations
const fileInfo = await invoke<Commands.FileInfo>('get_file_info', { 
  path: '/path/to/file' 
});

// Calculations
const result = await invoke<Commands.CalculationResult>('calculate', {
  operation: 'multiply',
  values: [5, 10, 2]
});
```

## Error Handling

```typescript
try {
  const result = await invoke('my_function', { data: 'test' });
} catch (error) {
  if (error.message.includes('not found')) {
    console.log('Function not registered in Rust backend');
  } else if (error.message.includes('connect')) {
    console.log('Server is not running');
  } else {
    console.log('Function error:', error.message);
  }
}
```

## Usage with Nano Framework

1. **Install nano-invoke** in your frontend:
   ```bash
   npm install nano-invoke
   ```

2. **Register functions** in your Rust backend (`nano_registry.rs`):
   ```rust
   pub fn register_all_nano_functions() {
       register_nano_command!("greet", greet);
       register_nano_command!("calculate", external_systems::calculator::calculate);
   }
   ```

3. **Call from frontend**:
   ```typescript
   import { invoke } from 'nano-invoke';
   
   const greeting = await invoke('greet', { name: 'World' });
   const result = await invoke('calculate', { operation: 'add', values: [1, 2] });
   ```

## Browser Compatibility

- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- All modern browsers with ES2020 and WebSocket support

## License

MIT License - see LICENSE file for details.

## Support

- 📧 Email: uziidevelopment@gmail.com
- 🐛 Issues: [GitHub Issues](https://github.com/imperium-industries/nano-invoke/issues)
- 🏠 Homepage: [https://imperiuminteractive.com](https://imperiuminteractive.com)