schema.Entity

If you already have classes for your data-types, schema.Entity mixin may be for you.

import { schema } from '@rest-hooks/rest';

export class Article {
  id = '';
  title = '';
  content = '';
  tags: string[] = [];
}

export class ArticleEntity extends schema.Entity(Article) {}

Options

The second argument to the mixin can be used to conveniently customize construction. If not specified the Base class' static members will be used. Alternatively, just like with Entity, you can always specify these as static members of the final class.

class User {
  username = '';
  createdAt = new Date(0);
}
class UserEntity extends schema.Entity(User, {
  pk: 'username',
  key: 'User',
  schema: { createdAt: Date },
}) {}

pk: string | (value, parent?, key?) => string | undefined = 'id'

Specifies the Entity.pk

A string indicates the field to use for pk.

A function is used just like Entity.pk, but the first argument (value) is this

Defaults to 'id'; which means pk is a required option unless the Base class has a serializable id member.

multi-column

class Thread {
  forum = '';
  slug = '';
  content = '';
}
class ThreadEntity extends schema.Entity(Thread, {
  pk(value) {
    return [value.forum, value.slug].join(',');
  },
}) {}

key: string

Specifies the Entity.key

schema: {[k:string]: Schema}

Specifies the Entity.schema

Methods

schema.Entity has the same methods as Entity with an improved mergeWithStore() lifecycle.

This method uses shouldReorder() to handle race conditions rather than useIncoming(), which is better able to handle partial field entities.

Eventually Entity will also be converted to use this default implementation. You can prepare for this by copying the mergeWithStore default implementation below.

static mergeWithStore(existingMeta, incomingMeta, existing, incoming): mergedValue

static mergeWithStore(
  existingMeta: {
    date: number;
    fetchedAt: number;
  },
  incomingMeta: { date: number; fetchedAt: number },
  existing: any,
  incoming: any,
) {
  const useIncoming = this.useIncoming(
    existingMeta,
    incomingMeta,
    existing,
    incoming,
  );

  if (useIncoming) {
    // distinct types are not mergeable (like delete symbol), so just replace
    if (typeof incoming !== typeof existing) {
      return incoming;
    } else {
      return this.shouldReorder(
        existingMeta,
        incomingMeta,
        existing,
        incoming,
      )
        ? this.merge(incoming, existing)
        : this.merge(existing, incoming);
    }
  } else {
    return existing;
  }
}

mergeWithStore() is called during normalization when a processed entity is already found in the store.

This calls useIncoming(), shouldReorder() and potentially merge()

static useIncoming(existingMeta, incomingMeta, existing, incoming): boolean

static useIncoming(
  existingMeta: { date: number; fetchedAt: number },
  incomingMeta: { date: number; fetchedAt: number },
  existing: any,
  incoming: any,
) {
  return true;
}

Preventing updates

useIncoming can also be used to short-circuit an entity update.

import deepEqual from 'deep-equal';

class ArticleEntity extends schema.Entity(
  class {
    id = '';
    title = '';
    content = '';
    published = false;
  },
) {
  static useIncoming(
    existingMeta: { date: number; fetchedAt: number },
    incomingMeta: { date: number; fetchedAt: number },
    existing: any,
    incoming: any,
  ) {
    return !deepEqual(incoming, existing);
  }
}

static shouldReorder(existingMeta, incomingMeta, existing, incoming): boolean

static shouldReorder(
  existingMeta: { date: number; fetchedAt: number },
  incomingMeta: { date: number; fetchedAt: number },
  existing: any,
  incoming: any,
) {
  return incomingMeta.fetchedAt < existingMeta.fetchedAt;
}

true return value will reorder incoming vs in-store entity argument order in merge. With the default merge, this will cause the fields of existing entities to override those of incoming, rather than the other way around.

Example

class LatestPriceEntity extends schema.Entity(
  class {
    id = '';
    updatedAt = 0;
    price = '0.0';
    symbol = '';
  },
) {
  static shouldReorder(
    existingMeta: { date: number; fetchedAt: number },
    incomingMeta: { date: number; fetchedAt: number },
    existing: { updatedAt: number },
    incoming: { updatedAt: number },
  ) {
    return incoming.updatedAt < existing.updatedAt;
  }
}

static merge(existing, incoming): mergedValue

static merge(existing: any, incoming: any) {
  return {
    ...existing,
    ...incoming,
  };
}

Merge is used to handle cases when an incoming entity is already found. This is called directly when the same entity is found in one response. By default it is also called when mergeWithStore() determines the incoming entity should be merged with an entity already persisted in the Rest Hooks store.

const vs class

If you don't need to further customize the entity, you can use a const declaration instead of extend to another class.

There is a subtle difference when referring to the class token in TypeScript - as class declarations will refer to the instance type; whereas const tokens refer to the value, so you must use typeof, but additionally typeof gives the class type, so you must layer InstanceType on top.

import { schema } from '@rest-hooks/rest';

export class Article {
  id = '';
  title = '';
  content = '';
  tags: string[] = [];
}

export class ArticleEntity extends schema.Entity(Article) {}
export const ArticleEntity2 = schema.Entity(Article);

const article: ArticleEntity = ArticleEntity.fromJS();
const articleFails: ArticleEntity2 = ArticleEntity2.fromJS();
const articleWorks: InstanceType<typeof ArticleEntity2> =
  ArticleEntity2.fromJS();