Funciones personalizadas

Es posible crear funciones personalizadas utilizando JavaScript. Estas funciones pueden ser creadas desde dos lugares:

• Desde Proyecto: Las funciones creadas desde esta página pueden ser utilizadas en cualquier modelo que pertenezca al proyecto.

• Desde las operaciones de Anonimizar o Sintetizar: Las funciones creadas desde aquí se aplican únicamente a la columna seleccionada. Estas funciones no se guardan de forma global y, por lo tanto, no pueden ser reutilizadas en otros lugares de la aplicación.

Creando una nueva función

La página para crear una nueva función está dividida en 3 partes:

• Consola: el área donde el usuario escribe el código de la función.
• Vista previa: El usuario puede ver el resultado del código ejecutándose utilizando los campos de Entrada y haciendo clic en el botón Ejecutar. También es posible agregar más registros a la vista previa.
• Funciones: Una lista de funciones predefinidas. Cuando se hace clic en una función, un código de sugerencia de la función se pega en la consola.

Funciones

chance (seed?)

Devuelve una instancia de Chance

• seed: valor inicial para instanciar Chance.

Ejemplos

chance().integer({ min: 100, max: 1000 });
chance(3131231).integer({ min: 100, max: 1000 });
chance(Math.random() * Date.now()).integer({ min: 100, max: 1000 });
chance().address();
chance().paragraph({ sentences: 1 };

Consulta la [documentación del paquete Chance ↗] (https://chancejs.com/) para más información

dateFormat (val, format)

Formatea una fecha con una máscara

• val: valor de fecha que puede ser una cadena, un número o un objeto Date.
• format: especifica el formato en el que se mostrará la fecha.

return dateFormat($val, 'yyyy-mm-dd')

Ejemplos

dateFormat(Date.now(), 'yy')
dateFormat('99/10/31', 'yy')
dateFormat('shortTime', 'yy')
dateFormat(new Date($val), 'yyyy-mm-dd')

db

Conecta a una base de datos utilizando los controladores de Gigantics. Lista de métodos disponibles:

connect (driver, options)

Devuelve una conexión a una base de datos.

• driver: cadena del controlador. Puede ser mysql, postgres, mssql, oracle, mongodb o sqlite3.
• options: lista de opciones para establecer la conexión.
  • host: dirección del endpoint.
  • port: número de puerto.
  • user: usuario de la base de datos.
  • password: contraseña de la base de datos para el usuario especificado.
  • db: nombre de la base de datos.

Ejemplos

const rows = await once(async () => {
  const d = await db.connect('mssql', {
    host: 'my.db.server',
    user: 'adventure',
    password: 's3CrEt',
    db: 'adventure'
  })
  const { recordset: res } = await d.query('SELECT * from Person.Person')
  return res[0]
})

decrypt (val, secret, options)

Desencripta datos utilizando el algoritmo aes-256-gcm

• val: cadena a desencriptar.
• secret: clave para desencriptar la cadena. Debe ser el mismo secreto que se usó con encrypt.
• options: solo se usa con valores encriptados con el formato anterior (valores que no empiezan por v2:).
  • saltLength: longitud del parámetro salt. Por defecto 5.

decrypt lee tanto los valores actuales v2: como los encriptados por versiones anteriores de Gigantics, así que los datos encriptados antes de una actualización se pueden seguir desencriptando.

return decrypt($val, 'MyS3cr3tkey')

deepReplace (oldStr, newStr, options, record)

Reemplaza los mismos datos en todas partes del registro actual

• oldStr: valor de cadena antigua.
• newStr: nueva cadena para reemplazar.
• options:
  • smartCase: si es true, se ignorará el uso de mayúsculas y minúsculas al coincidir la cadena a reemplazar.
• record: un registro cuyas propiedades serán verificadas para el reemplazo de datos.

Ejemplos

deepReplace('prev text', 'new text', {}, $rec)
deepReplace('old text', 'new text', { smartCase: true })
deepReplace('old text', 'new text', { smartCase: true }, $rec)
deepReplace(
  'old text',
  'new text',
  { smartCase: true },
  { CUSTOMER: 'Acme', CUSTOMER_KEY: 'ACME', ID: 3433 }
)

encrypt (val, secret, options)

Encripta datos utilizando aes-256-gcm

• val: valor a encriptar. Los valores que no son texto se convierten a texto. No acepta valores null.
• secret: clave para encriptar la cadena.
• options: se acepta por compatibilidad con versiones anteriores y se ignora.

La clave de cifrado se deriva del secreto una sola vez y se reutiliza para todos los valores, por lo que encriptar tablas grandes es rápido. Cada valor recibe su propio vector de inicialización (IV) aleatorio. El resultado es una cadena versionada que empieza por v2: seguida del IV, la etiqueta de autenticación y los datos encriptados en hexadecimal.

return encrypt($val, 'MyS3cr3tkey')

faker

Devuelve una instancia de Faker

Ejemplos

faker.address.city()
faker.lorem.lines()
faker.setLocale('es_MX')
faker.datatype.number({ min: 1, max: 100 })

Consulta la documentación del paquete Faker para una lista completa de funciones disponibles.

file

Devuelve un objeto de archivo con los siguientes métodos disponibles:

open (path, flags, ...args)

Abre y posiblemente crea un archivo.

• path: Una ruta a un archivo. Si se proporciona una URL, debe usar el protocolo file:.
• flags: Una cadena que indica el tipo de operaciones que se realizarán en el descriptor de archivo devuelto. Sus valores pueden ser r, r+, rs+, w, wx, w+, wx+, a, ax, a+ o ax+.
• args:
  • mode: Un modo de archivo. Si se pasa una cadena, se analiza como un entero octal. Si no se proporciona, el valor predeterminado es 0o666.

write (file, data, options)

Escribe datos en un archivo de forma asíncrona, reemplazando el archivo si ya existe. No es seguro llamar a fsPromises.writeFile() varias veces en el mismo archivo sin esperar a que se resuelva (o rechace) la Promesa.

• file: Una ruta a un archivo.
• data: Los datos a escribir. Si se proporciona algo que no sea un Buffer o Uint8Array, el valor se convierte en una cadena.
• options: Ya sea la codificación para el archivo, o un objeto que opcionalmente especifique la codificación, el modo de archivo y la bandera. Si no se proporciona codificación, se usa el valor predeterminado de utf8. Si no se proporciona modo, se usa el valor predeterminado de 0o666. Si el modo es una cadena, se analiza como un entero octal. Si no se proporciona la bandera, se usa el valor predeterminado de w.

read (file, data, options)

Lee de forma asíncrona el contenido completo de un archivo.

• file: Una ruta a un archivo.
• options: Un objeto que puede contener una bandera opcional. Si no se proporciona una bandera, el valor predeterminado es 'r'.

append (file, data, options)

Agrega datos a un archivo de forma asíncrona, creando el archivo si no existe.

• file: Una ruta a un archivo. Si se proporciona una URL, debe usar el protocolo file:. El soporte para URL es experimental. Si se proporciona un FileHandle, el archivo subyacente no se cerrará automáticamente.
• data: Los datos a escribir. Si se proporciona algo que no sea un Buffer o Uint8Array, el valor se convierte en una cadena.
• options: Ya sea la codificación para el archivo, o un objeto que opcionalmente especifique la codificación, el modo de archivo y la bandera. Si no se proporciona codificación, se usa el valor predeterminado de utf8. Si no se proporciona modo, se usa el valor predeterminado de 0o666. Si el modo es una cadena, se analiza como un entero octal. Si no se proporciona la bandera, se usa el valor predeterminado de a.

readdir (path, ...args)

Lee de forma asíncrona un directorio.

• path: Una ruta a un archivo. Si se proporciona una URL, debe usar el protocolo file:.
• options: La codificación (o un objeto que especifique la codificación), utilizada como la codificación del resultado. Si no se proporciona, se usa 'utf8'.

rename (oldPath, newPath)

Cambia de forma asíncrona el nombre o la ubicación de un archivo o directorio.

• oldPath: La ruta del archivo que se desea modificar.
• newPath: Nuevo nombre o ruta para el archivo.

copyFile (src, dest, ...args)

Copia de forma asíncrona src a dest. Por defecto, dest se sobrescribe si ya existe. Node.js no garantiza la atomicidad de la operación de copia. Si ocurre un error después de que el archivo de destino se haya abierto para escritura, Node.js intentará eliminar el destino.

• src: Una ruta al archivo fuente.
• dest: Una ruta al archivo de destino.
• args:
  • flags: Un entero opcional que especifica el comportamiento de la operación de copia. La única bandera admitida es fs.constants.COPYFILE_EXCL, que hace que la operación de copia falle si dest ya existe.

truncate (path, ...args)

Trunca de forma asíncrona un archivo a una longitud especificada.

• path: Una ruta a un archivo. Si se proporciona una URL, debe usar el protocolo file:.
• args:
  • len: Si no se especifica, el valor predeterminado es 0.

mkdir (path, ...args)

Crea de forma asíncrona un directorio.

• path: Una ruta a un archivo. Si se proporciona una URL, debe usar el protocolo file:.
• args:
  • options: Ya sea el modo de archivo, o un objeto que opcionalmente especifique el modo de archivo y si se deben crear carpetas principales. Si se pasa una cadena, se analiza como un entero octal. Si no se especifica, el valor predeterminado es 0o777.

mkdtemp (prefix, ...args)

Crea de forma asíncrona un directorio temporal único. Genera seis caracteres aleatorios que se agregarán detrás de un prefijo requerido para crear un directorio temporal único.

• prefix: Cadena que precederá al directorio temporal generado.
• args:
  • options: La codificación (o un objeto que especifique la codificación), utilizada como la codificación del resultado. Si no se proporciona, se usa 'utf8'.

base (path?)

Devuelve la ruta base.

• path: Ruta de archivo para agregar a la ruta base.

home (path?)

Devuelve la ruta del directorio de inicio.

• path: Ruta de archivo para agregar a la ruta del directorio de inicio.

Ejemplos

file.append('/tmp/file.txt', '\nhello')

genLabel (label, locale, opts)

Devuelve datos generados a partir de una etiqueta

• label: Nombre de la etiqueta de Gigantics.
• locale: Cadena de configuración regional.
• opts:
  • prefix: Cadena para agregar antes de los datos falsos.
  • suffix: Cadena para agregar después de los datos falsos.
  • case: Puede ser upper, lower, title, kebab, snake.
  • type: Variante a generar, en las etiquetas que tienen tipos. Para person/name puede ser first, last, full (nombre y apellido) o last_first (apellido y nombre).
  • suffixEnabled: Booleano que indica si el uso del sufijo está habilitado.
  • prefixEnabled: Booleano que indica si el uso del prefijo está habilitado.

Ejemplos

return genLabel('person/name', 'es-ES', {})

return genLabel('person/name', 'es-ES', { type: 'last_first' })

genLike (val, opts?)

Genera datos aleatorios que se asemejan a la entrada

• val: Cadena que se utilizará como referencia para la generación de datos.
• opts:
  • alphabet: Cadena que contiene los caracteres que se utilizarán en los datos resultantes.
  • re: Expresión regular.
  • size: Tamaño de la cadena resultante.
  • remove: Cadena que contiene los caracteres que se eliminarán.
  • add: Cadena que se agregará a los datos.

genLike(23839293)
genLike('X121221Z')

genRe (re, opts?)

Devuelve datos aleatorios que coinciden con la expresión regular de entrada

• re: Expresión regular.
• opts:
  • alphabet: Cadena que contiene los caracteres que se utilizarán en los datos resultantes.
  • re: Expresión regular.
  • size: Tamaño de la cadena resultante.
  • remove: Cadena que contiene los caracteres que se eliminarán.
  • add: Cadena que se agregará a los datos.

Ejemplos

genRe(/[A-D]{1}[1-3]{1}\d{4}/)
genRe(/\d{4}/) /* generate 4 digits numbers */
genRe('w{3}') /* 3 printable chars */
genRe(
  /[A-D]{1}[1-3]{1}\d{4}/
) /* letra de A a D, número del 1 al 3 y luego 4 dígitos */

hmac (val, secret, algo, outFmt)

Devuelve un hash con clave (HMAC) de la entrada. El mismo valor y el mismo secreto dan siempre la misma salida, así que un valor hasheado en una tabla coincide con el mismo valor hasheado en otra, sin necesidad de diccionario.

• val: Valor a hashear. Los valores que no son texto se convierten a texto. null y undefined se devuelven sin cambios.
• secret: Clave secreta. Es obligatoria: la función falla si está vacía.
• algo: Algoritmo a aplicar. Por defecto SHA-256. Puede ser: SHA-1, SHA-224, SHA3-224, SHA-256, SHA3-256, SHA-384, SHA3-384, SHA-512 o SHA3-512
• outFmt: Formato de salida. Por defecto HEX. Valores posibles: HEX, B64 o BYTES

hmac($val, 'my-secret')
hmac($val, 'my-secret', 'SHA-512')
hmac($val, 'my-secret', 'SHA-256', 'B64')

Cuándo usarla:

• En lugar de md5 o sha: estas funciones hashean solo el valor, así que cualquiera puede hashear una lista de valores conocidos (emails, documentos de identidad) y comparar los resultados para recuperar los originales. hmac añade una clave secreta, de modo que sin la clave los hashes no se pueden reproducir. Si es posible, guarda el secreto fuera de la regla, por ejemplo en una variable secreta.
• En lugar del diccionario: usa hmac cuando un hash sea un valor de reemplazo aceptable y necesites valores consistentes entre tablas, jobs y entornos sin guardar un diccionario. Usa el diccionario cuando el valor de reemplazo deba parecer un dato real (un nombre, un email) o deba mantener el formato original.
• En lugar de encrypt: encrypt es reversible pero da una salida distinta cada vez, por lo que no sirve para claves. hmac no es reversible pero da siempre la misma salida, por lo que sirve para claves primarias y foráneas.

log

Envía mensajes al registrador de jobs. Lista de métodos disponibles

info (msg, ...args)

debug (msg, ...args)

trace (lev, msg, ...args)

warn (msg, ...args)

error (msg, ...args)

fail (msg, ...args)

Ejemplos

log.info('my message')

md5 (str, encoding)

Devuelve un valor hash md5

• str: Cadena a ser hasheada.
• encoding: Si no se especifica, su valor será hex.

md5('Some text')
md5($val, 'base64')

mem

Reutiliza valores de transformaciones entre entidades y campos. Lista de métodos disponibles:

do (scope, oldVal, fn, options?)

Almacena una entrada en memoria aplicando una cierta transformación si el valor no está ya establecido. Si se almacenó previamente, devuelve el valor memorizado.

• scope: El contexto o ámbito bajo el cual se almacena o almacenará el valor.
• oldVal: Valor clave para buscar en la memoria.
• fn: Transformación que se almacenará.
• options:
  • once: Si es true, el valor no se almacenará ni actualizará si ya existía. Su valor predeterminado es false.

set (scope, oldVal, newVal, options)

Almacena un valor en memoria bajo un cierto ámbito.

• scope: El contexto o ámbito bajo el cual se almacenará el valor.
• oldVal: Valor clave para buscar la entrada en memoria.
• newVal: El nuevo valor que se almacenará.
• options:
  • once: Si es true, el valor no se almacenará ni actualizará si ya existe.

get (scope, oldVal)

Recupera un valor de la memoria.

• scope: El contexto o ámbito bajo el cual se almacena el valor.
• oldVal: Valor clave para buscar la entrada en memoria.

Ejemplos

await mem.do('Person.Person', $val, () => $val + Math.random())
await mem.do('CUSTOMERS', $val, () => 'a new value')
await mem.set('person/name', $val, 'a new value')
const newVal = await mem.get('person/name', $val)

Ayuda

• Usa el paquete mem si necesitas sincronizar datos entre diferentes columnas/campos y tablas de entidades.
• El paquete mem almacena y recupera datos de un diccionario a nivel de proyecto, y establece valores utilizando una combinación de un ámbito y un valor de campo hasheado o encriptado.
• Recomendamos el uso del método mem.do. Solo establecerá un valor si el valor no se encuentra, y devolverá ya sea el valor memorizado, si existe, o el valor de retorno de la función. Cuando una tabla se lee en paralelo y dos lectores calculan a la vez un valor para la misma entrada, gana el primer valor guardado y mem.do lo devuelve a ambos.
• mem.get(scope, $val) - devuelve el valor memorizado, o undefined si no se encuentra.
• mem.set(scope, $val, newVal) - establece un nuevo valor en un ámbito.
• Las claves se calculan igual que en el resto del diccionario del proyecto (HMAC-SHA256 con el secreto del diccionario, o MD5 en los diccionarios creados por versiones anteriores), así que los valores guardados con mem se comparten con el diccionario de las reglas.

once (cb)

Ejecuta una función una vez, almacena en caché y devuelve el resultado.

• cb: Función a ejecutar

const myVar = once(() => 1000 * 1000)

randomDate (inicio?, fin?)

Devuelve una fecha aleatoria entre dos fechas dadas.

• inicio: Fecha de inicio como número, cadena u objeto Date.
• fin: Fecha de fin como número, cadena u objeto Date.

randomDate('1980-01-01', '2010-12-31')

randomNumber (min, max, type, opts)

Devuelve un número aleatorio del tipo especificado entre dos valores.

• min: valor mínimo que puede tomar el número generado
• max: valor máximo que puede tomar el número generado
• type: Puede ser integer o floating
• opts:
  • fixed: Número de decimales cuando el tipo es floating

randomNumber(0, 100, 'integer' || 'floating')
randomNumber(100)
randomNumber(100, 1_000_000)
randomNumber(100, 1_000_000, 'integer')
randomNumber(-100, 1_000_000, 'floating', { fixed: 2 })

sha (val, algo, inFmt, outFmt)

Devuelve el valor hash del dato de entrada.

• val: Valor a hashear. Los números se hashean por su texto (1 como '1'); null se devuelve sin cambios.
• algo: Algoritmo a aplicar. Por defecto SHA-512. Puede ser:
  SHA-1, SHA-224, SHA3-224, SHA-256, SHA3-256, SHA-384, SHA3-384,
  SHA-512 o SHA3-512
• inFmt: Formato de entrada. Por defecto TEXT. Valores posibles: HEX, TEXT, B64, BYTES, ARRAYBUFFER o UINT8ARRAY
• outFmt: Formato de salida. Por defecto HEX. Valores posibles: B64, HEX, BYTES, ARRAYBUFFER o UINT8ARRAY

El hash depende solo del valor: la misma entrada da siempre la misma salida, en cualquier fila, tabla o job. Las versiones anteriores arrastraban estado de una fila a la siguiente, por lo que el mismo valor podía dar hashes distintos; los valores hasheados con sha por esas versiones no coinciden con los que se generan ahora.

sha($val, 'SHA-512', 'TEXT', 'HEX')
sha('my data')
sha('mydata', 'SHA3-256')
sha($val, 'SHA-512', 'TEXT', 'BYTES')
sha('bXlkYXRh', 'SHA3-256', 'B64', 'B64')

smartReplace (str, before, after)

Reemplaza una cadena manteniendo el estilo de mayúsculas/minúsculas.

• str: Cadena de origen.
• before: Cadena a buscar.
• after: Cadena que se usará como reemplazo.

smartReplace('some string', 'search', 'replacement')
smartReplace('SmartPeople', 'people', 'phone')

strReverse (str)

Invierte una cadena dada.

• str: Cadena a invertir

strReverse($val)
strReverse('hello')

Ejemplos

Podemos crear una función para convertir una columna de temperatura de Fahrenheit a Celsius:

return (5 / 9) * ($val - 32)

Donde $val representa el valor del campo en la tabla.
Entrada → Salida:

También podemos usar funciones de JavaScript:

function toCelsius(fahrenheit) {
  return (5 / 9) * (fahrenheit - 32)
}
return toCelsius($val).toFixed(2)

Entrada → Salida: