Latest Threat Research:SANDWORM_MODE: Shai-Hulud-Style npm Worm Hijacks CI Workflows and Poisons AI Toolchains.Details →
@prisma/sqlcommenter
Advanced tools
@prisma/sqlcommenter - npm Package Compare versions
+201
| Apache License | ||
| Version 2.0, January 2004 | ||
| http://www.apache.org/licenses/ | ||
| TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION | ||
| 1. Definitions. | ||
| "License" shall mean the terms and conditions for use, reproduction, | ||
| and distribution as defined by Sections 1 through 9 of this document. | ||
| "Licensor" shall mean the copyright owner or entity authorized by | ||
| the copyright owner that is granting the License. | ||
| "Legal Entity" shall mean the union of the acting entity and all | ||
| other entities that control, are controlled by, or are under common | ||
| control with that entity. For the purposes of this definition, | ||
| "control" means (i) the power, direct or indirect, to cause the | ||
| direction or management of such entity, whether by contract or | ||
| otherwise, or (ii) ownership of fifty percent (50%) or more of the | ||
| outstanding shares, or (iii) beneficial ownership of such entity. | ||
| "You" (or "Your") shall mean an individual or Legal Entity | ||
| exercising permissions granted by this License. | ||
| "Source" form shall mean the preferred form for making modifications, | ||
| including but not limited to software source code, documentation | ||
| source, and configuration files. | ||
| "Object" form shall mean any form resulting from mechanical | ||
| transformation or translation of a Source form, including but | ||
| not limited to compiled object code, generated documentation, | ||
| and conversions to other media types. | ||
| "Work" shall mean the work of authorship, whether in Source or | ||
| Object form, made available under the License, as indicated by a | ||
| copyright notice that is included in or attached to the work | ||
| (an example is provided in the Appendix below). | ||
| "Derivative Works" shall mean any work, whether in Source or Object | ||
| form, that is based on (or derived from) the Work and for which the | ||
| editorial revisions, annotations, elaborations, or other modifications | ||
| represent, as a whole, an original work of authorship. For the purposes | ||
| of this License, Derivative Works shall not include works that remain | ||
| separable from, or merely link (or bind by name) to the interfaces of, | ||
| the Work and Derivative Works thereof. | ||
| "Contribution" shall mean any work of authorship, including | ||
| the original version of the Work and any modifications or additions | ||
| to that Work or Derivative Works thereof, that is intentionally | ||
| submitted to Licensor for inclusion in the Work by the copyright owner | ||
| or by an individual or Legal Entity authorized to submit on behalf of | ||
| the copyright owner. For the purposes of this definition, "submitted" | ||
| means any form of electronic, verbal, or written communication sent | ||
| to the Licensor or its representatives, including but not limited to | ||
| communication on electronic mailing lists, source code control systems, | ||
| and issue tracking systems that are managed by, or on behalf of, the | ||
| Licensor for the purpose of discussing and improving the Work, but | ||
| excluding communication that is conspicuously marked or otherwise | ||
| designated in writing by the copyright owner as "Not a Contribution." | ||
| "Contributor" shall mean Licensor and any individual or Legal Entity | ||
| on behalf of whom a Contribution has been received by Licensor and | ||
| subsequently incorporated within the Work. | ||
| 2. Grant of Copyright License. Subject to the terms and conditions of | ||
| this License, each Contributor hereby grants to You a perpetual, | ||
| worldwide, non-exclusive, no-charge, royalty-free, irrevocable | ||
| copyright license to reproduce, prepare Derivative Works of, | ||
| publicly display, publicly perform, sublicense, and distribute the | ||
| Work and such Derivative Works in Source or Object form. | ||
| 3. Grant of Patent License. Subject to the terms and conditions of | ||
| this License, each Contributor hereby grants to You a perpetual, | ||
| worldwide, non-exclusive, no-charge, royalty-free, irrevocable | ||
| (except as stated in this section) patent license to make, have made, | ||
| use, offer to sell, sell, import, and otherwise transfer the Work, | ||
| where such license applies only to those patent claims licensable | ||
| by such Contributor that are necessarily infringed by their | ||
| Contribution(s) alone or by combination of their Contribution(s) | ||
| with the Work to which such Contribution(s) was submitted. If You | ||
| institute patent litigation against any entity (including a | ||
| cross-claim or counterclaim in a lawsuit) alleging that the Work | ||
| or a Contribution incorporated within the Work constitutes direct | ||
| or contributory patent infringement, then any patent licenses | ||
| granted to You under this License for that Work shall terminate | ||
| as of the date such litigation is filed. | ||
| 4. Redistribution. You may reproduce and distribute copies of the | ||
| Work or Derivative Works thereof in any medium, with or without | ||
| modifications, and in Source or Object form, provided that You | ||
| meet the following conditions: | ||
| (a) You must give any other recipients of the Work or | ||
| Derivative Works a copy of this License; and | ||
| (b) You must cause any modified files to carry prominent notices | ||
| stating that You changed the files; and | ||
| (c) You must retain, in the Source form of any Derivative Works | ||
| that You distribute, all copyright, patent, trademark, and | ||
| attribution notices from the Source form of the Work, | ||
| excluding those notices that do not pertain to any part of | ||
| the Derivative Works; and | ||
| (d) If the Work includes a "NOTICE" text file as part of its | ||
| distribution, then any Derivative Works that You distribute must | ||
| include a readable copy of the attribution notices contained | ||
| within such NOTICE file, excluding those notices that do not | ||
| pertain to any part of the Derivative Works, in at least one | ||
| of the following places: within a NOTICE text file distributed | ||
| as part of the Derivative Works; within the Source form or | ||
| documentation, if provided along with the Derivative Works; or, | ||
| within a display generated by the Derivative Works, if and | ||
| wherever such third-party notices normally appear. The contents | ||
| of the NOTICE file are for informational purposes only and | ||
| do not modify the License. You may add Your own attribution | ||
| notices within Derivative Works that You distribute, alongside | ||
| or as an addendum to the NOTICE text from the Work, provided | ||
| that such additional attribution notices cannot be construed | ||
| as modifying the License. | ||
| You may add Your own copyright statement to Your modifications and | ||
| may provide additional or different license terms and conditions | ||
| for use, reproduction, or distribution of Your modifications, or | ||
| for any such Derivative Works as a whole, provided Your use, | ||
| reproduction, and distribution of the Work otherwise complies with | ||
| the conditions stated in this License. | ||
| 5. Submission of Contributions. Unless You explicitly state otherwise, | ||
| any Contribution intentionally submitted for inclusion in the Work | ||
| by You to the Licensor shall be under the terms and conditions of | ||
| this License, without any additional terms or conditions. | ||
| Notwithstanding the above, nothing herein shall supersede or modify | ||
| the terms of any separate license agreement you may have executed | ||
| with Licensor regarding such Contributions. | ||
| 6. Trademarks. This License does not grant permission to use the trade | ||
| names, trademarks, service marks, or product names of the Licensor, | ||
| except as required for reasonable and customary use in describing the | ||
| origin of the Work and reproducing the content of the NOTICE file. | ||
| 7. Disclaimer of Warranty. Unless required by applicable law or | ||
| agreed to in writing, Licensor provides the Work (and each | ||
| Contributor provides its Contributions) on an "AS IS" BASIS, | ||
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or | ||
| implied, including, without limitation, any warranties or conditions | ||
| of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A | ||
| PARTICULAR PURPOSE. You are solely responsible for determining the | ||
| appropriateness of using or redistributing the Work and assume any | ||
| risks associated with Your exercise of permissions under this License. | ||
| 8. Limitation of Liability. In no event and under no legal theory, | ||
| whether in tort (including negligence), contract, or otherwise, | ||
| unless required by applicable law (such as deliberate and grossly | ||
| negligent acts) or agreed to in writing, shall any Contributor be | ||
| liable to You for damages, including any direct, indirect, special, | ||
| incidental, or consequential damages of any character arising as a | ||
| result of this License or out of the use or inability to use the | ||
| Work (including but not limited to damages for loss of goodwill, | ||
| work stoppage, computer failure or malfunction, or any and all | ||
| other commercial damages or losses), even if such Contributor | ||
| has been advised of the possibility of such damages. | ||
| 9. Accepting Warranty or Additional Liability. While redistributing | ||
| the Work or Derivative Works thereof, You may choose to offer, | ||
| and charge a fee for, acceptance of support, warranty, indemnity, | ||
| or other liability obligations and/or rights consistent with this | ||
| License. However, in accepting such obligations, You may act only | ||
| on Your own behalf and on Your sole responsibility, not on behalf | ||
| of any other Contributor, and only if You agree to indemnify, | ||
| defend, and hold each Contributor harmless for any liability | ||
| incurred by, or claims asserted against, such Contributor by reason | ||
| of your accepting any such warranty or additional liability. | ||
| END OF TERMS AND CONDITIONS | ||
| APPENDIX: How to apply the Apache License to your work. | ||
| To apply the Apache License to your work, attach the following | ||
| boilerplate notice, with the fields enclosed by brackets "[]" | ||
| replaced with your own identifying information. (Don't include | ||
| the brackets!) The text should be enclosed in the appropriate | ||
| comment syntax for the file format. We also recommend that a | ||
| file or class name and description of purpose be included on the | ||
| same "printed page" as the copyright notice for easier | ||
| identification within third-party archives. | ||
| Copyright [yyyy] [name of copyright owner] | ||
| Licensed under the Apache License, Version 2.0 (the "License"); | ||
| you may not use this file except in compliance with the License. | ||
| You may obtain a copy of the License at | ||
| http://www.apache.org/licenses/LICENSE-2.0 | ||
| Unless required by applicable law or agreed to in writing, software | ||
| distributed under the License is distributed on an "AS IS" BASIS, | ||
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| See the License for the specific language governing permissions and | ||
| limitations under the License. |
+25
-3
@@ -0,1 +1,3 @@ | ||
| declare type JsonQueryAction = 'findUnique' | 'findUniqueOrThrow' | 'findFirst' | 'findFirstOrThrow' | 'findMany' | 'createOne' | 'createMany' | 'createManyAndReturn' | 'updateOne' | 'updateMany' | 'updateManyAndReturn' | 'deleteOne' | 'deleteMany' | 'upsertOne' | 'aggregate' | 'groupBy' | 'executeRaw' | 'queryRaw' | 'runCommandRaw' | 'findRaw' | 'aggregateRaw'; | ||
| /** | ||
@@ -30,2 +32,12 @@ * Information about a compacted batch query (e.g. multiple independent | ||
| readonly query: SqlCommenterQueryInfo; | ||
| /** | ||
| * Raw SQL query generated from this Prisma query. | ||
| * | ||
| * It is always available when `PrismaClient` connects to the database and | ||
| * renders SQL queries directly. | ||
| * | ||
| * When using Prisma Accelerate, SQL rendering happens on Accelerate side and the raw | ||
| * SQL strings are not yet available when SQL commenter plugins are executed. | ||
| */ | ||
| readonly sql?: string; | ||
| } | ||
@@ -35,3 +47,3 @@ | ||
| * A SQL commenter plugin that returns key-value pairs to be added as comments. | ||
| * Return an empty object to add no comments. | ||
| * Return an empty object to add no comments. Keys with undefined values will be omitted. | ||
| * | ||
@@ -44,2 +56,4 @@ * @example | ||
| * model: context.query.modelName ?? 'raw', | ||
| * // Conditional key - will be omitted if ctx.sql is undefined | ||
| * sqlLength: context.sql ? String(context.sql.length) : undefined, | ||
| * } | ||
@@ -50,3 +64,3 @@ * } | ||
| export declare interface SqlCommenterPlugin { | ||
| (context: SqlCommenterContext): Record<string, string>; | ||
| (context: SqlCommenterContext): SqlCommenterTags; | ||
| } | ||
@@ -57,3 +71,3 @@ | ||
| */ | ||
| export declare type SqlCommenterQueryAction = 'findUnique' | 'findUniqueOrThrow' | 'findFirst' | 'findFirstOrThrow' | 'findMany' | 'createOne' | 'createMany' | 'createManyAndReturn' | 'updateOne' | 'updateMany' | 'updateManyAndReturn' | 'deleteOne' | 'deleteMany' | 'upsertOne' | 'aggregate' | 'groupBy' | 'executeRaw' | 'queryRaw' | 'runCommandRaw' | 'findRaw' | 'aggregateRaw'; | ||
| export declare type SqlCommenterQueryAction = JsonQueryAction; | ||
@@ -91,2 +105,10 @@ /** | ||
| /** | ||
| * Key-value pairs to add as SQL comments. | ||
| * Keys with undefined values will be omitted from the final comment. | ||
| */ | ||
| export declare type SqlCommenterTags = { | ||
| readonly [key: string]: string | undefined; | ||
| }; | ||
| export { } |
+25
-3
@@ -0,1 +1,3 @@ | ||
| declare type JsonQueryAction = 'findUnique' | 'findUniqueOrThrow' | 'findFirst' | 'findFirstOrThrow' | 'findMany' | 'createOne' | 'createMany' | 'createManyAndReturn' | 'updateOne' | 'updateMany' | 'updateManyAndReturn' | 'deleteOne' | 'deleteMany' | 'upsertOne' | 'aggregate' | 'groupBy' | 'executeRaw' | 'queryRaw' | 'runCommandRaw' | 'findRaw' | 'aggregateRaw'; | ||
| /** | ||
@@ -30,2 +32,12 @@ * Information about a compacted batch query (e.g. multiple independent | ||
| readonly query: SqlCommenterQueryInfo; | ||
| /** | ||
| * Raw SQL query generated from this Prisma query. | ||
| * | ||
| * It is always available when `PrismaClient` connects to the database and | ||
| * renders SQL queries directly. | ||
| * | ||
| * When using Prisma Accelerate, SQL rendering happens on Accelerate side and the raw | ||
| * SQL strings are not yet available when SQL commenter plugins are executed. | ||
| */ | ||
| readonly sql?: string; | ||
| } | ||
@@ -35,3 +47,3 @@ | ||
| * A SQL commenter plugin that returns key-value pairs to be added as comments. | ||
| * Return an empty object to add no comments. | ||
| * Return an empty object to add no comments. Keys with undefined values will be omitted. | ||
| * | ||
@@ -44,2 +56,4 @@ * @example | ||
| * model: context.query.modelName ?? 'raw', | ||
| * // Conditional key - will be omitted if ctx.sql is undefined | ||
| * sqlLength: context.sql ? String(context.sql.length) : undefined, | ||
| * } | ||
@@ -50,3 +64,3 @@ * } | ||
| export declare interface SqlCommenterPlugin { | ||
| (context: SqlCommenterContext): Record<string, string>; | ||
| (context: SqlCommenterContext): SqlCommenterTags; | ||
| } | ||
@@ -57,3 +71,3 @@ | ||
| */ | ||
| export declare type SqlCommenterQueryAction = 'findUnique' | 'findUniqueOrThrow' | 'findFirst' | 'findFirstOrThrow' | 'findMany' | 'createOne' | 'createMany' | 'createManyAndReturn' | 'updateOne' | 'updateMany' | 'updateManyAndReturn' | 'deleteOne' | 'deleteMany' | 'upsertOne' | 'aggregate' | 'groupBy' | 'executeRaw' | 'queryRaw' | 'runCommandRaw' | 'findRaw' | 'aggregateRaw'; | ||
| export declare type SqlCommenterQueryAction = JsonQueryAction; | ||
@@ -91,2 +105,10 @@ /** | ||
| /** | ||
| * Key-value pairs to add as SQL comments. | ||
| * Keys with undefined values will be omitted from the final comment. | ||
| */ | ||
| export declare type SqlCommenterTags = { | ||
| readonly [key: string]: string | undefined; | ||
| }; | ||
| export { } |
+10
-8
| { | ||
| "name": "@prisma/sqlcommenter", | ||
| "version": "0.0.1", | ||
| "version": "7.1.0-dev.34", | ||
| "description": "SQL commenter types for Prisma", | ||
@@ -28,11 +28,13 @@ "main": "dist/index.js", | ||
| "bugs": "https://github.com/prisma/prisma/issues", | ||
| "scripts": { | ||
| "dev": "DEV=true tsx helpers/build.ts", | ||
| "build": "tsx helpers/build.ts", | ||
| "prepublishOnly": "pnpm run build" | ||
| }, | ||
| "files": [ | ||
| "dist" | ||
| ], | ||
| "sideEffects": false | ||
| } | ||
| "sideEffects": false, | ||
| "devDependencies": { | ||
| "@prisma/json-protocol": "7.1.0-dev.34" | ||
| }, | ||
| "scripts": { | ||
| "dev": "DEV=true tsx helpers/build.ts", | ||
| "build": "tsx helpers/build.ts" | ||
| } | ||
| } |
+61
-40
@@ -46,3 +46,3 @@ # @prisma/sqlcommenter | ||
| const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL }) | ||
| const adapter = new PrismaPg({ connectionString: `${process.env.DATABASE_URL}` }) | ||
@@ -57,21 +57,21 @@ const prisma = new PrismaClient({ | ||
| Plugins receive a `SqlCommenterContext` object with information about the query being executed: | ||
| Plugins receive a `SqlCommenterContext` object with information about the query being executed. | ||
| See [API Reference](#api-reference) for more details. | ||
| ### Conditional Keys | ||
| Plugins return a `SqlCommenterTags` object where keys can have `undefined` values. Keys with `undefined` values are automatically filtered out from the final comment: | ||
| ```typescript | ||
| interface SqlCommenterContext { | ||
| query: SqlCommenterQueryInfo | ||
| } | ||
| import type { SqlCommenterPlugin } from '@prisma/sqlcommenter' | ||
| type SqlCommenterQueryInfo = | ||
| | { type: 'single'; modelName?: string; action: string; query: unknown } | ||
| | { type: 'compacted'; queries: SqlCommenterSingleQueryInfo[] } | ||
| const conditionalPlugin: SqlCommenterPlugin = (context) => ({ | ||
| model: context.query.modelName, // undefined for raw queries, automatically omitted | ||
| action: context.query.action, | ||
| // Include SQL length only when available (not available with Accelerate) | ||
| sqlLength: context.sql ? String(context.sql.length) : undefined, | ||
| }) | ||
| ``` | ||
| - **`type: 'single'`**: A single Prisma query is being executed | ||
| - `modelName`: The model being queried (e.g., `"User"`, `"Post"`). Undefined for raw queries. | ||
| - `action`: The Prisma operation (e.g., `"findMany"`, `"createOne"`, `"queryRaw"`) | ||
| - `query`: The full query object with selection and arguments | ||
| - **`type: 'compacted'`**: Multiple queries have been batched into a single SQL statement (e.g., automatic `findUnique` batching or explicit `$transaction` batches) | ||
| ### Example: Custom Application Tags | ||
@@ -82,15 +82,8 @@ | ||
| const applicationTags: SqlCommenterPlugin = (context) => { | ||
| const tags: Record<string, string> = { | ||
| application: 'my-service', | ||
| environment: process.env.NODE_ENV ?? 'development', | ||
| } | ||
| if (context.query.type === 'single' && context.query.modelName) { | ||
| tags.model = context.query.modelName | ||
| tags.operation = context.query.action | ||
| } | ||
| return tags | ||
| } | ||
| const applicationTags: SqlCommenterPlugin = (context) => ({ | ||
| application: 'my-service', | ||
| environment: process.env.NODE_ENV ?? 'development', | ||
| operation: context.query.action, | ||
| model: context.query.modelName, // automatically omitted if undefined | ||
| }) | ||
| ``` | ||
@@ -104,11 +97,7 @@ | ||
| const traceStorage = new AsyncLocalStorage<{ route: string }>() | ||
| const routeStorage = new AsyncLocalStorage<{ route: string }>() | ||
| const traceContext: SqlCommenterPlugin = () => { | ||
| const store = traceStorage.getStore() | ||
| if (store?.route) { | ||
| return { route: store.route } | ||
| } | ||
| return {} | ||
| } | ||
| const routeContext: SqlCommenterPlugin = () => ({ | ||
| route: routeStorage.getStore()?.route, | ||
| }) | ||
| ``` | ||
@@ -126,2 +115,10 @@ | ||
| ### `SqlCommenterTags` | ||
| ```typescript | ||
| type SqlCommenterTags = { readonly [key: string]: string | undefined } | ||
| ``` | ||
| Key-value pairs to add as SQL comments. Keys with `undefined` values are automatically filtered out and will not appear in the final comment. | ||
| ### `SqlCommenterPlugin` | ||
@@ -131,7 +128,7 @@ | ||
| interface SqlCommenterPlugin { | ||
| (context: SqlCommenterContext): Record<string, string> | ||
| (context: SqlCommenterContext): SqlCommenterTags | ||
| } | ||
| ``` | ||
| A function that receives query context and returns key-value pairs. Return an empty object to add no comments for a particular query. | ||
| A function that receives query context and returns key-value pairs. Return an empty object to add no comments for a particular query. Keys with `undefined` values are automatically omitted. | ||
@@ -153,3 +150,3 @@ ### `SqlCommenterContext` | ||
| | ({ type: 'single' } & SqlCommenterSingleQueryInfo) | ||
| | { type: 'compacted'; queries: SqlCommenterSingleQueryInfo[] } | ||
| | ({ type: 'compacted' } & SqlCommenterCompactedQueryInfo) | ||
| ``` | ||
@@ -159,2 +156,5 @@ | ||
| - **`type: 'single'`**: A single Prisma query is being executed | ||
| - **`type: 'compacted'`**: Multiple queries have been batched into a single SQL statement (e.g., automatic `findUnique` batching) | ||
| ### `SqlCommenterSingleQueryInfo` | ||
@@ -165,3 +165,3 @@ | ||
| modelName?: string | ||
| action: string | ||
| action: SqlCommenterQueryAction | ||
| query: unknown | ||
@@ -173,2 +173,22 @@ } | ||
| - `modelName`: The model being queried (e.g., `"User"`, `"Post"`). Undefined for raw queries. | ||
| - `action`: The Prisma operation (e.g., `"findMany"`, `"createOne"`, `"queryRaw"`) | ||
| - `query`: The full query object with selection and arguments. Specifics of the query representation are not part of the public API yet. | ||
| ### `SqlCommenterCompactedQueryInfo` | ||
| ```typescript | ||
| interface SqlCommenterCompactedQueryInfo { | ||
| modelName?: string | ||
| action: SqlCommenterQueryAction | ||
| queries: unknown[] | ||
| } | ||
| ``` | ||
| Information about a compacted batch query. | ||
| - `modelName`: The model being queried (e.g., `"User"`, `"Post"`). | ||
| - `action`: The Prisma operation (e.g., `"findUnique"`) | ||
| - `queries`: The full query objects with selections and arguments. Specifics of the query representation are not part of the public API yet. | ||
| ## Notes | ||
@@ -178,2 +198,3 @@ | ||
| - Later plugins override earlier ones if they return the same key | ||
| - Keys with `undefined` values are filtered out (they do not remove keys set by earlier plugins) | ||
| - Keys and values are URL-encoded per the sqlcommenter spec | ||
@@ -180,0 +201,0 @@ - Single quotes in values are escaped as `\'` |
No alert changes
Improved metrics
- Total package byte prevSize
26164
120.2%- Number of package files
7
16.67%- Lines of code
118
20.41%- Number of lines in readme file
196
12%Worsened metrics
- Dev dependency count
1
Infinity%No dependency changes