@synnaxlabs/x 0.7.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@synnaxlabs/x",
+  "private": false,
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Common Utilities for Synnax Labs",
+  "repository": "https://github.com/synnaxlabs/synnax/tree/main/x/go",
+  "keywords": [
+    "synnax",
+    "utilities",
+    "data acquisition",
+    "big data",
+    "telemetry",
+    "control syustems"
+  ],
+  "dependencies": {
+    "async-mutex": "^0.4.0",
+    "js-convert-case": "^4.2.0",
+    "msgpackr": "^1.9.9",
+    "nanoid": "^5.0.2",
+    "zod": "3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.8.7",
+    "@vitest/coverage-v8": "^0.34.6",
+    "vite": "^4.5.0",
+    "vitest": "^0.34.6",
+    "@synnaxlabs/tsconfig": "0.0.1",
+    "@synnaxlabs/vite-plugin": "0.0.1",
+    "eslint-config-synnaxlabs": "0.0.0"
+  },
+  "main": "dist/x.cjs.js",
+  "module": "dist/x.es.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest",
+    "cov": "vitest --coverage",
+    "lint": "eslint \"src/**/*.ts*\"",
+    "fix": "eslint \"src/**/*.ts*\" --fix"
+  }
+}

package/src/binary/encoder.spec.ts

@@ -0,0 +1,31 @@
+// Copyright 2023 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, test } from "vitest";
+import { z } from "zod";
+
+import { binary } from "@/binary";
+
+const SampleSchema = z.object({
+  channelKey: z.string(),
+  timeStamp: z.number(),
+  value: z.unknown(),
+});
+
+describe.each(binary.ENCODERS)("encoder", (e) => {
+  test(`[encoder] - encoder ${e.contentType} should encode correctly`, () => {
+    const sample = {
+      channelKey: "test",
+      timeStamp: 123,
+      value: new Array([1, 2, 3]),
+    };
+    const encoded = e.encode(sample);
+    expect(e.decode(encoded, SampleSchema)).toEqual(sample);
+  });
+});

package/src/binary/encoder.ts

@@ -0,0 +1,118 @@
+// Copyright 2023 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 { addExtension, pack, unpack } from "msgpackr";
+import { type ZodSchema, type z } from "zod";
+
+import { Case } from "@/case";
+
+/**
+ * CustomTypeEncoder is an interface for a class that needs to transform its
+ * value before encoding.
+ */
+interface CustomTypeEncoder {
+  /** The Class the custom encoder is set for */
+  Class: Function;
+
+  /**
+   * The function that transforms the value before encoding;
+   *
+   * @param instance - The instance of the class to transform.
+   * @returns The transformed value.
+   */
+  write: <P>(instance: P) => unknown;
+}
+
+/**
+ * EncoderDecoder is an entity that encodes and decodes messages to and from a
+ * binary format.
+ */
+export interface EncoderDecoder {
+  /** The HTTP content type of the encoder */
+  contentType: string;
+
+  /**
+   * Encodes the given payload into a binary representation.
+   *
+   * @param payload - The payload to encode.
+   * @returns An ArrayBuffer containing the encoded payload.
+   */
+  encode: (payload: unknown) => ArrayBuffer;
+
+  /**
+   * Decodes the given binary representation into a type checked payload.
+   *
+   * @param data - The data to decode.
+   * @param schema - The schema to decode the data with.
+   */
+  decode: <P>(data: Uint8Array | ArrayBuffer, schema?: ZodSchema<P>) => P;
+}
+
+interface StaticEncoderDecoder {
+  registerCustomType: (encoder: CustomTypeEncoder) => void;
+}
+
+/** MsgpackEncoderDecoder is a msgpack implementation of EncoderDecoder. */
+export class MsgpackEncoderDecoder implements EncoderDecoder {
+  contentType = "application/msgpack";
+
+  encode(payload: unknown): ArrayBuffer {
+    return pack(Case.toSnake(payload));
+  }
+
+  decode<P extends z.ZodTypeAny>(
+    data: Uint8Array | ArrayBuffer,
+    schema?: P,
+  ): z.output<P> {
+    const unpacked = Case.toCamel(unpack(new Uint8Array(data)));
+    return schema != null ? schema.parse(unpacked) : (unpacked as P);
+  }
+
+  static registerCustomType(encoder: CustomTypeEncoder): void {
+    addExtension({ type: 0, ...encoder });
+  }
+}
+
+/** JSONEncoderDecoder is a JSON implementation of EncoderDecoder. */
+export class JSONEncoderDecoder implements EncoderDecoder {
+  contentType = "application/json";
+
+  encode(payload: unknown): ArrayBuffer {
+    const json = JSON.stringify(Case.toSnake(payload), (_, v) => {
+      if (ArrayBuffer.isView(v)) return Array.from(v as Uint8Array);
+      return v;
+    });
+    return new TextEncoder().encode(json);
+  }
+
+  decode<P extends z.ZodTypeAny>(
+    data: Uint8Array | ArrayBuffer,
+    schema?: P,
+  ): z.output<P> {
+    const unpacked = Case.toCamel(JSON.parse(new TextDecoder().decode(data)));
+    return schema != null ? schema.parse(unpacked) : (unpacked as P);
+  }
+
+  static registerCustomType(): void {}
+}
+
+export const ENCODERS: EncoderDecoder[] = [
+  new MsgpackEncoderDecoder(),
+  new JSONEncoderDecoder(),
+];
+
+export const ENCODER_CLASSES: StaticEncoderDecoder[] = [
+  MsgpackEncoderDecoder,
+  JSONEncoderDecoder,
+];
+
+export const registerCustomTypeEncoder = (encoder: CustomTypeEncoder): void =>
+  ENCODER_CLASSES.forEach((encoderClass) => {
+    encoderClass.registerCustomType(encoder);
+  });

package/src/binary/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2023 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 binary from "@/binary/encoder";

package/src/case.ts

@@ -0,0 +1,31 @@
+// Copyright 2023 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 { camelKeys as _camelKeys, snakeKeys as _snakeKeys } from "js-convert-case";
+
+import { type UnknownRecord } from "@/record";
+
+const options = {
+  recursive: true,
+  recursiveInArray: true,
+  keepTypesOnRecursion: [Number, String, Uint8Array],
+};
+
+const snakeKeys = <T>(entity: T): Record<string, T[keyof T]> =>
+  _snakeKeys(entity, options) as Record<string, T[keyof T]>;
+
+const camelKeys = <T extends UnknownRecord<T>>(entity: T): Record<string, T[keyof T]> =>
+  _camelKeys(entity, options) as Record<string, T[keyof T]>;
+
+export namespace Case {
+  export const toSnake = snakeKeys;
+  export const toCamel = camelKeys;
+  export const capitalize = (str: string): string =>
+    str[0].toUpperCase() + str.slice(1);
+}

package/src/change/change.ts

@@ -0,0 +1,31 @@
+// Copyright 2023 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 { z } from "zod";
+
+export type Variant = "set" | "delete";
+
+export const Z = <V extends z.ZodTypeAny>(value: V) =>
+  z.object({
+    variant: z.enum(["set", "delete"]),
+    key: z.string(),
+    value,
+  });
+
+export type Change<K, V> =
+  | {
+      variant: "set";
+      key: K;
+      value: V;
+    }
+  | {
+      variant: "delete";
+      key: K;
+      value?: V;
+    };

package/src/change/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2023 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 change from "@/change/change";

package/src/clamp.ts

@@ -0,0 +1,14 @@
+// Copyright 2023 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 const clamp = (value: number, min?: number, max?: number): number => {
+  if (min != null) value = Math.max(value, min);
+  if (max != null) value = Math.min(value, max);
+  return value;
+};

package/src/compare/compare.ts

@@ -0,0 +1,116 @@
+// Copyright 2023 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 { type Primitive, isStringer, type PrimitiveRecord } from "@/primitive";
+import { type spatial } from "@/spatial";
+
+export type CompareF<T> = (a: T, b: T) => number;
+
+/**
+ * Creates the appropriate compare function for sorting the given
+ * primitive type.
+ *
+ * @param v The primitive value to create a compare function for.
+ * This is used to determine the type of comparison to perform.
+ * @param reverse Whether to reverse the sort order.
+ */
+export const newF = <T extends Primitive>(
+  v: T,
+  reverse: boolean = false,
+): CompareF<T> => {
+  const t = isStringer(v) ? "stringer" : typeof v;
+  let f: CompareF<T>;
+  switch (t) {
+    case "string":
+      f = (a: T, b: T) => (a as string).localeCompare(b as string);
+      break;
+    case "stringer":
+      f = (a: T, b: T) =>
+        (a as string).toString().localeCompare((b as string).toString());
+      break;
+    case "number":
+      f = (a: T, b: T) => (a as number) - (b as number);
+      break;
+    case "bigint":
+      f = (a: T, b: T) => ((a as bigint) - (b as bigint) > BigInt(0) ? 1 : -1);
+      break;
+    case "boolean":
+      f = (a: T, b: T) => Number(a) - Number(b);
+      break;
+    default:
+      console.warn("sortFunc: unknown type");
+      return () => -1;
+  }
+  return reverse ? reverseF(f) : f;
+};
+
+/**
+ * Creates a compare function that compares the field of the given object.
+ *
+ * @param key The key of the field to compare.
+ * @param value The object to compare the field of. This is used to determine the type of
+ * comparison to perform.
+ * @param reverse Whether to reverse the sort order.
+ */
+export const newFieldF = <T extends PrimitiveRecord>(
+  key: keyof T,
+  value: T,
+  reverse?: boolean,
+): CompareF<T> => {
+  const f = newF(value[key], reverse);
+  return (a: T, b: T) => f(a[key], b[key]);
+};
+
+/**
+ * Compares the two primitive arrays.
+ * @param a The first array to compare.
+ * @param b The second array to compare.
+ * @returns The array with the greater length if the array lengths are not equal. If the
+ * arrays are the same length, returns 0 if all elements are equal, otherwise returns -1.
+ */
+export const primitiveArrays = <T extends Primitive>(
+  a: readonly T[] | T[],
+  b: readonly T[] | T[],
+): number => {
+  if (a.length !== b.length) return a.length - b.length;
+  return a.every((v, i) => v === b[i]) ? 0 : -1;
+};
+
+export const unorderedPrimitiveArrays = <T extends Primitive>(
+  a: readonly T[] | T[],
+  b: readonly T[] | T[],
+): number => {
+  if (a.length !== b.length) return a.length - b.length;
+  if (a.length === 0) return 0;
+  const compareF = newF(a[0]);
+  const aSorted = [...a].sort(compareF);
+  const bSorted = [...b].sort(compareF);
+  return aSorted.every((v, i) => v === bSorted[i]) ? 0 : -1;
+};
+
+export const order = (a: spatial.Order, b: spatial.Order): number => {
+  if (a === b) return 0;
+  if (a === "first" && b === "last") return 1;
+  return -1;
+};
+
+/** @returns the reverse of the given compare function. */
+export const reverseF =
+  <T>(f: CompareF<T>): CompareF<T> =>
+  (a: T, b: T) =>
+    f(b, a);
+
+/** The equal return value of a compare function. */
+export const EQUAL = 0;
+
+/** The less than return value of a compare function. */
+export const LESS_THAN = -1;
+
+/** The greater than return value of a compare function. */
+export const GREATER_THAN = 1;

package/src/compare/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2023 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 compare from "@/compare/compare";

package/src/debounce.ts

@@ -0,0 +1,45 @@
+// Copyright 2023 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 const debounce = <F extends (...args: any[]) => void>(
+  func: F,
+  waitFor: number
+): F => {
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  if (waitFor === 0) return func;
+
+  const debounced = (...args: Parameters<F>): void => {
+    if (timeout !== null) {
+      clearTimeout(timeout);
+      timeout = null;
+    }
+    timeout = setTimeout(() => func(...args), waitFor);
+  };
+
+  return debounced as F;
+};
+
+export const throttle = <F extends (...args: any[]) => void>(
+  func: F,
+  waitFor: number
+): F => {
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  if (waitFor === 0) return func;
+
+  const throttled = (...args: Parameters<F>): void => {
+    if (timeout === null) {
+      timeout = setTimeout(() => {
+        func(...args);
+        timeout = null;
+      }, waitFor);
+    }
+  };
+
+  return throttled as F;
+}

package/src/deep/copy.ts

@@ -0,0 +1,13 @@
+// Copyright 2023 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 { type UnknownRecord } from "@/record";
+
+export const copy = <T extends UnknownRecord<T>>(obj: T): T =>
+  JSON.parse(JSON.stringify(obj));

package/src/deep/delete.spec.ts

@@ -0,0 +1,36 @@
+// Copyright 2023 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, it, expect } from "vitest";
+
+import { deep } from "@/deep";
+
+interface TestRecord {
+  a: number;
+  b: {
+    c?: number;
+    d?: number;
+  };
+}
+
+describe("deepDelete", () => {
+  it("should delete a key", () => {
+    const a: TestRecord = {
+      a: 1,
+      b: {
+        c: 2,
+      },
+    };
+    const b: TestRecord = {
+      a: 1,
+      b: {},
+    };
+    expect(deep.deleteD<TestRecord, 2>(a, "b.c")).toEqual(b);
+  });
+});

package/src/deep/delete.ts

@@ -0,0 +1,27 @@
+// Copyright 2023 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 { type Key } from "@/deep/key";
+import { type UnknownRecord } from "@/record";
+
+export const deleteD = <T extends UnknownRecord<T>, D extends number = 5>(
+  target: T,
+  ...keys: Array<Key<T, D>>
+): T => {
+  keys.forEach((key) => {
+    let curr: any = target;
+    const arr = key.split(".");
+    arr.forEach((k, i) => {
+      // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+      if (i === arr.length - 1) delete curr[k];
+      else curr = curr[k];
+    });
+  });
+  return target;
+};

package/src/deep/equal.spec.ts

@@ -0,0 +1,82 @@
+// Copyright 2023 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, it, expect } from "vitest";
+
+import { deep } from "@/deep";
+
+interface TestRecord {
+  a: number;
+  b: {
+    c?: number;
+    d?: number;
+  };
+}
+
+describe("deepEqual", () => {
+  describe("deepPartialEqual", () => {
+    it("should return true for overlapping objects", () => {
+      const base: TestRecord = { a: 1, b: { c: 2, d: 3 } };
+      const partial: TestRecord = { a: 1, b: { c: 2 } };
+      expect(deep.partialEqual(base, partial)).toBe(true);
+    });
+    it("should return false for non-overlapping objects", () => {
+      const base = { a: 1, b: { c: 2, d: 3 } };
+      const partial = { a: 1, b: { c: 2, d: 4 } };
+      expect(deep.partialEqual(base, partial)).toBe(false);
+    });
+  });
+  describe("deepEqual", () => {
+    it("should return true for equal objects", () => {
+      const a = { a: 1, b: { c: 2, d: 3 } };
+      const b = { a: 1, b: { c: 2, d: 3 } };
+      expect(deep.equal(a, b)).toBe(true);
+    });
+    it("should return false for non-equal objects", () => {
+      const a = { a: 1, b: { c: 2, d: 3 } };
+      const b = { a: 1, b: { c: 2, d: 4 } };
+      expect(deep.equal(a, b)).toBe(false);
+    });
+    it("should return false for partial objects", () => {
+      const a = { a: 1, b: { c: 2, d: 3 } };
+      const b = { a: 1, b: { c: 2 } };
+      expect(deep.equal(a, b)).toBe(false);
+    });
+    it("should return true for primitive arrays that are equal", () => {
+      const a = [1, 2, 3];
+      const b = [1, 2, 3];
+      expect(deep.equal(a, b)).toBe(true);
+    })
+    it("should true for object arrays that are equal", () => {
+      const a = [{ a: 1 }, { b: 2 }];
+      const b = [{ a: 1 }, { b: 2 }];
+      expect(deep.equal(a, b)).toBe(true);
+    });
+    it("should return true for nested object arrays that are equal", () => {
+      const a = [{ a: 1 }, { b: 2, c: [{ d: 3 }] }];
+      const b = [{ a: 1 }, { b: 2, c: [{ d: 3 }] }];
+      expect(deep.equal(a, b)).toBe(true);
+    });
+    it("shold return false for nested object arrays that are not equal", () => {
+      const a = [{ a: 1 }, { b: 2, c: [{ d: 3 }] }];
+      const b = [{ a: 1 }, { b: 2, c: [{ d: 4 }] }];
+      expect(deep.equal(a, b)).toBe(false);
+    });
+    it("should return false for primitive arrays that are not equal", () => {
+      const a = [1, 2, 3];
+      const b = [1, 2, 4];
+      expect(deep.equal(a, b)).toBe(false);
+    });
+    it("should return false for object arrays that are not equal", () => {
+      const a = [{ a: 1 }, { b: 2 }];
+      const b = [{ a: 1 }, { b: 2, c: 4}];
+      expect(deep.equal(a, b)).toBe(false);
+    });
+  });
+});