quetch 0.30.0 → 0.31.1

package/lib/tools/comparatorFieldValues.ts

@@ -0,0 +1,46 @@
+import { EMPTY_OBJECT } from "unchangeable";
+
+import type {
+  FieldFiltered,
+  NormalizedPathFieldSettings,
+  QuerySettings,
+} from "../types";
+
+import { escapeRegex } from "./escapeRegex.js";
+import { sameField } from "./sameField.js";
+
+/**
+ * Returns a function that transforms a `FilterChildren` into a `FilterStringMatch`.
+ *
+ * @param options - Options for the transformer.
+ * @returns A function that takes a `FilterChildren` and returns a `FilterStringMatch` that matches the paths of the children of the item specified in the `FilterChildren`.
+ */
+export function comparatorFieldValues<T>({
+  pathField = "path" as FieldFiltered<T, string>,
+  pathFieldSeparator = "/",
+  pathFieldSeparatorEscape = "\\",
+}: NormalizedPathFieldSettings<T> = EMPTY_OBJECT): QuerySettings<T>["compareFieldValues"] {
+  const fieldSeparatorRegexp = new RegExp(
+    !pathFieldSeparatorEscape
+      ? escapeRegex(pathFieldSeparator)
+      : `(?<!${escapeRegex(pathFieldSeparatorEscape)})${escapeRegex(pathFieldSeparator)}`,
+    "g",
+  );
+  return (field, a, b) => {
+    if (!sameField(field, pathField)) {
+      return undefined;
+    }
+    const normalizedA = (a as string).replaceAll?.(
+      fieldSeparatorRegexp,
+      "\x00",
+    );
+    const normalizedB = (b as string).replaceAll?.(
+      fieldSeparatorRegexp,
+      "\x00",
+    );
+    if (normalizedA > normalizedB) {
+      return 1;
+    }
+    return -1;
+  };
+}

package/lib/tools/filterChildren.ts

@@ -10,6 +10,7 @@ import { escapeRegex } from "./escapeRegex.js";
  * @param minDepth - The minimum depth of the child items relative to the parent.
  * @param maxDepth - The maximum depth of the child items relative to the parent.
  * @param pathSeparator - The character used to separate path segments.
+ * @param not - If true, generates a filter that matches items that are not children of the given parent path.
  * @returns A filter that can be used to match child items.
  */
 export function filterChildren<T>(
@@ -18,6 +19,7 @@ export function filterChildren<T>(
   minDepth = 1,
   maxDepth = Infinity,
   pathSeparator = "/",
+  not = false,
 ): FilterStringMatch<T> {
   const escapedSeparator = escapeRegex(pathSeparator);
   const segment = `${escapedSeparator}[^${escapedSeparator}]+`;
@@ -27,7 +29,7 @@ export function filterChildren<T>(
       : `{${minDepth},${maxDepth === Infinity ? "" : maxDepth}}`;
   return {
     field: pathFieldKey,
-    operator: "match",
+    operator: not ? "notMatch" : "match",
     value: `^${escapeRegex(parentPath)}(?:${segment})${quantifier}$`,
   };
 }

package/lib/tools/get.ts

@@ -1,5 +1,7 @@
 import { SELF } from "../constants/SELF.js";
-import type { Get, Path } from "../types";
+import type { Field, Get } from "../types";
+
+const { isArray } = Array;
 
 /**
  * Gets the property value of the given `value` at the specified `path` (an array of object property names or array indexes).
@@ -7,11 +9,11 @@ import type { Get, Path } from "../types";
  * If the `path` is a string, it is considered as a path with one item.
  * If the `path` leads to an unknown property, returns `undefined`.
  *
- * @param value The value from which to get the property value.
- * @param path The path leading to the property value or a property name or `undefined`.
+ * @param value - The value from which to get the property value.
+ * @param path - The path leading to the property value or a property name or `undefined`.
  * @returns The property value found at the given path, or `undefined` if it cannot be found.
  */
-export function get<const T, const P extends Path<T> | keyof T>(
+export function get<const T, const P extends Field<T>>(
   value: T,
   path?: P,
 ): Get<T, P> {
@@ -24,6 +26,9 @@ export function get<const T, const P extends Path<T> | keyof T>(
     case "symbol":
       return (value as any)?.[path];
     default: {
+      if (!isArray(path)) {
+        return value as any;
+      }
       switch (path.length as number) {
         case 0:
           return value as any;

package/lib/tools/querySettings.ts

@@ -0,0 +1,20 @@
+import { EMPTY_OBJECT } from "unchangeable";
+
+import type { NormalizedPathFieldSettings, QuerySettings } from "../types";
+
+import { comparatorFieldValues } from "./comparatorFieldValues.js";
+import { transformerFilterChildren } from "./transformerFilterChildren.js";
+/**
+ * Returns query settings for path fields.
+ *
+ * @param settings - Settings for normalizing path fields.
+ * @returns Query settings for path fields.
+ */
+export function querySettings<T>(
+  settings: NormalizedPathFieldSettings<T> = EMPTY_OBJECT,
+): QuerySettings<T> {
+  return {
+    compareFieldValues: comparatorFieldValues(settings),
+    transformFilterChildren: transformerFilterChildren(settings),
+  };
+}

package/lib/tools/sortItemList.test.ts

@@ -1,5 +1,6 @@
 import { expect, test } from "vitest";
 
+import { querySettings } from "./querySettings.js";
 import { sortItemList } from "./sortItemList.js";
 
 test("sorts items", () => {
@@ -76,10 +77,7 @@ test("sorts items with separator setting", () => {
         { path: "a\\/b.c" },
         { path: "a.b/c" },
       ],
-      {
-        pathField: "path",
-        pathFieldSeparator: "/",
-      },
+      querySettings(),
     ),
   ).toEqual([
     { path: "a" },
@@ -104,10 +102,7 @@ test("sorts items with separator setting", () => {
         { path: "a\\/b.c" },
         { path: "a.b/c" },
       ],
-      {
-        pathField: "path",
-        pathFieldSeparator: "/",
-      },
+      querySettings(),
     ),
   ).toEqual([
     { path: "a" },
@@ -119,4 +114,32 @@ test("sorts items with separator setting", () => {
     { path: "a.b.c" },
     { path: "a\\/b.c" },
   ]);
+
+  expect(
+    sortItemList(
+      [{ descending: false, field: "path" }],
+      [
+        { path: "a" },
+        { path: "a/b" },
+        { path: "a.b" },
+        { path: "a/b/c" },
+        { path: "a.b.c" },
+        { path: "a/b.c" },
+        { path: "a\\.b.c" },
+        { path: "a.b/c" },
+      ],
+      querySettings({
+        pathFieldSeparator: ".",
+      }),
+    ),
+  ).toEqual([
+    { path: "a" },
+    { path: "a.b" },
+    { path: "a.b.c" },
+    { path: "a.b/c" },
+    { path: "a/b" },
+    { path: "a/b.c" },
+    { path: "a/b/c" },
+    { path: "a\\.b.c" },
+  ]);
 });

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/testFilter.ts

@@ -121,7 +121,6 @@ export function testFilter<T>(
     }
     case "children":
     case "notChildren": {
-      const not = filter.operator[0] === "n";
       if (filter[CACHE] === undefined) {
         switch (true) {
           case settings?.transformFilterChildren !== undefined:
@@ -133,7 +132,7 @@ export function testFilter<T>(
           }
         }
       }
-      return negate(testFilter(filter[CACHE], value, settings), not);
+      return testFilter(filter[CACHE], value, settings);
     }
     case "custom": {
       return filter.value(value);

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,19 +19,17 @@ 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,
       minDepth,
       maxDepth,
       pathFieldSeparator,
+      filter.operator[0] === "n",
     );
   };
 }

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;