quetch 0.20.0 → 0.22.0

package/doc/type-aliases/QueryDelete.md

@@ -48,4 +48,4 @@ Query settings.
 
 ## Defined in
 
-[lib/types/QueryDelete.ts:9](https://github.com/nevoland/quetch/blob/74684cd5cd1bd7a08980d4ce305ecc4be0c3e8b8/lib/types/QueryDelete.ts#L9)
+[lib/types/QueryDelete.ts:9](https://github.com/nevoland/quetch/blob/5d54d23c7450a0f85309e15fdf3a25ea832b3452/lib/types/QueryDelete.ts#L9)

package/doc/type-aliases/QueryDeleteMultiple.md

@@ -48,4 +48,4 @@ Query settings.
 
 ## Defined in
 
-[lib/types/QueryDeleteMultiple.ts:9](https://github.com/nevoland/quetch/blob/74684cd5cd1bd7a08980d4ce305ecc4be0c3e8b8/lib/types/QueryDeleteMultiple.ts#L9)
+[lib/types/QueryDeleteMultiple.ts:9](https://github.com/nevoland/quetch/blob/5d54d23c7450a0f85309e15fdf3a25ea832b3452/lib/types/QueryDeleteMultiple.ts#L9)

package/doc/type-aliases/QueryMethod.md

@@ -12,4 +12,4 @@ Available query methods.
 
 ## Defined in
 
-[lib/types/QueryMethod.ts:6](https://github.com/nevoland/quetch/blob/74684cd5cd1bd7a08980d4ce305ecc4be0c3e8b8/lib/types/QueryMethod.ts#L6)
+[lib/types/QueryMethod.ts:6](https://github.com/nevoland/quetch/blob/5d54d23c7450a0f85309e15fdf3a25ea832b3452/lib/types/QueryMethod.ts#L6)

package/doc/type-aliases/QueryRead.md

@@ -76,4 +76,4 @@ Query settings.
 
 ## Defined in
 
-[lib/types/QueryRead.ts:10](https://github.com/nevoland/quetch/blob/74684cd5cd1bd7a08980d4ce305ecc4be0c3e8b8/lib/types/QueryRead.ts#L10)
+[lib/types/QueryRead.ts:10](https://github.com/nevoland/quetch/blob/5d54d23c7450a0f85309e15fdf3a25ea832b3452/lib/types/QueryRead.ts#L10)

package/doc/type-aliases/QueryReadMultiple.md

@@ -80,4 +80,4 @@ Query settings.
 
 ## Defined in
 
-[lib/types/QueryReadMultiple.ts:11](https://github.com/nevoland/quetch/blob/74684cd5cd1bd7a08980d4ce305ecc4be0c3e8b8/lib/types/QueryReadMultiple.ts#L11)
+[lib/types/QueryReadMultiple.ts:11](https://github.com/nevoland/quetch/blob/5d54d23c7450a0f85309e15fdf3a25ea832b3452/lib/types/QueryReadMultiple.ts#L11)

package/doc/type-aliases/QuerySettings.md

@@ -22,17 +22,35 @@ Settings to use when doing a query.
 
 Abort controller to abort the query.
 
-### pathFieldKey?
+### pathField?
 
-> `optional` **pathFieldKey**: [`FieldFiltered`](FieldFiltered.md)\<`T`, `string`\>
+> `optional` **pathField**: [`FieldFiltered`](FieldFiltered.md)\<`T`, `string`\>
 
-Field key to that contains the path value of an item.
+Path to the field that contains the path value of an item, used for displaying items in a tree.
 
 ### pathFieldSeparator?
 
 > `optional` **pathFieldSeparator**: `string`
 
-String used to separate the path nodes of an item.
+Maps path fields to a string used to separate the path nodes of a field value.
+
+#### Default
+
+```ts
+"/"
+```
+
+### pathFieldSeparatorEscape?
+
+> `optional` **pathFieldSeparatorEscape**: `string`
+
+String used to escape the separator.
+
+#### Default
+
+```ts
+"\\"
+```
 
 ### signal?
 
@@ -62,4 +80,4 @@ A filter that captures the items expressed by the provided `FilterChildren`.
 
 ## Defined in
 
-[lib/types/QuerySettings.ts:8](https://github.com/nevoland/quetch/blob/74684cd5cd1bd7a08980d4ce305ecc4be0c3e8b8/lib/types/QuerySettings.ts#L8)
+[lib/types/QuerySettings.ts:8](https://github.com/nevoland/quetch/blob/5d54d23c7450a0f85309e15fdf3a25ea832b3452/lib/types/QuerySettings.ts#L8)

package/doc/type-aliases/QueryUpdate.md

@@ -68,4 +68,4 @@ Partial property values to update.
 
 ## Defined in
 
-[lib/types/QueryUpdate.ts:9](https://github.com/nevoland/quetch/blob/74684cd5cd1bd7a08980d4ce305ecc4be0c3e8b8/lib/types/QueryUpdate.ts#L9)
+[lib/types/QueryUpdate.ts:9](https://github.com/nevoland/quetch/blob/5d54d23c7450a0f85309e15fdf3a25ea832b3452/lib/types/QueryUpdate.ts#L9)

package/doc/type-aliases/QueryUpdateMultiple.md

@@ -72,4 +72,4 @@ Partial property values to update.
 
 ## Defined in
 
-[lib/types/QueryUpdateMultiple.ts:10](https://github.com/nevoland/quetch/blob/74684cd5cd1bd7a08980d4ce305ecc4be0c3e8b8/lib/types/QueryUpdateMultiple.ts#L10)
+[lib/types/QueryUpdateMultiple.ts:10](https://github.com/nevoland/quetch/blob/5d54d23c7450a0f85309e15fdf3a25ea832b3452/lib/types/QueryUpdateMultiple.ts#L10)

package/doc/type-aliases/Result.md

@@ -16,4 +16,4 @@
 
 ## Defined in
 
-[lib/types/Result.ts:20](https://github.com/nevoland/quetch/blob/74684cd5cd1bd7a08980d4ce305ecc4be0c3e8b8/lib/types/Result.ts#L20)
+[lib/types/Result.ts:20](https://github.com/nevoland/quetch/blob/5d54d23c7450a0f85309e15fdf3a25ea832b3452/lib/types/Result.ts#L20)

package/doc/type-aliases/Store.md

@@ -68,4 +68,4 @@
 
 ## Defined in
 
-[lib/types/Store.ts:2](https://github.com/nevoland/quetch/blob/74684cd5cd1bd7a08980d4ce305ecc4be0c3e8b8/lib/types/Store.ts#L2)
+[lib/types/Store.ts:2](https://github.com/nevoland/quetch/blob/5d54d23c7450a0f85309e15fdf3a25ea832b3452/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/74684cd5cd1bd7a08980d4ce305ecc4be0c3e8b8/lib/types/Value.ts#L6)
+[lib/types/Value.ts:6](https://github.com/nevoland/quetch/blob/5d54d23c7450a0f85309e15fdf3a25ea832b3452/lib/types/Value.ts#L6)

package/doc/type-aliases/ValueMap.md

@@ -0,0 +1,21 @@
+[**quetch**](../README.md)
+
+***
+
+[quetch](../README.md) / ValueMap
+
+# Type Alias: ValueMap\<T, V\>
+
+> **ValueMap**\<`T`, `V`\>: `T` *extends* [`Primitive`](Primitive.md) ? `V` : `T` *extends* infer P[] ? `Record`\<`number`, [`ValueMap`](ValueMap.md)\<`P`, `V`\>\> : `T` *extends* `object` ? `{ [K in keyof T]?: ValueMap<T[K], V> }` : `never`
+
+Maps the properties of the provided value `T` to a specific value `V`.
+
+## Type Parameters
+
+• **T**
+
+• **V**
+
+## Defined in
+
+[lib/types/ValueMap.ts:6](https://github.com/nevoland/quetch/blob/5d54d23c7450a0f85309e15fdf3a25ea832b3452/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/74684cd5cd1bd7a08980d4ce305ecc4be0c3e8b8/lib/constants/CACHE.ts#L1)
+[lib/constants/CACHE.ts:1](https://github.com/nevoland/quetch/blob/5d54d23c7450a0f85309e15fdf3a25ea832b3452/lib/constants/CACHE.ts#L1)

package/doc/variables/SELF.md

@@ -10,4 +10,4 @@
 
 ## Defined in
 
-[lib/constants/SELF.ts:1](https://github.com/nevoland/quetch/blob/74684cd5cd1bd7a08980d4ce305ecc4be0c3e8b8/lib/constants/SELF.ts#L1)
+[lib/constants/SELF.ts:1](https://github.com/nevoland/quetch/blob/5d54d23c7450a0f85309e15fdf3a25ea832b3452/lib/constants/SELF.ts#L1)

package/lib/tools/queryItemList.ts

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

package/lib/tools/sameField.ts

@@ -0,0 +1,15 @@
+import type { Field } from "../types";
+
+const { isArray } = Array;
+
+export function sameField(a: Field<any>, b: Field<any>): boolean {
+  if (a === b) {
+    return true;
+  }
+  const aNormalized = isArray(a) ? a : [a];
+  const bNormalized = isArray(b) ? b : [b];
+  if (aNormalized.length !== bNormalized.length) {
+    return false;
+  }
+  return aNormalized.every((value, index) => value === bNormalized[index]);
+}

package/lib/tools/sortItemList.test.ts

@@ -61,3 +61,62 @@ test("sorts items", () => {
     { a: 3, c: "b" },
   ]);
 });
+
+test("sorts items with separator setting", () => {
+  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" },
+      ],
+      {
+        pathField: "path",
+        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" },
+  ]);
+  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" },
+      ],
+      {
+        pathField: "path",
+        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,24 +1,42 @@
-import type { Order } from "../types";
+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.
  * @returns A new sorted array.
  */
 export function sortItemList<T>(
   orderList: readonly Order<T>[] | undefined,
   value: readonly T[],
+  settings?: QuerySettings<T>,
 ) {
+  const {
+    pathField,
+    pathFieldSeparator = "/",
+    pathFieldSeparatorEscape,
+  } = settings ?? {};
   if (orderList === undefined || orderList.length === 0) {
     return value;
   }
   const normalizedOrder = orderList.map(normalizeOrder);
-  return [...value].sort((a, b) => {
+  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);
@@ -26,6 +44,26 @@ export function sortItemList<T>(
       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) {
+          return descending ? -1 : 1;
+        }
+        return descending ? 1 : -1;
+      }
       if (valueA > valueB) {
         return descending ? -1 : 1;
       }

package/lib/tools/splitPath.test.ts

@@ -0,0 +1,17 @@
+import { expect, test } from "vitest";
+
+import { splitPath } from "./splitPath.js";
+
+test("splits paths", () => {
+  expect(splitPath("/", "\\", "/a/b")).toEqual(["", "a", "b"]);
+  expect(splitPath("/", "\\", "/a\\/b")).toEqual(["", "a\\/b"]);
+  expect(splitPath("/", "", "/a\\/b")).toEqual(["", "a\\", "b"]);
+  expect(splitPath("", "", "/a/b")).toEqual(["/a/b"]);
+});
+
+test("returns path splitter", () => {
+  expect(splitPath("/", "\\")("/a/b")).toEqual(["", "a", "b"]);
+  expect(splitPath("/", "\\")("/a\\/b")).toEqual(["", "a\\/b"]);
+  expect(splitPath("/", "")("/a\\/b")).toEqual(["", "a\\", "b"]);
+  expect(splitPath("", "")("/a/b")).toEqual(["/a/b"]);
+});

package/lib/tools/splitPath.ts

@@ -0,0 +1,54 @@
+import { escapeRegex } from "./escapeRegex.js";
+
+type PathSplitter =
+  /**
+   * Takes a `path` string and returns an array of path items.
+   *
+   * @param path The path string to split.
+   *
+   */
+  (path: string) => readonly string[];
+
+/**
+ * Splits a `path` string using the `separator`, omitting those prefixed with a `separatorEscape`.
+ *
+ * If `path` is `undefined`, returns a function that takes `path` and splits it according to the provided `separator` and `separatorEscape` arguments.
+ *
+ * @param separator The separator string to use (defaults to `"/"`).
+ * @param separatorEscape The separator escape string to use (default to `"\\"`).
+ * @param path The path string to split.
+ * @returns An array containing the splitted path items if `path` is defined, or a function that takes a `path` string and returns an array.
+ */
+export function splitPath(
+  separator: string | undefined,
+  separatorEscape: string | undefined,
+  path: string,
+): readonly string[];
+export function splitPath(
+  separator?: string,
+  separatorEscape?: string,
+): PathSplitter;
+export function splitPath(
+  separator = "/",
+  separatorEscape = "\\",
+  path?: string,
+): readonly string[] | PathSplitter {
+  const fieldSeparatorRegexp = !separator
+    ? null
+    : new RegExp(
+        !separatorEscape
+          ? escapeRegex(separator)
+          : `(?<!${escapeRegex(separatorEscape)})${escapeRegex(separator)}`,
+        "g",
+      );
+  if (path == null) {
+    if (fieldSeparatorRegexp == null) {
+      return (path: string) => [path];
+    }
+    return (path: string) => path.split(fieldSeparatorRegexp);
+  }
+  if (fieldSeparatorRegexp == null) {
+    return [path];
+  }
+  return path.split(fieldSeparatorRegexp);
+}

package/lib/tools/testFilter.test.ts

@@ -322,7 +322,7 @@ test("tests filter with children predicates", () => {
       { operator: "children", value: ".a" },
       { path: ".a.b" },
       {
-        pathFieldKey: "path",
+        pathField: "path",
         pathFieldSeparator: ".",
       },
     ),
@@ -332,7 +332,7 @@ test("tests filter with children predicates", () => {
       { operator: "notChildren", value: ".a" },
       { path: ".a.b" },
       {
-        pathFieldKey: "path",
+        pathField: "path",
         pathFieldSeparator: ".",
       },
     ),
@@ -368,7 +368,7 @@ test("tests filter with children predicates", () => {
       { operator: "children", value: "ba" },
       { path: ".a.b" },
       {
-        pathFieldKey: "path",
+        pathField: "path",
         pathFieldSeparator: ".",
       },
     ),
@@ -378,7 +378,7 @@ test("tests filter with children predicates", () => {
       { operator: "notChildren", value: "ba" },
       { path: ".a.b" },
       {
-        pathFieldKey: "path",
+        pathField: "path",
         pathFieldSeparator: ".",
       },
     ),

package/lib/tools/testFilter.ts

@@ -1,3 +1,5 @@
+import { EMPTY_OBJECT } from "unchangeable";
+
 import { CACHE } from "../constants/CACHE.js";
 import type { QuerySettings } from "../types/QuerySettings.js";
 import type { FieldFiltered, Filter, FilterString } from "../types.js";
@@ -113,12 +115,12 @@ export function testFilter<T>(
             break;
           default: {
             const {
-              pathFieldKey = "id" as FieldFiltered<T, string>,
-              pathFieldSeparator = "/",
-            } = settings || {};
+              pathField = "id" as FieldFiltered<T, string>,
+              pathFieldSeparator,
+            } = settings || (EMPTY_OBJECT as QuerySettings<T>);
             filter[CACHE] = filterChildren(
               filter.value as string,
-              pathFieldKey,
+              pathField,
               filter.deep,
               pathFieldSeparator,
             );

package/lib/tools.ts

@@ -12,5 +12,7 @@ export { isFilterGroup } from "./tools/isFilterGroup.js";
 export { normalizeOrder } from "./tools/normalizeOrder.js";
 export { queryItemList } from "./tools/queryItemList.js";
 export { reverseOrder } from "./tools/reverseOrder.js";
+export { sameField } from "./tools/sameField.js";
 export { sortItemList } from "./tools/sortItemList.js";
+export { splitPath } from "./tools/splitPath.js";
 export { testFilter } from "./tools/testFilter.js";

package/lib/types/Field.ts

@@ -1,9 +1,7 @@
-import type { SELF } from "../constants/SELF.js";
-
 import type { CombineUnion } from "./CombineUnion";
+import type { FieldKey } from "./FieldKey.js";
 import type { Path } from "./Path";
-import type { Primitive } from "./Primitive";
 
 export type Field<T> = KeyOrPath<CombineUnion<T>>;
 
-type KeyOrPath<T> = (T extends Primitive ? typeof SELF : keyof T) | Path<T>;
+type KeyOrPath<T> = FieldKey<T> | Path<T>;

package/lib/types/FieldKey.ts

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

package/lib/types/FieldMap.ts

@@ -0,0 +1,6 @@
+import type { Field } from "./Field";
+
+/**
+ * Maps the fields of the provided value `T` to a specific value `V`.
+ */
+export type FieldMap<T, V> = readonly [Field<T>, V][];

package/lib/types/QuerySettings.ts

@@ -6,15 +6,22 @@ import type { FilterChildren } from "./FilterChildren";
  * Settings to use when doing a query.
  */
 export type QuerySettings<T> = {
-  // TODO: Move `path*` and `transform*` to fetch middleware?
   /**
-   * String used to separate the path nodes of an item.
+   * Path to the field that contains the path value of an item, used for displaying items in a tree.
    */
-  pathFieldSeparator?: string;
+  pathField?: FieldFiltered<T, string>;
+  /**
+   * String used to escape the separator.
+   *
+   * @default "\\"
+   */
+  pathFieldSeparatorEscape?: string;
   /**
-   * Field key to that contains the path value of an item.
+   * Maps path fields to a string used to separate the path nodes of a field value.
+   *
+   * @default "/"
    */
-  pathFieldKey?: FieldFiltered<T, string>;
+  pathFieldSeparator?: string;
   /**
    * Returns a filter that captures the items expressed by the provided `FilterChildren`. The return filter cannot use filters of type `FilterChildren`.
    *
@@ -23,7 +30,7 @@ export type QuerySettings<T> = {
    */
   transformFilterChildren?: (
     filter: FilterChildren<T>,
-  ) => Exclude<Filter<T>, { operator: "children" }>;
+  ) => Exclude<Filter<T>, { operator: "children" | "notChildren" }>;
   /**
    * Abort signal to abort the query.
    */

package/lib/types/ValueMap.ts

@@ -0,0 +1,14 @@
+import type { Primitive } from "./Primitive";
+
+/**
+ * Maps the properties of the provided value `T` to a specific value `V`.
+ */
+export type ValueMap<T, V> = T extends Primitive
+  ? V
+  : T extends Array<infer P>
+    ? Record<number, ValueMap<P, V>>
+    : T extends object
+      ? {
+          [K in keyof T]?: ValueMap<T[K], V>;
+        }
+      : never;

package/lib/types.ts

@@ -12,6 +12,8 @@ export type { FieldFunction } from "./types/FieldFunction";
 export type { FieldFunctionCustom } from "./types/FieldFunctionCustom";
 export type { FieldFunctionFormatDate } from "./types/FieldFunctionFormatDate";
 export type { FieldFunctionReturn } from "./types/FieldFunctionReturn";
+export type { FieldKey } from "./types/FieldKey";
+export type { FieldMap } from "./types/FieldMap";
 export type { Filter } from "./types/Filter";
 export type { FilterArray } from "./types/FilterArray";
 export type { FilterBoolean } from "./types/FilterBoolean";
@@ -60,3 +62,4 @@ export type { QueryUpdateMultiple } from "./types/QueryUpdateMultiple";
 export type { Result } from "./types/Result";
 export type { Store } from "./types/Store";
 export type { Value } from "./types/Value";
+export type { ValueMap } from "./types/ValueMap";

package/package.json

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