feat(types): provide type-safe key paths for filter / search / sort query options

Author: ChronicStone

src/query.ts

@@ -1,7 +1,7 @@
 import type { FilterMatchMode, GenericObject, MatchModeProcessorMap, QueryFilter, QueryFilterGroup, QueryParams, QueryResult } from './types'
 import { MatchModeProcessor, getObjectProperty, validateBetweenPayload } from './utils'
 
-export function query<T extends GenericObject, P extends QueryParams>(
+export function query<T extends GenericObject, P extends QueryParams<T>>(
   data: T[],
   params: P,
 ): QueryResult<T, P> {

src/types.ts

@@ -1,6 +1,30 @@
 export type Primitive = string | number | symbol
 export type GenericObject = Record<Primitive, unknown>
 
+export type NestedPaths<T> = T extends Array<infer U>
+  ? `${NestedPaths<U>}`
+  : T extends object
+    ? {
+        [K in keyof T & (string | number)]: K extends string
+          ? `${K}` | `${K}.${NestedPaths<T[K]>}`
+          : string;
+      }[keyof T & (string | number)]
+    : string
+
+export type NestedPathsForType<T, P> = T extends Array<infer U>
+  ? NestedPathsForType<U, P>
+  : T extends object
+    ? {
+        [K in keyof T & (string | number)]: K extends string
+          ? T[K] extends P
+            ? `${K}` | `${K}.${NestedPathsForType<T[K], P>}`
+            : T[K] extends object
+              ? `${K}.${NestedPathsForType<T[K], P>}`
+              : string
+          : string;
+      }[keyof T & (string | number)]
+    : string
+
 export type Operator = 'AND' | 'OR' | (() => 'AND' | 'OR')
 
 export type FilterMatchMode =
@@ -44,40 +68,44 @@ export type MatchModeCore = ({
   params: ObjectMapFilterParams | ((value: any) => ObjectMapFilterParams)
 })
 
-export type QueryFilter = {
-  key: string
+export type QueryFilter<Paths extends string = string> = {
+  key: Paths
   value: any
   operator?: Operator
 } & MatchModeCore
 
-export interface QueryFilterGroup {
+export interface QueryFilterGroup<Paths extends string = string> {
   operator: Operator
-  filters: QueryFilter[]
+  filters: QueryFilter<Paths>[]
 }
 
-export type FilterOptions = Array<QueryFilterGroup> | Array<QueryFilter>
+export type FilterOptions<Paths extends string = string> = Array<QueryFilterGroup<Paths>> | Array<QueryFilter<Paths>>
 
-export interface SearchOptions {
+export interface SearchOptions<Paths extends string = string> {
   value: string
-  keys: string[] | Array<{ key: string, caseSensitive?: boolean }>
+  keys: Paths[] | Array<{ key: Paths, caseSensitive?: boolean }>
   caseSensitive?: boolean
 }
 
-export interface SortOptions {
-  key: string
+export interface SortOption<Paths extends string = string> {
+  key: Paths
   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
+export interface QueryParams<
+  T extends GenericObject = GenericObject,
+  Paths extends NestedPaths<T> = NestedPaths<T>,
+  PrimitivePath extends string = NestedPathsForType<T, string | number | null | boolean | undefined>,
+> {
+  sort?: SortOption<PrimitivePath> | Array<SortOption<PrimitivePath>>
+  search?: SearchOptions<PrimitivePath>
+  filter?: FilterOptions<Paths>
   limit?: 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[] }
+export type QueryResult<T extends GenericObject, P extends QueryParams<T>> = P extends { limit: number } ? { totalRows: number, totalPages: number, rows: T[], unpaginatedRows: T[] } : { rows: T[] }
 
 export interface MatchModeProcessorMap {
   equals: ({ value, filter }: { value: any, filter: any }) => boolean

test/index.test.ts

@@ -38,13 +38,13 @@ for (const fixture of fixtures) {
 describe('performance check', () => {
   // VAL BETWEEN 1 & 100
   const getValue = () => Math.floor(Math.random() * 100)
-  const items = Array.from({ length: 1000000 }, (_, i) => ({ id: i, name: `Item ${i}`, value: getValue() }))
+  const items = Array.from({ length: 1000000 }, (_, i) => ({ id: i, name: `Item ${i}`, value: getValue(), other: [], address: { city: 'New York', country: 'USA' } }))
   it('query 1M rows - paginate + sort + search + filter in less than 500ms', () => {
     const start = performance.now()
     query(items, {
       limit: 10,
       sort: {
-        key: 'id',
+        key: 'address.country',
         dir: 'asc',
       },
       search: {