Custom functions

It is possible to create customized functions using JavaScript. These functions can be created from two places:

• From Project: The functions created from this page can be used in any model that belongs to the project.

• From the Anonymize or Synthesize operations: Functions created from here only apply only to the selected column. These functions are not saved globally and thus they cannot be reused from other places in the application.

Creating a new function

The page for creating a new function is divided into 3 parts:

• Console: the area where the user codes the function.
• Preview: The user can see the result of the code being run by using the Input fields and clicking the Run button. It is also possible to add more records to the preview.
• Functions: A list of preset functions. When a function is clicked, a hint code of the function is pasted in the console.

Functions

chance (seed?)

Return a Chance instance

• seed: inital value to instantiate Chance with.

Examples

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 };

Check the [Chance package documentation ↗] (https://chancejs.com/) for more info

dateFormat (val, format)

Format date with a mask

• val: date value that can be a string, a number or a Date object.
• format: specifies the format in which the date will be shown.

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

Examples

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

db

Connects to a database using Gigantics drivers. List of methods available:

connect (driver, options)

Return a connection to a database.

• driver: driver string. It can be mysql, postgres, mssql, oracle, mongodb or sqlite3
• options: list of options to establish the connection.
  • host: endpoint address.
  • port: port number.
  • user: database user.
  • password: database password for the specified user.
  • db: database name.

Examples

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)

Decrypt data using aes-256-gcm algorithm

• val: string to be decrypted.
• secret: key to use to decrypt the string.
• options:
  • saltLength: length of the salt parameter

return decrypt($val, 'MyS3cr3tkey')

deepReplace (oldStr, newStr, options, record)

Replace the same data everywhere in the current record

• oldStr: old string value.
• newStr: new strig to replace with.
• options:
  • smartCase: if true word casing will be ignored when matching the string to be replaced.
• record: a record whose properties will be checked for data replacement.

Examples

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)

Encrypt data with aes-256-gcm

• val: string to be encrypted.
• secret: key to use to encrypt the string.
• options:
  • saltLength: length of the salt parameter

return encrypt($val, 'MyS3cr3tkey')

faker

Return a Faker instance

Examples

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

Check the Faker package documentation for a complete list of available functions

file

Return a file object with the following methods available:

open (path, flags, ...args)

Open and possibly create a file.

• path: A path to a file. If a URL is provided, it must use the file: protocol.
• flags: A string indicating the type of operations to be performed on the returned file descriptor. Its values can be r, r+, rs+, w, wx, w+, wx+, a, ax, a+ or ax+
• args:
  • mode: A file mode. If a string is passed, it is parsed as an octal integer. If not supplied, it defaults to 0o666.

write (file, data, options)

Asynchronously write data to a file, replacing the file if it already exists. It is unsafe to call fsPromises.writeFile() multiple times on the same file without waiting for the Promise to be resolved (or rejected).

• file: A path to a file.
• data: The data to write. If something other than a Buffer or Uint8Array is provided, the value is coerced to a string.
• options: Either the encoding for the file, or an object optionally specifying the encoding, file mode, and flag. If encoding is not supplied, the default of utf8 is used. If mode is not supplied, the default of 0o666 is used. If mode is a string, it is parsed as an octal integer. If flag is not supplied, the default of w is used.

read (file, data, options)

Asynchronously read the entire contents of a file.

• file: A path to a file.
• options: An object that may contain an optional flag. If a flag is not provided, it defaults to 'r'.

append (file, data, options)

Asynchronously append data to a file, creating the file if it does not exist.

• file: A path to a file. If a URL is provided, it must use the file: protocol. URL support is experimental. If a FileHandle is provided, the underlying file will not be closed automatically.
• data: The data to write. If something other than a Buffer or Uint8Array is provided, the value is coerced to a string.
• options: Either the encoding for the file, or an object optionally specifying the encoding, file mode, and flag. If encoding is not supplied, the default of utf8 is used. If mode is not supplied, the default of 0o666 is used. If mode is a string, it is parsed as an octal integer. If flag is not supplied, the default of a is used.

readdir (path, ...args)

Asynchronously read a directory.

• path: A path to a file. If a URL is provided, it must use the file: protocol.
• options: The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, 'utf8' is used.

rename (oldPath, newPath)

Asynchronously change the name or location of a file or directory.

• oldPath: The path of the file aimed to be modified.
• newPath: New name or path for the file.

copyFile (src, dest, ...args)

Asynchronously copie src to dest. By default, dest is overwritten if it already exists. Node.js makes no guarantees about the atomicity of the copy operation. If an error occurs after the destination file has been opened for writing, Node.js will attempt to remove the destination.

• src: A path to the source file.
• dest: A path to the destination file.
• args:
  • flags: An optional integer that specifies the behavior of the copy operation. The only supported flag is fs.constants.COPYFILE_EXCL, which causes the copy operation to fail if dest already exists.

truncate (path, ...args)

Asynchronously truncate a file to a specified length.

• path: A path to a file. If a URL is provided, it must use the file: protocol.
• args:
  • len: If not specified, defaults to 0.

mkdir (path, ...args)

Asynchronously create a directory.

• path: A path to a file. If a URL is provided, it must use the file: protocol.
• args:
  • options: Either the file mode, or an object optionally specifying the file mode and whether parent folders should be created. If a string is passed, it is parsed as an octal integer. If not specified, defaults to 0o777.

mkdtemp (prefix, ...args)

Asynchronously create a unique temporary directory. Generates six random characters to be appended behind a required prefix to create a unique temporary directory.

• prefix: string that will preceed the generated temporary directory.
• args:
  • options: The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, 'utf8' is used.

base (path?)

Return base path

• path: File path to append to the base path.

home (path?)

Return home path

• path: File path to append to the home path.

Examples

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

genLabel (label, locale, opts)

Return generated data from a label

• label: Gigantics label name.
• locale: Locale string.
• opts:
  • prefix: String to add before the fake data.
  • suffix: String to add after the fake data.
  • case: It can be upper, lower, title, kebab, snake.
  • suffixEnabled: Boolean that indicates whether suffix use is enabled.
  • prefixEnabled: Boolean that indicates whether prefix use is enabled.

Examples

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

genLike (val, opts?)

Output random data that looks like the input

• val: String that will be used as reference for data generation.
• opts:
  • alphabet: String containing the characters that will be used in the resulting data.
  • re: Regular expression.
  • size: Size of the resulting string.
  • remove: String containing the characters to be removed.
  • add: String that will be added to the data.

genLike(23839293)
genLike('X121221Z')

genRe (re, opts?)

Return random data that matches the input regexp

• re: Regular expression.
• opts:
  • alphabet: String containing the characters that will be used in the resulting data.
  • re: Regular expression.
  • size: Size of the resulting string.
  • remove: String containing the characters to be removed.
  • add: String that will be added to the data.

Examples

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}/
) /* letter from A to D, number from 1 to 3 then 4 digits */

log

Send messages to the job logger. List of methods available

info (msg, ...args)

debug (msg, ...args)

trace (lev, msg, ...args)

warn (msg, ...args)

error (msg, ...args)

fail (msg, ...args)

Examples

log.info('my message')

md5 (str, encoding)

Return an md5 hashed value

• str: String to be hashed.
• encoding: If not specified, its value will be hex.

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

mem

Reuse transformations values across entities and fields. List of methods available:

do (scope, oldVal, fn, options?)

Store a memory entry by applying a certain transformation if the value is not set already. If it was previously stored, it returns the memoized value.

• scope: The context or scope the value is or will be stored under.
• oldVal: Key value to look for in memory.
• fn: Transformation to be stored.
• options:
  • once: If true, the value won't be stored or updated when it previously existed. Its value is false by default.

set (scope, oldVal, newVal, options)

Store a value in memory under a certain scope.

• scope: The context or scope the value will be stored under.
• oldVal: Key value to look up the memory entry.
• newVal: The new value to be stored.
• options:
  • once: If true, the value won't be stored or updated if it exists.

get (scope, oldVal)

Retrieve a value from memory.

• scope: The context or scope the value is stored under.
• oldVal: Key value to look up the memory entry.

Examples

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)

Help

• Use the mem package if you need to sincronize data across different columns/fields and entity tables.
• The mem package stores and retrieves data from project-wide dictionary, and sets values using a combination of a scope and a hashed or encrypted field value.
• We recommend the use of the mem.do method. It will only set a value if the value is not found, and return either the memoized value, if it exists, or the function return value.
• mem.get(scope, $val) - returns the memoized value, or undefined if not found.
• mem.set(scope, $val, newVal) - sets a new value into a scope

once (cb)

Run a function once, caches and returns the result.

• cb: Function to be run

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

randomDate (start?, end?)

Return a random date, between two given dates.

• start: Start date as number, string or Date object.
• end: End date as number, string or Date object.

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

randomNumber (min, max, type, opts)

Return random number of the specified type between two values

• min: lower value the generated number can take
• max: higher value the generated number can take
• type: Can be integer or floating
• opts:
  • fixed: Specifies the number of decimals when the type is 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)

Return a hashed value from input

• val: Value to be hashed.
• algo: Algorithm to be applied. It can take one of the following values: SHA-1, SHA-224, SHA3-224, SHA-256, SHA3-256, SHA-384, SHA3-384, SHA-512, SHA3-512, SHAKE128, or SHAKE256
• intFmt: Input format. It can take one of the following values: HEX, TEXT, B64, BYTES, ARRAYBUFFER, or UINT8ARRAY
• outFmt: Output format. It can take one of the following values B64, HEX, BYTES, ARRAYBUFFER, or UINT8ARRAY

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

smartReplace (str, before, after)

Replace a string keeping the casing

• str: Source string.
• before: String to match.
• after: String to use as a replacement.

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

strReverse (str)

Reverse a given string.

• str: String to reverse

strReverse($val)
strReverse('hello')

Examples

We can create a function to convert a temperature column from Farenheit to Celsius:

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

Where $val represents the value of the field in the table.

Input -> Output:

We can also use JavaScript functions:

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

Input -> Output: