@viliaapro/apifetch 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# apifetch
+
+A typed fetch wrapper with [Standard Schema](https://github.com/standard-schema/standard-schema) validation and status-code dispatch.
+
+## Philosophy
+
+HTTP responses fall into two categories:
+
+- **User errors** are expected outcomes — a 404, a 422, a 401. These are part of the API contract and should be handled as returned values, not exceptions. The caller defines a schema and transform for each status code they care about.
+- **Computer errors** are unexpected failures — the server returned a status code the client has no handler for, or the response body didn't match the expected schema. These indicate a bug or a contract violation and should throw exceptions.
+
+This means `apiFetch` never throws for non-ok responses. A 422 Unprocessable Content is not an exception — it's a value you handle. Only truly unexpected situations — unrecognized status codes and malformed response bodies — throw.
+
+## Installation
+
+```bash
+npm install @viliaapro/apifetch @standard-schema/spec http-status-codes zod
+```
+
+## Usage
+
+```typescript
+import { apiFetch } from 'apifetch';
+import { StatusCodes } from 'http-status-codes';
+import { z } from 'zod';
+
+const UserSchema = z.object({ id: z.number(), name: z.string() });
+const ErrorSchema = z.object({ message: z.string() });
+
+const result = await apiFetch('/api/users/1', {
+  [StatusCodes.OK]: {
+    schema: UserSchema,
+    transform: (user) => ({ kind: 'ok' as const, user }),
+  },
+  [StatusCodes.NOT_FOUND]: {
+    schema: ErrorSchema,
+    transform: (error) => ({ kind: 'not_found' as const, error }),
+  },
+  [StatusCodes.UNPROCESSABLE_ENTITY]: {
+    schema: ErrorSchema,
+    transform: (error) => ({ kind: 'invalid' as const, error }),
+  },
+});
+
+switch (result.kind) {
+  case 'ok':        return result.user;
+  case 'not_found': return null;
+  case 'invalid':   return showErrors(result.error);
+}
+```
+
+## Schema agnostic
+
+`apiFetch` accepts any [Standard Schema](https://github.com/standard-schema/standard-schema) compliant validator — Zod, Valibot, ArkType, or any other compliant library.
+
+## Errors
+
+Two exceptions are thrown, both extending `ApiError`:
+
+- **`UnrecognizedStatusError`** — the server returned a status code with no registered handler
+- **`MalformedResponseError`** — the response body failed schema validation; carries `issues` with the validation details
+
+Both carry the original `Response` object and a `status` convenience getter.
+
+```typescript
+import { UnrecognizedStatusError, MalformedResponseError } from 'apifetch';
+
+try {
+  const result = await apiFetch('/api/users/1', handlers);
+} catch (err) {
+  if (err instanceof MalformedResponseError) {
+    console.error(err.status, err.issues);
+  }
+  if (err instanceof UnrecognizedStatusError) {
+    console.error(err.status);
+  }
+}
+```
+
+## API
+
+### `apiFetch<R>(url, handlers, options?)`
+
+| Parameter  | Type                  | Description                        |
+|------------|-----------------------|------------------------------------|
+| `url`      | `string`              | Request URL                        |
+| `handlers` | `ResponseHandlers<R>` | Map of status codes to handlers    |
+| `options`  | `RequestInit`         | Standard fetch options (optional)  |
+
+Returns `Promise<R>` where `R` is inferred from the transform return types.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,24 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+type StatusHandler<S extends StandardSchemaV1, R> = {
+    schema: S;
+    transform: (value: StandardSchemaV1.InferOutput<S>) => R;
+};
+type ResponseHandlers<R> = {
+    [S in number]?: StatusHandler<StandardSchemaV1, R>;
+};
+declare class ApiError extends Error {
+    readonly response?: Response | undefined;
+    get status(): number | undefined;
+    constructor(message: string, response?: Response | undefined, options?: ErrorOptions);
+}
+declare class UnrecognizedStatusError extends ApiError {
+    constructor(response: Response);
+}
+declare class MalformedResponseError extends ApiError {
+    readonly issues: readonly StandardSchemaV1.Issue[];
+    constructor(response: Response, issues: readonly StandardSchemaV1.Issue[]);
+}
+declare function apiFetch<R>(url: string, handlers: ResponseHandlers<R>, options?: RequestInit): Promise<R>;
+
+export { ApiError, MalformedResponseError, type ResponseHandlers, type StatusHandler, UnrecognizedStatusError, apiFetch };

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+type StatusHandler<S extends StandardSchemaV1, R> = {
+    schema: S;
+    transform: (value: StandardSchemaV1.InferOutput<S>) => R;
+};
+type ResponseHandlers<R> = {
+    [S in number]?: StatusHandler<StandardSchemaV1, R>;
+};
+declare class ApiError extends Error {
+    readonly response?: Response | undefined;
+    get status(): number | undefined;
+    constructor(message: string, response?: Response | undefined, options?: ErrorOptions);
+}
+declare class UnrecognizedStatusError extends ApiError {
+    constructor(response: Response);
+}
+declare class MalformedResponseError extends ApiError {
+    readonly issues: readonly StandardSchemaV1.Issue[];
+    constructor(response: Response, issues: readonly StandardSchemaV1.Issue[]);
+}
+declare function apiFetch<R>(url: string, handlers: ResponseHandlers<R>, options?: RequestInit): Promise<R>;
+
+export { ApiError, MalformedResponseError, type ResponseHandlers, type StatusHandler, UnrecognizedStatusError, apiFetch };

package/dist/index.js

@@ -0,0 +1,72 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ApiError: () => ApiError,
+  MalformedResponseError: () => MalformedResponseError,
+  UnrecognizedStatusError: () => UnrecognizedStatusError,
+  apiFetch: () => apiFetch
+});
+module.exports = __toCommonJS(index_exports);
+var ApiError = class extends Error {
+  constructor(message, response, options) {
+    super(message, options);
+    this.response = response;
+    this.name = this.constructor.name;
+  }
+  get status() {
+    return this.response?.status;
+  }
+};
+var UnrecognizedStatusError = class extends ApiError {
+  constructor(response) {
+    super(`Unrecognized status code: ${response.status}`, response);
+  }
+};
+var MalformedResponseError = class extends ApiError {
+  constructor(response, issues) {
+    super(`Malformed response body for status: ${response.status}`, response);
+    this.issues = issues;
+  }
+};
+async function apiFetch(url, handlers, options = {}) {
+  const response = await fetch(url, {
+    ...options,
+    headers: { "Content-Type": "application/json", ...options.headers }
+  });
+  const handler = handlers[response.status];
+  if (!handler) {
+    throw new UnrecognizedStatusError(response);
+  }
+  const body = await response.json();
+  const result = await handler.schema["~standard"].validate(body);
+  if (result.issues) {
+    throw new MalformedResponseError(response, result.issues);
+  }
+  return handler.transform(result.value);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiError,
+  MalformedResponseError,
+  UnrecognizedStatusError,
+  apiFetch
+});

package/dist/index.mjs

@@ -0,0 +1,44 @@
+// src/index.ts
+var ApiError = class extends Error {
+  constructor(message, response, options) {
+    super(message, options);
+    this.response = response;
+    this.name = this.constructor.name;
+  }
+  get status() {
+    return this.response?.status;
+  }
+};
+var UnrecognizedStatusError = class extends ApiError {
+  constructor(response) {
+    super(`Unrecognized status code: ${response.status}`, response);
+  }
+};
+var MalformedResponseError = class extends ApiError {
+  constructor(response, issues) {
+    super(`Malformed response body for status: ${response.status}`, response);
+    this.issues = issues;
+  }
+};
+async function apiFetch(url, handlers, options = {}) {
+  const response = await fetch(url, {
+    ...options,
+    headers: { "Content-Type": "application/json", ...options.headers }
+  });
+  const handler = handlers[response.status];
+  if (!handler) {
+    throw new UnrecognizedStatusError(response);
+  }
+  const body = await response.json();
+  const result = await handler.schema["~standard"].validate(body);
+  if (result.issues) {
+    throw new MalformedResponseError(response, result.issues);
+  }
+  return handler.transform(result.value);
+}
+export {
+  ApiError,
+  MalformedResponseError,
+  UnrecognizedStatusError,
+  apiFetch
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@viliaapro/apifetch",
+  "version": "0.1.0",
+  "description": "A typed fetch wrapper with Standard Schema validation and status-code dispatch",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch"
+  },
+  "peerDependencies": {
+    "@standard-schema/spec": "^1.0.0"
+  },
+  "devDependencies": {
+    "@standard-schema/spec": "^1.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "fetch",
+    "typescript",
+    "standard-schema",
+    "http",
+    "api",
+    "rest"
+  ],
+  "license": "MIT"
+}