quetch 0.30.0 → 0.31.0

package/lib/tools/sortItemList.ts

@@ -1,73 +1,53 @@
+import { EMPTY_OBJECT } from "unchangeable";
+
 import type { Order, QuerySettings } from "../types";
 
-import { escapeRegex } from "./escapeRegex.js";
 import { get } from "./get.js";
 import { normalizeOrder } from "./normalizeOrder.js";
-import { sameField } from "./sameField.js";
 
 /**
  * Sorts provided `value` array according to the `orderList`.
  *
- * @param orderList The order to use for sorting.
- * @param value The array to sort.
- * @param settings Optional query settings.
+ * @param orderList - The order to use for sorting.
+ * @param value - The array to sort.
+ * @param settings - Optional query settings.
  * @returns A new sorted array.
  */
 export function sortItemList<T>(
-  orderList: readonly Order<T>[] | undefined,
+  orderList: NoInfer<readonly Order<T>[]> | undefined,
   value: readonly T[],
   settings?: QuerySettings<T>,
 ) {
-  const {
-    pathField,
-    pathFieldSeparator = "/",
-    pathFieldSeparatorEscape,
-  } = settings ?? {};
   if (orderList === undefined || orderList.length === 0) {
     return value;
   }
+  const { compareFieldValues } = settings ?? EMPTY_OBJECT;
   const normalizedOrder = orderList.map(normalizeOrder);
-  const fieldSeparatorRegexp =
-    pathField == null || pathFieldSeparator == null
-      ? null
-      : new RegExp(
-          !pathFieldSeparatorEscape
-            ? escapeRegex(pathFieldSeparator)
-            : `(?<!${escapeRegex(pathFieldSeparatorEscape)})${escapeRegex(pathFieldSeparator)}`,
-          "g",
-        );
   return value.toSorted((a, b) => {
     for (let index = 0; index < normalizedOrder.length; index++) {
       const { field, descending } = normalizedOrder[index]!;
-      const valueA = get(a, field as any);
-      const valueB = get(b, field as any);
+      const valueA = get(a, field);
+      const valueB = get(b, field);
       if (valueA === valueB) {
         continue;
       }
-      if (fieldSeparatorRegexp != null && sameField(field, pathField!)) {
-        if (valueA == null) {
-          return valueB == null ? 0 : descending ? 1 : -1;
-        }
-        if (valueB == null) {
-          return descending ? -1 : 1;
-        }
-        const normalizedA = (valueA as string).replaceAll(
-          fieldSeparatorRegexp,
-          "\x00",
-        );
-        const normalizedB = (valueB as string).replaceAll(
-          fieldSeparatorRegexp,
-          "\x00",
-        );
-        if (normalizedA > normalizedB) {
+      if (valueA == null) {
+        return valueB == null ? 0 : descending ? 1 : -1;
+      }
+      if (valueB == null) {
+        return descending ? -1 : 1;
+      }
+      const comparison = compareFieldValues?.(field, valueA, valueB);
+      if (comparison === undefined) {
+        if (valueA > valueB) {
           return descending ? -1 : 1;
         }
         return descending ? 1 : -1;
       }
-      if (valueA > valueB) {
-        return descending ? -1 : 1;
+      if (comparison === 0) {
+        continue;
       }
-      return descending ? 1 : -1;
+      return descending ? -comparison : comparison;
     }
     return 0;
   });

package/lib/tools/testFilter.test.ts

@@ -5,6 +5,7 @@ import { SELF } from "../constants.js";
 import type { FilterChildren } from "../types.js";
 
 import { filterFromValue } from "./filterFromValue.js";
+import { querySettings } from "./querySettings.js";
 import { testFilter } from "./testFilter.js";
 
 test("tests filter lists", () => {
@@ -360,27 +361,37 @@ test("tests filter with children predicates", () => {
       { id: "a" },
     ),
   ).toBe(true);
+
+  // Always true if `transformFilterChildren` is not provided, to avoid false negatives
   expect(
     testFilter({ operator: "notChildren", value: { id: "a" } }, { id: "a/b" }),
+  ).toBe(true);
+  expect(
+    testFilter(
+      { operator: "notChildren", value: { id: "a" } },
+      { id: "a/b" },
+      querySettings({ pathField: "id" }),
+    ),
   ).toBe(false);
+
   expect(
     testFilter(
       { operator: "children", value: { path: ".a" } },
       { path: ".a.b" },
-      {
+      querySettings({
         pathField: "path",
         pathFieldSeparator: ".",
-      },
+      }),
     ),
   ).toBe(true);
   expect(
     testFilter(
       { operator: "notChildren", value: { path: ".a" } },
       { path: ".a.b" },
-      {
+      querySettings({
         pathField: "path",
         pathFieldSeparator: ".",
-      },
+      }),
     ),
   ).toBe(false);
   const filterChildren: FilterChildren<{ path: string }> = {
@@ -397,7 +408,7 @@ test("tests filter with children predicates", () => {
             field: "path",
             operator: "startWith",
             value: `.${filter.value?.path}.`,
-          };
+          } as const;
         },
       },
     ),
@@ -415,36 +426,48 @@ test("tests filter with children predicates", () => {
             field: "path",
             operator: "startWith",
             value: `.${filter.value?.path}.`,
-          };
+          } as const;
         },
       },
     ),
   ).toBe(true);
   expect(filterChildren[CACHE]).toBeDefined();
   expect(
-    testFilter({ operator: "children", value: { id: "b" } }, { id: "a/b" }),
+    testFilter(
+      { operator: "children", value: { id: "b" } },
+      { id: "a/b" },
+      querySettings({
+        pathField: "id",
+      }),
+    ),
   ).toBe(false);
   expect(
-    testFilter({ operator: "notChildren", value: { id: "b" } }, { id: "a/b" }),
+    testFilter(
+      { operator: "notChildren", value: { id: "b" } },
+      { id: "a/b" },
+      querySettings({
+        pathField: "id",
+      }),
+    ),
   ).toBe(true);
   expect(
     testFilter(
       { operator: "children", value: { path: "ba" } },
       { path: ".a.b" },
-      {
+      querySettings({
         pathField: "path",
         pathFieldSeparator: ".",
-      },
+      }),
     ),
   ).toBe(false);
   expect(
     testFilter(
       { operator: "notChildren", value: { path: "ba" } },
       { path: ".a.b" },
-      {
+      querySettings({
         pathField: "path",
         pathFieldSeparator: ".",
-      },
+      }),
     ),
   ).toBe(true);
 });

package/lib/tools/transformerFilterChildren.ts

@@ -4,32 +4,12 @@ import type {
   FieldFiltered,
   FilterChildren,
   FilterStringMatch,
+  NormalizedPathFieldSettings,
 } from "../types";
 
 import { filterChildren } from "./filterChildren.js";
 import { get } from "./get.js";
 
-export type TransformerFilterChildrenOptions<T> = {
-  /**
-   * Path to the field that contains the path value of an item, used for displaying items in a tree.
-   *
-   * @default "path"
-   */
-  pathField?: FieldFiltered<T, string>;
-  /**
-   * String used to escape the separator.
-   *
-   * @default "\\"
-   */
-  pathFieldSeparatorEscape?: string;
-  /**
-   * Maps path fields to a string used to separate the path nodes of a field value.
-   *
-   * @default "/"
-   */
-  pathFieldSeparator?: string;
-};
-
 /**
  * Returns a function that transforms a `FilterChildren` into a `FilterStringMatch`.
  *
@@ -39,13 +19,10 @@ export type TransformerFilterChildrenOptions<T> = {
 export function transformerFilterChildren<T>({
   pathField = "path" as FieldFiltered<T, string>,
   pathFieldSeparator = "/",
-}: TransformerFilterChildrenOptions<T> = EMPTY_OBJECT) {
+}: NormalizedPathFieldSettings<T> = EMPTY_OBJECT) {
   return (filter: FilterChildren<T>): FilterStringMatch<T> => {
     const { value, minDepth = 1, maxDepth = Infinity } = filter;
-    if (value === undefined) {
-      throw new Error("FilterChildren must have a value");
-    }
-    const parentPath = get(value, pathField as any) as string;
+    const parentPath = (get(value, pathField as any) ?? "") as string;
     return filterChildren(
       parentPath,
       pathField,

package/lib/tools.ts

@@ -1,4 +1,5 @@
 // File automatically generated by `vite-plugin-module-list`
+export { comparatorFieldValues } from "./tools/comparatorFieldValues.js";
 export { cork } from "./tools/cork.js";
 export { defineCheckQuery } from "./tools/defineCheckQuery.js";
 export { defineCustomFetch } from "./tools/defineCustomFetch.js";
@@ -13,6 +14,7 @@ export { intrinsicFilter } from "./tools/intrinsicFilter.js";
 export { isFilterGroup } from "./tools/isFilterGroup.js";
 export { normalizeOrder } from "./tools/normalizeOrder.js";
 export { queryItemList } from "./tools/queryItemList.js";
+export { querySettings } from "./tools/querySettings.js";
 export { reverseOrder } from "./tools/reverseOrder.js";
 export { sameField } from "./tools/sameField.js";
 export { sortItemList } from "./tools/sortItemList.js";

package/lib/types/CombineUnion.ts

@@ -1,17 +1,19 @@
 import type { KeyFromUnion } from "./KeyFromUnion";
 import type { Primitive } from "./Primitive";
 
-export type CombineUnion<U> = [0] extends [1 & U]
-  ? any
-  : [U] extends [Function | readonly Function[]]
-    ? undefined
-    : [U] extends [Primitive]
-      ? U
-      : [U] extends readonly [Array<any>]
+export type CombineUnion<U> = [unknown] extends [U]
+  ? unknown
+  : [0] extends [1 & U]
+    ? any
+    : [U] extends [Function | readonly Function[]]
+      ? undefined
+      : [U] extends [Primitive]
         ? U
-        : {
-            [K in KeyFromUnion<U>]: Continue<Combine<U, K>>;
-          };
+        : [U] extends readonly [Array<any>]
+          ? U
+          : {
+              [K in KeyFromUnion<U>]: Continue<Combine<U, K>>;
+            };
 
 type Combine<U, K extends string | number | symbol> = Exclude<
   Extract<U, { [k in K]?: any }>[K],

package/lib/types/Decrement.ts

@@ -0,0 +1,5 @@
+type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+type NextDigit = [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+
+export type Decrement<D> = D extends Digit ? NextDigit[D] : -1;

package/lib/types/DepthLimit.ts

@@ -0,0 +1 @@
+export type DepthLimit = 4;

package/lib/types/FieldKey.ts

@@ -1,5 +1,10 @@
 import type { SELF } from "../constants/SELF.ts";
 
+import type { Key } from "./Key.ts";
 import type { Primitive } from "./Primitive";
 
-export type FieldKey<T> = T extends Primitive ? typeof SELF : keyof T;
+export type FieldKey<T> = T extends Primitive
+  ? typeof SELF
+  : [unknown] extends [T]
+    ? Key
+    : keyof T;

package/lib/types/Get.ts

@@ -1,14 +1,22 @@
+import type { Decrement } from "./Decrement";
+import type { DepthLimit } from "./DepthLimit";
 import type { Path } from "./Path";
 
 /**
  * Returns the type of the property at the specified `P` path.
  */
-export type Get<T, P> = [P] extends [readonly [infer K, ...infer R]]
-  ? K extends keyof T
-    ? R extends Path<T[K]>
-      ? Get<T[K], R>
-      : T[K]
-    : never
-  : [P] extends [keyof T]
-    ? T[P]
-    : T;
+export type Get<T, P, D = DepthLimit> = [unknown] extends [T]
+  ? unknown
+  : [0] extends [1 & T]
+    ? any
+    : D extends -1
+      ? any
+      : [P] extends [readonly [infer K, ...infer R]]
+        ? K extends keyof T
+          ? R extends Path<T[K]>
+            ? Get<T[K], R, Decrement<D>>
+            : T[K]
+          : never
+        : [P] extends [keyof T]
+          ? T[P]
+          : T;

package/lib/types/KeyFiltered.ts

@@ -7,14 +7,18 @@ type SymbolSelf = typeof SELF;
 /**
  * Returns union of keys whose mapped value extend the provided `P` type.
  */
-export type KeyFiltered<T, P> = [0] extends [1 & T]
+export type KeyFiltered<T, P> = [unknown] extends [T]
   ? Key | SymbolSelf
-  : T extends string | number | boolean | bigint | symbol
-    ? T extends P
-      ? SymbolSelf
-      : never
-    : T extends object
-      ? keyof {
-          [K in keyof T as Extract<T[K], P> extends never ? never : K]-?: T[K];
-        }
-      : never;
+  : [0] extends [1 & T]
+    ? Key | SymbolSelf
+    : T extends string | number | boolean | bigint | symbol
+      ? T extends P
+        ? SymbolSelf
+        : never
+      : T extends object
+        ? keyof {
+            [K in keyof T as Extract<T[K], P> extends never
+              ? never
+              : K]-?: T[K];
+          }
+        : never;

package/lib/types/NormalizedPathFieldSettings.ts

@@ -0,0 +1,25 @@
+import type { FieldFiltered } from "./FieldFiltered";
+
+/**
+ * Settings for fields that contain path values of items, used for displaying items in a tree.
+ */
+export type NormalizedPathFieldSettings<T> = {
+  /**
+   * Path to the field that contains the path value of an item, used for displaying items in a tree.
+   *
+   * @default "path"
+   */
+  pathField?: FieldFiltered<T, string>;
+  /**
+   * String used to escape the separator.
+   *
+   * @default "\\"
+   */
+  pathFieldSeparatorEscape?: string;
+  /**
+   * Maps path fields to a string used to separate the path nodes of a field value.
+   *
+   * @default "/"
+   */
+  pathFieldSeparator?: string;
+};

package/lib/types/Path.ts

@@ -1,19 +1,22 @@
-import type { Increment } from "./Increment";
+import type { Decrement } from "./Decrement";
+import type { DepthLimit } from "./DepthLimit";
 import type { Key } from "./Key";
 import type { Primitive } from "./Primitive";
 
-export type Path<T, D = 7> = [0] extends [1 & T]
+export type Path<T, D = DepthLimit> = [unknown] extends [T]
   ? readonly (Key | never)[]
-  : D extends -1
-    ? never
-    : T extends Primitive
-      ? readonly never[]
-      : T extends Array<infer P>
-        ? readonly [number] | readonly [number, ...Path<P, Increment<D>>]
-        : T extends object
-          ? {
-              [K in keyof T]:
-                | readonly [K]
-                | readonly [K, ...Path<T[K], Increment<D>>];
-            }[keyof T]
-          : never;
+  : [0] extends [1 & T]
+    ? readonly (Key | never)[]
+    : D extends -1
+      ? never
+      : T extends Primitive
+        ? readonly never[]
+        : T extends Array<infer P>
+          ? readonly [number] | readonly [number, ...Path<P, Decrement<D>>]
+          : T extends object
+            ? {
+                [K in keyof T]:
+                  | readonly [K]
+                  | readonly [K, ...Path<T[K], Decrement<D>>];
+              }[keyof T]
+            : never;

package/lib/types/PathFiltered.ts

@@ -1,20 +1,23 @@
-import type { Increment } from "./Increment";
+import type { Decrement } from "./Decrement";
+import type { DepthLimit } from "./DepthLimit";
 import type { Key } from "./Key";
 
-export type PathFiltered<T, P, D = 7> = [0] extends [1 & T]
+export type PathFiltered<T, P, D = DepthLimit> = [unknown] extends [T]
   ? readonly (Key | never)[]
-  : D extends -1
-    ? never
-    : T extends P
-      ? readonly never[]
-      : T extends ReadonlyArray<infer I>
-        ? Extract<I, P> extends never
-          ? readonly [number, ...PathFiltered<I, P, Increment<D>>]
-          : readonly [number]
-        : T extends object
-          ? {
-              [K in keyof T]: Extract<T[K], P> extends never
-                ? readonly [K, ...PathFiltered<T[K], P, Increment<D>>]
-                : readonly [K];
-            }[keyof T]
-          : never;
+  : [0] extends [1 & T]
+    ? readonly (Key | never)[]
+    : D extends -1
+      ? never
+      : T extends P
+        ? readonly never[]
+        : T extends ReadonlyArray<infer I>
+          ? Extract<I, P> extends never
+            ? readonly [number, ...PathFiltered<I, P, Decrement<D>>]
+            : readonly [number]
+          : T extends object
+            ? {
+                [K in keyof T]: Extract<T[K], P> extends never
+                  ? readonly [K, ...PathFiltered<T[K], P, Decrement<D>>]
+                  : readonly [K];
+              }[keyof T]
+            : never;

package/lib/types/QuerySettings.ts

@@ -1,4 +1,4 @@
-import type { FieldFiltered } from "./FieldFiltered";
+import type { Field } from "./Field";
 import type { FilterChildren } from "./FilterChildren";
 import type { IntrinsicFilter } from "./IntrinsicFilter";
 
@@ -6,22 +6,6 @@ import type { IntrinsicFilter } from "./IntrinsicFilter";
  * Settings to use when doing a query.
  */
 export type QuerySettings<T> = {
-  /**
-   * Path to the field that contains the path value of an item, used for displaying items in a tree.
-   */
-  pathField?: FieldFiltered<T, string>;
-  /**
-   * String used to escape the separator.
-   *
-   * @default "\\"
-   */
-  pathFieldSeparatorEscape?: string;
-  /**
-   * Maps path fields to a string used to separate the path nodes of a field value.
-   *
-   * @default "/"
-   */
-  pathFieldSeparator?: string;
   /**
    * Returns a filter that captures the items expressed by the provided `FilterChildren`. The return filter cannot use filters of type `FilterChildren` or `FilterContext`.
    *
@@ -29,6 +13,21 @@ export type QuerySettings<T> = {
    * @returns A filter that captures the items expressed by the provided `FilterChildren`.
    */
   transformFilterChildren?: (filter: FilterChildren<T>) => IntrinsicFilter<T>;
+  /**
+   * Compares two values of a field for sorting purposes. If not provided, values are compared using the default comparison operators (`>`, `<`, `===`).
+   *
+   * This function is called only when both `a` and `b` are defined and different. If it returns `undefined`, the default comparison operators are used as a fallback.
+   *
+   * @param a - The first value to compare.
+   * @param b - The second value to compare.
+   * @param field - The field for which the values are compared.
+   * @returns `-1` if `a` should be sorted before `b`, `1` if `a` should be sorted after `b`, `0` if they are considered equal, or `undefined` to use the default comparison operators.
+   */
+  compareFieldValues?<T>(
+    field: Field<T>,
+    a: NonNullable<any>,
+    b: NonNullable<any>,
+  ): -1 | 0 | 1 | undefined;
   /**
    * Abort signal to abort the query.
    */

package/lib/types.ts

@@ -6,6 +6,8 @@ export type { Context } from "./types/Context";
 export type { CustomFetch } from "./types/CustomFetch";
 export type { CustomFieldAggregateMap } from "./types/CustomFieldAggregateMap";
 export type { CustomFieldMap } from "./types/CustomFieldMap";
+export type { Decrement } from "./types/Decrement";
+export type { DepthLimit } from "./types/DepthLimit";
 export type { Field } from "./types/Field";
 export type { FieldFiltered } from "./types/FieldFiltered";
 export type { FieldFunction } from "./types/FieldFunction";
@@ -30,7 +32,6 @@ export type { Get } from "./types/Get";
 export type { Group } from "./types/Group";
 export type { Handler } from "./types/Handler";
 export type { Immutable } from "./types/Immutable";
-export type { Increment } from "./types/Increment";
 export type { InjectCustomFields } from "./types/InjectCustomFields";
 export type { IntersectUnion } from "./types/IntersectUnion";
 export type { IntrinsicFilter } from "./types/IntrinsicFilter";
@@ -41,6 +42,7 @@ export type { KeyFiltered } from "./types/KeyFiltered";
 export type { KeyFromUnion } from "./types/KeyFromUnion";
 export type { Locale } from "./types/Locale";
 export type { NextHandler } from "./types/NextHandler";
+export type { NormalizedPathFieldSettings } from "./types/NormalizedPathFieldSettings";
 export type { Order } from "./types/Order";
 export type { OrderNormalized } from "./types/OrderNormalized";
 export type { Parameters } from "./types/Parameters";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quetch",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "type": "module",
   "main": "./dist/main.js",
   "exports": {
@@ -39,7 +39,7 @@
     "lint": "npm run lint:ts",
     "lint:fix": "npm run lint:ts:fix",
     "lint:ts": "eslint . && tsc --project tsconfig.package.json --noEmit",
-    "lint:types": "tsc --project tsconfig.package.json --noEmit",
+    "lint:types:trace": "tsc --project tsconfig.package.json --noEmit --generateTrace ./trace",
     "lint:ts:fix": "eslint --fix .",
     "release:init": "npm publish --access=public",
     "release:patch": "npm version patch && git push origin --follow-tags && npm publish",

package/dist/types/Increment.d.ts

@@ -1,4 +0,0 @@
-type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
-type NextDigit = [1, 2, 3, 4, 5, 6, 7, 8, 9, -1];
-export type Increment<D> = D extends Digit ? NextDigit[D] : -1;
-export {};

package/dist/types/Increment.js

@@ -1 +0,0 @@
-//# sourceMappingURL=Increment.js.map

package/dist/types/Increment.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Increment.js","sourceRoot":"","sources":["../../lib/types/Increment.ts"],"names":[],"mappings":""}

package/doc/type-aliases/Increment.md

@@ -1,17 +0,0 @@
-[**quetch**](../README.md)
-
-***
-
-[quetch](../README.md) / Increment
-
-# Type Alias: Increment\<D\>
-
-> **Increment**\<`D`\>: `D` *extends* `Digit` ? `NextDigit`\[`D`\] : `-1`
-
-## Type Parameters
-
-• **D**
-
-## Defined in
-
-[lib/types/Increment.ts:5](https://github.com/nevoland/quetch/blob/94f546831241bf41f83cf97787b7e923c8cf7824/lib/types/Increment.ts#L5)

package/lib/types/Increment.ts

@@ -1,5 +0,0 @@
-type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
-
-type NextDigit = [1, 2, 3, 4, 5, 6, 7, 8, 9, -1];
-
-export type Increment<D> = D extends Digit ? NextDigit[D] : -1;