ts:japi

A highly-modular (typescript-friendly)-framework agnostic library for serializing data to the JSON:API specification

• ts:japi
  • Features
  • Installation
  • Getting Started
    • Examples
  • Serialization
    • Links
      • Pagination
    • Relationships
    • Metadata
    • Serializing Errors
    • Caching
  • Deserialization
  • API Reference
    • Serializer
    • Relator
    • Linker
    • Metaizer
    • Paginator
    • ErrorSerializer
    • Cache
    • PolymorphicSerializer
    • JapiError
  • Remarks
  • FAQ
  • For Developers
  • Contributing
  • License

Features

• This is the only typescript-compatible library that fully types the JSON:API specification and performs proper serialization.
• Zero dependencies.
• This is the only library with resource recursion.
• The modular framework laid out here highly promotes the specifications intentions:
  • Using links is no longer obfuscated.
  • Meta can truly be placed anywhere with possible dependencies laid out visibly.
• This library is designed to adhere to the specifications "never remove, only add" policy, so we will remain backwards-compatible.

Installation

npm install ts-japi

Getting Started

There are several classes used to serialize data (only Serializer is strictly required):

• Serializer — primary resource serialization
• Relator — relationships and included resources
• Linker — document and resource links
• Metaizer — metadata at any level
• Paginator — pagination links
• ErrorSerializer — error serialization
• Cache — response caching
• PolymorphicSerializer — polymorphic resource serialization

Examples

See the examples and test directories for usage. The full example shows nearly every Serializer option in use.

Serialization

Serializer is the only class required for basic serialization.

import { Serializer } from 'ts-japi';

const UserSerializer = new Serializer('users');

const user = { id: 'sample_user_id', createdAt: new Date() };

console.log(await UserSerializer.serialize(user));
// {
//   jsonapi: { version: '1.0' },
//   data: {
//     type: 'users',
//     id: 'sample_user_id',
//     attributes: { createdAt: '2020-05-20T15:44:37.650Z' }
//   }
// }

Links

Linker generates normalized document links. Its methods are not meant to be called directly — pass it to a serializer option.

import { Linker } from 'ts-japi';

const UserArticleLinker = new Linker((user: User, articles: Article | Article[]) => {
  return Array.isArray(articles)
    ? `https://www.example.com/users/${user.id}/articles/`
    : `https://www.example.com/users/${user.id}/articles/${articles.id}`;
});

Pagination

Paginator generates pagination links.

import { Paginator } from 'ts-japi';

const ArticlePaginator = new Paginator((articles: Article | Article[]) => {
  if (Array.isArray(articles)) {
    const nextPage = Number(articles[0].id) + 1;
    const prevPage = Number(articles[articles.length - 1].id) - 1;
    return {
      first: `https://www.example.com/articles/0`,
      last: `https://www.example.com/articles/10`,
      next: nextPage <= 10 ? `https://www.example.com/articles/${nextPage}` : null,
      prev: prevPage >= 0 ? `https://www.example.com/articles/${prevPage}` : null,
    };
  }
  return;
});

Use it via SerializerOptions.linkers.paginator.

Relationships

Relator generates top-level included data and resource-level relationships.

import { Serializer, Relator } from 'ts-japi';

const ArticleSerializer = new Serializer<Article>('articles');
const UserArticleRelator = new Relator<User, Article>(
  async (user) => user.getArticles(),
  ArticleSerializer
);

const UserSerializer = new Serializer<User>('users', {
  relators: UserArticleRelator,
});

Relator also accepts optional Linkers via the linkers option to define relationship and related resource links.

Metadata

Metaizer generates metadata. It can be used in:

• ErrorSerializerOptions.metaizers
• RelatorOptions.metaizer
• SerializerOptions.metaizers
• LinkerOptions.metaizer

import { Metaizer } from 'ts-japi';

const UserArticleMetaizer = new Metaizer((user: User, articles: Article | Article[]) => {
  return Array.isArray(articles)
    ? { user_created: user.createdAt, article_created: articles.map((a) => a.createdAt) }
    : { user_created: user.createdAt, article_created: articles.createdAt };
});

Serializing Errors

ErrorSerializer serializes any object as an error. Alternatively (recommended), extend JapiError to construct typed server errors.

import { ErrorSerializer } from 'ts-japi';

const PrimitiveErrorSerializer = new ErrorSerializer();

console.log(PrimitiveErrorSerializer.serialize(new Error('badness')));
// {
//   errors: [ { code: 'Error', detail: 'badness' } ],
//   jsonapi: { version: '1.0' }
// }

Caching

Set cache: true in SerializerOptions for a default Cache, or pass a Cache instance for custom equality logic.

import { Serializer, Cache } from 'ts-japi';

const MyCache = new Cache({ resolver: (a, b) => a?.id === b?.id });
const UserSerializer = new Serializer('users', { cache: MyCache });

Deserialization

This library does not provide deserialization. Many clients already consume JSON:API endpoints (see implementations), and unmarshalling data is typically coupled to framework-specific code (e.g. React state). Tighter integration is recommended over an unnecessary abstraction.

API Reference

Serializer

new Serializer<PrimaryType>(collectionName: string, options?: Partial<SerializerOptions<PrimaryType>>)

Methods:

Method	Description
serialize(data, options?)	Serializes primary data. Returns a Promise<DataDocument>.
getRelators()	Returns the relators associated with this serializer.
setRelators(relators)	Sets relators (useful for breaking cyclic dependencies).
getIdKeyFieldName()	Returns the name of the id field.

SerializerOptions<PrimaryType>:

Option	Type	Default	Description
idKey	keyof PrimaryType	"id"	The field name for the resource ID.
version	string | null	"1.0"	JSON:API version. Set to null to omit.
relators	Relator | Relator[] | Record<string, Relator>	—	Relators that generate relationships and included resources.
linkers.document	Linker	—	Linker for the top-level self link.
linkers.resource	Linker	—	Linker for the resource-level self link.
linkers.paginator	Paginator	—	Paginator for pagination links.
metaizers.jsonapi	Metaizer	—	Metadata for the JSON:API object.
metaizers.document	Metaizer	—	Metadata for the top-level document.
metaizers.resource	Metaizer	—	Metadata for each resource object.
include	number | string[]	0	Which relationships to include. A number includes all relationships up to that depth. An array of paths includes only those paths (e.g. ['articles', 'articles.comments']). Takes precedence over depth.
depth	number	0	Depth of relators to recurse for included resources. Deprecated — use include instead.
projection	Partial<Record<keyof PrimaryType, 0 | 1>> | null | undefined	null	Attribute projection. All 0s to hide, all 1s to show. null shows all. undefined omits attributes.
cache	boolean | Cache	false	Enables response caching.
onlyIdentifier	boolean	false	Serializes only resource identifier objects (no attributes).
onlyRelationship	string	false	Serializes only the relationship linkage for the named relator.
nullData	boolean	false	Forces data to be null.
asIncluded	boolean	false	Moves primary data to included and uses identifier objects for data.

Relator

new Relator<PrimaryType, RelatedType>(
  fetch: (data: PrimaryType) => Promise<RelatedType | RelatedType[] | null | undefined>,
  serializer: Serializer<RelatedType> | (() => Serializer<RelatedType>),
  options?: Partial<RelatorOptions<PrimaryType, RelatedType>>
)

Passing a getter function () => Serializer instead of a Serializer instance breaks circular references between serializers. When using a getter, options.relatedName is required.

RelatorOptions<PrimaryType, RelatedType>:

Option	Type	Description
linkers.relationship	Linker<[PrimaryType, RelatedType | RelatedType[] | null | undefined]>	Linker for the relationship self link.
linkers.related	Linker<[PrimaryType, RelatedType | RelatedType[] | null | undefined]>	Linker for the related resource link.
metaizer	Metaizer<[PrimaryType, RelatedType | RelatedType[] | null | undefined]>	Metaizer for relationship metadata.
relatedName	string	Override for the relationship name (defaults to the serializer's collection name). Required when passing a serializer getter.

Linker

new Linker<Dependencies>(
  link: (...args: Dependencies) => string,
  options?: LinkerOptions<Dependencies>
)
// where Dependencies extends any[]

LinkerOptions<Dependencies>:

Option	Type	Description
metaizer	Metaizer<Dependencies>	Adds meta to the link object.

Metaizer

new Metaizer<Dependencies>(
  metaize: (...args: Dependencies) => Record<string, unknown> | Promise<Record<string, unknown>>
)
// where Dependencies extends any[]

Paginator

new Paginator<DataType>(
  paginate: (data: DataType | DataType[]) => {
    first?: string | null;
    last?: string | null;
    prev?: string | null;
    next?: string | null;
  } | undefined
)

The callback returns an object with optional first, last, prev, next string URLs (or null to explicitly omit a link).

ErrorSerializer

new ErrorSerializer<ErrorType>(options?: Partial<ErrorSerializerOptions<ErrorType>>)

Methods:

Method	Description
serialize(errors, options?)	Serializes one or more errors synchronously. Returns an ErrorDocument.

By default, ErrorSerializer maps fields from standard Error objects:

Error field	JSON:API field
name	code
message	detail
id	id
code	status
reason	title
location	source.pointer

ErrorSerializerOptions<ErrorType>:

Option	Type	Description
attributes.id	keyof ErrorType	Field to use for error id. Default: "id"
attributes.status	keyof ErrorType	Field to use for HTTP status. Default: "code"
attributes.code	keyof ErrorType	Field to use for error code. Default: "name"
attributes.title	keyof ErrorType	Field to use for error title. Default: "reason"
attributes.detail	keyof ErrorType	Field to use for error detail. Default: "message"
attributes.source.pointer	keyof ErrorType	Field for JSON Pointer source. Default: "location"
attributes.source.parameter	keyof ErrorType	Field for query parameter source. Default: undefined
attributes.source.header	keyof ErrorType	Field for header source. Default: undefined
linkers.about	Linker<[JapiError]>	Linker for the error about link.
metaizers.jsonapi	Metaizer<[]>	Metadata for the JSON:API object.
metaizers.document	Metaizer<[JapiError[]]>	Metadata for the top-level document.
metaizers.error	Metaizer<[JapiError]>	Metadata for each error object.
version	string | null	JSON:API version. Default: "1.0"

Cache

new Cache<PrimaryType>(options?: Partial<CacheOptions<PrimaryType>>)

CacheOptions<PrimaryType>:

Option	Type	Default	Description
limit	number	10	Maximum number of documents to store before evicting the oldest.
resolver	(stored, incoming) => boolean	Object.is	Equality function to determine cache hits.

PolymorphicSerializer

Serializes a mixed array of resources that share a common discriminant field. Each type is routed to its own Serializer.

new PolymorphicSerializer<PrimaryType>(
  commonName: string,
  key: keyof PrimaryType,
  serializers: Record<string, Serializer> | Record<string, () => Serializer>
)

Example:

import { PolymorphicSerializer, Serializer } from 'ts-japi';

const DogSerializer = new Serializer('dogs');
const CatSerializer = new Serializer('cats');

const AnimalSerializer = new PolymorphicSerializer('animals', 'type', {
  dog: DogSerializer,
  cat: CatSerializer,
});

const animals = [
  { id: '1', type: 'dog', name: 'Rex' },
  { id: '2', type: 'cat', name: 'Whiskers' },
];

console.log(await AnimalSerializer.serialize(animals));

JapiError

Extend JapiError to create typed errors that pass through ErrorSerializer unchanged.

import { JapiError, ErrorSerializer } from 'ts-japi';

class NotFoundError extends JapiError {
  constructor(id: string) {
    super({ status: '404', code: 'NOT_FOUND', title: 'Not Found', detail: `Resource ${id} not found` });
  }
}

const serializer = new ErrorSerializer();
console.log(serializer.serialize(new NotFoundError('42')));
// { errors: [{ status: '404', code: 'NOT_FOUND', title: 'Not Found', detail: 'Resource 42 not found' }], jsonapi: { version: '1.0' } }

JapiError fields:

Field	Type	Description
id	string	Unique identifier for this error occurrence.
status	string	HTTP status code as a string.
code	string	Application-specific error code.
title	string	Short, human-readable summary (should not change between occurrences).
detail	string	Human-readable explanation of this specific occurrence.
source.pointer	string	JSON Pointer to the source field (e.g. /data/attributes/name).
source.parameter	string	Query parameter that caused the error.
source.header	string	Request header that caused the error.
links	object	Links object (e.g. about link).
meta	object	Non-standard meta information.

Remarks

There are several model classes used inside TS:JAPI such as Resource and Relationships. These models are used for normalization as well as traversing a JSON:API document. If you plan to fork this repo, you can extend these models and reimplement them to create your own custom (non-standard, extended) serializer.

FAQ

Why not just allow optional functions that return the internal Link Class (or just a URI string)?

The Link class is defined to be as general as possible in case of changes in the specification. In particular, the implementation of metadata and the types in our library rely on the generality of the Link class. Relying on user arguments will generate a lot of overhead for both us and users whenever the specs change.

Why does the Meta class exist if it is essentially just a plain object?

In case the specification is updated to change the meta objects in some functional way.

What is "resource recursion"?

Due to compound documents, it is possible to recurse through related resources via their resource linkages and obtain included resources beyond primary data relations. Use the include or depth option on Serializer with caution — deep recursion can degrade performance significantly.

For Developers

To get started in developing this library, run pnpm install, pnpm build and pnpm test (in this precise order) to assure everything is in working order.

Contributing

This project is maintained by the author, however contributions are welcome and appreciated. You can find TS:JAPI on GitHub: https://github.com/mathematic-inc/ts-japi

Feel free to submit an issue, but please do not submit pull requests unless it is to fix some issue. Feel free to open an issue if you find a bug.

License

Copyright © 2020 mathematic-inc.

Licensed under Apache 2.0.

This project is free and open-source work by a 501(c)(3) non-profit. If you find it useful, please consider donating.