nginstack

Class: EntitySet

@nginstack/orm/lib/EntitySet~ EntitySet

new EntitySet(baseClass, dataSet [, opt_options])

Classe que permite a manipulação de um conjunto de Entity dentro uma transação.

Parameters:
Name Type Argument Description
baseClass number

Classe mãe de todas as entidades contidas nesta conjunto de entidades.
dataSet DataSet

DataSet que será utilizado para persistir os dados das entidades.
opt_options EntitySetOptions | Record.<*, *> <optional>

Opções da entidade a ser criada.
See:
  • Entity

Members

autoPersist :boolean

Indica se os dados serão persistidos automaticamente no banco de dados quando forem realizadas alterações nas entidades que fazem parte desta coleção.

Type:
  • boolean
See:

baseClass :number

Classe mãe de todas as entidades contidas nesta conjunto de entidades.

Type:
  • number

Methods

<static> fromClass(classKey [, opt_options])

Obtém uma instância de EntitySet que permite consultar ou alterar os registros da classe de dados informada.

Esta função somente poder ser utilizada com classes de dados que façam parte do cache local do Engine, como os cadastros do sistema.

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

Parameters:
Name Type Argument Description
classKey number

Classe mãe das entidades que farão parte da coleção retornada.
opt_options Object | Record.<*, *> <optional>

Opções disponíveis:

  • userKey: usuário que será utilizado para validar as permissões. Mais detalhes em EntitySetOptions#userKey;
  • fields: campos da definição da classe que devem ser manipulados por essa entidade. Mais detalhes em EntitySetOptions#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 entidade. 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 EntitySetOptions#modelDef.
Throws:

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

Type
EntityError
Returns:

Conjunto com todas as entidades da classe informada.

Type
EntitySet
Example
var users = EntitySet.fromKey(ngin.keys.Classes.Users);
 users.toJSONString();

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

Obtém uma instância de EntitySet que permite consultar ou alterar os registros do DataSet informado respeitando as regras de negócio definidas nos arquivos de x-model e as permissões do usuário.

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

Parameters:
Name Type Argument Description
baseClass number

Classe mãe das entidades que farão parte da coleção retornada.
dataSet DataSet

DataSet que contém os registros que representam as entidades no banco de dados.
opt_options Record.<*, *> | Object <optional>

Opções disponíveis:

  • userKey: usuário que será utilizado para validar as permissões. Mais detalhes em EntitySetOptions#userKey;
  • fields: campos da definição da classe que devem ser manipulados por essa entidade. Mais detalhes em EntitySetOptions#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 entidade. 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 EntitySetOptions#modelDef.
Returns:

Conjunto de entidades contidas no dataSet informado.

Type
EntitySet
Example
var itemsPedido = EntitySet.fromDataSet(-2008879000, op.pedido);
 itemsPedido.toJSONString();

<static> persist(entitySets)

Persiste as alterações realizadas em um ou várias instâncias de EntitySet em uma única transação do banco de dados.

Parameters:
Name Type Description
entitySets EntitySet | Array.<EntitySet>

Instâncias de EntitySet que devem ter suas alterações persistidas no banco de dados.
Returns:

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

Type
number
Example
const Classes = require('@nginstack/engine/keys/Classes');
 const EntitySet = require('@nginstack/orm/lib/EntitySet');
 const users = EntitySet.fromClass(Classes.USERS);
 const groups = EntitySet.fromClass(Classes.GROUPS);
 try {
   doGoodThingsWith(users);
   doGoodThingsWith(groups);
 } finally {
   EntitySet.persist([users, groups]);
 }

bindDataSet(dataSet)

Informa um novo DataSet onde os dados da entidade serão persistidos. O DataSet informado deve ter a mesma estrutura do dataSet utilizado para construir a instância, 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 entitySet = EntitySet.fromClass(ngin.keys.Classes.GROUPS);
var ds = classes.getCachedDataSet(ngin.keys.Classes.GROUPS);
entitySet.bindDataSet(ds);

findByKey(key)

Pesquisa a entidade informada pela chave e retorna a instância dela caso a encontre ou null caso contrário.

Parameters:
Name Type Description
key number

Identificado da instância.
Returns:

Instância da entidade ou null, caso não haja uma com a chave informada.

Type
Entity

forEach(callback [, opt_context])

Itera na coleção de entidades fornecendo uma entidade que é alterada a cada iteração. Deve-se ter o cuidado para não utilizar a entidade fornecida ao iterador fora dele. Para coletar entidades dentro do iterador utilize o método Entity#clone()

Parameters:
Name Type Argument Description
callback function

Função parametrizada.
opt_context * <optional>

Contexto do callback, a palavra reservada "this" é equivalente ao objeto que deseja-se contextualizar. Se nenhum contexto for fornecido, a própria instância de EntitySet será utilizada.
Example
var chosenEntities = [];
entitySet.forEach(function (entity) {
  if (entity.get('iClass') === ngin.keys.Classes.GROUPS) {
    // errado
    chosenEntities.push(entity);

    // correto
    chosenEntities.push(entity.clone());
  }
});

insert(data)

Cria uma nova entidade com valores de propriedades informados. Caso a classe não seja informada em data, será utilizado o valor da propriedade #baseClass.

Este método possui um desempenho superior ao de criar uma entidade pelo #newEntity e atualizá-la com o método Entity#assign. Prefira o seu uso quando não for necessário ter acesso à instância da entidade criada.

Parameters:
Name Type Description
data Record.<*, *>

Valores das propriedades que devem ser atribuídos a nova entidade.
Returns:

Chave que identifica unicamente a entidade criada.

Type
number

merge(data)

Insere e atualiza as entidades com os dados informados. Caso os dados informados tenham informado o campo chave, será atualizada a entidade existente com essa chave, ou será gerado um erro caso não exista uma. Caso não seja informada uma chave, será criada uma entidade com os dados informados.

Parameters:
Name Type Description
data Record.<*, *> | Array.<*>

Dados de uma entidade ou um array com os dados das entidades a serem atualizados.
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:

Retorna um objeto com as propriedades inserted e updated. Essas propriedades serão um array das chaves das entidades inseridas ou modificadas por este método.

Type
Object

newEntity(data)

Cria uma nova entidade com a classe informada. Este método deve ser utilizado apenas quando deseja-se obter a instância da entidade. Por questões de desempenho sempre prefira usar #insert para criar uma entidade.

Parameters:
Name Type Description
data number | Record.<*, *>

Classe da nova entidade ou um objeto contendo os valores das propriedades da entidade a ser criada. Caso seja informado um objeto, os nomes dos campos devem ser padronizados em minúsculo.
Returns:

A entidade criada será retornada em edição, sendo responsabilidade do usuário desta API efetivar a inserção por meio do método Entity#post.

Type
Entity

persist()

Persiste as modificações realizadas nas entidades desta coleção.

As alterações realizadas nas instâncias de Entity retornadas por esta classe, como as retornadas pelos métodos #findByKey, #newEntity e #forEach, que não tenham sido efetivadas pelo método Entity#post serão efetivadas antes da persistência dos dados. Caso deseje descartar as alterações de uma entidade obtida de um EntitySet, utilize o método Entity#cancel.

See:
Returns:

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

Type
number
Example
const Classes = require('@nginstack/engine/keys/Classes');
 const EntitySet = require('@nginstack/orm/lib/EntitySet');
 const users = EntitySet.fromClass(Classes.USERS);
 const currentUser = users.findByKey(session.userKey);
 try {
   doGoodThingsWith(currentUser);
 } finally {
   users.persist();
 }

remove(entity)

Remove a entidade informada.

Parameters:
Name Type Description
entity number | Entity

Chave ou instância da entidade a ser removida.
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

removeAll()

Remove todas as entidades deste coleção.

some(callback [, opt_context])

Itera na coleção de entidades fornecendo uma entidade que pode ser alterada a cada iteração até que o resultado do callback fornecido seja verdadeira. O resultado deste método é um valor booleano e será falso somente se o resultado do callback for falso. Deve-se ter o cuidado para não utilizar a entidade fornecida ao callback fora dele.

Parameters:
Name Type Argument Description
callback function

Função parametrizada.
opt_context * <optional>

Contexto do callback, a palavra reservada "this" é equivalente ao objeto que deseja-se contextualizar. Se nenhum contexto for fornecido, a própria instância de EntitySet será utilizada.
Returns:
Type
boolean
Example
var entitySet = EntitySet.fromClass(ngin.keys.Classes.GROUPS_AND_ROLES);
var hasGroup = entitySet.some(function (entity) {
  return entity.get('iClass') === ngin.keys.Classes.GROUPS;
});

toJSONSchema()

Exporta a definição de uma coleção de entidades da classe informada no construtor, no formato JSON Schema. O resultado será similar ao do Entity#toJSONSchema, apenas que o esquema indicará que é um array de dados desse esquema.

Returns:
Type
Object

toJSONString()

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

Returns:
Type
string

update(key, data)

Atualiza a entidade identificada por key com valores das propriedades informadas. Será gerado um erro caso não exista uma entidade com a chave indicada.

Este método possui um desempenho superior ao de obter uma entidade pelo #findByKey e atualizá-la com o método Entity#assign. Prefira o seu uso quando não for necessário ter acesso à instância da entidade alterada.

Parameters:
Name Type Description
key number

Chave da entidade a ser atualizada.
data Object

Valores das propriedades que devem ser atribuídos a nova entidade.
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