@synnaxlabs/x 0.44.4 → 0.45.1

package/src/deep/path.spec.ts

@@ -10,164 +10,8 @@
 import { describe, expect, it } from "vitest";
 
 import { deep } from "@/deep";
-import { type record } from "@/record";
-
-interface TestRecord {
-  a: number;
-  b: {
-    c?: number;
-    d?: number;
-  };
-  c: number[];
-}
-
-describe("path", () => {
-  describe("get", () => {
-    it("should get a key", () => {
-      const a: TestRecord = {
-        a: 1,
-        b: {
-          c: 2,
-        },
-        c: [1],
-      };
-      expect(deep.get(a, "b.c")).toEqual(2);
-    });
-    it("should get an array index", () => {
-      const a: TestRecord = {
-        a: 1,
-        b: {
-          c: 2,
-        },
-        c: [1, 2, 3],
-      };
-      expect(deep.get(a, "c.1")).toEqual(2);
-    });
-    it("should return the object itself if the key is empty", () => {
-      const a: TestRecord = {
-        a: 1,
-        b: {
-          c: 2,
-        },
-        c: [1, 2, 3],
-      };
-      expect(deep.get(a, "")).toStrictEqual(a);
-    });
-    describe("custom getter function", () => {
-      const v = {
-        a: {
-          value: () => ({
-            c: 0,
-          }),
-        },
-      };
-      it("should use the custom getter function", () => {
-        expect(
-          deep.get(v, "a.value().c", {
-            optional: false,
-            getter: (obj, key) => {
-              if (key === "value()")
-                return (obj as { value: () => { c: number } }).value();
-              return obj[key];
-            },
-          }),
-        ).toEqual(0);
-      });
-
-      it("should get an array of keyed records", () => {
-        interface TestKeyedRecord {
-          values: record.KeyedNamed[];
-        }
-        const a: TestKeyedRecord = {
-          values: [
-            { key: "a", name: "a" },
-            { key: "b", name: "b" },
-          ],
-        };
-        expect(deep.get(a, "values.a.name")).toEqual("a");
-      });
-    });
-  });
-
-  describe("set", () => {
-    it("should set a key", () => {
-      const a: TestRecord = {
-        a: 1,
-        b: {
-          c: 2,
-        },
-        c: [1],
-      };
-      const b: TestRecord = {
-        a: 1,
-        b: {
-          c: 3,
-        },
-        c: [1],
-      };
-      deep.set(a, "b.c", 3);
-      expect(a).toEqual(b);
-    });
-
-    it("should set an array index", () => {
-      const a: TestRecord = {
-        a: 1,
-        b: {
-          c: 2,
-        },
-        c: [1, 2, 3],
-      };
-      const b: TestRecord = {
-        a: 1,
-        b: {
-          c: 2,
-        },
-        c: [1, 4, 3],
-      };
-      deep.set(a, "c.1", 4);
-      expect(a).toEqual(b);
-    });
-
-    it("should interpret a leading number also containing letters as a key", () => {
-      const data = {
-        a: [
-          {
-            key: "1b",
-            value: 1,
-          },
-        ],
-      };
-      deep.set(data, "a.1b.value", 2);
-      expect(deep.get(data, "a.1b.value")).toEqual(2);
-    });
-
-    it("should set a value on a nested object in the array by key", () => {
-      const data = {
-        config: {
-          channels: [{ key: "tMnAnJeQmn6", type: "ai_voltage" }],
-        },
-      };
-      deep.set(data, "config.channels.tMnAnJeQmn6.type", "ai_force_bridge_table");
-      expect(data.config.channels[0].type).toEqual("ai_force_bridge_table");
-    });
-
-    it("should set an entire item in the array by its key", () => {
-      const data = {
-        config: {
-          channels: [{ key: "tMnAnJeQmn6", type: "ai_voltage" }],
-        },
-      };
-      deep.set(data, "config.channels.tMnAnJeQmn6", {
-        key: "tMnAnJeQmn6",
-        type: "ai_force_bridge_table",
-      });
-      expect(data.config.channels[0]).toEqual({
-        key: "tMnAnJeQmn6",
-        type: "ai_force_bridge_table",
-      });
-    });
-  });
 
+describe("path utilities", () => {
   describe("transformPath", () => {
     it("should transform a path", () => {
       expect(deep.transformPath("a.b.c", (part) => part.toUpperCase())).toEqual(
@@ -184,7 +28,7 @@ describe("path", () => {
     });
   });
 
-  describe("matches", () => {
+  describe("pathsMatch", () => {
     it("should return true if two paths are equal", () => {
       expect(deep.pathsMatch("a.b.c", "a.b.c")).toEqual(true);
     });
@@ -197,6 +41,12 @@ describe("path", () => {
     it("should return true for an empty pattern", () => {
       expect(deep.pathsMatch("a.b.c", "")).toEqual(true);
     });
+    it("should return false if pattern is longer than path", () => {
+      expect(deep.pathsMatch("a.b", "a.b.c")).toEqual(false);
+    });
+    it("should return false if paths don't match", () => {
+      expect(deep.pathsMatch("a.b.c", "a.b.d")).toEqual(false);
+    });
   });
 
   describe("resolvePath", () => {
@@ -225,33 +75,92 @@ describe("path", () => {
     });
   });
 
-  describe("delete", () => {
-    const a: TestRecord = {
-      a: 1,
-      b: {
-        c: 2,
-      },
-      c: [1, 2, 3],
-    };
-    it("should delete a key", () => {
-      const cpy = deep.copy(a);
-      deep.remove(a, "b.c");
-      expect(a).toEqual({ ...cpy, b: {} });
+  describe("element", () => {
+    it("should get element at index", () => {
+      expect(deep.element("a.b.c", 1)).toEqual("b");
+    });
+
+    it("should handle negative index", () => {
+      expect(deep.element("a.b.c", -1)).toEqual("c");
+      expect(deep.element("a.b.c", -2)).toEqual("b");
     });
-    it("should delete an array index", () => {
-      const cpy = deep.copy(a);
-      deep.remove(a, "c.1");
-      expect(a).toEqual({ ...cpy, c: [1, 3] });
+
+    it("should get first element", () => {
+      expect(deep.element("a.b.c", 0)).toEqual("a");
     });
-    it("should not throw an error when the index is out of bounds", () => {
-      const cpy = deep.copy(a);
-      deep.remove(a, "c.100");
-      expect(a).toEqual(cpy);
+  });
+
+  describe("getIndex", () => {
+    it("should return index for numeric string", () => {
+      expect(deep.getIndex("42")).toEqual(42);
     });
-    it("should not throw an error when the key exists", () => {
-      const cpy = deep.copy(a);
-      deep.remove(a, "b.d");
-      expect(a).toEqual(cpy);
+
+    it("should return null for non-numeric string", () => {
+      expect(deep.getIndex("abc")).toBeNull();
+    });
+
+    it("should return null for mixed string", () => {
+      expect(deep.getIndex("1a")).toBeNull();
+    });
+
+    it("should handle zero", () => {
+      expect(deep.getIndex("0")).toEqual(0);
+    });
+  });
+
+  describe("defaultGetter", () => {
+    it("should get property from object", () => {
+      const obj = { a: 1, b: 2 };
+      expect(deep.defaultGetter(obj, "a")).toEqual(1);
+    });
+
+    it("should get index from array", () => {
+      const arr = [1, 2, 3];
+      expect(deep.defaultGetter(arr as any, "1")).toEqual(2);
+    });
+
+    it("should find keyed item in array", () => {
+      const arr = [
+        { key: "item1", value: 1 },
+        { key: "item2", value: 2 },
+      ];
+      expect(deep.defaultGetter(arr as any, "item2")).toEqual({ key: "item2", value: 2 });
+    });
+
+    it("should return undefined for non-existent key", () => {
+      const obj = { a: 1 };
+      expect(deep.defaultGetter(obj, "b")).toBeUndefined();
+    });
+
+    it("should handle empty array", () => {
+      const arr: any[] = [];
+      expect(deep.defaultGetter(arr as any, "0")).toBeUndefined();
+    });
+  });
+
+  describe("findBestKey", () => {
+    it("should find single part key", () => {
+      const obj = { a: { b: 1 } };
+      const result = deep.findBestKey(obj, ["a", "b"]);
+      expect(result).toEqual(["a", 1]);
+    });
+
+    it("should find multi-part key with period", () => {
+      const obj = { "a.b": { c: 1 } };
+      const result = deep.findBestKey(obj, ["a.b", "c"]);
+      expect(result).toEqual(["a.b", 1]);
+    });
+
+    it("should return null if no key found", () => {
+      const obj = { a: 1 };
+      const result = deep.findBestKey(obj, ["b", "c"]);
+      expect(result).toBeNull();
+    });
+
+    it("should prefer shorter key", () => {
+      const obj = { a: { b: 1 }, "a.b": 2 };
+      const result = deep.findBestKey(obj, ["a", "b"]);
+      expect(result).toEqual(["a", 1]);
     });
   });
-});
+});

package/src/deep/path.ts

@@ -10,6 +10,8 @@
 import { type Join } from "@/join";
 import { type record } from "@/record";
 
+export const SEPARATOR = ".";
+
 type Prev = [
   never,
   0,
@@ -36,10 +38,6 @@ type Prev = [
   ...0[],
 ];
 
-/**
- * A type that represents a deep key in an object.
- * @example type Key<T, 3> = "a" | "a.b" | "a.b.c"
- */
 export type Key<T, D extends number = 5> = [D] extends [never]
   ? never
   : T extends object
@@ -50,51 +48,6 @@ export type Key<T, D extends number = 5> = [D] extends [never]
       }[keyof T]
     : "";
 
-/** Options for the get function. */
-export interface GetOptions<O extends boolean | undefined = boolean | undefined> {
-  optional: O;
-  getter?: (obj: record.Unknown, key: string) => unknown;
-  separator?: string;
-}
-
-/**
- * A function that gets the value at the given path on the object. If the path does not exist
- * and the optional flag is set to true, null will be returned. If the path does not exist and
- * the optional flag is set to false, an error will be thrown.
- * @param obj the object to get the value from.
- * @param path the path to get the value at.
- * @param options the options for getting the value.
- * @param options.optional whether the path is optional.
- * @param options.getter a custom getter function to use on each part of the path.
- * @returns the value at the given path on the object.
- */
-export interface Get {
-  <V = record.Unknown, T = record.Unknown>(
-    obj: T,
-    path: string,
-    options?: GetOptions<false>,
-  ): V;
-  <V = record.Unknown, T = record.Unknown>(
-    obj: T,
-    path: string,
-    options?: GetOptions<boolean | undefined>,
-  ): V | null;
-}
-
-/** A strongly typed version of the @link Get function. */
-export interface TypedGet<V = record.Unknown, T = record.Unknown> {
-  (obj: T, path: string, options?: GetOptions<false>): V;
-  (obj: T, path: string, options?: GetOptions<boolean | undefined>): V | null;
-}
-
-/**
- * Executes the given replacer function on each part of the path.
- * @param path the path to transform
- * @param replacer the function to execute on each part of the path. If multiple
- * parts are returned, they will be joined with a period. If null/undefined is returned,
- * the part will be removed from the path.
- * @returns the transformed path.
- */
 export const transformPath = (
   path: string,
   replacer: (
@@ -102,7 +55,7 @@ export const transformPath = (
     index: number,
     parts: string[],
   ) => string | string[] | undefined,
-  separator = ".",
+  separator: string = SEPARATOR,
 ): string => {
   const parts = path.split(separator);
   const result = parts
@@ -116,7 +69,7 @@ export const transformPath = (
   return result.join(separator);
 };
 
-const defaultGetter = (obj: record.Unknown, key: string): unknown => {
+export const defaultGetter = (obj: record.Unknown, key: string): unknown => {
   if (!Array.isArray(obj)) return obj[key];
   const res = obj[key];
   if (res != null || obj.length == 0) return res;
@@ -127,167 +80,25 @@ const defaultGetter = (obj: record.Unknown, key: string): unknown => {
 };
 
 export const resolvePath = <T = record.Unknown>(path: string, obj: T): string => {
-  const parts = path.split(".");
+  const parts = path.split(SEPARATOR);
   parts.forEach((part, i) => {
     obj = defaultGetter(obj as record.Unknown, part) as T;
     if (obj != null && typeof obj === "object" && "key" in obj)
       parts[i] = obj.key as string;
   });
-  return parts.join(".");
-};
-
-/**
- * Gets the value at the given path on the object. If the path does not exist
- * and the optional flag is set to true, null will be returned. If the path does
- * not exist and the optional flag is set to false, an error will be thrown.
- * @param obj the object to get the value from.
- * @param path the path to get the value at.
- * @param opts the options for getting the value.
- * @param opts.optional whether the path is optional.
- * @param opts.getter a custom getter function to use on each part of the path.
- * @returns the value at the given path on the object.
- */
-export const get = (<V = record.Unknown, T = record.Unknown>(
-  obj: T,
-  path: string,
-  opts: GetOptions = { optional: false, separator: "." },
-): V | null => {
-  opts.separator ??= ".";
-  const { optional, getter = defaultGetter } = opts;
-  const parts = path.split(opts.separator);
-  if (parts.length === 1 && parts[0] === "") return obj as record.Unknown as V;
-  let result: record.Unknown = obj as record.Unknown;
-  for (const part of parts) {
-    const v = getter(result, part);
-    if (v == null) {
-      if (optional) return null;
-      throw new Error(`Path ${path} does not exist. ${part} is null`);
-    }
-    result = v as record.Unknown;
-  }
-  return result as V;
-}) as Get;
-
-const getIndex = (part: string): number | null => {
-  // in order to be considered an index, all characters must be numbers
-  for (const char of part) if (isNaN(parseInt(char))) return null;
-  return parseInt(part);
-};
-
-/**
- * Sets the value at the given path on the object. If the parents of the deep path
- * do not exist, new objects will be created.
- * @param obj the object to set the value on.
- * @param path the path to set the value at.
- * @param value the value to set.
- */
-export const set = <V>(obj: V, path: string, value: unknown): void => {
-  const parts = path.split(".");
-  let result: record.Unknown = obj as record.Unknown;
-  for (let i = 0; i < parts.length - 1; i++) {
-    const part = parts[i];
-    const v = defaultGetter(result, part);
-    if (v == null) throw new Error(`Path ${path} does not exist. ${part} is null`);
-    result = v as record.Unknown;
-  }
-  try {
-    if (!Array.isArray(result)) {
-      result[parts[parts.length - 1]] = value;
-      return;
-    }
-    if (result.length === 0) return;
-    const index = getIndex(parts[parts.length - 1]);
-    // If we can't parse an index, try to interpret it as an object key.
-    if (index == null) {
-      const first = result[0];
-      if (typeof first === "object" && "key" in first) {
-        const objIndex = result.findIndex((o) => o.key === parts[parts.length - 1]);
-        if (objIndex !== -1) {
-          result[objIndex] = value;
-          return;
-        }
-      }
-      return;
-    }
-    result[index] = value;
-  } catch (e) {
-    console.error("failed to set value", value, "at path", path, "on object", obj);
-    throw e;
-  }
+  return parts.join(SEPARATOR);
 };
 
-/**
- * Removes the value at the given path, modifying the object in place.
- * @param obj the object to remove the value from.
- * @param path the path to remove the value from.
- * @returns the object with the value removed.
- */
-export const remove = <V>(obj: V, path: string): void => {
-  const parts = path.split(".");
-  let result: record.Unknown = obj as record.Unknown;
-  for (let i = 0; i < parts.length - 1; i++) {
-    const part = parts[i];
-    if (result[part] == null) return;
-    result = result[part] as record.Unknown;
-  }
-  // if its an array, we need to splice it
-  if (Array.isArray(result)) {
-    const index = parseInt(parts[parts.length - 1]);
-    if (isNaN(index)) return;
-    result.splice(index, 1);
-    return;
-  }
-  delete result[parts[parts.length - 1]];
-};
-
-/**
- * Returns the element at the given index in the path.
- * @param path the path to get the element from
- * @param index the index of the element to get
- * @returns the element at the given index in the path
- */
 export const element = (path: string, index: number): string => {
-  const parts = path.split(".");
+  const parts = path.split(SEPARATOR);
   if (index < 0) return parts[parts.length + index];
   return parts[index];
 };
 
-/**
- * Checks if the path exists in the object.
- * @param obj the object to check
- * @param path the path to check
- * @returns whether the path exists in the object
- */
-export const has = <V = record.Unknown, T = record.Unknown>(
-  obj: T,
-  path: string,
-): boolean => {
-  try {
-    get<V, T>(obj, path);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-/**
- * Checks if the path matches the given pattern.
- *
- * @param path The path to check.
- * @param pattern The pattern to match against. Only "*" is supported as a wildcard.
- * @returns Whether the path matches the pattern.
- *
- *  * @example
- * pathsMatch("a.b.c", "a.b.c") // true
- * pathsMatch("a.b.c", "a.b") // true
- * pathsMatch("a.b", "a.b.c") // false
- * pathsMatch("a.b.c", "a.*") // true
- * pathsMatch("a.b.c", "a.*.c") // true
- */
 export const pathsMatch = (path: string, pattern: string): boolean => {
   if (pattern.length === 0) return true;
-  const parts = path.split(".");
-  const patterns = pattern.split(".");
+  const parts = path.split(SEPARATOR);
+  const patterns = pattern.split(SEPARATOR);
   if (patterns.length > parts.length) return false;
   for (let i = 0; i < patterns.length; i++) {
     const part = parts[i];
@@ -297,3 +108,21 @@ export const pathsMatch = (path: string, pattern: string): boolean => {
   }
   return true;
 };
+
+export const getIndex = (part: string): number | null => {
+  const num = parseInt(part);
+  if (isNaN(num) || num < 0 || num.toString() !== part) return null;
+  return num;
+};
+
+export const findBestKey = (
+  obj: record.Unknown,
+  remainingParts: string[],
+): [string, number] | null => {
+  for (let i = 1; i <= remainingParts.length; i++) {
+    const candidateKey = remainingParts.slice(0, i).join(SEPARATOR);
+    const v = defaultGetter(obj, candidateKey);
+    if (v != null) return [candidateKey, i];
+  }
+  return null;
+};