Skip to content

CLAUDE.md

Latest commit

 

History

History
104 lines (76 loc) · 3.75 KB

CLAUDE.md

File metadata and controls

104 lines (76 loc) · 3.75 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Node.js SDK for Milvus vector database, published as @zilliz/milvus2-sdk-node. Requires Node.js v18+.

Commands

# Install dependencies
yarn install

# Build (cleans dist/, compiles TS, generates sdk.json)
yarn build

# Run all tests (requires running Milvus instance)
yarn test

# Run a single test file (NODE_ENV=dev is required)
NODE_ENV=dev npx jest test/grpc/SomeTest.spec.ts

# Test coverage
yarn coverage

# Format code
npx prettier --write <file-or-directory>

# Regenerate proto JSON (after proto/ submodule update)
yarn proto:json

# Initialize proto submodule
git submodule update --init --recursive

Architecture

Source code lives in milvus/ (not src/). Build output goes to dist/.

Two Transport Layers

  1. gRPC (MilvusClient) — primary transport with connection pooling, automatic retries, and interceptors
  2. HTTP (HttpClient) — REST alternative for environments where gRPC isn't available

Class Inheritance Chain (gRPC)

BaseClient (proto loading, TLS, auth)
  → User (user/role management)
    → Database (database operations)
      → Collection (collection CRUD)
        → Data (insert/upsert/delete/query/search)
          → Partition (partition management)
            → MilvusIndex (index operations)
              → Resource (resource queries)
                → GRPCClient (channel pool, service init)
                  → MilvusClient (high-level API)

Each class in milvus/grpc/ adds one domain of Milvus operations. MilvusClient in milvus/MilvusClient.ts is the public entry point that extends GRPCClient with simplified high-level methods (aligned with the Python SDK).

Directory Layout

  • milvus/grpc/ — gRPC client classes (one per domain: Collection, Data, User, etc.)
  • milvus/http/ — HTTP client implementation
  • milvus/types/ — TypeScript type definitions for requests/responses
  • milvus/const/ — Constants, defaults, error codes
  • milvus/utils/ — Utilities (schema building, data formatting, gRPC helpers, validation)
  • milvus/proto-json/ — Generated proto definitions (from yarn proto:json)
  • proto/ — Git submodule with upstream Milvus .proto files
  • test/grpc/, test/http/, test/utils/ — Tests organized by transport/domain
  • test/tools/ — Test helpers (collection param generators, data generators)

Key Patterns

Adding a new gRPC API method:

  1. If proto has been updated: sync submodule (git submodule update --init --recursive) then regenerate JSON (yarn proto:json)
  2. Define request/response types in milvus/types/
  3. Implement method in the appropriate milvus/grpc/ class
  4. Wrap gRPC calls with promisify(this.grpcClient.methodName.bind(this.grpcClient), metadata, timeout)
  5. Check results against ErrorCode.SUCCESS
  6. Add tests in test/grpc/
  7. Add JSDoc for public methods (include @param and @returns)

Error handling:

if (res.error_code !== ErrorCode.SUCCESS) {
  throw new Error(res.reason);
}

gRPC interceptors (in milvus/utils/Grpc.ts): meta (auth/db_name), retry (exponential backoff), trace (OpenTelemetry), request metadata (timing).

Connection pooling: Uses generic-pool with configurable min/max (defaults: 5/10).

Code Style

  • TypeScript strict mode, target ES2015, CommonJS modules
  • Prettier: 2 spaces, single quotes, semicolons, ES5 trailing commas, avoid arrow parens
  • Classes: PascalCase; methods/variables: camelCase; constants: UPPER_CASE
  • Test files: *.spec.ts
  • Tests use describe/it blocks with beforeAll/afterAll for setup/cleanup
  • Tests are integration tests that connect to a real Milvus instance