@synnaxlabs/x 0.36.0 → 0.38.0

package/src/link/link.ts

@@ -0,0 +1,21 @@
+// Copyright 2024 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+const urlRegex = new RegExp(
+  "^(https?:\\/\\/)?" + // http:// or https:// (optional)
+    "((([a-zA-Z0-9][a-zA-Z0-9-]*\\.)+[a-zA-Z]{2,})|" + // domain name and extension
+    "localhost|" + // localhost
+    "(\\d{1,3}\\.){3}\\d{1,3})" + // or IP address
+    "(\\:\\d+)?" + // port (optional)
+    "(\\/[-a-zA-Z0-9@:%._\\+~#=]*)*" + // path (optional)
+    "(\\?[;&a-zA-Z0-9%_.,~+=-]*)?" + // query string (optional)
+    "(#[-a-zA-Z0-9_]*)?$", // fragment identifier (optional)
+);
+
+export const is = (string: string): boolean => urlRegex.test(string);

package/src/runtime/os.ts

@@ -10,7 +10,23 @@
 import { z } from "zod";
 
 export const OPERATING_SYSTEMS = ["MacOS", "Windows", "Linux", "Docker"] as const;
-export const osZ = z.enum(OPERATING_SYSTEMS);
+const LOWERCASE_OPERATING_SYSTEMS = ["macos", "windows", "linux", "docker"] as const;
+const LOWER_TO_UPPER_OPERATING_SYSTEMS: Record<
+  (typeof LOWERCASE_OPERATING_SYSTEMS)[number],
+  (typeof OPERATING_SYSTEMS)[number]
+> = {
+  macos: "MacOS",
+  windows: "Windows",
+  linux: "Linux",
+  docker: "Docker",
+};
+export const osZ = z
+  .enum(OPERATING_SYSTEMS)
+  .or(
+    z
+      .enum(LOWERCASE_OPERATING_SYSTEMS)
+      .transform((s) => LOWER_TO_UPPER_OPERATING_SYSTEMS[s]),
+  );
 export type OS = (typeof OPERATING_SYSTEMS)[number];
 
 export type RequiredGetOSProps = {
@@ -47,4 +63,4 @@ export const getOS = ((props: GetOSProps = {}): OS | undefined => {
   if (os != null) return os;
   os = evalOS();
   return os ?? default_;
-}) as unknown as GetOS;
+}) as GetOS;

package/src/sleep/sleep.ts

@@ -1,4 +1,4 @@
-import { CrudeTimeSpan, TimeSpan } from "@/telem";
+import { type CrudeTimeSpan, TimeSpan } from "@/telem";
 
 export const sleep = async (span: CrudeTimeSpan): Promise<void> =>
   await new Promise((resolve) =>

package/src/telem/index.ts

@@ -7,6 +7,6 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export type { GLBufferController } from "@/telem/gl";
+export { type GLBufferController } from "@/telem/gl";
 export * from "@/telem/series";
 export * from "@/telem/telem";

package/src/telem/series.spec.ts

@@ -933,6 +933,27 @@ describe("MultiSeries", () => {
     });
   });
 
+  describe("parseJSON", () => {
+    it("should correctly parse a multi-series of JSON", () => {
+      const a = new Series([
+        { a: 1, b: "apple" },
+        { a: 2, b: "banana" },
+      ]);
+      const b = new Series([
+        { a: 3, b: "carrot" },
+        { a: 4, b: "dog" },
+      ]);
+      const multi = new MultiSeries([a, b]);
+      const arr = multi.parseJSON(z.object({ a: z.number(), b: z.string() }));
+      expect(arr).toEqual([
+        { a: 1, b: "apple" },
+        { a: 2, b: "banana" },
+        { a: 3, b: "carrot" },
+        { a: 4, b: "dog" },
+      ]);
+    });
+  });
+
   describe("array construction", () => {
     it("should correctly construct a JS array from a multi-series", () => {
       const a = new Series(new Float32Array([1, 2, 3]));

package/src/telem/series.ts

@@ -7,7 +7,6 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { isTypedArray } from "util/types";
 import { z } from "zod";
 
 import { binary } from "@/binary";
@@ -390,7 +389,7 @@ export class Series<T extends TelemValue = TelemValue> {
   /** @returns a native typed array with the proper data type. */
   get data(): TypedArray {
     if (this.writePos === FULL_BUFFER) return this.underlyingData;
-    // @ts-expect-error - ABC
+    // @ts-expect-error - issues with union types in array constructors.
     return new this.dataType.Array(this._data, 0, this.writePos);
   }
 
@@ -420,7 +419,7 @@ export class Series<T extends TelemValue = TelemValue> {
 
   parseJSON<Z extends z.ZodTypeAny>(schema: Z): Array<z.output<Z>> {
     if (!this.dataType.equals(DataType.JSON))
-      throw new Error("cannot convert non-string series to strings");
+      throw new Error("cannot parse non-JSON series as JSON");
     return new TextDecoder()
       .decode(this.underlyingData)
       .split("\n")
@@ -623,10 +622,8 @@ export class Series<T extends TelemValue = TelemValue> {
     }
     const slice = this.data.slice(start, end);
     if (this.dataType.equals(DataType.STRING))
-      return new TextDecoder().decode(slice) as unknown as T;
-    return caseconv.snakeToCamel(
-      JSON.parse(new TextDecoder().decode(slice)),
-    ) as unknown as T;
+      return new TextDecoder().decode(slice) as T;
+    return caseconv.snakeToCamel(JSON.parse(new TextDecoder().decode(slice))) as T;
   }
 
   /**
@@ -650,8 +647,11 @@ export class Series<T extends TelemValue = TelemValue> {
 
   updateGLBuffer(gl: GLBufferController): void {
     this.gl.control = gl;
-    if (!this.dataType.equals(DataType.FLOAT32))
-      throw new Error("Only FLOAT32 arrays can be used in WebGL");
+    if (
+      !this.dataType.equals(DataType.FLOAT32) &&
+      !this.dataType.equals(DataType.UINT8)
+    )
+      throw new Error("Only FLOAT32 and UINT8 arrays can be used in WebGL");
     const { buffer, bufferUsage, prevBuffer } = this.gl;
 
     // If no buffer has been created yet, create one.
@@ -1092,6 +1092,12 @@ export class MultiSeries<T extends TelemValue = TelemValue> implements Iterable<
     return bounds.distance(b, start, end);
   }
 
+  parseJSON<Z extends z.ZodTypeAny>(schema: Z): Array<z.output<Z>> {
+    if (!this.dataType.equals(DataType.JSON))
+      throw new Error("cannot parse non-JSON series as JSON");
+    return this.series.flatMap((s) => s.parseJSON(schema));
+  }
+
   [Symbol.iterator](): Iterator<T> {
     if (this.series.length === 0)
       return {

package/src/telem/telem.ts

@@ -1231,7 +1231,8 @@ export class DataType extends String implements Stringer {
   }
 
   get isInteger(): boolean {
-    return this.toString().startsWith("int");
+    const str = this.toString();
+    return str.startsWith("int") || str.startsWith("uint");
   }
 
   get isFloat(): boolean {
@@ -1244,18 +1245,41 @@ export class DataType extends String implements Stringer {
     return v;
   }
 
+  get isUnsigned(): boolean {
+    return (
+      this.equals(DataType.UINT8) ||
+      this.equals(DataType.UINT16) ||
+      this.equals(DataType.UINT32) ||
+      this.equals(DataType.UINT64)
+    );
+  }
+
+  get isSigned(): boolean {
+    return (
+      this.equals(DataType.INT8) ||
+      this.equals(DataType.INT16) ||
+      this.equals(DataType.INT32) ||
+      this.equals(DataType.INT64)
+    );
+  }
+
   /** @returns true if the data type can be cast to the other data type without loss of precision. */
   canSafelyCastTo(other: DataType): boolean {
     if (this.equals(other)) return true;
-    if (
-      (this.isVariable && !other.isVariable) ||
-      (!this.isVariable && other.isVariable)
-    )
-      return false;
-    if ((this.isFloat && other.isInteger) || (this.isInteger && other.isFloat))
-      return this.density.valueOf() < other.density.valueOf();
-    if ((this.isFloat && other.isFloat) || (this.isInteger && other.isInteger))
-      return this.density.valueOf() <= other.density.valueOf();
+    if (!this.isNumeric || !other.isNumeric) return false;
+    if (this.isVariable || other.isVariable) return false;
+    if (this.isUnsigned && other.isSigned) return false;
+
+    if (this.isFloat)
+      return other.isFloat && this.density.valueOf() <= other.density.valueOf();
+    if (this.equals(DataType.INT32) && other.equals(DataType.FLOAT64)) return true;
+    if (this.equals(DataType.INT8) && other.equals(DataType.FLOAT32)) return true;
+    if (this.isInteger && other.isInteger)
+      return (
+        this.density.valueOf() <= other.density.valueOf() &&
+        this.isUnsigned === other.isUnsigned
+      );
+
     return false;
   }
 

package/src/unique/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2024 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+export * as unique from "@/unique/unique";

package/src/unique/unique.spec.ts

@@ -0,0 +1,192 @@
+// Copyright 2024 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { describe, expect, it } from "vitest";
+
+import { unique } from "@/unique";
+
+describe("unique", () => {
+  it("removes duplicate primitive values", () => {
+    const result = unique.unique([1, 2, 2, 3, 4, 4, 5]);
+    expect(result).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  it("works with strings", () => {
+    const result = unique.unique(["a", "b", "a", "c", "b"]);
+    expect(result).toEqual(["a", "b", "c"]);
+  });
+
+  it("works with mixed types", () => {
+    const result = unique.unique([1, "1", 2, "2", 1, "1"]);
+    expect(result).toEqual([1, "1", 2, "2"]);
+  });
+
+  it("handles an empty array", () => {
+    const result = unique.unique([]);
+    expect(result).toEqual([]);
+  });
+
+  it("works with readonly arrays", () => {
+    const values: readonly number[] = [1, 1, 2, 3];
+    const result = unique.unique(values);
+    expect(result).toEqual([1, 2, 3]);
+  });
+});
+
+describe("by", () => {
+  interface IDTestCase {
+    id: number;
+  }
+
+  it("removes duplicates based on a key function and keeps the first instance by default", () => {
+    const result = unique.by(
+      [
+        { id: 1, name: "A" },
+        { id: 2, name: "B" },
+        { id: 1, name: "C" },
+      ],
+      (value: IDTestCase) => value.id,
+    );
+    expect(result).toEqual([
+      { id: 1, name: "A" },
+      { id: 2, name: "B" },
+    ]);
+  });
+
+  it("removes duplicates based on a key function and keeps the first instance when keepFirst is true", () => {
+    const result = unique.by(
+      [
+        { id: 1, name: "A" },
+        { id: 2, name: "B" },
+        { id: 1, name: "C" },
+      ],
+      (value: IDTestCase) => value.id,
+      true,
+    );
+    expect(result).toEqual([
+      { id: 1, name: "A" },
+      { id: 2, name: "B" },
+    ]);
+  });
+
+  it("removes duplicates based on a key function and keeps the last instance when keepFirst is false", () => {
+    const result = unique.by(
+      [
+        { id: 1, name: "A" },
+        { id: 2, name: "B" },
+        { id: 1, name: "C" },
+      ],
+      (value: IDTestCase) => value.id,
+      false,
+    );
+    expect(result).toEqual([
+      { id: 2, name: "B" },
+      { id: 1, name: "C" },
+    ]);
+  });
+
+  interface ValueTestCase {
+    value: string;
+  }
+
+  it("works with a custom key function", () => {
+    const result = unique.by(
+      [{ value: "apple" }, { value: "banana" }, { value: "apple" }],
+      (v: ValueTestCase) => v.value,
+    );
+    expect(result).toEqual([{ value: "apple" }, { value: "banana" }]);
+  });
+
+  it("handles an empty array", () => {
+    const result = unique.by([], (v: unknown) => v);
+    expect(result).toEqual([]);
+  });
+
+  it("works with readonly arrays and keeps the first instance by default", () => {
+    const values: readonly { id: number; name: string }[] = [
+      { id: 1, name: "A" },
+      { id: 1, name: "B" },
+    ];
+    const result = unique.by(values, (v: IDTestCase) => v.id);
+    expect(result).toEqual([{ id: 1, name: "A" }]);
+  });
+
+  it("works with readonly arrays and keeps the last instance when keepFirst is false", () => {
+    const values: readonly { id: number; name: string }[] = [
+      { id: 1, name: "A" },
+      { id: 1, name: "B" },
+    ];
+    const result = unique.by(values, (v: IDTestCase) => v.id, false);
+    expect(result).toEqual([{ id: 1, name: "B" }]);
+  });
+
+  interface ComplexTestCase {
+    id: number;
+    nested: { value: string };
+  }
+
+  it("works with complex keys and keeps the first instance by default", () => {
+    const result = unique.by(
+      [
+        { id: 1, nested: { value: "A" } },
+        { id: 1, nested: { value: "B" } },
+        { id: 1, nested: { value: "A", otherKey: "4" } },
+      ],
+      (v: ComplexTestCase) => `${v.id}-${v.nested.value}`,
+    );
+    expect(result).toEqual([
+      { id: 1, nested: { value: "A" } },
+      { id: 1, nested: { value: "B" } },
+    ]);
+  });
+
+  it("works with complex keys and keeps the last instance when keepFirst is false", () => {
+    const result = unique.by(
+      [
+        { id: 1, nested: { value: "A" } },
+        { id: 1, nested: { value: "B" } },
+        { id: 1, nested: { value: "A", otherKey: "4" } },
+      ],
+      (v: ComplexTestCase) => `${v.id}-${v.nested.value}`,
+      false,
+    );
+    expect(result).toEqual([
+      { id: 1, nested: { value: "B" } },
+      { id: 1, nested: { value: "A", otherKey: "4" } },
+    ]);
+  });
+
+  it("handles cases where all keys are unique", () => {
+    const result = unique.by(
+      [
+        { id: 1, name: "A" },
+        { id: 2, name: "B" },
+        { id: 3, name: "C" },
+      ],
+      (v: IDTestCase) => v.id,
+    );
+    expect(result).toEqual([
+      { id: 1, name: "A" },
+      { id: 2, name: "B" },
+      { id: 3, name: "C" },
+    ]);
+  });
+
+  it("handles cases where all values are identical", () => {
+    const result = unique.by(
+      [
+        { id: 1, name: "A" },
+        { id: 1, name: "A" },
+        { id: 1, name: "A" },
+      ],
+      (v: IDTestCase) => v.id,
+    );
+    expect(result).toEqual([{ id: 1, name: "A" }]);
+  });
+});

package/src/unique/unique.ts

@@ -0,0 +1,67 @@
+// Copyright 2024 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+/**
+ * Removes duplicate values from an array, preserving the order of the first occurrence
+ * of each unique value.
+ *
+ * @param values - An array or readonly array of values to deduplicate.
+ * @returns A new array containing only unique values.
+ *
+ * @example
+ * ```typescript
+ * unique([1, 2, 2, 3, 4, 4, 5]); // [1, 2, 3, 4, 5]
+ * ```
+ */
+export const unique = <V>(values: V[] | readonly V[]): V[] => [...new Set(values)];
+
+/**
+ * Removes duplicate values from an array based on a key function, preserving either
+ * the first or last occurrence of each unique key. If
+ *
+ * @param values - An array or readonly array of values to deduplicate.
+ * @param key - A function that generates a unique key for each value.
+ * @param keepFirst - An optional boolean indicating whether to keep the first instance
+ *                    (`true`, default) or the last instance (`false`) of each unique key.
+ * @returns A new array containing only unique values based on the generated keys.
+ *
+ * @example
+ * // Default behavior (keep first instance):
+ * by(
+ *   [{ id: 1, name: "A" }, { id: 2, name: "B" }, { id: 1, name: "C" }],
+ *   (value) => value.id
+ * );
+ * // Result: [{ id: 1, name: "A" }, { id: 2, name: "B" }]
+ *
+ * @example
+ * // Keep last instance:
+ * by(
+ *   [{ id: 1, name: "A" }, { id: 2, name: "B" }, { id: 1, name: "C" }],
+ *   (value) => value.id,
+ *   false
+ * );
+ * // Result: [{ id: 2, name: "B" }, { id: 1, name: "C" }]
+ */
+export const by = <V>(
+  values: V[] | readonly V[],
+  key: (value: V) => unknown,
+  keepFirst: boolean = true,
+): V[] => {
+  const map = new Map<unknown, V>();
+  values.forEach((v) => {
+    const k = key(v);
+    if (map.has(k)) {
+      if (keepFirst) return;
+      map.delete(k);
+    }
+    // different delete and set operations for keepLast so order is preserved
+    map.set(k, v);
+  });
+  return Array.from(map.values());
+};

package/src/zodutil/index.ts

@@ -7,4 +7,4 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export * as zodutil from "./zodutil";
+export * as zodutil from "@/zodutil/zodutil";

package/src/zodutil/zodutil.ts

@@ -7,7 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { z, type ZodSchema } from "zod";
+import { z } from "zod";
 
 import { deep } from "@/deep";
 import { type UnknownRecord } from "@/record";
@@ -43,32 +43,4 @@ export const getFieldSchema: deep.TypedGet<z.ZodTypeAny, z.ZodTypeAny> = ((
     { ...options, getter: sourceTypeGetter } as deep.GetOptions<boolean | undefined>,
   ) as z.ZodTypeAny | null) as deep.TypedGet<z.ZodTypeAny, z.ZodTypeAny>;
 
-/**
- * Creates a transformer function that validates and transforms input values based on
- * provided schemas. The first schema to successfully validate the input value is used
- * in the transformation. If no schema is found that validates the input, the
- * transformer function returns null.
- *
- * @template Input - The type of the input value.
- * @template Output - The type of the output value.
- * @param transform - The function to transform the input value to the output value.
- * @param schemas - An array of Zod schemas to validate the input value against.
- * @returns A function that takes an unknown value, validates it against the schemas,
- * and uses the first valid schema to transform the input type. If no schema can
- * validate the input, the function returns null.
- */
-export const transformer =
-  <Input, Output>(
-    transform: (input: Input) => Output,
-    schemas: ZodSchema<Input>[],
-  ): ((value: unknown) => Output | null) =>
-  (value) => {
-    const matchingSchema = schemas.find((schema) => {
-      const res = schema.safeParse(value);
-      return res.success;
-    });
-    if (matchingSchema == null) return null;
-    return transform(matchingSchema.parse(value));
-  };
-
 export const bigInt = z.bigint().or(z.string().transform(BigInt));