ClickHouse · peter-leonov-ch · Jun 12, 2026 · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026
@@ -0,0 +1,64 @@
+---
+name: typescript-lsp
+description: >
+  Use the TypeScript language server (`typescript-language-server`) for precise
+  code intelligence in the `clickhouse-js` repository: go-to-definition, find
+  references, hover (type signatures and JSDoc, including `@deprecated` info),
+  workspace-wide symbol search, completions, and per-file type diagnostics.
+  Prefer this over grep when you need to resolve a symbol's actual definition,
+  find all usages of an exported API, or inspect inferred types across the
+  `packages/*` workspaces. The server is preinstalled as a root devDependency —
+  run the repository `setup` skill (`npm install`) first so `node_modules` is
+  populated. Do NOT use this skill for downstream projects that merely depend
+  on `@clickhouse/client`; it is specific to working inside this repo.
+---
+
+# TypeScript Language Server in clickhouse-js
+
+`typescript-language-server` is declared as a root devDependency, so after
+`npm install` (see the `setup` skill) it is available via `npx` and uses the
+workspace-local `typescript` (6.x) compiler, matching CI exactly.
+
+## Starting the server
+
+From the repo root:
+
+```bash
+npx typescript-language-server --stdio
+```
+
+It speaks LSP (JSON-RPC, `Content-Length`-framed) over stdio. There is no
+extra configuration: each `packages/*` workspace, `tests/clickhouse-test-runner`,
+`examples/node`, and `examples/web` has its own `tsconfig.json`, and the
+server picks the nearest one per opened file automatically.
+
+## Protocol essentials
+
+1. Send `initialize` with `rootUri`/`workspaceFolders` pointing at the repo
+   root, then the `initialized` notification.
+2. Send `textDocument/didOpen` with the full file text for every file you
+   want to query (the server reads dependencies from disk on its own; only
+   files you query positions in need to be opened).
+3. Positions are **0-based** (line and character).
+
+## Verified capabilities (typescript-language-server 5.x, TS 6.x)
+
+| Request                   | Notes                                                                                                                                                                                                           |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `textDocument/hover`      | Returns the full inferred signature + JSDoc markdown                                                                                                                                                            |
+| `textDocument/definition` | Resolves across workspace packages via source, not `dist/`                                                                                                                                                      |
+| `textDocument/references` | Within the opened file's project                                                                                                                                                                                |
+| `workspace/symbol`        | e.g. query `ClickHouseClient` finds class + re-exports                                                                                                                                                          |
+| `textDocument/completion` | Context-aware member completions                                                                                                                                                                                |
+| Diagnostics               | **Push only** (`textDocument/publishDiagnostics` notifications, sent ~1–3s after `didOpen`). The pull `textDocument/diagnostic` request is _not_ supported (`-32601`) — wait for the push notification instead. |
+
+## Tips
+
+- If your environment provides built-in LSP/code-intelligence tooling, point
+  it at `npx typescript-language-server --stdio` with the repo root as the
+  workspace folder.
+- For one-off scripted queries, spawn the server from Node, frame messages
+  with `Content-Length: <bytes>\r\n\r\n<json>`, and match responses by `id`.
+- A full workspace typecheck is still `npm run build && npm run typecheck`
+  (build first — some workspaces import compiled `dist/` outputs); the LSP is
+  for targeted, interactive queries, not for CI-equivalent validation.
@@ -90,6 +90,17 @@
     <flush_interval_milliseconds>1000</flush_interval_milliseconds>
   </query_log>
 
+  <opentelemetry_span_log>
+    <database>system</database>
+    <table>opentelemetry_span_log</table>
+    <engine>
+      ENGINE = MergeTree
+      PARTITION BY finish_date
+      ORDER BY (finish_date, finish_time_us)
+    </engine>
+    <flush_interval_milliseconds>1000</flush_interval_milliseconds>
+  </opentelemetry_span_log>
+
   <http_options_response>
     <header>
       <name>Access-Control-Allow-Origin</name>

@@ -90,6 +90,17 @@
     <flush_interval_milliseconds>1000</flush_interval_milliseconds>
   </query_log>
 
+  <opentelemetry_span_log>
+    <database>system</database>
+    <table>opentelemetry_span_log</table>
+    <engine>
+      ENGINE = MergeTree
+      PARTITION BY finish_date
+      ORDER BY (finish_date, finish_time_us)
+    </engine>
+    <flush_interval_milliseconds>1000</flush_interval_milliseconds>
+  </opentelemetry_span_log>
+
   <http_options_response>
     <header>
       <name>Access-Control-Allow-Origin</name>

@@ -32,6 +32,17 @@
     <flush_interval_milliseconds>1000</flush_interval_milliseconds>
   </query_log>
 
+  <opentelemetry_span_log>
+    <database>system</database>
+    <table>opentelemetry_span_log</table>
+    <engine>
+      ENGINE = MergeTree
+      PARTITION BY finish_date
+      ORDER BY (finish_date, finish_time_us)
+    </engine>
+    <flush_interval_milliseconds>1000</flush_interval_milliseconds>
+  </opentelemetry_span_log>
+
   <http_options_response>
     <header>
       <name>Access-Control-Allow-Origin</name>

@@ -1,9 +1,9 @@
 ---
 name: Bug report
 about: Create a report to help us improve
-title: ''
+title: ""
 labels: bug
-assignees: ''
+assignees: ""
 ---
 
 <!-- delete unnecessary items -->

@@ -1,9 +1,9 @@
 ---
 name: Feature request
 about: Suggest an idea for the client
-title: ''
+title: ""
 labels: enhancement
-assignees: ''
+assignees: ""
 ---
 
 <!-- delete unnecessary items -->

@@ -1,9 +1,9 @@
 ---
 name: Question
 about: Ask a question about the client
-title: ''
+title: ""
 labels: question
-assignees: ''
+assignees: ""
 ---
 
 > Make sure to check the [documentation](https://clickhouse.com/docs/en/integrations/language-clients/javascript) first.

@@ -1,26 +1,26 @@
 # https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
 version: 2
 updates:
-  - package-ecosystem: 'github-actions'
-    directory: '.github/workflows'
+  - package-ecosystem: "github-actions"
+    directory: ".github/workflows"
     schedule:
-      interval: 'weekly'
-      day: 'monday'
+      interval: "weekly"
+      day: "monday"
     groups:
       workflows:
-        dependency-type: 'development'
-  - package-ecosystem: 'npm'
-    directory: '/'
+        dependency-type: "development"
+  - package-ecosystem: "npm"
+    directory: "/"
     schedule:
-      interval: 'weekly'
-      day: 'monday'
+      interval: "weekly"
+      day: "monday"
     groups:
       dev-dependencies:
-        dependency-type: 'development'
+        dependency-type: "development"
     ignore:
-      - dependency-name: '@opentelemetry/auto-instrumentations-node'
-        versions: ['0.70.0']
-      - dependency-name: '@types/node'
-        versions: ['25.3.0']
-      - dependency-name: 'typescript-eslint'
-        versions: ['8.56.0']
+      - dependency-name: "@opentelemetry/auto-instrumentations-node"
+        versions: ["0.70.0"]
+      - dependency-name: "@types/node"
+        versions: ["25.3.0"]
+      - dependency-name: "typescript-eslint"
+        versions: ["8.56.0"]
@@ -17,6 +17,10 @@ In other cases when you've found a meaningful change to make, make it and push c
 
 When reviewing PRs to the `release` branch focus on flagging breaking changes and security issues in the broader context, as PRs to the `release` branch are normally bigger and include a cumulative change from a number of PRs.
 
+## CHANGELOG
+
+Every PR that adds a feature, fixes a bug, or changes observable behavior or the public API **must update `CHANGELOG.md` in the same PR**. If such a change does not touch `CHANGELOG.md`, flag it and ask the author to add an entry (a note in the PR description alone is not sufficient). Verify the entry follows the conventions in [`AGENTS.md`](../../AGENTS.md) ("API quality and stability"): placed under the top-most version heading (a new `# x.y.z` heading matching the unreleased `package.json` version when the latest heading is already released), grouped under a lowercase section heading (`## New features` / `## Improvements` / `## Bug fixes`), and ending with a `([#<n>])` PR reference link. Pure refactors, test-only changes, docs, and CI/tooling changes do not require a CHANGELOG entry.
+
 ## Breaking changes
 
 Always flag major breaking changes to the public API (removed/renamed exports, changed function signatures, changed default behavior, removed configuration options, etc.) when they are not accompanied by a clear explanation in the PR description or PR discussion/code comments justifying why the break is necessary. This is important because LLMs generating code against newer client versions rely heavily on training data from older versions; undocumented breaking changes degrade their effectiveness and produce broken code for users. When such a change lacks justification, request that the author either add a clear rationale (and, where possible, a migration note) or restore backwards compatibility (e.g., via a deprecation path).
@@ -1,10 +1,10 @@
-name: 'bump-version'
+name: "bump-version"
 
 on:
   workflow_dispatch:
     inputs:
       bump_type:
-        description: 'Version bump type'
+        description: "Version bump type"
         required: true
         type: choice
         options:
@@ -25,7 +25,7 @@ jobs:
       pull-requests: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: main
 

@@ -1,14 +1,14 @@
-name: 'misc'
+name: "misc"
 
 permissions: {}
 on:
   workflow_dispatch:
   push:
   schedule:
-    - cron: '0 10 * * *'
+    - cron: "0 10 * * *"
 
 concurrency:
-  group: '${{ github.workflow }}-${{ github.ref }}'
+  group: "${{ github.workflow }}-${{ github.ref }}"
   cancel-in-progress: true
 
 jobs:
@@ -19,7 +19,7 @@ jobs:
     if: always()
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Setup NodeJS
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0

@@ -1,4 +1,4 @@
-name: 'Copilot Setup Steps'
+name: "Copilot Setup Steps"
 permissions: {}
 
 # Automatically run the setup steps when they are changed to allow for easy validation,

@@ -1,4 +1,4 @@
-name: 'Skills E2E'
+name: "Skills E2E"
 
 permissions: {}
 on:
@@ -16,7 +16,7 @@ jobs:
   skills-packaging:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Setup Node.js
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0

@@ -1,4 +1,4 @@
-name: 'examples'
+name: "examples"
 
 permissions: {}
 on:
@@ -8,26 +8,26 @@ on:
       - main
       - release
     paths-ignore:
-      - '**/*.md'
-      - 'LICENSE'
-      - 'benchmarks/**'
+      - "**/*.md"
+      - "LICENSE"
+      - "benchmarks/**"
   pull_request:
     paths-ignore:
-      - '**/*.md'
-      - 'LICENSE'
-      - 'benchmarks/**'
+      - "**/*.md"
+      - "LICENSE"
+      - "benchmarks/**"
 
 concurrency:
-  group: '${{ github.workflow }}-${{ github.ref }}'
+  group: "${{ github.workflow }}-${{ github.ref }}"
   cancel-in-progress: true
 
 env:
   OTEL_SERVICE_NAME: vitest
   OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.OTEL_EXPORTER_OTLP_ENDPOINT }}
-  OTEL_EXPORTER_OTLP_HEADERS: 'authorization=${{ secrets.OTEL_EXPORTER_OTLP_API_KEY }}'
-  OTEL_RESOURCE_ATTRIBUTES: 'service.namespace=clickhouse-js,deployment.environment=ci'
-  VITEST_OTEL_ENABLED: 'true'
-  VITEST_COVERAGE: 'true'
+  OTEL_EXPORTER_OTLP_HEADERS: "authorization=${{ secrets.OTEL_EXPORTER_OTLP_API_KEY }}"
+  OTEL_RESOURCE_ATTRIBUTES: "service.namespace=clickhouse-js,deployment.environment=ci"
+  VITEST_OTEL_ENABLED: "true"
+  VITEST_COVERAGE: "true"
 
 jobs:
   code-quality:
@@ -41,7 +41,7 @@ jobs:
       run:
         working-directory: examples/${{ matrix.package }}
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Setup NodeJS
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
@@ -72,15 +72,15 @@ jobs:
       run:
         working-directory: examples/${{ matrix.package }}
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Start ClickHouse (version - ${{ matrix.clickhouse }}) in Docker
         uses: isbang/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.2
         env:
           CLICKHOUSE_VERSION: ${{ matrix.clickhouse }}
         with:
-          compose-file: 'docker-compose.yml'
-          down-flags: '--volumes'
+          compose-file: "docker-compose.yml"
+          down-flags: "--volumes"
 
       - name: Setup NodeJS
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
@@ -113,7 +113,7 @@ jobs:
           npm run run-examples
 
   success:
-    needs: ['code-quality', 'run-examples']
+    needs: ["code-quality", "run-examples"]
     runs-on: ubuntu-latest
     steps:
       - name: All examples checks passed

@@ -23,8 +23,8 @@ jobs:
         env:
           OTEL_SERVICE_NAME: github-actions
           OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.OTEL_EXPORTER_OTLP_ENDPOINT }}
-          OTEL_EXPORTER_OTLP_HEADERS: 'authorization=${{ secrets.OTEL_EXPORTER_OTLP_API_KEY }}'
-          OTEL_RESOURCE_ATTRIBUTES: 'service.namespace=clickhouse-js'
+          OTEL_EXPORTER_OTLP_HEADERS: "authorization=${{ secrets.OTEL_EXPORTER_OTLP_API_KEY }}"
+          OTEL_RESOURCE_ATTRIBUTES: "service.namespace=clickhouse-js"
         with:
           # Required for collecting workflow data
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}