test(lib): add test cases for pagination / sorting / filtering / seaerch / performance

Author: ChronicStone

.gitignore

@@ -11,4 +11,5 @@ node_modules
 temp
 playground/.nuxt
 docs/.vitepress/dist
-docs/.vitepress/cache
+docs/.vitepress/cache
+.vercel

docs/features/sorting.md

@@ -106,3 +106,138 @@ const result = query(data, {
 ```
 
 This will sort the data based on the math scores in descending order.
+
+## Advanced Sorting with Value Parsing
+
+The `SortOptions` interface now includes a `parser` option, which allows you to prepare and format values before sorting. This is particularly useful when dealing with mixed data types or when you need to apply custom sorting logic.
+
+```typescript
+export interface SortOptions {
+  key: string
+  dir?: 'asc' | 'desc'
+  parser?: 'number' | 'boolean' | 'string' | ((value: any) => string | number | boolean | null | undefined)
+}
+```
+
+The `parser` option can be one of the following:
+
+- A string value: `'number'`, `'boolean'`, or `'string'` for basic type conversion
+- A custom function that takes the value and returns a parsed version
+
+### Examples
+
+#### Using Built-in Parsers
+
+1. Sorting mixed string and number values as numbers:
+
+```ts twoslash
+import { query } from '@chronicstone/array-query'
+
+const data = [
+  { id: 1, value: '10' },
+  { id: 2, value: 5 },
+  { id: 3, value: '15' },
+  { id: 4, value: '3' }
+]
+
+const result = query(data, {
+  sort: { key: 'value', dir: 'asc', parser: 'number' }
+})
+```
+
+Result:
+```ts twoslash
+[
+  { id: 4, value: '3' },
+  { id: 2, value: 5 },
+  { id: 1, value: '10' },
+  { id: 3, value: '15' }
+]
+```
+
+2. Sorting boolean values:
+
+```ts twoslash
+import { query } from '@chronicstone/array-query'
+
+const data = [
+  { id: 1, isActive: 'true' },
+  { id: 2, isActive: false },
+  { id: 3, isActive: 'false' },
+  { id: 4, isActive: true }
+]
+
+const result = query(data, {
+  sort: { key: 'isActive', dir: 'desc', parser: 'boolean' }
+})
+```
+
+Result:
+```ts twoslash
+[
+  { id: 1, isActive: 'true' },
+  { id: 4, isActive: true },
+  { id: 2, isActive: false },
+  { id: 3, isActive: 'false' }
+]
+```
+
+#### Using Custom Parser Functions
+
+3. Sorting by date strings:
+
+```ts twoslash
+import { query } from '@chronicstone/array-query'
+
+const data = [
+  { id: 1, date: '2023-05-15' },
+  { id: 2, date: '2023-01-10' },
+  { id: 3, date: '2023-12-01' }
+]
+
+const result = query(data, {
+  sort: {
+    key: 'date',
+    dir: 'asc',
+    parser: value => new Date(value).getTime()
+  }
+})
+```
+
+Result:
+```ts twoslash
+[
+  { id: 2, date: '2023-01-10' },
+  { id: 1, date: '2023-05-15' },
+  { id: 3, date: '2023-12-01' }
+]
+```
+
+4. Sorting by a computed value:
+
+```ts twoslash
+import { query } from '@chronicstone/array-query'
+
+const data = [
+  { id: 1, firstName: 'John', lastName: 'Doe' },
+  { id: 2, firstName: 'Jane', lastName: 'Smith' },
+  { id: 3, firstName: 'Alice', lastName: 'Johnson' }
+]
+
+const result = query(data, {
+  sort: {
+    key: 'firstName',
+    dir: 'asc',
+    parser: (value, item) => `${item.lastName}, ${item.firstName}`
+  }
+})
+```
+
+Result:
+```ts twoslash
+[
+  { id: 3, firstName: 'Alice', lastName: 'Johnson' },
+  { id: 2, firstName: 'Jane', lastName: 'Smith' },
+  { id: 1, firstName: 'John', lastName: 'Doe' }
+]
+```

src/query.ts

@@ -23,12 +23,13 @@ export function query<T extends GenericObject, P extends QueryParams>(
     const sortArray = Array.isArray(params.sort) ? params.sort : [params.sort]
 
     result = result.sort((a, b) => {
-      for (const { key, dir } of sortArray) {
-        const aValue = getObjectProperty(a, key)
-        const bValue = getObjectProperty(b, key)
+      for (const { key, dir, parser } of sortArray) {
+        const parserHandler = typeof parser === 'function' ? parser : (v: any) => parser === 'number' ? Number(v) : parser === 'boolean' ? Boolean(v) : parser === 'string' ? String(v) : v
+        const aParsed = parserHandler(getObjectProperty(a, key)) ?? null
+        const bParsed = parserHandler(getObjectProperty(b, key)) ?? null
 
-        if (aValue !== bValue) {
-          const comparison = (aValue < bValue) ? -1 : 1
+        if (aParsed !== bParsed) {
+          const comparison = (aParsed < bParsed) ? -1 : 1
           return dir === 'asc' ? comparison : -comparison
         }
       }
@@ -162,7 +163,7 @@ export function query<T extends GenericObject, P extends QueryParams>(
     const unpaginatedRows = [...result]
     const totalRows = result.length
     const totalPages = Math.ceil(totalRows / params.limit)
-    const start = params.offset ?? 0
+    const start = ((params?.page ?? 1) - 1) * params.limit
     const end = start + params.limit
     result = result.slice(start, end)
 

src/types.ts

@@ -66,14 +66,15 @@ export interface SearchOptions {
 export interface SortOptions {
   key: string
   dir?: 'asc' | 'desc'
+  parser?: 'number' | 'boolean' | 'string' | ((value: any) => string | number | boolean | null | undefined)
 }
 
 export interface QueryParams {
   sort?: SortOptions | Array<SortOptions>
   search?: SearchOptions
   filter?: FilterOptions
   limit?: number
-  offset?: number
+  page?: number
 }
 
 export type QueryResult<T extends GenericObject, P extends QueryParams> = P extends { limit: number } ? { totalRows: number, totalPages: number, rows: T[], unpaginatedRows: T[] } : { rows: T[] }