Nothing Pleases Me

    ts-json-api
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.0 • Public • Published

    ts-json-api

    A collection of TypeScript interfaces and classes for working with JSONAPI.org-standard requests/responses.

    Interfaces

    There library supports JSONAPI standard in all its variations. Therefore, there are a number of interfaces you may find useful.

    Response

    This is the main interface. It works with any acceptable combination of ResponseWithData, ResponseWithErrors, & ResponseWithMeta. If you need to target specifc response types, it is recommend you use those more specific interfaces (covered below).

    See also: ResponseWithData, ResponseWithErrors, and ResponseWithMeta.

    ResourceObject

    This represents a single ResourceObject in a JSONAPI response. See also: ResourceObjects and ResourceObjectOrObjects.

    Other interfaces

    Due to JSONAPI's nested structure, it is constructed of a decent number of individual pieces. We recommend taking a look at src/types/index.ts for reference. Should you need to target more specific pieces of a response, it should be pretty self-explanitory.

    Example Interface usage

    import { Relationship, ResourceObject, Response } as JsonApi from 'ts-json-api';
    
    interface Article extends ResourceObject {
        type: 'articles';
        attributes: {
            title: string;
        };
        relationships: {
            author: Relationship<Person>;
            comments: Relationship<Comment[]>;
        };
    }
    
    type ArticleItemResponse = Response<Article>;
    type ArticleCollectionResponse = Response<Article[]>;
    
    interface Person extends ResourceObject {
        type: 'people';
        attributes: {
            'firstName': string;
            'lastName': string;
            twitter: string;
        };
    }
    
    interface Comment extends ResourceObject {
        type: 'comments';
        attributes: {
            body: string;
        };
    }

    The ApiResourceObject class

    ts-json-api provides an ResourceObject class that is helpful for acessing Resource Object data and updating it in an immutable way. All functions on the ApiResourceObject class will return a new ResourceObject, unaffecting the original.

    Example Usage

    import { ApiResourceObject } from 'ts-json-api';
    
    const exampleInput = {
        "type": "articles",
        "id": "1",
        "attributes": {
          "title": "JSON API paints my bikeshed!"
        },
        "relationships": {
          "author": {
            "links": {
              "self": "http://example.com/articles/1/relationships/author",
              "related": "http://example.com/articles/1/author"
            },
            "data": { "type": "people", "id": "9" }
          },
          "comments": {
            "links": {
              "self": "http://example.com/articles/1/relationships/comments",
              "related": "http://example.com/articles/1/comments"
            },
            "data": [
              { "type": "comments", "id": "5" },
              { "type": "comments", "id": "12" }
            ]
          }
        },
        "links": {
          "self": "http://example.com/articles/1"
        }
      }
    };
    
    const article = new ApiResourceObject(exampleInput);
    
    console.log(article.type());
    // "articles"
    
    console.log(article.id());
    // "1"
    
    console.log(article.attributes());
    /// {
    ///     "title": "JSON API paints my bikeshed!"
    /// }
    
    console.log(article.attribute('title'));
    // "JSON API paints my bikeshed"
    
    const updatedArticle = article.update({ title: "New Title" });
    
    console.log(updatedArticle.attribute('title'));
    // "New Title"
    
    console.log(article.attribute('title'))
    // "JSON API paints my bikeshed"
    // > NOTE: The original `article` is not affected
    
    
    /**
     * Relationships
     */
    const relationships = article.relationships();
    
    console.log(relationships.author.id());
    // "9"
    // Note that all relationship(s)-fetching methods return ResourceObject/ResourceObjects representing those relationship objects
    
    console.log(
        relationships.comments[0].id(),
        relationships.comments[1].id()
    );
    // "5", "12"
    
    console.log(article.relationship('author').id());
    // "9"
    
    // You "add" a relationship when the relationship represents a collection (ie. comments).
    const updatedArticle = article.addRelationship('comments', 'comments', '432');
    const updatedArticle = article.addRelationship('comments', CommentResourceObject);
    
    // You "set" a relationships when the relationship represents a single item (ie. author)
    const updatedArticle = article.setRelationship('editor', 'people', '123');
    const updatedArticle = article.setRelationship('editor', PeopleResourceObject);
    
    // You can also remove a relationship
    const updatedArticle = article.removeRelationship('comments', '9');
    
    /**
     *  Other helpful methods
     */
    
    // Helpful for posting to an API and/or working with other libraries
    article.toJSON()
    
    // Maybe your API call doesn't want to include relationship info
    article.withoutRelationships().toJSON()

    Utility Functions

    This package exposes all of its useful utility functions. Documentation is coming, but feel free to browse around src/fp. All functions are curried for all you functional programming geeks.

    Keywords

    none

    Install

    npm i ts-json-api

    DownloadsWeekly Downloads

    3,190

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    118 kB

    Total Files

    29

    Last publish

    Collaborators

    • rmarganti