Design

While all datatypes returned in a CyclopsResponse are readonly, we can think of cyclops as returning two types of data, namely transient user state and cachable public data. For example the state of a User may change due to their interaction with the website, updating a subscription for example. On the other hand there is cachable data like the Catalogue (a big old JSON data structure that contains all Aller Media brands, products and deals) that is not expected to change due to user interation and is infact public (one can perform a GET request without any cookies)

For this reason cyclops-frontend-react exposes two separate contexts CyclopsUserContext and CyclopsDataContext.

CyclopsUserContext

ICyclopsUserContext; // interface
CyclopsUserContextProvider;
useCyclopsUserContext: () => ICyclopsUserContext;

The cyclopsUserContext ensures that any action that requires the User data to be reloaded is performed automatically. This means that you do not have to worry about the User object becoming stale. As an example:

import {
  useCyclopsUserContext,
  ICyclopsUserContext,
  CyclopsResponse,
  IUser,
} from 'cyclops-frontend-react';

export const MyComponent = () => {
  const context: ICyclopsUserContext = useCyclopsUserContext();
  /* the userResponse is guaranteed to have a boolean value `.loading`. */
  if (context.user.loading) {
    return <div>you spin me right round baby right round</div>;
  }
  if (context.user.error) {
    /*
    cyclops-front does not currently try to hide the errors
    insead it catches and wraps them in the response.
    Note that an error may be due to the network - or due to
    a schema validation error.
    */
    return <div>Ooops!</div>;
  }
  if (context.user.result) {
    return <div>Hello {context.user.result.fullName}</div>;
  }
  return <div>The unknown user</div>;
};

managed sessions

If you only need to add a login button to your page then you can use the CyclopsSessionButton. This is a compenent that relies upon the existance of the CyclopsUserContextProvider and handles login status for you.

CyclopsDataContext

ICyclopsDataContext; // interface
CyclopsDataContextProvider;
useCyclopsDataContext: () => ICyclopsDataContext;

The data context currently only contains the Catalogue datastructure. This data can only be fetched as is cachable. This context is most likely only interesting if you are working on the minside webpage.

Contracts (JSON spec)

One of the main responsibilities of this library is to provide a contract with cyclops-api - your one stop shop for all user related interactions.

Every response value from the api is verified using the ajv libray (JSON schema).

When an object returned from the cyclops-api is exposed to the user of this library it returned as a CyclopsResponse type. This actually means that the responses are not returned as Promises.

export interface CyclopsError {
  error: any;
}

export interface CyclopsResponse<T> {
  loading: boolean;
  result?: T;
  error?: CyclopsError;
}