Migration guide

This guide allows you to know how to migrate from @lagoshny/ngx-hal-client to @lagoshny/ngx-hateoas-client. Why you may need does it see in the motivation section.

Motivation

The main reason to create a new hateoas library is @lagoshny/ngx-hal-client was a fork from angular4-hal library and now angular4-hal is not supported. To adds new features or refactoring fork version @lagoshny/ngx-hal-client is not the right way because it inherits all code from parent angular4-hal and the main problem is angular4-hal has not a good documentation and has some not documented features.

Lack of tests and documentation does not allow refactoring, implementing new functions and developing the old project. New library rewritten taking only the best principles from @lagoshny/ngx-hal-client fork.

Some new features:

A simplified configuration: now you inject configuration service and pass configuration as JS object instead of create a standalone configuration class with configuration interface implementation. See more in configuration.
Added ability to debug library with logging feature.
Changed support for subtypes now is not need to pass subtypes object to method param because each Resource class has own resource type.
Added HateoasResourceService is standalone generic resource service, only need to set generic param to resource type and use it without create a resource service class.
Added support for resource projection
Added more than 400 tests.
Added documentation describing all library features.
And much more.

It is strongly recommend migrate from @lagoshny/ngx-hal-client to @lagoshny/ngx-hateoas-client to be able to use new features.

Old @lagoshny/ngx-hal-client will not develop, will only bug fixes.

Migration steps

The first migration step is delete @lagoshny/ngx-hal-client from package.json file and install @lagoshny/ngx-hateoas-client by the command
```
npm i @lagoshny/ngx-hateoas-client --save
```
After that delete old @lagoshny/ngx-hal-client configuration and add a new @lagoshny/ngx-hateoas-client configuration using the same configuration params.
Now need change class imports from @lagoshny/ngx-hal-client to @lagoshny/ngx-hateoas-client.

To do it you can use replaceAll command with a code editor.
Do all RestService changes described below.

Find info about methods param changes in this section.
Do all Resource changes described below.
Do all EmbeddedResource changes described below.

Find info about methods param changes in this section.
Do all ResourcePage changes described below

Find info about methods param changes in this section.

Congratulations! It is all that you need to do to migrate to @lagoshny/ngx-hateoas-client.

You can found an example of the migration process by this commit from one of my applications.

If you have some questions or found a bug you can create new issue here.

Library changes

This section describes the main library changes compare with @lagoshny/ngx-hal-client library.

Configuration

The next changes were in the lib configuration:

The old configuration ExternalConfigService class was delete. Added new NgxHateoasClientConfigurationService class has the method configure to pass app configuration. How configure library with NgxHateoasClientConfigurationService see here.

RestService

Class RestService renamed to HateoasResourceOperation.

Common changes

The next common changes was in RestService (now is HateoasResourceOperation class):

Deleted constructor params: injector and resourceName, now only type param.
Deleted page methods: totalElement, totalPages, hasFirst, hasNext, hasPrev, hasLast, next, prev, first, last, page. See PagedResourceCollection to use these methods.
Deleted getByRelation and getByRelationArray use getRelation and getRelatedCollection from Resource class instead.
Deleted customQueryPost use customQuery instead.
Deleted count use customQuery instead.
Deleted getBySelfLink use getResource instead

Get changes

Renamed get to getResource and changed method signature:

Was:

get(id: any, params?: HalParam[]): Observable<T>;

Now:

getResource(id: number | string, options?: GetOption): Observable<T>;

Changed id param type from any to number|string
Renamed params to options and changed type from HalParam[] to GetOption.

See more about GetResource method here.

GetAll changes

Renamed getAll to getCollection and changed method signature:

Was:

getAll(options?: HalOptions, subType?: SubTypeBuilder): Observable<T[]>;

Now:

getCollection(options?: GetOption): Observable<ResourceCollection<T>>;

Changed options type from HalOptions to GetOption, see here how to change HalOptions to GetOption.
Deleted subType param, subtypes support, see here.

See more about GetCollection method here.

GetAllPage changes

Renamed getAllPage to getPage and changed method signature:

Was:

getAllPage(options?: HalOptions, subType?: SubTypeBuilder): Observable<ResourcePage<T>>;

Now:

getPage(options?: PagedGetOption): Observable<PagedResourceCollection<T>>;

Changed options type from HalOptions to PagedGetOption, see here how to change HalOptions to PagedGetOption.
Deleted subType param, subtypes support, see here.
Changed return value from ResourcePage to PagedCollectionResource see classes changes.

See more about GetPage method here.

Search changes

Renamed search to searchCollection and changed method signature:

Was:

search(query: string, options?: HalOptions, subType?: SubTypeBuilder): Observable<T[]>;

Now:

searchCollection(query: string, options?: GetOption): Observable<ResourceCollection<T>>;

Changed options type from HalOptions to GetOption, see here how to change HalOptions to GetOption.
Deleted subType param, subtypes support, see here.
Changed return type from Array<Resource> to ResourceCollection.

See more about SearchCollection method here.

SearchPage changes

searchPage changed method signature:

Was:

searchPage(query: string, options?: HalOptions, subType?: SubTypeBuilder): Observable<ResourcePage<T>>;

Now:

searchPage(query: string, options?: PagedGetOption): Observable<PagedResourceCollection<T>>;

Changed options type from HalOptions to PagedGetOption, see here how to change HalOptions to PagedGetOption.
Deleted subType param, subtypes support, see here.
Changed return type from ResourcePage to PagedCollectionResource.

See more about SearchPage method here.

SearchSingle changes

Renamed searchSingle to searchResource and changed method signature:

Was:

searchSingle(query: string, options?: HalOptions): Observable<T>;

Now:

searchResource(query: string, options?: GetOption): Observable<T>;

Changed options type from HalOptions to GetOption, see here how to change HalOptions to GetOption.

See more about SearchResource method here.

CustomQuery changes

customQuery changed method signature:

Was:

customQuery(query: string, options?: HalOptions, subType?: SubTypeBuilder): Observable<T[]>;

Now:

customQuery<R>(method: HttpMethod, query: string, requestBody?: RequestBody<any>, options?: PagedGetOption): Observable<R>;

Added generic param <R> that define return type instead of old Array<Resource>.
Added method param that defined the HTTP query method.
Added requestBody param allows pass request body (used with PATCH, PUT, POST methods).
Changed options type from HalOptions to PagedGetOption, see here how to change HalOptions to PagedGetOption.
Deleted subType param, subtypes support, see here.

See more about CustomQuery method here.

Create changes

Renamed create to createResource and changed method signature:

Was:

create(entity: T);

Now:

createResource(requestBody: RequestBody<T>): Observable<T>;

Renamed entity param to requestBody and changed type from T to RequestBody.

See more about CreateResource method here.

Update changes

Renamed update to updateResource and changed method signature:

Was:

update(entity: T);

Now:

updateResource(entity: T, requestBody?: RequestBody<any>): Observable<T | any>;

Added RequestBody param to pass part of entity values to change.

See more about UpdateResource method here.

Patch changes

Renamed patch to patchResource and changed method signature:

Was:

patch(entity: T, options?: Array<ResourceOptions> | Include);

Now:

patchResource(entity: T, requestBody?: RequestBody<any>): Observable<T | any>;

Changed options type to requestBody.

See more about PatchResource method here.

Delete changes

Renamed delete to deleteResource and changed method signature:

Was:

delete(entity: T): Observable<object>;

Now:

deleteResource(entity: T, options?: RequestOption): Observable<HttpResponse<any> | any>;

Added options param with type RequestOption that allowed to define request return type observe or response and pass request params.

See more about DeleteResource method here.

HandleError changes

Deleted handleError method, if you need, define the same method in your project:

handleError is simple wrapper:

    protected handleError(error: any): Observable<never> {
      return observableThrowError(error);
    }

Resource

This section contains Resource class changes.

Now each Resource class should have a @HateasoResource decorator that accepts resourceName param. You cas see more about this here

Was:

export class Product extends Resource {
  ...
}

Now:

@HateoasResource('products')
export class Product extends Resource {
  ...
}

GetRelation changes

getRelation method signature changes:

Was:

getRelation<T extends BaseResource>(type: {new (): T;}, relation: string, builder?: SubTypeBuilder, expireMs?: number, isCacheActive?: boolean): Observable<T>;

Now:

getRelation<T extends BaseResource>(relationName: string, options?: GetOption): Observable<T>;

Renamed relation param to relationName.
Deleted type, builder (more about subtypes here), expireMs, isCacheActive (more about cache support here).
Added options GetOption param.

See more about GetRelation method here.

GetProjection changes

Removed getProjection method, use getRelation with options: {params: {projection: 'projectionName'}}.

See more about GetRelation method here.

GetRelationArray changes

Renamed getRelationArray to getRelatedCollection and changed method signature:

Was:

getRelationArray<T extends BaseResource>(type: { new(): T }, relation: string, options?: HalOptions, embedded?: string, builder?: SubTypeBuilder, expireMs: number = 0, isCacheActive: boolean = true): Observable<T[]>;

Now:

getRelatedCollection<T extends ResourceCollection<BaseResource>>(relationName: string, options?: GetOption): Observable<T>;

Renamed relation param to relationName.
Deleted type, embedded (is not supported anymore), builder (more about subtypes here), expireMs, isCacheActive (more about cache support here).
Changed options type from HalOptions to GetOption, see here how to change HalOptions to GetOption.
Changed return type from Array<Resource> to ResourceCollection.

See more about GetRelatedCollection method here.

GetProjectionArray changes

Removed getProjectionArray method, use getRelatedCollection with options: {params: {projection: 'projectionName'}}.

See more about GetRelatedCollection method here.

AddRelation changes

addRelation changed method name and signature:

Was:

addRelation<T extends BaseResource>(relation: string, resource: T): Observable<any>;

Now:

addCollectionRelation<T extends Resource>(relationName: string, entities: Array<T>): Observable<HttpResponse<any>>;

Renamed relation param to relationName.
Renamed resource param to entities and changed param type to an array.

See more about addCollectionRelation method here.

SubstituteRelation changes

Renamed substituteRelation to bindRelation and some method changes:

Renamed relation param to relationName.
Renamed resource param to entities and changed param type to an array.

See more about BindRelation method here.

DeleteRelation changes

deleteRelation method changes:

Renamed param relation to relationName
Renamed param resource to entitiy

See more about DeleteRelation method here.

ClearCollectionRelation changes

Renamed clearCollectionRelation to unbindCollectionRelation and some method changes:

Renamed relation param to relationName.

See more about unbindCollectionRelation method here.

PostRelation changes

postRelation changed method signature:

Was:

postRelation(relation: string, body: any, options?: LinkOptions): Observable<any>;

Now:

postRelation(relationName: string, requestBody: RequestBody<any>, options?: RequestOption): Observable<any>;

Renamed relation to relationName.
Renamed body param to requestBody and change type from any to RequestBody.
Change options param type from LinkOptions to RequestOption.

See more about PostRelation method here.

PatchRelation changes

patchRelation changed method signature:

Was:

patchRelation(relation: string, body: any, options?: LinkOptions): Observable<any>;

Now:

patchRelation(relationName: string, requestBody: RequestBody<any>, options?: RequestOption): Observable<any>;

Renamed relation to relationName.
Renamed body param to requestBody and change type from any to RequestBody.
Change options param type from LinkOptions to RequestOption.

See more about PatchRelation method here.

EmbeddedResource changes

Now each EmbeddedResource class should have a @HateasoEmbeddedResource decorator that accepts relationNames param. You cas see more about this here

Was:

export class Client extends Resource {
  ...
  public clientAddress: Address;
  ...
}

export class Address extends EmbeddedResource {
  ...
}

Now:

@HateoasResource('clients')
export class Client extends Resource {
...
  public clientAddress: Address;
...
}

@HateoasEmbeddedResource(['clientAddress'])
export class Address extends EmbeddedResource {
  ...
}

ResourcePage changes

ResourcePage class renamed to PagedCollectionResource and has the next changes:

SortElements changes

sortElements changed method signature:

Was:

sortElements(...sort: Sort[]): Observable<ResourcePage<T>>;

Now:

sortElements(sortParam: Sort, options?: { useCache: true }): Observable<PagedResourceCollection<T>>;

Changed sort param type, new type is object, more see here.

See more about SortElements method here.

Other classes

CacheHelper changes

CacheHelper class does not exist anymore, use NgxHateoasClientConfigurationService to configure cache settings.

HalParam changes

HalParam class replaced to GetOption or PagedGetOption classes.

Everywhere was used HalParam now need to use GetOption or GetPagedOption depends on return value when return value is PagedResourceCollection then will be PagedGetOption, GetOption otherwise.

Example of migration from HalParam to GetOption or PagedGetOption:

HalParam representation:

params: [
  {
    key: 'projection',
    value: 'testProjection'
  },
  {
    key: 'param1',
    value: 'value1'
  },
  {
    key: 'param2',
    value: 'value2'
  }
]

After converting to GetOption or PagedGetOption:

params: { 
   projection: 'testProjection',
   param1: 'value1',
   param2: 'value2'
}

HalOptions changes

HalOptions class replaced to GetOption or PagedGetOption classes.

Everywhere was used HalOptions now need to use GetOption or GetPagedOption depends on return value when return value is PagedResourceCollection then will be PagedGetOption, GetOption otherwise.

Example of migration from HalOptions to GetOption or PagedGetOption:

HalOptions representation:

{
  size: 20,
  params: [
    {
      key: 'projection',
      value: 'testProjection'
    },
    {
      key: 'param1',
      value: 'value1'
    },
    {
      key: 'param2',
      value: 'value2'
    }
  ],
  sort: [
    {path: 'test', order: 'DESC'}
  ],
  notPaged: false
}

After converting to GetOption:

{
 params: { 
    projection: 'testProjection',
    param1: 'value1',
    param2: 'value2
 },
 sort: {
    test: 'DESC'
 }
}

Note! GetOption does not contain a size param because it is a page param.

After converting to PagedGetOption:

{
 params: { 
    projection: 'testProjection',
    param1: 'value1',
    param2: 'value2
 },
 sort: {
    test: 'DESC'
 },
 pageParams: {
    size: 20
 }
}

LinkOptions changes

LinkOptions replaced to RequestOption params.

Example of migration from LinkOptions to RequestOption:

LinkOptions representation:

{
  strictParams?: boolean,
  params: {
      param1: 'value1',
      param2: 'value2
  }
}

After converting to PagedGetOption:

{
  params: {
      param1: 'value1',
      param2: 'value2
  }
  observe?: 'body' | 'response';
}

strictParams was delete and observe was add that allows change response type from raw body to Angular HttpResponse.

Sort changes

Sort param was changed from array to object notation.

Was:

sort: [
  {path: 'test', order: 'DESC'}
]

Now:

sort: {
   test: 'DESC'
}

SubTypeBuilder changes

SubTypeBuilder param is not exist anymore, use Resource.isResourceOf method to know which resource type you got.

See more about support subtypes here.

ExpireMs and IsCacheActive changes

expireMs, isCacheActive params are not exist anymore. How to manage the cache see here.

Files

migration-guide.md

Latest commit

History

migration-guide.md

File metadata and controls

Migration guide

Contents

Motivation

Migration steps

Library changes

Configuration

RestService

Common changes

Get changes

GetAll changes

GetAllPage changes

Search changes

SearchPage changes

SearchSingle changes

CustomQuery changes

Create changes

Update changes

Patch changes

Delete changes

HandleError changes

Resource

GetRelation changes

GetProjection changes

GetRelationArray changes

GetProjectionArray changes

AddRelation changes

SubstituteRelation changes

DeleteRelation changes

ClearCollectionRelation changes

PostRelation changes

PatchRelation changes

EmbeddedResource changes

ResourcePage changes

SortElements changes

Other classes

CacheHelper changes

HalParam changes

HalOptions changes

LinkOptions changes

Sort changes

SubTypeBuilder changes

ExpireMs and IsCacheActive changes