Skip to content

# Util

## util : `object`

Various utility functions: HTTP, time/date, barcode creation, clipboard, etc.

Kind: global namespace

- util : `object`
  - .uuid : `object`
    - .v4() ⇒ `string`
    - .short([length]) ⇒ `string`
  - .http : `object`
    - .webhook : `object`
      - .geturl(sourcename) ⇒ `Promise.<string>`
      - .poll(sourcename) ⇒ `Promise.<Array.<Object>>`
      - .ack(webhookid)
    - .post(url, data, [responseType], [headers], [method], [continueOnBadStatusCode], [timeoutSeconds]) ⇒ `Promise.<(string|Blob|ArrayBuffer|Object)>`
    - .fetch(url, [responseType], [timeoutSeconds]) ⇒ `Promise.<(string|Blob|ArrayBuffer|Object)>`
  - .string : `object`
    - .split(input, separator, [limit]) ⇒ `Array.<string>`
    - .chunk(input, chunksize) ⇒ `Array.<string>`
  - .time : `object`
    - .now() ⇒ `number`
    - .diff(compareto) ⇒ `number`
    - .strtotime(str) ⇒ `number`
    - .format(format, [timestamp]) ⇒ `string`
    - .toDateString(timestamp) ⇒ `string`
    - .toTimeString(timestamp) ⇒ `string`
  - .clipboard : `object`
    - .copy(text, [showNotification]) ⇒ `Promise.<boolean>`
  - .barcode : `object`
    - .getBuffer(data, [type], [height], [scale], [includetext]) ⇒ `Promise.<Buffer>`
    - .getBase64(data, [type], [height], [scale], [includetext]) ⇒ `Promise.<string>`
  - .geography : `object`
    - .isoToCountryName(iso) ⇒ `string`
  - .objectEquals(a, b) ⇒ `boolean`
  - .delay([ms]) ⇒ `Promise`

### util.uuid : `object`

Unique ID generators.

Kind: static namespace of `util`

- .uuid : `object`
  - .v4() ⇒ `string`
  - .short([length]) ⇒ `string`

#### uuid.v4() ⇒ `string`

Generate a UUID string

Kind: static method of `uuid`
Returns: `string` - UUID v4 with dashes: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx

#### uuid.short([length]) ⇒ `string`

Generate a short random alphanumeric string.

Kind: static method of `uuid`
Returns: `string` - A string of length `length`, from the character set "acdefhjkmnpqrtuvwxy0123456789".

Param | Type | Default | Description
--- | --- | --- | ---
[length] | `number` | `16` | String character count.

### util.http : `object`

HTTP requests and webhooks.

Kind: static namespace of `util`

- .http : `object`
  - .webhook : `object`
    - .geturl(sourcename) ⇒ `Promise.<string>`
    - .poll(sourcename) ⇒ `Promise.<Array.<Object>>`
    - .ack(webhookid)
  - .post(url, data, [responseType], [headers], [method], [continueOnBadStatusCode], [timeoutSeconds]) ⇒ `Promise.<(string|Blob|ArrayBuffer|Object)>`
  - .fetch(url, [responseType], [timeoutSeconds]) ⇒ `Promise.<(string|Blob|ArrayBuffer|Object)>`

#### http.webhook : `object`

Use webhooks via a PostalPoint cloud relay service.

Kind: static namespace of `http`

- .webhook : `object`
  - .geturl(sourcename) ⇒ `Promise.<string>`
  - .poll(sourcename) ⇒ `Promise.<Array.<Object>>`
  - .ack(webhookid)

##### webhook.geturl(sourcename) ⇒ `Promise.<string>`

geturl - Returns a public URL that can be used as a webhook target/endpoint for third-party integrations.

Kind: static method of `webhook`
Returns: `Promise.<string>` - A URL for the webhook.

Param | Type | Description
--- | --- | ---
sourcename | `string` | Unique identifier for the webhook

##### webhook.poll(sourcename) ⇒ `Promise.<Array.<Object>>`

poll - Returns an array of webhook payloads received by the webhook identified by `sourcename`.

Kind: static method of `webhook`
Returns: `Promise.<Array.<Object>>` - Payloads as received by the webhook relay service.

Param | Type | Description
--- | --- | ---
sourcename | `string` | Unique identifier for the webhook

Example

    [
         {
             // Unique ID. Used for ack(webhookid).
             id: 123,

             // UNIX timestamp (in seconds) of when the data was received by the webhook URL.
             timestamp: 1234567890,

             // Source name set in geturl()
             source: "sourcename",

             // JSON string of all the HTTP headers sent to the webhook URL.
             headers: "{'Content-Type': 'application/json'}",

             // Entire HTTP request body sent to the webhook URL.
             body: ""
         }
    ]

##### webhook.ack(webhookid)

Acknowledge receipt of a webhook payload, deleting it from the relay server. Webhook payload is only queued for deletion, so polling may still return it for a short time.

Kind: static method of `webhook`

Param | Type | Description
--- | --- | ---
webhookid | `number` | Numeric unique ID received with the payload. See `poll`.

#### http.post(url, data, [responseType], [headers], [method], [continueOnBadStatusCode], [timeoutSeconds]) ⇒ `Promise.<(string|Blob|ArrayBuffer|Object)>`

post - Fetch a HTTP POST request.

Kind: static method of `http`
Returns: `Promise.<(string|Blob|ArrayBuffer|Object)>` - The server response body. See `responseType` parameter.

Param | Type | Default | Description
--- | --- | --- | ---
url | `string` |  |
data | `Object.<string, string>` |  | POST data key/value list
[responseType] | `string` | `"text"` | "text", "blob", "buffer", or "json"
[headers] | `Object.<string, string>` |  | HTTP headers to send. Defaults to `{"Content-Type": "application/json"}`.
[method] | `string` | `"POST"` |
[continueOnBadStatusCode] | `boolean` | `false` | If false, throws an Error when the HTTP response code is not 2XX. If true, ignores the response code and proceeds as normal.
[timeoutSeconds] | `number` | `15` | Aborts the request (timeout) after this many seconds.

#### http.fetch(url, [responseType], [timeoutSeconds]) ⇒ `Promise.<(string|Blob|ArrayBuffer|Object)>`

fetch - Fetch a HTTP GET request.

Kind: static method of `http`
Returns: `Promise.<(string|Blob|ArrayBuffer|Object)>` - The server response body. See `responseType` parameter.

Param | Type | Default | Description
--- | --- | --- | ---
url | `string` |  |
[responseType] | `string` | `"text"` | "text", "blob", "buffer", or "json"
[timeoutSeconds] | `number` | `15` | Aborts the request (timeout) after this many seconds.

### util.string : `object`

String manipulation functions.

Kind: static namespace of `util`

- .string : `object`
  - .split(input, separator, [limit]) ⇒ `Array.<string>`
  - .chunk(input, chunksize) ⇒ `Array.<string>`

#### string.split(input, separator, [limit]) ⇒ `Array.<string>`

Split a string with a separator regex.

Kind: static method of `string`

Param | Type | Description
--- | --- | ---
input | `string` | Input string
separator | `string` | Passed to `new RegExp(separator, 'g')`
[limit] | `number` | Maximum number of splits to perform

#### string.chunk(input, chunksize) ⇒ `Array.<string>`

Split a string into chunks of length `chunksize`.

Kind: static method of `string`

Param | Type | Description
--- | --- | ---
input | `string` | Input string
chunksize | `string` | Number of characters per chunk

### util.time : `object`

Date and time functions

Kind: static namespace of `util`

- .time : `object`
  - .now() ⇒ `number`
  - .diff(compareto) ⇒ `number`
  - .strtotime(str) ⇒ `number`
  - .format(format, [timestamp]) ⇒ `string`
  - .toDateString(timestamp) ⇒ `string`
  - .toTimeString(timestamp) ⇒ `string`

#### time.now() ⇒ `number`

Get the current UNIX timestamp in seconds.

Kind: static method of `time`

#### time.diff(compareto) ⇒ `number`

Get the number of seconds between now and the given Date or UNIX timestamp in seconds.

Kind: static method of `time`

Param | Type
--- | ---
compareto | `number` | `Date`

#### time.strtotime(str) ⇒ `number`

Parse a string date and return UNIX timestamp (in seconds).

Kind: static method of `time`

Param | Type
--- | ---
str | `string`

#### time.format(format, [timestamp]) ⇒ `string`

Take a Date or UNIX timestamp in seconds and format it to a string. Mostly compatible with the PHP date format codes.

Kind: static method of `time`

Param | Type | Default | Description
--- | --- | --- | ---
format | `string` |  | "Y-m-d H:i:s", etc
[timestamp] | `number` | `Date` | `now()` |

#### time.toDateString(timestamp) ⇒ `string`

Format a UNIX timestamp (in seconds) as a localized date string.

Kind: static method of `time`

Param | Type
--- | ---
timestamp | `number`

#### time.toTimeString(timestamp) ⇒ `string`

Format a UNIX timestamp (in seconds) as a localized time string.

Kind: static method of `time`

Param | Type
--- | ---
timestamp | `number`

### util.clipboard : `object`

OS clipboard

Kind: static namespace of `util`

#### clipboard.copy(text, [showNotification]) ⇒ `Promise.<boolean>`

Copy a string to the system clipboard.

Kind: static method of `clipboard`
Returns: `Promise.<boolean>` - True if the copy succeeded, else false.

Param | Type | Default | Description
--- | --- | --- | ---
text | `string` |  |
[showNotification] | `boolean` | `false` | If true, a "Copied" notification will appear onscreen briefly.

### util.barcode : `object`

Barcode image generation functions.

Kind: static namespace of `util`

- .barcode : `object`
  - .getBuffer(data, [type], [height], [scale], [includetext]) ⇒ `Promise.<Buffer>`
  - .getBase64(data, [type], [height], [scale], [includetext]) ⇒ `Promise.<string>`

#### barcode.getBuffer(data, [type], [height], [scale], [includetext]) ⇒ `Promise.<Buffer>`

Get a PNG image buffer of a barcode. Uses library "bwip-js".

Kind: static method of `barcode`
Returns: `Promise.<Buffer>` - PNG data for the barcode.

Param | Type | Default | Description
--- | --- | --- | ---
data | `string` |  |
[type] | `string` | `"\"code128\""` |
[height] | `number` | `10` |
[scale] | `number` | `2` |
[includetext] | `boolean` | `false` | Set true to render the barcode's content as text below the code.

#### barcode.getBase64(data, [type], [height], [scale], [includetext]) ⇒ `Promise.<string>`

Get a PNG image of a barcode as a base64 data URI. Uses library "bwip-js".

Kind: static method of `barcode`
Returns: `Promise.<string>` - "data:image/png;base64,..."

Param | Type | Default | Description
--- | --- | --- | ---
data | `string` |  |
[type] | `string` | `"\"code128\""` |
[height] | `number` | `10` |
[scale] | `number` | `2` |
[includetext] | `boolean` | `false` | Set true to render the barcode's content as text below the code.

### util.geography : `object`

Kind: static namespace of `util`

#### geography.isoToCountryName(iso) ⇒ `string`

Get a human-readable country name from an ISO country code.

Kind: static method of `geography`

Param | Type | Description
--- | --- | ---
iso | `string` | `number` | 2 or 3 letter country code, or numeric country code.

### util.objectEquals(a, b) ⇒ `boolean`

Compare two objects for equality. See https://stackoverflow.com/a/16788517

Kind: static method of `util`
Returns: `boolean` - True if equal, else false.

Param | Type
--- | ---
a | `*`
b | `*`

### util.delay([ms]) ⇒ `Promise`

Pause execution for some amount of time in an async function, i.e., returns a Promise that resolves in some number of milliseconds.

Kind: static method of `util`

Param | Type | Default | Description
--- | --- | --- | ---
[ms] | `number` | `1000` | Number of milliseconds to pause.