Peergate-nexa NPM

Nexa.js - WebRTC P2P Communication Client

Read this in other languages: English, 中文

English Documentation

Nexa.js is a lightweight WebRTC-based P2P communication client that simplifies browser-to-server connections using PeerJS. It provides a clean, Promise-based API for making requests to a PeerGate server.

Features

Simplified WebRTC Communication: Abstract away the complexity of WebRTC with a simple API
Promise-based Interface: Modern async/await compatible API
Automatic Connection Management: Handles connection establishment, reconnection, and cleanup
Request/Response Pattern: Familiar HTTP-like request/response pattern for P2P communication
Timeout Handling: Built-in connection and request timeouts
Debug Mode: Comprehensive logging for development and troubleshooting

Installation

Browser

Include the PeerJS library and Nexa.js in your HTML:

<!-- Include PeerJS first -->
<script src="https://unpkg.com/peerjs@1.5.1/dist/peerjs.min.js"></script>

<!-- Include Nexa.js -->
<script type="module">
  import Nexa from "https://unpkg.com/peergate-nexa/index.js";
  Nexa.init("my-server");
  const response = await Nexa.seek("/hello", { message: "hello" });
  console.log(response);
</script>

// Include Nexa.js
import Nexa from "https://unpkg.com/peergate-nexa/index.js";
Nexa.init("my-server");
const response = await Nexa.seek("/hello", { message: "hello" });
console.log(response);

NPM (for bundlers)

npm install peergate-nexa

Then import in your JavaScript:

// Include Nexa.js
import Nexa from "peergate-nexa";

Quick Start

Initialize Nexa with a server ID:

// Initialize with server ID and options
Nexa.init("my-server-id", {
  debug: true, // Enable debug logging
  connectionTimeout: 15000, // Connection timeout in ms
  requestTimeout: 30000, // Request timeout in ms
  autoReconnect: true, // Auto reconnect on disconnection
});

Send requests to the server:

// Using async/await
async function sendRequest() {
  try {
    // Send request to '/hello' route with data
    const response = await Nexa.seek("/hello", { message: "Hello, server!" });
    console.log("Response:", response);
  } catch (error) {
    console.error("Request failed:", error);
  }
}

// Call the function
sendRequest();

Close the connection when done:

// Close the connection
Nexa.close();

Core Concepts

Connection Model

Nexa.js uses a client-server model over WebRTC:

Initialization: Set up the client with a server ID
Lazy Connection: Connection is established on the first request
Request/Response: Send requests to specific routes on the server
Auto-reconnection: Automatically reconnect on disconnection (if enabled)

Request Flow

Client initializes Nexa with Nexa.init(serverId)
Client sends request with Nexa.seek(path, data)
Connection is established automatically if needed
Server processes the request and sends a response
Client resolves the Promise with the response data

API Reference

`Nexa.init(serverId, options)`

Initializes the Nexa client with a server ID and options.

Parameters:

serverId (string): The PeerID of the server to connect to
options (object, optional): Configuration options
- debug (boolean): Enable debug logging (default: false)
- connectionTimeout (number): Connection timeout in ms (default: 10000)
- requestTimeout (number): Request timeout in ms (default: 30000)
- peerOptions (object): PeerJS configuration options
- autoReconnect (boolean): Auto reconnect on disconnection (default: true)

Returns: void

Example:

Nexa.init("my-server-id", {
  debug: true,
  connectionTimeout: 15000,
  requestTimeout: 30000,
  autoReconnect: true,
  peerOptions: {
    // PeerJS specific options
    host: "your-peerjs-server.com",
    port: 9000,
    path: "/myapp",
  },
});

`Nexa.seek(path, body)`

Sends a request to the server and returns a Promise that resolves with the response.

Parameters:

path (string): The route path on the server
body (object, optional): The request data to send

Returns: Promise - Resolves with the server response or rejects with an error

Example:

// Basic usage
Nexa.seek("/hello", { message: "Hello!" })
  .then((response) => console.log("Response:", response))
  .catch((error) => console.error("Error:", error));

// With async/await
async function fetchUser(userId) {
  try {
    const user = await Nexa.seek("/users/" + userId);
    return user;
  } catch (error) {
    throw new Error(`Failed to fetch user: ${error.message}`);
  }
}

`Nexa.getPeerId()`

Gets the client's PeerJS ID.

Returns: string|null - The client's PeerID or null if not initialized

Example:

const myPeerId = Nexa.getPeerId();
console.log("My Peer ID:", myPeerId);

`Nexa.isConnected()`

Checks if the client is connected to the server.

Returns: boolean - True if connected, false otherwise

Example:

if (Nexa.isConnected()) {
  console.log("Connected to server");
} else {
  console.log("Not connected");
}

`Nexa.close()`

Closes the connection to the server and cleans up resources.

Returns: void

Example:

// Close the connection when done
Nexa.close();

`Nexa.debug(enable)`

Enables or disables debug logging.

Parameters:

enable (boolean, optional): Whether to enable debug mode (default: true)

Returns: void

Example:

// Enable debug mode
Nexa.debug(true);

// Disable debug mode
Nexa.debug(false);

Lifecycle Events

Nexa.js manages several internal lifecycle events:

Initialization: When Nexa.init() is called
Connection: When connection to the server is established
Request: When a request is sent to the server
Response: When a response is received from the server
Disconnection: When the connection is closed
Reconnection: When auto-reconnection is attempted

While these events are handled internally, you can observe the connection state using Nexa.isConnected().

Advanced Usage

Custom Error Handling

async function handleRequest() {
  try {
    const response = await Nexa.seek("/api/data");
    return response;
  } catch (error) {
    // Access error details
    console.error(`Error ${error.code}: ${error.message}`);
    console.error("Details:", error.details);

    // Handle specific error codes
    if (error.code === 404) {
      return { error: "Resource not found" };
    } else if (error.code === 403) {
      // Handle authentication errors
      await authenticate();
      return handleRequest(); // Retry after authentication
    }

    throw error; // Re-throw for other errors
  }
}

Connection Management

// Check connection before sending critical data
if (!Nexa.isConnected()) {
  console.warn("Not connected to server, data may be delayed");
}

// Send multiple requests in parallel
async function fetchMultipleResources() {
  try {
    const [users, products, orders] = await Promise.all([
      Nexa.seek("/users"),
      Nexa.seek("/products"),
      Nexa.seek("/orders"),
    ]);

    return { users, products, orders };
  } catch (error) {
    console.error("Failed to fetch resources:", error);
    throw error;
  }
}

Error Handling

Nexa.js provides detailed error information:

Connection Errors: Occur during connection establishment
Request Timeout: When a request exceeds the timeout period
Server Errors: Errors returned by the server
Client Errors: Errors in the client configuration or state

Error objects may include:

message: Error description
code: Error status code (for server errors)
details: Additional error details

Examples

Basic Example

// Initialize Nexa
Nexa.init("my-server");

// Send a simple request
async function sayHello() {
  try {
    const response = await Nexa.seek("/hello", { name: "User" });
    console.log("Server says:", response.greeting);
  } catch (error) {
    console.error("Failed to say hello:", error);
  }
}

// Clean up when done
function cleanup() {
  Nexa.close();
  console.log("Connection closed");
}

Form Submission Example

document
  .getElementById("userForm")
  .addEventListener("submit", async (event) => {
    event.preventDefault();

    const formData = {
      username: document.getElementById("username").value,
      email: document.getElementById("email").value,
      age: parseInt(document.getElementById("age").value),
    };

    try {
      // Initialize if not already
      if (!Nexa.isConnected()) {
        Nexa.init("user-service");
      }

      // Submit form data
      const response = await Nexa.seek("/users/create", formData);

      // Show success message
      showMessage(`User created with ID: ${response.userId}`);
    } catch (error) {
      // Show error message
      showMessage(`Error: ${error.message}`, "error");
    }
  });

中文文档

Nexa.js 是一个轻量级的基于 WebRTC 的 P2P 通信客户端，它使用 PeerJS 简化了浏览器到服务器的连接。它提供了一个简洁的、基于 Promise 的 API，用于向 PeerGate 服务器发送请求。

特性

简化的 WebRTC 通信：通过简单的 API 抽象 WebRTC 的复杂性
基于 Promise 的接口：现代 async/await 兼容的 API
自动连接管理：处理连接建立、重连和清理
请求/响应模式：熟悉的类 HTTP 请求/响应模式用于 P2P 通信
超时处理：内置连接和请求超时
调试模式：用于开发和故障排除的全面日志记录

安装

浏览器

在 HTML 中引入 PeerJS 库和 Nexa.js：

<!-- Include PeerJS first -->
<script src="https://unpkg.com/peerjs@1.5.1/dist/peerjs.min.js"></script>

<!-- Include Nexa.js -->
<script type="module">
  import Nexa from "https://unpkg.com/peergate-nexa/index.js";
  Nexa.init("my-server");
  const response = await Nexa.seek("/hello", { message: "hello" });
  console.log(response);
</script>

// Include Nexa.js
import Nexa from "https://unpkg.com/peergate-nexa/index.js";
Nexa.init("my-server");
const response = await Nexa.seek("/hello", { message: "hello" });
console.log(response);

NPM（用于打包工具）

npm install peergate-nexa

然后在 JavaScript 中导入：

// Include Nexa.js
import Nexa from "peergate-nexa";
Nexa.init("my-server");
const response = await Nexa.seek("/hello", { message: "hello" });
console.log(response);

快速开始

使用服务器 ID 初始化 Nexa：

// 使用服务器 ID 和选项初始化
Nexa.init("my-server-id", {
  debug: true, // 启用调试日志
  connectionTimeout: 15000, // 连接超时（毫秒）
  requestTimeout: 30000, // 请求超时（毫秒）
  autoReconnect: true, // 断开连接时自动重连
});

向服务器发送请求：

// 使用 async/await
async function sendRequest() {
  try {
    // 向 '/hello' 路由发送带数据的请求
    const response = await Nexa.seek("/hello", { message: "你好，服务器！" });
    console.log("响应：", response);
  } catch (error) {
    console.error("请求失败：", error);
  }
}

// 调用函数
sendRequest();

完成后关闭连接：

// 关闭连接
Nexa.close();

核心概念

连接模型

Nexa.js 通过 WebRTC 使用客户端-服务器模型：

初始化：使用服务器 ID 设置客户端
延迟连接：连接在第一次请求时建立
请求/响应：向服务器上的特定路由发送请求
自动重连：断开连接时自动重连（如果启用）

请求流程

客户端通过 Nexa.init(serverId) 初始化 Nexa
客户端通过 Nexa.seek(path, data) 发送请求
如果需要，自动建立连接
服务器处理请求并发送响应
客户端使用响应数据解析 Promise

API 参考

`Nexa.init(serverId, options)`

使用服务器 ID 和选项初始化 Nexa 客户端。

参数：

serverId (string)：要连接的服务器的 PeerID
options (object, 可选)：配置选项
- debug (boolean)：启用调试日志（默认：false）
- connectionTimeout (number)：连接超时（毫秒）（默认：10000）
- requestTimeout (number)：请求超时（毫秒）（默认：30000）
- peerOptions (object)：PeerJS 配置选项
- autoReconnect (boolean)：断开连接时自动重连（默认：true）

返回值：void

示例：

Nexa.init("my-server-id", {
  debug: true,
  connectionTimeout: 15000,
  requestTimeout: 30000,
  autoReconnect: true,
  peerOptions: {
    // PeerJS 特定选项
    host: "your-peerjs-server.com",
    port: 9000,
    path: "/myapp",
  },
});

`Nexa.seek(path, body)`

向服务器发送请求，并返回一个解析为响应的 Promise。

参数：

path (string)：服务器上的路由路径
body (object, 可选)：要发送的请求数据

返回值：Promise - 解析为服务器响应或拒绝并返回错误

示例：

// 基本用法
Nexa.seek("/hello", { message: "你好！" })
  .then((response) => console.log("响应：", response))
  .catch((error) => console.error("错误：", error));

// 使用 async/await
async function fetchUser(userId) {
  try {
    const user = await Nexa.seek("/users/" + userId);
    return user;
  } catch (error) {
    throw new Error(`获取用户失败：${error.message}`);
  }
}

`Nexa.getPeerId()`

获取客户端的 PeerJS ID。

返回值：string|null - 客户端的 PeerID 或未初始化时为 null

示例：

const myPeerId = Nexa.getPeerId();
console.log("我的 Peer ID：", myPeerId);

`Nexa.isConnected()`

检查客户端是否已连接到服务器。

返回值：boolean - 已连接为 true，否则为 false

示例：

if (Nexa.isConnected()) {
  console.log("已连接到服务器");
} else {
  console.log("未连接");
}

`Nexa.close()`

关闭与服务器的连接并清理资源。

返回值：void

示例：

// 完成后关闭连接
Nexa.close();

`Nexa.debug(enable)`

启用或禁用调试日志。

参数：

enable (boolean, 可选)：是否启用调试模式（默认：true）

返回值：void

示例：

// 启用调试模式
Nexa.debug(true);

// 禁用调试模式
Nexa.debug(false);

生命周期事件

Nexa.js 管理几个内部生命周期事件：

初始化：调用 Nexa.init() 时
连接：与服务器建立连接时
请求：向服务器发送请求时
响应：从服务器接收响应时
断开连接：连接关闭时
重新连接：尝试自动重连时

虽然这些事件在内部处理，但您可以使用 Nexa.isConnected() 观察连接状态。

高级用法

自定义错误处理

async function handleRequest() {
  try {
    const response = await Nexa.seek("/api/data");
    return response;
  } catch (error) {
    // 访问错误详情
    console.error(`错误 ${error.code}：${error.message}`);
    console.error("详情：", error.details);

    // 处理特定错误代码
    if (error.code === 404) {
      return { error: "未找到资源" };
    } else if (error.code === 403) {
      // 处理身份验证错误
      await authenticate();
      return handleRequest(); // 身份验证后重试
    }

    throw error; // 重新抛出其他错误
  }
}

连接管理

// 在发送关键数据前检查连接
if (!Nexa.isConnected()) {
  console.warn("未连接到服务器，数据可能会延迟");
}

// 并行发送多个请求
async function fetchMultipleResources() {
  try {
    const [users, products, orders] = await Promise.all([
      Nexa.seek("/users"),
      Nexa.seek("/products"),
      Nexa.seek("/orders"),
    ]);

    return { users, products, orders };
  } catch (error) {
    console.error("获取资源失败：", error);
    throw error;
  }
}

错误处理

Nexa.js 提供详细的错误信息：

连接错误：在连接建立过程中发生
请求超时：当请求超过超时时间
服务器错误：服务器返回的错误
客户端错误：客户端配置或状态中的错误

错误对象可能包括：

message：错误描述
code：错误状态码（对于服务器错误）
details：额外的错误详情

示例

基本示例

// 初始化 Nexa
Nexa.init("my-server");

// 发送简单请求
async function sayHello() {
  try {
    const response = await Nexa.seek("/hello", { name: "用户" });
    console.log("服务器说：", response.greeting);
  } catch (error) {
    console.error("问候失败：", error);
  }
}

// 完成后清理
function cleanup() {
  Nexa.close();
  console.log("连接已关闭");
}

表单提交示例

document
  .getElementById("userForm")
  .addEventListener("submit", async (event) => {
    event.preventDefault();

    const formData = {
      username: document.getElementById("username").value,
      email: document.getElementById("email").value,
      age: parseInt(document.getElementById("age").value),
    };

    try {
      // 如果尚未初始化则初始化
      if (!Nexa.isConnected()) {
        Nexa.init("user-service");
      }

      // 提交表单数据
      const response = await Nexa.seek("/users/create", formData);

      // 显示成功消息
      showMessage(`用户创建成功，ID：${response.userId}`);
    } catch (error) {
      // 显示错误消息
      showMessage(`错误：${error.message}`, "error");
    }
  });

webrtc p2p peer-to-peer api gateway peerjs express server client browser

4 months ago

4 months ago

4 months ago

4 months ago

Nexa.js - WebRTC P2P Communication Client

English Documentation

Table of Contents

Features

Installation

Browser

NPM (for bundlers)

Quick Start

Core Concepts

Connection Model

Request Flow

API Reference

Nexa.init(serverId, options)

Nexa.seek(path, body)

Nexa.getPeerId()

Nexa.isConnected()

Nexa.close()

Nexa.debug(enable)

Lifecycle Events

Advanced Usage

Custom Error Handling

Connection Management

Error Handling

Examples

Basic Example

Form Submission Example

中文文档

目录

特性

安装

浏览器

NPM（用于打包工具）

快速开始

核心概念

连接模型

请求流程

API 参考

Nexa.init(serverId, options)

Nexa.seek(path, body)

Nexa.getPeerId()

Nexa.isConnected()

Nexa.close()

Nexa.debug(enable)

生命周期事件

高级用法

自定义错误处理

连接管理

错误处理

示例

基本示例

表单提交示例

`Nexa.init(serverId, options)`

`Nexa.seek(path, body)`

`Nexa.getPeerId()`

`Nexa.isConnected()`

`Nexa.close()`

`Nexa.debug(enable)`

`Nexa.init(serverId, options)`

`Nexa.seek(path, body)`

`Nexa.getPeerId()`

`Nexa.isConnected()`

`Nexa.close()`

`Nexa.debug(enable)`