npm package: @origins-digital/query-filter-prisma
Description: Common query-filter-prisma utilities for all projects
Author: Origins Digital
Latest version: 3.1.4

# @origins-digital/query-filter-prisma

A package for building type-safe Prisma query filters in TypeScript.

> **Zod compatibility**: Works with query filter schemas built using **Zod v4.x**.

## Installation

```bash
npm install @origins-digital/query-filter-prisma
```

## Features

- Type-safe Prisma query filtering
- Support for complex filter conditions
- Built-in comparison operators
- Seamless integration with Prisma's query API
- Flexible filter grouping (AND/OR/NOT)
- Support for nested object filtering

## Usage

### Basic Filtering

```typescript
import { QueryFilter } from '@origins-digital/query-filter-core';
import { PrismaWhereBuilder } from '@origins-digital/query-filter-prisma';

type User = {
  id: string;
  name: string;
  age: number;
  isActive: boolean;
};

// Simple equality filter
const filter: QueryFilter<User> = {
  name: { eq: 'John' },
  age: { gt: 18 },
  isActive: { is: true },
};

// Convert to Prisma where clause
const prismaWhere = PrismaWhereBuilder.build(filter);

// Use with Prisma client
const users = await prisma.user.findMany({
  where: prismaWhere,
});
```

### Complex Filtering

```typescript
// Complex filter with AND/OR/NOT
const filter: QueryFilter<User> = {
  or: [
    { name: { contains: 'John' } },
    {
      and: [
        { age: { gt: 18 } },
        { isActive: { is: true } },
        { NOT: { name: { contains: 'Doe' } } },
      ],
    },
  ],
};

const prismaWhere = PrismaWhereBuilder.build(filter);
```

### String Comparisons

```typescript
const filter: QueryFilter<User> = {
  name: {
    contains: 'John',
    startsWith: 'J',
    endsWith: 'n',
    mode: 'insensitive', // Case-insensitive comparison
  },
};
```

### Numeric Comparisons

```typescript
const filter: QueryFilter<User> = {
  age: {
    gt: 18, // Greater than
    lt: 65, // Less than
    gte: 21, // Greater than or equal
    lte: 60, // Less than or equal
    in: [18, 21, 30], // In array
  },
};
```

### Boolean Comparisons

```typescript
const filter: QueryFilter<User> = {
  isActive: {
    is: true, // IS TRUE
    isNot: false, // IS NOT FALSE
  },
};
```

### Date Comparisons

```typescript
const filter: QueryFilter<User> = {
  createdAt: {
    gt: new Date('2024-01-01'),
    lt: new Date('2024-12-31'),
    between: {
      lower: new Date('2024-01-01'),
      upper: new Date('2024-12-31'),
    },
  },
};
```

## API Reference

### PrismaWhereBuilder

```typescript
class PrismaWhereBuilder {
  static build<Entity>(filter: QueryFilter<Entity>): PrismaQueryFilter<Entity>;
}
```

### PrismaQueryFilter

```typescript
type PrismaQueryFilter<T> = {
  AND?: PrismaQueryFilter<T> | PrismaQueryFilter<T>[];
  OR?: PrismaQueryFilter<T>[];
  NOT?: PrismaQueryFilter<T> | PrismaQueryFilter<T>[];
  [K in keyof T]?: PrismaFilterFieldComparison<T[K]>;
};
```

### PrismaFilterFieldComparison

```typescript
type PrismaFilterFieldComparison<FieldType> = {
  // Common operators
  equals?: FieldType;
  in?: FieldType[];
  notIn?: FieldType[];
  lt?: FieldType;
  lte?: FieldType;
  gt?: FieldType;
  gte?: FieldType;
  not?: PrismaFilterFieldComparison<FieldType> | FieldType;

  // String specific operators
  contains?: string;
  startsWith?: string;
  endsWith?: string;
  mode?: 'default' | 'insensitive';
};
```

## Filter Operators

### Common Operators

- `equals`: Equal to
- `in`: In array
- `notIn`: Not in array
- `lt`: Less than
- `lte`: Less than or equal to
- `gt`: Greater than
- `gte`: Greater than or equal to
- `not`: Not equal to or nested comparison

### String Operators

- `contains`: Contains substring
- `startsWith`: Starts with
- `endsWith`: Ends with
- `mode`: Case sensitivity ('default' or 'insensitive')

### Boolean Operators

- `equals`: Equal to
- `not`: Not equal to

### Date Operators

- `equals`: Equal to
- `in`: In array
- `notIn`: Not in array
- `lt`: Less than
- `lte`: Less than or equal to
- `gt`: Greater than
- `gte`: Greater than or equal to
- `not`: Not equal to or nested comparison

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.