@synnaxlabs/x 0.7.0

package/src/deep/equal.ts

@@ -0,0 +1,65 @@
+// 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";
+import { Primitive } from "@/primitive";
+
+type DeepEqualBaseRecord = UnknownRecord | {
+  equals?: (other: any) => boolean;
+}
+
+export const equal = <T extends DeepEqualBaseRecord | DeepEqualBaseRecord[] | Primitive[]>(a: T, b: T): boolean => {
+  const aIsArray = Array.isArray(a);
+  const bIsArray = Array.isArray(b);
+  if (aIsArray !== bIsArray) return false;
+  if (aIsArray && bIsArray) {
+    const aArr = a as DeepEqualBaseRecord[];
+    const bArr = b as DeepEqualBaseRecord[];
+    if (aArr.length !== bArr.length) return false;
+    for (let i = 0; i < aArr.length; i++) {
+      if (!equal(aArr[i], bArr[i])) return false;
+    }
+    return true;
+  }
+  if (typeof a !== "object" || typeof b !== "object") return a === b;
+  if ("equals" in a) 
+    return (a.equals as (other: any) => boolean)(b);
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    // @ts-expect-error
+    const aVal = a[key];
+    // @ts-expect-error
+    const bVal = b[key];
+    if (typeof aVal === "object" && typeof bVal === "object") {
+      if (!equal(aVal, bVal)) return false;
+    } else if (aVal !== bVal) return false;
+  }
+  return true;
+};
+
+export const partialEqual = <T extends UnknownRecord<T>>(
+  base: T,
+  partial: Partial<T>,
+): boolean => {
+  const baseKeys = Object.keys(base);
+  const partialKeys = Object.keys(partial);
+  if (partialKeys.length > baseKeys.length) return false;
+  for (const key of partialKeys) {
+    // @ts-expect-error
+    const baseVal = base[key];
+    // @ts-expect-error
+    const partialVal = partial[key];
+    if (typeof baseVal === "object" && typeof partialVal === "object") {
+      if (!partialEqual(baseVal, partialVal)) return false;
+    } else if (baseVal !== partialVal) return false;
+  }
+  return true;
+};

package/src/deep/external.ts

@@ -0,0 +1,15 @@
+// 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 * from "@/deep/copy";
+export * from "@/deep/delete";
+export * from "@/deep/key";
+export * from "@/deep/merge";
+export * from "@/deep/partial";
+export * from "@/deep/equal";

package/src/deep/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 deep from "@/deep/external";

package/src/deep/key.ts

@@ -0,0 +1,46 @@
+// 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 Join } from "@/join";
+
+type Prev = [
+  never,
+  0,
+  1,
+  2,
+  3,
+  4,
+  5,
+  6,
+  7,
+  8,
+  9,
+  10,
+  11,
+  12,
+  13,
+  14,
+  15,
+  16,
+  17,
+  18,
+  19,
+  20,
+  ...Array<0>,
+];
+
+export type Key<T, D extends number = 5> = [D] extends [never]
+  ? never
+  : T extends object
+  ? {
+      [K in keyof T]-?: K extends string | number
+        ? `${K}` | Join<K, Key<T[K], Prev[D]>>
+        : never;
+    }[keyof T]
+  : "";

package/src/deep/merge.spec.ts

@@ -0,0 +1,63 @@
+// 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("deepMerge", () => {
+  it("should deep two objects", () => {
+    const a: TestRecord = {
+      a: 1,
+      b: {
+        c: 2,
+      },
+    };
+    const b: TestRecord = {
+      a: 3,
+      b: {
+        d: 4,
+      },
+    };
+    const c: TestRecord = {
+      a: 3,
+      b: {
+        c: 2,
+        d: 4,
+      },
+    };
+    expect(deep.merge(a, b)).toEqual(c);
+  });
+  it("Should set a value even when its parent is undefined", () => {
+    const a: TestRecord = {
+      a: 1,
+    };
+    const b: TestRecord = {
+      a: 3,
+      b: {
+        d: 4,
+      },
+    };
+    const c: TestRecord = {
+      a: 3,
+      b: {
+        d: 4,
+      },
+    };
+    expect(deep.merge(a, b)).toEqual(c);
+  });
+});

package/src/deep/merge.ts

@@ -0,0 +1,41 @@
+// 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 Partial } from "@/deep/partial";
+import { isObject } from "@/identity";
+import { type UnknownRecord } from "@/record";
+
+export const merge = <T extends UnknownRecord<T>>(
+  base: T,
+  ...objects: Array<Partial<T>>
+): T => {
+  if (objects.length === 0) return base;
+  const source = objects.shift();
+
+  if (isObject(base) && isObject(source)) {
+    for (const key in source) {
+      try {
+        if (isObject(source[key])) {
+          if (!(key in base)) Object.assign(base, { [key]: {} });
+          // @ts-expect-error
+          merge(base[key], source[key]);
+        } else {
+          Object.assign(base, { [key]: source[key] });
+        }
+      } catch (e) {
+        if (e instanceof TypeError) {
+          throw new TypeError(`.${key}: ${e.message}`);
+        }
+        throw e;
+      }
+    }
+  }
+
+  return merge(base, ...objects);
+};

package/src/deep/partial.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 type Partial<T> = T extends object
+  ? {
+      [P in keyof T]?: Partial<T[P]>;
+    }
+  : T;

package/src/destructor.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 type Destructor = () => void;

package/src/identity.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.
+
+import { type UnknownRecord } from "@/record";
+
+export const isObject = <T extends UnknownRecord = UnknownRecord>(
+  item?: unknown,
+): item is T => item != null && typeof item === "object" && !Array.isArray(item);

package/src/index.ts

@@ -0,0 +1,34 @@
+// 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 * from "@/telem";
+export * from "@/primitive";
+export * from "@/record";
+export * from "@/renderable";
+export * from "@/optional";
+export * from "@/identity";
+export * from "@/runtime";
+export * from "@/deep";
+export * from "@/debounce";
+export * from "@/clamp";
+export * from "@/compare";
+export * from "@/runtime";
+export * from "@/unique";
+export * from "@/kv";
+export * from "@/spatial";
+export * from "@/url";
+export * from "@/toArray";
+export * from "@/case";
+export * from "@/search";
+export * from "@/destructor";
+export * from "@/worker/worker";
+export * from "@/transform";
+export * from "@/binary";
+export * from "@/observe";
+export * from "@/change";

package/src/join.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 type Join<K, P> = K extends string | number
+  ? P extends string | number
+    ? `${K}${"" extends P ? "" : "."}${P}`
+    : never
+  : never;

package/src/kv/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 kv from "@/kv/types";

package/src/kv/types.ts

@@ -0,0 +1,52 @@
+// 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 interface KV<K = string, V = string, WK = K, WV = V, D = K>
+  extends Reader<K, V>,
+    Writer<WK, WV>,
+    Deleter<D> {}
+
+export interface Reader<K = string, V = string> {
+  /** @returns the value for a given key, or null if the key is not present. */
+  get: (key: K) => V | null;
+}
+
+export interface Writer<K = string, V = string> {
+  /** Sets a key-value pair in the store. */
+  set: (key: K, value: V) => void;
+}
+
+export interface Deleter<K = string> {
+  /** Deletes a key-value pair from the store. */
+  delete: (key: K) => void;
+}
+
+/** A read-writable key-value store. */
+export interface Async<K = string, V = string, WK = K, WV = V, D = K>
+  extends AsyncReader<K, V>,
+    AsyncWriter<WK, WV>,
+    AsyncDeleter<D> {}
+
+/** A readable key-value store. */
+export interface AsyncReader<K = string, V = string> {
+  /** Get the value for a given key. */
+  get: (key: K) => Promise<V | null>;
+}
+
+/** A writable key-value store. */
+export interface AsyncWriter<K = string, V = string> {
+  /** Sets a key-value pair in the store. The value must be serializable. */
+  set: (key: K, value: V) => Promise<void>;
+}
+
+/** A key-value store that can delete key-value pairs. */
+export interface AsyncDeleter<K = string> {
+  /** Deletes a key-value pair from the store. */
+  delete: (key: K) => Promise<void>;
+}

package/src/mock/MockGLBufferController.ts

@@ -0,0 +1,70 @@
+// 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 { vi, Mock } from "vitest";
+
+import { GLBufferController } from "@/telem/gl";
+
+export class MockGLBufferController implements GLBufferController {
+  ARRAY_BUFFER: number = 1;
+  STATIC_DRAW: number = 2;
+  DYNAMIC_DRAW: number = 3;
+
+  targets: Record<number, number> = {};
+  counter: number = 0;
+  buffers: Record<number, ArrayBuffer> = {};
+
+  createBufferMock: Mock<[], WebGLBuffer | null> = vi.fn();
+  bufferDataMock: Mock<[number, ArrayBufferLike | number, number]> = vi.fn();
+  bufferSubDataMock: Mock<[number, number, ArrayBufferLike]> = vi.fn();
+  bindBufferMock: Mock<[number, WebGLBuffer | null]> = vi.fn();
+  deleteBufferMock: Mock<[WebGLBuffer | null]> = vi.fn();
+
+  deleteBuffer(buffer: WebGLBuffer | null): void {
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+    if (buffer != null) delete this.buffers[buffer as number];
+    this.deleteBufferMock(buffer);
+  }
+
+  createBuffer(): WebGLBuffer | null {
+    this.createBufferMock();
+    const v = ++this.counter;
+    this.buffers[v] = new ArrayBuffer(0);
+    return v;
+  }
+
+  bufferData(
+    target: number,
+    dataOrSize: ArrayBufferLike | number,
+    usage: number
+  ): void {
+    if (typeof dataOrSize === "number")
+      this.buffers[this.targets[target]] = new ArrayBuffer(dataOrSize);
+    else this.buffers[this.targets[target]] = dataOrSize;
+
+    this.bufferDataMock(target, dataOrSize as any, usage);
+  }
+
+  bindBuffer(target: number, buffer: WebGLBuffer | null): void {
+    if (buffer === 0) throw new Error("Cannot bind to 0");
+    this.targets[target] = buffer as number;
+    this.bindBufferMock(target, buffer);
+  }
+
+  bufferSubData(target: number, offset: number, data: ArrayBufferLike): void {
+    let buffer = this.buffers[this.targets[target]];
+    if (buffer == null) {
+      buffer = new ArrayBuffer(offset + data.byteLength);
+      this.buffers[target] = buffer;
+    }
+    const view = new Uint8Array(buffer);
+    view.set(new Uint8Array(data), offset);
+    this.bufferSubDataMock(target, offset, data);
+  }
+}

package/src/mock/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 * from "@/mock/MockGLBufferController";

package/src/observe/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 observe from "@/observe/observe";

package/src/observe/observe.ts

@@ -0,0 +1,33 @@
+// 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 Destructor } from "@/destructor";
+
+export type Handler<T> = (value: T) => void;
+
+export interface Observable<T> {
+  onChange: (handler: Handler<T>) => Destructor;
+}
+
+export class Observer<T> implements Observable<T> {
+  private readonly handlers: Map<Handler<T>, null>;
+
+  constructor() {
+    this.handlers = new Map();
+  }
+
+  onChange(handler: Handler<T>): Destructor {
+    this.handlers.set(handler, null);
+    return () => this.handlers.delete(handler);
+  }
+
+  notify(value: T): void {
+    this.handlers.forEach((_, handler) => handler(value));
+  }
+}

package/src/optional.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 type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;

package/src/primitive.ts

@@ -0,0 +1,46 @@
+// 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 "@/record";
+
+export type Primitive =
+  | string
+  | number
+  | bigint
+  | boolean
+  | Stringer
+  | null
+  | undefined;
+
+export interface Stringer {
+  toString: () => string;
+}
+
+export const isStringer = (value: unknown): boolean =>
+  value != null && typeof value === "object" && "toString" in value;
+
+export type PrimitiveRecord = Record<Key, Primitive>;
+
+export const primitiveIsZero = (value: Primitive): boolean => {
+  if (isStringer(value)) return value?.toString().length === 0;
+  switch (typeof value) {
+    case "string":
+      return value.length === 0;
+    case "number":
+      return value === 0;
+    case "bigint":
+      return value === BigInt(0);
+    case "boolean":
+      return !value;
+    case "undefined":
+      return true;
+    case "object":
+      return value === null;
+  }
+};

package/src/record.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.
+
+import { z } from "zod";
+
+import { type RenderableValue } from "@/renderable";
+
+export type Key = string | number | symbol;
+
+export type KeyedRecord<
+  K extends Key = Key,
+  E extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  key: K;
+} & Partial<Record<keyof E, unknown>>;
+
+export type UnknownRecord<E extends Record<Key, unknown> = Record<Key, unknown>> =
+  Partial<Record<keyof E, unknown>>;
+
+export type RenderableRecord<
+  E extends Record<string, RenderableValue> = Record<string, RenderableValue>,
+> = E;
+
+export type KeyedRenderableRecord<
+  K extends Key = Key,
+  E extends Record<string, RenderableValue> = Record<string, RenderableValue>,
+> = KeyedRecord<K, E> & Omit<RenderableRecord<E>, "key">;
+
+export const unknownRecordZ = z.record(
+  z.union([z.number(), z.string(), z.symbol()]),
+  z.unknown(),
+);
+
+export type Entries<T> = {
+  [K in keyof T]: [K, T[K]];
+}[keyof T][];
+
+export const getEntries = <T extends Record<Key, unknown>>(obj: T): Entries<T> =>
+  Object.entries(obj) as Entries<T>;

package/src/renderable.ts

@@ -0,0 +1,20 @@
+// 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 Stringer } from "@/primitive";
+
+export type PureRenderableValue = string | number | undefined;
+export type RenderableValue = PureRenderableValue | Stringer;
+
+export const convertRenderV = (value: RenderableValue): string | number | undefined => {
+  if (value === undefined || typeof value === "string" || typeof value === "number")
+    return value;
+  if (value.toString === undefined) throw new Error("invalid renderer");
+  return value.toString();
+};