@triptease/sql-template-postgres 0.23.24 → 0.35.6

package/README.md

@@ -1,56 +1,200 @@
-# Sql Template
-
-This is yet another SQL tagged template for Typescript/Javascript
-
-## Why another library?
-
-* Typescript first
-* Functional/Immutable
-* Super simple implementation (the main SQL function is [3 lines of code](https://github.com/triptease/sql-template/blob/master/sql-template/src/SQL.ts#L5))
-* Full escaping of identifiers and values
-* Plugable to any DB (currently only Postgres @triptease\sql-template-postgres )
-* Automatic support for prepareStatement naming (Postgres)
-
-## Installation
-
-```shell
-npm install @triptease/sql-template @triptease/sql-template-postgres
-```
-
-## Usage
-
-```javascript
-import {SQL, id} from "@triptease/sql-template";
-import {statement} from "@triptease/sql-template-postgres";
-
-client.query(statement(SQL`select * from ${id(table)} where name = ${name}`));
-```
-
-## Cheatsheet
-
-### Core (@triptease/sql-template) 
-
-| function                                       | Description                                                          |
-|------------------------------------------------|----------------------------------------------------------------------|
-| `SQL`                                          | The main function to create tagged templates for SQL (*DB agnostic*) |
-| `text` (alias `raw`)                           | Input raw SQL without any escaping (*use with care*)                 |
- | `id` / `ids`                                   | Input dynamic identifiers into SQL (*escaped as needed*)             |
- | `value` (optional) / `values` (alias `spread`) | Input one or more values into SQL (*escaped as needed*)              |
-
-
-### Postgres (@triptease/sql-template-postgres)
-
-| function                                       | Description                                                         |
-|------------------------------------------------|---------------------------------------------------------------------|
-| `statement`                                    | Converts DB agnostic `SQL` template into postgres statement         |
-| `prepareStatement`                             | Converts DB agnostic `SQL` template into postgres prepare statement |
-| `debugQuery`                                   | Used to debug a query (*use with care*)                             |
-
-*use with care -> Used incorrectly you can open yourself up to SQL injection*
-
-
-### Extending
-
-It is incredibly simple to extend to other DBs, have a look at the [postgres implementation](https://github.com/triptease/sql-template/blob/master/sql-template-postgres/src/index.ts#L17). 
-
-
+# Sql Template
+
+This is yet another SQL tagged template for Typescript/Javascript
+
+## Why another library?
+
+* Typescript first
+* Functional/Immutable
+* Super simple implementation (see [SQL.ts](https://github.com/triptease/sql-template/blob/master/sql-template/src/SQL.ts))
+* Full escaping of identifiers and values
+* Plugable to any DB (currently Postgres via `@triptease/sql-template-postgres` with `pg`)
+* Automatic support for prepareStatement naming (Postgres)
+
+## Installation
+
+```shell
+npm install @triptease/sql-template @triptease/sql-template-postgres
+# or
+bun add @triptease/sql-template @triptease/sql-template-postgres
+```
+
+Both packages are plain ESM JavaScript with type declarations, so they work in Node and Bun.
+`@triptease/sql-template` has no dependencies and `@triptease/sql-template-postgres` depends only on it
+(it does not depend on `pg`; bring your own driver). In Node they can also be loaded with `require()`
+(Node 20.19+/22.12+, which can `require()` ES modules).
+
+## Usage
+
+### Node with [pg](https://node-postgres.com/)
+
+```typescript
+import pg from "pg";
+import {SQL, id, values} from "@triptease/sql-template";
+import {statement, prepareStatement} from "@triptease/sql-template-postgres";
+
+const pool = new pg.Pool();
+const {rows} = await pool.query(statement(SQL`select * from ${id(table)} where name = ${name}`));
+// SQL: select * from "users" where name = $1   values: ['Dan']
+
+// named prepared statement (name defaults to a hash of the SQL)
+await pool.query(prepareStatement(SQL`select * from users where id in (${values(userIds)})`));
+```
+
+### Bun
+
+If you only target Bun, its built-in [`sql`](https://bun.com/docs/api/sql) tagged template already binds values
+and escapes identifiers, so you probably don't need this library. Use it in Bun when your query code also has to
+run on Node with `pg`, or when you want queries as plain immutable values you can build, test and log
+(`debugQuery`) without a connection.
+
+### Composing
+
+```typescript
+import {SQL, id, ids, text, values} from "@triptease/sql-template";
+
+const where = SQL`where ${id('name')} = ${name}`;
+const query = SQL`select ${ids(['id', 'name'])} from users ${where}`; // templates nest
+const either = SQL`select * from users where ${values([a, b], text(' or '))}`; // explicit raw separator
+```
+
+Templates are immutable (frozen) and flat. Expressions are identified by a `Symbol.for` brand rather than
+`instanceof`, so templates built by a different copy of `@triptease/sql-template` (e.g. two installed
+versions) still work, while plain data (such as parsed JSON) can never be mistaken for SQL.
+
+## Cheatsheet
+
+### Core (@triptease/sql-template)
+
+| function                                       | Description                                                                                 |
+|------------------------------------------------|---------------------------------------------------------------------------------------------|
+| `SQL`                                          | The main function to create tagged templates for SQL (*DB agnostic*)                        |
+| `text` (alias `raw`)                           | Input raw SQL without any escaping (*use with care*)                                        |
+| `id` / `ids(names, separator?)`                | Input dynamic identifiers into SQL (*escaped as needed*)                                    |
+| `value` (optional) / `values(list, separator?)` (alias `spread`) | Input one or more values into SQL (*bound as parameters*)                 |
+| `template`                                     | Combine expressions into a (flattened, frozen) template                                     |
+| `isExpression` / `isText` / `isIdentifier` / `isValue` / `isTemplate` / `kindOf` | Type guards based on the expression brand (for adapters) |
+
+`separator` is an Expression and defaults to `text(', ')`.
+
+### Postgres (@triptease/sql-template-postgres)
+
+| function                                       | Description                                                          |
+|------------------------------------------------|----------------------------------------------------------------------|
+| `statement`                                    | Converts DB agnostic `SQL` template into a postgres statement (`pg`) |
+| `prepareStatement`                             | Converts DB agnostic `SQL` template into a named prepared statement (`pg`) |
+| `escapeIdentifier` / `escapeLiteral`           | Postgres identifier and string literal escaping (ported from `pg`)   |
+| `debugQuery`                                   | Renders a template with values inlined, for debugging (*see below*) |
+
+*use with care -> Used incorrectly you can open yourself up to SQL injection*
+
+`debugQuery` escapes every value (strings, numbers, booleans, null, Dates, Buffers, arrays and objects), but
+it is meant for logging: execute queries with `statement`/`prepareStatement` so values are bound as
+parameters. Inlined literals are not always typed the way parameters are (e.g. arrays become array literal
+strings and objects JSON strings, which need a cast in some contexts). Dates are inlined as UTC ISO strings, so for
+`timestamp` (without time zone) or text targets the output only matches what `pg` executes when the process runs
+with `TZ=UTC`.
+
+## Breaking changes (since the pg-only releases)
+
+* The `separator` of `values`/`spread`/`ids` is now an Expression: replace `values(xs, ' or ')` with
+  `values(xs, text(' or '))`. Passing a string throws a `TypeError` (it used to be inserted as raw SQL).
+* `@triptease/sql-template-postgres` no longer depends on `pg`; its `QueryConfig` is a local type
+  that is structurally compatible with pg's.
+* Adapters throw on expressions they do not understand instead of silently dropping them, and SQL with an
+  invalid escape sequence (e.g. ``SQL`\u` ``) throws instead of producing the text `undefined`.
+* Public types use `unknown` instead of `any`; `ids` takes `string[]`.
+* The packages are ESM only (they used to be CommonJS):
+  * `require()` needs Node 20.19+/22.12+ (older Node versions can only `import` them).
+  * TypeScript consumers need `"module"`/`"moduleResolution"` set to `nodenext` (or `node20`) or `bundler`.
+    A CommonJS project using `node16` (or `nodenext` before TypeScript 5.8) gets error TS1479; switch to one of
+    those settings or load the packages with `import()`.
+  * Only the package roots are exported: deep imports such as `@triptease/sql-template/Text` fail with
+    `ERR_PACKAGE_PATH_NOT_EXPORTED`. Import everything from `@triptease/sql-template` /
+    `@triptease/sql-template-postgres`.
+* `Expression` is abstract and subclassing it is not supported: an instance of your own subclass is rejected with
+  a `TypeError` (compose `SQL`/`text`/`id`/`value`/`template` instead).
+* `debugQuery` output changed: `null`/`undefined` render as `NULL`, booleans as `TRUE`/`FALSE`, negative numbers
+  are parenthesised, `NaN`/`Infinity` are quoted, and Dates, Buffers, arrays and objects are rendered as escaped
+  literals. Do not parse or compare its output.
+* A `Template` built directly with `new Template([...])` now keeps the values of nested templates (they used to be
+  dropped).
+
+## Extending
+
+It is simple to extend to other DBs: switch on `kindOf(expression)` (`'text'`, `'identifier'`, `'value'`,
+`'template'`) and throw on anything else. Have a look at the
+[postgres implementation](https://github.com/triptease/sql-template/blob/master/sql-template-postgres/src/statement.ts).
+
+## Development
+
+Tool versions (node, bun) are pinned in `mise.toml`. Install [mise](https://mise.jdx.dev/getting-started.html), then:
+
+```shell
+mise install   # installs the pinned node and bun
+./run          # install deps, clean, build (tsc --build), typecheck and test (bun test)
+```
+
+The repo is a bun workspace: each package has a published `src/package.json` (runtime dependencies only)
+and a private `test/package.json` (test dependencies). Tests import the packages by name.
+
+The postgres integration tests (`sql-template-postgres/test/integration.test.ts`) run real queries through
+`pg`. They need a database:
+
+```shell
+DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres ./run
+```
+
+Without `DATABASE_URL` they are skipped locally (with a warning) but fail when `CI=true`; the GitHub Actions
+test job provides a `postgres:18` service.
+
+## Releasing
+
+Every push to `triptease/sql-template` that passes the `test` job runs the `publish` job in
+[`.github/workflows/build.yml`](.github/workflows/build.yml), which runs `scripts/release.ts`:
+
+* Version: `0.<git rev-list --count HEAD>.<GITHUB_RUN_NUMBER>`; dist-tag `latest` on `master`, `dev` on other branches.
+* It does a clean `tsc --build` (without declaration maps, as the `.ts` sources are not published), then
+  writes `<pkg>/dist/package.json` from `<pkg>/src/package.json` (version
+  stamped, `workspace:*` replaced by that version, `main`/`types`/`exports` pointing at the `.js`/`.d.ts`
+  files, explicit `files`) and copies this README next to it. The `dist` directory is what gets published, so
+  import paths never contain `src/` or `dist/`. It fails if any `workspace:` range is left.
+* It publishes core first, then postgres, with `npm publish <pkg>/dist`:
+  * to **GitHub Packages** (`npm.pkg.github.com`) on every run, using the workflow's `GITHUB_TOKEN`;
+  * to **npmjs** only when the repo variable `NPM_PUBLISH` is `true`, with `--access public --provenance`,
+    authenticated by npm Trusted Publishing (OIDC), or by an `NPM_TOKEN` secret if one exists.
+* Versions that are already on a registry are skipped, so a failed run can simply be re-run.
+* The staged `dist` directories are kept as the `dist` artifact of the workflow run.
+
+Check what would be published without uploading anything (`npm publish --dry-run`; add `NPM_PUBLISH=true`
+to include npmjs):
+
+```shell
+./run release --dry-run
+```
+
+`./run ci` runs the full build and tests, then the release script.
+
+### One-off setup (needs an npm org admin and a GitHub repo admin)
+
+1. On npmjs.com, for **each** of `@triptease/sql-template` and `@triptease/sql-template-postgres`:
+   Settings → Trusted Publisher → GitHub Actions, organization `triptease`, repository `sql-template`,
+   workflow filename `build.yml`, environment empty. The workflow filename is part of the trust
+   relationship, so do not rename `build.yml`. Once it works, npm recommends disallowing token publishing
+   for the packages (Settings → Publishing access).
+2. In the GitHub repo, set the Actions variable `NPM_PUBLISH` to `true` (Settings → Secrets and variables →
+   Actions → Variables). Until then npmjs publishing is skipped and only GitHub Packages is published.
+   (Alternative to step 1: add an `NPM_TOKEN` repo secret with publish rights; the publish step uses it if set.)
+3. GitHub Packages: after the first publish, check both packages under the org's Packages page, make sure
+   they are linked to this repository and set their visibility to public if they should be visible
+   outside the org.
+
+### Installing from GitHub Packages
+
+npmjs is the main channel. Installing from GitHub Packages needs authentication even for public packages:
+a token with `read:packages` and an `.npmrc` like
+
+```ini
+@triptease:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```

package/escape.d.ts

@@ -0,0 +1,11 @@
+/** Quotes an identifier for Postgres, e.g. `user's "x"` -> `"user's ""x"""`. */
+export declare function escapeIdentifier(str: string): string;
+/** Quotes a string literal for Postgres, e.g. `it's` -> `'it''s'` (uses `E'...'` when it contains backslashes). */
+export declare function escapeLiteral(str: string): string;
+/** @internal Lower-case hex of the bytes of a typed array / DataView / Buffer. */
+export declare function hex(view: ArrayBufferView): string;
+/**
+ * @internal Converts a JS array to a Postgres array literal the same way pg does
+ * (ported from pg/lib/utils.js arrayString, MIT), except Dates are always sent as UTC ISO strings.
+ */
+export declare function arrayLiteral(array: readonly unknown[]): string;

package/escape.js

@@ -0,0 +1,67 @@
+// escapeIdentifier and escapeLiteral are ported from node-postgres (pg/lib/utils.js),
+// Copyright (c) 2010 - 2021 Brian Carlson, MIT License: https://github.com/brianc/node-postgres
+// The only change is that non-string input throws instead of being coerced.
+function requireString(value, what) {
+    if (typeof value !== 'string')
+        throw new TypeError(`${what} must be a string but was ${value === null ? 'null' : typeof value}`);
+    return value;
+}
+/** Quotes an identifier for Postgres, e.g. `user's "x"` -> `"user's ""x"""`. */
+export function escapeIdentifier(str) {
+    return '"' + requireString(str, 'Identifier').replace(/"/g, '""') + '"';
+}
+/** Quotes a string literal for Postgres, e.g. `it's` -> `'it''s'` (uses `E'...'` when it contains backslashes). */
+export function escapeLiteral(str) {
+    requireString(str, 'Literal');
+    let hasBackslash = false;
+    let escaped = "'";
+    for (let i = 0; i < str.length; i++) {
+        const c = str[i];
+        if (c === "'") {
+            escaped += c + c;
+        }
+        else if (c === '\\') {
+            escaped += c + c;
+            hasBackslash = true;
+        }
+        else {
+            escaped += c;
+        }
+    }
+    escaped += "'";
+    if (hasBackslash)
+        escaped = ' E' + escaped;
+    return escaped;
+}
+/** @internal Lower-case hex of the bytes of a typed array / DataView / Buffer. */
+export function hex(view) {
+    const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+    let result = '';
+    for (const b of bytes)
+        result += b.toString(16).padStart(2, '0');
+    return result;
+}
+// Ported from pg/lib/utils.js (MIT, see above)
+function escapeElement(element) {
+    return '"' + element.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+/**
+ * @internal Converts a JS array to a Postgres array literal the same way pg does
+ * (ported from pg/lib/utils.js arrayString, MIT), except Dates are always sent as UTC ISO strings.
+ */
+export function arrayLiteral(array) {
+    return '{' + array.map(item => {
+        if (item === null || item === undefined)
+            return 'NULL';
+        if (Array.isArray(item))
+            return arrayLiteral(item);
+        if (ArrayBuffer.isView(item))
+            return '\\\\x' + hex(item);
+        if (item instanceof Date)
+            return escapeElement(item.toISOString());
+        if (typeof item === 'object')
+            return escapeElement(JSON.stringify(item));
+        return escapeElement(String(item));
+    }).join(',') + '}';
+}
+//# sourceMappingURL=escape.js.map

package/escape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.js","sourceRoot":"","sources":["../src/escape.ts"],"names":[],"mappings":"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","sourcesContent":["// escapeIdentifier and escapeLiteral are ported from node-postgres (pg/lib/utils.js),\n// Copyright (c) 2010 - 2021 Brian Carlson, MIT License: https://github.com/brianc/node-postgres\n// The only change is that non-string input throws instead of being coerced.\n\nfunction requireString(value: unknown, what: string): string {\n    if (typeof value !== 'string') throw new TypeError(`${what} must be a string but was ${value === null ? 'null' : typeof value}`);\n    return value;\n}\n\n/** Quotes an identifier for Postgres, e.g. `user's \"x\"` -> `\"user's \"\"x\"\"\"`. */\nexport function escapeIdentifier(str: string): string {\n    return '\"' + requireString(str, 'Identifier').replace(/\"/g, '\"\"') + '\"';\n}\n\n/** Quotes a string literal for Postgres, e.g. `it's` -> `'it''s'` (uses `E'...'` when it contains backslashes). */\nexport function escapeLiteral(str: string): string {\n    requireString(str, 'Literal');\n    let hasBackslash = false;\n    let escaped = \"'\";\n    for (let i = 0; i < str.length; i++) {\n        const c = str[i];\n        if (c === \"'\") {\n            escaped += c + c;\n        } else if (c === '\\\\') {\n            escaped += c + c;\n            hasBackslash = true;\n        } else {\n            escaped += c;\n        }\n    }\n    escaped += \"'\";\n    if (hasBackslash) escaped = ' E' + escaped;\n    return escaped;\n}\n\n/** @internal Lower-case hex of the bytes of a typed array / DataView / Buffer. */\nexport function hex(view: ArrayBufferView): string {\n    const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);\n    let result = '';\n    for (const b of bytes) result += b.toString(16).padStart(2, '0');\n    return result;\n}\n\n// Ported from pg/lib/utils.js (MIT, see above)\nfunction escapeElement(element: string): string {\n    return '\"' + element.replace(/\\\\/g, '\\\\\\\\').replace(/\"/g, '\\\\\"') + '\"';\n}\n\n/**\n * @internal Converts a JS array to a Postgres array literal the same way pg does\n * (ported from pg/lib/utils.js arrayString, MIT), except Dates are always sent as UTC ISO strings.\n */\nexport function arrayLiteral(array: readonly unknown[]): string {\n    return '{' + array.map(item => {\n        if (item === null || item === undefined) return 'NULL';\n        if (Array.isArray(item)) return arrayLiteral(item);\n        if (ArrayBuffer.isView(item)) return '\\\\\\\\x' + hex(item);\n        if (item instanceof Date) return escapeElement(item.toISOString());\n        if (typeof item === 'object') return escapeElement(JSON.stringify(item));\n        return escapeElement(String(item));\n    }).join(',') + '}';\n}\n"]}

package/index.d.ts

@@ -1,5 +1,2 @@
-import { QueryConfig } from "pg";
-import { Template } from '@triptease/sql-template';
-export declare function debugQuery(sql: Template): string;
-export declare function statement(template: Template): QueryConfig;
-export declare function prepareStatement(template: Template, name?: string): QueryConfig;
+export { type QueryConfig, statement, prepareStatement, debugQuery } from './statement.js';
+export { escapeIdentifier, escapeLiteral } from './escape.js';

package/index.js

@@ -1,52 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.prepareStatement = exports.statement = exports.debugQuery = void 0;
-const pg_1 = require("pg");
-const crypto_1 = require("crypto");
-const sql_template_1 = require("@triptease/sql-template");
-const escapeIdentifier = pg_1.Client.prototype.escapeIdentifier;
-const escapeLiteral = pg_1.Client.prototype.escapeLiteral;
-function debugQuery(sql) {
-    return sql.expressions.reduce((a, e) => {
-        if (e instanceof sql_template_1.Text)
-            return a + e.text;
-        if (e instanceof sql_template_1.Identifier)
-            return a + escapeIdentifier(e.identifier);
-        if (e instanceof sql_template_1.Value)
-            return a + (typeof e.value === 'string' ? escapeLiteral(e.value) : e.value);
-        return a;
-    }, '');
-}
-exports.debugQuery = debugQuery;
-function toSql(sql) {
-    let count = 1;
-    return sql.expressions.reduce((a, e) => {
-        if (e instanceof sql_template_1.Text)
-            return a + e.text;
-        if (e instanceof sql_template_1.Identifier)
-            return a + escapeIdentifier(e.identifier);
-        if (e instanceof sql_template_1.Value)
-            return a + '$' + count++;
-        return a;
-    }, '');
-}
-function statement(template) {
-    return {
-        text: toSql(template),
-        values: template.expressions.flatMap(e => e instanceof sql_template_1.Value ? [e.value] : [])
-    };
-}
-exports.statement = statement;
-function hashSHA256(value) {
-    return (0, crypto_1.createHash)('sha256').update(value).digest('hex');
-}
-function prepareStatement(template, name) {
-    const { text, values } = statement(template);
-    return {
-        name: name !== null && name !== void 0 ? name : `urn:hash::sha256:${hashSHA256(text)}`,
-        text,
-        values
-    };
-}
-exports.prepareStatement = prepareStatement;
+export { statement, prepareStatement, debugQuery } from './statement.js';
+export { escapeIdentifier, escapeLiteral } from './escape.js';
 //# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,SAAS,EAAE,gBAAgB,EAAE,UAAU,EAAC,MAAM,gBAAgB,CAAC;AACzF,OAAO,EAAC,gBAAgB,EAAE,aAAa,EAAC,MAAM,aAAa,CAAC","sourcesContent":["export {type QueryConfig, statement, prepareStatement, debugQuery} from './statement.js';\nexport {escapeIdentifier, escapeLiteral} from './escape.js';\n"]}

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@triptease/sql-template-postgres",
-  "version": "0.23.24",
+  "version": "0.35.6",
+  "type": "module",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/triptease/sql-template.git"
+    "url": "git+https://github.com/triptease/sql-template.git",
+    "directory": "sql-template-postgres/src"
   },
   "author": "Triptease",
   "license": "MIT",
@@ -11,22 +13,22 @@
     "url": "https://github.com/triptease/sql-template/issues"
   },
   "homepage": "https://github.com/triptease/sql-template/",
-  "publishConfig": {
-    "directory": "../dist",
-    "access": "public"
-  },
-  "files": [
-    "*.js",
-    "*.d.ts"
-  ],
   "dependencies": {
-    "@triptease/sql-template": "0.23.24",
-    "pg": "^8.7.1",
-    "tslib": "^2.3.1"
+    "@triptease/sql-template": "0.35.6"
   },
-  "devDependencies": {
-    "@types/pg": "^8.6.4"
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
   },
-  "scripts": {},
-  "readme": "# Sql Template\r\n\r\nThis is yet another SQL tagged template for Typescript/Javascript\r\n\r\n## Why another library?\r\n\r\n* Typescript first\r\n* Functional/Immutable\r\n* Super simple implementation (the main SQL function is [3 lines of code](https://github.com/triptease/sql-template/blob/master/sql-template/src/SQL.ts#L5))\r\n* Full escaping of identifiers and values\r\n* Plugable to any DB (currently only Postgres @triptease\\sql-template-postgres )\r\n* Automatic support for prepareStatement naming (Postgres)\r\n\r\n## Installation\r\n\r\n```shell\r\nnpm install @triptease/sql-template @triptease/sql-template-postgres\r\n```\r\n\r\n## Usage\r\n\r\n```javascript\r\nimport {SQL, id} from \"@triptease/sql-template\";\r\nimport {statement} from \"@triptease/sql-template-postgres\";\r\n\r\nclient.query(statement(SQL`select * from ${id(table)} where name = ${name}`));\r\n```\r\n\r\n## Cheatsheet\r\n\r\n### Core (@triptease/sql-template) \r\n\r\n| function                                       | Description                                                          |\r\n|------------------------------------------------|----------------------------------------------------------------------|\r\n| `SQL`                                          | The main function to create tagged templates for SQL (*DB agnostic*) |\r\n| `text` (alias `raw`)                           | Input raw SQL without any escaping (*use with care*)                 |\r\n | `id` / `ids`                                   | Input dynamic identifiers into SQL (*escaped as needed*)             |\r\n | `value` (optional) / `values` (alias `spread`) | Input one or more values into SQL (*escaped as needed*)              |\r\n\r\n\r\n### Postgres (@triptease/sql-template-postgres)\r\n\r\n| function                                       | Description                                                         |\r\n|------------------------------------------------|---------------------------------------------------------------------|\r\n| `statement`                                    | Converts DB agnostic `SQL` template into postgres statement         |\r\n| `prepareStatement`                             | Converts DB agnostic `SQL` template into postgres prepare statement |\r\n| `debugQuery`                                   | Used to debug a query (*use with care*)                             |\r\n\r\n*use with care -> Used incorrectly you can open yourself up to SQL injection*\r\n\r\n\r\n### Extending\r\n\r\nIt is incredibly simple to extend to other DBs, have a look at the [postgres implementation](https://github.com/triptease/sql-template/blob/master/sql-template-postgres/src/index.ts#L17). \r\n\r\n\r\n"
-}
+  "files": [
+    "**/*.js",
+    "**/*.js.map",
+    "**/*.d.ts",
+    "README.md"
+  ]
+}

package/statement.d.ts

@@ -0,0 +1,17 @@
+import { type Template } from '@triptease/sql-template';
+/** Structurally compatible with pg's `QueryConfig`, so pg is not a dependency. */
+export interface QueryConfig {
+    text: string;
+    values: unknown[];
+    name?: string;
+}
+/** Converts a DB agnostic template into a postgres statement (`$1`, `$2`, ... placeholders plus values). */
+export declare function statement(template: Template): QueryConfig;
+/** Like `statement` but named, so postgres prepares it. The default name is derived from the SQL text. */
+export declare function prepareStatement(template: Template, name?: string): Required<QueryConfig>;
+/**
+ * Renders the template as a single SQL string with every value inlined as an escaped literal.
+ * Intended for logging/debugging: prefer `statement`/`prepareStatement` (bound parameters) for execution,
+ * as inlined literals can be typed differently by postgres (e.g. arrays become text array literals).
+ */
+export declare function debugQuery(template: Template): string;

package/statement.js

@@ -0,0 +1,93 @@
+import { createHash } from 'node:crypto';
+import { kindOf } from '@triptease/sql-template';
+import { arrayLiteral, escapeIdentifier, escapeLiteral, hex } from './escape.js';
+/** @internal Renders a template, escaping identifiers and delegating values. Throws on anything it does not understand. */
+function render(template, renderValue) {
+    let sql = '';
+    const visit = (e) => {
+        const kind = kindOf(e);
+        switch (kind) {
+            case 'text': {
+                const text = e.text;
+                if (typeof text !== 'string')
+                    throw new TypeError('Text expression without a string');
+                sql += text;
+                return;
+            }
+            case 'identifier':
+                sql += escapeIdentifier(e.identifier);
+                return;
+            case 'value':
+                sql += renderValue(e.value);
+                return;
+            case 'template':
+                for (const child of e.expressions)
+                    visit(child);
+                return;
+            default:
+                throw new TypeError(kind === undefined
+                    ? `Not an Expression: ${e === null ? 'null' : typeof e}`
+                    : `Unsupported expression kind: ${kind}`);
+        }
+    };
+    visit(template);
+    return sql;
+}
+/** Converts a DB agnostic template into a postgres statement (`$1`, `$2`, ... placeholders plus values). */
+export function statement(template) {
+    const values = [];
+    const text = render(template, value => '$' + values.push(value));
+    return { text, values };
+}
+function hashSHA256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+/** Like `statement` but named, so postgres prepares it. The default name is derived from the SQL text. */
+export function prepareStatement(template, name) {
+    const { text, values } = statement(template);
+    return {
+        name: name ?? hashSHA256(text).slice(0, 63),
+        text,
+        values
+    };
+}
+function numberLiteral(value) {
+    if (typeof value === 'number' && !Number.isFinite(value))
+        return `'${value}'`; // 'NaN', 'Infinity', '-Infinity'
+    const text = String(value);
+    // parenthesise negatives so that e.g. `1 -${-1}` cannot become a `--` comment
+    return text.startsWith('-') ? `(${text})` : text;
+}
+/** @internal Renders a value as an escaped postgres literal. */
+function literal(value) {
+    if (value === null || value === undefined)
+        return 'NULL';
+    switch (typeof value) {
+        case 'string':
+            return escapeLiteral(value);
+        case 'number':
+        case 'bigint':
+            return numberLiteral(value);
+        case 'boolean':
+            return value ? 'TRUE' : 'FALSE';
+        case 'object':
+            if (value instanceof Date)
+                return escapeLiteral(value.toISOString());
+            if (ArrayBuffer.isView(value))
+                return `'\\x${hex(value)}'::bytea`;
+            if (Array.isArray(value))
+                return escapeLiteral(arrayLiteral(value));
+            return escapeLiteral(JSON.stringify(value));
+        default:
+            throw new TypeError(`Cannot render a ${typeof value} as SQL`);
+    }
+}
+/**
+ * Renders the template as a single SQL string with every value inlined as an escaped literal.
+ * Intended for logging/debugging: prefer `statement`/`prepareStatement` (bound parameters) for execution,
+ * as inlined literals can be typed differently by postgres (e.g. arrays become text array literals).
+ */
+export function debugQuery(template) {
+    return render(template, literal);
+}
+//# sourceMappingURL=statement.js.map

package/statement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statement.js","sourceRoot":"","sources":["../src/statement.ts"],"names":[],"mappings":"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","sourcesContent":["import {createHash} from 'node:crypto';\nimport {type Expression, type Identifier, kindOf, type Template, type Text, type Value} from '@triptease/sql-template';\nimport {arrayLiteral, escapeIdentifier, escapeLiteral, hex} from './escape.js';\n\n/** Structurally compatible with pg's `QueryConfig`, so pg is not a dependency. */\nexport interface QueryConfig {\n    text: string;\n    values: unknown[];\n    name?: string;\n}\n\n/** @internal Renders a template, escaping identifiers and delegating values. Throws on anything it does not understand. */\nfunction render(template: Template, renderValue: (value: unknown) => string): string {\n    let sql = '';\n    const visit = (e: Expression): void => {\n        const kind = kindOf(e);\n        switch (kind) {\n            case 'text': {\n                const text = (e as Text).text;\n                if (typeof text !== 'string') throw new TypeError('Text expression without a string');\n                sql += text;\n                return;\n            }\n            case 'identifier':\n                sql += escapeIdentifier((e as Identifier).identifier);\n                return;\n            case 'value':\n                sql += renderValue((e as Value).value);\n                return;\n            case 'template':\n                for (const child of (e as Template).expressions) visit(child);\n                return;\n            default:\n                throw new TypeError(kind === undefined\n                    ? `Not an Expression: ${e === null ? 'null' : typeof e}`\n                    : `Unsupported expression kind: ${kind}`);\n        }\n    };\n    visit(template);\n    return sql;\n}\n\n/** Converts a DB agnostic template into a postgres statement (`$1`, `$2`, ... placeholders plus values). */\nexport function statement(template: Template): QueryConfig {\n    const values: unknown[] = [];\n    const text = render(template, value => '$' + values.push(value));\n    return {text, values};\n}\n\nfunction hashSHA256(value: string): string {\n    return createHash('sha256').update(value).digest('hex');\n}\n\n/** Like `statement` but named, so postgres prepares it. The default name is derived from the SQL text. */\nexport function prepareStatement(template: Template, name?: string): Required<QueryConfig> {\n    const {text, values} = statement(template);\n    return {\n        name: name ?? hashSHA256(text).slice(0, 63),\n        text,\n        values\n    };\n}\n\nfunction numberLiteral(value: number | bigint): string {\n    if (typeof value === 'number' && !Number.isFinite(value)) return `'${value}'`; // 'NaN', 'Infinity', '-Infinity'\n    const text = String(value);\n    // parenthesise negatives so that e.g. `1 -${-1}` cannot become a `--` comment\n    return text.startsWith('-') ? `(${text})` : text;\n}\n\n/** @internal Renders a value as an escaped postgres literal. */\nfunction literal(value: unknown): string {\n    if (value === null || value === undefined) return 'NULL';\n    switch (typeof value) {\n        case 'string':\n            return escapeLiteral(value);\n        case 'number':\n        case 'bigint':\n            return numberLiteral(value);\n        case 'boolean':\n            return value ? 'TRUE' : 'FALSE';\n        case 'object':\n            if (value instanceof Date) return escapeLiteral(value.toISOString());\n            if (ArrayBuffer.isView(value)) return `'\\\\x${hex(value)}'::bytea`;\n            if (Array.isArray(value)) return escapeLiteral(arrayLiteral(value));\n            return escapeLiteral(JSON.stringify(value));\n        default:\n            throw new TypeError(`Cannot render a ${typeof value} as SQL`);\n    }\n}\n\n/**\n * Renders the template as a single SQL string with every value inlined as an escaped literal.\n * Intended for logging/debugging: prefer `statement`/`prepareStatement` (bound parameters) for execution,\n * as inlined literals can be typed differently by postgres (e.g. arrays become text array literals).\n */\nexport function debugQuery(template: Template): string {\n    return render(template, literal);\n}\n"]}