docs(examples): improve AI-agent consumability of coding/ examples by Copilot · Pull Request #701 · ClickHouse/clickhouse-js

Copilot · 2026-05-05T08:38:55Z

Created examples/web/performance/ and ported node/performance/select_streaming_json_each_row.ts as web/performance/select_streaming_json_each_row.ts using the Web ResultSet.stream() (ReadableStream<Row[]>) consumed via getReader() (no Node-only APIs)
Updated the header in web/coding/select_json_each_row.ts to point at the new web streaming example instead of the Node one
Updated examples/README.md: added web/performance/ to the directory tree, reworded the "no web performance folder" note, and added a Web column to the performance/ table with the new entry
npm run typecheck and npm run lint pass cleanly in examples/web

Agent-Logs-Url: https://github.com/ClickHouse/clickhouse-js/sessions/0ae7e4c8-4ad0-4fa2-8957-490fd70c0d40 Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com>

CLAassistant · 2026-05-05T08:39:04Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

codecov · 2026-05-05T08:41:31Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

peter-leonov-ch · 2026-05-05T10:00:48Z

@copilot resolve the merge conflicts in this pull request

Copilot · 2026-05-05T10:04:48Z

@copilot resolve the merge conflicts in this pull request

Merged origin/main in fe31ac9. The 4 conflicts (select_json_each_row.ts and select_json_with_metadata.ts in both node/ and web/ coding) were resolved by adopting main's JSDoc header style and folding in the extra technical hints from this branch (mention of rows.json<T>(), ResponseJSON<Row>, and the streaming counterpart). npm run typecheck and npm run lint pass in both examples/node and examples/web.

Copilot

Pull request overview

This PR improves the top-of-file documentation headers across the Node and Web coding examples so each script is easier to discover, understand, and adapt (including by AI-agent skill retrieval), without changing runtime behavior.

Changes:

Added/expanded concise “what this demonstrates / when to use it” headers across examples/node/coding and examples/web/coding.
Replaced the bare “taken from issue link” header in insert_from_select.ts (and its duplicate in examples/node/performance/) with a descriptive explanation of the INSERT … SELECT + AggregateFunction pattern.
Removed a misleading cross-platform note from the Web-only async_insert.ts header.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
examples/web/coding/session_id_and_temporary_tables.ts	Adds a clearer header explaining `session_id` usage and notes the Web-specific UUID source.
examples/web/coding/select_json_with_metadata.ts	Refines the JSDoc to explain the JSON envelope and when to use `ResponseJSON<Row>`.
examples/web/coding/select_json_each_row.ts	Updates JSDoc to mention `rows.json<T>()` and references streaming examples.
examples/web/coding/insert_into_different_db.ts	Adds a header explaining fully-qualified `database.table` usage with a non-default client DB.
examples/web/coding/insert_from_select.ts	Replaces the issue-only header with a description of the `INSERT ... SELECT` + aggregate-state pattern.
examples/web/coding/insert_decimals.ts	Adds guidance on string-based decimal IO and `toString` usage to avoid precision loss.
examples/web/coding/default_format_setting.ts	Adds a header explaining `default_format` usage with `client.exec` and `ResultSet`.
examples/web/coding/async_insert.ts	Removes a misleading statement about working with both Node and Web clients from a Web example.
examples/web/coding/array_json_each_row.ts	Adds a header describing JSONEachRow insert/select with arrays of objects.
examples/node/performance/insert_from_select.ts	Syncs the improved descriptive header for the aggregate-state `INSERT ... SELECT` example.
examples/node/coding/session_id_and_temporary_tables.ts	Adds a clearer header explaining `session_id` for temporary tables + load balancer caveats.
examples/node/coding/select_json_with_metadata.ts	Refines the JSDoc to explain the JSON envelope and when to use `ResponseJSON<Row>`.
examples/node/coding/select_json_each_row.ts	Updates JSDoc to mention `rows.json<T>()` and points to the node streaming example.
examples/node/coding/insert_into_different_db.ts	Adds a header explaining fully-qualified `database.table` usage with a non-default client DB.
examples/node/coding/insert_from_select.ts	Replaces the issue-only header with a description of the `INSERT ... SELECT` + aggregate-state pattern.
examples/node/coding/insert_decimals.ts	Adds guidance on string-based decimal IO and `toString` usage to avoid precision loss.
examples/node/coding/default_format_setting.ts	Adds a header explaining `default_format` usage with `client.exec` and `ResultSet`.
examples/node/coding/array_json_each_row.ts	Adds a header describing JSONEachRow insert/select with arrays of objects.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Agent-Logs-Url: https://github.com/ClickHouse/clickhouse-js/sessions/5e005788-6a73-482a-ace1-fe0cbf78b314 Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com>

peter-leonov-ch · 2026-05-05T16:21:27Z

@copilot apply PR review comments.

…t_json_each_row Agent-Logs-Url: https://github.com/ClickHouse/clickhouse-js/sessions/3539fc35-272d-4316-8e2c-817f1a3f2e56 Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com>

Copilot · 2026-05-05T16:24:08Z

@copilot apply PR review comments.

Addressed the reviewer's note on examples/web/coding/select_json_each_row.ts in 279d0f3 — the header now clarifies that the Web ResultSet does support .stream() (returning ReadableStream<Row[]>), and that only the dedicated Web example file is missing while node/performance/select_streaming_json_each_row.ts remains the streaming reference.

…mance Agent-Logs-Url: https://github.com/ClickHouse/clickhouse-js/sessions/855ff54d-26dd-4819-a9f0-19c2ab1712f0 Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com>

`AGENTS.md` had drifted from reality after PRs #662–#712: it claimed `examples/web` has no `performance/` folder, pointed at a placeholder docs path, and said nothing about the `skills/` directory or the `.claude/skills/setup/` skill that replaced `copilot-setup-steps.yml`. ## Summary - **Examples › `performance/`** — drop the "no `performance/` folder under `examples/web`" claim; #701 added one for browser-safe streaming. - **Log-message docs guidance** — point at the real `docs/` layout from #677 (`docs/socket_hang_up_econnreset.md`, `docs/howto/`) instead of a fictional `docs/example-log-message.md`. The example URL in the snippet now also resolves to a real page (`docs/socket_hang_up_econnreset.md`). - **New `Skills` section** — documents the repo-root `skills/` directory (#681, #682, #702): `client-node`'s `prepack` ships it via `@clickhouse/client`, the `agents.skills` field of `packages/client-node/package.json` declares which skills are discoverable, and the `Skills E2E` workflow (`.github/workflows/e2e-skills.yml`, backed by `tests/e2e/skills/check.js`) asserts the packaged tarball contains the declared skills. Routes contributors to `.claude/skills/setup/SKILL.md` (#705) instead of re-introducing `copilot-setup-steps.yml`. - **`agents.skills` manifest** — adds `clickhouse-js-node-coding` alongside `clickhouse-js-node-troubleshooting` so both shipped skills are discoverable to downstream tooling. `tests/e2e/skills/check.js` is extended to verify both skills land in the packaged `@clickhouse/client` tarball. - **New `Embedded docs` section** — surfaces `docs/` as the preferred home for pages linked from log messages. - **CHANGELOG guidance** — aligns with the PR template: entry goes in the PR description and is folded into `CHANGELOG.md` at release time. Documentation refresh plus a small manifest/test change to make the second shipped skill discoverable. ## Checklist - [x] A human-readable description of the changes was provided to include in CHANGELOG --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com> Co-authored-by: Peter Leonov <peter.leonov@clickhouse.com>

docs(examples): improve AI-agent consumability of coding/ examples

92a7d62

Agent-Logs-Url: https://github.com/ClickHouse/clickhouse-js/sessions/0ae7e4c8-4ad0-4fa2-8957-490fd70c0d40 Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com>

Copilot AI assigned Copilot and peter-leonov-ch May 5, 2026

Copilot AI requested review from Copilot and removed request for Copilot May 5, 2026 08:38

Copilot created this pull request from a session on behalf of peter-leonov-ch May 5, 2026 08:38 View session

Copilot started work on behalf of peter-leonov-ch May 5, 2026 10:00 View session

Merge origin/main into copilot/analyze-and-improve-code-examples

fe31ac9

Copilot AI requested review from Copilot and removed request for Copilot May 5, 2026 10:04

Copilot AI requested a review from peter-leonov-ch May 5, 2026 10:05

Copilot finished work on behalf of peter-leonov-ch May 5, 2026 10:05

Copilot started work on behalf of peter-leonov-ch May 5, 2026 10:10 View session

peter-leonov-ch marked this pull request as ready for review May 5, 2026 10:10

Copilot AI review requested due to automatic review settings May 5, 2026 10:10

peter-leonov-ch requested a review from mshustov as a code owner May 5, 2026 10:10

Copilot started reviewing on behalf of peter-leonov-ch May 5, 2026 10:10 View session

Copilot AI reviewed May 5, 2026

View reviewed changes

Comment thread examples/web/coding/select_json_each_row.ts Outdated

docs(examples): use // file headers and move them above imports

4a6b2ea

Agent-Logs-Url: https://github.com/ClickHouse/clickhouse-js/sessions/5e005788-6a73-482a-ace1-fe0cbf78b314 Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com>

Copilot finished work on behalf of peter-leonov-ch May 5, 2026 10:14

Copilot started work on behalf of peter-leonov-ch May 5, 2026 16:21 View session

docs(examples/web): clarify Web ResultSet supports .stream() in selec…

279d0f3

…t_json_each_row Agent-Logs-Url: https://github.com/ClickHouse/clickhouse-js/sessions/3539fc35-272d-4316-8e2c-817f1a3f2e56 Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com>

Copilot AI requested review from Copilot and removed request for Copilot May 5, 2026 16:24

Copilot finished work on behalf of peter-leonov-ch May 5, 2026 16:25

Copilot started work on behalf of peter-leonov-ch May 5, 2026 16:27 View session

docs(examples/web): port select_streaming_json_each_row to web/perfor…

e3b4b5f

…mance Agent-Logs-Url: https://github.com/ClickHouse/clickhouse-js/sessions/855ff54d-26dd-4819-a9f0-19c2ab1712f0 Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com>

Copilot AI requested review from Copilot and removed request for Copilot May 5, 2026 16:31

Copilot finished work on behalf of peter-leonov-ch May 5, 2026 16:32

peter-leonov-ch approved these changes May 5, 2026

View reviewed changes

peter-leonov-ch merged commit 010172d into main May 5, 2026
58 checks passed

peter-leonov-ch deleted the copilot/analyze-and-improve-code-examples branch May 5, 2026 17:10

Copilot AI mentioned this pull request May 9, 2026

docs(AGENTS.md): refresh based on last 4 weeks of PRs #714

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(examples): improve AI-agent consumability of coding/ examples#701

docs(examples): improve AI-agent consumability of coding/ examples#701
peter-leonov-ch merged 5 commits into
mainfrom
copilot/analyze-and-improve-code-examples

Copilot AI commented May 5, 2026 •

edited

Loading

Uh oh!

CLAassistant commented May 5, 2026

Uh oh!

codecov Bot commented May 5, 2026

Uh oh!

peter-leonov-ch commented May 5, 2026

Uh oh!

Copilot AI commented May 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

peter-leonov-ch commented May 5, 2026

Uh oh!

Copilot AI commented May 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

Copilot AI commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CLAassistant commented May 5, 2026

Uh oh!

codecov Bot commented May 5, 2026

Codecov Report

Uh oh!

peter-leonov-ch commented May 5, 2026

Uh oh!

Copilot AI commented May 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

peter-leonov-ch commented May 5, 2026

Uh oh!

Copilot AI commented May 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented May 5, 2026 •

edited

Loading