@synnaxlabs/x 0.42.1 → 0.43.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 { createMatcher, type Discriminated } from "./matcher";
+
+describe("createMatcher", () => {
+  class TestClass implements Discriminated {
+    discriminator = "test";
+    constructor(public value: string) {}
+  }
+
+  const isTestClass = 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 Discriminated {
+      discriminator = "a";
+      constructor(public value: string) {}
+    }
+
+    class ClassB implements Discriminated {
+      discriminator = "b";
+      constructor(public value: string) {}
+    }
+
+    const isClassA = createMatcher("a", ClassA);
+    const isClassB = 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

@@ -7,18 +7,47 @@
 // 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 z from "zod/v4";
 
 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/kv/types.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 } from "zod";
+import { z } from "zod/v4";
 
 export interface Reader<V = unknown> {
   /** @returns the value for a given key, or null if the key is not present. */

package/src/migrate/migrate.spec.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { describe, expect, it } from "vitest";
-import { z } from "zod";
+import { z } from "zod/v4";
 
 import { migrate } from "@/migrate";
 

package/src/migrate/migrate.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 } from "zod";
+import { z } from "zod/v4";
 
 import { compare } from "@/compare";
 import { type Optional } from "@/optional";
@@ -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/notation/notation.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 } from "zod";
+import { z } from "zod/v4";
 
 export const NOTATIONS = ["standard", "scientific", "engineering"] as const;
 export const notationZ = z.enum(NOTATIONS);

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";

package/src/primitive/primitive.spec.ts

@@ -0,0 +1,126 @@
+// 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 { z } from "zod/v4";
+
+import { binary } from "@/binary";
+import { primitive } from "@/primitive";
+
+class ExampleStringer implements primitive.Stringer {
+  readonly value: string;
+  constructor(value: string) {
+    this.value = value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}
+
+describe("primitive", () => {
+  describe("isZero", () => {
+    interface Spec {
+      value: primitive.Value;
+      expected: boolean;
+    }
+    const SPECS: Spec[] = [
+      { value: 0, expected: true },
+      { value: 1, expected: false },
+      { value: 0n, expected: true },
+      { value: 12n, expected: false },
+      { value: true, expected: false },
+      { value: false, expected: true },
+      { value: undefined, expected: true },
+      { value: new ExampleStringer(""), expected: true },
+      { value: new ExampleStringer("cat"), expected: false },
+    ];
+    SPECS.forEach(({ value, expected }) => {
+      // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+      it(`should return ${expected} for ${value} ${typeof value}`, () => {
+        expect(primitive.isZero(value)).toEqual(expected);
+      });
+    });
+  });
+
+  describe("isStringer", () => {
+    it("should return true for a stringer", () => {
+      expect(primitive.isStringer(new ExampleStringer("cat"))).toEqual(true);
+    });
+    it("should return false for a non-stringer", () => {
+      expect(primitive.isStringer(0)).toEqual(false);
+    });
+    it("should return false for null", () => {
+      expect(primitive.isStringer(null)).toEqual(false);
+    });
+  });
+
+  describe("ValueExtension", () => {
+    class MyValueExtension extends primitive.ValueExtension<bigint> {
+      valueOf(): bigint {
+        return this.value;
+      }
+      toJSON(): bigint {
+        return this.value;
+      }
+    }
+
+    describe("valueOf", () => {
+      it("should return the value", () => {
+        const value = new MyValueExtension(12n);
+        expect(value.valueOf()).toEqual(12n);
+      });
+    });
+
+    describe("toJSON", () => {
+      it("should return the value", () => {
+        const value = new MyValueExtension(12n);
+        expect(value.toJSON()).toEqual(12n);
+      });
+    });
+
+    describe("toString", () => {
+      it("should return the value", () => {
+        const value = new MyValueExtension(12n);
+        expect(value.toString()).toEqual("12");
+      });
+    });
+
+    describe("encode + decode", () => {
+      it("should encode + decode a value extension", () => {
+        const v = {
+          myDog: new MyValueExtension(12n),
+        };
+        const encoded = binary.JSON_CODEC.encode(v);
+        const decoded = binary.JSON_CODEC.decode(encoded);
+        expect(decoded).toEqual({
+          myDog: "12",
+        });
+      });
+
+      it("should encode + decode a value extension with a schema", () => {
+        const v = {
+          myDog: new MyValueExtension(12n),
+        };
+        const schema = z.object({
+          myDog: z
+            .bigint()
+            .or(z.string())
+            .transform((v) => new MyValueExtension(BigInt(v))),
+        });
+        const encoded = binary.JSON_CODEC.encode(v);
+        const decoded = binary.JSON_CODEC.decode(encoded, schema);
+        expect(decoded).toEqual({
+          myDog: new MyValueExtension(12n),
+        });
+        expect(decoded.myDog).toBeInstanceOf(MyValueExtension);
+      });
+    });
+  });
+});

package/src/primitive/primitive.ts

@@ -0,0 +1,82 @@
+// 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.
+
+/** Union of types that are primitive values or can be converted to primitive values */
+export type Value = string | number | bigint | boolean | Stringer | null | undefined;
+
+/**
+ * ValueExtension is a utility class that can be extended in order to implement objects
+ * that pseudo-extend a primitive value with additional functionality.
+ */
+export class ValueExtension<V extends NonNullable<Value>> {
+  /** The underlying primitive value */
+  protected readonly value: V;
+
+  constructor(value: V) {
+    this.value = value;
+  }
+
+  /** Overrides the JS default valueOf() function to return the primitive value. */
+  valueOf(): V {
+    return this.value;
+  }
+
+  /** toJSON ensures that only the primitive value gets encoded during JSON
+   * stringification. */
+  toJSON(): V {
+    return this.value;
+  }
+
+  /** @returns a string representation of the item. */
+  toString(): string {
+    return this.value.toString();
+  }
+}
+
+/**
+ * Stringer is a type that implements a toString() method in order to return a string
+ * representation of itself.
+ */
+export interface Stringer {
+  /** @returns a string representation of the item. */
+  toString: () => string;
+}
+
+/** @returns true if the value implements primitive.Stringer, otherwise returns false. */
+export const isStringer = (value: unknown): boolean =>
+  value != null && typeof value === "object" && "toString" in value;
+
+/**
+ * @returns true if the given primitive is the zero value for its type.
+ * For strings value == ""
+ * For numbers value == 0
+ * For bigints value == 0n
+ * For booleans value == false
+ * For objects value == null
+ * For undefined returns true
+ */
+export const isZero = <V extends Value>(value: V): 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 === 0n;
+    case "boolean":
+      return !value;
+    case "undefined":
+      return true;
+    case "object":
+      return value == null;
+    default:
+      return false;
+  }
+};

package/src/record.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 } from "zod";
+import { z } from "zod/v4";
 
 export type Key = string | number;
 
@@ -40,8 +40,6 @@ export const getEntries = <T extends Record<Key, unknown>>(obj: T): Entries<T> =
 
 export const mapValues = <T extends Record<Key, unknown>, U>(
   obj: T,
-  fn: (value: T[keyof T], key: Key) => U,
+  fn: (value: T[keyof T], key: keyof T) => U,
 ): Record<Key, U> =>
-  Object.fromEntries(
-    getEntries(obj).map(([key, value]) => [key, fn(value, key as Key)]),
-  );
+  Object.fromEntries(getEntries(obj).map(([key, value]) => [key, fn(value, key)]));

package/src/renderable.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 { type Stringer } from "@/primitive";
+import { type Stringer } from "@/primitive/primitive";
 
 export type PureRenderableValue = string | number | undefined;
 export type RenderableValue = PureRenderableValue | Stringer;

package/src/replace.ts

@@ -1 +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 type Replace<T, R> = Omit<T, keyof R> & R;

package/src/runtime/detect.ts

@@ -17,14 +17,12 @@ export type Runtime = "browser" | "node" | "webworker";
  */
 export const detect = (): Runtime => {
   if (
-
     typeof process !== "undefined" &&
     process.versions != null &&
     process.versions.node != null
   )
     return "node";
 
-
   if (typeof window === "undefined" || window.document === undefined)
     return "webworker";
 

package/src/runtime/os.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 } from "zod";
+import { z } from "zod/v4";
 
 export const OPERATING_SYSTEMS = ["macOS", "Windows", "Linux"] as const;
 const LOWERCASE_OPERATING_SYSTEMS = ["macos", "windows", "linux"] as const;

package/src/spatial/base.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 } from "zod";
+import { z } from "zod/v4";
 
 export const numberCouple = z.tuple([z.number(), z.number()]);
 export const bigNumberCouple = z.tuple([z.bigint(), z.bigint()]);

package/src/spatial/bounds/bounds.spec.ts

@@ -28,16 +28,36 @@ describe("Bounds", () => {
         expect(bound.upper).toEqual(2);
       });
     });
+
     it("should accept two arguments", () => {
       const bound = bounds.construct(1, 2);
       expect(bound.lower).toEqual(1);
       expect(bound.upper).toEqual(2);
     });
+
     it("should consider a single argument as the upper bound", () => {
       const bound = bounds.construct(1);
       expect(bound.lower).toEqual(0);
       expect(bound.upper).toEqual(1);
     });
+
+    describe("makeValid", () => {
+      it("should make the bounds valid", () => {
+        const bound = bounds.construct<number>(2, 1, { makeValid: true });
+        expect(bound.lower).toEqual(1);
+        expect(bound.upper).toEqual(2);
+      });
+      it("should allow for options in a single argument constructor", () => {
+        const bound = bounds.construct<number>([2, 1], { makeValid: false });
+        expect(bound.lower).toEqual(2);
+        expect(bound.upper).toEqual(1);
+      });
+      it("should not make the bounds valid if makeValid is false", () => {
+        const bound = bounds.construct(1, 2, { makeValid: false });
+        expect(bound.lower).toEqual(1);
+        expect(bound.upper).toEqual(2);
+      });
+    });
   });
   describe("equals", () => {
     it("should return true if the bounds are equal", () => {