nginstack

Class: DBKey

@nginstack/engine/lib/dbkey/DBKey~ DBKey

new DBKey(key)

Representa uma chave no cache local e permite que os campos dessa chave possam ser acessadas como propriedades deste objeto.

No interpretador iJavaScript, chaves também podem ser representadas como números primitivos. No V8 isso não é possível e o uso desta classe é obrigatória. Para garantir a compatibilidade com os dois runtimes, é recomendado que o número seja convertido para um DBKey antes de acessar uma propriedade dinâmica.

Não é aceita a construção de um DBKey a partir de um valor null ou 0, o que gera implicações práticas no runtime V8 ao limitar o encadeamento da leitura de campos como propriedades. A expressão relKey.ifile.iparent.iname não gera erros no runtime Ije, mesmo quando os campos ifile e iparent são nulos, pois o Ije retorna null na tentativa de leitura das propriedades dos valores nulos. No V8, esse tipo de expressão irá gerar um erro, pois a leitura de uma propriedade de um null gera um TypeError, conforme especificação da linguagem.

Para a leitura de um campo a partir uma expressão, é recomendado o uso do método #val ou uma de suas variações com tipo de dado esperado. Esses métodos podem ser utilizados em instâncias de DBKey ou como métodos estáticos desta classe, quando é necessário ler um campo de uma chave numérica ou de um valor que potencialmente pode ser null.

Esta classe também é publicada pelo Engine por meio da variável global DBKey.

Parameters:
Name Type Description
key *

Representação numérica da chave.
Examples
const key = new DBKey(-1898186559);
key.val('iName'); // => 'administrator'
key.iname; // => 'administrator'
DBKey.str(-1898186559, 'iStatus.iName'); // => 'Ativo'

Methods

<static> bool(key, expr)

Retorna o valor do último campo informado na expressão caso a chave informada seja 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
key number | DBKey

Chave do registro do qual será lido o campo.
expr string

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

Valor do campo.

Type
boolean
Example
DBKey.bool(-1898186559, 'iClass.MAE'); // true
DBKey.bool(-1898186559, 'iName'); // true
DBKey.bool(-1898186559, 'iEnd'); // false

<static> date(key, expr)

Retorna o valor do último campo informado na expressão caso a chave informada seja 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
key number | DBKey

Chave do registro do qual será lido o campo.
expr string

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

Valor do campo.

Type
Date | null
Example
DBKey.date(session.userKey, 'iLastPasswdChg'); // Date()
DBKey.date(-1898186559, 'iEnd'); // null
DBKey.date(-1898186559, 'iName'); // Error()

<static> dbkey(key, expr)

Retorna o valor do último campo informado na expressão caso a chave informada seja de um registro que faça parte do cache local. O valor retornado sempre será uma instância de DBKey ou null.

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
key number | DBKey

Chave do registro do qual será lido o campo.
expr string

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

Valor do campo.

Type
DBKey | null
Example
DBKey.dbkey(-1898186559, 'iClass'); // DBKey(-1898187809)
DBKey.dbkey(-1898186559, 'iSmtpServer'); // null
DBKey.dbkey(-1898186559, 'iName'); // Error()

<static> equals(a, b)

Testa se as chaves informadas são iguais, aceitando representações numéricas e textuais delas.

Será retornado false se forem informados valores que não são representações de chave, como null e undefined, tornando esse método útil para comparar valores de chaves que podem potencialmente ser nulos, como no exemplo abaixo.

Parameters:
Name Type Description
a DBKey | string | number

Valor a ser testado.
b DBKey | string | number

Valor a ser testado.
Returns:

True se valores forem representações válidas de chaves e se elas forem iguais.

Type
boolean
Examples
for (ds.first(); !ds.eof && DBKey.equals(ds.dbkey('iStatus'), statusKey); ds.next()) {
}
DBKey.equals(DBKey(-1), -1); // true
DBKey.equals(-1, -1); // true
DBKey.equals(-1, '-1'); // true
DBKey.equals(-1, null); // false
DBKey.equals(DBKey(-1), -2); // false
DBKey.equals(null, null); // false

<static> from(value)

Obtém uma instância de DBKey a partir do valor informado.

Caso seja um DBKey, será retornado o próprio valor informado. Se for um número ou um texto que possa ser convertido em um número inteiro, cria uma nova instância para representar a chave. Esta função não verifica se a chave existe ou não no sistema. Ela apenas verifica se o valor pode representar uma chave. Em termos práticos ela garante que o valor pode ser utilizado como argumento para o construtor desta classe sem gerar um erro.

O uso desta função é recomendado para converter um valor para DBKey que potencialmente já pode ser um DBKey. Ao contrário do construtor, não será criada uma nova instância de DBKey se o valor informado já for um.

Parameters:
Name Type Description
value *

Valor a ser convertido em um DBKey.
Returns:

Valor convertido em um DBKey.

Type
DBKey
Example
DBKey.from(DBKey(-1)); // DBKey(-1)
DBKey.from(-1898186559); // DBKey(-1898186559)
DBKey.from(-2); // DBKey(-2)

DBKey.from('text'); // Error()
DBKey.from(NaN); // Error()

<static> isLike(value)

Retorna true se o valor informado for uma instância de DBKey ou se for um valor que possa representar uma chave do banco de dados.

Esta função não verifica se a chave existe ou não no sistema. Ela apenas verifica se o valor pode ser convertido em um DBKey, retornando true para valores inteiros e para null. Em termos práticos ela garante que o valor pode ser utilizado como argumento para o construtor desta classe sem gerar um erro.

Parameters:
Name Type Description
value *

Valor a ser verificado.
Returns:

True se o valor for uma instância de DBKey ou puder ser convertida para uma.

Type
boolean
Example
DBKey.isLike(DBKey.from((-1)); // true
DBKey.isLike(-1898186559); // true
DBKey.isLike('-1898186559'); // true
DBKey.isLike(-2); // true
DBKey.isLike(DBKey.from(null)); // true
DBKey.isLike(null); // true

DBKey.isLike('text'); // false
DBKey.isLike(NaN); // false
DBKey.isLike(undefined); // false
DBKey.isLike(''); // false

<static> num(key, expr)

Retorna o valor do último campo informado na expressão caso a chave informada seja 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
key number | DBKey

Chave do registro do qual será lido o campo.
expr string

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

Valor do campo.

Type
number
Example
DBKey.num(-1898186559, 'iClass.MAE'); // -1898187811
DBKey.num(-1898186559, 'iName'); // Error()

<static> str(key, expr)

Retorna o valor do último campo informado na expressão caso a chave informada seja 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
key number | DBKey

Chave do registro do qual será lido o campo.
expr string

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

Valor do campo.

Type
string
Example
DBKey.str(-1898186559, 'iStatus.iName'); // 'Ativo'

<static> val(key, expr)

Retorna o valor do último campo informado na expressão caso a chave informada seja de um registro que faça parte do cache local.

Tentar obter um campo que não existe na tabela do registro produzirá um erro. 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 este 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/engine/lib/dbkey/DBKey~DBKey.str
* module:@nginstack/engine/lib/dbkey/DBKey~DBKey.num
* module:@nginstack/engine/lib/dbkey/DBKey~DBKey.bool
* module:@nginstack/engine/lib/dbkey/DBKey~DBKey.date
* module:@nginstack/engine/lib/dbkey/DBKey~DBKey.dbkey
Parameters:
Name Type Description
key number | DBKey

Chave do registro do qual será lido o campo.
expr string

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

Valor do campo.

Type
string | number | null | boolean | Date
Example
DBKey.val(-1898186559, 'iName'); // => 'administrator'
DBKey.val(-1898186559, 'iClass.NOME') // => 'Usuários'
DBKey.val(-1898186559, 'iUnknownField') // => Error()

bool(expr)

Retorna o valor do último campo informado na expressão caso esta chave seja 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
DBKey.from(-1898186559).bool('iClass.MAE'); // true
DBKey.from(-1898186559).bool('iName'); // true
DBKey.from(-1898186559).bool('iEnd'); // false

date(expr)

Retorna o valor do último campo informado na expressão caso esta chave seja 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
DBKey.from(session.userKey).date('iLastPasswdChg'); // Date()
DBKey.from(-1898186559).date('iEnd'); // null
DBKey.from(-1898186559).date('iName'); // Error()

dbkey(expr)

Retorna o valor do último campo informado na expressão caso esta chave seja de um registro que faça parte do cache local. O valor retornado sempre será uma instância de DBKey ou null.

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
DBKey.from(-1898186559).dbkey('iClass'); // DBKey(-1898187809)
DBKey.from(-1898186559).dbkey('iSmtpServer'); // null
DBKey.from(-1898186559).dbkey('iName'); // Error()

equals(value)

Testa se o valor informado é uma chave igual a esta DBKey, ou um número ou string que represente a mesma chave.

Parameters:
Name Type Description
value DBKey | string | number

Valor a ser testado.
Returns:

True se o valor informado for uma chave igual a esta DBKey.

Type
boolean
Example
DBKey.from(-1).equals(-1); // true
DBKey.from(-1).equals(DBKey(-1)); // true
DBKey.from(-1).equals('-1'); // true
DBKey.from(-1).equals(null); // false
DBKey.from(-1).equals(-2); // false

num(expr)

Retorna o valor do último campo informado na expressão caso esta chave seja 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
DBKey.from(-1898186559).num('iClass.MAE'); // -1898187811
DBKey.from(-1898186559).num('iName'); // Error()

str(expr)

Retorna o valor do último campo informado na expressão caso esta chave seja 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
DBKey.from(-1898186559).str('iStatus.iName'); // 'Ativo'

val(expr)

Retorna o valor do último campo informado na expressão caso esta chave seja de um registro que faça parte do cache local.

Tentar obter um campo que não existe na tabela do registro produzirá um erro. 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 este 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/engine/lib/dbkey/DBKey~DBKey#str
* module:@nginstack/engine/lib/dbkey/DBKey~DBKey#num
* module:@nginstack/engine/lib/dbkey/DBKey~DBKey#bool
* module:@nginstack/engine/lib/dbkey/DBKey~DBKey#date
* module:@nginstack/engine/lib/dbkey/DBKey~DBKey#dbkey
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 | number | null | boolean | Date
Example
const key = new DBKey(-1898186559);
key.val('iName'); // => 'administrator'
key.val('iClass.NOME') // => 'Usuários'
key.val('iUnknownField') // => Error()