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,14 +32,135 @@ jobs:
 
       - uses: pnpm/action-setup@v4
         with:
-          version: 9
+          version: 10.12.4
           run_install: true
 
       - name: Linting
         run: pnpm eslint
 
+      # `pnpm format` writes; nothing verified the result, so formatting drifted
+      # into files no other gate reads.
+      - name: Formatting
+        run: pnpm format:check
+
       - 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,55 @@ 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: Install Chromium
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Browser bundle tests
+        run: pnpm test:qwp-browser
+
+      - 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.
+      # Run the script rather than inlining its commands: hand-copying them
+      # here dropped the TypeScript 4.9 leg, and publish.yml is
+      # workflow_dispatch-only with no dependency on build.yml, so a dispatch
+      # from a branch that never opened a pull request reached npm publish with
+      # no legacy-consumer gate at all. The script re-runs `pnpm build`, which
+      # is idempotent.
+      - name: Type-checking (built package consumer)
+        run: pnpm typecheck:dist
+
+      # Checks both npm tarballs and follows every exported declaration and
+      # runtime module through its relative dependency graph.
       - name: Check for build artifacts
-        run: |
-          [ -f dist/cjs/index.js ] || (echo "CJS build missing" && exit 1)
-          [ -f dist/es/index.mjs ] || (echo "ESM build missing" && exit 1)
+        run: node scripts/check-build-artifacts.mjs
+
+      # Both packages are published from one commit, and npm-publish silently
+      # skips a version that already exists. Fail here instead of half-releasing.
+      - name: Check release versions
+        run: node scripts/check-release-versions.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

.gitleaks.toml

@@ -0,0 +1,29 @@
+# Gitleaks configuration for the QuestDB JavaScript clients.
+#
+# The default rule set is kept in full. This file only names the sample
+# credentials the repository has to spell out in the clear, so that
+# `generic-api-key`, which cannot tell a sample apart from a credential, stops
+# reporting them.
+#
+# Every value below is a placeholder or a published documentation sample. None
+# authenticates anything: the tests hand them to mock servers that run inside
+# the test process, and the examples point at a local QuestDB.
+
+title = "QuestDB JavaScript clients"
+
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Sample credentials used by the tests, examples, and README"
+regexes = [
+  # P-256 private scalars for ILP TCP authentication. Signing needs a real
+  # scalar, so these cannot be shortened to an obvious placeholder.
+  '''9b9x5WhJywDEuo1KGQWSPNxtX-6X6R2BRCKhYMMY6n8''', # kid "testapp", tests and examples.manifest.yaml
+  '''zhPiK3BkYMYJvRf5sqyrWNJwjDKHOWHnRbmQggUll6A''', # kid "user1", second key in the TCP auth tests
+  '''ZRxmCOQBpZoj2fZ-lEtqzVDkCre_ouF3ePpaQNDwoQk''', # kid "admin", the documented example key
+  # HTTP bearer tokens, which are opaque strings the client never interprets.
+  '''Xyvd3er6GF87ysaHk''', # README token example
+  '''abcdefghijkl123''',   # mock HTTP server in the transport tests
+  '''jwkprivkey123''',     # connect-string parsing fixture in the options tests
+]

CLAUDE.md

@@ -4,57 +4,76 @@ 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
+   - `bufferv3.ts`: Extends v2 with DECIMAL columns (`decimalColumn`, `decimalColumnText`)
+   - All three are public exports (`SenderBufferV1`/`V2`/`V3`), selected by `createBuffer`
    - 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
 
 - **Version 1**: Text-based serialization, compatible with older QuestDB versions
 - **Version 2**: Binary encoding for doubles, supports array columns, better performance
-- **Auto-negotiation**: HTTP transport can automatically detect and use the best protocol version
+- **Version 3**: Adds DECIMAL columns on top of version 2
+- **Auto-negotiation**: HTTP transport can automatically detect and use the best protocol version, preferring v3 over v2
 
 ### Key Design Patterns
 
@@ -66,6 +85,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 +100,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 or higher is recommended for new implementations; v2 adds array columns and v3 adds DECIMAL
+- 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.