@synnaxlabs/client 0.55.0 → 0.56.0

package/src/actions/actions.spec.ts

@@ -0,0 +1,229 @@
+// Copyright 2026 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 Draft, produce } from "immer";
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import { actions } from "@/actions";
+
+interface DemoState {
+  name: string;
+  items: { key: string; value: number }[];
+}
+
+type DemoAction =
+  | { type: "rename"; payload: { name: string } }
+  | { type: "set_item"; payload: { key: string; value: number } }
+  | { type: "remove_item"; payload: { key: string } };
+
+const renameAction = (name: string): DemoAction => ({
+  type: "rename",
+  payload: { name },
+});
+const setItemAction = (key: string, value: number): DemoAction => ({
+  type: "set_item",
+  payload: { key, value },
+});
+const removeItemAction = (key: string): DemoAction => ({
+  type: "remove_item",
+  payload: { key },
+});
+
+const reduceOne = (
+  draft: Draft<DemoState>,
+  action: DemoAction,
+): actions.HandlerResult<DemoAction> => {
+  switch (action.type) {
+    case "rename": {
+      const prev = draft.name;
+      draft.name = action.payload.name;
+      return { inverse: [renameAction(prev)], targets: ["name"] };
+    }
+    case "set_item": {
+      const idx = draft.items.findIndex((i) => i.key === action.payload.key);
+      if (idx === -1) {
+        draft.items.push(action.payload);
+        return {
+          inverse: [removeItemAction(action.payload.key)],
+          targets: [action.payload.key],
+        };
+      }
+      const prevValue = draft.items[idx].value;
+      draft.items[idx].value = action.payload.value;
+      return {
+        inverse: [setItemAction(action.payload.key, prevValue)],
+        targets: [action.payload.key],
+      };
+    }
+    case "remove_item": {
+      const idx = draft.items.findIndex((i) => i.key === action.payload.key);
+      if (idx === -1) return actions.NO_OP_RESULT;
+      const removed = draft.items[idx];
+      draft.items.splice(idx, 1);
+      return {
+        inverse: [setItemAction(removed.key, removed.value)],
+        targets: [removed.key],
+      };
+    }
+  }
+};
+
+const reduceAll = actions.createReduceAll(reduceOne);
+
+describe("snapshotDraft", () => {
+  it("Should return plain values unchanged", () => {
+    const v = { a: 1, b: [2, 3] };
+    expect(actions.snapshotDraft(v)).toBe(v);
+  });
+
+  it("Should freeze a draft into a plain object that survives the produce closure", () => {
+    const original = { items: [{ key: "a", value: 1 }] };
+    let captured: typeof original | undefined;
+    const next = produce(original, (draft) => {
+      captured = actions.snapshotDraft(draft.items[0]) as unknown as typeof original;
+      draft.items[0].value = 99;
+    });
+    expect(next.items[0].value).toBe(99);
+    expect(captured).toEqual({ key: "a", value: 1 });
+  });
+
+  it("Should preserve primitive values without wrapping", () => {
+    expect(actions.snapshotDraft(42)).toBe(42);
+    expect(actions.snapshotDraft("hello")).toBe("hello");
+    expect(actions.snapshotDraft(null)).toBe(null);
+  });
+});
+
+describe("NO_OP_RESULT", () => {
+  it("Should expose empty inverse and targets", () => {
+    expect(actions.NO_OP_RESULT.inverse).toHaveLength(0);
+    expect(actions.NO_OP_RESULT.targets).toHaveLength(0);
+  });
+});
+
+describe("createReduceAll", () => {
+  const initial: DemoState = { name: "before", items: [{ key: "a", value: 1 }] };
+
+  it("Should apply a single action and return the new state", () => {
+    const { next } = reduceAll(initial, [renameAction("after")]);
+    expect(next.name).toBe("after");
+    expect(initial.name).toBe("before");
+  });
+
+  it("Should accumulate inverses in reverse application order", () => {
+    const { inverse } = reduceAll(initial, [
+      renameAction("step-1"),
+      setItemAction("a", 2),
+      setItemAction("b", 7),
+    ]);
+    expect(inverse).toEqual([
+      removeItemAction("b"),
+      setItemAction("a", 1),
+      renameAction("before"),
+    ]);
+  });
+
+  it("Should round-trip state through forward then inverse application", () => {
+    const forward = [
+      renameAction("after"),
+      setItemAction("a", 2),
+      setItemAction("b", 7),
+    ];
+    const { next, inverse } = reduceAll(initial, forward);
+    const { next: roundtripped } = reduceAll(next, inverse);
+    expect(roundtripped).toEqual(initial);
+  });
+
+  it("Should de-duplicate targets across actions", () => {
+    const { targets } = reduceAll(initial, [
+      setItemAction("a", 5),
+      setItemAction("a", 6),
+      setItemAction("b", 7),
+    ]);
+    expect(targets).toHaveLength(2);
+    expect(targets).toEqual(expect.arrayContaining(["a", "b"]));
+  });
+
+  it("Should drop NO_OP_RESULT entries from the inverse list", () => {
+    const { inverse } = reduceAll(initial, [removeItemAction("missing")]);
+    expect(inverse).toHaveLength(0);
+  });
+
+  it("Should leave the source state untouched after produce", () => {
+    const before = JSON.parse(JSON.stringify(initial));
+    reduceAll(initial, [
+      renameAction("x"),
+      setItemAction("a", 99),
+      setItemAction("c", 3),
+    ]);
+    expect(initial).toEqual(before);
+  });
+});
+
+describe("scopedZ", () => {
+  const schema = actions.scopedZ(z.string(), z.object({ kind: z.string() }));
+
+  it("Should parse a fully-populated envelope", () => {
+    const parsed = schema.parse({
+      key: "abc",
+      dispatchKey: "dk",
+      seq: 42,
+      actions: [{ kind: "rename" }],
+    });
+    expect(parsed.key).toBe("abc");
+    expect(parsed.seq).toBe(42);
+    expect(parsed.actions).toEqual([{ kind: "rename" }]);
+  });
+
+  it("Should default seq to 0 when missing", () => {
+    const parsed = schema.parse({ key: "abc", dispatchKey: "dk", actions: [] });
+    expect(parsed.seq).toBe(0);
+  });
+
+  it("Should reject negative seq", () => {
+    expect(() =>
+      schema.parse({ key: "abc", dispatchKey: "dk", seq: -1, actions: [] }),
+    ).toThrow();
+  });
+
+  it("Should reject non-integer seq", () => {
+    expect(() =>
+      schema.parse({ key: "abc", dispatchKey: "dk", seq: 1.5, actions: [] }),
+    ).toThrow();
+  });
+
+  it("Should reject envelopes whose actions fail the inner schema", () => {
+    expect(() =>
+      schema.parse({
+        key: "abc",
+        dispatchKey: "dk",
+        actions: [{ kind: 7 }],
+      }),
+    ).toThrow();
+  });
+});
+
+describe("dispatchReqZ", () => {
+  const schema = actions.dispatchReqZ(z.string(), z.object({ kind: z.string() }));
+
+  it("Should parse a camelCase dispatchKey body", () => {
+    const parsed = schema.parse({
+      key: "abc",
+      dispatchKey: "dk",
+      actions: [{ kind: "x" }],
+    });
+    expect(parsed.dispatchKey).toBe("dk");
+    expect(parsed.actions).toEqual([{ kind: "x" }]);
+  });
+
+  it("Should reject a body missing dispatchKey", () => {
+    expect(() => schema.parse({ key: "abc", actions: [] })).toThrow();
+  });
+});

package/src/actions/actions.ts

@@ -0,0 +1,104 @@
+// Copyright 2026 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 { current, type Draft, isDraft, produce } from "immer";
+import { z } from "zod";
+
+/**
+ * Result returned by a single per-variant action handler. `inverse` is the
+ * action sequence the undo stack should replay to revert the handler's effect.
+ * `targets` is the set of document keys the handler touched, used by consumers
+ * to invalidate undoables targeting overlapping resources when a remote
+ * session emits a competing action.
+ */
+export interface HandlerResult<A> {
+  inverse: A[];
+  targets: readonly string[];
+}
+
+/**
+ * NO_OP_RESULT is the zero-value HandlerResult. Return it from a handler that
+ * declined to mutate state (e.g. lookup miss) so it neither contributes to the
+ * undo stack nor invalidates undoables targeting the same resource.
+ */
+export const NO_OP_RESULT: HandlerResult<never> = { inverse: [], targets: [] };
+
+/**
+ * Result returned by a reduceAll application: the new state, the inverse
+ * sequence that reverts the whole batch, and the union of all targets touched.
+ */
+export interface ReduceAllResult<S, A> {
+  next: S;
+  inverse: A[];
+  targets: readonly string[];
+}
+
+/**
+ * Returns a plain-object snapshot of an Immer draft so the result is safe to
+ * embed in an action stored on the undo stack. Returns non-draft inputs
+ * unchanged. The non-draft passthrough exists because when a reducer applies
+ * multiple actions in one produce(), an earlier action's wholesale
+ * assignment leaves the slot as a plain object, so the next action would
+ * crash if it called `current` unconditionally.
+ */
+export const snapshotDraft = <T>(v: T): T => (isDraft(v) ? current(v as Draft<T>) : v);
+
+/**
+ * createReduceAll lifts a per-variant `reduceOne` switch into a batched
+ * reducer. The returned function applies each action against an Immer draft of
+ * `state` in order, accumulates the inverses in reverse application order so a
+ * single undo replays them correctly, and unions the touched targets.
+ */
+export const createReduceAll =
+  <S, A>(reduceOne: (draft: Draft<S>, action: A) => HandlerResult<A>) =>
+  (state: S, actions: A[]): ReduceAllResult<S, A> => {
+    const inverse: A[] = [];
+    const targetsSet = new Set<string>();
+    const next = produce(state, (draft) => {
+      for (const action of actions) {
+        const result = reduceOne(draft, action);
+        if (result.inverse.length > 0) inverse.unshift(...result.inverse);
+        for (const t of result.targets) targetsSet.add(t);
+      }
+    });
+    return { next, inverse, targets: Array.from(targetsSet) };
+  };
+
+/**
+ * scopedZ builds the schema for envelopes broadcast on the sy_<service>_set
+ * cluster signals channel. The framer's JSON codec runs snakeToCamel before
+ * handing the value to the schema, so `dispatchKey` and `seq` are camelCase
+ * here even though the server emits them as snake_case. `seq` defaults to 0 so
+ * frames from servers that predate the field stay parseable.
+ */
+export const scopedZ = <K extends z.ZodType, A extends z.ZodType>(
+  keyZ: K,
+  actionZ: A,
+) =>
+  z.object({
+    key: keyZ,
+    dispatchKey: z.string(),
+    seq: z.number().int().nonnegative().default(0),
+    actions: actionZ.array(),
+  });
+
+/**
+ * dispatchReqZ builds the request body schema for the per-service dispatch
+ * endpoint. Stays camelCase; the JSON codec runs camelToSnake on encode so the
+ * wire ends up snake_case without per-field conversion here.
+ */
+export const dispatchReqZ = <K extends z.ZodType, A extends z.ZodType>(
+  keyZ: K,
+  actionZ: A,
+) =>
+  z.object({
+    key: keyZ,
+    dispatchKey: z.string(),
+    actions: actionZ.array(),
+  });

package/src/actions/external.ts

@@ -0,0 +1,10 @@
+// Copyright 2026 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 * from "@/actions/actions";

package/src/actions/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2026 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 actions from "@/actions/external";

package/src/arc/client.ts

@@ -8,7 +8,6 @@
 // included in the file licenses/APL.txt.
 
 import {
-  sendRequired,
   type Stream,
   type StreamClient,
   type UnaryClient,
@@ -77,8 +76,7 @@ export class Client {
   async create(arcs: New[]): Promise<Arc[]>;
   async create(arcs: New | New[]): Promise<Arc | Arc[]> {
     const isMany = Array.isArray(arcs);
-    const res = await sendRequired(
-      this.client,
+    const res = await this.client.send(
       "/arc/create",
       { arcs: array.toArray(arcs) },
       createReqZ,
@@ -91,8 +89,7 @@ export class Client {
   async retrieve(args: RetrieveArgs): Promise<Arc[]>;
   async retrieve(args: RetrieveArgs): Promise<Arc | Arc[]> {
     const isSingle = "key" in args || "name" in args;
-    const res = await sendRequired(
-      this.client,
+    const res = await this.client.send(
       "/arc/retrieve",
       args,
       retrieveArgsZ,
@@ -103,8 +100,7 @@ export class Client {
   }
 
   async delete(keys: Key | Key[]): Promise<void> {
-    await sendRequired(
-      this.client,
+    await this.client.send(
       "/arc/delete",
       { keys: array.toArray(keys) },
       deleteReqZ,

package/src/arc/compiler/types.gen.ts

@@ -9,6 +9,7 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
+import { record } from "@synnaxlabs/x";
 import { z } from "zod";
 
 /**
@@ -22,6 +23,6 @@ export const outputZ = z.object({
    * outputMemoryBases contains memory base addresses for multi-output functions, mapping
    * function keys to their base addresses.
    */
-  outputMemoryBases: z.record(z.string(), z.uint32()),
+  outputMemoryBases: record.nullishToEmpty(z.string(), z.uint32()),
 });
 export interface Output extends z.infer<typeof outputZ> {}

package/src/arc/ir/types.gen.ts

@@ -9,7 +9,7 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { array, zod } from "@synnaxlabs/x";
+import { array, record, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { types } from "@/arc/types";
@@ -76,7 +76,7 @@ export const authoritiesZ = z.object({
   /** default is the default authority for all write channels not explicitly listed. */
   default: zod.uint8.optional(),
   /** channels maps channel keys to their specific authority values. */
-  channels: z.record(z.uint32(), zod.uint8),
+  channels: record.nullishToEmpty(z.uint32(), zod.uint8),
 });
 export interface Authorities extends z.infer<typeof authoritiesZ> {}
 

package/src/arc/lsp.spec.ts

@@ -27,7 +27,7 @@ type JSONRPCResponse =
     };
 
 type LSPReceiver = {
-  receive: () => Promise<[{ content: string }, null] | [null, Error]>;
+  receive: () => Promise<{ content: string }>;
 };
 
 const MAX_DRAIN = 50;
@@ -38,9 +38,7 @@ const receiveResponse = async (
   expectedId: number,
 ): Promise<JSONRPCResponse> => {
   for (let i = 0; i < MAX_DRAIN; i++) {
-    const [res, err] = await stream.receive();
-    if (err != null) throw err;
-    if (res == null) throw new Error("Expected response");
+    const res = await stream.receive();
     const msg = JSON.parse(res.content);
     if (!("method" in msg) && "id" in msg && msg.id === expectedId)
       return msg as JSONRPCResponse;
@@ -56,9 +54,7 @@ const receiveNotification = async (
   expectedMethod: string,
 ): Promise<JSONRPCRequest> => {
   for (let i = 0; i < MAX_DRAIN; i++) {
-    const [res, err] = await stream.receive();
-    if (err != null) throw err;
-    if (res == null) throw new Error("Expected message");
+    const res = await stream.receive();
     const msg = JSON.parse(res.content);
     if ("method" in msg && msg.method === expectedMethod) return msg as JSONRPCRequest;
   }

package/src/arc/types/types.gen.ts

@@ -9,7 +9,7 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { array, zod } from "@synnaxlabs/x";
+import { array, record, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
 export enum Kind {
@@ -48,9 +48,9 @@ export const chanDirectionZ = z.enum(ChanDirection);
 /** Channels contains channel declarations for reading from and writing to Synnax channels. */
 export const channelsZ = z.object({
   /** read contains readable channel indices mapped to parameter names. */
-  read: z.record(z.uint32(), z.string()),
+  read: record.nullishToEmpty(z.uint32(), z.string()),
   /** write contains writable channel indices mapped to parameter names. */
-  write: z.record(z.uint32(), z.string()),
+  write: record.nullishToEmpty(z.uint32(), z.string()),
 });
 export interface Channels extends z.infer<typeof channelsZ> {}
 

package/src/auth/auth.spec.ts

@@ -33,8 +33,8 @@ describe("auth", () => {
     );
     const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
     const mw = client.middleware();
-    const res = await mw(DUMMY_CTX, async () => [DUMMY_CTX, null]);
-    expect(res).toEqual([DUMMY_CTX, null]);
+    const res = await mw(DUMMY_CTX, async () => DUMMY_CTX);
+    expect(res).toEqual(DUMMY_CTX);
   });
 
   test("invalid credentials", async () => {
@@ -49,8 +49,7 @@ describe("auth", () => {
       password: "wrong",
     });
     const mw = client.middleware();
-    const [, err] = await mw(DUMMY_CTX, async () => [DUMMY_CTX, null]);
-    expect(err).toBeInstanceOf(AuthError);
+    await expect(mw(DUMMY_CTX, async () => DUMMY_CTX)).rejects.toThrow(AuthError);
   });
 
   describe("token retry", () => {
@@ -68,16 +67,16 @@ describe("auth", () => {
         let isFirst = true;
         let tkOne: string | undefined;
         let tkTwo: string | undefined;
-        const [, err] = await mw(DUMMY_CTX, async () => {
+        const res = await mw(DUMMY_CTX, async () => {
           if (isFirst) {
             isFirst = false;
             tkOne = client.token;
-            return [DUMMY_CTX, new ErrorType()];
+            throw new ErrorType();
           }
           tkTwo = client.token;
-          return [DUMMY_CTX, null];
+          return DUMMY_CTX;
         });
-        expect(err).toBeNull();
+        expect(res).toEqual(DUMMY_CTX);
         expect(tkOne).toBeDefined();
         expect(tkTwo).toBeDefined();
       });
@@ -92,11 +91,11 @@ describe("auth", () => {
       );
       const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
       const mw = client.middleware();
-      const [, err] = await mw(DUMMY_CTX, async () => [
-        DUMMY_CTX,
-        new InvalidTokenError(),
-      ]);
-      expect(err).toBeInstanceOf(InvalidTokenError);
+      await expect(
+        mw(DUMMY_CTX, async () => {
+          throw new InvalidTokenError();
+        }),
+      ).rejects.toThrow(InvalidTokenError);
     });
   });
 });

package/src/auth/auth.ts

@@ -7,15 +7,15 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { type Middleware, sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
+import { type Middleware, type UnaryClient } from "@synnaxlabs/freighter";
 import { TimeStamp } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { ExpiredTokenError, InvalidTokenError } from "@/errors";
 import { user } from "@/user";
 
-const insecureCredentialsZ = z.object({ username: z.string(), password: z.string() });
-interface InsecureCredentials extends z.infer<typeof insecureCredentialsZ> {}
+const credentialsZ = z.object({ username: z.string(), password: z.string() });
+interface Credentials extends z.infer<typeof credentialsZ> {}
 
 const clusterInfoZ = z.object({
   clusterKey: z.string(),
@@ -49,12 +49,12 @@ type AuthState =
 
 export class Client {
   private readonly client: UnaryClient;
-  private readonly credentials: InsecureCredentials;
+  private readonly credentials: Credentials;
   private authState: AuthState = { authenticated: false };
   authenticating: Promise<Error | null> | undefined;
   private retryCount: number;
 
-  constructor(client: UnaryClient, credentials: InsecureCredentials) {
+  constructor(client: UnaryClient, credentials: Credentials) {
     this.client = client;
     this.credentials = credentials;
     this.retryCount = 0;
@@ -82,8 +82,7 @@ export class Client {
 
   async changePassword(newPassword: string): Promise<void> {
     if (!this.authenticated) throw new Error("Not authenticated");
-    await sendRequired<typeof changePasswordReqZ, typeof changePasswordResZ>(
-      this.client,
+    await this.client.send(
       "/auth/change-password",
       {
         username: this.credentials.username,
@@ -99,39 +98,42 @@ export class Client {
   middleware(): Middleware {
     const mw: Middleware = async (reqCtx, next) => {
       if (!this.authenticated && !reqCtx.target.endsWith(LOGIN_ENDPOINT)) {
-        this.authenticating ??= new Promise((resolve, reject) => {
-          this.client
-            .send(
+        this.authenticating ??= (async (): Promise<Error | null> => {
+          try {
+            const res = await this.client.send(
               LOGIN_ENDPOINT,
               this.credentials,
-              insecureCredentialsZ,
+              credentialsZ,
               tokenResponseZ,
-            )
-            .then(([res, err]) => {
-              if (err != null) return resolve(err);
-              if (res == null) return resolve(new Error("No response from login"));
-              this.authState = {
-                authenticated: true,
-                user: res.user,
-                token: res.token,
-              };
-              resolve(null);
-            })
-            .catch(reject);
-        });
+            );
+            this.authState = {
+              authenticated: true,
+              user: res.user,
+              token: res.token,
+            };
+            return null;
+          } catch (err) {
+            return err instanceof Error ? err : new Error(String(err));
+          }
+        })();
         const err = await this.authenticating;
-        if (err != null) return [reqCtx, err];
+        if (err != null) throw err;
       }
       reqCtx.params.Authorization = `Bearer ${this.token}`;
-      const [resCtx, err] = await next(reqCtx);
-      if (RETRY_ON.some((e) => e.matches(err)) && this.retryCount < MAX_RETRIES) {
-        this.authState = { authenticated: false };
-        this.authenticating = undefined;
-        this.retryCount += 1;
-        return mw(reqCtx, next);
+      try {
+        const resCtx = await next(reqCtx);
+        this.retryCount = 0;
+        return resCtx;
+      } catch (err) {
+        if (RETRY_ON.some((e) => e.matches(err)) && this.retryCount < MAX_RETRIES) {
+          this.authState = { authenticated: false };
+          this.authenticating = undefined;
+          this.retryCount += 1;
+          return mw(reqCtx, next);
+        }
+        this.retryCount = 0;
+        throw err;
       }
-      this.retryCount = 0;
-      return [resCtx, err];
     };
     return mw;
   }