Neolithic Prancing Minotaurs

    semantic-link
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.8 • Public • Published

    Semantic Link library

    A utility library for manipulating a list of links that form a semantic interface to a resource.

    This library is able to work with atom-like representations (ATOM is an XML-based document format). We use this to describe collections which describes lists of related information collections (in atom known as "feeds"). Collections (feeds in atom) are composed of a number of items (in atom known as "entries") each with an extensible set of attached metadata or attributes.

    The library has two aspects:

    1. Matching and filtering of link relations on a representation [filter,matches,getUri,getTitle]
    2. Sending and receiving across the wire via http (axios) based on above [get,put,post,delete, patch, tryGet]

    Representation

    Very simple examples

    import { getUri, matches, filter } from 'semantic-link';
    import * as semanticLink from 'semantic-link';
    
    const order = {
      links: [
        { rel: "self", href: "http://example.com/order/1" }
       ]
       title: "A first order"
     }
    
    getUri(order, /self/);                                // returns 'http://example.com/order/1'
    matches(order, /self/);                               // returns true
    filter(order, /self/);                                // returns order object
    
    semanticLink.get(order, /self/);                      // HTTP GET on self link to return representation (via axios)
    semanticLink.put(order, /self/, {title: 'Updated'});  // HTTP PUT on self link to send back data

    Installation

    Using yarn:

    $ yarn add semantic-link

    Note: this has a dependency on axios

    Usage

    //individually
    import { getUri, getTitle, matches, filter, get, put, post, del, patch, tryGet } from 'semantic-link';
    
    // as wildcard
    import * as semanticLink from 'semantic-link';

    Matching on link relations

    The basic interface for matching is to look for link rels on the representation.

    get(resource, 'self')
    get(resource, /self/)
    get(resource, /self|canonical/)
    post(resource, ['submit', 'self'])
    

    There are lots of ways to do this:

    • string: exact match on only that value
      • 'self'
    • regex: result of the regular expression
      • /self/ (anywhere)
      • /^self$/ (must match-same as string match)
      • /self|canonical/ (either)
      • /edit-form/
    • list of strings: exact match in order
      • ['self', 'submit']

    Note: you can have a list of regex too.

    Matching on media type (optional)

    The basic interface for matching can also be specific to media type.

    filter(resource, 'self')
    matches(resource, 'edit-form', 'text/uri-list')
    get(resource, 'self', 'application/json')
    post(resource, 'submit', 'application/json-patch+json', data)
    

    Note: When the media type is specified it must be found there is no fallback other types.

    Http (get,put,post,delete, patch, tryGet, link)

    This is just a light wrapper around axios and can have all the options of axios handed in.

    
    // Promise based
    
    get(resource, 'self')
        .then(response => {
            // type: AxiosResponse<LinkedRepresentation|CollectionRepresentation>
        })
        .then(err => {
            // type: AxiosError
        });
    
    // or async/await (or with error handling try/catch)
    
    const response = await get(resource, 'self');
    
    
    
    

    Cancellable (CancelToken)

    There is also a specific param for a Cancellable.

    import { CancelToken } from 'axios';
    
    const CancelToken = axios.CancelToken;
    const source = CancelToken.source();
    
    get(resource, 'self', 'application/json', source.token)
    
    source.cancel('Operation canceled by the user.');
    

    Note: access to axios is through the link interface (all the other methods call this) and the AxiosRequestConfig can overridden on the options. Also note, it is likely that you'd be better to use the axios interceptors. There are a couple of scenarios:

    1. 401 unauthorised should be implemented through interceptors, as well as setting of www-authenticate headers
    2. Semantic link uses an atom-like across-the-wire microformat (aka media type) and the same for in-memory It is recommended that to use this in-memory structure and translate between other microformats (eg HAL, SIREN, Collection+JSON)). This can be done through many ways (1) on the outside of the request/response (2) through interceptors and (3) on the AxiosRequestConfig. Any of these should work with the library.
    3. Throttling should be done outside of both of these mechanisms. It has been implemented with this utility using Bottleneck.

    License

    MIT

    Install

    npm i semantic-link

    DownloadsWeekly Downloads

    1

    Version

    1.0.8

    License

    MIT

    Unpacked Size

    94.5 kB

    Total Files

    26

    Last publish

    Collaborators

    • semanticlink