@jsonapi-serde/server 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 - Server
+
+[![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)
+
+---
+
+JSON:API Serde is a framework-agnostic [JSON:API](https://jsonapi.org) serialization and deserialization library.
+
+## 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/server/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/common/error.d.ts

@@ -0,0 +1,53 @@
+import type { $ZodIssue } from "zod/v4/core";
+import type { JsonApiErrorObject } from "./json-api.js";
+import { JsonApiDocument } from "./response.js";
+/**
+ * A JSON:API-compliant error wrapper
+ *
+ * Accepts one or more `JsonApiErrorObject` instances and provides status inference and document transformation.
+ */
+export declare class JsonApiError {
+    readonly errors: JsonApiErrorObject[];
+    readonly status: number;
+    /**
+     * Creates a new `JsonApiError` from one or more error objects
+     *
+     * Automatically infers a suitable HTTP status code.
+     *
+     * @throws {Error} when no errors are supplied
+     */
+    constructor(errors: JsonApiErrorObject | JsonApiErrorObject[]);
+    /**
+     * Determines the appropriate HTTP status code from the error set
+     *
+     * Falls back to 500 or 400 based on presence and severity of error codes.
+     * A warning is emitted when no status codes were defined.
+     */
+    private static determineStatusCode;
+    /**
+     * Converts the error into a full JSON:API error document
+     */
+    toDocument(): JsonApiDocument;
+}
+/**
+ * Structured metadata that can be attached to a Zod issue to influence JSON:API output
+ */
+export declare class ZodValidationErrorParams {
+    /** Custom error code to override Zod’s default for custom errors */
+    readonly code: string;
+    /** Optional detailed explanation of the error */
+    readonly detail: string | undefined;
+    /** Optional HTTP status code (e.g., 400 or 422) */
+    readonly status: number | undefined;
+    constructor(code: string, detail?: string, status?: number);
+}
+/**
+ * Translates Zod validation issues into a JSON:API error document
+ */
+export declare class ZodValidationError extends JsonApiError {
+    constructor(errors: $ZodIssue[], source: "query" | "body");
+    /**
+     * Resolves the `source` field of a JSON:API error based on Zod’s path
+     */
+    private static getSource;
+}

package/dist/common/error.js

@@ -0,0 +1,114 @@
+import { JsonApiDocument } from "./response.js";
+/**
+ * A JSON:API-compliant error wrapper
+ *
+ * Accepts one or more `JsonApiErrorObject` instances and provides status inference and document transformation.
+ */
+export class JsonApiError {
+    errors;
+    status;
+    /**
+     * Creates a new `JsonApiError` from one or more error objects
+     *
+     * Automatically infers a suitable HTTP status code.
+     *
+     * @throws {Error} when no errors are supplied
+     */
+    constructor(errors) {
+        this.errors = Array.isArray(errors) ? errors : [errors];
+        if (this.errors.length === 0) {
+            throw new Error("At least one error must be supplied");
+        }
+        this.status = JsonApiError.determineStatusCode(this.errors);
+    }
+    /**
+     * Determines the appropriate HTTP status code from the error set
+     *
+     * Falls back to 500 or 400 based on presence and severity of error codes.
+     * A warning is emitted when no status codes were defined.
+     */
+    static determineStatusCode = (errors) => {
+        const uniqueStatusCodes = [
+            ...new Set(errors
+                .map((error) => error.status)
+                .filter((value) => value !== undefined)
+                .map((value) => Number.parseInt(value, 10))),
+        ];
+        if (uniqueStatusCodes.length === 0) {
+            console.warn("No error contained a status code, falling back to 500");
+            return 500;
+        }
+        if (uniqueStatusCodes.length === 1) {
+            return uniqueStatusCodes[0];
+        }
+        if (uniqueStatusCodes.some((statusCode) => statusCode >= 500 && statusCode < 600)) {
+            return 500;
+        }
+        return 400;
+    };
+    /**
+     * Converts the error into a full JSON:API error document
+     */
+    toDocument() {
+        return new JsonApiDocument({
+            errors: this.errors,
+        }, this.status);
+    }
+}
+/**
+ * Structured metadata that can be attached to a Zod issue to influence JSON:API output
+ */
+export class ZodValidationErrorParams {
+    /** Custom error code to override Zod’s default for custom errors */
+    code;
+    /** Optional detailed explanation of the error */
+    detail;
+    /** Optional HTTP status code (e.g., 400 or 422) */
+    status;
+    constructor(code, detail, status) {
+        this.code = code;
+        this.detail = detail;
+        this.status = status;
+    }
+}
+/**
+ * Translates Zod validation issues into a JSON:API error document
+ */
+export class ZodValidationError extends JsonApiError {
+    constructor(errors, source) {
+        super(errors.map((error) => {
+            const params = error.code === "custom" && error.params instanceof ZodValidationErrorParams
+                ? error.params
+                : null;
+            const { code, input, path, message, ...rest } = error;
+            const meta = params
+                ? Object.fromEntries(Object.entries(rest).filter(([key]) => key !== "params"))
+                : rest;
+            return {
+                status: params?.status?.toString() ?? (source === "query" ? "400" : "422"),
+                code: params?.code ?? code,
+                title: message,
+                detail: params?.detail,
+                source: ZodValidationError.getSource(source, path),
+                meta: Object.keys(meta).length > 0 ? meta : undefined,
+            };
+        }));
+    }
+    /**
+     * Resolves the `source` field of a JSON:API error based on Zod’s path
+     */
+    static getSource(errorSource, path) {
+        if (errorSource === "body") {
+            return { pointer: `/${path.join("/")}` };
+        }
+        if (path.length === 0) {
+            return undefined;
+        }
+        return {
+            parameter: `${path[0].toString()}${path
+                .slice(1)
+                .map((element) => `[${element.toString}]`)
+                .join()}`,
+        };
+    }
+}

package/dist/common/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./error.js";
+export * from "./json-api.js";
+export * from "./response.js";

package/dist/common/index.js

@@ -0,0 +1,3 @@
+export * from "./error.js";
+export * from "./json-api.js";
+export * from "./response.js";

package/dist/common/json-api.d.ts

@@ -0,0 +1,94 @@
+/** Arbitrary metadata object allowed anywhere in a JSON:API document */
+export type Meta = Record<string, unknown>;
+/** A link object with optional attributes for rich linking information */
+export type LinkObject = {
+    href: string;
+    rel?: string;
+    describedby?: string;
+    title?: string;
+    type?: string;
+    hreflang?: string;
+    meta?: Meta;
+};
+/** A link can be a plain string URL or a full `LinkObject` */
+export type Link = LinkObject | string;
+/** A collection of named links. Keys are optional and can be nullified */
+export type Links<TKey extends string = string> = Partial<Record<TKey, Link | null>>;
+/** Standard top-level links as defined by JSON:API */
+export type TopLevelLinks = Links<"self" | "related" | "describedby" | "first" | "last" | "prev" | "next">;
+/** A JSON:API-compliant error object */
+export type JsonApiErrorObject = {
+    id?: string;
+    links?: Links<"about" | "type">;
+    status?: string;
+    code?: string;
+    title?: string;
+    detail?: string;
+    source?: {
+        pointer?: string;
+        parameter?: string;
+        header?: string;
+    };
+    meta?: Meta;
+};
+export type JsonApiImplementation = {
+    version?: string;
+    ext?: string[];
+    profile?: string[];
+    meta?: Meta;
+};
+/** Optional fields allowed at the top level of a JSON:API document */
+type OptionalTopLevelMembers = {
+    links?: TopLevelLinks;
+    included?: Resource[];
+};
+/** A data document contains a primary resource (`data`) and may include `meta` */
+type DataTopLevelMembers = {
+    data: Resource | Resource[] | null;
+    errors?: undefined;
+    meta?: Meta;
+};
+/** An error document includes one or more errors, but no primary data */
+type ErrorTopLevelMembers = {
+    data?: undefined;
+    errors: JsonApiErrorObject[];
+    meta?: Meta;
+};
+/** A meta-only document contains only `meta`, no data or errors */
+type MetaTopLevelMembers = {
+    data?: undefined;
+    errors?: undefined;
+    meta: Meta;
+};
+/**
+ * The top-level members of a JSON:API document
+ *
+ * One of `data`, `errors`, or `meta` must be present.
+ */
+export type TopLevelMembers = OptionalTopLevelMembers & (DataTopLevelMembers | ErrorTopLevelMembers | MetaTopLevelMembers);
+/** Resource attributes are key-value pairs */
+export type Attributes = Record<string, unknown>;
+/** A map of relationship names to their definitions */
+export type Relationships = Record<string, Relationship>;
+/** A reference to another resource */
+export type ResourceIdentifier = {
+    type: string;
+    id: string;
+    meta?: Meta;
+};
+/** A relationship describes links and/or resource identifiers */
+export type Relationship = {
+    data?: ResourceIdentifier | ResourceIdentifier[] | null;
+    links?: Links<"self" | "related" | string>;
+    meta?: Meta;
+};
+/** A full resource object in the JSON:API format */
+export type Resource = {
+    id: string;
+    type: string;
+    attributes?: Partial<Attributes>;
+    relationships?: Partial<Relationships>;
+    links?: Links<"self" | string>;
+    meta?: Meta;
+};
+export {};

package/dist/common/json-api.js

@@ -0,0 +1 @@
+export {};

package/dist/common/response.d.ts

@@ -0,0 +1,43 @@
+import type { JsonApiMediaType } from "../http/index.js";
+import type { JsonApiImplementation, TopLevelMembers } from "./json-api.js";
+type MediaTypeOptions = {
+    extensions?: string[];
+    profiles?: string[];
+};
+/**
+ * Represents a JSON:API-compliant HTTP response document
+ *
+ * Encapsulates status, headers, and body generation.
+ */
+export declare class JsonApiDocument {
+    private readonly members;
+    private readonly mediaTypeOptions;
+    private readonly status;
+    /**
+     * Constructs a new JSON:API response document
+     */
+    constructor(members: TopLevelMembers, status?: number, mediaTypeOptions?: MediaTypeOptions);
+    /**
+     * Returns the HTTP status code for this response
+     */
+    getStatus(): number;
+    /**
+     * Returns the top-level JSON:API body object
+     */
+    getBody(): TopLevelMembers & {
+        jsonapi: JsonApiImplementation;
+    };
+    /**
+     * Returns the full `Content-Type` header for this response
+     *
+     * Automatically includes `ext` and `profile` parameters if present in `jsonapi`.
+     */
+    getContentType(): string;
+    /**
+     * Verifies that the client accepts the content type of this document
+     *
+     * @throws {JsonApiError} if content type is not acceptable
+     */
+    verifyAcceptMediaType(acceptableTypes: JsonApiMediaType[]): void;
+}
+export {};

package/dist/common/response.js

@@ -0,0 +1,78 @@
+import { JsonApiError } from "./error.js";
+/**
+ * Represents a JSON:API-compliant HTTP response document
+ *
+ * Encapsulates status, headers, and body generation.
+ */
+export class JsonApiDocument {
+    members;
+    mediaTypeOptions;
+    status;
+    /**
+     * Constructs a new JSON:API response document
+     */
+    constructor(members, status = 200, mediaTypeOptions) {
+        this.members = members;
+        this.mediaTypeOptions = mediaTypeOptions;
+        this.status = status;
+    }
+    /**
+     * Returns the HTTP status code for this response
+     */
+    getStatus() {
+        return this.status;
+    }
+    /**
+     * Returns the top-level JSON:API body object
+     */
+    getBody() {
+        return {
+            jsonapi: {
+                version: "1.1",
+                ext: this.mediaTypeOptions?.extensions,
+                profile: this.mediaTypeOptions?.profiles,
+            },
+            ...this.members,
+        };
+    }
+    /**
+     * Returns the full `Content-Type` header for this response
+     *
+     * Automatically includes `ext` and `profile` parameters if present in `jsonapi`.
+     */
+    getContentType() {
+        const contentType = "application/vnd.api+json";
+        const parameters = [];
+        if (this.mediaTypeOptions?.extensions && this.mediaTypeOptions.extensions.length > 0) {
+            parameters.push(`ext="${this.mediaTypeOptions.extensions.join(" ")}"`);
+        }
+        if (this.mediaTypeOptions?.profiles && this.mediaTypeOptions.profiles.length > 0) {
+            parameters.push(`profile="${this.mediaTypeOptions.profiles.join(" ")}"`);
+        }
+        if (parameters.length === 0) {
+            return contentType;
+        }
+        return `${contentType};${parameters.join(";")}`;
+    }
+    /**
+     * Verifies that the client accepts the content type of this document
+     *
+     * @throws {JsonApiError} if content type is not acceptable
+     */
+    verifyAcceptMediaType(acceptableTypes) {
+        const appliedExtensions = this.mediaTypeOptions?.extensions;
+        const matchingTypes = acceptableTypes.filter((type) => {
+            return type.ext.every((extension) => appliedExtensions?.includes(extension));
+        });
+        if (matchingTypes.length > 0) {
+            return;
+        }
+        throw new JsonApiError({
+            status: "406",
+            code: "not_acceptable",
+            title: "Not Acceptable",
+            detail: "No valid accept types provided, you must accept application/vnd.api+json",
+            meta: appliedExtensions ? { appliedExtensions } : undefined,
+        });
+    }
+}

package/dist/common/utils.d.ts

@@ -0,0 +1,5 @@
+export type Identity<T> = T;
+export type Flatten<T> = Identity<{
+    [K in keyof T]: T[K];
+}>;
+export type ParentPaths<T extends string> = T extends `${infer Head}.${infer Tail}` ? Head | `${Head}.${ParentPaths<Tail>}` : T;

package/dist/common/utils.js

@@ -0,0 +1 @@
+export {};

package/dist/http/accept.d.ts

@@ -0,0 +1,53 @@
+import { MediaTypeParser } from "./media-type-parser.js";
+/**
+ * Parsed representation of a single media type in the Accept header
+ */
+export type ParsedAcceptMediaType = {
+    type: string;
+    subType: string;
+    parameters: Record<string, string>;
+    weight: number;
+    acceptExt: Record<string, string>;
+};
+/**
+ * List of all parsed media types sorted by descending quality (`q`) weight
+ */
+export type ParsedAccept = ParsedAcceptMediaType[];
+/**
+ * Parses and represents an HTTP `Accept` header as structured data
+ */
+export declare class AcceptParser extends MediaTypeParser {
+    private static readonly default;
+    private static readonly weightRegexp;
+    /**
+     * Parses the Accept header string into a structured `ParsedAccept` array
+     *
+     * @throws {MediaTypeParserError} when parsing of Accept header fails
+     */
+    static parse(header: string): ParsedAccept;
+    /**
+     * Parses the header into an ordered list of media types
+     */
+    private process;
+    private readMediaType;
+    private readSeparator;
+}
+/**
+ * Represents a parsed and filtered JSON:API media type with `ext` and `profile` parameters
+ */
+export type JsonApiMediaType = {
+    ext: string[];
+    profile: string[];
+};
+/**
+ * Filters and extracts valid JSON:API media types from an `Accept` header
+ *
+ * Only includes entries with:
+ *
+ * - `type` of `application` or `*`
+ * - `subType` of `vnd.api+json` or `*`
+ * - No extra parameters beyond `ext` and `profile`
+ *
+ * @throws {MediaTypeParserError} when parsing of Accept header fails
+ */
+export declare const getAcceptableMediaTypes: (header: string | undefined) => JsonApiMediaType[];

package/dist/http/accept.js

@@ -0,0 +1,114 @@
+import { MediaTypeParser, MediaTypeParserError } from "./media-type-parser.js";
+/**
+ * Parses and represents an HTTP `Accept` header as structured data
+ */
+export class AcceptParser extends MediaTypeParser {
+    static default = {
+        type: "*",
+        subType: "*",
+        parameters: {},
+        weight: 1,
+        acceptExt: {},
+    };
+    static weightRegexp = /^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/;
+    /**
+     * Parses the Accept header string into a structured `ParsedAccept` array
+     *
+     * @throws {MediaTypeParserError} when parsing of Accept header fails
+     */
+    static parse(header) {
+        const parser = new AcceptParser(header);
+        return parser.process();
+    }
+    /**
+     * Parses the header into an ordered list of media types
+     */
+    process() {
+        this.skipWhitespace();
+        if (this.index === this.length) {
+            return [AcceptParser.default];
+        }
+        const accept = [];
+        let mediaType;
+        let hasMore;
+        do {
+            [mediaType, hasMore] = this.readMediaType();
+            accept.push(mediaType);
+        } while (hasMore);
+        accept.sort((a, b) => b.weight - a.weight);
+        return accept;
+    }
+    readMediaType() {
+        const type = this.readToken().toLowerCase();
+        this.consumeChar("/");
+        const subType = this.readToken().toLowerCase();
+        this.skipWhitespace();
+        if (this.index === this.length) {
+            return [{ ...AcceptParser.default, type, subType }, false];
+        }
+        if (this.readSeparator() === ",") {
+            this.skipWhitespace();
+            return [{ ...AcceptParser.default, type, subType }, true];
+        }
+        const parameters = {};
+        let weight = 1;
+        const acceptExt = {};
+        let parameterTarget = parameters;
+        for (const [name, value] of this.readParameters(true)) {
+            if (name === "q") {
+                parameterTarget = acceptExt;
+                if (!AcceptParser.weightRegexp.test(value)) {
+                    throw new MediaTypeParserError(`Invalid weight: ${value}`);
+                }
+                weight = Number.parseFloat(value);
+                continue;
+            }
+            parameterTarget[name] = value;
+        }
+        this.skipWhitespace();
+        const hasMore = this.index < this.length;
+        if (hasMore) {
+            this.consumeChar(",");
+            this.skipWhitespace();
+        }
+        return [{ type, subType, parameters, weight, acceptExt }, hasMore];
+    }
+    readSeparator() {
+        // No need for an index check here, as the caller already took care of it.
+        const char = this.header[this.index];
+        this.index += 1;
+        if (char !== "," && char !== ";") {
+            throw new MediaTypeParserError(`Unexpected character at pos ${this.index - 1}, expected separator`);
+        }
+        return char;
+    }
+}
+/**
+ * Filters and extracts valid JSON:API media types from an `Accept` header
+ *
+ * Only includes entries with:
+ *
+ * - `type` of `application` or `*`
+ * - `subType` of `vnd.api+json` or `*`
+ * - No extra parameters beyond `ext` and `profile`
+ *
+ * @throws {MediaTypeParserError} when parsing of Accept header fails
+ */
+export const getAcceptableMediaTypes = (header) => {
+    const accept = AcceptParser.parse(header ?? "");
+    return accept.reduce((accept, mediaType) => {
+        if ((mediaType.type !== "*" && mediaType.type !== "application") ||
+            (mediaType.subType !== "*" && mediaType.subType !== "vnd.api+json")) {
+            return accept;
+        }
+        const { ext, profile, ...rest } = mediaType.parameters;
+        if (Object.keys(rest).length !== 0) {
+            return accept;
+        }
+        accept.push({
+            ext: ext ? ext.split(" ") : [],
+            profile: profile ? profile.split(" ") : [],
+        });
+        return accept;
+    }, []);
+};

package/dist/http/content-type.d.ts

@@ -0,0 +1,18 @@
+import { MediaTypeParser } from "./media-type-parser.js";
+export type ParsedContentType = {
+    type: string;
+    subType: string;
+    parameters: Record<string, string>;
+};
+/**
+ * Parses and represents an HTTP `Content-Type` header as structured data
+ */
+export declare class ContentTypeParser extends MediaTypeParser {
+    /**
+     * Parses the Content-Type header string into a structured `ParsedContentType` object
+     *
+     * @throws {ParserError} when parsing of Content-Type header fails
+     */
+    static parse(header: string): ParsedContentType;
+    private process;
+}

package/dist/http/content-type.js

@@ -0,0 +1,36 @@
+import { MediaTypeParser, MediaTypeParserError } from "./media-type-parser.js";
+/**
+ * Parses and represents an HTTP `Content-Type` header as structured data
+ */
+export class ContentTypeParser extends MediaTypeParser {
+    /**
+     * Parses the Content-Type header string into a structured `ParsedContentType` object
+     *
+     * @throws {ParserError} when parsing of Content-Type header fails
+     */
+    static parse(header) {
+        const parser = new ContentTypeParser(header);
+        return parser.process();
+    }
+    process() {
+        this.skipWhitespace();
+        const type = this.readToken().toLowerCase();
+        this.consumeChar("/");
+        const subType = this.readToken().toLowerCase();
+        const parameters = {};
+        this.skipWhitespace();
+        if (this.index === this.length) {
+            return { type, subType, parameters };
+        }
+        if (this.header[this.index] !== ";") {
+            throw new MediaTypeParserError(`Unexpected character at pos ${this.index}, expected separator`);
+        }
+        this.index += 1;
+        if (this.index < this.length) {
+            for (const [name, value] of this.readParameters(false)) {
+                parameters[name] = value;
+            }
+        }
+        return { type, subType, parameters };
+    }
+}

package/dist/http/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./accept.js";
+export * from "./content-type.js";
+export { MediaTypeParserError } from "./media-type-parser.js";
+export * from "./search-params.js";