@synnaxlabs/x 0.42.1 → 0.43.0

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

package/src/uuid/uuid.spec.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.
+
+import { describe, expect, it } from "vitest";
+
+import { uuid } from "@/uuid";
+
+describe("UUID", () => {
+  describe("create", () => {
+    it("should generate a valid UUID v4", () => {
+      const uid = uuid.create();
+      expect(uid).toMatch(
+        /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+      );
+    });
+
+    it("should generate unique UUIDs", () => {
+      const uuids = new Set();
+      for (let i = 0; i < 1000; i++) {
+        const uid = uuid.create();
+        expect(uuids.has(uid)).toBe(false);
+        uuids.add(uid);
+      }
+    });
+  });
+
+  describe("parse", () => {
+    it("should parse a valid UUID from bytes", () => {
+      // Example UUID: 123e4567-e89b-12d3-a456-426614174000
+      const bytes = new Uint8Array([
+        0x12, 0x3e, 0x45, 0x67, 0xe8, 0x9b, 0x12, 0xd3, 0xa4, 0x56, 0x42, 0x66, 0x14,
+        0x17, 0x40, 0x00,
+      ]);
+      const uid = uuid.parse(bytes);
+      expect(uid).toBe("123e4567-e89b-12d3-a456-426614174000");
+    });
+
+    it("should handle zero bytes", () => {
+      const bytes = new Uint8Array(16);
+      const uid = uuid.parse(bytes);
+      expect(uid).toBe("00000000-0000-0000-0000-000000000000");
+    });
+
+    it("should handle all ones", () => {
+      const bytes = new Uint8Array(16).fill(0xff);
+      const uid = uuid.parse(bytes);
+      expect(uid).toBe("ffffffff-ffff-ffff-ffff-ffffffffffff");
+    });
+
+    it("should handle random bytes", () => {
+      const bytes = new Uint8Array([
+        0x7f, 0x3e, 0x45, 0x67, 0xe8, 0x9b, 0x12, 0xd3, 0xa4, 0x56, 0x42, 0x66, 0x14,
+        0x17, 0x40, 0x00,
+      ]);
+      const uid = uuid.parse(bytes);
+      expect(uid).toMatch(
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+      );
+    });
+
+    it("should throw error for invalid byte length", () => {
+      const bytes = new Uint8Array(15); // Invalid length
+      expect(() => uuid.parse(bytes)).toThrow();
+    });
+
+    it("should maintain byte order", () => {
+      // Test with a specific pattern to verify byte order
+      const bytes = new Uint8Array([
+        0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd,
+        0xee, 0xff, 0x00,
+      ]);
+      const uid = uuid.parse(bytes);
+      expect(uid).toBe("11223344-5566-7788-99aa-bbccddeeff00");
+    });
+  });
+});

package/src/uuid/uuid.ts

@@ -0,0 +1,48 @@
+// 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 { NIL, stringify, v4 as uuid } from "uuid";
+
+/**
+ * Creates a new random UUID (Universally Unique Identifier) version 4.
+ * This function uses the cryptographically secure random number generator
+ * to generate a UUID that is suitable for use as a unique identifier.
+ *
+ * @returns {string} A new UUID v4 string in the format 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'
+ * where x is any hexadecimal digit and y is one of 8, 9, A, or B.
+ *
+ * @example
+ * const id = create(); // Returns something like "123e4567-e89b-12d3-a456-426614174000"
+ */
+export const create = (): string => uuid();
+
+/**
+ * Parses a UUID from a byte array.
+ * This function converts a 16-byte array into a standard UUID string format.
+ * It can optionally start parsing from a specific offset in the byte array.
+ *
+ * @param {Uint8Array} bytes - The byte array containing the UUID. Must be at least 16 bytes long.
+ * @param {number} [offset=0] - Optional offset in the byte array to start parsing from.
+ *
+ * @returns {string} A UUID string in the format 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+ *
+ * @throws {Error} If the byte array is less than 16 bytes long (accounting for offset)
+ *
+ * @example
+ * const bytes = new Uint8Array([
+ *   0x12, 0x3e, 0x45, 0x67, 0xe8, 0x9b, 0x12, 0xd3,
+ *   0xa4, 0x56, 0x42, 0x66, 0x14, 0x17, 0x40, 0x00
+ * ]);
+ * const uuid = parse(bytes); // Returns "123e4567-e89b-12d3-a456-426614174000"
+ */
+export const parse = (bytes: Uint8Array, offset?: number): string =>
+  stringify(bytes, offset);
+
+/** The zero value for a UUID - 00000000-0000-0000-0000-000000000000 */
+export const ZERO = NIL;

package/src/zod/external.ts

@@ -7,5 +7,5 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export * from "@/zod/integer";
+export * from "@/zod/nullToUndefined";
 export * from "@/zod/util";

package/src/zod/nullToUndefined.spec.ts

@@ -0,0 +1,31 @@
+// 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 { zod } from "@/zod";
+
+describe("zod", () => {
+  describe("nullToUndefined", () => {
+    const schema = zod.nullToUndefined(z.string());
+    it("should parse the normal case", () => {
+      expect(schema.parse("string")).toBe("string");
+    });
+    it("should parse null as undefined", () => {
+      expect(schema.parse(null)).toBe(undefined);
+    });
+    it("should parse undefined as undefined", () => {
+      expect(schema.parse(undefined)).toBe(undefined);
+    });
+    it("should throw for other values", () => {
+      expect(() => schema.parse(1)).toThrow(z.ZodError);
+    });
+  });
+});

package/src/zod/nullToUndefined.ts

@@ -0,0 +1,23 @@
+// 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 { type z } from "zod/v4";
+
+export const nullToUndefined = <Input, Output>(
+  schema: z.ZodType<Input, Output>,
+): z.ZodOptional<
+  z.ZodPipe<
+    z.ZodNullable<z.ZodType<Input, Output>>,
+    z.ZodTransform<Awaited<Input & {}> | undefined, Input | null>
+  >
+> =>
+  schema
+    .nullable()
+    .transform((s) => (s === null ? undefined : s))
+    .optional();

package/src/zod/util.spec.ts

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

package/src/zod/util.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 z } from "zod";
+import { type z } from "zod/v4";
 
 import { deep } from "@/deep";
 import { type UnknownRecord } from "@/record";
@@ -34,13 +34,13 @@ const sourceTypeGetter = (obj: unknown, key: string): z.ZodAny | null => {
   return v;
 };
 
-export const getFieldSchema: deep.TypedGet<z.ZodTypeAny, z.ZodTypeAny> = ((
-  schema: z.ZodTypeAny,
+export const getFieldSchema: deep.TypedGet<z.ZodType, z.ZodType> = ((
+  schema: z.ZodType,
   path: string,
   options?: Omit<deep.GetOptions, "getter">,
-): z.ZodTypeAny | null =>
-  deep.get<z.ZodTypeAny, z.ZodTypeAny>(
+): z.ZodType | null =>
+  deep.get<z.ZodType, z.ZodType>(
     sourceTypeGetter(schema, "shape") as unknown as z.ZodObject<z.ZodRawShape>,
     getFieldSchemaPath(path),
     { ...options, getter: sourceTypeGetter } as deep.GetOptions<boolean | undefined>,
-  )) as deep.TypedGet<z.ZodTypeAny, z.ZodTypeAny>;
+  )) as deep.TypedGet<z.ZodType, z.ZodType>;

package/tsconfig.json

@@ -2,7 +2,7 @@
   "extends": "@synnaxlabs/tsconfig/base.json",
   "compilerOptions": {
     "baseUrl": ".",
-    "composite": true,
+    "composite": true
   },
   "include": ["src/**/*"]
 }