Class: Entity

@nginstack/orm/lib/Entity~ Entity


new Entity(classKey, dataSet [, opt_options])

Classe utilizada para manipular registros das classes de dados do sistema, declaradas por meio de arquivos x-model. O seu uso é recomendado em vez da manipulação direta via dataSets, pois as regras de negócio declaradas no x-model, por meio de eventos e definições de campos, são respeitadas com base nas permissões do usuário corrente da sessão ou do usuário indicado nas opções do construtor.

Não é recomendado utilizar diretamente o construtor Entity, prefira:

  • Entity.fromKey: para consultar ou alterar registros que façam parte do cache local;
  • Entity.fromDataSet: para consultar ou alterar registros de APIs existentes que hoje expõem DataSets como interface de dados, como os objetos de gestão;
  • EntitySet.newEntity: para construir uma nova entidade de uma determinada classe de dados;
  • EntitySet.findByKey: para consultar ou alterar entidades de uma determinada coleção previamente criada.
Parameters:
Name Type Argument Description
classKey number

Classe de dados da entidade.

dataSet DataSet

DataSet que contém os dados da entidade. Enquanto a entidade criada existir, o DataSet informado não poderá ter a sua posição alterada. A mudança da posição do DataSet impedirá o uso da entidade criada. A entidade criada terá a propriedade Entity#autoPersist com o mesmo valor da propriedade DataSet#automaticApplyUpdates do DataSet informado.

opt_options EntityOptions | Record.<*, *> <optional>

Opções da entidade a ser criada.

See:
  • EntitySet
  • Key
  • KeySet
Throws:

Será gerado um erro caso a chave informada em opt_options.keynão exista ou se o usuário não tiver permissão de visão para a classe desta entidade.

Type
EntityError

Members


<static> requiresStrictMode :boolean

Indica que a classe module:@nginstack/orm/lib/Entity somente modificará registros nas classes de dados que estiverem como o modo estrito habilitado.

Type:
  • boolean

autoPersist :boolean

Indica se os dados serão persistidos automaticamente no banco de dados quando for executado o método #post.

Type:
  • boolean
See:

classKey :number

Chave da classe de dados desta entidade.

Type:
  • number
Example
const Entity = require('@nginstack/orm/lib/Entity');
 const currentUser = Entity.fromKey(session.userKey);
 currentUser.classKey.nome // => Usuários

key :number

Chave que identifica unicamente esta entidade no banco de dados.

Type:
  • number
Example
const Entity = require('@nginstack/orm/lib/Entity');
 const currentUser = Entity.fromKey(session.userKey);
 currentUser.key === session.userKey // => true

postPending :boolean

Indica que uma entidade recém criada ou alterações realizadas em uma entidade existente não foram efetivadas pelo método #post.

Type:
  • boolean
See:

state :EntityState

Indica qual é o estado de modificação desta entidade. Valores possíveis:

  • EntityState.UNCHANGED: A entidade não foi modificada desde a sua criação ou da última execução do método Entity#persist.
  • EntityState.ADDED: uma nova entidade foi criada, mas as alterações ainda não foram persistidas no banco de dados.
  • EntityState.MODIFIED: a entidade foi modificada, mas as alterações ainda não foram persistidas no banco de dados.
  • EntityState.DELETED: a entidade foi excluída, mas as alterações ainda não foram persistidas no banco de dados.
  • EntityState.DETACHED: indica que uma instância de Entity não faz mais parte de um EntitySet, nem representa uma entidade do banco de dados. Normalmente, uma entidade fica nesse estado após a exclusão de uma entidade ter sido persistida no banco de dados ou quando o dataSet informado para a Entidade teve a sua posição modificada.
Type:
  • EntityState
Example
const Entity = require('@nginstack/orm/lib/Entity');
 const currentUser = Entity.fromKey(session.userKey);
 assert.equal(currentUser.state, EntityState.UNCHANGED);
 currentUser.set('iemailaddress', 'user@server.com');
 assert.equal(currentUser.state, EntityState.MODIFIED);
 currentUser.post();
 assert.equal(currentUser.state, EntityState.UNCHANGED);

Methods


<static> fromDataSet(classKey, dataSet [, opt_options])

Cria uma entidade para manipular o registro corrente do dataSet.

A entidade criada terá a propriedade Entity#autoPersist com o mesmo valor da propriedade DataSet#automaticApplyUpdates do DataSet informado.

Parameters:
Name Type Argument Description
classKey number

Classe de dados da entidade que será manipulada.

dataSet DataSet

DataSet que contém a entidade que deverá ser manipulada pela Entidade a ser criada.

opt_options Object | Record.<*, *> <optional>

Opções disponíveis:

  • userKey: usuário que será utilizado para validar as permissões. Mais detalhes em EntityOptions#userKey;
  • fields: campos da definição da classe que devem ser manipulados por essa entidade. Mais detalhes em EntityOptions#fields;
  • modelDef: definição do modelo de dados que deve ser utilizada. Por padrão, a definição do modelo de dados utilizada é a da informada. No entanto, em alguns cenários de uso é necessário retirar ou complementar comportamentos do modelo. O uso desta opção não é recomendada, pois ela desabilita a capacidade da entidade ajustar dinamicamente as regras de modelo quando a classe é alterada. Mais detalhes em EntityOptions#modelDef.
Returns:

Entidade contida na posição corrente do DataSet.

Type
Entity
Example
const users = Entity.fromDataSet(ClassKeys.USERS, ds);
 users.toJSONString();

<static> fromKey(key [, opt_options])

Cria uma entidade para manipular o registro indicado pela chave key. Esta função somente poder ser utilizada com registros que façam parte do cache local do Engine, como os cadastros do sistema.

Por padrão, a entidade criada terá a propriedade Entity#autoPersist ativa.

Parameters:
Name Type Argument Description
key number

Chave da entidade a ser criada.

opt_options Object | Record.<*, *> <optional>

Opções disponíveis:

  • userKey: usuário que será utilizado para validar as permissões. Mais detalhes em EntityOptions#userKey;
  • fields: campos da definição da classe que devem ser manipulados por essa entidade. Mais detalhes em EntityOptions#fields;
  • modelDef: definição do modelo de dados que deve ser utilizada. Por padrão, a definição do modelo de dados utilizada é a da classe da chave informada. No entanto, em alguns cenários de uso é necessário retirar ou complementar comportamentos do modelo. O uso desta opção não é recomendada, pois ela desabilita a capacidade da entidade ajustar dinamicamente as regras de modelo quando a classe é alterada. Mais detalhes em EntityOptions#modelDef.
Throws:

Será gerado um erro caso a chave informada não exista ou se o usuário corrente não tiver permissão de visão para a classe desta entidade.

Type
EntityError
Returns:

Entidade associada à chave informada.

Type
Entity
Example
var entity = Entity.fromKey(ngin.keys.Users.ANONYMOUS);
 entity.toJSONString();

assign(values)

Serão atribuídas as propriedades do objeto informado. As propriedades existentes no objeto informado que não existem neste serão ignoradas. Propriedades existentes em obj que o usuário não tem poder de edição irá produzir um erro apenas se o valor existente em obj for diferente do existente na entidade.

Parameters:
Name Type Description
values Object.<string, *>

Mapa de propriedades a serem atribuídas à entidade.


bindDataSet(dataSet)

Informa um novo DataSet onde os dados da entidade serão persistidos. O DataSet informado deve ter a mesma estrutura do dataSet informado no construtor, ou seja, deve ter os mesmos campos, com os mesmos tipos, na mesma ordem.

Parameters:
Name Type Description
dataSet DataSet

DataSet que será utilizado para gravar os dados da entidade.

Example
var entity = Entity.fromKey(ngin.keys.Classes.GROUPS);
var ds = classes.getCachedDataSet(ngin.keys.Classes.GROUPS);
entitySet.bindDataSet(ds);

cancel()

Cancela a edição corrente ou criação da entidade. Após a execução dos métodos #post e #persist não será possível cancelar a edição corrente.

Example
const Entity = require('@nginstack/orm/lib/Entity');
 const currentUser = Entity.fromKey(session.userKey);
 currentUser.edit();
 try {
   doStrangeThingsWith(currentUser);
 } catch (e) {
   currentUser.cancel();
   throw e;
 }

clone()

Obtém entidade clone a partir da entidade original.

Returns:

Entidade clone.

Type
Entity
Example
var clone = new Entity(chaveDaClasse, {key: chaveDoRegistro}).clone();

delete()

Exclui esta entidade. Após a execução deste método, a entidade estará com estado DELETED ou DETACHED (caso autoPersist esteja ativo) e não poderá ser mais modificada.

Example
const Entity = require('@nginstack/orm/lib/Entity');
 const user = Entity.fromKey(userToRemove);
 currentUser.delete();

edit()

Inicia a edição da entidade. Esse método é executado automaticamente ao tentar alterar o valor da entidade por meio do método #set. Ele deve ser utilizado apenas quando deseja-se rodar os eventos de edição programaticamente.

Example
const Entity = require('@nginstack/orm/lib/Entity');
 const currentUser = Entity.fromKey(session.userKey);
 assert.equal(currentUser.state, EntityState.UNCHANGED);
 currentUser.edit();
 assert.equal(currentUser.state, EntityState.MODIFIED);

get()

Obtém o valor de uma propriedade da entidade. Tentar acessar uma propriedade que não existe ou que o usuário não tenha visão produzirá um erro.

Returns:

Valor da propriedade.

Type
*
Example
const Groups = require('@nginstack/engine/keys/Groups');
 const Entity = require('@nginstack/orm/lib/Entity');
 const currentUser = Entity.fromKey(session.userKey);
 // Retorna true, se o usuário estiver associado diretamente o grupo Administrators
 currentUser.get('igroups').includes(Groups.ADMINISTRATORS);

persist()

Persiste as modificações realizadas neste entidade no banco de dados. Caso a entidade esteja em edição ou inserção, será executado o método #post antes da persistência dos dados.

See:
Returns:

Versão das alterações no banco de dados.

Type
number
Example
const Entity = require('@nginstack/orm/lib/Entity');
 const currentUser = Entity.fromKey(session.userKey);
 try {
   doGoodThingsWith(currentUser);
 } finally {
   currentUser.persist();
 }

post()

Efetiva a edição ou criação da entidade localmente no dataSet. Caso #autoPersist esteja habilitado, as alterações serão persistidas pelo método #persist automaticamente, em conjunto com o post. Caso não esteja, as alterações serão efetivadas no DataSet informado ao construtor, mas não serão persistidas no banco de dados. Neste caso, o método #persist deve ser executado posteriormente para que as alterações sejam gravadas no banco de dados.

Caso as alterações devam ser gravadas no banco de dados, prefira utilizar diretamente o método #persist. O método persist efetiva as alterações pendentes via post, antes de gravar as alterações no banco de dados.

See:
Example
const Entity = require('@nginstack/orm/lib/Entity');
 const currentUser = Entity.fromKey(session.userKey);
 try {
   doGoodThingsWith(currentUser);
 } finally {
   currentUser.post();
 }

set(name, value)

Atualiza uma propriedade desta entidade. Tentar alterar uma propriedade que não existe ou que o usuário não tenha poder de alterar produzirá um erro.

Parameters:
Name Type Description
name string

Nome da propriedade.

value *

Valor da propriedade.

Example
const Entity = require('@nginstack/orm/lib/Entity');
 const currentUser = Entity.fromKey(session.userKey);
 currentUser.set('iemailaddress', 'user@server.com');
 currentUser.post();

toJSONSchema()

Exporta a definição desta classe no formato JSON Schema.

Returns:
Type
Object

toJSONString()

Cria uma representação JSON desta entidade. Serão exportadas apenas as propriedades visíveis pelo usuário.

Returns:

JSON com os campos visíveis para o usuário.

Type
string
Example
const Entity = require('@nginstack/orm/lib/Entity');
 const currentUser = Entity.fromKey(session.userKey);
 currentUser.toJSONString()