@synnaxlabs/x 0.16.1 → 0.24.0

package/src/join.ts

@@ -1,4 +1,4 @@
-// Copyright 2023 Synnax Labs, Inc.
+// Copyright 2024 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.

package/src/kv/index.ts

@@ -1,4 +1,4 @@
-// Copyright 2023 Synnax Labs, Inc.
+// Copyright 2024 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.

package/src/kv/types.ts

@@ -1,4 +1,4 @@
-// Copyright 2023 Synnax Labs, Inc.
+// Copyright 2024 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.

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

package/src/math/math.ts

@@ -0,0 +1,33 @@
+// 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.
+
+type Value = number | bigint;
+
+/** @returns the product of a and b, coercing b to the type of a if necessary. */
+export const sub = <V extends Value>(a: V, b: Value): V => {
+  if (typeof a === "bigint") return (a - BigInt(b)) as V;
+  return (a - Number(b)) as V;
+};
+
+/** @returns the sum of a and b, coercing b to the type of a if necessary. */
+export const add = <V extends Value>(a: V, b: Value): V => {
+  if (typeof a === "bigint") return (a + BigInt(b)) as V;
+  // @ts-expect-error - a is a number but typescript doesn't recognize that.
+  return (a + Number(b)) as V;
+};
+
+/** @returns true if a is close to b within epsilon. */
+export const closeTo = (a: number, b: number, epsilon = 0.0001): boolean =>
+  Math.abs(a - b) < epsilon;
+
+/** @returns the nearest number to num with 1 significant digit. */
+export const roundToNearestMagnitude = (num: number): number => {
+  const magnitude = Math.pow(10, Math.floor(Math.log10(num)));
+  return Math.round(num / magnitude) * magnitude;
+};

package/src/migrate/index.ts

@@ -1 +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 migrate from "@/migrate/migrate";

package/src/migrate/migrate.spec.ts

@@ -1,79 +1,90 @@
+// 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 { z } from "zod";
 
-import {
-  type Migration,
-  migratable,
-  migrator,
-  type Migrations,
-} from "@/migrate/migrate";
+import { migrate } from "@/migrate";
 
-const entityV0_0_0 = migratable.extend({
+const entityV0 = z.object({
+  version: z.literal("0.0.0"),
   name: z.string(),
 });
 
-type EntityV0_0_0 = z.infer<typeof entityV0_0_0>;
+type EntityV0 = z.infer<typeof entityV0>;
 
-const entityV0_0_1 = migratable.extend({
+const entityV1 = z.object({
+  version: z.literal("1.0.0"),
   title: z.string(),
 });
 
-type EntityV0_0_1 = z.infer<typeof entityV0_0_1>;
+const migrateV1 = migrate.createMigration<EntityV0, EntityV1>({
+  name: "entity",
+  inputSchema: entityV0,
+  outputSchema: entityV1,
+  migrate: (entity) => {
+    const { name, ...rest } = entity;
+    return { ...rest, version: "1.0.0", title: entity.name };
+  },
+});
+
+type EntityV1 = z.infer<typeof entityV1>;
 
-const entityV0_0_2 = migratable.extend({
+const entityV2 = z.object({
+  version: z.literal("2.0.0"),
   title: z.string(),
   description: z.string(),
 });
 
-type EntityV0_0_2 = z.infer<typeof entityV0_0_2>;
+type EntityV2 = z.infer<typeof entityV2>;
 
-const migrations: Migrations = {
-  "0.0.0": ((entity: EntityV0_0_0): EntityV0_0_1 => {
-    const { name, ...rest } = entity;
-    return {
-      ...rest,
-      version: "0.0.1",
-      title: entity.name,
-    };
-  }) as Migration<EntityV0_0_0, EntityV0_0_1>,
-  "0.0.1": (entity: EntityV0_0_1): EntityV0_0_2 => {
-    return {
-      ...entity,
-      version: "0.0.2",
-      description: "",
-    };
-  },
+const migrateV2 = migrate.createMigration<EntityV1, EntityV2>({
+  name: "entity",
+  inputSchema: entityV1,
+  outputSchema: entityV2,
+  migrate: (entity) => ({ ...entity, version: "2.0.0", description: "" }),
+});
+
+const migrations: migrate.Migrations = {
+  "0.0.0": migrateV1,
+  "1.0.0": migrateV2,
 };
 
 describe("migrator", () => {
-  it("should migrate an entity from v0.0.0 to v0.0.2", () => {
-    const entity: EntityV0_0_0 = {
-      version: "0.0.0",
-      name: "foo",
-    };
-    const migrated = migrator(migrations)(entity);
-    expect(migrated).toEqual({
-      version: "0.0.2",
-      title: "foo",
-      description: "",
-    });
+  it("should migrate an entity from v0 to v2", () => {
+    const entity: EntityV0 = { version: "0.0.0", name: "foo" };
+    const DEFAULT: EntityV2 = { version: "2.0.0", title: "", description: "" };
+    const migrated = migrate.migrator({
+      name: "entity",
+      migrations,
+      def: DEFAULT,
+    })(entity);
+    expect(migrated).toEqual({ version: "2.0.0", title: "foo", description: "" });
   });
-  it("should not migrate an entity from v0.0.2", () => {
-    const entity: EntityV0_0_2 = {
-      version: "0.0.2",
-      title: "foo",
-      description: "bar",
-    };
-    const migrated = migrator(migrations)(entity);
-    expect(migrated).toEqual(entity);
+  it("should migrate an entity from v1 to v2", () => {
+    const entity: EntityV1 = { version: "1.0.0", title: "foo" };
+    const DEFAULT: EntityV2 = { version: "2.0.0", title: "", description: "" };
+    const migrated = migrate.migrator({
+      name: "entity",
+      migrations,
+      def: DEFAULT,
+    })(entity);
+    expect(migrated).toEqual({ version: "2.0.0", title: "foo", description: "" });
   });
-  it("should not migrate an entity from v0.0.3", () => {
-    const entity = {
-      version: "0.0.3",
-      title: "foo",
-      description: "bar",
-    };
-    const migrated = migrator(migrations)(entity);
+  it("should not migrate an entity from v2 to v2", () => {
+    const entity: EntityV2 = { version: "2.0.0", title: "foo", description: "bar" };
+    const DEFAULT: EntityV2 = { version: "2.0.0", title: "", description: "" };
+    const migrated = migrate.migrator({
+      name: "entity",
+      migrations,
+      def: DEFAULT,
+    })(entity);
     expect(migrated).toEqual(entity);
   });
 });

package/src/migrate/migrate.ts

@@ -1,3 +1,12 @@
+// 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 { z } from "zod";
 
 import { compare } from "@/compare";
@@ -6,6 +15,15 @@ export const semVerZ = z.string().regex(/^\d+\.\d+\.\d+$/);
 
 export type SemVer = z.infer<typeof semVerZ>;
 
+/**
+ * Compares the two semantic versions.
+ *
+ * @param a  The first semantic version.
+ * @param b  The second semantic version.
+ * @returns a number, where the the number is compare.LESS_THAN (negative) if a is OLDER
+ * than B, compare.EQUAL (0) if a is the same as b, and compare.GREATER_THAN (positive)
+ * if a is NEWER than b.
+ */
 const compareSemVer: compare.CompareF<string> = (a, b) => {
   const semA = semVerZ.parse(a);
   const semB = semVerZ.parse(b);
@@ -16,32 +34,123 @@ const compareSemVer: compare.CompareF<string> = (a, b) => {
   return aPatch - bPatch;
 };
 
+/**
+ * @returns true if the first semantic version is newer than the second.
+ * @param a The first semantic version.
+ * @param b The second semantic version.
+ */
 const semVerNewer = (a: SemVer, b: SemVer): boolean =>
   compare.isGreaterThan(compareSemVer(a, b));
 
-export const migratable = z.object({
-  version: semVerZ,
-});
+export type Migratable<V extends string = string> = { version: V };
+
+export type Migration<I extends Migratable, O extends Migratable> = (input: I) => O;
 
-export interface Migratable extends z.infer<typeof migratable> {}
+export interface MigrationProps<
+  I extends Migratable,
+  O extends Migratable,
+  ZI extends z.ZodTypeAny,
+  ZO extends z.ZodTypeAny,
+> {
+  name: string;
+  inputSchema?: ZI;
+  outputSchema?: ZO;
+  migrate: Migration<I, O>;
+}
 
-export type Migration<I = unknown, O = unknown> = (
-  migratable: Migratable & I,
-) => Migratable & O;
+export const createMigration =
+  <
+    I extends Migratable,
+    O extends Migratable,
+    ZI extends z.ZodTypeAny = z.ZodTypeAny,
+    ZO extends z.ZodTypeAny = z.ZodTypeAny,
+  >({
+    name,
+    migrate,
+  }: MigrationProps<I, O, ZI, ZO>): Migration<I, O> =>
+  (input: I): O => {
+    try {
+      const out = migrate(input);
+      console.log(`${name} migrated: ${input.version} -> ${out.version}`);
+      return out;
+    } catch (e) {
+      console.log(`${name} failed to migrate from ${input.version}`);
+      console.error(e);
+      throw e;
+    }
+  };
 
+/**
+ * A record of migrations to be applied, where the key of the record is the
+ * input version of the migration.
+ */
 export type Migrations = Record<string, Migration<any, any>>;
 
-export const migrator = <I = unknown, O = unknown>(
-  migrations: Migrations,
-): Migration<I, O> => {
-  const latestVersion = Object.keys(migrations).sort(compareSemVer).pop() ?? "";
+interface MigratorProps<O extends Migratable, ZO extends z.ZodTypeAny = z.ZodTypeAny> {
+  name: string;
+  migrations: Migrations;
+  def: O;
+  targetSchema?: ZO;
+}
+
+export const migrator = <O extends Migratable, ZO extends z.ZodTypeAny = z.ZodTypeAny>({
+  name,
+  migrations,
+  targetSchema,
+  def,
+}: MigratorProps<O, ZO>): ((v: Migratable) => O) => {
+  const latestMigrationVersion = Object.keys(migrations).sort(compareSemVer).pop();
+  if (latestMigrationVersion == null)
+    return (v: Migratable) => {
+      if (v.version !== def.version) {
+        console.log(
+          `${name} version ${v.version} is newer than latest version of ${def.version}. 
+          Returning default instead.
+          `,
+        );
+        return def;
+      }
+      try {
+        if (targetSchema != null) return targetSchema.parse(v);
+        return v;
+      } catch (e) {
+        console.log(`${name} failed to parse default. Exiting with default`);
+        console.error(e);
+        return def;
+      }
+    };
   const migLength = Object.keys(migrations).length;
+  let migrationApplied = false;
   const f = (old: Migratable): Migratable => {
-    if (migLength === 0 || semVerNewer(old.version, latestVersion)) return old;
-    const version = old.version;
-    const migration = migrations[version];
-    const new_: Migratable = migration(old);
-    return f(new_);
+    try {
+      if (migLength === 0 || semVerNewer(old.version, latestMigrationVersion)) {
+        if (migrationApplied) console.log(`${name} ${old.version} now up to date`);
+        else
+          console.log(
+            `${name} version ${old.version} is up to date with target version ${def.version}`,
+          );
+        return old;
+      }
+      const version = old.version;
+      const migrate = migrations[version];
+      const new_: Migratable = migrate(old);
+      migrationApplied = true;
+      return f(new_);
+    } catch (e) {
+      console.log(
+        `${name} failed to migrate from ${old.version} to ${latestMigrationVersion}`,
+      );
+      console.error(e);
+      return def;
+    }
+  };
+  return (v: Migratable): O => {
+    try {
+      return f(v) as O;
+    } catch (e) {
+      console.log(`${name} failed to parse final result. Exiting with default`);
+      console.error(e);
+      return def;
+    }
   };
-  return f as unknown as Migration<I, O>;
 };

package/src/mock/MockGLBufferController.ts

@@ -1,4 +1,4 @@
-// Copyright 2023 Synnax Labs, Inc.
+// Copyright 2024 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -7,9 +7,9 @@
 // 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 { type Mock,vi } from "vitest";
 
-import { GLBufferController } from "@/telem/gl";
+import { type GLBufferController } from "@/telem/gl";
 
 export class MockGLBufferController implements GLBufferController {
   ARRAY_BUFFER: number = 1;
@@ -27,7 +27,7 @@ export class MockGLBufferController implements GLBufferController {
   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);
   }
@@ -42,13 +42,13 @@ export class MockGLBufferController implements GLBufferController {
   bufferData(
     target: number,
     dataOrSize: ArrayBufferLike | number,
-    usage: 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);
+    this.bufferDataMock(target, dataOrSize, usage);
   }
 
   bindBuffer(target: number, buffer: WebGLBuffer | null): void {

package/src/mock/index.ts

@@ -1,4 +1,4 @@
-// Copyright 2023 Synnax Labs, Inc.
+// Copyright 2024 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.

package/src/observe/index.ts

@@ -1,4 +1,4 @@
-// Copyright 2023 Synnax Labs, Inc.
+// Copyright 2024 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.

package/src/observe/observe.ts

@@ -1,4 +1,4 @@
-// Copyright 2023 Synnax Labs, Inc.
+// Copyright 2024 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -15,19 +15,50 @@ export interface Observable<T> {
   onChange: (handler: Handler<T>) => Destructor;
 }
 
-export class Observer<T> implements Observable<T> {
-  private readonly handlers: Map<Handler<T>, null>;
+export interface ObservableAsyncCloseable<T> extends Observable<T> {
+  close: () => Promise<void>;
+}
+
+export type Transform<I, O> = (value: I) => [O, true] | [O | null, false];
+
+export class Observer<I, O = I> implements Observable<O> {
+  private readonly handlers: Map<Handler<O>, null>;
+  private readonly transform?: Transform<I, O>;
+
+  constructor(transform?: Transform<I, O>, handlers?: Map<Handler<O>, null>) {
+    this.transform = transform;
+    this.handlers = handlers ?? new Map();
+  }
+
+  onChange(handler: Handler<O>): Destructor {
+    this.handlers.set(handler, null);
+    return () => this.handlers.delete(handler);
+  }
+
+  notify(value: I): void {
+    let newValue: O = value as unknown as O;
+    if (this.transform != null) {
+      const [nv, changed] = this.transform(value);
+      if (!changed) return;
+      newValue = nv;
+    }
+    this.handlers.forEach((_, handler) => handler(newValue));
+  }
+}
+
+export class BaseObserver<V> implements Observable<V> {
+  private readonly handlers: Map<Handler<V>, null>;
 
-  constructor(handlers?: Map<Handler<T>, null>) {
+  constructor(handlers?: Map<Handler<V>, null>) {
     this.handlers = handlers ?? new Map();
   }
 
-  onChange(handler: Handler<T>): Destructor {
+  onChange(handler: Handler<V>): Destructor {
     this.handlers.set(handler, null);
     return () => this.handlers.delete(handler);
   }
 
-  notify(value: T): void {
+  notify(value: V): void {
     this.handlers.forEach((_, handler) => handler(value));
   }
 }

package/src/observe/obsever.spec.ts

@@ -0,0 +1,56 @@
+// 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 { observe } from "@/observe";
+
+describe("observe", () => {
+  describe("Observer", () => {
+    it("should correctly notify the receives of values", () => {
+      const observer = new observe.Observer<number>();
+      const values: number[] = [];
+      observer.onChange((value) => values.push(value));
+      observer.notify(1);
+      observer.notify(2);
+      expect(values).toEqual([1, 2]);
+    });
+    it("should stop notifying a handler after the destructor is called", () => {
+      const observer = new observe.Observer<number>();
+      const values: number[] = [];
+      const destructor = observer.onChange((value) => values.push(value));
+      observer.notify(1);
+      destructor();
+      observer.notify(2);
+      expect(values).toEqual([1]);
+    });
+    it("should correctly transform an observed value", () => {
+      const observer = new observe.Observer<number, string>((value) => [
+        value.toString(),
+        true,
+      ]);
+      const values: string[] = [];
+      observer.onChange((value) => values.push(value));
+      observer.notify(1);
+      observer.notify(2);
+      expect(values).toEqual(["1", "2"]);
+    });
+    it("should not notify when the transform returns false", () => {
+      const observer = new observe.Observer<number, string>((value) => [
+        value.toString(),
+        false,
+      ]);
+      const values: string[] = [];
+      observer.onChange((value) => values.push(value));
+      observer.notify(1);
+      observer.notify(2);
+      expect(values).toEqual([]);
+    });
+  });
+});

package/src/optional.ts

@@ -1,4 +1,4 @@
-// Copyright 2023 Synnax Labs, Inc.
+// Copyright 2024 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -9,7 +9,6 @@
 
 export type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
 
-
 export type Required<T> = {
-    [P in keyof T]-?: T[P];
-};
+  [P in keyof T]-?: T[P];
+};

package/src/primitive.ts

@@ -1,4 +1,4 @@
-// Copyright 2023 Synnax Labs, Inc.
+// Copyright 2024 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.

package/src/record.ts

@@ -1,4 +1,4 @@
-// Copyright 2023 Synnax Labs, Inc.
+// Copyright 2024 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -11,18 +11,22 @@ import { z } from "zod";
 
 export type Key = string | number | symbol;
 
-export type UnknownRecord = { [key: Key]: unknown };
+export type UnknownRecord = Record<Key, unknown>;
 
-export type Keyed<K extends Key> = { key: K };
+export interface Keyed<K extends Key> {
+  key: K;
+}
 
 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 type Entries<T> = Array<
+  {
+    [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

@@ -1,4 +1,4 @@
-// Copyright 2023 Synnax Labs, Inc.
+// Copyright 2024 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.

package/src/runtime/detect.ts

@@ -1,4 +1,4 @@
-// Copyright 2023 Synnax Labs, Inc.
+// Copyright 2024 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -17,14 +17,14 @@ export type Runtime = "browser" | "node" | "webworker";
  */
 export const detect = (): Runtime => {
   if (
-    // eslint-disable-next-line @typescript-eslint/prefer-optional-chain
+     
     typeof process !== "undefined" &&
     process.versions != null &&
     process.versions.node != null
   )
     return "node";
 
-  // eslint-disable-next-line @typescript-eslint/prefer-optional-chain
+   
   if (typeof window === "undefined" || window.document === undefined)
     return "webworker";
 

package/src/runtime/external.ts

@@ -1,4 +1,4 @@
-// Copyright 2023 Synnax Labs, Inc.
+// Copyright 2024 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.