jsonapi-nano

A lightweight, ultra-fast, zero-dependency presentation layer engine for formatting data into strict, compliance-ready JSON:API spec configurations. 100% framework-agnostic design built for modern cloud-native architectures.

📖 Complete Documentation

Our full installation guides, framework integration examples, type parameters, and error-handling utilities are live at: 👉 emmanuel-melon.github.io/jsonapi-nano

Installation

npm install @emelon/jsonapi-nano

Quick Start

import {
  createResource,
  serialize,
  belongsTo,
  fieldsFromQuery,
} from "@emelon/jsonapi-nano";

interface Article {
  id: string;
  title: string;
  body: string;
  authorId: string;
}

interface Author {
  id: string;
  name: string;
}

// 1. Define reusable presentation schemas matching your entities
const authorResource = createResource<Author>("authors", {
  attributes: (author) => ({ name: author.name }),
});

const articleResource = createResource<Article>("articles", {
  attributes: (article) => ({ title: article.title, body: article.body }),
  relationships: (article) => ({
    author: belongsTo("authors", article.authorId),
  }),
});

// 2. Format data into strict JSON:API specifications with side-loaded data
const mockArticles = [
  {
    id: "1",
    title: "The Will of Fire",
    body: "Believing in your dreams no matter what.",
    authorId: "7",
  },
];
const mockAuthors = [{ id: "7", name: "Naruto Uzumaki" }];

const output = serialize(mockArticles, articleResource, {
  include: {
    author: [mockAuthors, authorResource],
  },
  // Optional: Pass raw express/fastify query params for sparse fieldsets
  fields: fieldsFromQuery(req.query),
});

Output Target Shape:

{
  "data": [
    {
      "type": "articles",
      "id": "1",
      "attributes": {
        "title": "The Will of Fire",
        "body": "Believing in your dreams no matter what."
      },
      "relationships": {
        "author": {
          "data": { "type": "authors", "id": "7" }
        }
      }
    }
  ],
  "included": [
    {
      "type": "authors",
      "id": "7",
      "attributes": {
        "name": "Naruto Uzumaki"
      }
    }
  ],
  "meta": {
    "timestamp": "2026-06-13T18:20:33.243Z"
  }
}

Spec Compliance

jsonapi-nano is not a tutorial on JSON:API — see jsonapi.org for the full specification. Below is the current implementation status of serialize / createResource / serializeErrors against the spec.

| Feature | Status | Notes | | --------------------------------------------------- | -------------- | ----------------------------------------------------------------- | | data (resource objects, type/id/attributes) | ✅ Implemented | Core createResource + serialize | | meta (top-level and per-resource) | ✅ Implemented | Auto timestamp is opt-out via options.timestamp: false | | links (top-level and per-resource) | ✅ Implemented | | | relationships | ✅ Implemented | Semantic abstractions available via belongsTo helper | | included (compound documents) | ✅ Implemented | Fully resolved and deduped by type+id via options.include | | jsonapi top-level member | ✅ Implemented | Via serialize options | | errors array | ✅ Implemented | serializeErrors, includes source.pointer/parameter/header | | Sparse fieldsets (fields[type]) | ✅ Implemented | Fully supported via query utility filtering | | Pagination links/meta helpers | 🚧 Planned | Not yet supported | | Resource type validation | 🚧 Planned | No runtime validation of member-name format | | Error object id / links.about | 🚧 Planned | Not yet on ErrorConfig |

License

MIT © Emmanuel Gatwech