quetch 0.29.0 → 0.30.0

package/doc/type-aliases/Store.md

@@ -68,4 +68,4 @@
 
 ## Defined in
 
-[lib/types/Store.ts:2](https://github.com/nevoland/quetch/blob/439120295bc3ab3895611a5a04d7281d9d40fc45/lib/types/Store.ts#L2)
+[lib/types/Store.ts:2](https://github.com/nevoland/quetch/blob/94f546831241bf41f83cf97787b7e923c8cf7824/lib/types/Store.ts#L2)

package/doc/type-aliases/Value.md

@@ -36,4 +36,4 @@ Path leading to the value.
 
 ## Defined in
 
-[lib/types/Value.ts:6](https://github.com/nevoland/quetch/blob/439120295bc3ab3895611a5a04d7281d9d40fc45/lib/types/Value.ts#L6)
+[lib/types/Value.ts:6](https://github.com/nevoland/quetch/blob/94f546831241bf41f83cf97787b7e923c8cf7824/lib/types/Value.ts#L6)

package/doc/type-aliases/ValueMap.md

@@ -18,4 +18,4 @@ Maps the properties of the provided value `T` to a specific value `V`.
 
 ## Defined in
 
-[lib/types/ValueMap.ts:6](https://github.com/nevoland/quetch/blob/439120295bc3ab3895611a5a04d7281d9d40fc45/lib/types/ValueMap.ts#L6)
+[lib/types/ValueMap.ts:6](https://github.com/nevoland/quetch/blob/94f546831241bf41f83cf97787b7e923c8cf7824/lib/types/ValueMap.ts#L6)

package/doc/variables/CACHE.md

@@ -10,4 +10,4 @@
 
 ## Defined in
 
-[lib/constants/CACHE.ts:1](https://github.com/nevoland/quetch/blob/439120295bc3ab3895611a5a04d7281d9d40fc45/lib/constants/CACHE.ts#L1)
+[lib/constants/CACHE.ts:1](https://github.com/nevoland/quetch/blob/94f546831241bf41f83cf97787b7e923c8cf7824/lib/constants/CACHE.ts#L1)

package/doc/variables/FILTER_ANY.md

@@ -16,4 +16,4 @@
 
 ## Defined in
 
-[lib/constants/FILTER\_ANY.ts:1](https://github.com/nevoland/quetch/blob/439120295bc3ab3895611a5a04d7281d9d40fc45/lib/constants/FILTER_ANY.ts#L1)
+[lib/constants/FILTER\_ANY.ts:1](https://github.com/nevoland/quetch/blob/94f546831241bf41f83cf97787b7e923c8cf7824/lib/constants/FILTER_ANY.ts#L1)

package/doc/variables/FILTER_NONE.md

@@ -16,4 +16,4 @@
 
 ## Defined in
 
-[lib/constants/FILTER\_NONE.ts:1](https://github.com/nevoland/quetch/blob/439120295bc3ab3895611a5a04d7281d9d40fc45/lib/constants/FILTER_NONE.ts#L1)
+[lib/constants/FILTER\_NONE.ts:1](https://github.com/nevoland/quetch/blob/94f546831241bf41f83cf97787b7e923c8cf7824/lib/constants/FILTER_NONE.ts#L1)

package/doc/variables/SELF.md

@@ -10,4 +10,4 @@
 
 ## Defined in
 
-[lib/constants/SELF.ts:1](https://github.com/nevoland/quetch/blob/439120295bc3ab3895611a5a04d7281d9d40fc45/lib/constants/SELF.ts#L1)
+[lib/constants/SELF.ts:1](https://github.com/nevoland/quetch/blob/94f546831241bf41f83cf97787b7e923c8cf7824/lib/constants/SELF.ts#L1)

package/lib/tools/intrinsicFilter.ts

@@ -0,0 +1,30 @@
+import type { Filter, IntrinsicFilter, QuerySettings } from "../types";
+
+/**
+ * Transforms a filter into an intrinsic filter by replacing `children` and `notChildren` filters with their transformed versions from the query settings.
+ *
+ * @param filter - The filter to transform.
+ * @param settings - The query settings that may contain a `transformFilterChildren` function to transform `children` and `notChildren` filters.
+ * @returns The transformed intrinsic filter.
+ */
+export function intrinsicFilter<T>(
+  settings: Required<Pick<QuerySettings<T>, "transformFilterChildren">>,
+  filter: Filter<T>,
+): IntrinsicFilter<T> {
+  switch (filter.operator) {
+    case "any":
+    case "all":
+    case "none":
+      return {
+        ...filter,
+        value: filter.value?.map((filter) =>
+          intrinsicFilter(settings, filter),
+        ) as readonly Filter<T>[],
+      };
+    case "children":
+    case "notChildren":
+      return settings.transformFilterChildren(filter)!;
+    default:
+      return filter;
+  }
+}

package/lib/tools/queryItemList.ts

@@ -83,7 +83,7 @@ export function queryItemList<T, const Q extends Query<T>>(
         );
       }
       // Sort
-      result = sortItemList(order, result, query.settings);
+      result = sortItemList(order, result, settings);
       // Slice
       if (offset !== 0 || limit !== Infinity) {
         result = result.slice(offset, offset + limit);
@@ -125,7 +125,7 @@ export function queryItemList<T, const Q extends Query<T>>(
             );
           }
           // Sort
-          result = sortItemList(order, result, query.settings);
+          result = sortItemList(order, result, settings);
           // Slice
           if (offset !== 0 || limit !== Infinity) {
             result = result.slice(offset, offset + limit);

package/lib/tools/testFilter.test.ts

@@ -2,7 +2,7 @@ import { expect, test } from "vitest";
 
 import { CACHE } from "../constants/CACHE.js";
 import { SELF } from "../constants.js";
-import type { FilterChildren, FilterContext } from "../types.js";
+import type { FilterChildren } from "../types.js";
 
 import { filterFromValue } from "./filterFromValue.js";
 import { testFilter } from "./testFilter.js";
@@ -77,7 +77,7 @@ test("tests filter lists", () => {
           { field: "a", operator: "equal", value: "foo" },
           { field: "c", operator: "equal", value: "baz" },
         ],
-        minimum: 2,
+        min: 2,
       },
       { a: "foo", b: "bar", c: "baz" },
     ),
@@ -90,8 +90,8 @@ test("tests filter lists", () => {
           { field: "a", operator: "equal", value: "foo" },
           { field: "c", operator: "equal", value: "baz" },
         ],
-        minimum: 1,
-        maximum: 2,
+        min: 1,
+        max: 2,
       },
       { a: "foo", b: "bar", c: "baz" },
     ),
@@ -104,7 +104,7 @@ test("tests filter lists", () => {
           { field: "a", operator: "equal", value: "foo" },
           { field: "c", operator: "equal", value: "baz" },
         ],
-        maximum: 1,
+        max: 1,
       },
       { a: "foo", b: "bar", c: "baz" },
     ),

package/lib/tools/testFilter.ts

@@ -1,16 +1,7 @@
-import { EMPTY_OBJECT } from "unchangeable";
-
 import { CACHE } from "../constants/CACHE.js";
 import type { QuerySettings } from "../types/QuerySettings.js";
-import type {
-  Context,
-  FieldFiltered,
-  Filter,
-  FilterString,
-  IntrinsicFilter,
-} from "../types.js";
+import type { Filter, FilterString } from "../types.js";
 
-import { filterChildren } from "./filterChildren.js";
 import { get } from "./get.js";
 
 const { isArray } = Array;
@@ -32,7 +23,7 @@ function valueFromFilter<T>(value: T, filter: Filter<T>): any {
  * @returns `true` if the `value` matches the `filter` and `false` otherwise.
  */
 export function testFilter<T>(
-  filter: Filter<T> | undefined,
+  filter: NoInfer<Filter<T>> | undefined,
   value: T | undefined,
   settings?: QuerySettings<T>,
 ): boolean {
@@ -49,12 +40,12 @@ export function testFilter<T>(
       );
     case "any": {
       const length = filter.value?.length ?? 0;
-      const minimum = filter.minimum ?? (length > 0 ? 1 : 0);
-      const maximum = filter.maximum ?? Infinity;
+      const min = filter.min ?? (length > 0 ? 1 : 0);
+      const max = filter.max ?? Infinity;
       if (filter.value === undefined || filter.value.length === 0) {
         return true;
       }
-      if (minimum === 1 && maximum >= length) {
+      if (min === 1 && max >= length) {
         return filter.value.some((filter) =>
           testFilter(filter, value, settings),
         );
@@ -64,7 +55,7 @@ export function testFilter<T>(
           count + (testFilter(filter, value, settings) ? 1 : 0),
         0,
       );
-      return matched >= minimum && matched <= maximum;
+      return matched >= min && matched <= max;
     }
     case "none": {
       if (filter.value === undefined || filter.value.length === 0) {
@@ -137,16 +128,8 @@ export function testFilter<T>(
             filter[CACHE] = settings.transformFilterChildren(filter);
             break;
           default: {
-            const { pathField = "id", pathFieldSeparator } =
-              settings || EMPTY_OBJECT;
-            pathField;
-            filter[CACHE] = filterChildren<Context<T>>(
-              (get(filter.value, pathField as any) as string) ?? "",
-              pathField as FieldFiltered<Context<T>, string>,
-              filter.minDepth,
-              filter.maxDepth,
-              pathFieldSeparator,
-            ) as IntrinsicFilter<T>;
+            // Opt-out if no filter transformation is provided
+            return true;
           }
         }
       }

package/lib/tools/transformerFilterChildren.ts

@@ -0,0 +1,57 @@
+import { EMPTY_OBJECT } from "unchangeable";
+
+import type {
+  FieldFiltered,
+  FilterChildren,
+  FilterStringMatch,
+} 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`.
+ *
+ * @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 transformerFilterChildren<T>({
+  pathField = "path" as FieldFiltered<T, string>,
+  pathFieldSeparator = "/",
+}: TransformerFilterChildrenOptions<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;
+    return filterChildren(
+      parentPath,
+      pathField,
+      minDepth,
+      maxDepth,
+      pathFieldSeparator,
+    );
+  };
+}

package/lib/tools.ts

@@ -9,6 +9,7 @@ export { filterChildren } from "./tools/filterChildren.js";
 export { filterFromValue } from "./tools/filterFromValue.js";
 export { get } from "./tools/get.js";
 export { groupFilters } from "./tools/groupFilters.js";
+export { intrinsicFilter } from "./tools/intrinsicFilter.js";
 export { isFilterGroup } from "./tools/isFilterGroup.js";
 export { normalizeOrder } from "./tools/normalizeOrder.js";
 export { queryItemList } from "./tools/queryItemList.js";
@@ -17,3 +18,4 @@ export { sameField } from "./tools/sameField.js";
 export { sortItemList } from "./tools/sortItemList.js";
 export { splitPath } from "./tools/splitPath.js";
 export { testFilter } from "./tools/testFilter.js";
+export { transformerFilterChildren } from "./tools/transformerFilterChildren.js";

package/lib/types/AggregateFunction.ts

@@ -13,8 +13,8 @@ export type AggregateFunction<T> =
         | "median"
         | "standardDeviation"
         | "mean"
-        | "minimum"
-        | "maximum"
+        | "min"
+        | "max"
         | "variance"
         | "mode";
       field: Field<T>;

package/lib/types/Context.ts

@@ -2,6 +2,14 @@ import type { SELF } from "../constants/SELF.js";
 
 import type { Primitive } from "./Primitive.js";
 
+/**
+ * Describes the entity so that it can be identified or selected in a filter.
+ *
+ * The context of a single item (`query.multiple` is `false`) is typically its identifier.
+ * The context of a list of items (`query.multiple` is `true`) typically consists of common properties that reference the parent entity.
+ *
+ * It can be a partial object of the type `T` or a primitive value wrapped in an object with the `SELF` key.
+ */
 export type Context<T> = [0] extends [1 & T]
   ? any
   : T extends Primitive

package/lib/types/FilterChildren.ts

@@ -1,6 +1,5 @@
 import type { CACHE } from "../constants/CACHE.js";
 
-import type { Context } from "./Context";
 import type { IntrinsicFilter } from "./IntrinsicFilter.js";
 
 /**
@@ -8,7 +7,7 @@ import type { IntrinsicFilter } from "./IntrinsicFilter.js";
  */
 export type FilterChildren<T> = {
   operator: "children" | "notChildren";
-  value?: Context<T>;
+  value?: T;
   /**
    * Minimum depth of the children to match. If `0`, matches the parent. If `1`, matches the direct children, if `2`, the grandchildren, and so on.
    *

package/lib/types/FilterGroup.ts

@@ -29,13 +29,13 @@ export type FilterGroup<T> =
        *
        * @default `1` if filters are provided, `0` otherwise
        */
-      minimum?: number;
+      min?: number;
       /**
        * Maximum number of filters that can match.
        *
        * @default Infinity
        */
-      maximum?: number;
+      max?: number;
     }
   | {
       /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quetch",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "type": "module",
   "main": "./dist/main.js",
   "exports": {