Merge pull request #166 from Mitch5000/Add-typed-Result-helpers-for-pattern-matching-on-errors-FIXED

 Add typed Result helpers for pattern matching on errors FIXED

Author: Just-Bamford

src/index.ts

@@ -196,12 +196,22 @@ export {
   assertOk,
   attachTraceId,
   err,
+  isAccountNotFound,
+  isContractError,
   isErr,
   isErrorCode,
   isOk,
+  isTxFailed,
   ok,
 } from "./shared/response";
-export type { SorokitError, SorokitResult } from "./shared/response";
+export type {
+  AccountNotFoundErrorCode,
+  ContractErrorCode,
+  SorokitError,
+  SorokitErrorResult,
+  SorokitResult,
+  TxFailedErrorCode,
+} from "./shared/response";
 export { generateTraceId } from "./shared/utils";
 
 // ─── Metrics ──────────────────────────────────────────────────────────────────

src/shared/response.ts

@@ -26,6 +26,25 @@ export interface SorokitError {
   traceId?: string;
 }
 
+export type SorokitErrorResult<C extends SorokitErrorCode = SorokitErrorCode> = {
+  status: "error";
+  data: null;
+  error: SorokitError & { code: C };
+};
+
+export type AccountNotFoundErrorCode = SorokitErrorCode.ACCOUNT_NOT_FOUND;
+
+export type TxFailedErrorCode =
+  | SorokitErrorCode.TX_BUILD_FAILED
+  | SorokitErrorCode.TX_SIMULATE_FAILED
+  | SorokitErrorCode.TX_SUBMIT_FAILED;
+
+export type ContractErrorCode =
+  | SorokitErrorCode.CONTRACT_INVOKE_FAILED
+  | SorokitErrorCode.CONTRACT_READ_FAILED
+  | SorokitErrorCode.CONTRACT_PREPARE_FAILED
+  | SorokitErrorCode.CONTRACT_SIMULATE_FAILED;
+
 export enum SorokitErrorCode {
   // Wallet
   WALLET_NOT_FOUND = "WALLET_NOT_FOUND",
@@ -117,10 +136,42 @@ export function isErr<T>(
 export function isErrorCode<T, C extends SorokitErrorCode>(
   result: SorokitResult<T>,
   code: C,
-): result is { status: "error"; data: null; error: SorokitError & { code: C } } {
+): result is SorokitErrorResult<C> {
   return result.status === "error" && result.error.code === code;
 }
 
+/** Type guard — narrows to ACCOUNT_NOT_FOUND error results. */
+export function isAccountNotFound<T>(
+  result: SorokitResult<T>,
+): result is SorokitErrorResult<AccountNotFoundErrorCode> {
+  return isErrorCode(result, SorokitErrorCode.ACCOUNT_NOT_FOUND);
+}
+
+/** Type guard — narrows to transaction failure error results. */
+export function isTxFailed<T>(
+  result: SorokitResult<T>,
+): result is SorokitErrorResult<TxFailedErrorCode> {
+  return (
+    result.status === "error" &&
+    (result.error.code === SorokitErrorCode.TX_BUILD_FAILED ||
+      result.error.code === SorokitErrorCode.TX_SIMULATE_FAILED ||
+      result.error.code === SorokitErrorCode.TX_SUBMIT_FAILED)
+  );
+}
+
+/** Type guard — narrows to contract-related error results. */
+export function isContractError<T>(
+  result: SorokitResult<T>,
+): result is SorokitErrorResult<ContractErrorCode> {
+  return (
+    result.status === "error" &&
+    (result.error.code === SorokitErrorCode.CONTRACT_INVOKE_FAILED ||
+      result.error.code === SorokitErrorCode.CONTRACT_READ_FAILED ||
+      result.error.code === SorokitErrorCode.CONTRACT_PREPARE_FAILED ||
+      result.error.code === SorokitErrorCode.CONTRACT_SIMULATE_FAILED)
+  );
+}
+
 /**
  * Assert that a result is ok — throws if it is an error.
  * Use in contexts where an error is unrecoverable and you want to fail fast.

src/tests/result.test.ts

@@ -1,5 +1,22 @@
-import { describe, it, expect } from "vitest";
-import { ok, err, isOk, isErr, isErrorCode, assertOk, SorokitErrorCode } from "../shared/response";
+import { describe, it, expect, expectTypeOf } from "vitest";
+import {
+  ok,
+  err,
+  isOk,
+  isErr,
+  isErrorCode,
+  isAccountNotFound,
+  isTxFailed,
+  isContractError,
+  assertOk,
+  SorokitErrorCode,
+} from "../shared/response";
+import type {
+  AccountNotFoundErrorCode,
+  ContractErrorCode,
+  SorokitErrorResult,
+  TxFailedErrorCode,
+} from "../shared/response";
 
 describe("shared/response", () => {
   describe("ok()", () => {
@@ -100,3 +117,97 @@ describe("assertOk()", () => {
     );
   });
 });
+
+describe("error-specific result type guards", () => {
+  describe("isAccountNotFound()", () => {
+    it("returns true for ACCOUNT_NOT_FOUND", () => {
+      const result = err(SorokitErrorCode.ACCOUNT_NOT_FOUND, "not found");
+      expect(isAccountNotFound(result)).toBe(true);
+    });
+
+    it("returns false for ok results and other error codes", () => {
+      expect(isAccountNotFound(ok(42))).toBe(false);
+      expect(
+        isAccountNotFound(err(SorokitErrorCode.ACCOUNT_FETCH_FAILED, "fetch failed")),
+      ).toBe(false);
+      expect(isAccountNotFound(err(SorokitErrorCode.TX_SUBMIT_FAILED, "tx failed"))).toBe(
+        false,
+      );
+    });
+
+    it("narrows to the error branch with ACCOUNT_NOT_FOUND code", () => {
+      const result = err<number>(SorokitErrorCode.ACCOUNT_NOT_FOUND, "not found");
+
+      if (isAccountNotFound(result)) {
+        expectTypeOf(result).toEqualTypeOf<SorokitErrorResult<AccountNotFoundErrorCode>>();
+        expectTypeOf(result.error.code).toEqualTypeOf<SorokitErrorCode.ACCOUNT_NOT_FOUND>();
+        expect(result.data).toBeNull();
+      }
+    });
+  });
+
+  describe("isTxFailed()", () => {
+    it.each([
+      SorokitErrorCode.TX_BUILD_FAILED,
+      SorokitErrorCode.TX_SIMULATE_FAILED,
+      SorokitErrorCode.TX_SUBMIT_FAILED,
+    ])("returns true for %s", (code) => {
+      expect(isTxFailed(err(code, "transaction failed"))).toBe(true);
+    });
+
+    it("returns false for ok results and non-transaction error codes", () => {
+      expect(isTxFailed(ok(42))).toBe(false);
+      expect(isTxFailed(err(SorokitErrorCode.TX_NOT_FOUND, "tx not found"))).toBe(false);
+      expect(isTxFailed(err(SorokitErrorCode.ACCOUNT_NOT_FOUND, "not found"))).toBe(false);
+      expect(isTxFailed(err(SorokitErrorCode.CONTRACT_INVOKE_FAILED, "contract"))).toBe(
+        false,
+      );
+    });
+
+    it("narrows to the error branch with transaction failure codes", () => {
+      const result = err<string>(SorokitErrorCode.TX_BUILD_FAILED, "build failed");
+
+      if (isTxFailed(result)) {
+        expectTypeOf(result).toEqualTypeOf<SorokitErrorResult<TxFailedErrorCode>>();
+        expectTypeOf(result.error.code).toEqualTypeOf<TxFailedErrorCode>();
+        expect(result.data).toBeNull();
+      }
+    });
+  });
+
+  describe("isContractError()", () => {
+    it.each([
+      SorokitErrorCode.CONTRACT_INVOKE_FAILED,
+      SorokitErrorCode.CONTRACT_READ_FAILED,
+      SorokitErrorCode.CONTRACT_PREPARE_FAILED,
+      SorokitErrorCode.CONTRACT_SIMULATE_FAILED,
+    ])("returns true for %s", (code) => {
+      expect(isContractError(err(code, "contract failed"))).toBe(true);
+    });
+
+    it("returns false for ok results and non-contract error codes", () => {
+      expect(isContractError(ok(42))).toBe(false);
+      expect(isContractError(err(SorokitErrorCode.TX_SUBMIT_FAILED, "tx failed"))).toBe(
+        false,
+      );
+      expect(isContractError(err(SorokitErrorCode.ACCOUNT_NOT_FOUND, "not found"))).toBe(
+        false,
+      );
+      expect(isContractError(err(SorokitErrorCode.NETWORK_ERROR, "network"))).toBe(false);
+    });
+
+    it("narrows to the error branch with contract error codes", () => {
+      const result = err<boolean>(
+        SorokitErrorCode.CONTRACT_SIMULATE_FAILED,
+        "simulate failed",
+      );
+
+      if (isContractError(result)) {
+        expectTypeOf(result).toEqualTypeOf<SorokitErrorResult<ContractErrorCode>>();
+        expectTypeOf(result.error.code).toEqualTypeOf<ContractErrorCode>();
+        expect(result.data).toBeNull();
+      }
+    });
+  });
+});
+