Entity service

What is it?

The Skyframe entity service is a utility class exposed by the Shell through its entityService attribute. Its function is to provide a generic, repository-like interface that allows the developers (and also the internal Skyframe modules) to request resources (page, detail, etc.) of Skyframe entities, and create or make changes to them, without the need of interacting with Angular's HTTPClient.

How to use it?

Build an entity instance

EntityService#build is equivalent to Shell#createEntity.

The build methods allow us to create an entity instance, and optionally, initialize it with a set of values:

Copy
const unknownCustomer = shell.entityService.build(Customer);
// => Customer {}

const john = shell.entityService.build(Customer, {
  id: 1,
  name: 'john',
  orders: [{ id: 1 }, { id: 4 }]
});
// => Customer { id: 1, name: 'john', orders: [Order { id: 1 }, Order { id: 4 }] }

Create a new entity in the database

The create method performs an HTTP POST request to the Skyframe server, to create a new entity in the database:

Copy
// Build the new entity first
const newCustomer = shell.createEntity(Customer);
newCustomer.name = 'tom';
newCustomer.orders = [{ id: 1 }, { id: 4 }];

shell.entityService
  .create(Customer, newCustomer)
  .subscribe((createdCustomer) => {
    console.log(createdCustomer);
  });
// => Customer { id: 515, name: 'tom', orders: [Order { id: 1 }, Order { id: 4 }] }

// Using async/await
const createdCustomer = await shell.entityService
  .create(Customer, newCustomer)
  .toPromise();
console.log(createdCustomer);
// => Customer { id: 515, name: 'tom', orders: [Order { id: 1 }, Order { id: 4 }] }

Retrieve an entity

The getOne method performs an HTTP GET request to the Skyframe server, to retrieve an existing entity by its id:

Copy
shell.entityService.getOne(Customer, 515).subscribe((customer) => {
  console.log(customer);
});
// => Customer { id: 515, name: 'tom', orders: [Order { id: 1 }, Order { id: 4 }] }

// Using async/await
const customer = await shell.entityService.getOne(Customer, 515).toPromise();
console.log(createdCustomer);
// => Customer { id: 515, name: 'tom', orders: [Order { id: 1 }, Order { id: 4 }] }

Retrieve an entity page

The getMany method performs an HTTP GET request to the Skyframe server, to retrieve a page of entities:

Copy
shell.entityService.getMany(Customer).subscribe((customerPage) => {
  console.log(customerPage);
});
// => { count: 516, rows: [Customer { id: 1, name: 'john'}, ...] }

// Using async/await
const customer = await shell.entityService.getMany(Customer).toPromise();
console.log(createdCustomer);
// => { count: 516, rows: [Customer { id: 1, name: 'john'}, ...] }

Update an entity

The update method performs an HTTP PUT request to the Skyframe server, to update a particular entity by its id:

Copy
// Retrieve the customer from backend
const tom = await shell.entityService.getOne(Customer, 515).toPromise();
console.log(tom.name);
// => 'tom'

tom.name = 'Tom'; // Fix uppercase

const updatedTom = await shell.entityService
  .update(Customer, tom.id, tom)
  .toPromise();
console.log(updatedTom.name);
// => 'Tom'

// Let's retrieve Tom from backend again
const tomAfterUpdate = await shell.entityService
  .getOne(Customer, 515)
  .toPromise();
console.log(tomAfterUpdate.name);
// => 'Tom'

Apply patches to an entity

The patch method performs an HTTP PATCH request to the Skyframe server, to apply a partial update to a particular entity by its id:

Unlike the update method, you don't need the whole entity data, but only include the fields you want to update.

Copy
const namePatch = shell.createEntity(Customer, { name: 'Tom' });
const updatedTom = await shell.entityService
  .patch(Customer, 515, namePatch)
  .toPromise();
console.log(updatedTom.name);
// => 'Tom'

Delete an entity

The delete method performs an HTTP DELETE request to the Skyframe server, to remove an entity from the database by its id:

Copy
const beforeDelete = await shell.entityService
  .getOne(Customer, 515)
  .toPromise();
console.log(beforeDelete);
// => Customer { id: 515, name: 'tom', orders: [Order { id: 1 }, Order { id: 4 }] }

await shell.entityService.delete(Customer, 515).toPromise();

const afterDelete = await shell.entityService.getOne(Customer, 515).toPromise();
// => throws error: { statusCode: 404, message: 'Not found' }

Advanced

Working with relations

You may want to check the CRUD Endpoints Reference to know in-depth how are the foreign keys and related fields handled when you are creating, updating, or deleting entities.

API reference

build

Copy
public build<T extends Constructor>(
  entityClass: T,
  data?: DeepPartial<InstanceType<T>>
): InstanceType<T>;

Parameters

entityClass: The Skyframe entity class.

data (Optional): The data that the created entity instance should contain.

Return value

Returns a new instance of the provided entityClass.

create

Copy
public create<T extends Constructor>(
  entityClass: T,
  entity: InstanceType<T>,
  parentIds?: number[]
): Observable<InstanceType<T>>;

Parameters

entityClass: The Skyframe entity class.

entity: The entity to be created in the database (the request body).

parentIds (Optional): It should be provided if the target entityClass is the child's side of a composition relation. If the entityClass has a parent A, and A has a parent B, and B has a parent C, the parentIds would be [cId, bId, aId] (from the greatest to the lowest ancestor's id).

Return value

Returns the Observable of the created entity's instance.

getOne

Copy
public getOne<T extends Constructor>(
  entityClass: T,
  id: number,
  parentIds?: number[],
  options?: GetOptions
): Observable<InstanceType<T>>;

Parameters

entityClass: The Skyframe entity class.

id: The id of the requested entity.

parentIds (Optional): It should be provided if the target entityClass is the child's side of a composition relation. If the entityClass has a parent A, and A has a parent B, and B has a parent C, the parentIds would be [cId, bId, aId] (from the greatest to the lowest ancestor's id).

options (Optional): Extra request options:

options.params (Optional): an HttpParams instance representing the extra query params.

Return value

Returns the Observable of the retrieved entity's instance.

getMany

Copy
public getMany<T extends Constructor>(
  entityClass: T,
  parentIds?: number[],
  options?: GetOptions
): Observable<Page<InstanceType<T>>>;

Parameters

entityClass: The Skyframe entity class.

parentIds (Optional): It should be provided if the target entityClass is the child's side of a composition relation. If the entityClass has a parent A, and A has a parent B, and B has a parent C, the parentIds would be [cId, bId, aId] (from the greatest to the lowest ancestor's id).

options (Optional): Extra request options:

options.params (Optional): an HttpParams instance representing the extra query params.

Return value

Returns the Observable of the retrieved entity page. The page contains count and rows. The count represents the total number of rows, while the rows are an array of fetched entities for the current page.

update

Copy
public update<T extends Constructor>(
  entityClass: T,
  entityId: number,
  entity: InstanceType<T>,
  parentIds?: number[]
): Observable<InstanceType<T>>;

Parameters

entityClass: The Skyframe entity class.

entityId: The id of the entity to be updated.

entity: The entity holding the updated fields.

parentIds (Optional): It should be provided if the target entityClass is the child's side of a composition relation. If the entityClass has a parent A, and A has a parent B, and B has a parent C, the parentIds would be [cId, bId, aId] (from the greatest to the lowest ancestor's id).

Return value

Returns the Observable of the updated entity instance returned from the Skyframe server.

patch

Copy
public patch<T extends Constructor>(
  entityClass: T,
  entityId: number,
  entity: InstanceType<T>,
  parentIds?: number[]
): Observable<InstanceType<T>>;

Parameters

entityClass: The Skyframe entity class.

entityId: The id of the entity to be updated.

entity: The entity holding the fields to be updated (only the fields that needs to be updated).

parentIds (Optional): It should be provided if the target entityClass is the child's side of a composition relation. If the entityClass has a parent A, and A has a parent B, and B has a parent C, the parentIds would be [cId, bId, aId] (from the greatest to the lowest ancestor's id).

Return value

Returns the Observable of the updated entity instance returned from the Skyframe server.

delete

Copy
public delete<T extends Constructor>(
  entityClass: T,
  entityId: number,
  parentIds?: number[]
): Observable<void>;

Parameters

entityClass: The Skyframe entity class.

entityId: The id of the entity to be deleted.

parentIds (Optional): It should be provided if the target entityClass is the child's side of a composition relation. If the entityClass has a parent A, and A has a parent B, and B has a parent C, the parentIds would be [cId, bId, aId] (from the greatest to the lowest ancestor's id).

Return value

No return values.