@vertz/fetch 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { EntityErrorType, FetchErrorType, Result as Result3 } from "@vertz/errors";
+import { err, isErr, isOk, matchError, ok, unwrap, unwrapOr } from "@vertz/errors";
+import { FetchError as BaseFetchError, Result } from "@vertz/errors";
 type AuthStrategy = {
 	type: "bearer";
 	token: string | (() => string | Promise<string>);
@@ -47,19 +50,39 @@ interface RequestOptions {
 	body?: unknown;
 	signal?: AbortSignal;
 }
-interface FetchResponse<T> {
+type FetchResponse<T> = Result<{
 	data: T;
 	status: number;
 	headers: Headers;
-}
+}, BaseFetchError>;
 interface StreamingRequestOptions extends RequestOptions {
 	format: StreamingFormat;
 }
+/** Paginated list response envelope returned by entity list endpoints. */
+interface ListResponse<T> {
+	items: T[];
+	total: number;
+	limit: number;
+	nextCursor: string | null;
+	hasNextPage: boolean;
+}
 declare class FetchClient {
 	private readonly config;
-	private readonly fetchFn;
+	/**
+	* Custom fetch provided via config, bound to globalThis.
+	* When not provided, globalThis.fetch is read at call time — this allows
+	* SSR handlers to patch globalThis.fetch for relative URL resolution
+	* without the client capturing a stale reference at construction time.
+	*/
+	private readonly customFetchFn;
 	constructor(config: FetchClientConfig);
+	private get fetchFn();
 	request<T>(method: string, path: string, options?: RequestOptions): Promise<FetchResponse<T>>;
+	get<T>(path: string, options?: RequestOptions): Promise<FetchResponse<T>>;
+	post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<FetchResponse<T>>;
+	put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<FetchResponse<T>>;
+	patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<FetchResponse<T>>;
+	delete<T>(path: string, options?: RequestOptions): Promise<FetchResponse<T>>;
 	requestStream<T>(options: StreamingRequestOptions & {
 		method: string;
 		path: string;
@@ -75,40 +98,56 @@ declare class FetchClient {
 	private applyStrategy;
 	private safeParseJSON;
 }
-declare class FetchError extends Error {
+import { FetchError, Result as Result2 } from "@vertz/errors";
+interface QueryDescriptor<
+	T,
+	E = FetchError
+> extends PromiseLike<Result2<T, E>> {
+	readonly _tag: "QueryDescriptor";
+	readonly _key: string;
+	readonly _fetch: () => Promise<Result2<T, E>>;
+	/** Phantom field to carry the error type through generics. Never set at runtime. */
+	readonly _error?: E;
+}
+declare function isQueryDescriptor<
+	T,
+	E = FetchError
+>(value: unknown): value is QueryDescriptor<T, E>;
+declare function createDescriptor<T>(method: string, path: string, fetchFn: () => Promise<FetchResponse<T>>, query?: Record<string, unknown>): QueryDescriptor<T>;
+declare class FetchError2 extends Error {
 	readonly status: number;
 	readonly body?: unknown;
 	constructor(message: string, status: number, body?: unknown);
 }
-declare class BadRequestError extends FetchError {
+declare class BadRequestError extends FetchError2 {
 	constructor(message: string, body?: unknown);
 }
-declare class UnauthorizedError extends FetchError {
+declare class UnauthorizedError extends FetchError2 {
 	constructor(message: string, body?: unknown);
 }
-declare class ForbiddenError extends FetchError {
+declare class ForbiddenError extends FetchError2 {
 	constructor(message: string, body?: unknown);
 }
-declare class NotFoundError extends FetchError {
+declare class NotFoundError extends FetchError2 {
 	constructor(message: string, body?: unknown);
 }
-declare class ConflictError extends FetchError {
+declare class ConflictError extends FetchError2 {
 	constructor(message: string, body?: unknown);
 }
-declare class GoneError extends FetchError {
+declare class GoneError extends FetchError2 {
 	constructor(message: string, body?: unknown);
 }
-declare class UnprocessableEntityError extends FetchError {
+declare class UnprocessableEntityError extends FetchError2 {
 	constructor(message: string, body?: unknown);
 }
-declare class RateLimitError extends FetchError {
+declare class RateLimitError extends FetchError2 {
 	constructor(message: string, body?: unknown);
 }
-declare class InternalServerError extends FetchError {
+declare class InternalServerError extends FetchError2 {
 	constructor(message: string, body?: unknown);
 }
-declare class ServiceUnavailableError extends FetchError {
+declare class ServiceUnavailableError extends FetchError2 {
 	constructor(message: string, body?: unknown);
 }
-declare function createErrorFromStatus(status: number, message: string, body?: unknown): FetchError;
-export { createErrorFromStatus, UnprocessableEntityError, UnauthorizedError, StreamingRequestOptions, StreamingFormat, ServiceUnavailableError, RetryConfig, RequestOptions, RateLimitError, NotFoundError, InternalServerError, HooksConfig, GoneError, ForbiddenError, FetchResponse, FetchError, FetchClientConfig, FetchClient, ConflictError, BadRequestError, AuthStrategy };
+declare function createErrorFromStatus(status: number, message: string, body?: unknown): FetchError2;
+export { unwrapOr, unwrap, ok, matchError, isQueryDescriptor, isOk, isErr, err, createErrorFromStatus, createDescriptor, UnprocessableEntityError, UnauthorizedError, StreamingRequestOptions, StreamingFormat, ServiceUnavailableError, RetryConfig, Result3 as Result, RequestOptions, RateLimitError, QueryDescriptor, NotFoundError, ListResponse, InternalServerError, HooksConfig, GoneError, ForbiddenError, FetchResponse, FetchErrorType, FetchError2 as FetchError, FetchClientConfig, FetchClient, EntityErrorType, ConflictError, BadRequestError, AuthStrategy };

package/dist/index.js

@@ -1,162 +1,128 @@
-// src/errors.ts
-class FetchError extends Error {
-  status;
-  body;
-  constructor(message, status, body) {
-    super(message);
-    this.name = "FetchError";
-    this.status = status;
-    this.body = body;
-  }
-}
-
-class BadRequestError extends FetchError {
-  constructor(message, body) {
-    super(message, 400, body);
-    this.name = "BadRequestError";
-  }
-}
-
-class UnauthorizedError extends FetchError {
-  constructor(message, body) {
-    super(message, 401, body);
-    this.name = "UnauthorizedError";
-  }
-}
-
-class ForbiddenError extends FetchError {
-  constructor(message, body) {
-    super(message, 403, body);
-    this.name = "ForbiddenError";
-  }
-}
-
-class NotFoundError extends FetchError {
-  constructor(message, body) {
-    super(message, 404, body);
-    this.name = "NotFoundError";
-  }
-}
-
-class ConflictError extends FetchError {
-  constructor(message, body) {
-    super(message, 409, body);
-    this.name = "ConflictError";
-  }
-}
-
-class GoneError extends FetchError {
-  constructor(message, body) {
-    super(message, 410, body);
-    this.name = "GoneError";
-  }
-}
-
-class UnprocessableEntityError extends FetchError {
-  constructor(message, body) {
-    super(message, 422, body);
-    this.name = "UnprocessableEntityError";
-  }
-}
-
-class RateLimitError extends FetchError {
-  constructor(message, body) {
-    super(message, 429, body);
-    this.name = "RateLimitError";
-  }
-}
-
-class InternalServerError extends FetchError {
-  constructor(message, body) {
-    super(message, 500, body);
-    this.name = "InternalServerError";
-  }
-}
-
-class ServiceUnavailableError extends FetchError {
-  constructor(message, body) {
-    super(message, 503, body);
-    this.name = "ServiceUnavailableError";
-  }
-}
-var errorMap = {
-  400: BadRequestError,
-  401: UnauthorizedError,
-  403: ForbiddenError,
-  404: NotFoundError,
-  409: ConflictError,
-  410: GoneError,
-  422: UnprocessableEntityError,
-  429: RateLimitError,
-  500: InternalServerError,
-  503: ServiceUnavailableError
-};
-function createErrorFromStatus(status, message, body) {
-  const ErrorClass = errorMap[status];
-  if (ErrorClass) {
-    return new ErrorClass(message, body);
-  }
-  return new FetchError(message, status, body);
-}
+// src/index.ts
+import { err as err2, isErr, isOk, matchError, ok as ok3, unwrap, unwrapOr } from "@vertz/errors";
 
 // src/client.ts
+import {
+  createHttpError,
+  err,
+  FetchNetworkError,
+  FetchTimeoutError,
+  FetchValidationError,
+  ok,
+  ParseError
+} from "@vertz/errors";
 var DEFAULT_RETRY_ON = [429, 500, 502, 503, 504];
 
 class FetchClient {
   config;
-  fetchFn;
+  customFetchFn;
   constructor(config) {
     this.config = config;
-    this.fetchFn = config.fetch ?? globalThis.fetch;
+    this.customFetchFn = config.fetch ? config.fetch.bind(globalThis) : null;
+  }
+  get fetchFn() {
+    return this.customFetchFn ?? globalThis.fetch.bind(globalThis);
   }
   async request(method, path, options) {
-    const retryConfig = this.resolveRetryConfig();
-    let lastError;
-    for (let attempt = 0;attempt <= retryConfig.retries; attempt++) {
-      if (attempt > 0) {
-        const delay = this.calculateBackoff(attempt, retryConfig);
-        await this.sleep(delay);
-      }
-      const url = this.buildURL(path, options?.query);
-      const headers = new Headers(this.config.headers);
-      if (options?.headers) {
-        for (const [key, value] of Object.entries(options.headers)) {
-          headers.set(key, value);
+    try {
+      const retryConfig = this.resolveRetryConfig();
+      let lastError;
+      for (let attempt = 0;attempt <= retryConfig.retries; attempt++) {
+        if (attempt > 0) {
+          const delay = this.calculateBackoff(attempt, retryConfig);
+          await this.sleep(delay);
         }
+        const url = this.buildURL(path, options?.query);
+        const headers = new Headers(this.config.headers);
+        if (options?.headers) {
+          for (const [key, value] of Object.entries(options.headers)) {
+            headers.set(key, value);
+          }
+        }
+        const signal = this.buildSignal(options?.signal);
+        const isRelativeUrl = url.startsWith("/");
+        const requestUrl = isRelativeUrl ? `http://localhost${url}` : url;
+        const serializedBody = options?.body !== undefined ? JSON.stringify(options.body) : undefined;
+        const request = new Request(requestUrl, {
+          method,
+          headers,
+          body: serializedBody,
+          signal
+        });
+        if (options?.body !== undefined) {
+          request.headers.set("Content-Type", "application/json");
+        }
+        const authedRequest = await this.applyAuth(request);
+        await this.config.hooks?.beforeRequest?.(authedRequest);
+        const response = isRelativeUrl ? await this.fetchFn(url, {
+          method: authedRequest.method,
+          headers: authedRequest.headers,
+          body: serializedBody,
+          signal: authedRequest.signal
+        }) : await this.fetchFn(authedRequest);
+        if (!response.ok) {
+          const body = await this.safeParseJSON(response);
+          let serverCode;
+          if (body && typeof body === "object" && "error" in body) {
+            const errorObj = body.error;
+            if (errorObj && typeof errorObj.code === "string") {
+              serverCode = errorObj.code;
+            }
+            if (errorObj?.code === "ValidationError" && Array.isArray(errorObj.errors)) {
+              return err(new FetchValidationError("Validation failed", errorObj.errors));
+            }
+          }
+          const httpError = createHttpError(response.status, response.statusText, serverCode);
+          if (attempt < retryConfig.retries && retryConfig.retryOn.includes(response.status)) {
+            lastError = httpError;
+            await this.config.hooks?.beforeRetry?.(attempt + 1, httpError);
+            continue;
+          }
+          await this.config.hooks?.onError?.(httpError);
+          return err(httpError);
+        }
+        await this.config.hooks?.afterResponse?.(response);
+        if (response.status === 204 || response.status === 205) {
+          return ok({ data: undefined, status: response.status, headers: response.headers });
+        }
+        let data;
+        try {
+          data = await response.json();
+        } catch (parseError) {
+          return err(new ParseError("", "Failed to parse response JSON", parseError));
+        }
+        return ok({
+          data,
+          status: response.status,
+          headers: response.headers
+        });
       }
-      const signal = this.buildSignal(options?.signal);
-      const request = new Request(url, {
-        method,
-        headers,
-        body: options?.body !== undefined ? JSON.stringify(options.body) : undefined,
-        signal
-      });
-      if (options?.body !== undefined) {
-        request.headers.set("Content-Type", "application/json");
-      }
-      const authedRequest = await this.applyAuth(request);
-      await this.config.hooks?.beforeRequest?.(authedRequest);
-      const response = await this.fetchFn(authedRequest);
-      if (!response.ok) {
-        const body = await this.safeParseJSON(response);
-        const error = createErrorFromStatus(response.status, response.statusText, body);
-        if (attempt < retryConfig.retries && retryConfig.retryOn.includes(response.status)) {
-          lastError = error;
-          await this.config.hooks?.beforeRetry?.(attempt + 1, error);
-          continue;
+      return err(lastError ?? new FetchNetworkError("All retries exhausted"));
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        const abortSignal = error instanceof DOMException ? error.cause : error;
+        if (abortSignal instanceof Error && abortSignal.name === "TimeoutError") {
+          return err(new FetchTimeoutError);
         }
-        await this.config.hooks?.onError?.(error);
-        throw error;
+        return err(new FetchNetworkError("Request aborted"));
       }
-      await this.config.hooks?.afterResponse?.(response);
-      const data = await response.json();
-      return {
-        data,
-        status: response.status,
-        headers: response.headers
-      };
+      return err(new FetchNetworkError("Network request failed"));
     }
-    throw lastError;
+  }
+  async get(path, options) {
+    return this.request("GET", path, options);
+  }
+  async post(path, body, options) {
+    return this.request("POST", path, { ...options, body });
+  }
+  async put(path, body, options) {
+    return this.request("PUT", path, { ...options, body });
+  }
+  async patch(path, body, options) {
+    return this.request("PATCH", path, { ...options, body });
+  }
+  async delete(path, options) {
+    return this.request("DELETE", path, options);
   }
   async* requestStream(options) {
     const url = this.buildURL(options.path, options.query);
@@ -172,20 +138,35 @@ class FetchClient {
       headers.set("Accept", "application/x-ndjson");
     }
     const signal = this.buildSignal(options.signal);
-    const request = new Request(url, {
+    const isRelativeUrl = url.startsWith("/");
+    const requestUrl = isRelativeUrl ? `http://localhost${url}` : url;
+    const serializedBody = options.body !== undefined ? JSON.stringify(options.body) : undefined;
+    const request = new Request(requestUrl, {
       method: options.method,
       headers,
-      body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+      body: serializedBody,
       signal
     });
     const authedRequest = await this.applyAuth(request);
     await this.config.hooks?.beforeRequest?.(authedRequest);
-    const response = await this.fetchFn(authedRequest);
+    const response = isRelativeUrl ? await this.fetchFn(url, {
+      method: authedRequest.method,
+      headers: authedRequest.headers,
+      body: serializedBody,
+      signal: authedRequest.signal
+    }) : await this.fetchFn(authedRequest);
     if (!response.ok) {
       const body = await this.safeParseJSON(response);
-      const error = createErrorFromStatus(response.status, response.statusText, body);
-      await this.config.hooks?.onError?.(error);
-      throw error;
+      let serverCode;
+      if (body && typeof body === "object" && "error" in body) {
+        const errorObj = body.error;
+        if (errorObj && typeof errorObj.code === "string") {
+          serverCode = errorObj.code;
+        }
+      }
+      const httpError = createHttpError(response.status, response.statusText, serverCode);
+      await this.config.hooks?.onError?.(httpError);
+      throw httpError;
     }
     if (!response.body) {
       return;
@@ -290,15 +271,32 @@ class FetchClient {
   }
   buildURL(path, query) {
     const base = this.config.baseURL;
-    const url = base ? new URL(path, base) : new URL(path);
+    const isAbsoluteBase = base && /^https?:\/\//.test(base);
+    let urlString;
+    if (base && isAbsoluteBase) {
+      const relativePath = path.startsWith("/") ? path.slice(1) : path;
+      const normalizedBase = base.endsWith("/") ? base : `${base}/`;
+      urlString = new URL(relativePath, normalizedBase).toString();
+    } else if (base) {
+      const normalizedBase = base.endsWith("/") ? base.slice(0, -1) : base;
+      const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+      urlString = `${normalizedBase}${normalizedPath}`;
+    } else {
+      urlString = path;
+    }
     if (query) {
+      const params = new URLSearchParams;
       for (const [key, value] of Object.entries(query)) {
         if (value !== undefined && value !== null) {
-          url.searchParams.set(key, String(value));
+          params.set(key, String(value));
         }
       }
+      const qs = params.toString();
+      if (qs) {
+        urlString += `${urlString.includes("?") ? "&" : "?"}${qs}`;
+      }
     }
-    return url.toString();
+    return urlString;
   }
   async applyAuth(request) {
     const strategies = this.config.authStrategies;
@@ -346,8 +344,152 @@ class FetchClient {
     }
   }
 }
+// src/descriptor.ts
+import { ok as ok2 } from "@vertz/errors";
+function isQueryDescriptor(value) {
+  return value !== null && typeof value === "object" && "_tag" in value && value._tag === "QueryDescriptor";
+}
+function createDescriptor(method, path, fetchFn, query) {
+  const key = `${method}:${path}${serializeQuery(query)}`;
+  const fetchResult = async () => {
+    const response = await fetchFn();
+    if (!response.ok)
+      return response;
+    return ok2(response.data.data);
+  };
+  return {
+    _tag: "QueryDescriptor",
+    _key: key,
+    _fetch: fetchResult,
+    then(onFulfilled, onRejected) {
+      return fetchResult().then(onFulfilled, onRejected);
+    }
+  };
+}
+function serializeQuery(query) {
+  if (!query)
+    return "";
+  const params = new URLSearchParams;
+  for (const key of Object.keys(query).sort()) {
+    const value = query[key];
+    if (value !== undefined && value !== null) {
+      params.set(key, String(value));
+    }
+  }
+  const str = params.toString();
+  return str ? `?${str}` : "";
+}
+// src/errors.ts
+class FetchError extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.name = "FetchError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+class BadRequestError extends FetchError {
+  constructor(message, body) {
+    super(message, 400, body);
+    this.name = "BadRequestError";
+  }
+}
+
+class UnauthorizedError extends FetchError {
+  constructor(message, body) {
+    super(message, 401, body);
+    this.name = "UnauthorizedError";
+  }
+}
+
+class ForbiddenError extends FetchError {
+  constructor(message, body) {
+    super(message, 403, body);
+    this.name = "ForbiddenError";
+  }
+}
+
+class NotFoundError extends FetchError {
+  constructor(message, body) {
+    super(message, 404, body);
+    this.name = "NotFoundError";
+  }
+}
+
+class ConflictError extends FetchError {
+  constructor(message, body) {
+    super(message, 409, body);
+    this.name = "ConflictError";
+  }
+}
+
+class GoneError extends FetchError {
+  constructor(message, body) {
+    super(message, 410, body);
+    this.name = "GoneError";
+  }
+}
+
+class UnprocessableEntityError extends FetchError {
+  constructor(message, body) {
+    super(message, 422, body);
+    this.name = "UnprocessableEntityError";
+  }
+}
+
+class RateLimitError extends FetchError {
+  constructor(message, body) {
+    super(message, 429, body);
+    this.name = "RateLimitError";
+  }
+}
+
+class InternalServerError extends FetchError {
+  constructor(message, body) {
+    super(message, 500, body);
+    this.name = "InternalServerError";
+  }
+}
+
+class ServiceUnavailableError extends FetchError {
+  constructor(message, body) {
+    super(message, 503, body);
+    this.name = "ServiceUnavailableError";
+  }
+}
+var errorMap = {
+  400: BadRequestError,
+  401: UnauthorizedError,
+  403: ForbiddenError,
+  404: NotFoundError,
+  409: ConflictError,
+  410: GoneError,
+  422: UnprocessableEntityError,
+  429: RateLimitError,
+  500: InternalServerError,
+  503: ServiceUnavailableError
+};
+function createErrorFromStatus(status, message, body) {
+  const ErrorClass = errorMap[status];
+  if (ErrorClass) {
+    return new ErrorClass(message, body);
+  }
+  return new FetchError(message, status, body);
+}
 export {
+  unwrapOr,
+  unwrap,
+  ok3 as ok,
+  matchError,
+  isQueryDescriptor,
+  isOk,
+  isErr,
+  err2 as err,
   createErrorFromStatus,
+  createDescriptor,
   UnprocessableEntityError,
   UnauthorizedError,
   ServiceUnavailableError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertz/fetch",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "description": "Type-safe HTTP client for Vertz",
@@ -24,6 +24,9 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "@vertz/errors": "workspace:*"
+  },
   "scripts": {
     "build": "bunup",
     "test": "vitest run",
@@ -31,7 +34,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^25.3.1",
     "@vitest/coverage-v8": "^4.0.18",
     "bunup": "latest",
     "typescript": "^5.7.0",