@jsonapi-serde/server 0.0.0

package/dist/response/internal.js

@@ -0,0 +1,156 @@
+import assert from "node:assert/strict";
+import { JsonApiDocument } from "../common/response.js";
+/**
+ * Serializes one or more entities into a JSON:API-compliant document
+ */
+export const serializeDocument = (map, type, entity, options) => {
+    let data;
+    const includeCollection = new IncludeCollection(map, options);
+    if (entity === null) {
+        data = null;
+    }
+    else if (Symbol.iterator in entity) {
+        data = [];
+        for (const singleEntity of entity) {
+            data.push(serializeEntityToResource(map, type, singleEntity, includeCollection, "", options?.fields, options?.context));
+        }
+    }
+    else {
+        data = serializeEntityToResource(map, type, entity, includeCollection, "", options?.fields, options?.context);
+    }
+    return new JsonApiDocument({
+        data,
+        included: includeCollection.toJson(),
+        links: options?.links,
+        meta: options?.meta,
+    }, options?.status, { extensions: options?.extensions, profiles: options?.profiles });
+};
+/**
+ * Extracts a relationship's resource identifier, adding the full entity to the included collection if needed
+ */
+const extractIncluded = (identifier, includedCollection, fieldPath) => {
+    const { entity, ...rest } = identifier;
+    if (entity) {
+        includedCollection.add(identifier.type, entity, fieldPath);
+    }
+    return rest;
+};
+/**
+ * Builds a JSON:API-compliant relationships object for a serialized entity
+ */
+const buildRelationships = (serializedEntity, includeCollection, parentPath) => {
+    if (!serializedEntity.relationships) {
+        return undefined;
+    }
+    const relationships = {};
+    for (const [key, relationship] of Object.entries(serializedEntity.relationships)) {
+        /* node:coverage disable */
+        if (!relationship) {
+            continue;
+        }
+        /* node:coverage enable */
+        const { data, ...rest } = relationship;
+        if (!data) {
+            relationships[key] = { ...rest, data };
+            continue;
+        }
+        const path = parentPath === "" ? key : `${parentPath}.${key}`;
+        if (Array.isArray(data)) {
+            relationships[key] = {
+                ...rest,
+                data: data.map((data) => extractIncluded(data, includeCollection, path)),
+            };
+            continue;
+        }
+        relationships[key] = {
+            ...rest,
+            data: extractIncluded(data, includeCollection, path),
+        };
+    }
+    return relationships;
+};
+/**
+ * Filters object fields based on an allowlist of field names
+ */
+const filterFields = (values, includedFields) => {
+    if (!values) {
+        return undefined;
+    }
+    if (!includedFields) {
+        return Object.keys(values).length === 0 ? undefined : values;
+    }
+    const entries = Object.entries(values).filter(([key]) => includedFields.includes(key));
+    if (entries.length === 0) {
+        return undefined;
+    }
+    return Object.fromEntries(entries);
+};
+/**
+ * Converts a single entity into a JSON:API resource object
+ */
+const serializeEntityToResource = (map, type, entity, includeCollection, parentPath, fields, context) => {
+    const serializedEntity = map[type].serialize(entity, context?.[type]);
+    const includedFields = fields?.[type];
+    return {
+        id: map[type].getId(entity),
+        type,
+        attributes: filterFields(serializedEntity.attributes, includedFields),
+        relationships: filterFields(buildRelationships(serializedEntity, includeCollection, parentPath), includedFields),
+        meta: serializedEntity.meta,
+        links: serializedEntity.links,
+    };
+};
+/**
+ * Tracks which related entities should be included in the top-level `included` array
+ */
+class IncludeCollection {
+    map;
+    options;
+    resources = [];
+    alreadyIncluded = new Set();
+    /**
+     * Creates a new include collection based on inclusion rules
+     */
+    constructor(map, options) {
+        this.map = map;
+        this.options = options;
+    }
+    /**
+     * Adds an entity to the included set if it's not already present and matches an include path
+     */
+    add(type, entity, fieldPath) {
+        if (!this.shouldInclude(fieldPath)) {
+            return;
+        }
+        assert(this.map[type], `Type '${type}' is not registered in serializer`);
+        const key = `${type}\0${this.map[type].getId(entity)}`;
+        if (this.alreadyIncluded.has(key)) {
+            return;
+        }
+        this.alreadyIncluded.add(key);
+        this.resources.push(serializeEntityToResource(this.map, type, entity, this, fieldPath, this.options?.fields, this.options?.context));
+    }
+    /**
+     * Converts the included resource set to JSON:API format
+     */
+    toJson() {
+        if (!this.options?.include || this.options.include.length === 0) {
+            return undefined;
+        }
+        return this.resources;
+    }
+    /**
+     * Checks if a given path should be included in the document
+     */
+    shouldInclude(fieldPath) {
+        if (!this.options?.include) {
+            return false;
+        }
+        for (const includePath of this.options.include) {
+            if (includePath === fieldPath || includePath.startsWith(`${fieldPath}.`)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

package/dist/response/serializer.d.ts

@@ -0,0 +1,154 @@
+import type { Attributes, Links, Meta, Relationship, ResourceIdentifier, TopLevelLinks } from "../common/json-api.js";
+import type { JsonApiDocument } from "../common/response.js";
+import type { Flatten } from "../common/utils.js";
+/**
+ * A resource identifier with an optional `entity` field
+ *
+ * Used to enable inclusion of full resource data in `included`.
+ */
+export type IncludableResourceIdentifier<TMap extends SerializeMap, TType extends keyof TMap & string = keyof TMap & string> = Omit<ResourceIdentifier, "type"> & {
+    type: TType;
+    entity?: InferEntity<TMap[TType]> | undefined;
+};
+/**
+ * A relationship object that supports including full entities
+ */
+export type IncludableRelationship<TMap extends SerializeMap> = Omit<Relationship, "data"> & {
+    data: IncludableResourceIdentifier<TMap> | IncludableResourceIdentifier<TMap>[] | null;
+};
+/**
+ * The structure returned by an `EntitySerializer`
+ *
+ * This mimics a partial JSON:API resource object.
+ */
+export type SerializedEntity<TMap extends SerializeMap> = {
+    attributes?: Partial<Attributes>;
+    relationships?: Partial<Record<string, IncludableRelationship<TMap>>>;
+    meta?: Meta;
+    links?: Links;
+};
+/**
+ * Context passed to individual entity serializers
+ */
+export type EntitySerializerContext = Record<string, unknown>;
+/**
+ * A serializer that converts a specific entity type into a partial resource object
+ */
+export type EntitySerializer<T extends object, TContext extends EntitySerializerContext = EntitySerializerContext, TMap extends SerializeMap = SerializeMap> = {
+    getId: (entity: T) => string;
+    serialize: (entity: T, context?: TContext) => SerializedEntity<TMap>;
+};
+/**
+ * Infers the entity type from an EntitySerializer
+ */
+export type InferEntity<T extends EntitySerializer<object>> = T extends EntitySerializer<infer U> ? U : never;
+/**
+ * Infers the context type from an EntitySerializer
+ */
+export type InferContext<T extends EntitySerializer<object>> = T extends EntitySerializer<any, infer U> ? U : never;
+/**
+ * A generic serializer type used for mapping any entity
+ *
+ * biome-ignore lint/suspicious/noExplicitAny: Required for inference
+ */
+export type AnyEntitySerializer = EntitySerializer<any>;
+/**
+ * A map from resource type to their associated serializer
+ */
+export type SerializeMap = {
+    [key: string]: AnyEntitySerializer;
+};
+/**
+ * Options for customizing serialization output
+ */
+export type SerializeOptions<TMap extends SerializeMap> = {
+    /**
+     * Context for serializers
+     */
+    context?: Partial<SerializerContext<TMap>>;
+    /**
+     * HTTP status code to include in the response
+     */
+    status?: number;
+    /**
+     * Relationship paths to include in `included`
+     */
+    include?: string[];
+    /**
+     * Fields to include for each resource type
+     */
+    fields?: Partial<Record<keyof TMap & string, string[]>>;
+    /**
+     * Top-level `links` object
+     */
+    links?: TopLevelLinks;
+    /**
+     * Top-level `meta` object
+     */
+    meta?: Meta;
+    /**
+     * JSON:API extension URIs
+     */
+    extensions?: string[];
+    /**
+     * JSON:API profile URIs
+     */
+    profiles?: string[];
+};
+/**
+ * Context passed down to entity serializers
+ */
+export type SerializerContext<TMap extends SerializeMap> = {
+    [K in keyof TMap]: InferContext<TMap[K]>;
+};
+/**
+ * A function that serializes one or more entities into a JSON:API document
+ */
+export type Serializer<TMap extends SerializeMap> = <TType extends keyof TMap & string>(type: TType, entity: InferEntity<TMap[TType]> | Iterable<InferEntity<TMap[TType]>> | null, options?: SerializeOptions<TMap>) => JsonApiDocument;
+/**
+ * Infers the serialize map from a serializer
+ */
+export type InferSerializeMap<T extends Serializer<SerializeMap>> = T extends Serializer<infer U> ? U : never;
+/**
+ * Infers the serialize entity from a serializer
+ */
+export type InferSerializedEntity<T extends Serializer<SerializeMap>> = SerializedEntity<InferSerializeMap<T>>;
+/**
+ * Empty map used as initial state for the builder
+ */
+type EmptyMap = {
+    [key: string]: never;
+};
+/**
+ * Utility type to merge two `SerializeMap` types
+ *
+ * If the base is empty, returns the new map; otherwise merges both.
+ */
+type MergeMap<TBase extends SerializeMap, TNew extends SerializeMap> = TBase extends EmptyMap ? TNew : Flatten<TBase & TNew>;
+/**
+ * Fluent builder for constructing a typed `Serializer` instance
+ *
+ * You start with `SerializeBuilder.new()`, then chain `.add(...)` for each entity type you want to support, and finally
+ * call `.build()` to get the serializer.
+ */
+export declare class SerializeBuilder<T extends SerializeMap> {
+    private readonly serializers;
+    private constructor();
+    /**
+     * Creates a new `SerializeBuilder` with no registered serializers
+     */
+    static new(): SerializeBuilder<EmptyMap>;
+    /**
+     * Adds a serializer for a given resource `type`
+     */
+    add<TType extends string, TEntity extends object, TResult = SerializeBuilder<MergeMap<T, {
+        [K in TType]: EntitySerializer<TEntity>;
+    }>>>(type: TType, serializer: EntitySerializer<TEntity>): TResult;
+    /**
+     * Finalizes the builder and returns a fully-typed JSON:API serializer
+     *
+     * The returned function can serialize a single entity or an iterable of entities using the registered serializers.
+     */
+    build(): Serializer<T>;
+}
+export {};

package/dist/response/serializer.js

@@ -0,0 +1,38 @@
+import { serializeDocument } from "./internal.js";
+/**
+ * Fluent builder for constructing a typed `Serializer` instance
+ *
+ * You start with `SerializeBuilder.new()`, then chain `.add(...)` for each entity type you want to support, and finally
+ * call `.build()` to get the serializer.
+ */
+export class SerializeBuilder {
+    serializers;
+    constructor(serializers) {
+        this.serializers = serializers;
+    }
+    /**
+     * Creates a new `SerializeBuilder` with no registered serializers
+     */
+    static new() {
+        return new SerializeBuilder({});
+    }
+    /**
+     * Adds a serializer for a given resource `type`
+     */
+    add(type, serializer) {
+        return new SerializeBuilder({
+            ...this.serializers,
+            [type]: serializer,
+        });
+    }
+    /**
+     * Finalizes the builder and returns a fully-typed JSON:API serializer
+     *
+     * The returned function can serialize a single entity or an iterable of entities using the registered serializers.
+     */
+    build() {
+        return (type, entity, options) => {
+            return serializeDocument(this.serializers, type, entity, options);
+        };
+    }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@jsonapi-serde/server",
+  "version": "0.0.0",
+  "description": "Framework agnostic JSON:API serialization and deserialization",
+  "type": "module",
+  "author": "Ben Scholzen 'DASPRiD'",
+  "license": "BSD-3-Clause",
+  "keywords": [
+    "jsonapi",
+    "typescript",
+    "zod",
+    "serializer",
+    "deserializer",
+    "parser"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dasprid/jsonapi-serde-js.git"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "exports": {
+    "./common": {
+      "types": [
+        "./dist/common/index.d.ts",
+        "./src/common/index.ts"
+      ],
+      "jsonapi-serde": "./src/common/index.ts",
+      "default": "./dist/common/index.js"
+    },
+    "./http": {
+      "types": [
+        "./dist/http/index.d.ts",
+        "./src/http/index.ts"
+      ],
+      "jsonapi-serde": "./src/http/index.ts",
+      "default": "./dist/http/index.js"
+    },
+    "./request": {
+      "types": [
+        "./dist/request/index.d.ts",
+        "./src/request/index.ts"
+      ],
+      "jsonapi-serde": "./src/request/index.ts",
+      "default": "./dist/request/index.js"
+    },
+    "./response": {
+      "types": [
+        "./dist/response/index.d.ts",
+        "./src/response/index.ts"
+      ],
+      "jsonapi-serde": "./src/response/index.ts",
+      "default": "./dist/response/index.js"
+    }
+  },
+  "devDependencies": {
+    "zod": "^3.25.42"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.42"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "tsx --test --test-reporter=spec",
+    "typecheck": "tsc --noEmit",
+    "ci:test": "c8 --reporter=lcov pnpm test"
+  }
+}