@jsonapi-serde/server 0.0.0

package/dist/request/body.js

@@ -0,0 +1,273 @@
+import { z } from "zod/v4";
+import { JsonApiError, ZodValidationError, ZodValidationErrorParams } from "../common/index.js";
+import { ContentTypeParser } from "../http/index.js";
+import { MediaTypeParserError } from "../http/index.js";
+/**
+ * Creates a Zod schema that ensures a string equals the provided fixed type
+ */
+const fixedTypeSchema = (type) => z.string().check((context) => {
+    if (context.value !== type) {
+        context.issues.push({
+            code: "custom",
+            message: "Type mismatch",
+            params: new ZodValidationErrorParams("type_mismatch", `Type '${context.value}' does not match '${type}'`, 409),
+            input: context.value,
+        });
+    }
+});
+/**
+ * Constructs a Zod schema for a JSON:API resource identifier
+ */
+export const resourceIdentifierSchema = (type, idSchema = z.string()) => z.strictObject({
+    type: fixedTypeSchema(type),
+    id: idSchema,
+});
+/**
+ * Constructs a Zod schema for a client resource identifier using `lid`
+ */
+export const clientResourceIdentifierSchema = (type) => z.strictObject({
+    type: fixedTypeSchema(type),
+    lid: z.string(),
+});
+/**
+ * Constructs a relationship object schema that wraps a given relationship data schema
+ */
+export const relationshipSchema = (schema) => z.strictObject({
+    data: schema,
+});
+/**
+ * A container class for looking up included resources of a given type by `lid`
+ */
+export class IncludedResourceMap {
+    type;
+    resources;
+    constructor(type, resources) {
+        this.type = type;
+        this.resources = resources;
+    }
+    /**
+     * Returns the resource with the given `lid` or null if not found
+     */
+    safeGet(lid) {
+        return this.resources.get(lid) ?? null;
+    }
+    /**
+     * Returns the resource with the given `lid`, or throws if not included
+     *
+     * @throws {JsonApiError} if the resource is missing
+     */
+    get(lid) {
+        const resource = this.resources.get(lid);
+        if (!resource) {
+            throw new JsonApiError({
+                status: "422",
+                code: "missing_included_resource",
+                title: "Missing included resource",
+                detail: `A referenced resource of type '${this.type}' and lid '${lid}' is missing in the document`,
+            });
+        }
+        return resource;
+    }
+}
+const buildIncludedSchema = (includedTypes) => {
+    if (!includedTypes) {
+        return z.undefined();
+    }
+    const includedResourceSchemas = [];
+    for (const [type, schemas] of Object.entries(includedTypes)) {
+        includedResourceSchemas.push(z.object({
+            lid: z.string(),
+            type: z.literal(type),
+            attributes: schemas.attributesSchema ? schemas.attributesSchema : z.undefined(),
+            relationships: schemas.relationshipsSchema
+                ? schemas.relationshipsSchema
+                : z.undefined(),
+        }));
+    }
+    if (includedResourceSchemas.length === 0) {
+        return z.array(z.never()).optional();
+    }
+    if (includedResourceSchemas.length === 1) {
+        return z.array(includedResourceSchemas[0]).optional();
+    }
+    return z
+        .array(z.discriminatedUnion("type", [
+        includedResourceSchemas[0],
+        ...includedResourceSchemas.slice(1),
+    ]))
+        .optional();
+};
+/**
+ * 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 const parseResourceRequest = (context, options) => {
+    const body = parseBody(context);
+    const includedSchema = buildIncludedSchema(options.includedTypeSchemas);
+    const parseResult = z
+        .strictObject({
+        data: z.strictObject({
+            id: options.idSchema ?? z.undefined(),
+            type: fixedTypeSchema(options.type),
+            attributes: options.attributesSchema ?? z.undefined(),
+            relationships: options.relationshipsSchema ?? z.undefined(),
+        }),
+        included: includedSchema,
+    })
+        .safeParse(body);
+    if (!parseResult.success) {
+        throw new ZodValidationError(parseResult.error.issues, "body");
+    }
+    const { data, included } = parseResult.data;
+    const result = {
+        type: options.type,
+    };
+    if ("id" in data) {
+        result.id = data.id;
+    }
+    if ("attributes" in data) {
+        result.attributes = data.attributes;
+    }
+    if ("relationships" in data) {
+        result.relationships = data.relationships;
+    }
+    if (options.includedTypeSchemas) {
+        const includedTypes = Object.fromEntries(Object.keys(options.includedTypeSchemas).map((type) => [type, new Map()]));
+        if (included) {
+            for (const resource of included) {
+                const map = includedTypes[resource.type];
+                map.set(resource.lid, resource);
+            }
+        }
+        result.includedTypes = Object.fromEntries(Object.entries(options.includedTypeSchemas).map(([type]) => [
+            type,
+            new IncludedResourceMap(type, includedTypes[type]),
+        ]));
+    }
+    return result;
+};
+/**
+ * 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 const parseRelationshipRequest = (context, type, idSchema) => {
+    const body = parseBody(context);
+    const parseResult = z
+        .object({
+        data: z.object({
+            type: z.literal(type),
+            id: (idSchema ?? z.string()),
+        }),
+    })
+        .safeParse(body);
+    if (!parseResult.success) {
+        throw new ZodValidationError(parseResult.error.issues, "body");
+    }
+    return parseResult.data.data.id;
+};
+/**
+ * Parses a JSON:API relationships request and returns a list of string IDs
+ *
+ * @throws {JsonApiError} for invalid content type or schema errors
+ */
+export const parseRelationshipsRequest = (context, type, idSchema = z.string()) => {
+    const body = parseBody(context);
+    const parseResult = z
+        .object({
+        data: z.array(z.object({
+            type: z.literal(type),
+            id: idSchema,
+        })),
+    })
+        .safeParse(body);
+    if (!parseResult.success) {
+        throw new ZodValidationError(parseResult.error.issues, "body");
+    }
+    return parseResult.data.data.map((identifier) => identifier.id);
+};
+/**
+ * Parses and validates the body content as JSON
+ *
+ * @throws {JsonApiError} if the body is not valid JSON
+ */
+const parseBody = (context) => {
+    validateContentType(context.contentType);
+    if (typeof context.body !== "string") {
+        return context.body;
+    }
+    try {
+        return JSON.parse(context.body);
+    }
+    catch (error) {
+        throw new JsonApiError({
+            status: "400",
+            code: "invalid_json_body",
+            title: "Invalid JSON body",
+            /* node:coverage ignore next */
+            detail: error instanceof Error ? error.message : undefined,
+        });
+    }
+};
+/**
+ * Validates that the provided content type is supported for JSON:API
+ *
+ * @throws {JsonApiError} for unsupported media types
+ */
+const validateContentType = (contentType) => {
+    if (!contentType) {
+        throw new JsonApiError({
+            status: "415",
+            code: "unsupported_media_type",
+            title: "Unsupported Media Type",
+            detail: `Media type is missing, use 'application/vnd.api+json'`,
+            source: { header: "Content-Type" },
+        });
+    }
+    let parts;
+    try {
+        parts = ContentTypeParser.parse(contentType);
+    }
+    catch (error) {
+        /* node:coverage disable */
+        if (!(error instanceof MediaTypeParserError)) {
+            throw error;
+        }
+        /* node:coverage enable */
+        throw new JsonApiError({
+            status: "400",
+            code: "bad_request",
+            title: "Bad Request",
+            detail: error.message,
+            source: {
+                header: "Content-Type",
+            },
+        });
+    }
+    if (parts.type !== "application" || parts.subType !== "vnd.api+json") {
+        throw new JsonApiError({
+            status: "415",
+            code: "unsupported_media_type",
+            title: "Unsupported Media Type",
+            detail: `Unsupported media type '${parts.type}/${parts.subType}', use 'application/vnd.api+json'`,
+            source: { header: "Content-Type" },
+        });
+    }
+    const { ext, profile, ...rest } = parts.parameters;
+    if (Object.keys(rest).length === 0) {
+        return;
+    }
+    throw new JsonApiError({
+        status: "415",
+        code: "unsupported_media_type",
+        title: "Unsupported Media Type",
+        detail: `Unknown media type parameters: ${Object.keys(rest).join(", ")}`,
+        source: { header: "Content-Type" },
+    });
+};

package/dist/request/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./body.js";
+export * from "./query.js";

package/dist/request/index.js

@@ -0,0 +1,2 @@
+export * from "./body.js";
+export * from "./query.js";

package/dist/request/query.d.ts

@@ -0,0 +1,116 @@
+import { z } from "zod/v4";
+import type { $ZodType } from "zod/v4/core";
+import type { ParentPaths } from "../common/utils.js";
+import { type SearchParamsInput } from "../http/index.js";
+/**
+ * Options for the `include` query parameter
+ *
+ * Defines which related resources are allowed in an `include` request.
+ */
+export type ParseQueryIncludeOptions<TInclude extends string> = {
+    /**
+     * Allowed include-paths (e.g., "author", "comments.author")
+     *
+     * Allowing "comments" automatically allows "comments.author".
+     */
+    allowed: TInclude[];
+    /** Default include-paths if none are provided in the query */
+    default?: string[];
+};
+/**
+ * Represents a sortable field and its sort direction
+ */
+export type SortField<TSort extends string> = {
+    /** Field name to sort by */
+    field: TSort;
+    /**
+     * Sort direction.
+     *
+     * - `asc` for ascending
+     * - `desc` for descending
+     */
+    order: "desc" | "asc";
+};
+/**
+ * Represents a list of sortable fields
+ */
+export type Sort<TSort extends string> = SortField<TSort>[];
+/**
+ * Options for the `sort` query parameter
+ */
+export type ParseQuerySortOptions<TFields extends string> = {
+    /** List of field names that are allowed to be sorted */
+    allowed: TFields[];
+    /** Default sorting order, if none is provided in the query */
+    default?: SortField<TFields>[];
+    /** Whether multiple sort fields are allowed (comma-separated) */
+    multiple?: boolean;
+};
+export type SparseFieldSets = Record<string, string[]>;
+export type PartialSparseFieldSets<TFieldSets extends SparseFieldSets> = {
+    [K in keyof TFieldSets]?: Partial<TFieldSets[K]>;
+};
+/**
+ * Options for the `fields` (sparse fieldsets) query parameter
+ *
+ * Allows specifying which fields are allowed per resource type.
+ */
+export type ParseQuerySparseFieldsetOptions<TAllowed extends Record<string, string[]>> = {
+    /** Allowed field names per resource type (e.g., { articles: ["title", "body"] }) */
+    allowed: TAllowed;
+    /** Default fieldsets to apply when the query omits some or all `fields` */
+    default?: PartialSparseFieldSets<TAllowed>;
+};
+/**
+ * Configuration object for creating a JSON:API query parser
+ *
+ * Omitting a property will disallow it in the query parameters.
+ */
+export type ParseQueryOptions<TInclude extends string | undefined, TSortFields extends string | undefined, TSparseFieldSets extends SparseFieldSets | undefined, TFilterSchema extends $ZodType | undefined, TPageSchema extends $ZodType | undefined> = {
+    /** Configuration for `include` query param */
+    include?: TInclude extends string ? ParseQueryIncludeOptions<TInclude> : undefined;
+    /** Configuration for `sort` query param */
+    sort?: TSortFields extends string ? ParseQuerySortOptions<TSortFields> : undefined;
+    /** Configuration for `fields` query param */
+    fields?: TSparseFieldSets extends SparseFieldSets ? ParseQuerySparseFieldsetOptions<TSparseFieldSets> : undefined;
+    /** Zod schema for validating and parsing the `filter` query param */
+    filter?: TFilterSchema;
+    /** Zod schema for validating and parsing the `page` query param */
+    page?: TPageSchema;
+};
+/**
+ * Structured result returned by the query parser
+ */
+export type ParseQueryResult<TInclude extends string | undefined, TSortFields extends string | undefined, TSparseFieldSets extends SparseFieldSets | undefined, TFilterSchema extends $ZodType | undefined, TPageSchema extends $ZodType | undefined> = {
+    include: TInclude extends string ? ParentPaths<TInclude>[] : undefined;
+    sort: TSortFields extends string ? Sort<TSortFields> : undefined;
+    fields: TSparseFieldSets extends SparseFieldSets ? PartialSparseFieldSets<TSparseFieldSets> : undefined;
+    filter: TFilterSchema extends $ZodType ? z.output<TFilterSchema> : undefined;
+    page: TPageSchema extends $ZodType ? z.output<TPageSchema> : undefined;
+};
+/**
+ * A query parser that parses a JSON:API-style query string into a strongly typed object.
+ */
+export type QueryParser<TInclude extends string | undefined, TSortFields extends string | undefined, TSparseFieldSets extends SparseFieldSets | undefined, TFilterSchema extends $ZodType | undefined, TPageSchema extends $ZodType | undefined> = (searchParams: SearchParamsInput) => ParseQueryResult<TInclude, TSortFields, TSparseFieldSets, TFilterSchema, TPageSchema>;
+/**
+ * Creates a query parser for JSON:API-compliant query strings.
+ *
+ * @example
+ * ```ts
+ * import { createQueryParser } from "jsonapi-serde/request";
+ *
+ * const parsePostQuery = createQueryParser({
+ *   include: { allowed: ["author", "comments.author"] },
+ *   sort: { allowed: ["title", "createdAt"], multiple: false },
+ *   fields: {
+ *     allowed: {
+ *       articles: ["title", "body"],
+ *       users: ["name"],
+ *     },
+ *   },
+ * });
+ *
+ * const query = parsePostQuery("include=author&sort=-createdAt&fields[articles]=title,body");
+ * ```
+ */
+export declare const createQueryParser: <TInclude extends string | undefined, TSortFields extends string | undefined, TSparseFieldSets extends SparseFieldSets | undefined, TFilterSchema extends $ZodType | undefined, TPageSchema extends $ZodType | undefined>(options: ParseQueryOptions<TInclude, TSortFields, TSparseFieldSets, TFilterSchema, TPageSchema>) => QueryParser<NoInfer<TInclude>, NoInfer<TSortFields>, NoInfer<TSparseFieldSets>, NoInfer<TFilterSchema>, NoInfer<TPageSchema>>;

package/dist/request/query.js

@@ -0,0 +1,142 @@
+import { z } from "zod/v4";
+import { ZodValidationError, ZodValidationErrorParams } from "../common/error.js";
+import { parseSearchParams } from "../http/index.js";
+/**
+ * Builds a schema to validate and transform the `include` parameter
+ */
+const buildIncludeSchema = (options) => z
+    .string()
+    .transform((paths) => (paths === "" ? [] : paths.split(",")))
+    .check((context) => {
+    for (const path of context.value) {
+        if (!options.allowed.some((value) => value === path || value.startsWith(`${path}.`))) {
+            context.issues.push({
+                code: "custom",
+                message: "Invalid include path",
+                input: context.value,
+                continue: true,
+                params: new ZodValidationErrorParams("invalid_include_path", `Path '${path}' cannot be included`),
+            });
+        }
+    }
+})
+    .default(options.default ?? []);
+/**
+ * Builds a schema to validate and transform the `sort` parameter
+ */
+const buildSortSchema = (options) => z
+    .string()
+    .transform((fields) => {
+    if (fields === "") {
+        return [];
+    }
+    return fields.split(",").map((field) => {
+        if (field.startsWith("-")) {
+            return { field: field.substring(1), order: "desc" };
+        }
+        return { field, order: "asc" };
+    });
+})
+    .check((context) => {
+    if (context.value.length > 1 && !options.multiple) {
+        context.issues.push({
+            code: "custom",
+            message: "Too many sort fields",
+            input: context.value,
+            continue: true,
+            params: new ZodValidationErrorParams("too_many_sort_fields", "Only a single sort field is allowed"),
+        });
+        return;
+    }
+    for (const field of context.value) {
+        if (!options.allowed.includes(field.field)) {
+            context.issues.push({
+                code: "custom",
+                message: "Invalid sort field",
+                input: context.value,
+                continue: true,
+                params: new ZodValidationErrorParams("invalid_sort_field", `Field '${field.field}]' cannot be sorted by`),
+            });
+        }
+    }
+})
+    .default(options.default ?? []);
+/**
+ * Builds a schema to validate and transform the `fields` parameter
+ */
+const buildSparseFieldsetSchema = (options) => z.strictObject(Object.fromEntries(Object.entries(options.allowed).map(([type, allowedFields]) => [
+    type,
+    z
+        .string()
+        .transform((fields) => (fields === "" ? [] : fields.split(",")))
+        .check((context) => {
+        for (const field of context.value) {
+            if (!allowedFields.includes(field)) {
+                context.issues.push({
+                    code: "custom",
+                    message: "Unknown resource field",
+                    input: context.value,
+                    continue: true,
+                    params: new ZodValidationErrorParams("unknown_resource_field", `Resource '${type}' has no field with name '${field}'`),
+                });
+            }
+        }
+    })
+        .optional(),
+])))
+    .default({})
+    .transform((fieldSets) => {
+    /* node:coverage disable */
+    if (!options.default) {
+        return fieldSets;
+    }
+    /* node:coverage enable */
+    return { ...options.default, ...fieldSets };
+});
+/**
+ * Creates a query parser for JSON:API-compliant query strings.
+ *
+ * @example
+ * ```ts
+ * import { createQueryParser } from "jsonapi-serde/request";
+ *
+ * const parsePostQuery = createQueryParser({
+ *   include: { allowed: ["author", "comments.author"] },
+ *   sort: { allowed: ["title", "createdAt"], multiple: false },
+ *   fields: {
+ *     allowed: {
+ *       articles: ["title", "body"],
+ *       users: ["name"],
+ *     },
+ *   },
+ * });
+ *
+ * const query = parsePostQuery("include=author&sort=-createdAt&fields[articles]=title,body");
+ * ```
+ */
+export const createQueryParser = (options) => {
+    const schema = z.strictObject({
+        include: options.include
+            ? buildIncludeSchema(options.include)
+            : z.undefined({ error: "'include' parameter is not supported" }),
+        sort: options.sort
+            ? buildSortSchema(options.sort)
+            : z.undefined({ error: "'sort' parameter is not supported" }),
+        fields: options.fields
+            ? buildSparseFieldsetSchema(options.fields)
+            : z.undefined({ error: "'fields' parameter is not supported" }),
+        filter: options.filter
+            ? options.filter
+            : z.undefined({ error: "'filter' parameter is not supported" }),
+        page: options.page
+            ? options.page
+            : z.undefined({ error: "'page' parameter is not supported" }),
+    });
+    return (input) => {
+        const parseResult = schema.safeParse(parseSearchParams(input));
+        if (!parseResult.success) {
+            throw new ZodValidationError(parseResult.error.issues, "query");
+        }
+        return parseResult.data;
+    };
+};

package/dist/response/index.d.ts

@@ -0,0 +1 @@
+export * from "./serializer.js";

package/dist/response/index.js

@@ -0,0 +1 @@
+export * from "./serializer.js";

package/dist/response/internal.d.ts

@@ -0,0 +1,6 @@
+import { JsonApiDocument } from "../common/response.js";
+import type { InferEntity, SerializeMap, SerializeOptions } from "./serializer.js";
+/**
+ * Serializes one or more entities into a JSON:API-compliant document
+ */
+export declare const serializeDocument: <TMap extends SerializeMap, TType extends keyof TMap & string, TEntity extends InferEntity<TMap[TType]>>(map: TMap, type: TType, entity: TEntity | Iterable<TEntity> | null, options?: SerializeOptions<TMap>) => JsonApiDocument;