@litepos/autoquery 5.0.1 → 5.0.2

package/README.md

@@ -1,4 +1,4 @@
-# pkg-placeholder
+# @litepos/autoquery
 
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
@@ -6,37 +6,204 @@
 [![JSDocs][jsdocs-src]][jsdocs-href]
 [![License][license-src]][license-href]
 
-_description_
+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.
 
-## Note for Developers
+## Features
 
-This starter recommands using [npm Trusted Publisher](https://github.com/e18e/ecosystem-issues/issues/201), where the release is done on CI to ensure the security of the packages.
+- 🎯 **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
 
-To do so, you need to run `pnpm publish` manually for the very first time to create the package on npm, and then go to `https://www.npmjs.com/package/<your-package-name>/access` to set the connection to your GitHub repo.
+## Installation
 
-Then for the future releases, you can run `pnpm run release` to do the release and the GitHub Actions will take care of the release process.
+```bash
+npm install @litepos/autoquery
+# or
+pnpm add @litepos/autoquery
+# or
+yarn add @litepos/autoquery
+```
 
-## Sponsors
+## Quick Start
 
-<p align="center">
-  <a href="https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg">
-    <img src='https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg'/>
-  </a>
-</p>
+```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 © [Anthony Fu](https://github.com/antfu)
+[MIT](./LICENSE) License © [LitePOS](https://litepos.ai)
 
 <!-- Badges -->
 
-[npm-version-src]: https://img.shields.io/npm/v/pkg-placeholder?style=flat&colorA=080f12&colorB=1fa669
-[npm-version-href]: https://npmjs.com/package/pkg-placeholder
-[npm-downloads-src]: https://img.shields.io/npm/dm/pkg-placeholder?style=flat&colorA=080f12&colorB=1fa669
-[npm-downloads-href]: https://npmjs.com/package/pkg-placeholder
-[bundle-src]: https://img.shields.io/bundlephobia/minzip/pkg-placeholder?style=flat&colorA=080f12&colorB=1fa669&label=minzip
-[bundle-href]: https://bundlephobia.com/result?p=pkg-placeholder
-[license-src]: https://img.shields.io/github/license/antfu/pkg-placeholder.svg?style=flat&colorA=080f12&colorB=1fa669
-[license-href]: https://github.com/antfu/pkg-placeholder/blob/main/LICENSE
+[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/pkg-placeholder
+[jsdocs-href]: https://www.jsdocs.io/package/@litepos/autoquery

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@litepos/autoquery",
   "type": "module",
-  "version": "5.0.1",
+  "version": "5.0.2",
   "packageManager": "pnpm@10.17.1",
   "description": "AutoQuery is a library for building queries for LitePOS.",
   "author": "LitePOS <info@litepos.ai>",