@jsonapi-serde/server 0.0.0

package/dist/http/index.js

@@ -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";

package/dist/http/media-type-parser.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Thrown when parsing the header fails due to invalid syntax or unexpected characters
+ */
+export declare class MediaTypeParserError extends Error {
+}
+/**
+ * Parsed representation of a single media type
+ */
+export type MediaType = {
+    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 Accept = MediaType[];
+type RawParameter = [string, string];
+export declare abstract class MediaTypeParser {
+    protected readonly header: string;
+    protected readonly length: number;
+    protected index: number;
+    protected constructor(header: string);
+    protected readParameters(allowMediaTypeSeparator: boolean): RawParameter[];
+    protected readParameter(): RawParameter;
+    protected readParameterValue(): string;
+    protected readQuotedString(): string;
+    protected skipWhitespace(): void;
+    protected consumeChar(char: string): void;
+    protected readToken(): string;
+}
+export {};

package/dist/http/media-type-parser.js

@@ -0,0 +1,118 @@
+/**
+ * Thrown when parsing the header fails due to invalid syntax or unexpected characters
+ */
+export class MediaTypeParserError extends Error {
+}
+/**
+ * Returns a string of ASCII characters in a given range
+ */
+const asciiRange = (start, end) => {
+    let chars = "";
+    for (let ascii = start; ascii <= end; ++ascii) {
+        chars += String.fromCharCode(ascii);
+    }
+    return chars;
+};
+// Definitions from RFCs used in parsing tokens and quoted strings.
+const DIGIT = asciiRange(0x30, 0x39);
+const ALPHA = asciiRange(0x41, 0x5a) + asciiRange(0x61, 0x7a);
+const VCHAR = asciiRange(0x21, 0x7e);
+const TCHAR = `!#$%&'*+-.^_\`|~${DIGIT}${ALPHA}`;
+const OBS_TEXT = asciiRange(0x80, 0xff);
+const QD_TEXT = `\t !${asciiRange(0x23, 0x5b)}${asciiRange(0x50, 0x7e)}${OBS_TEXT}`;
+const QCHAR = `\t ${VCHAR} ${OBS_TEXT}`;
+export class MediaTypeParser {
+    header;
+    length;
+    index = 0;
+    constructor(header) {
+        this.header = header;
+        this.length = header.length;
+    }
+    readParameters(allowMediaTypeSeparator) {
+        const parameters = [];
+        while (this.index < this.length) {
+            this.skipWhitespace();
+            parameters.push(this.readParameter());
+            this.skipWhitespace();
+            if (this.index === this.length ||
+                (allowMediaTypeSeparator && this.header[this.index] === ",")) {
+                break;
+            }
+            this.consumeChar(";");
+        }
+        return parameters;
+    }
+    readParameter() {
+        this.skipWhitespace();
+        const parameterName = this.readToken();
+        this.consumeChar("=");
+        const parameterValue = this.readParameterValue();
+        return [parameterName, parameterValue];
+    }
+    readParameterValue() {
+        if (this.header[this.index] === '"') {
+            return this.readQuotedString();
+        }
+        return this.readToken();
+    }
+    readQuotedString() {
+        this.consumeChar('"');
+        let result = "";
+        let endFound = false;
+        while (this.index < this.length) {
+            const char = this.header[this.index];
+            this.index += 1;
+            if (char === '"') {
+                endFound = true;
+                break;
+            }
+            if (char !== "\\") {
+                if (!QD_TEXT.includes(char)) {
+                    throw new MediaTypeParserError(`Unexpected character at pos ${this.index - 1}`);
+                }
+                result += char;
+                continue;
+            }
+            if (this.index === this.length) {
+                throw new MediaTypeParserError("Unexpected end of header");
+            }
+            const quotedChar = this.header[this.index];
+            this.index += 1;
+            if (!QCHAR.includes(quotedChar)) {
+                throw new MediaTypeParserError(`Unexpected character at pos ${this.index - 1}`);
+            }
+            result += quotedChar;
+        }
+        if (!endFound) {
+            throw new MediaTypeParserError("Unclosed quoted string");
+        }
+        return result;
+    }
+    skipWhitespace() {
+        while (this.index < this.length &&
+            (this.header[this.index] === " " || this.header[this.index] === "\t")) {
+            this.index += 1;
+        }
+    }
+    consumeChar(char) {
+        if (this.index === this.length) {
+            throw new MediaTypeParserError("Unexpected end of header");
+        }
+        if (this.header[this.index] !== char) {
+            throw new MediaTypeParserError(`Unexpected character "${this.header[this.index]}" at pos ${this.index}, expected "${char}"`);
+        }
+        this.index += 1;
+    }
+    readToken() {
+        let token = "";
+        while (this.index < this.length && TCHAR.includes(this.header[this.index])) {
+            token += this.header[this.index];
+            this.index += 1;
+        }
+        if (token.length === 0) {
+            throw new MediaTypeParserError(`Could not find a token at pos ${this.index}`);
+        }
+        return token;
+    }
+}

package/dist/http/search-params.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Represents a nested object in parsed search params
+ */
+type ParsedSearchParamsObject = {
+    [k: string]: ParsedSearchParamsObject | ParsedSearchParamsArray | string;
+};
+/**
+ * Represents an array in parsed search params
+ */
+type ParsedSearchParamsArray = (ParsedSearchParamsObject | ParsedSearchParamsArray | string)[];
+/**
+ * Root type representing the fully parsed search parameters
+ */
+export type ParsedSearchParams = ParsedSearchParamsObject;
+/**
+ * Input type accepted by `URLSearchParams`, such as string, object, or iterable
+ */
+export type SearchParamsInput = ConstructorParameters<typeof URLSearchParams>[0];
+/**
+ * Parses a URL query string or `URLSearchParams` input into a deeply nested object
+ *
+ * Supports bracket and array notation like `user[address][city]=NY`.
+ *
+ * @example
+ * ```ts
+ * parseSearchParams("foo[0]=bar&foo[1]=baz");
+ * // => { foo: ["bar", "baz"] }
+ * ```
+ */
+export declare const parseSearchParams: (input: SearchParamsInput) => ParsedSearchParams;
+export {};

package/dist/http/search-params.js

@@ -0,0 +1,99 @@
+/**
+ * Matches the full key with optional bracketed subkeys (e.g., "user[address][city]")
+ */
+const fullKeyRegex = /^([^\[\]]+)((?:\[[^\[\]]*])*)$/;
+/**
+ * Matches each bracketed section inside a key (e.g., "[address]", "[city]")
+ */
+const bracketsRegex = /\[([^\[\]]*)]/g;
+/**
+ * Matches numeric array indices (e.g., "0", "1")
+ */
+const indexRegex = /^\d+$/;
+/**
+ * Parses a query string key into a path array
+ */
+const parseKey = (key) => {
+    const match = fullKeyRegex.exec(key);
+    if (!match) {
+        return null;
+    }
+    const path = [match[1]];
+    const brackets = match[2];
+    path.push(...Array.from(brackets.matchAll(bracketsRegex), (match) => match[1]));
+    return path;
+};
+/**
+ * Recursively removes undefined entries and empty holes from arrays
+ */
+const filterEmptyItems = (current) => {
+    if (Array.isArray(current)) {
+        return current
+            .filter((value) => value !== undefined)
+            .map((value) => {
+            if (typeof value === "string") {
+                return value;
+            }
+            return filterEmptyItems(value);
+        });
+    }
+    return Object.fromEntries(Object.entries(current).map(([key, value]) => {
+        if (typeof value === "string") {
+            return [key, value];
+        }
+        return [key, filterEmptyItems(value)];
+    }));
+};
+/**
+ * Parses a URL query string or `URLSearchParams` input into a deeply nested object
+ *
+ * Supports bracket and array notation like `user[address][city]=NY`.
+ *
+ * @example
+ * ```ts
+ * parseSearchParams("foo[0]=bar&foo[1]=baz");
+ * // => { foo: ["bar", "baz"] }
+ * ```
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Kept within one function for performance reasons
+export const parseSearchParams = (input) => {
+    const searchParams = new URLSearchParams(input);
+    const result = {};
+    for (const [key, value] of searchParams) {
+        const path = parseKey(key);
+        if (!path) {
+            continue;
+        }
+        let previous = null;
+        let keyInPrevious = null;
+        let current = result;
+        for (let i = 0; i < path.length; ++i) {
+            const part = path[i];
+            const isLast = i === path.length - 1;
+            const isIndex = indexRegex.test(part);
+            if (Array.isArray(current) && !isIndex && part !== "") {
+                current = Object.fromEntries([...current.entries()].filter(([_, value]) => value !== undefined));
+                if (previous && keyInPrevious !== null) {
+                    previous[keyInPrevious] = current;
+                }
+            }
+            const key = Array.isArray(current) && isIndex
+                ? Number.parseInt(part, 10)
+                : Array.isArray(current) && part === ""
+                    ? current.length
+                    : part;
+            if (isLast) {
+                current[key] = value;
+                continue;
+            }
+            previous = current;
+            keyInPrevious = key;
+            if (!current[key] || typeof current[key] === "string") {
+                const next = path[i + 1];
+                current[key] = next === "" || indexRegex.test(next) ? [] : {};
+            }
+            current = current[key];
+        }
+    }
+    return filterEmptyItems(result);
+};

package/dist/request/body.d.ts

@@ -0,0 +1,165 @@
+import { z } from "zod/v4";
+import type { $ZodType } from "zod/v4/core";
+/**
+ * Represents the structure of the request body and its content type
+ */
+export type BodyContext = {
+    /** The request body, either as a raw JSON string or already-parsed object */
+    body: Record<string, unknown> | string;
+    /** The request's Content-Type header value */
+    contentType: string | undefined;
+};
+/**
+ * Zod schema for a resource identifier with a required `type` and `id`
+ */
+export type ResourceIdentifierSchema<TType extends string> = $ZodType<{
+    type: TType;
+    id: string;
+}>;
+/**
+ * Constructs a Zod schema for a JSON:API resource identifier
+ */
+export declare const resourceIdentifierSchema: <TType extends string>(type: TType, idSchema?: $ZodType<string>) => ResourceIdentifierSchema<TType>;
+/**
+ * Zod schema for a client-generated resource identifier with a local ID (`lid`)
+ */
+export type ClientResourceIdentifierSchema<TType extends string> = $ZodType<{
+    type: TType;
+    lid: string;
+}>;
+/**
+ * Constructs a Zod schema for a client resource identifier using `lid`
+ */
+export declare const clientResourceIdentifierSchema: <TType extends string>(type: TType) => ClientResourceIdentifierSchema<TType>;
+type AnyResourceIdentifier = z.output<ResourceIdentifierSchema<string>> | z.output<ClientResourceIdentifierSchema<string>>;
+/**
+ * Union type representing one or more resource identifiers or `null`
+ */
+export type RelationshipDataSchema = $ZodType<AnyResourceIdentifier | AnyResourceIdentifier[] | null>;
+/**
+ * Schema for a JSON:API relationship object with a `data` field
+ */
+export type RelationshipSchema<TDataSchema extends RelationshipDataSchema> = $ZodType<{
+    data: z.output<TDataSchema>;
+}>;
+/**
+ * Constructs a relationship object schema that wraps a given relationship data schema
+ */
+export declare const relationshipSchema: <TDataSchema extends RelationshipDataSchema>(schema: TDataSchema) => RelationshipSchema<TDataSchema>;
+/**
+ * Zod schema for a map of named relationships
+ */
+export type RelationshipsSchema = $ZodType<Record<string, z.output<RelationshipSchema<RelationshipDataSchema>>>>;
+/**
+ * Zod schema for a generic JSON:API attributes object
+ */
+export type AttributesSchema = $ZodType<Record<string, unknown>>;
+/**
+ * Configuration object for parsing a resource request
+ *
+ * Includes optional `idSchema`, `attributesSchema`, and `relationshipsSchema`, and an optional map of
+ * `includedTypeSchemas` keyed by type name.
+ */
+export type ParseResourceRequestOptions<TIdSchema extends $ZodType<string> | undefined, TType extends string, TAttributesSchema extends AttributesSchema | undefined, TRelationshipsSchema extends RelationshipsSchema | undefined, TIncludedTypeSchemas extends IncludedTypeSchemas | undefined> = {
+    /** Optional Zod schema to validate the `id` field in the primary resource */
+    idSchema?: TIdSchema;
+    /** The expected resource `type` value for the primary data object */
+    type: TType;
+    /** Optional Zod schema for validating the `attributes` object in the request */
+    attributesSchema?: TAttributesSchema;
+    /** Optional Zod schema for validating the `relationships` object in the request */
+    relationshipsSchema?: TRelationshipsSchema;
+    /**
+     * Optional map of included resource `type` names to their validation schemas
+     *
+     * Used to validate and organize entries in the top-level `included` array.
+     */
+    includedTypeSchemas?: TIncludedTypeSchemas;
+};
+/**
+ * A parsed included resource entry
+ */
+export type IncludedResource<TOptions extends AnyIncludedResourceSchemas> = {
+    /** The local identifier (lid) of the included resource */
+    lid: string;
+    /** The `type` of the included resource */
+    type: string;
+    /** The `attributes` of the resource, if a schema was provided */
+    attributes: TOptions["attributesSchema"] extends AttributesSchema ? z.output<TOptions["attributesSchema"]> : undefined;
+    /** The `relationships` of the resource, if a schema was provided. */
+    relationships: TOptions["relationshipsSchema"] extends RelationshipsSchema ? z.output<TOptions["relationshipsSchema"]> : undefined;
+};
+/**
+ * A container class for looking up included resources of a given type by `lid`
+ */
+export declare class IncludedResourceMap<TResourceOptions extends AnyIncludedResourceSchemas> {
+    private readonly type;
+    private resources;
+    constructor(type: string, resources: Map<string, IncludedResource<TResourceOptions>>);
+    /**
+     * Returns the resource with the given `lid` or null if not found
+     */
+    safeGet(lid: string): IncludedResource<TResourceOptions> | null;
+    /**
+     * Returns the resource with the given `lid`, or throws if not included
+     *
+     * @throws {JsonApiError} if the resource is missing
+     */
+    get(lid: string): IncludedResource<TResourceOptions>;
+}
+/**
+ * Map of all included resource types and their corresponding resource maps
+ */
+export type IncludedTypesContainer<T extends IncludedTypeSchemas> = {
+    [K in keyof T]: IncludedResourceMap<T[K]>;
+};
+/**
+ * Parsed result from a resource request
+ */
+export type ParseResourceRequestResult<TIdSchema extends $ZodType<string> | undefined, TType extends string, TAttributesSchema extends AttributesSchema | undefined, TRelationshipsSchema extends RelationshipsSchema | undefined, TIncludedTypeSchemas extends IncludedTypeSchemas | undefined> = {
+    id: TIdSchema extends $ZodType<string> ? z.output<TIdSchema> : undefined;
+    type: TType;
+    attributes: TAttributesSchema extends AttributesSchema ? z.output<TAttributesSchema> : undefined;
+    relationships: TRelationshipsSchema extends RelationshipsSchema ? z.output<TRelationshipsSchema> : undefined;
+    includedTypes: TIncludedTypeSchemas extends IncludedTypeSchemas ? IncludedTypesContainer<TIncludedTypeSchemas> : undefined;
+};
+/**
+ * Describes the schema of an included resource, including optional attributes and relationships
+ */
+export type IncludedResourceSchemas<TAttributesSchema extends AttributesSchema | undefined, TRelationshipsSchema extends RelationshipsSchema | undefined> = {
+    /** Optional Zod schema for validating the `attributes` object */
+    attributesSchema?: TAttributesSchema;
+    /** Optional Zod schema for validating the `relationships` object */
+    relationshipsSchema?: TRelationshipsSchema;
+};
+type AnyIncludedResourceSchemas = IncludedResourceSchemas<any, any>;
+/**
+ * Map of included resource types to their schemas
+ */
+export type IncludedTypeSchemas = {
+    [key: string]: IncludedResourceSchemas<AttributesSchema | undefined, RelationshipsSchema | undefined>;
+};
+/**
+ * Parses a JSON:API resource request
+ *
+ * Validates content type, parses the document, and extracts resource and included data according to the provided
+ * options.
+ *
+ * @throws {JsonApiError} for invalid content type or malformed document
+ */
+export declare const parseResourceRequest: <TIdSchema extends $ZodType<string> | undefined, TType extends string, TAttributesSchema extends AttributesSchema | undefined, TRelationshipsSchema extends RelationshipsSchema | undefined, TIncludedTypeSchemas extends IncludedTypeSchemas | undefined>(context: BodyContext, options: ParseResourceRequestOptions<TIdSchema, TType, TAttributesSchema, TRelationshipsSchema, TIncludedTypeSchemas>) => ParseResourceRequestResult<NoInfer<TIdSchema>, NoInfer<TType>, NoInfer<TAttributesSchema>, NoInfer<TRelationshipsSchema>, NoInfer<TIncludedTypeSchemas>>;
+/**
+ * Parses a JSON:API relationship request and returns an ID
+ *
+ * The `idSchema` can be made `.nullable`.
+ *
+ * @throws {JsonApiError} for invalid content type or schema errors
+ */
+export declare const parseRelationshipRequest: <TIdSchema extends $ZodType<string | null> | undefined>(context: BodyContext, type: string, idSchema?: TIdSchema) => TIdSchema extends $ZodType<string | null> ? z.output<NoInfer<TIdSchema>> : string;
+/**
+ * Parses a JSON:API relationships request and returns a list of string IDs
+ *
+ * @throws {JsonApiError} for invalid content type or schema errors
+ */
+export declare const parseRelationshipsRequest: (context: BodyContext, type: string, idSchema?: $ZodType<string>) => string[];
+export {};