ISSUE-66 Added additional lib config to specify HAL format

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 3.3.0 (2022-07-25)
+#### Changes
+- Fixed [issue-66](https://github.com/lagoshny/ngx-hateoas-client/issues/66).
+  > Added new Lib configuration that allows to specify HAL format for resource collections. See more in [docs](https://github.com/lagoshny/ngx-hateoas-client#halformat).
+
 ## 3.2.2 (2022-06-29)
 #### Changes
 - Fixed [issue-61](https://github.com/lagoshny/ngx-hateoas-client/issues/61).

README.md

@@ -108,6 +108,7 @@ You can found examples of usage this client with [task-manager-front](https://gi
   - [Http params](#http-params)
 - [UseTypes](#usetypes-params)
 - [TypesFormat](#typesformat)
+- [HALFormat](#halformat)
 - [Cache support](#cache-support)
 - [Logging](#Logging)
 7. [Public classes](#Public-classes)
@@ -3521,6 +3522,33 @@ For the `Resource JSON` like this:
 
 `Resource` instance will have property `someDate` as type `Date`.
 
+#### HALFormat
+Configuring HAL format that used to parse `JSON` as `Resource`.
+
+Example:
+````ts
+halFormat: {
+    collections: {
+        embeddedOptional: false
+    }
+}
+````
+
+Property `collections` contains all format settings for collections. Available the next settings for `collections`:
+
+- `embeddedOptional` - by default `false`, means that server side should add `_embedded` property when returns empty resource collection like that:
+
+```json
+{
+  "_embedded" : {
+    "orders : [
+    ]
+  }
+}
+```
+when value is set to `true` then it is not required to add `_embedded` property when returns empty resource collection.
+
+
 #### isProduction param
 Some `hateoas-client` features can change their behaviours depends on this param. For example, [Logging](#logging) disable all `warning` messages when `isProduction` is true.
 

projects/ngx-hateoas-client/README.md

@@ -108,6 +108,7 @@ You can found examples of usage this client with [task-manager-front](https://gi
   - [Http params](#http-params)
 - [UseTypes](#usetypes-params)
 - [TypesFormat](#typesformat)
+- [HALFormat](#halformat)
 - [Cache support](#cache-support)
 - [Logging](#Logging)
 7. [Public classes](#Public-classes)
@@ -3512,6 +3513,32 @@ For the `Resource JSON` like this:
 
 `Resource` instance will have property `someDate` as type `Date`.
 
+#### HALFormat
+Configuring HAL format that used to parse `JSON` as `Resource`.
+
+Example:
+````ts
+halFormat: {
+    collections: {
+        embeddedOptional: false
+    }
+}
+````
+
+Property `collections` contains all format settings for collections. Available the next settings for `collections`:
+
+- `embeddedOptional` - by default `false`, means that server side should add `_embedded` property when returns empty resource collection like that:
+
+```json
+{
+  "_embedded" : {
+    "orders : [
+    ]
+  }
+}
+```
+when value is set to `true` then it is not required to add `_embedded` property when returns empty resource collection.
+
 #### isProduction param
 Some `hateoas-client` features can change their behaviours depends on this param. For example, [Logging](#logging) disable all `warning` messages when `isProduction` is true.
 

projects/ngx-hateoas-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lagoshny/ngx-hateoas-client",
-  "version": "3.2.2",
+  "version": "3.3.0",
   "description": "This client used to develop `Angular 12+` applications working with RESTfulll server API with HAL/JSON response type (supports server implementation by Spring HATEOAS)",
   "readme": "README.md",
   "license": "MIT",

projects/ngx-hateoas-client/src/lib/config/hateoas-configuration.interface.ts

@@ -128,4 +128,23 @@ export interface HateoasConfiguration {
     }
   };
 
+  /**
+   * Additional configuration to specify settings for HAL format.
+   */
+  halFormat?: {
+    collections?: {
+      /**
+       * If {@code true}, then for empty collections, not required to specify _embedded property.
+       * When {@code false} (be default), you need to specify empty _embedded property for empty collections.
+       *
+       * By default, Spring Data REST includes empty _embedded property for empty collections,
+       * but when using Spring HATEOAS you need to do it manually.
+       *
+       * Recommending use Spring Data REST approach and return empty _embedded property for empty collection
+       * for more predictable determine resource type algorithm.
+       */
+      embeddedOptional: boolean;
+    }
+  };
+
 }

projects/ngx-hateoas-client/src/lib/config/lib-config.ts

@@ -28,6 +28,11 @@ export class LibConfig {
         page: 0
       }
     },
+    halFormat: {
+      collections: {
+        embeddedOptional: false
+      }
+    },
     isProduction: false
   };
 

projects/ngx-hateoas-client/src/lib/model/resource-type.spec.ts

@@ -1,15 +1,19 @@
 import { isEmbeddedResource, isPagedResourceCollection, isResource, isResourceCollection } from './resource-type';
 import {
   rawEmbeddedResource,
+  rawEmptyPagedResourceCollection,
+  rawEmptyResourceCollection,
   rawPagedResourceCollection,
   rawResource,
   rawResourceCollection
 } from './resource/resources.test';
+import { LibConfig } from '../config/lib-config';
 
 describe('ResourceType', () => {
 
   it('object IS EMBEDDED_RESOURCE with _links object WITHOUT self link', () => {
     const result = isEmbeddedResource({
+      test: 'Test',
       _links: {
         someRelation: {
           href: 'http://localhost:8080/api/v1/someRelation/1'
@@ -21,12 +25,13 @@ describe('ResourceType', () => {
   });
 
   it('object IS EMBEDDED_RESOURCE with empty _links object', () => {
-    expect(isEmbeddedResource({_links: {}})).toBeTrue();
+    expect(isEmbeddedResource({test: 'Test', _links: {}})).toBeTrue();
   });
 
 
   it('object IS NOT EMBEDDED_RESOURCE with _links object WITH self link', () => {
     const result = isEmbeddedResource({
+      test: 'Test',
       _links: {
         self: {
           href: 'http://localhost:8080/api/v1/self/1'
@@ -179,6 +184,32 @@ describe('ResourceType', () => {
     expect(isResourceCollection(rawPagedResourceCollection)).toBeFalse();
   });
 
+  it('empty resource collection without _embedded property IS COLLECTION_RESOURCE when embeddedOptional is TRUE', () => {
+    spyOn(LibConfig, 'getConfig').and.returnValue({
+      ...LibConfig.DEFAULT_CONFIG,
+      halFormat: {
+        collections: {
+          embeddedOptional: true
+        }
+      }
+    });
+
+    expect(isResourceCollection(rawEmptyResourceCollection)).toBeTrue();
+  });
+
+  it('empty resource collection without _embedded property IS NOT COLLECTION_RESOURCE when embeddedOptional is FALSE', () => {
+    spyOn(LibConfig, 'getConfig').and.returnValue({
+      ...LibConfig.DEFAULT_CONFIG,
+      halFormat: {
+        collections: {
+          embeddedOptional: false
+        }
+      }
+    });
+
+    expect(isResourceCollection(rawEmptyResourceCollection)).toBeFalse();
+  });
+
   it('object IS PAGED RESOURCE COLLECTION with _embedded AND page object', () => {
     expect(isPagedResourceCollection(rawPagedResourceCollection)).toBeTrue();
   });
@@ -236,4 +267,28 @@ describe('ResourceType', () => {
     expect(isPagedResourceCollection(rawResourceCollection)).toBeFalse();
   });
 
+  it('empty paged resource collection without _embedded property IS PAGE_COLLECTION_RESOURCE when embeddedOptional is TRUE', () => {
+    spyOn(LibConfig, 'getConfig').and.returnValue({
+      ...LibConfig.DEFAULT_CONFIG,
+      halFormat: {
+        collections: {
+          embeddedOptional: true
+        }
+      }
+    });
+    expect(isPagedResourceCollection(rawEmptyPagedResourceCollection)).toBeTrue();
+  });
+
+  it('empty paged resource collection without _embedded property IS NOT PAGE_COLLECTION_RESOURCE when embeddedOptional is FALSE', () => {
+    spyOn(LibConfig, 'getConfig').and.returnValue({
+      ...LibConfig.DEFAULT_CONFIG,
+      halFormat: {
+        collections: {
+          embeddedOptional: false
+        }
+      }
+    });
+    expect(isPagedResourceCollection(rawEmptyPagedResourceCollection)).toBeFalse();
+  });
+
 });

projects/ngx-hateoas-client/src/lib/model/resource-type.ts

@@ -1,4 +1,5 @@
 import { isObject } from 'lodash-es';
+import { LibConfig } from '../config/lib-config';
 
 export function isEmbeddedResource(object: any) {
   // Embedded resource doesn't have self link in _links object
@@ -10,19 +11,35 @@ export function isResource(object: any): boolean {
 }
 
 export function isResourceCollection(object: any): boolean {
-  return isObject(object) &&
-         ('_embedded' in object) &&
-         ('_links' in object) &&
-         !('page' in object) &&
-         (Object.keys(object).length === 2);
+  const baseCondition = isObject(object) &&
+    ('_links' in object) &&
+    !('page' in object);
+  if (!baseCondition) {
+    return false;
+  }
+
+  if (LibConfig.getConfig().halFormat.collections.embeddedOptional) {
+    return baseCondition && (Object.keys(object).length === 1 ||
+      '_embedded' in object && Object.keys(object).length === 2);
+  } else {
+    return baseCondition && '_embedded' in object && Object.keys(object).length === 2;
+  }
 }
 
 export function isPagedResourceCollection(object: any): boolean {
-  return isObject(object) &&
-         ('_embedded' in object) &&
-         ('_links' in object) &&
-         ('page' in object) &&
-         (Object.keys(object).length === 3);
+  const baseCondition = isObject(object) &&
+    ('_links' in object) &&
+    ('page' in object);
+  if (!baseCondition) {
+    return false;
+  }
+
+  if (LibConfig.getConfig().halFormat.collections.embeddedOptional) {
+    return baseCondition && (Object.keys(object).length === 2 ||
+      '_embedded' in object && Object.keys(object).length === 3);
+  } else {
+    return baseCondition && '_embedded' in object && Object.keys(object).length === 3;
+  }
 }
 
 /**

projects/ngx-hateoas-client/src/lib/model/resource/base-resource.spec.ts

@@ -13,7 +13,8 @@ import { RequestParam, RESOURCE_OPTIONS_PROP } from '../declarations';
 import { DEFAULT_ROUTE_NAME } from '../../config/hateoas-configuration.interface';
 
 class TestProductResource extends BaseResource {
-  // tslint:disable-next-line:variable-name
+  public name = 'TestName';
+// tslint:disable-next-line:variable-name
   _links = {
     self: {
       href: 'http://localhost:8080/api/v1/product/1'

projects/ngx-hateoas-client/src/lib/model/resource/resources.test.ts

@@ -37,12 +37,14 @@ export const rawResource = {
 
 @HateoasResource('resource')
 export class RawResource extends Resource {
+  public name = 'Test';
 }
 
 @HateoasResource('test')
 export class SimpleResource extends Resource {
+  public name = 'Test';
 
-  // tslint:disable-next-line:variable-name
+// tslint:disable-next-line:variable-name
   _links = {
     self: {
       href: 'http://localhost:8080/api/v1/test/1'
@@ -55,6 +57,7 @@ export class SimpleResource extends Resource {
 }
 
 export const rawCaseSensitiveResource = {
+  name: 'Test',
   _links: {
     self: {
       href: 'http://localhost:8080/api/v1/testResource/1'
@@ -85,6 +88,8 @@ export class SimpleResourceProjection extends Resource {
 @HateoasEmbeddedResource(['anotherResource'])
 export class SimpleEmbeddedResource extends EmbeddedResource {
 
+  public name: string;
+
   // tslint:disable-next-line:variable-name
   _links = {
     anotherResource: {
@@ -94,6 +99,14 @@ export class SimpleEmbeddedResource extends EmbeddedResource {
 
 }
 
+export const rawEmptyResourceCollection = {
+  _links: {
+    self: {
+      href: 'http://localhost:8080/api/v1/collection'
+    }
+  }
+};
+
 export const rawResourceCollection = {
   _embedded: {
     tests: [
@@ -135,6 +148,32 @@ export class SimpleResourceCollection extends ResourceCollection<SimpleResource>
 
 }
 
+export const rawEmptyPagedResourceCollection = {
+  page: {
+    totalElements: 100,
+    number: 2,
+    size: 10,
+    totalPages: 10
+  },
+  _links: {
+    self: {
+      href: 'http://localhost:8080/api/v1/pagedCollection'
+    },
+    first: {
+      href: 'http://localhost:8080/api/v1/pagedCollection?page=0&size=1'
+    },
+    next: {
+      href: 'http://localhost:8080/api/v1/pagedCollection?page=1&size=1'
+    },
+    prev: {
+      href: 'http://localhost:8080/api/v1/pagedCollection?page=0&size=1'
+    },
+    last: {
+      href: 'http://localhost:8080/api/v1/pagedCollection?page=1&size=1'
+    }
+  }
+};
+
 export const rawPagedResourceCollection = {
   _embedded: {
     tests: [

projects/ngx-hateoas-client/src/lib/service/external/hateoas-resource.service.spec.ts

@@ -9,6 +9,7 @@ import anything = jasmine.anything;
 
 @HateoasResource('resourceRelation')
 class ResourceRelation extends Resource {
+  public name = 'Test';
   // tslint:disable-next-line:variable-name
   _links = {
     self: {
@@ -24,7 +25,7 @@ class ResourceRelation extends Resource {
 @HateoasResource('resourceWithRelation')
 class ResourceWithRelation extends SimpleResource {
   public relation: ResourceRelation;
-  public name: 'Test';
+  public name = 'Test';
 }
 
 describe('HateoasResourceService', () => {