nginstack

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.js');
 const currentUser = Entity.fromKey(session.userKey);
 DBKey.str(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.js');
 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.js');
 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
const classKey = -1898187810; // Grupos
const entity = Entity.fromKey(classKey);
const ds = classes.getCachedDataSet(classKey);
entitySet.bindDataSet(ds);

bool(expr)

Obtém o valor de uma propriedade da entidade ou do último campo de uma expressão lookup caso o primeiro campo dessa expressão contenha a chave de um registro que faça parte do cache local. O valor retornado sempre será um primitivo do tipo boolean.

Caso o valor do campo solicitado não seja um booleano, ele será convertido em um de forma equivalente a expressão Boolean(value).

Ver #val para mais detalhes.

Parameters:
Name Type Description
expr string

O nome de um campo ou uma expressão de campos separados por ".".
See:
Returns:

Valor do campo.

Type
boolean
Example
const Entity = require('@nginstack/orm/lib/Entity.js');
const user = Entity.fromKey(-1898186559);
user.bool('iClass.MAE') // => true
user.bool('iName') // => true
user.bool('iEnd') // => false

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.js');
 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();

date(expr)

Obtém o valor de uma propriedade da entidade ou do último campo de uma expressão lookup caso o primeiro campo dessa expressão contenha a chave de um registro que faça parte do cache local. O valor retornado sempre será uma instância de Date ou null.

Será gerado um erro caso o valor do campo solicitado não seja uma data, exceto quando ele for null. Nesse caso, o valor retornado também será null.

Ver #val para mais detalhes.

Parameters:
Name Type Description
expr string

O nome de um campo ou uma expressão de campos separados por ".".
See:
Returns:

Valor do campo.

Type
Date | null
Example
const Entity = require('@nginstack/orm/lib/Entity.js');
const user = Entity.fromKey(-1898186559);
user.date('iLastPasswdChg') // => Date()
user.date('iEnd') // => null
user.date('iName') // => Error()

dbkey(expr)

Obtém o valor de uma propriedade da entidade ou do último campo de uma expressão lookup caso o primeiro campo dessa expressão contenha a chave de um registro que faça parte do cache local.

O valor retornado será uma instância de DBKey quando o campo estiver preenchido ou null no caso contrário. Será gerado um erro caso o valor do campo solicitado não seja um valor numérico inteiro. Ver #val para mais detalhes.

Parameters:
Name Type Description
expr string

O nome de um campo ou uma expressão de campos separados por ".".
See:
Returns:

Valor do campo.

Type
DBKey | null
Example
const Entity = require('@nginstack/orm/lib/Entity.js');
const user = Entity.fromKey(-1898186559);
user.dbkey('iClass') // => DBKey(-1898187809)
user.dbkey('iSecurityPolicy') // => null
user.dbkey('iName') // Error()

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.js');
 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.js');
 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.

O valor retornado por este método será tratado e normalizado de acordo com o tipo do campo declarado no modelo de dados. Por exemplo, a leitura de campos do tipo lookup múltiplo retornarão um array em vez uma lista textual de chaves. Utilize o método #val para obter o valor real armazenado na base de dados sem tratamentos adicionais.

Returns:

Valor da propriedade.

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

num(expr)

Obtém o valor de uma propriedade da entidade ou do último campo de uma expressão lookup caso o primeiro campo dessa expressão contenha a chave de um registro que faça parte do cache local. O valor retornado sempre será um primitivo do tipo number.

Caso o valor do campo solicitado seja nulo, será retornado 0. Será gerado um erro se valor não for numérico.

Ver #val para mais detalhes.

Parameters:
Name Type Description
expr string

O nome de um campo ou uma expressão de campos separados por ".".
See:
Returns:

Valor do campo.

Type
number
Example
const Entity = require('@nginstack/orm/lib/Entity.js');
const user = Entity.fromKey(-1898186559);
user.num('iClass.MAE') // => -1898187811
user.num('iName') // => Error()

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.js');
 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.js');
 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.js');
 const currentUser = Entity.fromKey(session.userKey);
 currentUser.set('iemailaddress', 'user@server.com');
 currentUser.post();

str(expr)

Obtém o valor de uma propriedade da entidade ou do último campo de uma expressão lookup caso o primeiro campo dessa expressão contenha a chave de um registro que faça parte do cache local. O valor retornado sempre será um primitivo do tipo string.

Ver #val para mais detalhes.

Parameters:
Name Type Description
expr string

O nome de um campo ou uma expressão de campos separados por ".".
See:
Returns:

Valor do campo.

Type
string
Example
const Entity = require('@nginstack/orm/lib/Entity.js');
const user = Entity.fromKey(-1898186559);
user.str('iClass.NOME') // => 'Usuários'

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.js');
 const currentUser = Entity.fromKey(session.userKey);
 currentUser.toJSONString()

val(expr)

Obtém o valor de uma propriedade da entidade ou do último campo de uma expressão lookup caso o primeiro campo dessa expressão contenha a chave de um registro que faça parte do cache local. Diferentemente do método #get, o valor retornado por este método será aquele armazenado na base de dados, sem nenhum tipo de tratamento ou normalização.

Tentar acessar uma propriedade que não existe na entidade ou que o usuário não tenha visão produzirá um erro, assim como tentar obter um campo que não existe na tabela de um registro. Essa verificação é realizada com base nos campos da tabela gravada no cache local. Um campo recém criado no banco de dados não poderá ser utilizado por este método enquanto o Engine não for reiniciado para atualizar a estrutura do banco local.

Solicitar um campo de um valor nulo retornará null e interromperá a avaliação da expressão. Esse comportamento possibilita que uma expressão possa ser utilizada sem que seja necessário verificar se todos os valores dos campos são não nulos. Observar que esse comportamento não se aplica para uma chave inválida, como a gerada a partir de um valor não numérico ou NaN. Neste caso específico, será gerado um erro ao tentar obter o campo.

O valor retornado por este método sempre será um primitivo ou uma data, mesmo que seja solicitado o valor de um campo que contenha outras chaves no sistema. Nesse caso, será retornado o o valor numérico da chave como number.

Uma característica importante deste método é que o tipo do valor retornado poderá mudar para a mesma expressão informada. Isso ocorre quando um dos campos da expressão é null o que forçará que o retorno deste método também seja null. Portanto, ao utilizar esse método, sempre verifique se o retorno é diferente de null antes de utilizar os métodos esperados para o tipo do campo final da expressão. Preferencialmente, pode ser utilizado um dos métodos abaixo para garantir o tipo retornado:

* module:@nginstack/orm/lib/Entity~Entity#str
* module:@nginstack/orm/lib/Entity~Entity#num
* module:@nginstack/orm/lib/Entity~Entity#bool
* module:@nginstack/orm/lib/Entity~Entity#date
* module:@nginstack/orm/lib/Entity~Entity#dbkey
Parameters:
Name Type Description
expr string

O nome de uma propriedade ou uma expressão de campos separados por ".".
See:
Returns:

Valor do campo.

Type
string | number | null | boolean | Date
Example
const Entity = require('@nginstack/orm/lib/Entity.js');
const user = Entity.fromKey(-1898186559);
user.val('iName'); // => 'administrator'
user.val('iClass.NOME') // => 'Usuários'
user.val('iUnknownField') // => Error()
user.val('iClass.iUnknownField') // => Error()