@jsonapi-serde/integration-koa 0.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2025-present, Ben Scholzen 'DASPRiD'
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,22 @@
+# JSON:API Serde - Koa Integration
+
+[![Test](https://github.com/DASPRiD/jsonapi-serde-js/actions/workflows/test.yml/badge.svg)](https://github.com/DASPRiD/jsonapi-serde-js/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/DASPRiD/jsonapi-serde-js/graph/badge.svg?token=UfRUzGqiN3)](https://codecov.io/gh/DASPRiD/jsonapi-serde-js)
+
+---
+
+Koa integration for [@jsonapi-serde/server](https://github.com/dasprid/jsonapi-serde-js).
+
+## Documentation
+
+To check out docs, visit [jsonapi-serde.js.org](https://jsonapi-serde.js.org).
+
+## Changelog
+
+Detailed changes for each release are documented in the [CHANGELOG](https://github.com/dasprid/jsonapi-serde-js/blob/main/packages/integration/koa/CHANGELOG.md)
+
+## License
+
+[BSD-3-Clause](https://github.com/dasprid/jsonapi-serde-js/blob/main/LICENSE)
+
+Copyright (c) 2025-present, Ben Scholzen 'DASPRiD'

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./middleware.js";
+export * from "./response.js";
+export * from "./tree-router.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./middleware.js";
+export * from "./response.js";
+export * from "./tree-router.js";

package/dist/middleware.d.ts

@@ -0,0 +1,33 @@
+import { type JsonApiMediaType } from "@jsonapi-serde/server/http";
+import type { Middleware } from "koa";
+/**
+ * The Koa state shape extended with JSON:API parsing metadata
+ */
+export type JsonApiContextState = {
+    jsonApi: {
+        /**
+         * List of acceptable JSON:API media types parsed from the `Accept` header
+         */
+        acceptableTypes: JsonApiMediaType[];
+    };
+};
+/**
+ * Middleware that parses and validates the `Accept` header for JSON:API media types
+ *
+ * On success, adds `acceptableTypes` to `ctx.state.jsonApi`.
+ * On failure, responds with HTTP 400 and a JSON:API error document.
+ */
+export declare const jsonApiRequestMiddleware: () => Middleware<Partial<JsonApiContextState>>;
+type ErrorMiddlewareOptions = {
+    /**
+     * Optional error logger callback
+     */
+    logError?: (error: unknown, exposed: boolean) => void;
+};
+/**
+ * Middleware to catch errors thrown during request handling and respond with JSON:API-compliant error documents
+ *
+ * Supports optional error logging via the `logError` callback.
+ */
+export declare const jsonApiErrorMiddleware: (options?: ErrorMiddlewareOptions) => Middleware;
+export {};

package/dist/middleware.js

@@ -0,0 +1,107 @@
+import { JsonApiError } from "@jsonapi-serde/server/common";
+import { MediaTypeParserError, getAcceptableMediaTypes, } from "@jsonapi-serde/server/http";
+import { isHttpError } from "http-errors";
+/**
+ * Middleware that parses and validates the `Accept` header for JSON:API media types
+ *
+ * On success, adds `acceptableTypes` to `ctx.state.jsonApi`.
+ * On failure, responds with HTTP 400 and a JSON:API error document.
+ */
+export const jsonApiRequestMiddleware = () => {
+    return async (context, next) => {
+        try {
+            context.state.jsonApi = {
+                acceptableTypes: getAcceptableMediaTypes(context.get("Accept")),
+            };
+        }
+        catch (error) {
+            /* node:coverage disable */
+            if (!(error instanceof MediaTypeParserError)) {
+                throw error;
+            }
+            /* node:coverage enable */
+            const document = new JsonApiError({
+                status: "400",
+                code: "bad_request",
+                title: "Bad Request",
+                detail: error.message,
+                source: {
+                    header: "accept",
+                },
+            }).toDocument();
+            context.set("Content-Type", document.getContentType());
+            context.status = document.getStatus();
+            context.body = document.getBody();
+            return;
+        }
+        return next();
+    };
+};
+/**
+ * Maps various error types to a JSON:API error object
+ *
+ * Determines if the error details can be safely exposed to clients.
+ */
+const getJsonApiError = (error) => {
+    if (isHttpError(error) && error.expose) {
+        return [
+            new JsonApiError({
+                status: error.status.toString(),
+                code: error.name
+                    .replace(/Error$/, "")
+                    .replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)
+                    .replace(/^_+|_+$/g, ""),
+                title: error.message,
+            }),
+            true,
+        ];
+    }
+    if (error instanceof Error &&
+        "status" in error &&
+        typeof error.status === "number" &&
+        error.status >= 400 &&
+        error.status < 500) {
+        return [
+            new JsonApiError({
+                status: error.status.toString(),
+                code: error.name
+                    .replace(/Error$/, "")
+                    .replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)
+                    .replace(/^_+|_+$/g, ""),
+                title: error.message,
+            }),
+            true,
+        ];
+    }
+    if (error instanceof JsonApiError) {
+        return [error, error.status < 500];
+    }
+    return [
+        new JsonApiError({
+            status: "500",
+            code: "internal_server_error",
+            title: "Internal Server Error",
+        }),
+        false,
+    ];
+};
+/**
+ * Middleware to catch errors thrown during request handling and respond with JSON:API-compliant error documents
+ *
+ * Supports optional error logging via the `logError` callback.
+ */
+export const jsonApiErrorMiddleware = (options) => {
+    return async (context, next) => {
+        try {
+            await next();
+        }
+        catch (error) {
+            const [jsonApiError, exposed] = getJsonApiError(error);
+            options?.logError?.(error, exposed);
+            const document = jsonApiError.toDocument();
+            context.set("Content-Type", document.getContentType());
+            context.status = document.getStatus();
+            context.body = document.getBody();
+        }
+    };
+};

package/dist/request.d.ts

@@ -0,0 +1,26 @@
+import type { BodyContext } from "@jsonapi-serde/server/request";
+import type { Context as KoaContext } from "koa";
+type BodyParserKoaContext = KoaContext & {
+    request: {
+        body?: unknown;
+    };
+};
+/**
+ * Extracts a `BodyContext` from a Koa context for JSON:API request parsing
+ *
+ * This function reads the request body and content-type header from the Koa context and validates that the body is
+ * either a string or an object.
+ *
+ * @throws {Error} If the body is neither a string nor a non-null object.
+ *
+ * @example
+ * ```ts
+ * import { bodyContext } from "@jsonapi-serde/koa";
+ *
+ * app.use(async (ctx, next) => {
+ *   const context = bodyContext(ctx);
+ * });
+ * ```
+ */
+export declare const bodyContext: (koaContext: BodyParserKoaContext) => BodyContext;
+export {};

package/dist/request.js

@@ -0,0 +1,27 @@
+/**
+ * Extracts a `BodyContext` from a Koa context for JSON:API request parsing
+ *
+ * This function reads the request body and content-type header from the Koa context and validates that the body is
+ * either a string or an object.
+ *
+ * @throws {Error} If the body is neither a string nor a non-null object.
+ *
+ * @example
+ * ```ts
+ * import { bodyContext } from "@jsonapi-serde/koa";
+ *
+ * app.use(async (ctx, next) => {
+ *   const context = bodyContext(ctx);
+ * });
+ * ```
+ */
+export const bodyContext = (koaContext) => {
+    const body = koaContext.request.body;
+    if ((typeof body !== "string" && typeof body !== "object") || body === null) {
+        throw new Error("Body must either be a string or an object");
+    }
+    return {
+        body: body,
+        contentType: koaContext.get("Content-Type"),
+    };
+};

package/dist/response.d.ts

@@ -0,0 +1,26 @@
+import type { JsonApiDocument } from "@jsonapi-serde/server/common";
+import type { ParameterizedContext } from "koa";
+import type { JsonApiContextState } from "./middleware.js";
+/**
+ * Sends a JSON:API response using the given Koa context and JSON:API document
+ *
+ * This function sets the HTTP status, response body, and content-type headers according to the provided JSON:API
+ * document. It also verifies that the client's Accept header matches the media types supported by the document.
+ *
+ * The function requires that the `jsonApiRequestMiddleware` has been registered on the Koa app to populate
+ * `context.state.jsonApi` with the acceptable media types.
+ *
+ * @throws {JsonApiError} when the document's media type is not acceptable by the client.
+ *
+ * @example
+ * ```ts
+ * import { sendJsonApiResponse } from "./response";
+ * import { jsonApiRequestMiddleware } from "./middleware";
+ *
+ * app.use(async (context) => {
+ *   const document = {}; // Serialized document
+ *   sendJsonApiResponse(context, document);
+ * });
+ * ```
+ */
+export declare const sendJsonApiResponse: (context: ParameterizedContext<Partial<JsonApiContextState>>, document: JsonApiDocument) => void;

package/dist/response.js

@@ -0,0 +1,31 @@
+/**
+ * Sends a JSON:API response using the given Koa context and JSON:API document
+ *
+ * This function sets the HTTP status, response body, and content-type headers according to the provided JSON:API
+ * document. It also verifies that the client's Accept header matches the media types supported by the document.
+ *
+ * The function requires that the `jsonApiRequestMiddleware` has been registered on the Koa app to populate
+ * `context.state.jsonApi` with the acceptable media types.
+ *
+ * @throws {JsonApiError} when the document's media type is not acceptable by the client.
+ *
+ * @example
+ * ```ts
+ * import { sendJsonApiResponse } from "./response";
+ * import { jsonApiRequestMiddleware } from "./middleware";
+ *
+ * app.use(async (context) => {
+ *   const document = {}; // Serialized document
+ *   sendJsonApiResponse(context, document);
+ * });
+ * ```
+ */
+export const sendJsonApiResponse = (context, document) => {
+    if (!context.state.jsonApi) {
+        throw new Error("You must register `jsonApiRequestMiddleware` in Koa");
+    }
+    document.verifyAcceptMediaType(context.state.jsonApi.acceptableTypes);
+    context.status = document.getStatus();
+    context.body = document.getBody();
+    context.set("content-type", document.getContentType());
+};

package/dist/tree-router.d.ts

@@ -0,0 +1,22 @@
+import type { Context } from "koa";
+type BaseContext = Pick<Context, "response" | "remove" | "status" | "body">;
+/**
+ * Handles HTTP method not allowed or resource not found errors for koa-tree-router
+ *
+ * This function inspects the `Allow` header of the response:
+ * - If it is empty, it means no allowed methods exist, so it removes the header and throws a 404 Not Found JSON:API
+ *   error.
+ * - Otherwise, it throws a 405 Method Not Allowed JSON:API error including the allowed methods in the error detail.
+ *
+ * Intended for use as a fallback handler when a request uses an HTTP method* that is not supported on the resource.
+ *
+ * @example
+ * ```ts
+ * import Router from "koa-tree-router";
+ * import { treeRouterMethodNotAllowedHandler } from "@jsonapi-serde/koa";
+ *
+ * const router = Router({ onMethodNotAllowed: treeRouterMethodNotAllowedHandler });
+ * ```
+ */
+export declare const treeRouterMethodNotAllowedHandler: <TContext extends BaseContext>(context: TContext) => never;
+export {};

package/dist/tree-router.js

@@ -0,0 +1,35 @@
+import { JsonApiError } from "@jsonapi-serde/server/common";
+/**
+ * Handles HTTP method not allowed or resource not found errors for koa-tree-router
+ *
+ * This function inspects the `Allow` header of the response:
+ * - If it is empty, it means no allowed methods exist, so it removes the header and throws a 404 Not Found JSON:API
+ *   error.
+ * - Otherwise, it throws a 405 Method Not Allowed JSON:API error including the allowed methods in the error detail.
+ *
+ * Intended for use as a fallback handler when a request uses an HTTP method* that is not supported on the resource.
+ *
+ * @example
+ * ```ts
+ * import Router from "koa-tree-router";
+ * import { treeRouterMethodNotAllowedHandler } from "@jsonapi-serde/koa";
+ *
+ * const router = Router({ onMethodNotAllowed: treeRouterMethodNotAllowedHandler });
+ * ```
+ */
+export const treeRouterMethodNotAllowedHandler = (context) => {
+    if (context.response.headers.allow === "") {
+        context.remove("allow");
+        throw new JsonApiError({
+            status: "404",
+            code: "not_found",
+            title: "Resource not found",
+        });
+    }
+    throw new JsonApiError({
+        status: "405",
+        code: "method_not_allowed",
+        title: "Method not allowed",
+        detail: `Allowed methods: ${context.response.headers.allow}`,
+    });
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@jsonapi-serde/integration-koa",
+  "version": "0.0.0",
+  "description": "Koa integration for @jsonapi-serde/server",
+  "type": "module",
+  "author": "Ben Scholzen 'DASPRiD'",
+  "license": "BSD-3-Clause",
+  "keywords": [
+    "jsonapi",
+    "typescript",
+    "zod",
+    "serializer",
+    "deserializer",
+    "parser",
+    "koa"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dasprid/jsonapi-serde-js.git"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "@jsonapi-serde": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/http-errors": "^2.0.4",
+    "@types/koa": "^2.15.0",
+    "http-errors": "^2.0.0",
+    "koa": "^3.0.0",
+    "koa-tree-router": "^0.13.1",
+    "@jsonapi-serde/server": "^0.0.0"
+  },
+  "peerDependencies": {
+    "koa": "^2.0.0 || ^3.0.0",
+    "http-errors": "^1.0.0 || ^2.0.0",
+    "@jsonapi-serde/server": "^0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "tsx -C jsonapi-serde --test --test-reporter=spec  --experimental-test-module-mocks --no-warnings=ExperimentalWarning test/**/*.ts",
+    "typecheck": "tsc --noEmit",
+    "ci:test": "c8 --reporter=lcov pnpm test"
+  }
+}