Skip to main content

Upgrading from 5 to 6

npm install --save rest-hooks@6 @rest-hooks/rest@3

Highlights

Package compatibility

Be sure to upgrade these packages prior to upgrading Rest Hooks itself. They maintain compatibility with rest hooks 5.

Upgrade at the same time:

@rest-hooks/rest 3.0 drops compatibility with older versions, so this will have to be upgraded in unison. All breaking changes are listed below

caution

Due to a bug in npm 7, it might install multiple peerDeps (@rest-hooks/normalizr). If this happens, you can fix by completely uninstalling rest hooks packages and then reininstalling:

npm uninstall rest-hooks @rest-hooks/rest
npm install --save rest-hooks@6 @rest-hooks/rest@3

Exports moved to @rest-hooks/legacy.

FlatEntity, SimpleRecord, NestedEntity, schemas, isEntity, Entity, Resource, SimpleResource, SchemaDetail, SchemaList, Method

These are still supported! They are simply moved to @rest-hooks/legacy. This allows smooth incremental migrations.

  1. yarn add @rest-hooks/[email protected]

    has all of these, and is compatible with both rest-hooks 5 and 6.

  2. Upgrade rest-hooks to 6 & @rest-hooks/legacy to 3.

  3. Gradually migrate to @rest-hooks/rest

Importing directly from hidden files is no longer supported

All packages now use package exports, which if supported disallow importing directly from any sub path like rest-hooks/lib/react-integration/hooks/useSuspense

Doing this was never supported as file locations would change without announcement. However, now with tooling that supports package exports, it will not work at all.

Store state internals

Entities no longer normalize to their class. Class construction is now done during denormalization step. This means the internal state of Rest Hooks is a POJO. This improves serialization. However, it does mean relying on the internal state in a Manager to be a class will break. Additionally the expected serialization of Rest Hooks store will be slightly different, which could affect snapshot tests or persistance efforts like using IndexedDB.

@rest-hooks/endpoint changes

SimpleRecord -> Object

SimpleRecord was removed (though available in @rest-hooks/legacy)

Object can be used instead

export class Address extends SimpleRecord {
readonly street: string = '';
readonly suite: string = '';
readonly city: string = '';
readonly zipcode: string = '';
readonly createdAt: Date = new Date(0);

static schema = {
createdAt: Date,
};
}

@rest-hooks/rest changes from 2 -> 3

These add on to the existing changes of @rest-hooks/rest from @rest-hooks/legacy

  • If Resource.fromJS() was used to customize normalization process, use process() instead.

     class MyResource extends Resource {
    static process(input: any, parent: any, key: string | undefined): any {
    return {
    ...input,
    extraThing: 5,
    };
    }
    }
  • New default error behavior

    To keep existing
    class MyResource extends Resource {
    static getEndpointExtra(): EndpointExtraOptions | undefined {
    return {
    errorPolicy: error => 'soft' as const,
    };
    }
    }

Full list of changes

Node >=12

Node 12 is now the minimum version required. This only applies if Rest Hooks is actually used within node. (SSR or testing are likely cases.)

@rest-hooks/endpoint

Entity

  • fromJS() -> process() to customize init
  • normalize results in POJO rather than instances
    • This is only meaningful for those inspecting the rest hooks state directly
  • FlatEntity, SimpleRecord removed (use @rest-hooks/legacy)

@rest-hooks/rest

  • peerDep @rest-hooks/endpoint > 2

@rest-hooks/core

  • buildInferredResult -> inferResults

  • Error behavior

    • useError() will no longer create synthetic errors for missing entities

    • useError() errorPolicy

      EndpointExtraOptions

      interface EndpointExtraOptions {
      //...rest
      errorPolicy?: (error: any) => 'soft' | undefined;
      }

      'soft' vs undefined

      • 'soft' avoids errors if existing results are still available (even if stale)
      • undefined (hard error) means any error always falls

      @rest-hooks/rest

      New default policy: 5xx are soft, else hard.

      @rest-hooks/rest is where errors have 'status' members. This concept does not exist in base Endpoints.

        static getEndpointExtra(): EndpointExtraOptions | undefined {
      return;
      return {
      errorPolicy: error =>
      error.status >= 500 ? ('soft' as const) : undefined,
      };
      }

      PollingSubscription

                // never break when data already exists
      errorPolicy: () => 'soft' as const,

      @rest-hooks/legacy - Resource

      Existing policy was to always be 'soft' no matter what. This maintains that behavior.

        /** @deprecated */
      /** Get the request options for this SimpleResource */
      static getFetchOptions(): FetchOptions | undefined {
      return {
      errorPolicy: () => 'soft' as const,
      };
      }

      https://github.com/data-client/rest-hooks/pull/971

    • polled fetch errors are always 'soft'

    • @rest-hooks/rest

      • 5xx: 'soft'
      • 4xx, 3xx, etc: 'hard'
  • peerDep @rest-hooks/endpoint > 2

rest-hooks

Removed exports from 'rest-hooks': NestedEntity, schemas, isEntity, Entity, Resource, SimpleResource, SchemaDetail, SchemaList, Method

  • use @rest-hooks/legacy, or @rest-hooks/rest instead

@rest-hooks/legacy

  • peerDep @rest-hooks/endpoint > 2

Full Release notes

Support

If you have any trouble upgrading, you can get some help from the community discord Chat

If you find any bugs or other issues, feel free to open a github ticket