custom error types - closes #9

Author: ethanniser

.changeset/modern-regions-read.md

@@ -0,0 +1,5 @@
+---
+"@s2-dev/streamstore": patch
+---
+
+custom error types

.gitignore

@@ -32,3 +32,5 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
 # Finder (MacOS) folder config
 .DS_Store
+
+.claude

src/error.ts

@@ -8,51 +8,115 @@
 export class S2Error extends Error {
 	public readonly code?: string;
 	public readonly status?: number;
-	public readonly data?: Record<string, unknown>;
 
 	constructor({
 		message,
 		code,
 		status,
-		data,
 	}: {
-		/** Human-readable error message. */
 		message: string;
 		code?: string;
 		status?: number;
-		/** Additional error details when available. */
-		data?: Record<string, unknown>;
 	}) {
-		// Include full data in the error message for better visibility
-		const dataStr = data ? `\nData: ${JSON.stringify(data, null, 2)}` : "";
-		super(`${message}${dataStr}`);
+		super(message);
 		this.code = code;
 		this.status = status;
-		this.data = data;
 		this.name = "S2Error";
 	}
+}
+
+/**
+ * Thrown when an append operation fails due to a sequence number mismatch.
+ *
+ * This occurs when you specify a `matchSeqNum` condition in your append request,
+ * but the current tail sequence number of the stream doesn't match.
+ *
+ * The `expectedSeqNum` property contains the actual next sequence number
+ * that should be used for a successful append.
+ */
+export class SeqNumMismatchError extends S2Error {
+	/** The expected next sequence number for the stream. */
+	public readonly expectedSeqNum: number;
 
-	public toString() {
-		return `${this.message} (code: ${this.code}, status: ${this.status}, data: ${JSON.stringify(this.data, null, 2)})`;
+	constructor({
+		message,
+		code,
+		status,
+		expectedSeqNum,
+	}: {
+		message: string;
+		code?: string;
+		status?: number;
+		expectedSeqNum: number;
+	}) {
+		super({
+			message: `${message}\nExpected sequence number: ${expectedSeqNum}`,
+			code,
+			status,
+		});
+		this.name = "SeqNumMismatchError";
+		this.expectedSeqNum = expectedSeqNum;
 	}
+}
+
+/**
+ * Thrown when an append operation fails due to a fencing token mismatch.
+ *
+ * This occurs when you specify a `fencingToken` condition in your append request,
+ * but the current fencing token of the stream doesn't match.
+ *
+ * The `expectedFencingToken` property contains the actual fencing token
+ * that should be used for a successful append.
+ */
+export class FencingTokenMismatchError extends S2Error {
+	/** The expected fencing token for the stream. */
+	public readonly expectedFencingToken: string;
 
-	public toJSON() {
-		return {
-			message: this.message,
-			code: this.code,
-			status: this.status,
-			data: this.data,
-		};
+	constructor({
+		message,
+		code,
+		status,
+		expectedFencingToken,
+	}: {
+		message: string;
+		code?: string;
+		status?: number;
+		expectedFencingToken: string;
+	}) {
+		super({
+			message: `${message}\nExpected fencing token: ${expectedFencingToken}`,
+			code,
+			status,
+		});
+		this.name = "FencingTokenMismatchError";
+		this.expectedFencingToken = expectedFencingToken;
 	}
+}
 
-	public [Symbol.for("nodejs.util.inspect.custom")]() {
-		return {
-			name: "S2Error",
-			message: this.message,
-			code: this.code,
-			status: this.status,
-			data: this.data,
-			stack: this.stack,
-		};
+/**
+ * Thrown when a read operation fails because the requested position is beyond the stream tail.
+ *
+ * This occurs when you specify a `startSeqNum` that is greater than the current tail
+ * of the stream (HTTP 416 Range Not Satisfiable).
+ *
+ * To handle this gracefully, you can set `clamp: true` in your read options to
+ * automatically start from the tail instead of throwing an error.
+ */
+export class RangeNotSatisfiableError extends S2Error {
+	constructor({
+		message = "Range not satisfiable: requested position is beyond the stream tail. Use 'clamp: true' to start from the tail instead.",
+		code,
+		status = 416,
+	}: {
+		message?: string;
+		code?: string;
+		status?: number;
+	} = {}) {
+		super({
+			message,
+			code,
+			status,
+		});
+		this.name = "RangeNotSatisfiableError";
 	}
 }

src/index.ts

@@ -10,7 +10,12 @@ export type {
 	ListBasinsArgs,
 	ReconfigureBasinArgs,
 } from "./basins.js";
-export { S2Error } from "./error.js";
+export {
+	FencingTokenMismatchError,
+	RangeNotSatisfiableError,
+	S2Error,
+	SeqNumMismatchError,
+} from "./error.js";
 export type {
 	AccessTokenInfo,
 	AccessTokenScope,

src/stream.ts

@@ -1,5 +1,10 @@
 import type { S2RequestOptions } from "./common.js";
-import { S2Error } from "./error.js";
+import {
+	FencingTokenMismatchError,
+	RangeNotSatisfiableError,
+	S2Error,
+	SeqNumMismatchError,
+} from "./error.js";
 import type { Client } from "./generated/client/types.gen.js";
 import {
 	type AppendAck,
@@ -84,11 +89,8 @@ export class S2Stream {
 				});
 			} else {
 				// special case for 416 - Range Not Satisfiable
-				throw new S2Error({
-					message:
-						"Range not satisfiable: requested position is beyond the stream tail. Use 'clamp: true' to start from the tail instead.",
+				throw new RangeNotSatisfiableError({
 					status: response.response.status,
-					data: response.error,
 				});
 			}
 		}
@@ -199,12 +201,28 @@ export class S2Stream {
 					status: response.response.status,
 				});
 			} else {
-				// special case for 412
-				throw new S2Error({
-					message: "Append condition failed",
-					status: response.response.status,
-					data: response.error,
-				});
+				// special case for 412 - append condition failed
+				if ("seq_num_mismatch" in response.error) {
+					throw new SeqNumMismatchError({
+						message: "Append condition failed: sequence number mismatch",
+						code: "APPEND_CONDITION_FAILED",
+						status: response.response.status,
+						expectedSeqNum: response.error.seq_num_mismatch,
+					});
+				} else if ("fencing_token_mismatch" in response.error) {
+					throw new FencingTokenMismatchError({
+						message: "Append condition failed: fencing token mismatch",
+						code: "APPEND_CONDITION_FAILED",
+						status: response.response.status,
+						expectedFencingToken: response.error.fencing_token_mismatch,
+					});
+				} else {
+					// fallback for unknown 412 error format
+					throw new S2Error({
+						message: "Append condition failed",
+						status: response.response.status,
+					});
+				}
 			}
 		}
 		return response.data;
@@ -297,11 +315,8 @@ class ReadSession<
 				});
 			} else {
 				// special case for 416 - Range Not Satisfiable
-				throw new S2Error({
-					message:
-						"Range not satisfiable: requested position is beyond the stream tail. Use 'clamp: true' to start from the tail instead.",
+				throw new RangeNotSatisfiableError({
 					status: response.response.status,
-					data: response.error,
 				});
 			}
 		}