docs(types): document type-safe querying

Author: ChronicStone

README.md

@@ -1,6 +1,6 @@
 # 🔍 ArrayQuery
 
-ArrayQuery is a powerful TypeScript package that brings ORM-like querying capabilities to local arrays. It allows you to manipulate and retrieve data from arrays with ease, using a familiar and intuitive API.
+ArrayQuery is a powerful TypeScript package that brings type-safe querying capabilities to local arrays. It allows you to manipulate and retrieve data from arrays with ease, using a familiar and intuitive API.
 
 ## ✨ Features
 

bun.lockb

@@ -55,6 +55,7 @@ export default defineConfig({
       {
         text: 'Features',
         items: [
+          { text: 'Type-Safe Queries', link: '/features/type-safety' },
           { text: 'Pagination', link: '/features/pagination' },
           { text: 'Sorting', link: '/features/sorting' },
           { text: 'Searching', link: '/features/searching' },

docs/.vitepress/config.ts

@@ -212,32 +212,3 @@ Result:
   { 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' }
-]
-```

docs/features/sorting.md

@@ -0,0 +1,99 @@
+## Type-Safe Queries
+
+ArrayQuery provides type safety for query parameters, ensuring that you can only use valid keys for sorting, searching, and filtering. This feature helps catch errors at compile-time and provides excellent autocompletion support in your IDE.
+
+### Sorting
+
+When specifying the `key` for sorting, you'll get type-safe suggestions based on the properties of your data:
+
+```ts twoslash
+// @noErrors
+import { query } from '@chronicstone/array-query'
+
+const users = [
+  { id: 1, name: 'Alice', age: 30, email: '[email protected]' },
+  { id: 2, name: 'Bob', age: 25, email: '[email protected]' },
+]
+
+const result = query(users, {
+  sort: { key: '' }
+//              ^|
+})
+```
+
+Hovering over the empty string will show a popover with valid options: `"id" | "name" | "age" | "email"`.
+
+### Searching
+
+The `keys` array in the search options is also type-safe:
+
+```ts twoslash
+// @noErrors
+import { query } from '@chronicstone/array-query'
+
+const products = [
+  { id: 1, name: 'Laptop', price: 1000, description: 'Powerful laptop' },
+  { id: 2, name: 'Phone', price: 500, description: 'Smart phone' },
+]
+
+const result = query(products, {
+  search: {
+    value: 'laptop',
+    keys: ['']
+    //      ^|
+  }
+})
+```
+
+The popover for the empty string will show: `"id" | "name" | "price" | "description"`.
+
+### Filtering
+
+Filter keys are also type-safe, including for nested properties:
+
+```ts twoslash
+// @noErrors
+import { query } from '@chronicstone/array-query'
+
+const employees = [
+  { id: 1, name: 'Alice', department: { name: 'IT', location: 'New York' } },
+  { id: 2, name: 'Bob', department: { name: 'HR', location: 'London' } },
+]
+
+const result = query(employees, {
+  filter: [
+    { key: '' }
+    //      ^|
+  ]
+})
+```
+
+### Complex Nested Structures
+
+ArrayQuery handles complex nested structures with ease:
+
+```typescript twoslash
+// @noErrors
+import { query } from '@chronicstone/array-query'
+
+const data = [
+  {
+    id: 1,
+    info: {
+      personal: { name: 'Alice', age: 30 },
+      professional: { title: 'Developer', skills: ['JavaScript', 'TypeScript'] }
+    },
+    contacts: [
+      { type: 'email', value: '[email protected]' },
+      { type: 'phone', value: '123-456-7890' }
+    ]
+  }
+]
+
+const result = query(data, {
+  sort: { key: '', dir: 'asc' },
+//              ^|
+})
+```
+
+These type-safe queries ensure that you're always using valid property paths, reducing errors and improving the developer experience when working with ArrayQuery.

docs/features/type-safety.md

@@ -1,6 +1,6 @@
 # Introduction to ArrayQuery
 
-ArrayQuery is a powerful TypeScript library designed to bring ORM-like querying capabilities to local arrays. It provides an intuitive and efficient way to manipulate and retrieve data from arrays, offering functionality similar to database querying but for in-memory JavaScript/TypeScript arrays.
+ArrayQuery is a powerful TypeScript library designed to bring Type-Safe ORM-like querying capabilities to local arrays. It provides an intuitive and efficient way to manipulate and retrieve data from arrays, offering functionality similar to database querying but for in-memory JavaScript/TypeScript arrays.
 
 ## What is ArrayQuery?
 

docs/getting-started/introduction.md

@@ -1,10 +1,10 @@
 ---
 layout: home
 
-title: ORM-like Querying for Local Arrays
+title: Type-Safe ORM-like Querying for Local Arrays
 hero:
   name: "ArrayQuery"
-  text: "ORM-like Querying for Local Arrays"
+  text: "Type-Safe ORM-like Querying for Arrays"
   tagline: "Manipulate and retrieve data from arrays with ease using a familiar and intuitive API."
   image:
     src: /images/logo.svg

docs/index.md

@@ -52,7 +52,7 @@
     "@antfu/eslint-config": "^2.22.0-beta.2",
     "@antfu/ni": "^0.21.12",
     "@antfu/utils": "^0.7.10",
-    "@chronicstone/array-query": "0.2.3",
+    "@chronicstone/array-query": "0.2.4",
     "@faker-js/faker": "^8.4.1",
     "@shikijs/vitepress-twoslash": "^1.10.3",
     "@types/node": "^20.14.10",