@ciphercross/prisma-toolkit

Utility toolkit for common Prisma operations - pagination, transactions, and error handling.

Installation

npm install @ciphercross/prisma-toolkit

Peer Dependencies

This package requires:

• @prisma/client (^5.0.0 or ^6.0.0)

Features

📄 Pagination

Offset-based Pagination

import { paginate } from '@ciphercross/prisma-toolkit';

const result = await paginate(prisma.user, {
  page: 1,
  limit: 20,
  where: { active: true },
  orderBy: { createdAt: 'desc' },
});

// result: { data: User[], meta: PaginationMeta }

Cursor-based Pagination

import { cursorPaginate } from '@ciphercross/prisma-toolkit';

const result = await cursorPaginate(prisma.user, {
  limit: 20,
  cursor: 'cursor-string',
  orderBy: { id: 'asc' },
});

// result: { data: User[], nextCursor: string | null }

🔍 Helpers

Check if record exists

import { exists } from '@ciphercross/prisma-toolkit';

const userExists = await exists(prisma.user, {
  where: { email: '[email protected]' },
});

Get or throw

import { getOrThrow } from '@ciphercross/prisma-toolkit';

const user = await getOrThrow(prisma.user, {
  where: { id: userId },
}, 'User not found');

Safe update

import { safeUpdate } from '@ciphercross/prisma-toolkit';

const updated = await safeUpdate(prisma.user, {
  where: { id: userId },
  data: { name: 'New Name' },
});

Pick fields

import { pick } from '@ciphercross/prisma-toolkit';

const userData = pick(user, ['id', 'email', 'name']);

🔄 Transactions

import { transaction } from '@ciphercross/prisma-toolkit';

const result = await transaction(prisma, async (tx) => {
  const user = await tx.user.create({ data: { ... } });
  await tx.profile.create({ data: { userId: user.id, ... } });
  return user;
});

⚠️ Prisma Error Helpers

import {
  isPrismaUniqueError,
  isPrismaNotFoundError,
  getPrismaUniqueField,
  getPrismaErrorCode,
} from '@ciphercross/prisma-toolkit';

try {
  await prisma.user.create({ data: { email: '[email protected]' } });
} catch (error) {
  if (isPrismaUniqueError(error)) {
    const field = getPrismaUniqueField(error);
    console.log(`Duplicate value in field: ${field}`);
  }
  
  if (isPrismaNotFoundError(error)) {
    console.log('Record not found');
  }
  
  const errorCode = getPrismaErrorCode(error);
  console.log(`Prisma error code: ${errorCode}`);
}

API Reference

Pagination

• paginate(model, options) - Offset-based pagination
• cursorPaginate(model, options) - Cursor-based pagination

Helpers

• exists(model, args) - Check if record exists
• getOrThrow(model, args, message?) - Get record or throw error
• safeUpdate(model, args) - Update record if exists, return null otherwise
• pick(object, keys) - Pick specific fields from object

Transactions

• transaction(prisma, callback) - Execute operations in transaction

Error Helpers

• isPrismaError(error) - Check if error is Prisma error
• isPrismaUniqueError(error) - Check if error is unique constraint violation
• isPrismaNotFoundError(error) - Check if error is not found error
• isPrismaForeignKeyError(error) - Check if error is foreign key constraint violation
• getPrismaErrorCode(error) - Get Prisma error code
• getPrismaUniqueField(error) - Get field name from unique constraint error
• PRISMA_ERROR_CODES - Object with all Prisma error codes

Development

Build

npm run build

Check version in npm

# Check current version from package.json
npm run check-version

# Check custom version
npm run check-version:custom 1.0.0

Publishing

This package uses GitHub Actions for automated publishing. To publish a new version:

1. Ensure you have NPM_TOKEN secret configured in GitHub repository settings
2. Go to Actions → "Publish to npm" → Run workflow
3. Enter the version you want to publish (e.g., 1.0.0)
4. The workflow will:
   • Check if the version already exists in npm
   • Update version in package.json
   • Build the package
   • Publish to npm
   • Create a git tag

Alternatively, you can create a git tag:

git tag v1.0.0
git push origin v1.0.0

License

MIT