prisma-pg-toolkit 1.0.0

package/README.MD

@@ -0,0 +1,88 @@
+# prisma-pg-toolkit
+
+Joins (`INNER` / `LEFT` / `RIGHT` / `FULL OUTER` / `CROSS`) and locking (pessimistic / optimistic) helpers for **Prisma + PostgreSQL**.
+
+Prisma's client only performs `LEFT JOIN`-style relation loading internally, and has no built-in row locking. This library fills both gaps with safe, config-driven APIs — no raw SQL required from consumers.
+
+> **Postgres only.** Join syntax (`FULL OUTER JOIN`, `RIGHT JOIN`) and locking (`FOR UPDATE`) differ across databases — this library targets Postgres specifically.
+
+## Install
+
+```bash
+npm install prisma-pg-toolkit
+```
+
+Requires `@prisma/client` v5+ as a peer dependency.
+
+## Setup
+
+```ts
+import { PrismaClient } from '@prisma/client';
+import { withToolKit } from 'prisma-pg-toolkit';
+
+const base = new PrismaClient();
+const prisma = withToolKit(base);
+```
+
+## Joins
+
+```ts
+const result = await prisma.$join({
+  from: 'User',
+  select: ['User.email', 'Post.title'],
+  join: {
+    type: 'LEFT', // 'INNER' | 'LEFT' | 'RIGHT' | 'FULL OUTER' | 'CROSS'
+    table: 'Post',
+    on: { fromColumn: 'id', toColumn: 'userId' },
+  },
+  where: { column: 'published', op: '=', value: true }, // optional
+});
+```
+
+`CROSS` joins don't need an `on` clause.
+
+## Pessimistic locking
+
+Locks a row (`SELECT ... FOR UPDATE`) inside a transaction. Other callers requesting the same row **wait** until the transaction commits or rolls back.
+
+```ts
+await prisma.$lock.pessimistic(
+  { table: 'User', id: 1, mode: 'FOR UPDATE' }, // or 'FOR SHARE'
+  async (tx, row) => {
+    return tx.user.update({ where: { id: row.id }, data: { name: 'Updated' } });
+  }
+);
+```
+
+## Optimistic locking
+
+Requires a `version: Int` column on the model. Update succeeds only if `expectedVersion` still matches the current row; otherwise throws `OptimisticLockError`, and the caller should re-fetch and retry.
+
+```ts
+import { OptimisticLockError } from 'prisma-pg-toolkit';
+
+try {
+  await prisma.$lock.optimistic({
+    model: 'user', // matches your Prisma model accessor, lowercase
+    id: 1,
+    expectedVersion: 3,
+    data: { name: 'New Name' },
+  });
+} catch (err) {
+  if (err instanceof OptimisticLockError) {
+    // row changed since you read it — re-fetch and retry
+  }
+}
+```
+
+## Security
+
+Table and column names are validated against a strict identifier pattern before being spliced into SQL — only letters, digits, and underscores, matching Postgres' identifier rules. Values are always passed as parameterized bindings via Prisma's tagged-template `$queryRaw`, never string-concatenated.
+
+## Testing
+
+Manual test scripts demonstrating all join types and both locking strategies against seeded data are in [`src/testing`](./src/testing) on GitHub — useful as runnable examples.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,159 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  OptimisticLockError: () => OptimisticLockError,
+  buildJoinQuery: () => buildJoinQuery,
+  optimisticLockUpdate: () => optimisticLockUpdate,
+  pessimisticLock: () => pessimisticLock,
+  withToolKit: () => withToolKit
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/joins/JoinBuilder.ts
+var import_client = require("@prisma/client");
+
+// src/security/security.ts
+var IDENT_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var MAX_IDENTIFIER_LENGTH = 63;
+function validateSegment(segment) {
+  if (segment.length === 0) {
+    throw new Error("Identifier segment cannot be empty");
+  }
+  if (segment.length > MAX_IDENTIFIER_LENGTH) {
+    throw new Error(`Identifier "${segment}" exceeds ${MAX_IDENTIFIER_LENGTH} character limit(Postgres will silently truncate it)`);
+  }
+  if (!IDENT_RE.test(segment)) {
+    throw new Error(`Unsafe or invalid identifier: "${segment}"`);
+  }
+}
+function assertSafeIdentifier(name) {
+  validateSegment(name);
+  return name;
+}
+function assertSafeQualifiedIdentifier(name) {
+  const [core, ...rest] = name.split(/\s+as\s+/i);
+  if (rest.length > 1) {
+    throw new Error(`Invalid identifier expression: "${name}"`);
+  }
+  const segment = core.trim().split(".");
+  if (segment.length > 2) {
+    throw new Error(`Invalid identifier expression: "${name}"`);
+  }
+  segment.forEach(validateSegment);
+  if (rest.length === 1) {
+    validateSegment(rest[0].trim());
+  }
+  return name;
+}
+function quoteIdentifier(name) {
+  return `"${name}"`;
+}
+
+// src/joins/JoinBuilder.ts
+function buildJoinQuery(config) {
+  const fromTable = assertSafeIdentifier(config.from);
+  const selectCols = (config.select ?? ["*"]).map((c) => c === "*" ? c : assertSafeQualifiedIdentifier(c)).join(", ");
+  let query = import_client.Prisma.sql`SELECT ${import_client.Prisma.raw(selectCols)} FROM ${import_client.Prisma.raw(`"${quoteIdentifier(fromTable)}"`)}`;
+  if (config.join) {
+    const { type, table, on } = config.join;
+    const joinTable = assertSafeIdentifier(table);
+    if (type === "CROSS") {
+      query = import_client.Prisma.sql`${query} CROSS JOIN ${import_client.Prisma.raw(`"${quoteIdentifier(joinTable)}"`)}`;
+    } else {
+      if (!on) throw new Error(`on Condition is required for ${type} JOIN`);
+      const fromCol = assertSafeIdentifier(on.fromColumn);
+      const toCol = assertSafeIdentifier(on.toColumn);
+      query = import_client.Prisma.sql`${query} ${import_client.Prisma.raw(type)} JOIN ${import_client.Prisma.raw(`"${quoteIdentifier(joinTable)}"`)} ON ${import_client.Prisma.raw(`"${quoteIdentifier(fromTable)}"."${quoteIdentifier(fromCol)}"`)} = ${import_client.Prisma.raw(`"${quoteIdentifier(joinTable)}"."${quoteIdentifier(toCol)}"`)}`;
+    }
+  }
+  if (config.where) {
+    const col = assertSafeIdentifier(config.where.column);
+    const op = config.where.op;
+    query = import_client.Prisma.sql`${query} WHERE ${import_client.Prisma.raw(`"${quoteIdentifier(col)}"`)} ${import_client.Prisma.raw(op)} ${config.where.value}`;
+  }
+  return query;
+}
+
+// src/locking/passimisticLocking.ts
+var import_client2 = require("@prisma/client");
+async function pessimisticLock(prisma, config, fn) {
+  const table = assertSafeIdentifier(config.table);
+  const mode = config.mode ?? "FOR UPDATE";
+  return prisma.$transaction(
+    async (tx) => {
+      const rows = await tx.$queryRaw(
+        import_client2.Prisma.sql`SELECT * FROM ${import_client2.Prisma.raw(`${quoteIdentifier(table)}`)} WHERE id = ${config.id} ${import_client2.Prisma.raw(mode)}`
+      );
+      if (!rows.length) throw new Error(`Row not found in ${table} with id ${config.id}`);
+      return fn(tx, rows[0]);
+    },
+    { maxWait: config.maxWait ?? 5e3, timeout: config.timeout ?? 1e4 }
+  );
+}
+
+// src/locking/optimisticLocking.ts
+var OptimisticLockError = class extends Error {
+  constructor(message = "Row was modified by another transaction") {
+    super(message);
+    this.name = "OptimisticLockError";
+  }
+};
+async function optimisticLockUpdate(prisma, config) {
+  const client = prisma;
+  if (!client[config.model]) {
+    throw new Error(`Model "${config.model}" not found on Prisma client`);
+  }
+  const result = await client[config.model].updateMany({
+    where: { id: config.id, version: config.expectedVersion },
+    data: { ...config.data, version: { increment: 1 } }
+  });
+  if (result.count === 0) {
+    throw new OptimisticLockError();
+  }
+  return result;
+}
+
+// src/index.ts
+function withToolKit(prisma) {
+  return prisma.$extends({
+    name: "prisma-toolkit",
+    client: {
+      async $join(config) {
+        const sql = buildJoinQuery(config);
+        return prisma.$queryRaw(sql);
+      },
+      $lock: {
+        pessimistic: (config, fn) => pessimisticLock(prisma, config, fn),
+        optimistic: (config) => optimisticLockUpdate(prisma, config)
+      }
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OptimisticLockError,
+  buildJoinQuery,
+  optimisticLockUpdate,
+  pessimisticLock,
+  withToolKit
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/joins/JoinBuilder.ts","../src/security/security.ts","../src/locking/passimisticLocking.ts","../src/locking/optimisticLocking.ts"],"sourcesContent":["import { PrismaClient, Prisma } from \"@prisma/client\"\r\nimport { buildJoinQuery } from \"./joins/JoinBuilder\"\r\nimport { pessimisticLock } from \"./locking/passimisticLocking\"\r\nimport { optimisticLockUpdate } from \"./locking/optimisticLocking\"\r\n\r\n\r\nexport function withToolKit(\r\n    prisma: PrismaClient\r\n) {\r\n    return prisma.$extends({\r\n        name: \"prisma-toolkit\",\r\n        client: {\r\n            async $join(config: Parameters<typeof buildJoinQuery>[0]) {\r\n                const sql = buildJoinQuery(config)\r\n                return prisma.$queryRaw(sql)\r\n            },\r\n            $lock: {\r\n                pessimistic: (config: Parameters<typeof pessimisticLock>[1], fn: Parameters<typeof pessimisticLock>[2]) => pessimisticLock(prisma, config, fn),\r\n                optimistic: (config: Parameters<typeof optimisticLockUpdate>[1]) => optimisticLockUpdate(prisma, config)\r\n            }\r\n        }\r\n    })\r\n}\r\n\r\nexport { buildJoinQuery } from \"./joins/JoinBuilder\"\r\nexport { pessimisticLock } from \"./locking/passimisticLocking\"\r\nexport { optimisticLockUpdate, OptimisticLockError } from \"./locking/optimisticLocking\"\r\nexport type { JoinType } from \"./joins/JoinBuilder\"","import { Prisma } from \"@prisma/client\"\r\nimport { assertSafeIdentifier, assertSafeQualifiedIdentifier, quoteIdentifier } from \"../security/security\"\r\n\r\nexport type JoinType = \"INNER\" | \"LEFT\" | \"RIGHT\" | \"FULL OUTER\" | \"CROSS\"\r\n\r\ninterface JoinCondition {\r\n    fromColumn: string\r\n    toColumn: string\r\n}\r\n\r\ninterface JoinConfig {\r\n    from: string\r\n    select?: string[]\r\n    join?: {\r\n        type: JoinType,\r\n        table: string,\r\n        on?: JoinCondition\r\n    }\r\n    where?: {\r\n        column: string\r\n        op: '=' | '!=' | '>' | '<' | '>=' | '<=';\r\n        value: any\r\n    }\r\n}\r\n\r\n\r\nexport function buildJoinQuery(config: JoinConfig): Prisma.Sql {\r\n    const fromTable = assertSafeIdentifier(config.from)\r\n    const selectCols = (config.select ?? ['*']).map((c) => (c === '*' ? c : assertSafeQualifiedIdentifier(c))).join(', ')\r\n    let query = Prisma.sql`SELECT ${Prisma.raw(selectCols)} FROM ${Prisma.raw(`\"${quoteIdentifier(fromTable)}\"`)}`;\r\n    if (config.join) {\r\n        const { type, table, on } = config.join\r\n        const joinTable = assertSafeIdentifier(table)\r\n        if (type === \"CROSS\") {\r\n            query = Prisma.sql`${query} CROSS JOIN ${Prisma.raw(`\"${quoteIdentifier(joinTable)}\"`)}`;\r\n        }\r\n        else {\r\n            if (!on) throw new Error(`on Condition is required for ${type} JOIN`)\r\n            const fromCol = assertSafeIdentifier(on.fromColumn)\r\n            const toCol = assertSafeIdentifier(on.toColumn)\r\n            query = Prisma.sql`${query} ${Prisma.raw(type)} JOIN ${Prisma.raw(`\"${quoteIdentifier(joinTable)}\"`)} ON ${Prisma.raw(`\"${quoteIdentifier(fromTable)}\".\"${quoteIdentifier(fromCol)}\"`)} = ${Prisma.raw(`\"${quoteIdentifier(joinTable)}\".\"${quoteIdentifier(toCol)}\"`)}`;\r\n        }\r\n    }\r\n    if (config.where) {\r\n        const col = assertSafeIdentifier(config.where.column)\r\n        const op = config.where.op\r\n        query = Prisma.sql`${query} WHERE ${Prisma.raw(`\"${quoteIdentifier(col)}\"`)} ${Prisma.raw(op)} ${config.where.value}`\r\n    }\r\n    return query\r\n}\r\n\r\n\r\n","const IDENT_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;\r\nconst MAX_IDENTIFIER_LENGTH = 63\r\n\r\nfunction validateSegment(segment: string): void {\r\n    if (segment.length === 0) {\r\n        throw new Error(\"Identifier segment cannot be empty\")\r\n    }\r\n    if (segment.length > MAX_IDENTIFIER_LENGTH) {\r\n        throw new Error(`Identifier \"${segment}\" exceeds ${MAX_IDENTIFIER_LENGTH} character limit(Postgres will silently truncate it)`)\r\n    }\r\n    if (!IDENT_RE.test(segment)) {\r\n        throw new Error(`Unsafe or invalid identifier: \"${segment}\"`)\r\n    }\r\n}\r\n\r\nexport function assertSafeIdentifier(name: string): string {\r\n    validateSegment(name)\r\n    return name\r\n}\r\n\r\nexport function assertSafeQualifiedIdentifier(name: string): string {\r\n    const [core, ...rest] = name.split(/\\s+as\\s+/i)\r\n    if (rest.length > 1) {\r\n        throw new Error(`Invalid identifier expression: \"${name}\"`)\r\n    }\r\n    const segment = core.trim().split(\".\")\r\n    if (segment.length > 2) {\r\n        throw new Error(`Invalid identifier expression: \"${name}\"`)\r\n    }\r\n    segment.forEach(validateSegment)\r\n\r\n    if (rest.length === 1) {\r\n        validateSegment(rest[0].trim())\r\n    }\r\n    return name\r\n}\r\n\r\nexport function quoteIdentifier(name: string): string {\r\n    return `\"${name}\"`\r\n}","import { Prisma, PrismaClient } from \"@prisma/client\"\r\nimport { assertSafeIdentifier, quoteIdentifier } from \"../security/security\"\r\n\r\ninterface PessimisticLockConfig {\r\n    table: string\r\n    id: string | number\r\n    mode?: \"FOR UPDATE\" | \"FOR SHARE\"\r\n    maxWait?: number\r\n    timeout?: number\r\n\r\n}\r\n\r\nexport async function pessimisticLock<T>(\r\n    prisma: PrismaClient,\r\n    config: PessimisticLockConfig,\r\n    fn: (tx: Prisma.TransactionClient, row: any) => Promise<T>\r\n): Promise<T> {\r\n    const table = assertSafeIdentifier(config.table)\r\n    const mode = config.mode ?? \"FOR UPDATE\"\r\n    return prisma.$transaction(async (tx) => {\r\n        const rows: any[] = await tx.$queryRaw(\r\n            Prisma.sql`SELECT * FROM ${Prisma.raw(`${quoteIdentifier(table)}`)} WHERE id = ${config.id} ${Prisma.raw(mode)}`\r\n        )\r\n        if (!rows.length) throw new Error(`Row not found in ${table} with id ${config.id}`)\r\n        return fn(tx, rows[0])\r\n    },\r\n        { maxWait: config.maxWait ?? 5000, timeout: config.timeout ?? 10000 }\r\n    )\r\n}","import { PrismaClient } from \"@prisma/client\";\r\n\r\nexport class OptimisticLockError extends Error {\r\n    constructor(message = \"Row was modified by another transaction\") {\r\n        super(message)\r\n        this.name = \"OptimisticLockError\"\r\n    }\r\n}\r\n\r\ninterface OptimisticLockConfig {\r\n    model: string\r\n    id: number\r\n    expectedVersion: number\r\n    data: Record<string, any>\r\n}\r\n\r\nexport async function optimisticLockUpdate(\r\n    prisma: PrismaClient,\r\n    config: OptimisticLockConfig\r\n) {\r\n    const client = prisma as any\r\n    if (!client[config.model]) {\r\n        throw new Error(`Model \"${config.model}\" not found on Prisma client`)\r\n    }\r\n    const result = await client[config.model].updateMany({\r\n        where: { id: config.id, version: config.expectedVersion },\r\n        data: { ...config.data, version: { increment: 1 } }\r\n    })\r\n    if (result.count === 0) {\r\n        throw new OptimisticLockError()\r\n    }\r\n    return result\r\n}"],"mappings":"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","names":["import_client"]}

package/dist/index.d.cts

@@ -0,0 +1,69 @@
+import * as _prisma_client_runtime_library from '@prisma/client/runtime/library';
+import { Prisma, PrismaClient } from '@prisma/client';
+
+type JoinType = "INNER" | "LEFT" | "RIGHT" | "FULL OUTER" | "CROSS";
+interface JoinCondition {
+    fromColumn: string;
+    toColumn: string;
+}
+interface JoinConfig {
+    from: string;
+    select?: string[];
+    join?: {
+        type: JoinType;
+        table: string;
+        on?: JoinCondition;
+    };
+    where?: {
+        column: string;
+        op: '=' | '!=' | '>' | '<' | '>=' | '<=';
+        value: any;
+    };
+}
+declare function buildJoinQuery(config: JoinConfig): Prisma.Sql;
+
+interface PessimisticLockConfig {
+    table: string;
+    id: string | number;
+    mode?: "FOR UPDATE" | "FOR SHARE";
+    maxWait?: number;
+    timeout?: number;
+}
+declare function pessimisticLock<T>(prisma: PrismaClient, config: PessimisticLockConfig, fn: (tx: Prisma.TransactionClient, row: any) => Promise<T>): Promise<T>;
+
+declare class OptimisticLockError extends Error {
+    constructor(message?: string);
+}
+interface OptimisticLockConfig {
+    model: string;
+    id: number;
+    expectedVersion: number;
+    data: Record<string, any>;
+}
+declare function optimisticLockUpdate(prisma: PrismaClient, config: OptimisticLockConfig): Promise<any>;
+
+declare function withToolKit(prisma: PrismaClient): _prisma_client_runtime_library.DynamicClientExtensionThis<Prisma.TypeMap<_prisma_client_runtime_library.InternalArgs & {
+    result: {};
+    model: {};
+    query: {};
+    client: {
+        $join: () => (config: Parameters<typeof buildJoinQuery>[0]) => Promise<unknown>;
+        $lock: () => {
+            pessimistic: (config: Parameters<typeof pessimisticLock>[1], fn: Parameters<typeof pessimisticLock>[2]) => Promise<unknown>;
+            optimistic: (config: Parameters<typeof optimisticLockUpdate>[1]) => Promise<any>;
+        };
+    };
+}, {}>, Prisma.TypeMapCb<Prisma.PrismaClientOptions>, {
+    result: {};
+    model: {};
+    query: {};
+    client: {
+        $join: () => (config: Parameters<typeof buildJoinQuery>[0]) => Promise<unknown>;
+        $lock: () => {
+            pessimistic: (config: Parameters<typeof pessimisticLock>[1], fn: Parameters<typeof pessimisticLock>[2]) => Promise<unknown>;
+            optimistic: (config: Parameters<typeof optimisticLockUpdate>[1]) => Promise<any>;
+        };
+    };
+}>;
+
+export { type JoinType, OptimisticLockError, buildJoinQuery, optimisticLockUpdate, pessimisticLock, withToolKit };

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import * as _prisma_client_runtime_library from '@prisma/client/runtime/library';
+import { Prisma, PrismaClient } from '@prisma/client';
+
+type JoinType = "INNER" | "LEFT" | "RIGHT" | "FULL OUTER" | "CROSS";
+interface JoinCondition {
+    fromColumn: string;
+    toColumn: string;
+}
+interface JoinConfig {
+    from: string;
+    select?: string[];
+    join?: {
+        type: JoinType;
+        table: string;
+        on?: JoinCondition;
+    };
+    where?: {
+        column: string;
+        op: '=' | '!=' | '>' | '<' | '>=' | '<=';
+        value: any;
+    };
+}
+declare function buildJoinQuery(config: JoinConfig): Prisma.Sql;
+
+interface PessimisticLockConfig {
+    table: string;
+    id: string | number;
+    mode?: "FOR UPDATE" | "FOR SHARE";
+    maxWait?: number;
+    timeout?: number;
+}
+declare function pessimisticLock<T>(prisma: PrismaClient, config: PessimisticLockConfig, fn: (tx: Prisma.TransactionClient, row: any) => Promise<T>): Promise<T>;
+
+declare class OptimisticLockError extends Error {
+    constructor(message?: string);
+}
+interface OptimisticLockConfig {
+    model: string;
+    id: number;
+    expectedVersion: number;
+    data: Record<string, any>;
+}
+declare function optimisticLockUpdate(prisma: PrismaClient, config: OptimisticLockConfig): Promise<any>;
+
+declare function withToolKit(prisma: PrismaClient): _prisma_client_runtime_library.DynamicClientExtensionThis<Prisma.TypeMap<_prisma_client_runtime_library.InternalArgs & {
+    result: {};
+    model: {};
+    query: {};
+    client: {
+        $join: () => (config: Parameters<typeof buildJoinQuery>[0]) => Promise<unknown>;
+        $lock: () => {
+            pessimistic: (config: Parameters<typeof pessimisticLock>[1], fn: Parameters<typeof pessimisticLock>[2]) => Promise<unknown>;
+            optimistic: (config: Parameters<typeof optimisticLockUpdate>[1]) => Promise<any>;
+        };
+    };
+}, {}>, Prisma.TypeMapCb<Prisma.PrismaClientOptions>, {
+    result: {};
+    model: {};
+    query: {};
+    client: {
+        $join: () => (config: Parameters<typeof buildJoinQuery>[0]) => Promise<unknown>;
+        $lock: () => {
+            pessimistic: (config: Parameters<typeof pessimisticLock>[1], fn: Parameters<typeof pessimisticLock>[2]) => Promise<unknown>;
+            optimistic: (config: Parameters<typeof optimisticLockUpdate>[1]) => Promise<any>;
+        };
+    };
+}>;
+
+export { type JoinType, OptimisticLockError, buildJoinQuery, optimisticLockUpdate, pessimisticLock, withToolKit };

package/dist/index.js

@@ -0,0 +1,128 @@
+// src/joins/JoinBuilder.ts
+import { Prisma } from "@prisma/client";
+
+// src/security/security.ts
+var IDENT_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var MAX_IDENTIFIER_LENGTH = 63;
+function validateSegment(segment) {
+  if (segment.length === 0) {
+    throw new Error("Identifier segment cannot be empty");
+  }
+  if (segment.length > MAX_IDENTIFIER_LENGTH) {
+    throw new Error(`Identifier "${segment}" exceeds ${MAX_IDENTIFIER_LENGTH} character limit(Postgres will silently truncate it)`);
+  }
+  if (!IDENT_RE.test(segment)) {
+    throw new Error(`Unsafe or invalid identifier: "${segment}"`);
+  }
+}
+function assertSafeIdentifier(name) {
+  validateSegment(name);
+  return name;
+}
+function assertSafeQualifiedIdentifier(name) {
+  const [core, ...rest] = name.split(/\s+as\s+/i);
+  if (rest.length > 1) {
+    throw new Error(`Invalid identifier expression: "${name}"`);
+  }
+  const segment = core.trim().split(".");
+  if (segment.length > 2) {
+    throw new Error(`Invalid identifier expression: "${name}"`);
+  }
+  segment.forEach(validateSegment);
+  if (rest.length === 1) {
+    validateSegment(rest[0].trim());
+  }
+  return name;
+}
+function quoteIdentifier(name) {
+  return `"${name}"`;
+}
+
+// src/joins/JoinBuilder.ts
+function buildJoinQuery(config) {
+  const fromTable = assertSafeIdentifier(config.from);
+  const selectCols = (config.select ?? ["*"]).map((c) => c === "*" ? c : assertSafeQualifiedIdentifier(c)).join(", ");
+  let query = Prisma.sql`SELECT ${Prisma.raw(selectCols)} FROM ${Prisma.raw(`"${quoteIdentifier(fromTable)}"`)}`;
+  if (config.join) {
+    const { type, table, on } = config.join;
+    const joinTable = assertSafeIdentifier(table);
+    if (type === "CROSS") {
+      query = Prisma.sql`${query} CROSS JOIN ${Prisma.raw(`"${quoteIdentifier(joinTable)}"`)}`;
+    } else {
+      if (!on) throw new Error(`on Condition is required for ${type} JOIN`);
+      const fromCol = assertSafeIdentifier(on.fromColumn);
+      const toCol = assertSafeIdentifier(on.toColumn);
+      query = Prisma.sql`${query} ${Prisma.raw(type)} JOIN ${Prisma.raw(`"${quoteIdentifier(joinTable)}"`)} ON ${Prisma.raw(`"${quoteIdentifier(fromTable)}"."${quoteIdentifier(fromCol)}"`)} = ${Prisma.raw(`"${quoteIdentifier(joinTable)}"."${quoteIdentifier(toCol)}"`)}`;
+    }
+  }
+  if (config.where) {
+    const col = assertSafeIdentifier(config.where.column);
+    const op = config.where.op;
+    query = Prisma.sql`${query} WHERE ${Prisma.raw(`"${quoteIdentifier(col)}"`)} ${Prisma.raw(op)} ${config.where.value}`;
+  }
+  return query;
+}
+
+// src/locking/passimisticLocking.ts
+import { Prisma as Prisma2 } from "@prisma/client";
+async function pessimisticLock(prisma, config, fn) {
+  const table = assertSafeIdentifier(config.table);
+  const mode = config.mode ?? "FOR UPDATE";
+  return prisma.$transaction(
+    async (tx) => {
+      const rows = await tx.$queryRaw(
+        Prisma2.sql`SELECT * FROM ${Prisma2.raw(`${quoteIdentifier(table)}`)} WHERE id = ${config.id} ${Prisma2.raw(mode)}`
+      );
+      if (!rows.length) throw new Error(`Row not found in ${table} with id ${config.id}`);
+      return fn(tx, rows[0]);
+    },
+    { maxWait: config.maxWait ?? 5e3, timeout: config.timeout ?? 1e4 }
+  );
+}
+
+// src/locking/optimisticLocking.ts
+var OptimisticLockError = class extends Error {
+  constructor(message = "Row was modified by another transaction") {
+    super(message);
+    this.name = "OptimisticLockError";
+  }
+};
+async function optimisticLockUpdate(prisma, config) {
+  const client = prisma;
+  if (!client[config.model]) {
+    throw new Error(`Model "${config.model}" not found on Prisma client`);
+  }
+  const result = await client[config.model].updateMany({
+    where: { id: config.id, version: config.expectedVersion },
+    data: { ...config.data, version: { increment: 1 } }
+  });
+  if (result.count === 0) {
+    throw new OptimisticLockError();
+  }
+  return result;
+}
+
+// src/index.ts
+function withToolKit(prisma) {
+  return prisma.$extends({
+    name: "prisma-toolkit",
+    client: {
+      async $join(config) {
+        const sql = buildJoinQuery(config);
+        return prisma.$queryRaw(sql);
+      },
+      $lock: {
+        pessimistic: (config, fn) => pessimisticLock(prisma, config, fn),
+        optimistic: (config) => optimisticLockUpdate(prisma, config)
+      }
+    }
+  });
+}
+export {
+  OptimisticLockError,
+  buildJoinQuery,
+  optimisticLockUpdate,
+  pessimisticLock,
+  withToolKit
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/joins/JoinBuilder.ts","../src/security/security.ts","../src/locking/passimisticLocking.ts","../src/locking/optimisticLocking.ts","../src/index.ts"],"sourcesContent":["import { Prisma } from \"@prisma/client\"\r\nimport { assertSafeIdentifier, assertSafeQualifiedIdentifier, quoteIdentifier } from \"../security/security\"\r\n\r\nexport type JoinType = \"INNER\" | \"LEFT\" | \"RIGHT\" | \"FULL OUTER\" | \"CROSS\"\r\n\r\ninterface JoinCondition {\r\n    fromColumn: string\r\n    toColumn: string\r\n}\r\n\r\ninterface JoinConfig {\r\n    from: string\r\n    select?: string[]\r\n    join?: {\r\n        type: JoinType,\r\n        table: string,\r\n        on?: JoinCondition\r\n    }\r\n    where?: {\r\n        column: string\r\n        op: '=' | '!=' | '>' | '<' | '>=' | '<=';\r\n        value: any\r\n    }\r\n}\r\n\r\n\r\nexport function buildJoinQuery(config: JoinConfig): Prisma.Sql {\r\n    const fromTable = assertSafeIdentifier(config.from)\r\n    const selectCols = (config.select ?? ['*']).map((c) => (c === '*' ? c : assertSafeQualifiedIdentifier(c))).join(', ')\r\n    let query = Prisma.sql`SELECT ${Prisma.raw(selectCols)} FROM ${Prisma.raw(`\"${quoteIdentifier(fromTable)}\"`)}`;\r\n    if (config.join) {\r\n        const { type, table, on } = config.join\r\n        const joinTable = assertSafeIdentifier(table)\r\n        if (type === \"CROSS\") {\r\n            query = Prisma.sql`${query} CROSS JOIN ${Prisma.raw(`\"${quoteIdentifier(joinTable)}\"`)}`;\r\n        }\r\n        else {\r\n            if (!on) throw new Error(`on Condition is required for ${type} JOIN`)\r\n            const fromCol = assertSafeIdentifier(on.fromColumn)\r\n            const toCol = assertSafeIdentifier(on.toColumn)\r\n            query = Prisma.sql`${query} ${Prisma.raw(type)} JOIN ${Prisma.raw(`\"${quoteIdentifier(joinTable)}\"`)} ON ${Prisma.raw(`\"${quoteIdentifier(fromTable)}\".\"${quoteIdentifier(fromCol)}\"`)} = ${Prisma.raw(`\"${quoteIdentifier(joinTable)}\".\"${quoteIdentifier(toCol)}\"`)}`;\r\n        }\r\n    }\r\n    if (config.where) {\r\n        const col = assertSafeIdentifier(config.where.column)\r\n        const op = config.where.op\r\n        query = Prisma.sql`${query} WHERE ${Prisma.raw(`\"${quoteIdentifier(col)}\"`)} ${Prisma.raw(op)} ${config.where.value}`\r\n    }\r\n    return query\r\n}\r\n\r\n\r\n","const IDENT_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;\r\nconst MAX_IDENTIFIER_LENGTH = 63\r\n\r\nfunction validateSegment(segment: string): void {\r\n    if (segment.length === 0) {\r\n        throw new Error(\"Identifier segment cannot be empty\")\r\n    }\r\n    if (segment.length > MAX_IDENTIFIER_LENGTH) {\r\n        throw new Error(`Identifier \"${segment}\" exceeds ${MAX_IDENTIFIER_LENGTH} character limit(Postgres will silently truncate it)`)\r\n    }\r\n    if (!IDENT_RE.test(segment)) {\r\n        throw new Error(`Unsafe or invalid identifier: \"${segment}\"`)\r\n    }\r\n}\r\n\r\nexport function assertSafeIdentifier(name: string): string {\r\n    validateSegment(name)\r\n    return name\r\n}\r\n\r\nexport function assertSafeQualifiedIdentifier(name: string): string {\r\n    const [core, ...rest] = name.split(/\\s+as\\s+/i)\r\n    if (rest.length > 1) {\r\n        throw new Error(`Invalid identifier expression: \"${name}\"`)\r\n    }\r\n    const segment = core.trim().split(\".\")\r\n    if (segment.length > 2) {\r\n        throw new Error(`Invalid identifier expression: \"${name}\"`)\r\n    }\r\n    segment.forEach(validateSegment)\r\n\r\n    if (rest.length === 1) {\r\n        validateSegment(rest[0].trim())\r\n    }\r\n    return name\r\n}\r\n\r\nexport function quoteIdentifier(name: string): string {\r\n    return `\"${name}\"`\r\n}","import { Prisma, PrismaClient } from \"@prisma/client\"\r\nimport { assertSafeIdentifier, quoteIdentifier } from \"../security/security\"\r\n\r\ninterface PessimisticLockConfig {\r\n    table: string\r\n    id: string | number\r\n    mode?: \"FOR UPDATE\" | \"FOR SHARE\"\r\n    maxWait?: number\r\n    timeout?: number\r\n\r\n}\r\n\r\nexport async function pessimisticLock<T>(\r\n    prisma: PrismaClient,\r\n    config: PessimisticLockConfig,\r\n    fn: (tx: Prisma.TransactionClient, row: any) => Promise<T>\r\n): Promise<T> {\r\n    const table = assertSafeIdentifier(config.table)\r\n    const mode = config.mode ?? \"FOR UPDATE\"\r\n    return prisma.$transaction(async (tx) => {\r\n        const rows: any[] = await tx.$queryRaw(\r\n            Prisma.sql`SELECT * FROM ${Prisma.raw(`${quoteIdentifier(table)}`)} WHERE id = ${config.id} ${Prisma.raw(mode)}`\r\n        )\r\n        if (!rows.length) throw new Error(`Row not found in ${table} with id ${config.id}`)\r\n        return fn(tx, rows[0])\r\n    },\r\n        { maxWait: config.maxWait ?? 5000, timeout: config.timeout ?? 10000 }\r\n    )\r\n}","import { PrismaClient } from \"@prisma/client\";\r\n\r\nexport class OptimisticLockError extends Error {\r\n    constructor(message = \"Row was modified by another transaction\") {\r\n        super(message)\r\n        this.name = \"OptimisticLockError\"\r\n    }\r\n}\r\n\r\ninterface OptimisticLockConfig {\r\n    model: string\r\n    id: number\r\n    expectedVersion: number\r\n    data: Record<string, any>\r\n}\r\n\r\nexport async function optimisticLockUpdate(\r\n    prisma: PrismaClient,\r\n    config: OptimisticLockConfig\r\n) {\r\n    const client = prisma as any\r\n    if (!client[config.model]) {\r\n        throw new Error(`Model \"${config.model}\" not found on Prisma client`)\r\n    }\r\n    const result = await client[config.model].updateMany({\r\n        where: { id: config.id, version: config.expectedVersion },\r\n        data: { ...config.data, version: { increment: 1 } }\r\n    })\r\n    if (result.count === 0) {\r\n        throw new OptimisticLockError()\r\n    }\r\n    return result\r\n}","import { PrismaClient, Prisma } from \"@prisma/client\"\r\nimport { buildJoinQuery } from \"./joins/JoinBuilder\"\r\nimport { pessimisticLock } from \"./locking/passimisticLocking\"\r\nimport { optimisticLockUpdate } from \"./locking/optimisticLocking\"\r\n\r\n\r\nexport function withToolKit(\r\n    prisma: PrismaClient\r\n) {\r\n    return prisma.$extends({\r\n        name: \"prisma-toolkit\",\r\n        client: {\r\n            async $join(config: Parameters<typeof buildJoinQuery>[0]) {\r\n                const sql = buildJoinQuery(config)\r\n                return prisma.$queryRaw(sql)\r\n            },\r\n            $lock: {\r\n                pessimistic: (config: Parameters<typeof pessimisticLock>[1], fn: Parameters<typeof pessimisticLock>[2]) => pessimisticLock(prisma, config, fn),\r\n                optimistic: (config: Parameters<typeof optimisticLockUpdate>[1]) => optimisticLockUpdate(prisma, config)\r\n            }\r\n        }\r\n    })\r\n}\r\n\r\nexport { buildJoinQuery } from \"./joins/JoinBuilder\"\r\nexport { pessimisticLock } from \"./locking/passimisticLocking\"\r\nexport { optimisticLockUpdate, OptimisticLockError } from \"./locking/optimisticLocking\"\r\nexport type { JoinType } from \"./joins/JoinBuilder\""],"mappings":"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","names":["Prisma","Prisma"]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "prisma-pg-toolkit",
+  "version": "1.0.0",
+  "description": "Joins (INNER/LEFT/RIGHT/FULL OUTER/CROSS) and locking (pessimistic/optimistic) helpers for Prisma",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "dev": "tsx src/testing/test-joins.ts",
+    "prisma:migrate": "npx prisma migrate dev --name init",
+    "prisma:generate": "npx prisma generate",
+    "seed": "tsx prisma/seed.ts",
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "prisma",
+    "joins",
+    "locking",
+    "optimistic-locking",
+    "pessimistic-locking"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "@prisma/client": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@prisma/client": "^6.19.3",
+    "prisma": "^6.19.3",
+    "ts-node": "^10.9.2",
+    "ts-node-dev": "^2.0.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+import { PrismaClient, Prisma } from "@prisma/client"
+import { buildJoinQuery } from "./joins/JoinBuilder"
+import { pessimisticLock } from "./locking/passimisticLocking"
+import { optimisticLockUpdate } from "./locking/optimisticLocking"
+
+
+export function withToolKit(
+    prisma: PrismaClient
+) {
+    return prisma.$extends({
+        name: "prisma-toolkit",
+        client: {
+            async $join(config: Parameters<typeof buildJoinQuery>[0]) {
+                const sql = buildJoinQuery(config)
+                return prisma.$queryRaw(sql)
+            },
+            $lock: {
+                pessimistic: (config: Parameters<typeof pessimisticLock>[1], fn: Parameters<typeof pessimisticLock>[2]) => pessimisticLock(prisma, config, fn),
+                optimistic: (config: Parameters<typeof optimisticLockUpdate>[1]) => optimisticLockUpdate(prisma, config)
+            }
+        }
+    })
+}
+
+export { buildJoinQuery } from "./joins/JoinBuilder"
+export { pessimisticLock } from "./locking/passimisticLocking"
+export { optimisticLockUpdate, OptimisticLockError } from "./locking/optimisticLocking"
+export type { JoinType } from "./joins/JoinBuilder"

package/src/joins/JoinBuilder.ts

@@ -0,0 +1,52 @@
+import { Prisma } from "@prisma/client"
+import { assertSafeIdentifier, assertSafeQualifiedIdentifier, quoteIdentifier } from "../security/security"
+
+export type JoinType = "INNER" | "LEFT" | "RIGHT" | "FULL OUTER" | "CROSS"
+
+interface JoinCondition {
+    fromColumn: string
+    toColumn: string
+}
+
+interface JoinConfig {
+    from: string
+    select?: string[]
+    join?: {
+        type: JoinType,
+        table: string,
+        on?: JoinCondition
+    }
+    where?: {
+        column: string
+        op: '=' | '!=' | '>' | '<' | '>=' | '<=';
+        value: any
+    }
+}
+
+
+export function buildJoinQuery(config: JoinConfig): Prisma.Sql {
+    const fromTable = assertSafeIdentifier(config.from)
+    const selectCols = (config.select ?? ['*']).map((c) => (c === '*' ? c : assertSafeQualifiedIdentifier(c))).join(', ')
+    let query = Prisma.sql`SELECT ${Prisma.raw(selectCols)} FROM ${Prisma.raw(`"${quoteIdentifier(fromTable)}"`)}`;
+    if (config.join) {
+        const { type, table, on } = config.join
+        const joinTable = assertSafeIdentifier(table)
+        if (type === "CROSS") {
+            query = Prisma.sql`${query} CROSS JOIN ${Prisma.raw(`"${quoteIdentifier(joinTable)}"`)}`;
+        }
+        else {
+            if (!on) throw new Error(`on Condition is required for ${type} JOIN`)
+            const fromCol = assertSafeIdentifier(on.fromColumn)
+            const toCol = assertSafeIdentifier(on.toColumn)
+            query = Prisma.sql`${query} ${Prisma.raw(type)} JOIN ${Prisma.raw(`"${quoteIdentifier(joinTable)}"`)} ON ${Prisma.raw(`"${quoteIdentifier(fromTable)}"."${quoteIdentifier(fromCol)}"`)} = ${Prisma.raw(`"${quoteIdentifier(joinTable)}"."${quoteIdentifier(toCol)}"`)}`;
+        }
+    }
+    if (config.where) {
+        const col = assertSafeIdentifier(config.where.column)
+        const op = config.where.op
+        query = Prisma.sql`${query} WHERE ${Prisma.raw(`"${quoteIdentifier(col)}"`)} ${Prisma.raw(op)} ${config.where.value}`
+    }
+    return query
+}
+
+

package/src/locking/optimisticLocking.ts

@@ -0,0 +1,33 @@
+import { PrismaClient } from "@prisma/client";
+
+export class OptimisticLockError extends Error {
+    constructor(message = "Row was modified by another transaction") {
+        super(message)
+        this.name = "OptimisticLockError"
+    }
+}
+
+interface OptimisticLockConfig {
+    model: string
+    id: number
+    expectedVersion: number
+    data: Record<string, any>
+}
+
+export async function optimisticLockUpdate(
+    prisma: PrismaClient,
+    config: OptimisticLockConfig
+) {
+    const client = prisma as any
+    if (!client[config.model]) {
+        throw new Error(`Model "${config.model}" not found on Prisma client`)
+    }
+    const result = await client[config.model].updateMany({
+        where: { id: config.id, version: config.expectedVersion },
+        data: { ...config.data, version: { increment: 1 } }
+    })
+    if (result.count === 0) {
+        throw new OptimisticLockError()
+    }
+    return result
+}

package/src/locking/passimisticLocking.ts

@@ -0,0 +1,29 @@
+import { Prisma, PrismaClient } from "@prisma/client"
+import { assertSafeIdentifier, quoteIdentifier } from "../security/security"
+
+interface PessimisticLockConfig {
+    table: string
+    id: string | number
+    mode?: "FOR UPDATE" | "FOR SHARE"
+    maxWait?: number
+    timeout?: number
+
+}
+
+export async function pessimisticLock<T>(
+    prisma: PrismaClient,
+    config: PessimisticLockConfig,
+    fn: (tx: Prisma.TransactionClient, row: any) => Promise<T>
+): Promise<T> {
+    const table = assertSafeIdentifier(config.table)
+    const mode = config.mode ?? "FOR UPDATE"
+    return prisma.$transaction(async (tx) => {
+        const rows: any[] = await tx.$queryRaw(
+            Prisma.sql`SELECT * FROM ${Prisma.raw(`${quoteIdentifier(table)}`)} WHERE id = ${config.id} ${Prisma.raw(mode)}`
+        )
+        if (!rows.length) throw new Error(`Row not found in ${table} with id ${config.id}`)
+        return fn(tx, rows[0])
+    },
+        { maxWait: config.maxWait ?? 5000, timeout: config.timeout ?? 10000 }
+    )
+}

package/src/security/security.ts

@@ -0,0 +1,40 @@
+const IDENT_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const MAX_IDENTIFIER_LENGTH = 63
+
+function validateSegment(segment: string): void {
+    if (segment.length === 0) {
+        throw new Error("Identifier segment cannot be empty")
+    }
+    if (segment.length > MAX_IDENTIFIER_LENGTH) {
+        throw new Error(`Identifier "${segment}" exceeds ${MAX_IDENTIFIER_LENGTH} character limit(Postgres will silently truncate it)`)
+    }
+    if (!IDENT_RE.test(segment)) {
+        throw new Error(`Unsafe or invalid identifier: "${segment}"`)
+    }
+}
+
+export function assertSafeIdentifier(name: string): string {
+    validateSegment(name)
+    return name
+}
+
+export function assertSafeQualifiedIdentifier(name: string): string {
+    const [core, ...rest] = name.split(/\s+as\s+/i)
+    if (rest.length > 1) {
+        throw new Error(`Invalid identifier expression: "${name}"`)
+    }
+    const segment = core.trim().split(".")
+    if (segment.length > 2) {
+        throw new Error(`Invalid identifier expression: "${name}"`)
+    }
+    segment.forEach(validateSegment)
+
+    if (rest.length === 1) {
+        validateSegment(rest[0].trim())
+    }
+    return name
+}
+
+export function quoteIdentifier(name: string): string {
+    return `"${name}"`
+}

package/src/testing/seed-joins.ts

@@ -0,0 +1,21 @@
+import { Prisma, PrismaClient } from "@prisma/client"
+
+const prisma = new PrismaClient()
+
+
+async function runJoin(label: string, sql: Prisma.Sql) {
+    const rows = await prisma.$queryRaw(sql)
+    console.log(`\n--- ${label} (${(rows as any[]).length} rows) ---`)
+    console.table(rows)
+}
+
+async function main() {
+    await runJoin("INNER JOIN (expect 3)", Prisma.sql`SELECT u.email, p.title FROM "User" u INNER JOIN "Post" p ON p."userId" = u.id`)
+    await runJoin("LEFT JOIN (expect 4, + TOM)", Prisma.sql`SELECT u.email, p.title FROM "User" u LEFT JOIN "Post" p ON p."userId" = u.id`)
+    await runJoin("RIGHT JOIN (expect 4 + Abandoned Post)", Prisma.sql`SELECT u.email,p.title FROM "User" u RIGHT JOIN "Post" p ON p."userId" = u.id`)
+    await runJoin("FULL OUTER JOIN (expect 5", Prisma.sql`SELECT u.email, p.title FROM "User" u FULL OUTER JOIN "Post" p ON p."userId" = u.id`);
+    await runJoin("CROS JOIN (expect 4 users * 4 posts = 16", Prisma.sql`SELECT u.email, p.title FROM "User" u CROSS JOIN "Post" p`)
+}
+
+main().then(() => console.log("Main function exexuted")).catch((err) => console.log(err)).finally(() => prisma.$disconnect())
+

package/src/testing/test-joins.ts

@@ -0,0 +1,21 @@
+import { PrismaClient } from "@prisma/client";
+import { withToolKit } from "../index.js";
+
+const base = new PrismaClient()
+const prisma = withToolKit(base)
+
+async function main() {
+    const data: any = {
+        from: "User",
+        select: ["title", "content"],
+        join: {
+            type: "CROSS",
+            table: "Post",
+            on: { fromColumn: "id", toColumn: "userId" }
+        }
+    }
+    const result = await prisma.$join(data)
+    return result
+}
+
+main().then((res) => console.table(res)).catch((err) => console.error(err)).finally(() => base.$disconnect())

package/src/testing/test-optimistic.ts

@@ -0,0 +1,33 @@
+import { PrismaClient } from "@prisma/client"
+import { withToolKit } from ".."
+
+const base = new PrismaClient()
+const prisma = withToolKit(base)
+
+async function main() {
+    const user = await prisma.user.findFirst({ where: { email: "tom1@gmail.com" } })
+    if (!user) throw new Error("emailId not found")
+    console.log("current version ", user.version)
+
+    const success = await prisma.$lock.optimistic({
+        model: "user",
+        id: user.id,
+        expectedVersion: user.version,
+        data: { name: "Updated Tom" }
+    })
+    console.log("Updated with new version successded ", success)
+
+    try {
+        const test2 = await prisma.$lock.optimistic({
+            model: "user",
+            id: user.id,
+            expectedVersion: user.version,
+            data: { name: "This should not apply" }
+        })
+        if (!test2) console.log('ERROR: stale update should NOT have succeeded');
+        console.log("this is new version", test2)
+    } catch (error: any) {
+        console.log('Correctly rejected stale update:', error.message);
+    }
+}
+main().then((res) => console.table(res)).catch((err) => console.error(err)).finally(() => base.$disconnect())

package/src/testing/test-pessimistic.ts

@@ -0,0 +1,47 @@
+import { PrismaClient } from "@prisma/client"
+import { withToolKit } from ".."
+
+const urlLink = process.env.DIRECT_URL! as string
+if (!urlLink) throw new Error("DIRECT_URL not exist")
+
+const base = new PrismaClient({
+    datasources: { db: { url: urlLink } }
+})
+const prisma = withToolKit(base)
+
+function sleep(ms: number) {
+    return new Promise((res) => setTimeout(res, ms))
+}
+
+async function main() {
+    const user = await prisma.user.findFirst({ where: { email: "tom1@gmail.com" } })
+    if (!user) throw new Error("Email Id not found for user")
+    const log = (label: string) => console.log(`[${new Date().toISOString()}] ${label}`)
+    const txa = prisma.$lock.pessimistic({ table: "User", id: user.id, mode: "FOR UPDATE" }, async (tx, row) => {
+        log("TX A: acquired lock")
+        await sleep(3000)
+        log("TX A: releasing lock (transaction committing)")
+        return row
+    })
+
+    const txb = (async () => {
+        await sleep(200)
+        log('TX B: attempting to acquire lock (should block here)');
+        return prisma.$lock.pessimistic({
+            table: "User",
+            id: user.id,
+            mode: "FOR UPDATE"
+        },
+            async function (tx, row) {
+                log("TX B: acquired lock (A must have released it)")
+                return row
+            }
+        )
+    })()
+    await txa
+    await txb
+    log("Both transactions complete")
+
+
+}
+main().then((res) => console.log(res)).catch((err) => console.error(err)).finally(() => prisma.$disconnect())