npm package: @litepos/autoquery
Description: AutoQuery is a library for building queries for LitePOS.
Author: LitePOS
Latest version: 5.0.10

# @litepos/autoquery

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![bundle][bundle-src]][bundle-href]
[![JSDocs][jsdocs-src]][jsdocs-href]
[![License][license-src]][license-href]

A TypeScript library for building type-safe queries for LitePOS API endpoints. AutoQuery provides a fluent interface for constructing complex database queries with support for various operators, filtering, sorting, and pagination.

## Features

- 🎯 **Type-safe query building** - Full TypeScript support with compile-time type checking
- 🔍 **Rich filtering operators** - Numeric, string, date, and array operators
- 📊 **Built-in pagination** - Skip/take functionality with total count support
- 🔄 **Flexible sorting** - Ascending and descending order by any field
- 📅 **Date operations** - Specialized date filtering with month/day operators
- 🏗️ **Fluent API** - Chainable methods for intuitive query construction
- 🎨 **LitePOS integration** - Designed specifically for LitePOS API endpoints

## Installation

```bash
npm install @litepos/autoquery
# or
pnpm add @litepos/autoquery
# or
yarn add @litepos/autoquery
```

## Quick Start

```typescript
import { NumericOperators, QueryBuilder, SortOrder, StringOperators } from '@litepos/autoquery'

// Define your data model
interface Invoice {
  id: number
  refId: string
  grandTotal: number
  status: string
  paidAt: Date
}

// Build a query
const query = new QueryBuilder<Invoice>()
  .addParam('grandTotal', NumericOperators.GreaterThan, 100)
  .addParam('status', StringOperators.Contains, 'paid')
  .sortBy('paidAt', SortOrder.Desc)
  .skip(0)
  .take(10)
  .includeTotal(true)

// Get the query parameters
const params = query._build()
```

## Core Concepts

### QueryBuilder

The main class for building queries. It provides a fluent interface for adding filters, sorting, and pagination.

```typescript
const query = new QueryBuilder<YourDataType>()
  .addParam('field', operator, value)
  .sortBy('field', SortOrder.Asc)
  .skip(0)
  .take(10)
```

### Operators

AutoQuery supports various operator types for different data types:

#### Numeric Operators
```typescript
NumericOperators.GreaterThan
NumericOperators.LessThan
NumericOperators.EqualTo
NumericOperators.Between
```

#### String Operators
```typescript
StringOperators.Contains
StringOperators.StartsWith
StringOperators.EndsWith
StringOperators.Like
```

#### Date Operators
```typescript
DateOperators.GreaterThan
DateOperators.Between
DateOperators.StartsWith // For exact date matching
DateOperators.Contains // For month matching
```

#### Array Operators
```typescript
ArrayOperators.In
ArrayOperators.NotIn
```

#### Null Operators
```typescript
NullOperators.IsNull
NullOperators.IsNotNull
```

## Advanced Usage

### Date Filtering

```typescript
// Filter by exact date
query.addParam('paidAt', DateOperators.StartsWith, '2019-01-01')

// Filter by month
query.addParam('paidAt', DateOperators.Contains, MonthValues.Jan)

// Filter by date range
query.addParam('paidAt', DateOperators.Between, ['2019-01-01', '2019-12-31'])
```

### Complex Queries

```typescript
const query = new QueryBuilder<Invoice>()
  .addParam('grandTotal', NumericOperators.GreaterThan, 100)
  .addParam('status', StringOperators.In, ['paid', 'pending'])
  .addParam('refId', StringOperators.Contains, 'INV-')
  .addParam('paidAt', NullOperators.IsNotNull)
  .sortBy('grandTotal', SortOrder.Desc)
  .skip(20)
  .take(50)
  .includeTotal(true)
  .jsconfig('dh:iso8601dt')
```

### Invoice-Specific Queries

```typescript
import { IInvoiceParams, InvoicesQuery } from '@litepos/autoquery'

const invoiceParams: IInvoiceParams = {
  RefIdContains: 'INV-',
  GrandTotal: 100,
  StatusContains: 'paid',
  PaidAtAfter: '2019-01-01T00:00:00',
  skip: 0,
  take: 10
}

const invoiceQuery = new InvoicesQuery(invoiceParams)
```

## API Reference

### QueryBuilder Methods

| Method | Description | Parameters |
|--------|-------------|------------|
| `addParam` | Add a filter parameter | `property`, `operator`, `value` |
| `addRawParam` | Add a raw parameter | `key`, `value` |
| `sortBy` | Set sorting order | `property`, `order` |
| `skip` | Set number of records to skip | `number` |
| `take` | Set number of records to take | `number` |
| `includeTotal` | Include total count in response | `boolean` |
| `jsconfig` | Set JavaScript configuration | `string` |

### Response Types

```typescript
interface IQueryResponse<T> {
  offset?: number
  total?: number
  results?: T[]
  meta?: { [index: string]: string }
  responseStatus?: ResponseStatus
}
```

## TypeScript Support

AutoQuery is built with TypeScript and provides full type safety:

- Compile-time validation of field names
- Type-safe operator selection based on field types
- IntelliSense support for all methods and properties
- Generic type support for custom data models

## License

[MIT](./LICENSE) License © [LitePOS](https://litepos.ai)

<!-- Badges -->

[npm-version-src]: https://img.shields.io/npm/v/@litepos/autoquery?style=flat&colorA=080f12&colorB=1fa669
[npm-version-href]: https://npmjs.com/package/@litepos/autoquery
[npm-downloads-src]: https://img.shields.io/npm/dm/@litepos/autoquery?style=flat&colorA=080f12&colorB=1fa669
[npm-downloads-href]: https://npmjs.com/package/@litepos/autoquery
[bundle-src]: https://img.shields.io/bundlephobia/minzip/@litepos/autoquery?style=flat&colorA=080f12&colorB=1fa669&label=minzip
[bundle-href]: https://bundlephobia.com/result?p=@litepos/autoquery
[license-src]: https://img.shields.io/github/license/litepos/litepos-autoquery.svg?style=flat&colorA=080f12&colorB=1fa669
[license-href]: https://github.com/litepos/litepos-autoquery/blob/main/LICENSE
[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
[jsdocs-href]: https://www.jsdocs.io/package/@litepos/autoquery