{"_id":"kysely-sqlcommenter","_rev":"5-0d94e726c5c17a98923e28af60816d46","name":"kysely-sqlcommenter","dist-tags":{"latest":"0.2.0"},"versions":{"0.0.1":{"name":"kysely-sqlcommenter","version":"0.0.1","author":{"name":"Jaroslav Šmolík","email":"smolijar@gmail.com"},"license":"MIT","_id":"kysely-sqlcommenter@0.0.1","maintainers":[{"name":"grissius","email":"grissius@gmail.com"}],"homepage":"https://github.com/smolijar/kysely-sqlcommenter#readme","bugs":{"url":"https://github.com/smolijar/kysely-sqlcommenter/issues"},"dist":{"shasum":"5cb3dec044d59ac2a16daf67d21dc3ada4c10b84","tarball":"https://registry.npmjs.org/kysely-sqlcommenter/-/kysely-sqlcommenter-0.0.1.tgz","fileCount":6,"integrity":"sha512-gtrSc7yBreO6cdqtVFwOpoYzRgi46NFXHsXV1G95SfKVlZs3PENdqV1/ahCXyuDyOj78TpXESVezABV8p3gWVg==","signatures":[{"sig":"MEYCIQCpZdU0VN5cpr47+LyJ5HLxUQdo4U9EFXi25wo95IipeAIhANZNcXqRiSm8wux8ceovaqQZHMvGsVYBAmemrPsF25GH","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":150679},"main":"./dist/kysely-sqlcommenter.umd.cjs","type":"module","types":"./dist/kysely-sqlcommenter.d.ts","module":"./dist/kysely-sqlcommenter.js","exports":{".":{"import":"./dist/kysely-sqlcommenter.js","require":"./dist/kysely-sqlcommenter.umd.cjs"}},"gitHead":"0336a7641d09dd5384cb5591e04083aa41bfc538","scripts":{"dev":"vite","test":"vitest","build":"tsc && vite build","test:integration":"./integration-test-builder/test.sh"},"_npmUser":{"name":"grissius","email":"grissius@gmail.com"},"repository":{"url":"git+https://github.com/smolijar/kysely-sqlcommenter.git","type":"git"},"_npmVersion":"10.2.3","description":"<div align=\"center\">","directories":{},"_nodeVersion":"18.19.0","_hasShrinkwrap":false,"devDependencies":{"vite":"^5.0.8","kysely":"^0.27.2","vitest":"^1.2.2","typescript":"^5.2.2","@types/node":"^20.11.7","vite-plugin-dts":"^3.7.2"},"_npmOperationalInternal":{"tmp":"tmp/kysely-sqlcommenter_0.0.1_1707569788936_0.823003155754013","host":"s3://npm-registry-packages"}},"0.1.0":{"name":"kysely-sqlcommenter","version":"0.1.0","keywords":["kysely","sqlcommenter","sql"],"author":{"name":"Jaroslav Šmolík","email":"smolijar@gmail.com"},"license":"MIT","_id":"kysely-sqlcommenter@0.1.0","maintainers":[{"name":"grissius","email":"grissius@gmail.com"}],"homepage":"https://github.com/smolijar/kysely-sqlcommenter#readme","bugs":{"url":"https://github.com/smolijar/kysely-sqlcommenter/issues"},"dist":{"shasum":"1c5eeb678ddf0f667c2b74560c290f6c5a53f74b","tarball":"https://registry.npmjs.org/kysely-sqlcommenter/-/kysely-sqlcommenter-0.1.0.tgz","fileCount":10,"integrity":"sha512-0J+GZP5v8pQo0UIrKfU6Cf6OrmUj4bt8PRtHeRRpiEgJ6zFaor1LTgyRXp593/S+p0qOYCwoaJSAqcsfb4gtXg==","signatures":[{"sig":"MEQCID8zSn2iNSgVAAHgjuMX5BYJ3XtWtOJHvHURkv+t9iOGAiBinwDQ7jXK7z7+bJwB444ZAvIcrr61GuDpqO5YcqhdGg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/kysely-sqlcommenter@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":12650},"main":"./dist/kysely-sqlcommenter.umd.cjs","type":"module","types":"./dist/main.d.ts","module":"./dist/kysely-sqlcommenter.js","exports":{".":{"types":"./dist/main.d.ts","import":"./dist/kysely-sqlcommenter.js","require":"./dist/kysely-sqlcommenter.umd.cjs"}},"gitHead":"8f36058fa96e4e07fa5ef0feb7091a8937f349b7","scripts":{"dev":"vite","test":"vitest --run","audit":"pnpm audit --audit-level high","build":"tsc --noEmit && vite build && tsc -p tsconfig.build.json","test:watch":"vitest","prepublishOnly":"pnpm test && pnpm run test:integration","test:integration":"./integration-test-builder/test.sh"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:4e54388a-6ae7-4f24-aa88-adea40ef58d1"}},"repository":{"url":"git+https://github.com/smolijar/kysely-sqlcommenter.git","type":"git"},"_npmVersion":"11.16.0","description":"SqlCommenter plugin and helpers for Kysely","directories":{},"sideEffects":false,"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"packageManager":"pnpm@10.33.0","devDependencies":{"vite":"^8.1.3","kysely":"^0.29.2","vitest":"^4.1.9","typescript":"^5.9.3","@types/node":"^20.19.43"},"peerDependencies":{"kysely":">=0.28.17 <0.30.0"},"_npmOperationalInternal":{"tmp":"tmp/kysely-sqlcommenter_0.1.0_1783621307353_0.5682024852157559","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"kysely-sqlcommenter","version":"0.2.0","description":"SqlCommenter plugin and helpers for Kysely","type":"module","packageManager":"pnpm@10.33.0","author":{"name":"Jaroslav Šmolík","email":"smolijar@gmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/smolijar/kysely-sqlcommenter.git"},"homepage":"https://github.com/smolijar/kysely-sqlcommenter#readme","bugs":{"url":"https://github.com/smolijar/kysely-sqlcommenter/issues"},"sideEffects":false,"keywords":["kysely","sqlcommenter","sql"],"main":"./dist/kysely-sqlcommenter.umd.cjs","module":"./dist/kysely-sqlcommenter.js","types":"./dist/main.d.ts","exports":{".":{"types":"./dist/main.d.ts","import":"./dist/kysely-sqlcommenter.js","require":"./dist/kysely-sqlcommenter.umd.cjs"}},"scripts":{"dev":"vite","build":"tsc --noEmit && vite build && tsc -p tsconfig.build.json","test":"vitest --run","test:watch":"vitest","test:integration":"./integration-test-builder/test.sh","audit":"pnpm audit --audit-level high","prepublishOnly":"pnpm test && pnpm run test:integration"},"peerDependencies":{"kysely":">=0.28.17 <0.30.0"},"devDependencies":{"@types/node":"^20.19.43","kysely":"^0.29.2","typescript":"^5.9.3","vite":"^8.1.3","vitest":"^4.1.9"},"gitHead":"97d0da52fd72ea102067de77a87576c6d120202c","_id":"kysely-sqlcommenter@0.2.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-Yyvt1/VCDYfrfCKtEhHeo+TI3JvNTlj+G++ljsnIa6dfDS1p1r1gUrLr8uKm5F1PbTaLnl3AyxI3O3+90vnwIA==","shasum":"9d200b5a07d40656374d47215cb73dddbc6c91c0","tarball":"https://registry.npmjs.org/kysely-sqlcommenter/-/kysely-sqlcommenter-0.2.0.tgz","fileCount":10,"unpackedSize":14317,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/kysely-sqlcommenter@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCbmgu51/Ug13aKcQLd658qnWo9kdIdJE85pnLwu2/1UgIhAOnTkaloxT/+UCQn/klChGpBIG0RjRB68qHjntZqqZDd"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:4e54388a-6ae7-4f24-aa88-adea40ef58d1"}},"directories":{},"maintainers":[{"name":"grissius","email":"grissius@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kysely-sqlcommenter_0.2.0_1784036501457_0.2149073360159508"},"_hasShrinkwrap":false}},"time":{"created":"2024-02-10T12:56:28.936Z","modified":"2026-07-14T13:41:41.891Z","0.0.0":"2024-01-28T15:35:54.363Z","0.0.1":"2024-02-10T12:56:29.115Z","0.1.0":"2026-07-09T18:21:47.505Z","0.2.0":"2026-07-14T13:41:41.590Z"},"bugs":{"url":"https://github.com/smolijar/kysely-sqlcommenter/issues"},"author":{"name":"Jaroslav Šmolík","email":"smolijar@gmail.com"},"license":"MIT","homepage":"https://github.com/smolijar/kysely-sqlcommenter#readme","keywords":["kysely","sqlcommenter","sql"],"repository":{"type":"git","url":"git+https://github.com/smolijar/kysely-sqlcommenter.git"},"description":"SqlCommenter plugin and helpers for Kysely","maintainers":[{"name":"grissius","email":"grissius@gmail.com"}],"readme":"<div align=\"center\">\n  \n<img src=\"https://i.imgur.com/Nh40Jdw.png\" width=300 />\n\n# Kysely SqlCommenter\n\n[SqlCommenter](https://google.github.io/sqlcommenter/) plugin for [Kysely](https://kysely.dev/)\n\n[![npm version](https://img.shields.io/npm/v/kysely-sqlcommenter.svg)](https://www.npmjs.com/package/kysely-sqlcommenter)\n[![CI](https://github.com/smolijar/kysely-sqlcommenter/actions/workflows/test.yaml/badge.svg)](https://github.com/smolijar/kysely-sqlcommenter/actions/workflows/test.yaml)\n\n</div>\n\n## Getting started\n\n```bash\nnpm install kysely-sqlcommenter\n```\n\nRequires Kysely `>=0.28.17 <0.30.0`.\n\nSqlCommenterPlugin does not change the API of Kysely. You only provide it a callback for getting the metadata for the comment. [AsyncLocalStorage](https://nodejs.org/api/async_hooks.html#class-asynclocalstorage) or any alternative is needed.\n\nInitialize the `AsyncLocalStorage`:\n\n```ts\nimport { AsyncLocalStorage } from 'node:async_hooks'\nimport { SqlCommentLike } from 'kysely-sqlcommenter'\n\nconst asyncLocalStorage = new AsyncLocalStorage<SqlCommentLike>()\n```\n\nRegister the `SqlCommenterPlugin` using the `asyncLocalStorage` in callback:\n\n```ts\nimport { SqlCommenterPlugin } from 'kysely-sqlcommenter'\n\nconst db = new Kysely<DB>({\n  // ... kysely config\n  plugins: [\n    // Provide callback\n    new SqlCommenterPlugin(() => asyncLocalStorage.getStore()),\n  ],\n})\n```\n\nCreate a root middleware, register the root span with storage via `asyncLocalStorage.run`. Everything in the callstack of this `next` will have access to a shared copy of the storage (new calls will have exclusive storage). You can initialize it with a value.\n\n```ts\napp.use((req, res, next) => {\n  asyncLocalStorage.run({ controller: req.path }, next)\n})\n```\n\nAny supported DML query will have the appropriate _SqlComment_. Supported query types: select, update, insert, delete, and merge.\n\n```ts\ndb.selectFrom('cats').select(['id', 'name'])\n// select \"id\", \"name\" from \"cats\" /*controller='cats'*/\n```\n\n### Cloud SQL Query Insights\n\nSqlcommenter spec wraps values in single quotes: `/*action='list'*/`. Cloud SQL Query Insights currently displays those delimiters as part of the tag value. Keep the default for spec-compliant output, or disable value quoting if you only target Cloud SQL display:\n\n```ts\nconst db = new Kysely<DB>({\n  // ... kysely config\n  plugins: [\n    new SqlCommenterPlugin(() => asyncLocalStorage.getStore(), {\n      quoteValues: false,\n    }),\n  ],\n})\n```\n\nThis emits `/*action=list*/`, which is intentionally not sqlcommenter-spec compliant.\nThe explicit `sqlCommenter` helper accepts the same option as its third argument.\n\n### Per-query\n\nFor explicit per-query comments, use Kysely's `$call` helper API:\n\n```ts\nimport { sqlCommenter } from 'kysely-sqlcommenter'\n\ndb.selectFrom('cats')\n  .$call((qb) => sqlCommenter(qb, { controller: 'cats', action: 'list' }))\n  .select(['id', 'name'])\n// select \"id\", \"name\" from \"cats\" /*action='list',controller='cats'*/\n```\n\nSee the full working example for express [here](./examples/express.ts), including concurrency demo and adjusting the comment in other middleware.\n\n## Features\n\n- SqlCommenter spec serialization tests\n- Callback API with AsyncLocalStorage examples\n- Explicit helper API via Kysely `$call`\n- DML query support: select, update, insert, delete, and merge\n- Package smoke tests and CI\n\n## References\n\n- [SqlCommenter](https://google.github.io/sqlcommenter/)\n- [Kysely](https://kysely.dev/)\n- [Support for sqlcommenter? #384](https://github.com/kysely-org/kysely/issues/384)\n","readmeFilename":"README.md"}