util
@prismatic-io/spectral › "util"
The util
module provides a set of functions commonly needed to author custom components.
Many functions in the util
module are used to coerce data into a particular type, and can be accessed through util.types
.
For example, util.types.toInt("5.5")
will return an integer, 5
.
#
Index#
Functions- formatJsonExample
- isBigInt
- isBool
- isBufferDataPayload
- isData
- isDate
- isInt
- isJSON
- isNumber
- isUrl
- keyValPairListToObject
- lowerCaseHeaders
- toBigInt
- toBool
- toBufferDataPayload
- toData
- toDate
- toInt
- toJSON
- toNumber
- toString
#
FunctionsConst
formatJsonExample#
▸ formatJsonExample(input
: unknown): string
Defined in packages/spectral/src/util.ts:319
This function helps to format JSON examples for documentation.
Parameters:
Name | Type | Description |
---|---|---|
input | unknown | An object to be JSONified. |
Returns: string
This function returns a code block that can be used for documentation.
Const
isBigInt#
▸ isBigInt(value
: unknown): value is bigint
Defined in packages/spectral/src/util.ts:143
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The value to test |
Returns: value is bigint
This function returns true if the type of value
is a bigint, or false otherwise.
Const
isBool#
▸ isBool(value
: unknown): value is boolean
Defined in packages/spectral/src/util.ts:24
Determine if a variable is a boolean (true or false).
util.types.isBool(false)
will returntrue
, sincefalse
is a boolean.util.types.isBool("Hello")
will returnfalse
, since"Hello"
is not a boolean.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The variable to test. |
Returns: value is boolean
True if the value is a boolean, or false otherwise.
Const
isBufferDataPayload#
▸ isBufferDataPayload(value
: unknown): boolean
Defined in packages/spectral/src/util.ts:238
This function tests if the object provided is a Prismatic DataPayload
object.
A DataPayload
object is an object with a data
attribute, and optional contentType
attribute.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The value to test |
Returns: boolean
This function returns true if value
is a DataPayload object, and false otherwise.
Const
isData#
▸ isData(value
: unknown): boolean
Defined in packages/spectral/src/util.ts:298
deprecated
This function tests if the object provided is a Prismatic DataPayload
object.
A DataPayload
object is an object with a data
attribute, and optional contentType
attribute.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The value to test |
Returns: boolean
This function returns true if value
is a DataPayload object, and false otherwise.
Const
isDate#
▸ isDate(value
: unknown): value is Date
Defined in packages/spectral/src/util.ts:169
This function returns true if value
is a variable of type Date
, and false otherwise.
Parameters:
Name | Type |
---|---|
value | unknown |
Returns: value is Date
Const
isInt#
▸ isInt(value
: unknown): value is number
Defined in packages/spectral/src/util.ts:62
This function checks if value is an integer.
util.types.isInt(5)
returns true, while util.types.isInt("5")
or util.types.isInt(5.5)
returns false.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The variable to test. |
Returns: value is number
This function returns true or false, depending on if value
is an integer.
Const
isJSON#
▸ isJSON(value
: string): boolean
Defined in packages/spectral/src/util.ts:348
This function returns true if value
resembles the shape of JSON, and false otherwise.
isJSON(undefined) will return
false`isJSON(null) will return
true`isJSON("") will return
false`isJSON(5) will return
true`isJSON('{"name":"John", "age":30, "car":null}') will return
true`
Parameters:
Name | Type | Description |
---|---|---|
value | string | The value to test against |
Returns: boolean
This function returns a boolean, dependant on whether value
can be parsed to JSON.
Const
isNumber#
▸ isNumber(value
: unknown): boolean
Defined in packages/spectral/src/util.ts:112
Determine if a variable is a number, or can easily be coerced into a number.
util.types.isNumber(3.21)
will returntrue
, since3.21
is a number.util.types.isBool("5.5")
will returntrue
, since the string"5.5"
can easily be coerced into a number.util.types.isBool("Hello")
will returnfalse
, since"Hello"
is not a number.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The variable to test. |
Returns: boolean
This function returns true if value
can easily be coerced into a number, and false otherwise.
Const
isUrl#
▸ isUrl(value
: string): boolean
Defined in packages/spectral/src/util.ts:206
This function tests if the string provided is a valid URL, and returns true
if the URL is valid.
Note: this function only tests that the string is a syntactically correct URL; it does not check
if the URL is web accessible.
util.types.isUrl('https://prismatic.io')
will return true.util.types.isUrl('https:://prismatic.io')
will return false due to the extraneous:
symbol.
Parameters:
Name | Type | Description |
---|---|---|
value | string | The URL to test. |
Returns: boolean
This function returns true if value
is a valid URL, and false otherwise.
Const
keyValPairListToObject#
▸ keyValPairListToObject‹TValue›(kvpList
: KeyValuePair‹unknown›[], valueConverter?
: undefined | function): Record‹string, TValue›
Defined in packages/spectral/src/util.ts:218
This function helps to transform key-value lists to objects. This is useful for transforming inputs that are key-value collections into objects.
For example, an input that is a collection might return [{key: "foo", value: "bar"},{key: "baz", value: 5}]
.
If that array were passed into util.types.keyValPairListToObject()
, an object would be returned of the form
{foo: "bar", baz: 5}
.
Type parameters:
▪ TValue
Parameters:
Name | Type | Description |
---|---|---|
kvpList | KeyValuePair‹unknown›[] | An array of objects with key and value properties. |
valueConverter? | undefined | function | Optional function to call for each value . |
Returns: Record‹string, TValue›
Const
lowerCaseHeaders#
▸ lowerCaseHeaders(headers
: Record‹string, string›): Record‹string, string›
Defined in packages/spectral/src/util.ts:376
This function returns a lower cased version of the headers passed to it.
lowerCaseHeaders({"Content-Type": "Application/JSON"}) will return {"content-type": "Application/JSON"}
lowerCaseHeaders({"Cache-Control": "max-age=604800"}) will return {"cache-control": "max-age=604800"}
lowerCaseHeaders({"Accept-Language": "en-us"}) will return {"accept-language": "en-us"}
Parameters:
Name | Type | Description |
---|---|---|
headers | Record‹string, string› | The headers to convert to lower case |
Returns: Record‹string, string›
This function returns a header object
Const
toBigInt#
▸ toBigInt(value
: unknown): BigInt
Defined in packages/spectral/src/util.ts:156
This function coerces a provided value into a bigint if possible.
The provided value
must be a bigint, integer, string representing an integer, or a boolean.
util.types.toBigInt(3)
will return3n
.util.types.toBigInt("-5")
will return-5n
.util.types.toBigInt(true)
will return1n
(andfalse
will return0n
).util.types.toBigInt("5.5")
will throw an error, as5.5
is not an integer.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The value to coerce to bigint. |
Returns: BigInt
This function returns the bigint representation of value
.
Const
toBool#
▸ toBool(value
: unknown, defaultValue?
: undefined | false | true): boolean
Defined in packages/spectral/src/util.ts:39
Convert truthy (true, "t", "true", "y", "yes") values to boolean true
,
and falsy (false, "f", "false", "n", "no") values to boolean false
.
Truthy/falsy checks are case-insensitive.
In the event that value
is undefined or an empty string, a default value can be provided.
For example, util.types.toBool('', true)
will return true
.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The value to convert to a boolean. |
defaultValue? | undefined | false | true | The value to return if value is undefined or an empty string. |
Returns: boolean
The boolean equivalent of the truthy or falsy value
.
Const
toBufferDataPayload#
▸ toBufferDataPayload(value
: unknown): DataPayload
Defined in packages/spectral/src/util.ts:254
Many libraries for third-party API that handle binary files expect Buffer
objects.
This function helps to convert strings, Uint8Arrays, and Arrays to a data structure
that has a Buffer and a string representing contentType
.
You can access the buffer like this:
const { data, contentType } = util.types.toBufferDataPayload(someData);
If value
cannot be converted to a Buffer, an error will be thrown.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The string, Buffer, Uint8Array, or Array to convert to a Buffer. |
Returns: DataPayload
This function returns an object with two keys: data
, which is a Buffer
, and contentType
, which is a string.
Const
toData#
▸ toData(value
: unknown): DataPayload
Defined in packages/spectral/src/util.ts:312
deprecated
Many libraries for third-party API that handle binary files expect Buffer
objects.
This function helps to convert strings, Uint8Arrays, and Arrays to a data structure
that has a Buffer and a string representing contentType
.
You can access the buffer like this:
const { data, contentType } = util.types.toData(someData);
If value
cannot be converted to a Buffer, an error will be thrown.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The string, Buffer, Uint8Array, or Array to convert to a Buffer. |
Returns: DataPayload
This function returns an object with two keys: data
, which is a Buffer
, and contentType
, which is a string.
Const
toDate#
▸ toDate(value
: unknown): Date
Defined in packages/spectral/src/util.ts:181
This function parses an ISO date if possible, or throws an error if the value provided cannot be coerced into a Date object.
util.types.toDate(new Date('1995-12-17T03:24:00'))
will returnDate('1995-12-17T09:24:00.000Z')
since aDate
object was passed in.util.types.toDate('2021-03-20')
will returnDate('2021-03-20T05:00:00.000Z')
since a valid ISO date was passed in.parseISODate('2021-03-20-05')
will throw an error sincevalue
was not a valid ISO date.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The value to turn into a date. |
Returns: Date
The date equivalent of value
.
Const
toInt#
▸ toInt(value
: unknown, defaultValue?
: undefined | number): number
Defined in packages/spectral/src/util.ts:76
This function converts a variable to an integer if possible.
util.types.toInt(5.5)
will return 5
. util.types.toInt("20.3")
will return 20
.
In the event that value
is undefined or an empty string, a default value can be provided.
For example, util.types.toInt('', 1)
will return 1
.
This function will throw an exception if value
cannot be coerced to an integer.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The value to convert to an integer. |
defaultValue? | undefined | number | The value to return if value is undefined, an empty string, or not able to be coerced. |
Returns: number
This function returns an integer if possible.
Const
toJSON#
▸ toJSON(value
: unknown): string
Defined in packages/spectral/src/util.ts:362
This function accepts an arbitrary object/value and safely serializes it (handles cyclic references).
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | Arbitrary object/value to serialize. |
Returns: string
JSON serialized text that can be safely logged.
Const
toNumber#
▸ toNumber(value
: unknown, defaultValue?
: undefined | number): number
Defined in packages/spectral/src/util.ts:127
This function coerces a value (number or string) into a number.
In the event that value
is undefined or an empty string, a defaultValue
can be provided, or zero will be returned.
If value
is not able to be coerced into a number but is defined, an error will be thrown.
util.types.toNumber("3.22")
will return the number3.22
.util.types.toNumber("", 5.5)
will return the default value5.5
, sincevalue
was an empty string.util.types.toNumber(undefined)
will return0
, sincevalue
was undefined and nodefaultValue
was given.util.types.toNumber("Hello")
will throw an error, since the string"Hello"
cannot be coerced into a number.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The value to turn into a number. |
defaultValue? | undefined | number | The value to return if value is undefined or an empty string. |
Returns: number
This function returns the numerical version of value
if possible, or the defaultValue
if value
is undefined or an empty string.
Const
toString#
▸ toString(value
: unknown, defaultValue
: string): string
Defined in packages/spectral/src/util.ts:334
This function converts a value
to a string.
If value
is undefined or an empty string, an optional defaultValue
can be returned.
util.types.toString("Hello")
will return"Hello"
.util.types.toString(5.5)
will return"5.5"
.util.types.toString("", "Some default")
will return"Some Default"
.util.types.toString(undefined)
will return""
.
Parameters:
Name | Type | Default | Description |
---|---|---|---|
value | unknown | - | The value to convert to a string. |
defaultValue | string | "" | A default value to return if value is undefined or an empty string. |
Returns: string
This function returns the stringified version fo value
, or defaultValue
in the case that value
is undefined or an empty string.