@synnaxlabs/x 0.49.3 → 0.52.3

package/src/shallow/copy.ts

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

package/src/shallow/index.ts

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

package/src/singleton/define.spec.ts

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

package/src/singleton/define.ts

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

package/src/singleton/index.ts

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

package/src/sleep/index.ts

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

package/src/sleep/sleep.ts

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

package/src/spatial/base.ts

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

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

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

package/src/spatial/bounds/bounds.ts

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

package/src/spatial/bounds/index.ts

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

package/src/spatial/box/box.spec.ts

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

package/src/spatial/box/box.ts

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

package/src/spatial/box/index.ts

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

package/src/spatial/dimensions/dimensions.spec.ts

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

package/src/spatial/dimensions/dimensions.ts

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

package/src/spatial/dimensions/index.ts

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

package/src/spatial/direction/direction.spec.ts

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

package/src/spatial/direction/direction.ts

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

package/src/spatial/direction/index.ts

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

package/src/spatial/external.ts

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

package/src/spatial/index.ts

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

package/src/spatial/location/index.ts

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

package/src/spatial/location/location.spec.ts

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

package/src/spatial/location/location.ts

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

package/src/spatial/scale/index.ts

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

package/src/spatial/scale/scale.spec.ts

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

package/src/spatial/scale/scale.ts

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

package/src/spatial/spatial.ts

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

package/src/spatial/sticky/index.ts

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

package/src/spatial/sticky/sticky.spec.ts

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

package/src/spatial/sticky/sticky.ts

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

package/src/spatial/xy/index.ts

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

package/src/spatial/xy/xy.spec.ts

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

package/src/spatial/xy/xy.ts

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

package/src/status/index.ts

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

package/src/status/status.spec.ts

@@ -1,4 +1,4 @@
-// Copyright 2025 Synnax Labs, Inc.
+// Copyright 2026 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -8,6 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { describe, expect, it } from "vitest";
+import { z } from "zod";
 
 import { id } from "@/id";
 import { status } from "@/status";
@@ -129,4 +130,170 @@ describe("status", () => {
       expect(result.success).toBe(true);
     });
   });
+
+  describe("toString", () => {
+    it("should format a basic status with variant and message", () => {
+      const s = status.create({ variant: "success", message: "Operation completed" });
+      const result = status.toString(s);
+      expect(result).toBe("SUCCESS: Operation completed");
+    });
+
+    it("should include name when present and includeName is true", () => {
+      const s = status.create({
+        variant: "info",
+        message: "System started",
+        name: "SystemStatus",
+      });
+      const result = status.toString(s);
+      expect(result).toBe("INFO [SystemStatus]: System started");
+    });
+
+    it("should exclude name when includeName is false", () => {
+      const s = status.create({
+        variant: "warning",
+        message: "Low memory",
+        name: "MemoryMonitor",
+      });
+      const result = status.toString(s, { includeName: false });
+      expect(result).toBe("WARNING: Low memory");
+    });
+
+    it("should include timestamp when includeTimestamp is true", () => {
+      const s = status.create({ variant: "error", message: "Failed" });
+      const result = status.toString(s, { includeTimestamp: true });
+      expect(result).toMatch(/^ERROR: Failed \(.+\)$/);
+    });
+
+    it("should format plain text description", () => {
+      const s = status.create({
+        variant: "error",
+        message: "Connection failed",
+        description: "Unable to reach server at localhost:9090",
+      });
+      const result = status.toString(s);
+      expect(result).toBe(
+        "ERROR: Connection failed\n\nDescription: Unable to reach server at localhost:9090",
+      );
+    });
+
+    it("should pretty-print JSON description", () => {
+      const s = status.create({
+        variant: "error",
+        message: "Validation failed",
+        description: JSON.stringify({ field: "email", reason: "invalid format" }),
+      });
+      const result = status.toString(s);
+      expect(result).toContain("ERROR: Validation failed");
+      expect(result).toContain("Description:");
+      expect(result).toContain('"field": "email"');
+      expect(result).toContain('"reason": "invalid format"');
+    });
+
+    it("should include stack trace from exception details", () => {
+      const error = new Error("Something went wrong");
+      const s = status.fromException(error);
+      const result = status.toString(s);
+      expect(result).toContain("ERROR: Something went wrong");
+      expect(result).toContain("Stack Trace:");
+      expect(result).toContain("Error: Something went wrong");
+    });
+
+    it("should handle all variants", () => {
+      const variants: status.Variant[] = [
+        "success",
+        "info",
+        "warning",
+        "error",
+        "loading",
+        "disabled",
+      ];
+      for (const variant of variants) {
+        const s = status.create({ variant, message: "Test message" });
+        const result = status.toString(s);
+        expect(result).toBe(`${variant.toUpperCase()}: Test message`);
+      }
+    });
+
+    it("should handle status with all optional fields", () => {
+      const error = new Error("Full error");
+      const s = status.fromException(error, "Custom message");
+      s.name = "ErrorHandler";
+      const result = status.toString(s, { includeTimestamp: true });
+      expect(result).toContain("ERROR [ErrorHandler]: Custom message");
+      expect(result).toContain("Description: Full error");
+      expect(result).toContain("Stack Trace:");
+    });
+
+    it("should not include name brackets when name is empty string", () => {
+      const s = status.create({ variant: "success", message: "Done" });
+      const result = status.toString(s);
+      expect(result).toBe("SUCCESS: Done");
+      expect(result).not.toContain("[]");
+    });
+
+    it("should include extra details beyond stack trace", () => {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const detailsSchema = z.object({
+        statusCode: z.number(),
+        endpoint: z.string(),
+        requestId: z.string(),
+      });
+      const s = status.create<typeof detailsSchema>({
+        variant: "error",
+        message: "Request failed",
+        details: {
+          statusCode: 404,
+          endpoint: "/api/users",
+          requestId: "abc-123",
+        },
+      });
+      const result = status.toString(s);
+      expect(result).toContain("ERROR: Request failed");
+      expect(result).toContain("Details:");
+      expect(result).toContain('"statusCode": 404');
+      expect(result).toContain('"endpoint": "/api/users"');
+      expect(result).toContain('"requestId": "abc-123"');
+    });
+
+    it("should include both stack trace and extra details separately", () => {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const detailsSchema = z.object({
+        stack: z.string(),
+        query: z.string(),
+        duration: z.number(),
+      });
+      const s = status.create<typeof detailsSchema>({
+        variant: "error",
+        message: "Database error",
+        details: {
+          stack: "Error: Database error\n    at query (db.ts:10)",
+          query: "SELECT * FROM users",
+          duration: 1500,
+        },
+      });
+      const result = status.toString(s);
+      expect(result).toContain("ERROR: Database error");
+      expect(result).toContain("Stack Trace:\nError: Database error");
+      expect(result).toContain("Details:");
+      expect(result).toContain('"query": "SELECT * FROM users"');
+      expect(result).toContain('"duration": 1500');
+      expect(result).not.toContain('"stack"');
+    });
+
+    it("should exclude error object from details output", () => {
+      const error = new Error("Test error");
+      const s = status.fromException(error);
+      const result = status.toString(s);
+      expect(result).toContain("Stack Trace:");
+      expect(result).not.toContain('"error"');
+    });
+
+    it("should not include Details section when only stack and error are present", () => {
+      const error = new Error("Test error");
+      const s = status.fromException(error);
+      const result = status.toString(s);
+      expect(result).toContain("Stack Trace:");
+      expect(result).not.toContain("Details:");
+    });
+  });
 });

package/src/status/status.ts

@@ -1,4 +1,4 @@
-// Copyright 2025 Synnax Labs, Inc.
+// Copyright 2026 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -12,6 +12,7 @@ import { z } from "zod";
 import { array } from "@/array";
 import { id } from "@/id";
 import { label } from "@/label";
+import { narrow } from "@/narrow";
 import { type optional } from "@/optional";
 import { TimeStamp } from "@/telem";
 
@@ -132,3 +133,48 @@ export const removeVariants = (
   }
   return remove === variant ? undefined : variant;
 };
+
+export interface ToStringOptions {
+  includeTimestamp?: boolean;
+  includeName?: boolean;
+}
+
+const DEFAULT_TO_STRING_OPTIONS: ToStringOptions = {
+  includeTimestamp: false,
+  includeName: true,
+};
+
+export const toString = <Details = never>(
+  stat: Status<Details>,
+  options: ToStringOptions = {},
+): string => {
+  const opts = { ...DEFAULT_TO_STRING_OPTIONS, ...options };
+  const parts: string[] = [];
+  let header = stat.variant.toUpperCase();
+  if (opts.includeName && stat.name.length > 0) header += ` [${stat.name}]`;
+  header += `: ${stat.message}`;
+  if (opts.includeTimestamp) header += ` (${stat.time.toString("dateTime", "local")})`;
+  parts.push(header);
+  if (stat.description != null) {
+    let descriptionText: string;
+    try {
+      const parsed = JSON.parse(stat.description);
+      descriptionText = `Description:\n${JSON.stringify(parsed, null, 2)}`;
+    } catch {
+      descriptionText = `Description: ${stat.description}`;
+    }
+    parts.push(descriptionText);
+  }
+  if ("details" in stat && narrow.isObject(stat.details)) {
+    const details = stat.details as Record<string, unknown>;
+    // Extract stack trace separately for special formatting
+    if ("stack" in details) parts.push(`Stack Trace:\n${String(details.stack)}`);
+    // Include other details (excluding stack and error which don't serialize well)
+    const extraDetails = Object.fromEntries(
+      Object.entries(details).filter(([k]) => k !== "stack" && k !== "error"),
+    );
+    if (Object.keys(extraDetails).length > 0)
+      parts.push(`Details:\n${JSON.stringify(extraDetails, null, 2)}`);
+  }
+  return parts.join("\n\n");
+};

package/src/strings/deduplicateFileName.spec.ts

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

package/src/strings/deduplicateFileName.ts

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

package/src/strings/external.ts

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

package/src/strings/index.ts

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

package/src/strings/strings.spec.ts

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

package/src/strings/strings.ts

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

package/src/sync/index.ts

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

package/src/sync/mutex.ts

@@ -1,4 +1,4 @@
-// Copyright 2025 Synnax Labs, Inc.
+// Copyright 2026 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -7,11 +7,11 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { Mutex as Core } from "async-mutex";
+import { Mutex as Base } from "async-mutex";
 
-export type Mutex<G> = G & Core;
+export type Mutex<G> = G & Base;
 
-export class mutex<G> extends Core {
+export class mutex<G> extends Base {
   constructor(guard: G) {
     super();
     Object.assign(this, guard);

package/src/telem/gl.ts

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

package/src/telem/index.ts

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

package/src/telem/series.spec.ts

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

package/src/telem/series.ts

@@ -1,4 +1,4 @@
-// Copyright 2025 Synnax Labs, Inc.
+// Copyright 2026 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -1553,9 +1553,9 @@ class MultiSeriesIterator<T extends TelemValue = TelemValue> implements Iterator
   }
 }
 
-class MultiSubIterator<T extends TelemValue = TelemValue>
-  implements IterableIterator<T>
-{
+class MultiSubIterator<
+  T extends TelemValue = TelemValue,
+> implements IterableIterator<T> {
   private readonly series: MultiSeries<T>;
   private index: number;
   private end: number;

package/src/telem/telem.spec.ts

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

package/src/telem/telem.ts

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

package/src/testutil/index.ts

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