@litepos/autoquery 5.0.1 → 5.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +189 -22
  2. package/dist/index.d.ts +29 -30
  3. package/dist/index.js +8 -9
  4. package/package.json +34 -31
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # pkg-placeholder
1
+ # @litepos/autoquery
2
2
 
3
3
  [![npm version][npm-version-src]][npm-version-href]
4
4
  [![npm downloads][npm-downloads-src]][npm-downloads-href]
@@ -6,37 +6,204 @@
6
6
  [![JSDocs][jsdocs-src]][jsdocs-href]
7
7
  [![License][license-src]][license-href]
8
8
 
9
- _description_
9
+ 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.
10
10
 
11
- ## Note for Developers
11
+ ## Features
12
12
 
13
- 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.
13
+ - 🎯 **Type-safe query building** - Full TypeScript support with compile-time type checking
14
+ - 🔍 **Rich filtering operators** - Numeric, string, date, and array operators
15
+ - 📊 **Built-in pagination** - Skip/take functionality with total count support
16
+ - 🔄 **Flexible sorting** - Ascending and descending order by any field
17
+ - 📅 **Date operations** - Specialized date filtering with month/day operators
18
+ - 🏗️ **Fluent API** - Chainable methods for intuitive query construction
19
+ - 🎨 **LitePOS integration** - Designed specifically for LitePOS API endpoints
14
20
 
15
- 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.
21
+ ## Installation
16
22
 
17
- 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.
23
+ ```bash
24
+ npm install @litepos/autoquery
25
+ # or
26
+ pnpm add @litepos/autoquery
27
+ # or
28
+ yarn add @litepos/autoquery
29
+ ```
18
30
 
19
- ## Sponsors
31
+ ## Quick Start
20
32
 
21
- <p align="center">
22
- <a href="https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg">
23
- <img src='https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg'/>
24
- </a>
25
- </p>
33
+ ```typescript
34
+ import { NumericOperators, QueryBuilder, SortOrder, StringOperators } from '@litepos/autoquery'
35
+
36
+ // Define your data model
37
+ interface Invoice {
38
+ id: number
39
+ refId: string
40
+ grandTotal: number
41
+ status: string
42
+ paidAt: Date
43
+ }
44
+
45
+ // Build a query
46
+ const query = new QueryBuilder<Invoice>()
47
+ .addParam('grandTotal', NumericOperators.GreaterThan, 100)
48
+ .addParam('status', StringOperators.Contains, 'paid')
49
+ .sortBy('paidAt', SortOrder.Desc)
50
+ .skip(0)
51
+ .take(10)
52
+ .includeTotal(true)
53
+
54
+ // Get the query parameters
55
+ const params = query._build()
56
+ ```
57
+
58
+ ## Core Concepts
59
+
60
+ ### QueryBuilder
61
+
62
+ The main class for building queries. It provides a fluent interface for adding filters, sorting, and pagination.
63
+
64
+ ```typescript
65
+ const query = new QueryBuilder<YourDataType>()
66
+ .addParam('field', operator, value)
67
+ .sortBy('field', SortOrder.Asc)
68
+ .skip(0)
69
+ .take(10)
70
+ ```
71
+
72
+ ### Operators
73
+
74
+ AutoQuery supports various operator types for different data types:
75
+
76
+ #### Numeric Operators
77
+ ```typescript
78
+ NumericOperators.GreaterThan
79
+ NumericOperators.LessThan
80
+ NumericOperators.EqualTo
81
+ NumericOperators.Between
82
+ ```
83
+
84
+ #### String Operators
85
+ ```typescript
86
+ StringOperators.Contains
87
+ StringOperators.StartsWith
88
+ StringOperators.EndsWith
89
+ StringOperators.Like
90
+ ```
91
+
92
+ #### Date Operators
93
+ ```typescript
94
+ DateOperators.GreaterThan
95
+ DateOperators.Between
96
+ DateOperators.StartsWith // For exact date matching
97
+ DateOperators.Contains // For month matching
98
+ ```
99
+
100
+ #### Array Operators
101
+ ```typescript
102
+ ArrayOperators.In
103
+ ArrayOperators.NotIn
104
+ ```
105
+
106
+ #### Null Operators
107
+ ```typescript
108
+ NullOperators.IsNull
109
+ NullOperators.IsNotNull
110
+ ```
111
+
112
+ ## Advanced Usage
113
+
114
+ ### Date Filtering
115
+
116
+ ```typescript
117
+ // Filter by exact date
118
+ query.addParam('paidAt', DateOperators.StartsWith, '2019-01-01')
119
+
120
+ // Filter by month
121
+ query.addParam('paidAt', DateOperators.Contains, MonthValues.Jan)
122
+
123
+ // Filter by date range
124
+ query.addParam('paidAt', DateOperators.Between, ['2019-01-01', '2019-12-31'])
125
+ ```
126
+
127
+ ### Complex Queries
128
+
129
+ ```typescript
130
+ const query = new QueryBuilder<Invoice>()
131
+ .addParam('grandTotal', NumericOperators.GreaterThan, 100)
132
+ .addParam('status', StringOperators.In, ['paid', 'pending'])
133
+ .addParam('refId', StringOperators.Contains, 'INV-')
134
+ .addParam('paidAt', NullOperators.IsNotNull)
135
+ .sortBy('grandTotal', SortOrder.Desc)
136
+ .skip(20)
137
+ .take(50)
138
+ .includeTotal(true)
139
+ .jsconfig('dh:iso8601dt')
140
+ ```
141
+
142
+ ### Invoice-Specific Queries
143
+
144
+ ```typescript
145
+ import { IInvoiceParams, InvoicesQuery } from '@litepos/autoquery'
146
+
147
+ const invoiceParams: IInvoiceParams = {
148
+ RefIdContains: 'INV-',
149
+ GrandTotal: 100,
150
+ StatusContains: 'paid',
151
+ PaidAtAfter: '2019-01-01T00:00:00',
152
+ skip: 0,
153
+ take: 10
154
+ }
155
+
156
+ const invoiceQuery = new InvoicesQuery(invoiceParams)
157
+ ```
158
+
159
+ ## API Reference
160
+
161
+ ### QueryBuilder Methods
162
+
163
+ | Method | Description | Parameters |
164
+ |--------|-------------|------------|
165
+ | `addParam` | Add a filter parameter | `property`, `operator`, `value` |
166
+ | `addRawParam` | Add a raw parameter | `key`, `value` |
167
+ | `sortBy` | Set sorting order | `property`, `order` |
168
+ | `skip` | Set number of records to skip | `number` |
169
+ | `take` | Set number of records to take | `number` |
170
+ | `includeTotal` | Include total count in response | `boolean` |
171
+ | `jsconfig` | Set JavaScript configuration | `string` |
172
+
173
+ ### Response Types
174
+
175
+ ```typescript
176
+ interface IQueryResponse<T> {
177
+ offset?: number
178
+ total?: number
179
+ results?: T[]
180
+ meta?: { [index: string]: string }
181
+ responseStatus?: ResponseStatus
182
+ }
183
+ ```
184
+
185
+ ## TypeScript Support
186
+
187
+ AutoQuery is built with TypeScript and provides full type safety:
188
+
189
+ - Compile-time validation of field names
190
+ - Type-safe operator selection based on field types
191
+ - IntelliSense support for all methods and properties
192
+ - Generic type support for custom data models
26
193
 
27
194
  ## License
28
195
 
29
- [MIT](./LICENSE) License © [Anthony Fu](https://github.com/antfu)
196
+ [MIT](./LICENSE) License © [LitePOS](https://litepos.ai)
30
197
 
31
198
  <!-- Badges -->
32
199
 
33
- [npm-version-src]: https://img.shields.io/npm/v/pkg-placeholder?style=flat&colorA=080f12&colorB=1fa669
34
- [npm-version-href]: https://npmjs.com/package/pkg-placeholder
35
- [npm-downloads-src]: https://img.shields.io/npm/dm/pkg-placeholder?style=flat&colorA=080f12&colorB=1fa669
36
- [npm-downloads-href]: https://npmjs.com/package/pkg-placeholder
37
- [bundle-src]: https://img.shields.io/bundlephobia/minzip/pkg-placeholder?style=flat&colorA=080f12&colorB=1fa669&label=minzip
38
- [bundle-href]: https://bundlephobia.com/result?p=pkg-placeholder
39
- [license-src]: https://img.shields.io/github/license/antfu/pkg-placeholder.svg?style=flat&colorA=080f12&colorB=1fa669
40
- [license-href]: https://github.com/antfu/pkg-placeholder/blob/main/LICENSE
200
+ [npm-version-src]: https://img.shields.io/npm/v/@litepos/autoquery?style=flat&colorA=080f12&colorB=1fa669
201
+ [npm-version-href]: https://npmjs.com/package/@litepos/autoquery
202
+ [npm-downloads-src]: https://img.shields.io/npm/dm/@litepos/autoquery?style=flat&colorA=080f12&colorB=1fa669
203
+ [npm-downloads-href]: https://npmjs.com/package/@litepos/autoquery
204
+ [bundle-src]: https://img.shields.io/bundlephobia/minzip/@litepos/autoquery?style=flat&colorA=080f12&colorB=1fa669&label=minzip
205
+ [bundle-href]: https://bundlephobia.com/result?p=@litepos/autoquery
206
+ [license-src]: https://img.shields.io/github/license/litepos/litepos-autoquery.svg?style=flat&colorA=080f12&colorB=1fa669
207
+ [license-href]: https://github.com/litepos/litepos-autoquery/blob/main/LICENSE
41
208
  [jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
42
- [jsdocs-href]: https://www.jsdocs.io/package/pkg-placeholder
209
+ [jsdocs-href]: https://www.jsdocs.io/package/@litepos/autoquery
package/dist/index.d.ts CHANGED
@@ -90,20 +90,20 @@ declare enum NumericOperators {
90
90
  'NotEqualTo' = 10,
91
91
  }
92
92
  declare enum StringOperators {
93
- 'Contains' = 0,
94
- 'NotContains' = 1,
95
- 'StartsWith' = 2,
96
- 'EndsWith' = 3,
97
- "Like" = 4,
93
+ Contains = 0,
94
+ NotContains = 1,
95
+ StartsWith = 2,
96
+ EndsWith = 3,
97
+ Like = 4,
98
98
  }
99
99
  declare enum ArrayOperators {
100
- 'In' = 0,
101
- 'NotIn' = 1,
100
+ In = 0,
101
+ NotIn = 1,
102
102
  }
103
103
  declare enum NullOperators {
104
- 'IsNull' = 0,
104
+ IsNull = 0,
105
105
  // Check if field IS NULL
106
- 'IsNotNull' = 1,
106
+ IsNotNull = 1,
107
107
  }
108
108
  declare enum MonthOperator {
109
109
  WithinAMonth = "Contains",
@@ -112,25 +112,25 @@ declare enum DayOperator {
112
112
  At = "StartsWith",
113
113
  }
114
114
  declare enum DateOperators {
115
- 'GreaterThan' = 0,
116
- 'GreaterThanOrEqualTo' = 1,
117
- 'LessThan' = 2,
118
- 'LessThanOrEqualTo' = 3,
119
- 'Between' = 4,
115
+ GreaterThan = 0,
116
+ GreaterThanOrEqualTo = 1,
117
+ LessThan = 2,
118
+ LessThanOrEqualTo = 3,
119
+ Between = 4,
120
120
  // BETWEEN value1 AND value2
121
- 'StartsWith' = 5,
121
+ StartsWith = 5,
122
122
  // For exact date matching (e.g., "2019-01-01")
123
- 'Contains' = 6,
124
- }
125
- type DateOperatorValueMap = {
126
- 'GreaterThan': string;
127
- 'GreaterThanOrEqualTo': string;
128
- 'LessThan': string;
129
- 'LessThanOrEqualTo': string;
130
- 'Between': [string, string];
131
- 'StartsWith': string;
132
- 'Contains': MonthValues;
133
- };
123
+ Contains = 6,
124
+ }
125
+ interface DateOperatorValueMap {
126
+ GreaterThan: string;
127
+ GreaterThanOrEqualTo: string;
128
+ LessThan: string;
129
+ LessThanOrEqualTo: string;
130
+ Between: [string, string];
131
+ StartsWith: string;
132
+ Contains: MonthValues;
133
+ }
134
134
  declare enum MonthValues {
135
135
  Jan = "-01-",
136
136
  Feb = "-02-",
@@ -154,11 +154,10 @@ declare class QueryBuilder<T> {
154
154
  take(take: number): this;
155
155
  sortBy<K extends keyof T>(property: K, orderBy: SortOrder): this;
156
156
  jsconfig(param: string): this;
157
- /** @internal */
158
- _build(): Record<string, string>;
157
+ build(): Record<string, string>;
159
158
  }
160
- type QueryEtcParams = {
159
+ interface QueryEtcParams {
161
160
  search_keywords?: string;
162
- };
161
+ }
163
162
  //#endregion
164
163
  export { ArrayOperators, DateOperatorValueMap, DateOperators, DayOperator, EnumToString, IBaseParams, IInvoiceParams, IInvoicesQuery, IQueryResponse, InvoicesQuery, MonthOperator, MonthValues, NullOperators, NumericOperators, Operator, OperatorValueMap, QueryBuilder, QueryEtcParams, QueryResponse, QueryableType, ResponseStatus, SortOrder, StringOperators, ValidationError };
package/dist/index.js CHANGED
@@ -102,29 +102,28 @@ var QueryBuilder = class {
102
102
  return this;
103
103
  }
104
104
  includeTotal(flag) {
105
- if (flag) this.params["include"] = "total";
105
+ if (flag) this.params.include = "total";
106
106
  return this;
107
107
  }
108
108
  skip(skip) {
109
- this.params["skip"] = `${skip}`;
109
+ this.params.skip = `${skip}`;
110
110
  return this;
111
111
  }
112
112
  take(take) {
113
- this.params["take"] = `${take}`;
113
+ this.params.take = `${take}`;
114
114
  return this;
115
115
  }
116
116
  sortBy(property, orderBy) {
117
- if (orderBy === SortOrder.Asc) this.params["OrderBy"] = `${property.toString()}`;
118
- else this.params["OrderByDesc"] = `${property.toString()}`;
117
+ if (orderBy === SortOrder.Asc) this.params.OrderBy = `${property.toString()}`;
118
+ else this.params.OrderByDesc = `${property.toString()}`;
119
119
  return this;
120
120
  }
121
121
  jsconfig(param) {
122
- this.params["jsconfig"] = param;
122
+ this.params.jsconfig = param;
123
123
  return this;
124
124
  }
125
- /** @internal */
126
- _build() {
127
- this.params["jsconfig"] = "dh:iso8601dt";
125
+ build() {
126
+ this.params.jsconfig = "dh:iso8601dt";
128
127
  return this.params;
129
128
  }
130
129
  };
package/package.json CHANGED
@@ -1,12 +1,17 @@
1
1
  {
2
2
  "name": "@litepos/autoquery",
3
3
  "type": "module",
4
- "version": "5.0.1",
5
- "packageManager": "pnpm@10.17.1",
4
+ "version": "5.0.3",
6
5
  "description": "AutoQuery is a library for building queries for LitePOS.",
7
6
  "author": "LitePOS <info@litepos.ai>",
8
7
  "license": "MIT",
9
- "keywords": ["litepos", "autoquery", "query", "database", "sql"],
8
+ "keywords": [
9
+ "litepos",
10
+ "autoquery",
11
+ "query",
12
+ "database",
13
+ "sql"
14
+ ],
10
15
  "sideEffects": false,
11
16
  "exports": {
12
17
  ".": "./dist/index.js",
@@ -18,39 +23,37 @@
18
23
  "files": [
19
24
  "dist"
20
25
  ],
21
- "scripts": {
22
- "build": "tsdown",
23
- "dev": "tsdown --watch",
24
- "lint": "eslint",
25
- "prepublishOnly": "nr build",
26
- "release": "bumpp",
27
- "start": "tsx src/index.ts",
28
- "test": "vitest",
29
- "typecheck": "tsc --noEmit",
30
- "prepare": "simple-git-hooks"
31
- },
32
26
  "devDependencies": {
33
- "@antfu/eslint-config": "catalog:cli",
34
- "@antfu/ni": "catalog:cli",
35
- "@antfu/utils": "catalog:inlined",
36
- "@types/node": "catalog:types",
37
- "bumpp": "catalog:cli",
38
- "eslint": "catalog:cli",
39
- "lint-staged": "catalog:cli",
40
- "simple-git-hooks": "catalog:cli",
41
- "tinyexec": "catalog:testing",
42
- "tsdown": "catalog:cli",
43
- "tsx": "catalog:cli",
44
- "typescript": "catalog:cli",
45
- "vite": "catalog:cli",
46
- "vitest": "catalog:testing",
47
- "vitest-package-exports": "catalog:testing",
48
- "yaml": "catalog:testing"
27
+ "@antfu/eslint-config": "^5.4.1",
28
+ "@antfu/ni": "^26.0.1",
29
+ "@antfu/utils": "^9.2.1",
30
+ "@types/node": "^24.5.2",
31
+ "bumpp": "^10.2.3",
32
+ "eslint": "^9.36.0",
33
+ "lint-staged": "^16.2.0",
34
+ "simple-git-hooks": "^2.13.1",
35
+ "tinyexec": "^1.0.1",
36
+ "tsdown": "^0.15.4",
37
+ "tsx": "^4.20.5",
38
+ "typescript": "^5.9.2",
39
+ "vite": "^7.1.7",
40
+ "vitest": "^3.2.4",
41
+ "vitest-package-exports": "^0.1.1",
42
+ "yaml": "^2.8.1"
49
43
  },
50
44
  "simple-git-hooks": {
51
45
  "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"
52
46
  },
53
47
  "lint-staged": {
54
48
  "*": "eslint --fix"
49
+ },
50
+ "scripts": {
51
+ "build": "tsdown",
52
+ "dev": "tsdown --watch",
53
+ "lint": "eslint",
54
+ "release": "bumpp",
55
+ "start": "tsx src/index.ts",
56
+ "test": "vitest",
57
+ "typecheck": "tsc --noEmit"
55
58
  }
56
- }
59
+ }