feat(qwp): add browser and Node.js QWP client

.github/workflows/build.yml

@@ -6,7 +6,11 @@ on:
       - main
   pull_request:
   schedule:
-    - cron: '15 2,10,18 * * *'
+    - cron: "15 2,10,18 * * *"
+  # GitHub disables a scheduled workflow after 60 days of repository
+  # inactivity, which stops it running on pull requests too. Dispatch is
+  # how to re-run it after that without pushing to a branch.
+  workflow_dispatch:
 
 jobs:
   test:
@@ -28,7 +32,7 @@ jobs:
 
       - uses: pnpm/action-setup@v4
         with:
-          version: 9
+          version: 10.12.4
           run_install: true
 
       - name: Linting
@@ -37,5 +41,121 @@ jobs:
       - name: Type-checking
         run: pnpm typecheck
 
+      # This contract uses DOM libraries with no @types/node and covers only
+      # the source graph shipped in @questdb/browser-client.
+      - name: Type-checking (browser)
+        run: pnpm typecheck:qwp-browser
+
+      # `pnpm typecheck` covers src plus a single contract file, so nothing
+      # type-checked test/** at all: a test could reference a deleted export
+      # and still pass, because vitest strips types without checking them.
+      - name: Type-checking (tests)
+        run: pnpm typecheck:test
+
+      - name: Type-checking (benchmarks)
+        run: pnpm typecheck:bench
+
+      - name: Linting (benchmarks)
+        run: pnpm lint:bench
+
       - name: Tests
         run: pnpm test
+
+      # Loads the built bundles through package.json `exports`, the way a
+      # consumer does, and verifies the two npm package boundaries.
+      - name: Built package tests
+        run: pnpm test:dist
+
+      # test:dist asserts runtime behaviour only. The compiled writers promise
+      # per-column row typing, which lives entirely in the emitted .d.ts files
+      # and is therefore invisible to source-level tests, where the public
+      # entries share one private-core module instance.
+      - name: Type-checking (built package consumer)
+        run: pnpm typecheck:dist
+
+      # The same gate publish.yml runs. Keeping it here too means a chunk that
+      # escapes `files`, or a regression in the check itself, fails a pull
+      # request instead of first being discovered during a release.
+      - name: Check for build artifacts
+        run: node scripts/check-build-artifacts.mjs
+
+  # Drives the built browser bundle in real Chromium against a local mock
+  # server. Tests that need a live QuestDB belong in the server repositories,
+  # where the topology and authentication fixtures already exist.
+  qwp-browser:
+    name: QWP browser bundle
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10.12.4
+          run_install: true
+
+      - name: Install Chromium
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Browser bundle tests
+        run: pnpm test:qwp-browser
+
+  enterprise-qwp-e2e:
+    name: Dispatch Enterprise QWP E2E
+    runs-on: ubuntu-latest
+    # Azure credentials are not exposed to fork PRs. The repository variable
+    # keeps this dormant until the Enterprise pipeline and PAT are configured.
+    if: >-
+      vars.ENTERPRISE_E2E_ENABLED == 'true' &&
+      (github.event_name != 'pull_request' ||
+       github.event.pull_request.head.repo.full_name == github.repository)
+    steps:
+      - name: Queue Enterprise TypeScript-client E2E
+        env:
+          ENT_DISPATCH_PAT: ${{ secrets.ENT_DISPATCH_PAT }}
+          CLIENT_COMMIT: ${{ github.event.pull_request.head.sha || github.sha }}
+          CLIENT_PR_NUMBER: ${{ github.event.pull_request.number || '' }}
+          CLIENT_BRANCH: ${{ github.head_ref || github.ref_name }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${ENT_DISPATCH_PAT:-}" ]; then
+            echo "ENT_DISPATCH_PAT is not configured" >&2
+            exit 1
+          fi
+
+          ORG_URL="https://dev.azure.com/questdb/"
+          PROJECT="questdb-enterprise"
+          PIPELINE_NAME="build-and-test-e2e-javascript-client"
+          PIPELINES=$(curl -fsS -u ":${ENT_DISPATCH_PAT}" \
+            "${ORG_URL}${PROJECT}/_apis/pipelines?api-version=7.0")
+          PIPELINE_ID=$(echo "$PIPELINES" | jq -r --arg name "$PIPELINE_NAME" \
+            '.value[] | select(.name == $name) | .id' | head -1)
+          if [ -z "$PIPELINE_ID" ] || [ "$PIPELINE_ID" = "null" ]; then
+            echo "Enterprise pipeline '$PIPELINE_NAME' is not registered" >&2
+            exit 1
+          fi
+
+          BODY=$(jq -n \
+            --arg commit "$CLIENT_COMMIT" \
+            --arg pr "$CLIENT_PR_NUMBER" \
+            --arg branch "$CLIENT_BRANCH" \
+            '{
+              templateParameters: {
+                javascriptClientCommit: $commit,
+                javascriptClientPrNumber: $pr,
+                clientBranch: $branch
+              }
+            }')
+          RESPONSE=$(curl -fsS -u ":${ENT_DISPATCH_PAT}" \
+            -H "Content-Type: application/json" \
+            -X POST \
+            -d "$BODY" \
+            "${ORG_URL}${PROJECT}/_apis/pipelines/${PIPELINE_ID}/runs?api-version=7.0")
+          echo "Enterprise E2E queued: $(echo "$RESPONSE" | jq -r '._links.web.href')"

.github/workflows/publish.yml

@@ -20,7 +20,7 @@ jobs:
 
       - uses: pnpm/action-setup@v4
         with:
-          version: 9
+          version: 10.12.4
           run_install: true
 
       - name: Linting
@@ -29,21 +29,43 @@ jobs:
       - name: Type-checking
         run: pnpm typecheck
 
+      # This contract uses DOM libraries with no @types/node and covers only
+      # the source graph shipped in @questdb/browser-client.
+      - name: Type-checking (browser)
+        run: pnpm typecheck:qwp-browser
+
       - name: Tests
         run: pnpm test
 
       - name: Build
         run: pnpm build
 
-      - name: Check for build artifacts
+      - name: Built package tests
+        run: pnpm exec vitest run --config vitest.dist.config.ts
+
+      # Guards the emitted .d.ts row typing, which no runtime suite can see.
+      - name: Type-checking (built package consumer)
         run: |
-          [ -f dist/cjs/index.js ] || (echo "CJS build missing" && exit 1)
-          [ -f dist/es/index.mjs ] || (echo "ESM build missing" && exit 1)
+          pnpm exec tsc --noEmit -p tsconfig.dist-types.json
+          pnpm exec tsc --noEmit -p tsconfig.dist-types.cjs.json
+
+      # Checks both npm tarballs and follows every exported declaration and
+      # runtime module through its relative dependency graph.
+      - name: Check for build artifacts
+        run: node scripts/check-build-artifacts.mjs
+
+      - name: Publish @questdb/nodejs-client
+        uses: JS-DevTools/npm-publish@v3
+        with:
+          token: ${{ secrets.CI_TOKEN }}
+          access: public
+          strategy: all
+          package: packages/nodejs-client/package.json
 
-      - name: Publish
+      - name: Publish @questdb/browser-client
         uses: JS-DevTools/npm-publish@v3
         with:
           token: ${{ secrets.CI_TOKEN }}
           access: public
           strategy: all
-          package: package.json
+          package: packages/browser-client/package.json

CLAUDE.md

@@ -4,51 +4,67 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is the QuestDB Node.js client library (@questdb/nodejs-client) that provides data ingestion capabilities to QuestDB databases. The client supports multiple transport protocols (HTTP/HTTPS, TCP/TCPS) and authentication methods.
+This repository builds the QuestDB JavaScript clients: `@questdb/nodejs-client`
+for Node.js and `@questdb/browser-client` for browsers. A private
+`@questdb/client-core` workspace package owns their shared implementation.
 
 ## Development Commands
 
 ### Build
+
 ```bash
-pnpm build          # Build the library using bunchee (produces both ESM and CJS outputs)
+pnpm build          # Build both public ESM/CJS packages from client-core
 ```
 
 ### Testing
+
 ```bash
 pnpm test           # Run all tests using Vitest
 ```
 
 ### Code Quality
+
 ```bash
 pnpm eslint         # Run ESLint on all source files
 pnpm typecheck      # Run TypeScript type checking without emitting files
 pnpm format         # Format code using Prettier
 ```
 
 ### Documentation
+
 ```bash
-pnpm docs           # Build JSDoc documentation
+pnpm run docs       # Build TypeDoc documentation
 pnpm preview:docs   # Preview generated documentation locally
 ```
 
 ## Architecture
 
 ### Core Components
 
-1. **Sender** (`src/sender.ts`): Main API class that orchestrates data ingestion. Handles auto-flushing, connection management, and provides the builder pattern API for constructing rows.
+Runtime-neutral QWP implementation lives under `packages/client-core/src`.
+Each public package owns its runtime-specific source, package metadata,
+documentation, and single root build.
+
+1. **Sender** (`packages/nodejs-client/src/sender.ts`): Main Node.js API class that orchestrates data ingestion. Handles auto-flushing, connection management, and provides the builder pattern API for constructing rows.
+
+2. **Transport Layer** (`packages/nodejs-client/src/transport/`):
 
-2. **Transport Layer** (`src/transport/`):
    - `http/undici.ts`: Default HTTP transport using Undici library for high performance
    - `http/stdlib.ts`: Alternative HTTP transport using Node.js built-in modules
    - `tcp.ts`: TCP/TCPS transport for persistent connections with JWK authentication
    - Protocol negotiation and retry logic for HTTP transports
 
-3. **Buffer System** (`src/buffer/`):
+3. **Buffer System** (`packages/nodejs-client/src/buffer/`):
+
    - `bufferv1.ts`: Text-based protocol (version 1) for backward compatibility
    - `bufferv2.ts`: Binary protocol (version 2) with double encoding and array support
    - Dynamic buffer resizing and row-level transaction support
 
-4. **Configuration** (`src/options.ts`): Comprehensive options parsing from connection strings with validation and deprecation handling.
+4. **Configuration** (`packages/nodejs-client/src/options.ts`): Comprehensive options parsing from connection strings with validation and deprecation handling.
+
+5. **QWP core** (`packages/client-core/src/qwp/` and `packages/client-core/src/_qwp/`): Shared browser-safe protocol/session code.
+
+6. **Runtime adapters**: `packages/nodejs-client/src/qwp.ts` owns Node WebSocket, UDP, TLS, and persistence support; `packages/browser-client/src/index.ts` owns the browser WebSocket and authentication adapter. The browser package must remain free of Node built-ins, Node typings, `undici`, and `ws`.
 
 ### Protocol Versions
 
@@ -66,6 +82,7 @@ pnpm preview:docs   # Preview generated documentation locally
 ## Testing Strategy
 
 Tests are organized by component:
+
 - `sender.config.test.ts`: Configuration parsing and validation
 - `sender.buffer.test.ts`: Buffer operations and protocol serialization
 - `sender.transport.test.ts`: Transport layer functionality
@@ -80,4 +97,5 @@ Integration tests use TestContainers to spin up QuestDB instances for realistic
 - Buffer automatically resizes up to `max_buf_size` (default 100MB)
 - Auto-flush triggers based on row count or time interval
 - Each worker thread needs its own Sender instance (buffers cannot be shared)
-- Protocol version 2 is recommended for new implementations with array column support
+- Protocol version 2 is recommended for new implementations with array column support
+- Run `pnpm test:dist` after package-boundary changes; it checks both npm tarballs, ESM/CJS loading, browser bundling, and the absence of Node modules from the browser artifact.

CONTRIBUTING.md

@@ -1,26 +1,29 @@
-# Contributing to nodejs-questdb-client
+# Contributing to the QuestDB JavaScript Client
 
-Thank you for your interest in contributing to nodejs-questdb-client! This document provides guidelines and instructions for contributing to the project.
+Thank you for your interest in contributing to the QuestDB JavaScript Client!
+This repository contains both the Node.js and browser npm packages.
 
 ## Development Setup
 
 1. Fork and clone the repository:
+
 ```bash
 git clone https://github.com/YOUR_USERNAME/nodejs-questdb-client.git
 cd nodejs-questdb-client
 ```
 
 2. Install dependencies:
+
 ```bash
 pnpm install
 ```
 
-
 ## Running Tests
 
 The project uses Vitest for testing. Tests are located in the `test` directory.
 
 1. Run tests in watch mode during development:
+
 ```bash
 pnpm run test
 ```
@@ -30,8 +33,7 @@ pnpm run test
 - Some tests use mock servers and certificates located in the `test/certs` directory
 
 > You can generate the certificates by running the `generateCerts.sh` script in the `scripts` directory. The script requires two arguments: the output directory and the password for the certificates.
-`./scripts/generateCerts.sh . questdbPwd123`
-
+> `./scripts/generateCerts.sh . questdbPwd123`
 
 ## Code Style and Quality
 
@@ -40,23 +42,27 @@ pnpm run test
 2. Format your code using Prettier
 
 3. Lint your code:
+
 ```bash
-pnpm run lint
+pnpm eslint
 ```
 
 4. Fix linting issues:
+
 ```bash
-pnpm run lint --fix
+pnpm eslint --fix
 ```
 
 ## Making Changes
 
 1. Create a new branch for your changes:
+
 ```bash
 git checkout -b feature/your-feature-name
 ```
 
 2. Make your changes and commit them with clear, descriptive commit messages:
+
 ```bash
 git add .
 git commit -m "feat: add new feature"
@@ -65,6 +71,7 @@ git commit -m "feat: add new feature"
 We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification for commit messages.
 
 3. Push your changes to your fork:
+
 ```bash
 git push origin feature/your-feature-name
 ```
@@ -88,10 +95,10 @@ git push origin feature/your-feature-name
 ## Need Help?
 
 If you have questions or need help, you can:
+
 - Open an issue with your question
 - Join our community discussions (if available)
 
 ## License
 
-By contributing to nodejs-questdb-client, you agree that your contributions will be licensed under the project's license.
-
+By contributing to the QuestDB JavaScript Client, you agree that your contributions will be licensed under the project's license.