@huaqiu/huaqiu-client

Ergonomic TypeScript runtime discovery and client library for HQ EDA.

Installation

npm install @huaqiu/huaqiu-client

Quick Start

import { connect } from "@huaqiu/huaqiu-client";

async function main() {
  const client = await connect();

  const projects = await client.project.listProjects({});
  console.log("Projects:", projects.projects);
}

main().catch(console.error);

Features

• Automatic Runtime Discovery: Automatically discovers running HQ EDA instances from the local registry
• Multi-Service Client: Provides clients for all HQ EDA services
• Type-Safe APIs: Full TypeScript support with generated protobuf types
• Dual Module Support: Works with both CommonJS and ES Modules
• Connection Management: Built-in session management and transport handling

API

connect(options?: ConnectOptions): Promise<EditorClient>

Connect to an HQ EDA runtime instance.

Options:

| Option | Type | Description | |--------|------|-------------| | instanceId | string | Target a specific editor instance by ID | | grpcEndpoint | string | Direct gRPC endpoint (bypasses discovery) | | sessionId | string | Custom session ID (defaults to UUID) | | timeoutMs | number | Connection timeout in milliseconds |

listEditors(): Promise<EditorInfo[]>

List all active HQ EDA editor instances.

getRuntimeDir(): string

Get the runtime registry directory path for the current platform.

EditorClient

The main client class providing access to all services:

Discovery Service

• client.discovery — Runtime discovery operations

Core Services

• client.ai — AI service
• client.capability — Capability management
• client.context — Context service

Workspace & Project

• client.workspace — Workspace management
• client.project — Project operations

Canvas & Graph

• client.kernel — Kernel operations
• client.graph — Graph manipulation
• client.selection — Selection management
• client.canvasOps — Canvas operations
• client.componentPlace — Component placement
• client.objPlace — Object placement

ERC

• client.erc — ERC (Electrical Rule Check) service

Runtime

• client.runtime — Runtime management
• client.transaction — Transaction handling
• client.event — Event subscription

Import/Export

• client.import — Import service
• client.export — Export service

Context Helpers

• client.createEditorContext() — Create editor context
• client.createProjectContext(projectId, options) — Create project context

Examples

Connect to a specific instance

import { connect } from "@huaqiu/huaqiu-client";

const client = await connect({
  instanceId: "my-editor-instance",
});

Connect with a direct endpoint

import { connect } from "@huaqiu/huaqiu-client";

const client = await connect({
  grpcEndpoint: "localhost:8080",
});

List all running editors

import { listEditors } from "@huaqiu/huaqiu-client";

const editors = await listEditors();
console.log("Active editors:", editors);

Create project context

import { connect } from "@huaqiu/huaqiu-client";

const client = await connect();
const projectContext = client.createProjectContext("project-123", {
  workspaceId: "workspace-456",
});

Get runtime directory

import { getRuntimeDir } from "@huaqiu/huaqiu-client";

const dir = getRuntimeDir();
console.log("Runtime directory:", dir);

Runtime Discovery

The client automatically discovers HQ EDA instances by scanning the runtime registry directory:

• Windows: %LOCALAPPDATA%\HQ\runtime
• macOS: ~/Library/Application Support/HQ/runtime
• Linux: ~/.hq/runtime

Each running instance registers itself via a JSON file in this directory. The client checks if the process is still alive before returning it as available.

Types

EditorInfo

interface EditorInfo {
  schemaVersion: number;
  instanceId: string;
  pid: number;
  grpcEndpoint: string;
  version: string;
  capabilities: string[];
  startedAt?: string;
}

ConnectOptions

interface ConnectOptions {
  instanceId?: string;
  grpcEndpoint?: string;
  sessionId?: string;
  timeoutMs?: number;
}

ProjectContextOptions

interface ProjectContextOptions {
  workspaceId?: string;
  transactionId?: string;
  operationId?: string;
}

Requirements

• Node.js >= 18.0.0
• HQ EDA runtime instance running (for automatic discovery)

License

Apache-2.0