@synnaxlabs/x 0.42.3 → 0.44.0

package/src/instance/matcher.spec.ts

@@ -0,0 +1,78 @@
+// Copyright 2025 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 { instance } from "@/instance";
+
+describe("createMatcher", () => {
+  class TestClass implements instance.Discriminated {
+    discriminator = "test";
+    constructor(public value: string) {}
+  }
+
+  const isTestClass = instance.createMatcher("test", TestClass);
+
+  it("should return true for instances of the class", () => {
+    const instance = new TestClass("value");
+    expect(isTestClass(instance)).toBe(true);
+  });
+
+  it("should return true for objects with matching discriminator", () => {
+    const obj = { discriminator: "test", value: "value" };
+    expect(isTestClass(obj)).toBe(true);
+  });
+
+  it("should return false for null", () => {
+    expect(isTestClass(null)).toBe(false);
+  });
+
+  it("should return false for undefined", () => {
+    expect(isTestClass(undefined)).toBe(false);
+  });
+
+  it("should return false for non-objects", () => {
+    expect(isTestClass("string")).toBe(false);
+    expect(isTestClass(123)).toBe(false);
+    expect(isTestClass(true)).toBe(false);
+  });
+
+  it("should return false for objects with different discriminator", () => {
+    const obj = { discriminator: "other", value: "value" };
+    expect(isTestClass(obj)).toBe(false);
+  });
+
+  it("should return false for objects without discriminator", () => {
+    const obj = { value: "value" };
+    expect(isTestClass(obj)).toBe(false);
+  });
+
+  it("should work with multiple class instances", () => {
+    class ClassA implements instance.Discriminated {
+      discriminator = "a";
+      constructor(public value: string) {}
+    }
+
+    class ClassB implements instance.Discriminated {
+      discriminator = "b";
+      constructor(public value: string) {}
+    }
+
+    const isClassA = instance.createMatcher("a", ClassA);
+    const isClassB = instance.createMatcher("b", ClassB);
+
+    const instanceA = new ClassA("value");
+    const instanceB = new ClassB("value");
+
+    expect(isClassA(instanceA)).toBe(true);
+    expect(isClassA(instanceB)).toBe(false);
+    expect(isClassB(instanceA)).toBe(false);
+    expect(isClassB(instanceB)).toBe(true);
+  });
+});

package/src/instance/matcher.ts

@@ -0,0 +1,98 @@
+// Copyright 2025 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.
+
+/**
+ * Interface for objects that can be discriminated by a string identifier.
+ * Classes or objects implementing this interface must have a discriminator property
+ * that uniquely identifies their type.
+ *
+ * @example
+ * ```typescript
+ * class User implements Discriminated {
+ *   discriminator = "user";
+ *   constructor(public name: string) {}
+ * }
+ * ```
+ */
+export interface Discriminated {
+  discriminator: string;
+}
+
+/**
+ * Creates a type guard function that checks if a value is an instance of a class
+ * using a discriminator property. It is up to the caller to ensure that the
+ * discriminator property is unique, consistent across all instances of the class,
+ * and will not appear in objects that are not instances of the class.
+ *
+ * This is particularly useful when working with instances of classes that have
+ * been duplicated or mangled by a bundler.
+ *
+ * @typeParam T - The type that extends Discriminated
+ * @param discriminator - The string value to match against the object's discriminator property
+ * @param cls - The class constructor to check for instanceof
+ * @returns A type guard function that returns true if the value matches either condition
+ *
+ * @example
+ * ```typescript
+ * class User implements Discriminated {
+ *   discriminator = "user";
+ *   constructor(public name: string) {}
+ * }
+ *
+ * const isUser = createMatcher("user", User);
+ *
+ * // Works with class instances
+ * const user = new User("John");
+ * if (isUser(user)) {
+ *   console.log(user.name); // TypeScript knows user is a User
+ * }
+ *
+ * // Works with plain objects
+ * const obj = { discriminator: "user", name: "John" };
+ * if (isUser(obj)) {
+ *   console.log(obj.name); // TypeScript knows obj is a User
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Working with multiple types
+ * class Admin implements Discriminated {
+ *   discriminator = "admin";
+ *   constructor(public name: string, public role: string) {}
+ * }
+ *
+ * class Guest implements Discriminated {
+ *   discriminator = "guest";
+ *   constructor(public name: string) {}
+ * }
+ *
+ * const isAdmin = createMatcher("admin", Admin);
+ * const isGuest = createMatcher("guest", Guest);
+ *
+ * function handleUser(user: unknown) {
+ *   if (isAdmin(user)) {
+ *     console.log(user.role); // TypeScript knows user is an Admin
+ *   } else if (isGuest(user)) {
+ *     console.log(user.name); // TypeScript knows user is a Guest
+ *   }
+ * }
+ * ```
+ */
+export const createMatcher =
+  <T extends Discriminated>(
+    discriminator: string,
+    cls: new (...args: any[]) => T,
+  ): ((value: unknown) => value is T) =>
+  (value: unknown): value is T =>
+    value instanceof cls ||
+    (typeof value === "object" &&
+      value !== null &&
+      "discriminator" in value &&
+      value.discriminator === discriminator);

package/src/jsonrpc/jsonrpc.spec.ts

@@ -109,8 +109,9 @@ describe("JSON-RPC", () => {
   });
   describe("encodeMessage", () => {
     it("should encode a message", () => {
-      const message = {
+      const message: jsonRPC.Request = {
         jsonrpc: "2.0",
+        id: 1,
         method: "$/status/show",
       };
       const messageStr = JSON.stringify(message);

package/src/jsonrpc/jsonrpc.ts

@@ -11,14 +11,43 @@ import z from "zod";
 
 import { binary } from "@/binary";
 
-const messageZ = z.object({
-  jsonrpc: z.string(),
-  id: z.number().optional(),
-  method: z.string().optional(),
-  params: z.unknown().optional(),
-  result: z.unknown().optional(),
+export const requestZ = z.object({
+  jsonrpc: z.literal("2.0"),
+  method: z.string(),
+  // params should be z.union([z.record(z.string(), z.json()),
+  // z.array(z.json())]).optional() but the VSCode JSON RPC implementation uses a looser
+  // definition of params then in the JSON-RPC spec.
+  params: z.any().optional(),
+  id: z.union([z.string(), z.number(), z.null()]).optional(),
 });
 
+export type Request = z.infer<typeof requestZ>;
+
+const baseResponseZ = z.object({
+  jsonrpc: z.literal("2.0"),
+  id: z.union([z.string(), z.number(), z.null()]),
+});
+
+const successResponseZ = baseResponseZ.extend({
+  result: z.json(),
+});
+
+const errorResponseZ = baseResponseZ.extend({
+  error: z.object({
+    code: z.number().int(),
+    // This should be z.string(), but the VSCode JSON RPC implementation uses a looser
+    // definition of error than the JSON-RPC spec.
+    message: z.string().optional(),
+    data: z.json().optional(),
+  }),
+});
+
+export const responseZ = z.union([successResponseZ, errorResponseZ]);
+
+export type Response = z.infer<typeof responseZ>;
+
+export const messageZ = z.union([requestZ, responseZ]);
+
 export type Message = z.infer<typeof messageZ>;
 
 export interface ChunkParser {

package/src/map/index.ts

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

package/src/map/map.spec.ts

@@ -0,0 +1,132 @@
+// Copyright 2025 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 { map } from "@/map";
+
+describe("map", () => {
+  describe("getOrSetDefault", () => {
+    it("should return existing value when key exists", () => {
+      const testMap = new Map<string, number>();
+      testMap.set("existing", 42);
+
+      const result = map.getOrSetDefault(testMap, "existing", 100);
+
+      expect(result).toEqual(42);
+      expect(testMap.get("existing")).toEqual(42);
+      expect(testMap.size).toEqual(1);
+    });
+
+    it("should set and return default value when key doesn't exist", () => {
+      const testMap = new Map<string, number>();
+
+      const result = map.getOrSetDefault(testMap, "new", 100);
+
+      expect(result).toEqual(100);
+      expect(testMap.get("new")).toEqual(100);
+      expect(testMap.size).toEqual(1);
+    });
+
+    it("should replace the value when key exists with undefined value", () => {
+      const testMap = new Map<string, number | undefined>();
+      testMap.set("undefined", undefined);
+
+      const result = map.getOrSetDefault(testMap, "undefined", 100);
+
+      expect(result).toEqual(100);
+      expect(testMap.get("undefined")).toEqual(100);
+      expect(testMap.size).toEqual(1);
+    });
+
+    it("should return null when key exists with null value", () => {
+      const testMap = new Map<string, number | null>();
+      testMap.set("null", null);
+
+      const result = map.getOrSetDefault(testMap, "null", 100);
+
+      expect(result).toBeNull();
+      expect(testMap.get("null")).toBeNull();
+      expect(testMap.size).toEqual(1);
+    });
+
+    it("should work with different key types", () => {
+      const numberMap = new Map<number, string>();
+      const result1 = map.getOrSetDefault(numberMap, 1, "default");
+      expect(result1).toEqual("default");
+      expect(numberMap.get(1)).toEqual("default");
+      const objKey = { id: 1 };
+      const objectMap = new Map<object, string>();
+      const result2 = map.getOrSetDefault(objectMap, objKey, "object-default");
+      expect(result2).toEqual("object-default");
+      expect(objectMap.get(objKey)).toEqual("object-default");
+    });
+
+    it("should work with different value types", () => {
+      const stringMap = new Map<string, string>();
+      const result1 = map.getOrSetDefault(stringMap, "key", "default");
+      expect(result1).toEqual("default");
+      const boolMap = new Map<string, boolean>();
+      const result2 = map.getOrSetDefault(boolMap, "key", true);
+      expect(result2).toEqual(true);
+      const objValue = { name: "test" };
+      const objMap = new Map<string, object>();
+      const result3 = map.getOrSetDefault(objMap, "key", objValue);
+      expect(result3).toEqual(objValue);
+      expect(result3).toBe(objValue);
+    });
+
+    it("should handle empty maps", () => {
+      const emptyMap = new Map<string, number>();
+
+      const result = map.getOrSetDefault(emptyMap, "first", 42);
+
+      expect(result).toEqual(42);
+      expect(emptyMap.get("first")).toEqual(42);
+      expect(emptyMap.size).toEqual(1);
+    });
+
+    it("should handle multiple operations on same map", () => {
+      const testMap = new Map<string, number>();
+      const result1 = map.getOrSetDefault(testMap, "key1", 10);
+      expect(result1).toEqual(10);
+      expect(testMap.size).toEqual(1);
+      const result2 = map.getOrSetDefault(testMap, "key1", 20);
+      expect(result2).toEqual(10); // Original value, not new default
+      expect(testMap.size).toEqual(1);
+      const result3 = map.getOrSetDefault(testMap, "key2", 30);
+      expect(result3).toEqual(30);
+      expect(testMap.size).toEqual(2);
+    });
+
+    it("should handle falsy values correctly", () => {
+      const testMap = new Map<string, number | string | boolean>();
+      testMap.set("zero", 0);
+      const result1 = map.getOrSetDefault(testMap, "zero", 100);
+      expect(result1).toEqual(0);
+      testMap.set("empty", "");
+      const result2 = map.getOrSetDefault(testMap, "empty", "default");
+      expect(result2).toEqual("");
+      testMap.set("false", false);
+      const result3 = map.getOrSetDefault(testMap, "false", true);
+      expect(result3).toEqual(false);
+    });
+
+    it("should handle arrays and complex objects", () => {
+      const testMap = new Map<string, number[]>();
+      const defaultArray = [1, 2, 3];
+
+      const result = map.getOrSetDefault(testMap, "array", defaultArray);
+
+      expect(result).toEqual([1, 2, 3]);
+      expect(result).toBe(defaultArray); // Same reference
+      expect(testMap.get("array")).toBe(defaultArray);
+    });
+  });
+});

package/src/map/map.ts

@@ -0,0 +1,17 @@
+// Copyright 2025 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 getOrSetDefault = <K, V>(map: Map<K, V>, key: K, defaultValue: V): V => {
+  const value = map.get(key);
+  if (value === undefined) {
+    map.set(key, defaultValue);
+    return defaultValue;
+  }
+  return value;
+};

package/src/math/math.ts

@@ -7,27 +7,20 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-/** A primitive numeric value is either a number or a bigint. */
-export type PrimitiveNumeric = number | bigint;
-
-/** An extension of {@link PrimitiveNumeric} that includes the {@link BigInt} and {@link Number} classes. */
-export type Numeric = PrimitiveNumeric | Number | BigInt;
-
-const isBigInt = (n: Numeric): n is bigint | BigInt =>
-  typeof n === "bigint" || n instanceof BigInt;
+/** A numeric value is either a a number, or a bigint. */
+export type Numeric = number | bigint;
 
 /**
  * @returns the product of a and b, coercing b to the type of a if necessary. */
 export const sub = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (isBigInt(a)) return (a.valueOf() - BigInt(b.valueOf().valueOf())) as V;
-  return (a.valueOf() - Number(b.valueOf())) as 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 Numeric>(a: V, b: Numeric): V => {
-  if (isBigInt(a)) return (a.valueOf() + BigInt(b.valueOf().valueOf())) as V;
-  // @ts-expect-error - a is a number but typescript doesn't recognize that.
-  return (a + Number(b.valueOf())) as V;
+  if (typeof a === "bigint") return (a + BigInt(b)) as V;
+  return ((a as unknown as number) + Number(b)) as V;
 };
 
 /** @returns true if a is close to b within epsilon. */
@@ -36,8 +29,8 @@ export const closeTo = (a: number, b: number, epsilon = 0.0001): boolean =>
 
 /** @returns true if a is equal to b, coercing b to the type of a if necessary. */
 export const equal = <V extends Numeric>(a: V, b: Numeric): boolean => {
-  if (isBigInt(a)) return a === BigInt(b.valueOf().valueOf());
-  return a === Number(b.valueOf());
+  if (typeof a === "bigint") return a === BigInt(b);
+  return a === Number(b);
 };
 
 /**
@@ -53,32 +46,31 @@ export const roundToNearestMagnitude = (num: number): number => {
 
 /** @returns the minimum of a and b, coercing b to the type of a if necessary. */
 export const min = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (isBigInt(a))
-    return (a.valueOf() < BigInt(b.valueOf()) ? a : BigInt(b.valueOf())) as V;
-  return (a.valueOf() < Number(b.valueOf()) ? a : Number(b.valueOf())) as V;
+  if (a <= b) return a;
+  if (typeof a === "bigint") return (a <= b ? a : BigInt(b)) as V;
+  return (a <= b ? a : Number(b)) as V;
 };
 
 /** @returns the maximum of a and b, coercing b to the type of a if necessary. */
 export const max = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (isBigInt(a))
-    return (a.valueOf() > BigInt(b.valueOf()) ? a : BigInt(b.valueOf())) as V;
-  return (a.valueOf() > Number(b.valueOf()) ? a : Number(b.valueOf())) as V;
+  if (typeof a === "bigint") return (a >= b ? a : BigInt(b)) as V;
+  return (a >= b ? a : Number(b)) as V;
 };
 
 /** @returns the absolute value of a. */
 export const abs = <V extends Numeric>(a: V): V => {
-  if (isBigInt(a) || a instanceof BigInt) return (a.valueOf() < 0n ? -a : a) as V;
-  return (a.valueOf() < 0 ? -a : a) as V;
+  if (a < 0) return -a as V;
+  return a;
 };
 
 /** @returns the multiplication of a and b, coercing b to the type of a if necessary. */
 export const mult = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (isBigInt(a)) return (a.valueOf() * BigInt(b.valueOf())) as V;
-  return (a.valueOf() * Number(b.valueOf())) as V;
+  if (typeof a === "bigint") return (a * BigInt(b)) as V;
+  return (a * Number(b)) as V;
 };
 
 /** @returns the division of a and b, coercing b to the type of a if necessary. */
 export const div = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (isBigInt(a)) return (a.valueOf() / BigInt(b.valueOf())) as V;
-  return (a.valueOf() / Number(b.valueOf())) as V;
+  if (typeof a === "bigint") return (a / BigInt(b)) as V;
+  return (a / Number(b)) as V;
 };

package/src/migrate/migrate.spec.ts

@@ -59,7 +59,7 @@ const migrations: migrate.Migrations = {
 describe("compareSemVer", () => {
   it("should return true when the major version is higher", () => {
     expect(migrate.compareSemVer("1.0.0", "0.0.0")).toBeGreaterThan(0);
-    expect(migrate.semVerNewer("3.0.0", "0.3.0")).toBeTruthy();
+    expect(migrate.semVerNewer("3.0.0", "0.3.0")).toBe(true);
   });
   describe("only check major", () => {
     it("should return equal when the major versions are equal but the minor and patch are different", () => {

package/src/migrate/migrate.ts

@@ -70,7 +70,7 @@ export const compareSemVer = ((
     if (aPatch > bPatch) return compare.GREATER_THAN;
   }
   return compare.EQUAL;
-}) satisfies compare.CompareF<SemVer>;
+}) satisfies compare.Comparator<SemVer>;
 
 /**
  * @returns true if the two semantic versions are equal.
@@ -118,8 +118,8 @@ export type Migration<I extends Migratable, O extends Migratable> = (input: I) =
 export interface MigrationProps<
   I extends Migratable,
   O extends Migratable,
-  ZI extends z.ZodTypeAny,
-  ZO extends z.ZodTypeAny,
+  ZI extends z.ZodType,
+  ZO extends z.ZodType,
 > {
   name: string;
   inputSchema?: ZI;
@@ -131,8 +131,8 @@ export const createMigration =
   <
     I extends Migratable,
     O extends Migratable,
-    ZI extends z.ZodTypeAny = z.ZodTypeAny,
-    ZO extends z.ZodTypeAny = z.ZodTypeAny,
+    ZI extends z.ZodType = z.ZodType,
+    ZO extends z.ZodType = z.ZodType,
   >({
     name,
     migrate,
@@ -155,7 +155,7 @@ export const createMigration =
  */
 export type Migrations = Record<string, Migration<any, any>>;
 
-interface MigratorProps<O extends Migratable, ZO extends z.ZodTypeAny = z.ZodTypeAny> {
+interface MigratorProps<O extends Migratable, ZO extends z.ZodType = z.ZodType> {
   name: string;
   migrations: Migrations;
   def: O;
@@ -168,7 +168,7 @@ export type Migrator = <I extends Optional<Migratable, "version">, O>(v: I) => O
 export const migrator = <
   I extends Optional<Migratable, "version">,
   O extends Migratable,
-  ZO extends z.ZodTypeAny = z.ZodTypeAny,
+  ZO extends z.ZodType = z.ZodType,
 >({
   name,
   migrations,

package/src/optional.ts

@@ -8,7 +8,3 @@
 // included in the file licenses/APL.txt.
 
 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];
-};

package/src/primitive/index.ts

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