@synnaxlabs/freighter 0.41.0 → 0.42.0

package/dist/http.d.ts

@@ -16,6 +16,6 @@ export declare class HTTPClient extends MiddlewareCollector implements UnaryClie
     fetch: typeof fetch;
     constructor(endpoint: URL, encoder: binary.Codec, secure?: boolean);
     get headers(): Record<string, string>;
-    send<RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny = RQ>(target: string, req: z.input<RQ> | z.output<RQ>, reqSchema: RQ, resSchema: RS): Promise<[z.output<RS> | null, Error | null]>;
+    send<RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny = RQ>(target: string, req: z.input<RQ> | z.output<RQ>, reqSchema: RQ, resSchema: RS): Promise<[z.output<RS>, null] | [null, Error]>;
 }
 //# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,MAAM,EAAW,KAAK,GAAG,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B,OAAO,EAAgB,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AActD;;;;;;GAMG;AACH,qBAAa,UAAW,SAAQ,mBAAoB,YAAW,WAAW;IACxE,QAAQ,EAAE,GAAG,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;IACtB,KAAK,EAAE,OAAO,KAAK,CAAC;gBAER,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAE,OAAe;IAczE,IAAI,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIpC;IAEK,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,UAAU,EAAE,EAAE,SAAS,CAAC,CAAC,UAAU,GAAG,EAAE,EAC9D,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAC/B,SAAS,EAAE,EAAE,EACb,SAAS,EAAE,EAAE,GACZ,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC,CAAC;CAuDhD"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,MAAM,EAAmB,KAAK,GAAG,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B,OAAO,EAAgB,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAoBtD;;;;;;GAMG;AACH,qBAAa,UAAW,SAAQ,mBAAoB,YAAW,WAAW;IACxE,QAAQ,EAAE,GAAG,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;IACtB,KAAK,EAAE,OAAO,KAAK,CAAC;gBAER,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAE,OAAe;IAczE,IAAI,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIpC;IAEK,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,UAAU,EAAE,EAAE,SAAS,CAAC,CAAC,UAAU,GAAG,EAAE,EAC9D,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAC/B,SAAS,EAAE,EAAE,EACb,SAAS,EAAE,EAAE,GACZ,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;CAwDjD"}

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-export { BaseTypedError, decodeError, encodeError, EOF, errorMatcher, type ErrorPayload, errorZ, type MatchableErrorType, registerError, StreamClosed, type TypedError, Unreachable, } from './errors';
+export { EOF, StreamClosed, Unreachable } from './errors';
 export { HTTPClient } from './http';
 export { type Context, type Middleware, type Next } from './middleware';
 export { type Stream, type StreamClient } from './stream';
 export { sendRequired, type UnaryClient, unaryWithBreaker } from './unary';
 export { WebSocketClient } from './websocket';
+export { type WebsocketMessage } from './websocket';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EACL,cAAc,EACd,WAAW,EACX,WAAW,EACX,GAAG,EACH,YAAY,EACZ,KAAK,YAAY,EACjB,MAAM,EACN,KAAK,kBAAkB,EACvB,aAAa,EACb,YAAY,EACZ,KAAK,UAAU,EACf,WAAW,GACZ,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,IAAI,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,IAAI,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/unary.d.ts

@@ -1,4 +1,4 @@
-import { breaker } from '@synnaxlabs/x';
+import { breaker, errors } from '@synnaxlabs/x';
 import { z } from 'zod';
 import { Transport } from './transport';
 /**
@@ -12,7 +12,7 @@ export interface UnaryClient extends Transport {
      * @param req - The request to send.
      * @param resSchema - The schema to validate the response against.
      */
-    send: <RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny = RQ>(target: string, req: z.input<RQ> | z.output<RQ>, reqSchema: RQ, resSchema: RS) => Promise<[z.output<RS>, null] | [null, Error]>;
+    send: <RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny = RQ>(target: string, req: z.input<RQ> | z.output<RQ>, reqSchema: RQ, resSchema: RS) => Promise<errors.Return<z.output<RS>>>;
 }
 export declare const unaryWithBreaker: (base: UnaryClient, cfg: breaker.Config) => UnaryClient;
 export declare const sendRequired: <RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny = RQ>(client: UnaryClient, target: string, req: z.input<RQ> | z.output<RQ>, reqSchema: RQ, resSchema: RS) => Promise<z.output<RS>>;

package/dist/unary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unary.d.ts","sourceRoot":"","sources":["../src/unary.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC;AAI7B,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;GAGG;AACH,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C;;;;;OAKG;IACH,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,UAAU,EAAE,EAAE,SAAS,CAAC,CAAC,UAAU,GAAG,EAAE,EAC1D,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAC/B,SAAS,EAAE,EAAE,EACb,SAAS,EAAE,EAAE,KACV,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;CACpD;AAED,eAAO,MAAM,gBAAgB,GAC3B,MAAM,WAAW,EACjB,KAAK,OAAO,CAAC,MAAM,KAClB,WA2BF,CAAC;AAEF,eAAO,MAAM,YAAY,GACvB,EAAE,SAAS,CAAC,CAAC,UAAU,EACvB,EAAE,SAAS,CAAC,CAAC,UAAU,GAAG,EAAE,EAE5B,QAAQ,WAAW,EACnB,QAAQ,MAAM,EACd,KAAK,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAC/B,WAAW,EAAE,EACb,WAAW,EAAE,KACZ,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAItB,CAAC"}
+{"version":3,"file":"unary.d.ts","sourceRoot":"","sources":["../src/unary.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC;AAI7B,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;GAGG;AACH,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C;;;;;OAKG;IACH,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,UAAU,EAAE,EAAE,SAAS,CAAC,CAAC,UAAU,GAAG,EAAE,EAC1D,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAC/B,SAAS,EAAE,EAAE,EACb,SAAS,EAAE,EAAE,KACV,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;CAC3C;AAED,eAAO,MAAM,gBAAgB,GAC3B,MAAM,WAAW,EACjB,KAAK,OAAO,CAAC,MAAM,KAClB,WA4BF,CAAC;AAEF,eAAO,MAAM,YAAY,GACvB,EAAE,SAAS,CAAC,CAAC,UAAU,EACvB,EAAE,SAAS,CAAC,CAAC,UAAU,GAAG,EAAE,EAE5B,QAAQ,WAAW,EACnB,QAAQ,MAAM,EACd,KAAK,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAC/B,WAAW,EAAE,EACb,WAAW,EAAE,KACZ,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAItB,CAAC"}

package/dist/websocket.d.ts

@@ -1,7 +1,12 @@
-import { binary, URL } from '@synnaxlabs/x';
+import { binary, errors, URL } from '@synnaxlabs/x';
 import { z } from 'zod';
 import { MiddlewareCollector } from './middleware';
 import { Stream, StreamClient } from './stream';
+export type WebsocketMessage<P = unknown> = {
+    type: "data" | "close" | "open";
+    error?: errors.Payload;
+    payload?: P;
+};
 export declare const FREIGHTER_METADATA_PREFIX = "freighterctx";
 /**
  * WebSocketClient is an implementation of StreamClient that is backed by
@@ -10,6 +15,7 @@ export declare const FREIGHTER_METADATA_PREFIX = "freighterctx";
 export declare class WebSocketClient extends MiddlewareCollector implements StreamClient {
     baseUrl: URL;
     encoder: binary.Codec;
+    secure: boolean;
     static readonly MESSAGE_TYPE = "arraybuffer";
     /**
      * @param encoder - The encoder to use for encoding messages and decoding
@@ -17,6 +23,7 @@ export declare class WebSocketClient extends MiddlewareCollector implements Stre
      * @param baseEndpoint - A base url to use as a prefix for all requests.
      */
     constructor(baseEndpoint: URL, encoder: binary.Codec, secure?: boolean);
+    withCodec(codec: binary.Codec): WebSocketClient;
     /** Implements the StreamClient interface. */
     stream<RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny = RQ>(target: string, reqSchema: RQ, resSchema: RS): Promise<Stream<RQ, RS>>;
     private buildURL;

package/dist/websocket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,MAAM,EAA6B,KAAK,GAAG,EAAE,MAAM,eAAe,CAAC;AACjF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAgB,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAoH1D,eAAO,MAAM,yBAAyB,iBAAiB,CAAC;AAQxD;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,mBAAoB,YAAW,YAAY;IAC9E,OAAO,EAAE,GAAG,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;IAEtB,MAAM,CAAC,QAAQ,CAAC,YAAY,iBAAiB;IAE7C;;;;OAIG;gBACS,YAAY,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,UAAQ;IAMpE,6CAA6C;IACvC,MAAM,CAAC,EAAE,SAAS,CAAC,CAAC,UAAU,EAAE,EAAE,SAAS,CAAC,CAAC,UAAU,GAAG,EAAE,EAChE,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,EAAE,EACb,SAAS,EAAE,EAAE,GACZ,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAmB1B,OAAO,CAAC,QAAQ;YAWF,UAAU;CAsBzB"}
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"AASA,OAAO,EACL,KAAK,MAAM,EAEX,MAAM,EAEN,KAAK,GAAG,EACT,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAgB,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAc1D,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI;IAC1C,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,CAAC,CAAC;CACb,CAAC;AA8GF,eAAO,MAAM,yBAAyB,iBAAiB,CAAC;AAIxD;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,mBAAoB,YAAW,YAAY;IAC9E,OAAO,EAAE,GAAG,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;IAEhB,MAAM,CAAC,QAAQ,CAAC,YAAY,iBAAiB;IAE7C;;;;OAIG;gBACS,YAAY,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,UAAQ;IAOpE,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,GAAG,eAAe;IAM/C,6CAA6C;IACvC,MAAM,CAAC,EAAE,SAAS,CAAC,CAAC,UAAU,EAAE,EAAE,SAAS,CAAC,CAAC,UAAU,GAAG,EAAE,EAChE,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,EAAE,EACb,SAAS,EAAE,EAAE,GACZ,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAmB1B,OAAO,CAAC,QAAQ;YAWF,UAAU;CAsBzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synnaxlabs/freighter",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "type": "module",
   "description": "a modular transport abstraction",
   "repository": "https://github.com/synnaxlabs/synnax/tree/main/freighter/ts",
@@ -16,19 +16,20 @@
   "dependencies": {
     "node-fetch": "^2.7.0",
     "ws": "^8.18.1",
-    "zod": "^3.24.2",
-    "@synnaxlabs/alamos": "0.41.0",
-    "@synnaxlabs/x": "0.41.0"
+    "zod": "^4.0.0-beta",
+    "@synnaxlabs/alamos": "0.42.0",
+    "@synnaxlabs/x": "0.42.0"
   },
   "devDependencies": {
     "@types/node": "^22.13.10",
+    "@vitest/coverage-v8": "^3.1.3",
     "eslint": "^9.24.0",
     "madge": "^8.0.0",
     "typescript": "^5.8.3",
     "vite": "^6.2.5",
     "vitest": "^3.1.1",
-    "@synnaxlabs/vite-plugin": "0.0.1",
     "@synnaxlabs/tsconfig": "0.0.2",
+    "@synnaxlabs/vite-plugin": "0.0.1",
     "eslint-config-synnaxlabs": "0.0.1"
   },
   "main": "dist/freighter.cjs",

package/src/alamos.ts

@@ -9,13 +9,14 @@
 
 import { type Instrumentation } from "@synnaxlabs/alamos";
 
-import { type Context,type Middleware } from "@/middleware";
+import { type Context, type Middleware } from "@/middleware";
 
 export const middleware =
   (instrumentation: Instrumentation): Middleware =>
   async (context, next) => {
     if (context.role === "client") instrumentation.T.propagate(context.params);
-    const [res, exc] = await instrumentation.T.trace(
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+    const [res, exc] = (await instrumentation.T.trace(
       context.target,
       "debug",
       async (span): Promise<[Context, Error | null]> => {
@@ -23,7 +24,7 @@ export const middleware =
         if (err != null) span.recordError(err);
         return [ctx, err];
       },
-    );
+    )) as [Context, Error | null];
     log(context, instrumentation, exc);
     return [res, exc];
   };

package/src/errors.spec.ts

@@ -7,86 +7,19 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+import { errors } from "@synnaxlabs/x";
 import { describe, expect, test } from "vitest";
 
-import {
-  assertErrorType,
-  BaseTypedError,
-  decodeError,
-  encodeError,
-  EOF,
-  type ErrorPayload,
-  FREIGHTER,
-  isTypedError,
-  NONE,
-  registerError,
-  StreamClosed,
-  type TypedError,
-  UNKNOWN,
-  UnknownError,
-  Unreachable,
-} from "@/errors";
-
-class MyCustomError extends BaseTypedError {
-  type = "MyCustomError";
-}
-
-const myCustomErrorEncoder = (error: MyCustomError): ErrorPayload | null => {
-  if (error.type !== "MyCustomError") return null;
-  return { type: "MyCustomError", data: error.message };
-};
-
-const myCustomErrorDecoder = (encoded: ErrorPayload): TypedError =>
-  new MyCustomError(encoded.data);
+import { EOF, FreighterError, StreamClosed, Unreachable } from "@/errors";
 
 describe("errors", () => {
-  test("isTypedError", () => {
-    const error = new MyCustomError("test");
-    const fError = isTypedError(error);
-    expect(fError).toBeTruthy();
-    expect(error.type).toEqual("MyCustomError");
-  });
-
-  test("encoding and decoding a custom error through registry", () => {
-    registerError({
-      encode: myCustomErrorEncoder,
-      decode: myCustomErrorDecoder,
-    });
-    const error = new MyCustomError("test");
-    const encoded = encodeError(error);
-    expect(encoded.type).toEqual("MyCustomError");
-    expect(encoded.data).toEqual("test");
-    const decoded = assertErrorType<MyCustomError>(
-      "MyCustomError",
-      decodeError(encoded),
-    );
-    expect(decoded.message).toEqual("test");
-  });
-
-  test("encoding and decoding a null error", () => {
-    const encoded = encodeError(null);
-    expect(encoded.type).toEqual(NONE);
-    expect(encoded.data).toEqual("");
-    const decoded = decodeError(encoded);
-    expect(decoded).toBeNull();
-  });
-
-  test("encoding and decoding an unrecognized error", () => {
-    const error = new Error("test");
-    const encoded = encodeError(error);
-    expect(encoded.type).toEqual(UNKNOWN);
-    expect(encoded.data).toEqual("{}");
-    const decoded = decodeError(encoded);
-    expect(decoded).toEqual(new UnknownError("{}"));
-  });
-
   test("encoding and decoding freighter errors", () => {
     [new EOF(), new StreamClosed(), new Unreachable()].forEach((error) => {
-      const encoded = encodeError(error);
-      expect(encoded.type.startsWith(FREIGHTER)).toBeTruthy();
+      const encoded = errors.encode(error);
+      expect(encoded.type.startsWith(FreighterError.TYPE)).toBeTruthy();
       expect(encoded.data).toEqual(error.message);
-      const decoded = decodeError(encoded);
-      expect(decoded).toEqual(error);
+      const decoded = errors.decode(encoded);
+      expect(error.matches(decoded)).toBeTruthy();
     });
   });
 });

package/src/errors.ts

@@ -7,189 +7,41 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { URL } from "@synnaxlabs/x";
-import { z } from "zod";
-
-/** Basic interface for an error or error type that can be matched against a candidate error */
-export interface MatchableErrorType {
-  /**
-   * @returns a function that matches errors of the given type. Returns true if
-   * the provided instance of Error or a string message contains the provided error type.
-   */
-  matches: (e: string | Error | unknown) => boolean;
-}
-
-export interface TypedError extends Error {
-  discriminator: "FreighterError";
-  /**
-   * @description Returns a unique type identifier for the error. Freighter uses this to
-   * determine the correct decoder to use on the other end of the freighter.
-   */
-  type: string;
-}
+import { errors, URL } from "@synnaxlabs/x";
 
 /**
- * @param type - the error type to match
- * @returns a function that matches errors of the given type. Returns true if
- * the provided instance of Error or a string message contains the provided error type.
+ * @description Base class for all freighter-specific errors
  */
-export const errorMatcher =
-  (type: string) =>
-  (e: string | Error | unknown): boolean => {
-    if (e != null && typeof e === "object" && "type" in e && typeof e.type === "string")
-      return e.type.includes(type);
-    if (e instanceof Error) return e.message.includes(type);
-    if (typeof e !== "string") return false;
-    return e.includes(type);
-  };
-
-export class BaseTypedError extends Error implements TypedError {
-  readonly discriminator = "FreighterError";
-  type: string = "";
-}
-
-type ErrorDecoder = (encoded: ErrorPayload) => Error | null;
-type ErrorEncoder = (error: TypedError) => ErrorPayload | null;
-
-export const isTypedError = (error: unknown): error is TypedError => {
-  if (error == null || typeof error !== "object") return false;
-  const typedError = error as TypedError;
-  if (typedError.discriminator !== "FreighterError") return false;
-  if (!("type" in typedError))
-    throw new Error(
-      `Freighter error is missing its type property: ${JSON.stringify(typedError)}`,
-    );
-  return true;
-};
-
-export const assertErrorType = <T>(type: string, error?: Error | null): T => {
-  if (error == null)
-    throw new Error(`Expected error of type ${type} but got nothing instead`);
-  if (!isTypedError(error))
-    throw new Error(`Expected a typed error, got: ${error.message}`);
-  if (error.type !== type)
-    throw new Error(
-      `Expected error of type ${type}, got ${error.type}: ${error.message}`,
-    );
-  return error as T;
-};
-
-export const UNKNOWN = "unknown";
-export const NONE = "nil";
-export const FREIGHTER = "freighter";
-
-export const errorZ = z.object({ type: z.string(), data: z.string() });
-
-export type ErrorPayload = z.infer<typeof errorZ>;
-
-interface errorProvider {
-  encode: ErrorEncoder;
-  decode: ErrorDecoder;
-}
-
-class Registry {
-  private readonly providers: errorProvider[] = [];
-
-  register(provider: errorProvider): void {
-    this.providers.push(provider);
-  }
-
-  encode(error: unknown): ErrorPayload {
-    if (error == null) return { type: NONE, data: "" };
-    if (isTypedError(error))
-      for (const provider of this.providers) {
-        const payload = provider.encode(error);
-        if (payload != null) return payload;
-      }
-    return { type: UNKNOWN, data: JSON.stringify(error) };
-  }
-
-  decode(payload?: ErrorPayload | null): Error | null {
-    if (payload == null || payload.type === NONE) return null;
-    if (payload.type === UNKNOWN) return new UnknownError(payload.data);
-    for (const provider of this.providers) {
-      const error = provider.decode(payload);
-      if (error != null) return error;
-    }
-    return new UnknownError(payload.data);
-  }
-}
-
-const REGISTRY = new Registry();
-
-/**
- * Registers a custom error type with the error registry, which allows it to be
- * encoded/decoded and sent over the network.
- *
- * @param type - A unique string identifier for the error type.
- * @param encode - A function that encodes the error into a string.
- * @param decode - A function that decodes the error from a string.
- */
-export const registerError = ({
-  encode,
-  decode,
-}: {
-  encode: ErrorEncoder;
-  decode: ErrorDecoder;
-}): void => REGISTRY.register({ encode, decode });
-
-/**
- * Encodes an error into a payload that can be sent between a freighter server
- * and client.
- * @param error - The error to encode.
- * @returns The encoded error.
- */
-export const encodeError = (error: unknown): ErrorPayload => REGISTRY.encode(error);
+export class FreighterError extends errors.createTyped("freighter") {}
 
 /**
- * Decodes an error payload into an exception. If a custom decoder can be found
- * for the error type, it will be used. Otherwise, a generic Error containing
- * the error data is returned.
- *
- * @param payload - The encoded error payload.
- * @returns The decoded error.
+ * @description Error thrown when reaching the end of a file or stream
  */
-export const decodeError = (payload: ErrorPayload): Error | null =>
-  REGISTRY.decode(payload);
-
-export class UnknownError extends BaseTypedError implements TypedError {
-  type = "unknown";
-}
-
-const FREIGHTER_ERROR_TYPE = "freighter.";
-
-/** Thrown/returned when a stream closed normally. */
-export class EOF extends BaseTypedError implements TypedError {
-  static readonly TYPE = `${FREIGHTER_ERROR_TYPE}eof`;
-  type = EOF.TYPE;
-  static readonly matches = errorMatcher(EOF.TYPE);
-
+export class EOF extends FreighterError.sub("eof") {
   constructor() {
     super("EOF");
   }
 }
 
-/** Thrown/returned when a stream is closed abnormally. */
-export class StreamClosed extends BaseTypedError implements TypedError {
-  static readonly TYPE = `${FREIGHTER_ERROR_TYPE}stream_closed`;
-  static readonly matches = errorMatcher(StreamClosed.TYPE);
-  type = StreamClosed.TYPE;
-
+/**
+ * @description Error thrown when attempting to operate on a closed stream
+ */
+export class StreamClosed extends FreighterError.sub("stream_closed") {
   constructor() {
     super("StreamClosed");
   }
 }
 
+/**
+ * @description Arguments for constructing an Unreachable error
+ */
 export interface UnreachableArgs {
   message?: string;
   url?: URL;
 }
 
-/** Thrown when a target is unreachable. */
-export class Unreachable extends BaseTypedError implements TypedError {
-  static readonly TYPE = `${FREIGHTER_ERROR_TYPE}unreachable`;
-  type = Unreachable.TYPE;
-  static readonly matches = errorMatcher(Unreachable.TYPE);
+/** @description Thrown when a network target is unreachable. */
+export class Unreachable extends FreighterError.sub("unreachable") {
   url: URL;
 
   constructor(args: UnreachableArgs = {}) {
@@ -199,8 +51,8 @@ export class Unreachable extends BaseTypedError implements TypedError {
   }
 }
 
-const freighterErrorEncoder: ErrorEncoder = (error: TypedError) => {
-  if (!error.type.startsWith(FREIGHTER)) return null;
+const freighterErrorEncoder: errors.Encoder = (error: errors.Typed) => {
+  if (!error.type.startsWith(FreighterError.TYPE)) return null;
   if (EOF.matches(error)) return { type: EOF.TYPE, data: "EOF" };
   if (StreamClosed.matches(error))
     return { type: StreamClosed.TYPE, data: "StreamClosed" };
@@ -209,8 +61,8 @@ const freighterErrorEncoder: ErrorEncoder = (error: TypedError) => {
   throw new Error(`Unknown error type: ${error.type}: ${error.message}`);
 };
 
-const freighterErrorDecoder: ErrorDecoder = (encoded: ErrorPayload) => {
-  if (!encoded.type.startsWith(FREIGHTER_ERROR_TYPE)) return null;
+const freighterErrorDecoder: errors.Decoder = (encoded: errors.Payload) => {
+  if (!encoded.type.startsWith(FreighterError.TYPE)) return null;
   switch (encoded.type) {
     case EOF.TYPE:
       return new EOF();
@@ -219,11 +71,11 @@ const freighterErrorDecoder: ErrorDecoder = (encoded: ErrorPayload) => {
     case Unreachable.TYPE:
       return new Unreachable();
     default:
-      throw new Error(`Unknown error type: ${encoded.data}`);
+      throw new errors.Unknown(`Unknown error type: ${encoded.data}`);
   }
 };
 
-registerError({
+errors.register({
   encode: freighterErrorEncoder,
   decode: freighterErrorDecoder,
 });

package/src/http.ts

@@ -7,10 +7,10 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { type binary, runtime, type URL } from "@synnaxlabs/x";
+import { type binary, errors, runtime, type URL } from "@synnaxlabs/x";
 import { type z } from "zod";
 
-import { decodeError, errorZ, Unreachable } from "@/errors";
+import { Unreachable } from "@/errors";
 import { type Context, MiddlewareCollector } from "@/middleware";
 import { type UnaryClient } from "@/unary";
 
@@ -28,6 +28,12 @@ const resolveFetchAPI = (protocol: "http" | "https"): typeof fetch => {
   return async (info, init) => await _fetch(info, { ...init, agent });
 };
 
+const shouldCastToUnreachable = (err: Error): boolean =>
+  ("code" in err && err.code === "ECONNREFUSED") ||
+  err.message.toLowerCase().includes("load failed");
+
+const HTTP_STATUS_BAD_REQUEST = 400;
+
 /**
  * HTTPClientFactory provides a POST and GET implementation of the Unary
  * protocol.
@@ -65,14 +71,13 @@ export class HTTPClient extends MiddlewareCollector implements UnaryClient {
     req: z.input<RQ> | z.output<RQ>,
     reqSchema: RQ,
     resSchema: RS,
-  ): Promise<[z.output<RS> | null, Error | null]> {
+  ): Promise<[z.output<RS>, null] | [null, Error]> {
     req = reqSchema?.parse(req);
-    let res: RS | null = null;
+    let res: z.output<RS> | null = null;
     const url = this.endpoint.child(target);
     const request: RequestInit = {};
     request.method = "POST";
     request.body = this.encoder.encode(req ?? {});
-
     const [, err] = await this.executeMiddleware(
       {
         target: url.toString(),
@@ -92,18 +97,19 @@ export class HTTPClient extends MiddlewareCollector implements UnaryClient {
           httpRes = await f(ctx.target, request);
         } catch (err_) {
           let err = err_ as Error;
-          if (err.message === "Load failed") err = new Unreachable({ url });
+          if (shouldCastToUnreachable(err)) err = new Unreachable({ url });
           return [outCtx, err];
         }
-        const data = await httpRes.arrayBuffer();
+        const data = new Uint8Array(await (await httpRes.blob()).arrayBuffer());
         if (httpRes?.ok) {
-          if (resSchema != null) res = this.encoder.decode(data, resSchema);
+          if (resSchema != null) res = this.encoder.decode<RS>(data, resSchema);
           return [outCtx, null];
         }
         try {
-          if (httpRes.status !== 400) return [outCtx, new Error(httpRes.statusText)];
-          const err = this.encoder.decode(data, errorZ);
-          const decoded = decodeError(err);
+          if (httpRes.status !== HTTP_STATUS_BAD_REQUEST)
+            return [outCtx, new Error(httpRes.statusText)];
+          const err = this.encoder.decode(data, errors.payloadZ);
+          const decoded = errors.decode(err);
           return [outCtx, decoded];
         } catch (e) {
           return [
@@ -118,6 +124,7 @@ export class HTTPClient extends MiddlewareCollector implements UnaryClient {
       },
     );
 
-    return [res, err];
+    if (err != null) return [null, err];
+    return [res, null];
   }
 }

package/src/index.ts

@@ -7,22 +7,10 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export {
-  BaseTypedError,
-  decodeError,
-  encodeError,
-  EOF,
-  errorMatcher,
-  type ErrorPayload,
-  errorZ,
-  type MatchableErrorType,
-  registerError,
-  StreamClosed,
-  type TypedError,
-  Unreachable,
-} from "@/errors";
+export { EOF, StreamClosed, Unreachable } from "@/errors";
 export { HTTPClient } from "@/http";
 export { type Context, type Middleware, type Next } from "@/middleware";
 export { type Stream, type StreamClient } from "@/stream";
 export { sendRequired, type UnaryClient, unaryWithBreaker } from "@/unary";
 export { WebSocketClient } from "@/websocket";
+export { type WebsocketMessage } from "@/websocket";

package/src/unary.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 { breaker } from "@synnaxlabs/x";
+import { breaker, type errors } from "@synnaxlabs/x";
 import { type z } from "zod";
 
 import { Unreachable } from "@/errors";
@@ -30,7 +30,7 @@ export interface UnaryClient extends Transport {
     req: z.input<RQ> | z.output<RQ>,
     reqSchema: RQ,
     resSchema: RS,
-  ) => Promise<[z.output<RS>, null] | [null, Error]>;
+  ) => Promise<errors.Return<z.output<RS>>>;
 }
 
 export const unaryWithBreaker = (
@@ -53,12 +53,13 @@ export const unaryWithBreaker = (
       req: z.input<RQ> | z.output<RQ>,
       reqSchema: RQ,
       resSchema: RS,
-    ): Promise<[z.output<RS>, null] | [null, Error]> {
-      const brk = breaker.create(cfg);
+    ): Promise<errors.Return<z.output<RS>>> {
+      const brk = new breaker.Breaker(cfg);
       do {
         const [res, err] = await this.wrapped.send(target, req, reqSchema, resSchema);
-        if (err == null || !Unreachable.matches(err)) return [res, err];
-        if (!(await brk())) return [res, err];
+        if (err == null) return [res, null];
+        if (!Unreachable.matches(err)) return [null, err];
+        if (!(await brk.wait())) return [res, err];
       } while (true);
     }
   }