feat: add Slonik plugin with Zod validation and SQL helper translation

Author: Newbie012

.changeset/slonik-plugin-public.md

@@ -0,0 +1,8 @@
+---
+"@ts-safeql/eslint-plugin": patch
+"@ts-safeql/plugin-utils": patch
+"@ts-safeql/zod-annotator": patch
+"@ts-safeql/plugin-slonik": minor
+---
+
+Publish the experimental Slonik plugin and tighten plugin resolution behavior.

demos/plugin-slonik/eslint.config.js

@@ -0,0 +1,21 @@
+// @ts-check
+
+import safeql from "@ts-safeql/eslint-plugin/config";
+import slonik from "@ts-safeql/plugin-slonik";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config({
+  files: ["src/**/*.ts"],
+  languageOptions: {
+    parser: tseslint.parser,
+    parserOptions: {
+      projectService: true,
+    },
+  },
+  extends: [
+    safeql.configs.connections({
+      databaseUrl: "postgres://postgres:postgres@localhost:5432/postgres",
+      plugins: [slonik()],
+    }),
+  ],
+});

demos/plugin-slonik/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@ts-safeql-demos/plugin-slonik",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src"
+  },
+  "devDependencies": {
+    "@eslint/js": "catalog:",
+    "@slonik/pg-driver": "^48.13.2",
+    "@types/node": "catalog:",
+    "eslint": "catalog:",
+    "slonik": "^48.13.2",
+    "typescript": "catalog:",
+    "typescript-eslint": "catalog:",
+    "zod": "^4.3.6"
+  },
+  "dependencies": {
+    "@ts-safeql/eslint-plugin": "workspace:*",
+    "@ts-safeql/plugin-slonik": "workspace:*"
+  }
+}

demos/plugin-slonik/src/index.ts

@@ -0,0 +1,206 @@
+import { createPool, sql } from "slonik";
+import { createPgDriverFactory } from "@slonik/pg-driver";
+import { z } from "zod";
+
+const pool = await createPool("postgres://", { driverFactory: createPgDriverFactory() });
+
+section("sql.type — Zod schema validates result", () => {
+  example("inline schema", () =>
+    pool.one(sql.type(z.object({ id: z.number(), version: z.string() }))`
+      SELECT oid::int4 AS id, typname::text AS version FROM pg_type LIMIT 1
+    `),
+  );
+
+  example("referenced schema variable", () => {
+    const TypeRow = z.object({ id: z.number(), version: z.string() });
+    pool.one(sql.type(TypeRow)`
+      SELECT oid::int4 AS id, typname::text AS version FROM pg_type LIMIT 1
+    `);
+  });
+
+  example("nullable column", () =>
+    pool.one(sql.type(z.object({ v: z.string().nullable() }))`SELECT NULL::text AS v`),
+  );
+
+  example("multiple columns with mixed types", () =>
+    pool.one(sql.type(z.object({ n: z.number(), s: z.string(), b: z.boolean() }))`
+      SELECT 1::int4 AS n, 'hello'::text AS s, true AS b
+    `),
+  );
+});
+
+section("sql.typeAlias — alias→schema is runtime-only", () => {
+  example("validates SQL but skips type annotations", () =>
+    pool.query(sql.typeAlias("id")`SELECT 1 AS id`),
+  );
+});
+
+section("sql.unsafe — opt-out of type checking", () => {
+  example("no type annotation needed", () => pool.query(sql.unsafe`SELECT 1`));
+});
+
+section("sql.identifier", () => {
+  example("single name", () =>
+    pool.query(sql.unsafe`SELECT typname::text FROM ${sql.identifier(["pg_type"])} LIMIT 1`),
+  );
+
+  example("schema-qualified", () =>
+    pool.one(sql.type(z.object({ oid: z.number() }))`
+      SELECT oid::int4 AS oid FROM ${sql.identifier(["pg_catalog", "pg_type"])} LIMIT 1
+    `),
+  );
+});
+
+section("sql.json / sql.jsonb", () => {
+  example("sql.json", () =>
+    pool.one(sql.type(z.object({ p: z.string().nullable() }))`
+      SELECT ${sql.json({ id: 1 })}::jsonb ->> 'id' AS p
+    `),
+  );
+
+  example("sql.jsonb", () =>
+    pool.one(sql.type(z.object({ p: z.string().nullable() }))`
+      SELECT ${sql.jsonb([1, 2, 3])}::jsonb ->> 0 AS p
+    `),
+  );
+});
+
+section("sql.binary", () => {
+  example("bytea parameter", () =>
+    pool.query(sql.unsafe`SELECT ${sql.binary(Buffer.from("foo"))}`),
+  );
+});
+
+section("sql.date / sql.timestamp / sql.interval", () => {
+  example("sql.date", () =>
+    pool.one(sql.type(z.object({ d: z.string().nullable() }))`
+      SELECT ${sql.date(new Date("2022-08-19T03:27:24.951Z"))}::text AS d
+    `),
+  );
+
+  example("sql.timestamp", () =>
+    pool.one(sql.type(z.object({ d: z.string().nullable() }))`
+      SELECT ${sql.timestamp(new Date("2022-08-19T03:27:24.951Z"))}::text AS d
+    `),
+  );
+
+  example("sql.interval", () =>
+    pool.one(sql.type(z.object({ i: z.string().nullable() }))`
+      SELECT ${sql.interval({ days: 3 })}::text AS i
+    `),
+  );
+});
+
+section("sql.uuid", () => {
+  example("uuid parameter", () =>
+    pool.one(sql.type(z.object({ u: z.string().nullable() }))`
+      SELECT ${sql.uuid("00000000-0000-0000-0000-000000000000")}::text AS u
+    `),
+  );
+});
+
+section("sql.array", () => {
+  example("typed array", () =>
+    pool.one(sql.type(z.object({ a: z.number().nullable() }))`
+      SELECT ${sql.array([1, 2, 3], "int4")} AS a
+    `),
+  );
+
+  example("ANY() pattern from README", () =>
+    pool.query(sql.typeAlias("id")`
+      SELECT oid::int4 AS id FROM pg_type
+      WHERE oid = ANY(${sql.array([1, 2, 3], "int4")})
+    `),
+  );
+});
+
+section("sql.join — too dynamic, query skipped", () => {
+  example("comma-separated values", () =>
+    pool.query(sql.unsafe`SELECT ${sql.join([1, 2, 3], sql.fragment`, `)}`),
+  );
+
+  example("boolean expressions", () =>
+    pool.query(sql.unsafe`SELECT ${sql.join([1, 2], sql.fragment` AND `)}`),
+  );
+
+  example("tuple list", () =>
+    pool.query(sql.unsafe`
+      SELECT ${sql.join(
+        [
+          sql.fragment`(${sql.join([1, 2], sql.fragment`, `)})`,
+          sql.fragment`(${sql.join([3, 4], sql.fragment`, `)})`,
+        ],
+        sql.fragment`, `,
+      )}
+    `),
+  );
+});
+
+section("sql.unnest — too dynamic, query skipped", () => {
+  example("bulk insert with string type names", () =>
+    pool.query(sql.unsafe`
+      SELECT bar, baz
+      FROM ${sql.unnest(
+        [
+          [1, "foo"],
+          [2, "bar"],
+        ],
+        ["int4", "text"],
+      )} AS foo(bar, baz)
+    `),
+  );
+});
+
+section("sql.literalValue — too dynamic, query skipped", () => {
+  example("raw literal interpolation", () =>
+    pool.query(sql.unsafe`SELECT ${sql.literalValue("foo")}`),
+  );
+});
+
+section("sql.fragment — composable pieces", () => {
+  example("standalone fragment (not linted)", () => {
+    sql.fragment`WHERE 1 = 1`;
+  });
+
+  example("fragment as expression (query skipped)", () => {
+    const where = sql.fragment`WHERE typname = ${"bool"}`;
+    pool.query(sql.unsafe`SELECT typname FROM pg_type ${where}`);
+  });
+
+  example("nested fragments", () => {
+    const cond = sql.fragment`typname = ${"bool"}`;
+    const where = sql.fragment`WHERE ${cond}`;
+    pool.query(sql.unsafe`SELECT typname FROM pg_type ${where}`);
+  });
+});
+
+section("value placeholders — plain variables", () => {
+  example("plain value becomes $N parameter", () => {
+    const name = "bool";
+    pool.query(sql.unsafe`SELECT typname FROM pg_type WHERE typname = ${name}`);
+  });
+});
+
+section("invalid cases SafeQL catches", () => {
+  example("bad column", () => {
+    // eslint-disable-next-line @ts-safeql/check-sql -- column "nonexistent" does not exist
+    pool.query(sql.unsafe`SELECT nonexistent FROM pg_type`);
+  });
+
+  example("bad table", () => {
+    // eslint-disable-next-line @ts-safeql/check-sql -- relation "nonexistent" does not exist
+    pool.query(sql.type(z.object({}))`SELECT 1 FROM nonexistent`);
+  });
+
+  example("wrong zod schema", () => {
+    // eslint-disable-next-line @ts-safeql/check-sql -- Expected: z.object({ id: z.number() })
+    pool.one(sql.type(z.object({ id: z.string() }))`SELECT 1::int4 AS id`);
+  });
+});
+
+function section(_: string, fn: () => void) {
+  fn();
+}
+function example(_: string, fn: () => void) {
+  fn();
+}

demos/plugin-slonik/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.node.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  }
+}

docs/compatibility/postgres.js.md

@@ -86,4 +86,4 @@ const query = sql`SELECT id FROM users`
 
 // After: ✅
 const query = sql<{ id: number; }[]>`SELECT id FROM users`
-```
+```