@litepos/autoquery

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

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

Quick Start

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.

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

NumericOperators.GreaterThan
NumericOperators.LessThan
NumericOperators.EqualTo
NumericOperators.Between

String Operators

StringOperators.Contains
StringOperators.StartsWith
StringOperators.EndsWith
StringOperators.Like

Date Operators

DateOperators.GreaterThan
DateOperators.Between
DateOperators.StartsWith // For exact date matching
DateOperators.Contains // For month matching

Array Operators

ArrayOperators.In
ArrayOperators.NotIn

Null Operators

NullOperators.IsNull
NullOperators.IsNotNull

Advanced Usage

Date Filtering

// 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

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

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

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 © LitePOS