From ffe7cd964d68bcae32b12bb09422de1096ca4bfc Mon Sep 17 00:00:00 2001 From: Tommy Smith Date: Wed, 18 Feb 2026 13:57:52 +0000 Subject: [PATCH 1/2] Add `CLAUDE.md` file to repo --- CLAUDE.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..365ba831 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,90 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Official Weaviate TypeScript/JavaScript client library. Provides a typed SDK for interacting with Weaviate vector database instances via both REST/GraphQL (HTTP/1.1) and gRPC (HTTP/2) protocols. + +## Common Commands + +```bash +npm run build # Lint + build CJS and ESM to dist/node/ +npm run lint # ESLint +npm run lint:fix # ESLint with auto-fix +npm run format # Prettier format all source files +npm run format:check # Prettier check (CI uses this) +npm test # Run all tests (unit + integration + journey) via Vitest + +# Run a single test file +npx vitest run path/to/file.test.ts + +# Run only unit tests (no Weaviate instance needed) +npx vitest run --project unit + +# Run only integration tests (requires running Weaviate) +npx vitest run --project integration + +# Run only journey tests (requires running Weaviate) +npx vitest run --project journey +``` + +Integration and journey tests require a running Weaviate instance (default: `localhost:8080` for REST, `localhost:50051` for gRPC). CI uses `ci/run_dependencies.sh ` to start Weaviate via Docker Compose. The `WEAVIATE_VERSION` env var gates version-specific tests via `test/version.ts` helpers (`requireAtLeast`). + +## Architecture + +### Dual API Surface (v2 and v3) + +- **v3 API** (`src/index.ts`): Current collection-oriented API. Entry points are `connectToLocal()`, `connectToWeaviateCloud()`, `connectToCustom()`. Returns a `WeaviateClient` with namespaces: `collections`, `backup`, `cluster`, `roles`, `users`, `groups`, `alias`. +- **v2 API** (`src/v2/index.ts`): Legacy builder-pattern API exported as `weaviateV2`. Uses `schema`, `data`, `graphql`, `batch`, `classifications`, `c11y` namespaces. Still maintained but deprecated for new use. + +### Connection Layer (`src/connection/`) + +Three-tier inheritance: `ConnectionREST` (`http.ts`) → `ConnectionGQL` (`gql.ts`) → `ConnectionGRPC` (`grpc.ts`). The top-level client always creates a `ConnectionGRPC` which inherits REST and GraphQL capabilities. Connection setup handles auth (API key, OIDC, client credentials), proxies, and timeouts. + +### Collections Layer (`src/collections/`) + +The v3 API's core. `collections/index.ts` manages CRUD for collections. `collections/collection/index.ts` creates per-collection objects with sub-namespaces: +- **query/**: Search operations (BM25, hybrid, nearVector, nearText, nearImage, etc.) +- **generate/**: RAG/generative search operations +- **aggregate/**: Aggregation queries +- **data/**: CRUD operations on objects within a collection +- **config/**: Collection configuration management +- **configure/**: Builder helpers for creating collection configs (vectorizers, generative, reranker, vector index) +- **tenants/**: Multi-tenancy management +- **filters/**, **sort/**, **references/**, **iterator/**, **vectors/**: Supporting utilities + +### Serialization/Deserialization (`src/collections/serialize/`, `src/collections/deserialize/`) + +Translate between the client's TypeScript types and Weaviate's gRPC protobuf messages. `Serialize` converts query parameters into protobuf request objects. `Deserialize` converts gRPC responses back into typed client objects. + +### gRPC Layer (`src/grpc/`) + +Thin wrappers around generated protobuf clients for search, batch, tenants, and aggregation operations. Uses `nice-grpc` with retry middleware. + +### Generated Code + +- `src/proto/`: Auto-generated protobuf TypeScript types (refreshed via `npm run refresh-protos`). Do not edit manually. +- `src/openapi/`: Auto-generated OpenAPI types (refreshed via `npm run refresh-schema`). Do not edit manually. + +### Legacy Modules (`src/batch/`, `src/data/`, `src/graphql/`, `src/schema/`) + +Used by both v2 API directly and v3 API internally (e.g., `ClassCreator`, `ClassDeleter`, `SchemaGetter` are used by `collections/index.ts`). + +## Test Structure + +Tests use Vitest with three project configurations defined in `vitest.config.ts`: +- **unit** (`src/**/unit.test.ts`): Pure logic tests, no Weaviate instance needed. +- **integration** (`test/**/integration.test.ts`, `test/**/mock.test.ts`): Require a running Weaviate instance. +- **journey** (`test/**/journey.test.ts`): End-to-end tests requiring a running Weaviate instance. + +Test timeout is 100 seconds. Tests run sequentially (`--no-file-parallelism`). + +## Key Conventions + +- All internal imports use explicit `.js` extensions (ESM convention, resolved via Vitest alias). +- The build produces both CJS (`dist/node/cjs/`) and ESM (`dist/node/esm/`) outputs. +- TypeScript strict mode is enabled. +- Naming convention enforced by ESLint: `camelCase`, `UPPER_CASE`, or `PascalCase` for identifiers; properties are unrestricted. +- Collection names are auto-capitalized (first letter) before being sent to Weaviate. +- Heavy use of generics throughout the collections API for type-safe property access (`TProperties`, `TVectors`, `TName`). From a283bab9036c3a104b4bf552b701ff0dbe747419 Mon Sep 17 00:00:00 2001 From: Tommy Smith Date: Wed, 18 Feb 2026 14:02:53 +0000 Subject: [PATCH 2/2] Add contribution guidelines section --- CLAUDE.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 365ba831..3ad6dd53 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,6 +6,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co Official Weaviate TypeScript/JavaScript client library. Provides a typed SDK for interacting with Weaviate vector database instances via both REST/GraphQL (HTTP/1.1) and gRPC (HTTP/2) protocols. +## Contribution Guidelines + +- Develop all features in a user-centric way, prioritizing ease of use and intuitive API design. This includes: + - not only thoughtful method naming, parameter structures, and return types, + - but also ensuring that core implementations do not collide with user requirements. + - E.g., any tradeoffs should be shouldered by the internal implementation rather than exposing complexity to the user. +- Follow existing code style and architecture patterns. +- Write unit tests for new logic and integration/journey tests for new features. +- Use descriptive commit messages and PR titles. +- Ensure all tests pass before merging. + ## Common Commands ```bash