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
- isBigInt
- isBool
- isBufferDataPayload
- isConnection
- isData
- isDate
- isElement
- isInt
- isJSON
- isJSONForm
- isNumber
- isObjectFieldMap
- isObjectSelection
- isObjectWithTruthyKeys
- isPicklist
- isSchedule
- isString
- isUrl
- keyValPairListToObject
- lowerCaseHeaders
- toBigInt
- toBool
- toBufferDataPayload
- toData
- toDate
- toInt
- toJSON
- toJSONForm
- toNumber
- toObject
- toObjectFieldMap
- toObjectSelection
- toString
Functions
Const
isBigInt
▸ isBigInt(value
: unknown): value is bigint
Defined in packages/spectral/src/util.ts:286
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:166
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): value is DataPayload
Defined in packages/spectral/src/util.ts:404
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: value is DataPayload
This function returns true if value
is a DataPayload object, and false otherwise.
Const
isConnection
▸ isConnection(value
: unknown): value is ConnectionDefinition
Defined in packages/spectral/src/util.ts:509
This function checks if value is a valid connection.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The variable to test. |
Returns: value is ConnectionDefinition
This function returns true or false, depending on if value
is a valid connection.
Const
isData
▸ isData(value
: unknown): boolean
Defined in packages/spectral/src/util.ts:464
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:312
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
isElement
▸ isElement(value
: unknown): value is Element
Defined in packages/spectral/src/util.ts:40
This function checks if value is an Element.
util.types.isElement({key: "foo"})
and util.types.isElement({key: "foo", label: "Foo"})
return true.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The variable to test. |
Returns: value is Element
This function returns true or false, depending on if value
is an Element.
Const
isInt
▸ isInt(value
: unknown): value is number
Defined in packages/spectral/src/util.ts:204
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:549
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
isJSONForm
▸ isJSONForm(value
: unknown): value is JSONForm
Defined in packages/spectral/src/util.ts:128
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The value to test |
Returns: value is JSONForm
This function returns true if the type of value
is a JSONForm, or false otherwise.
Const
isNumber
▸ isNumber(value
: unknown): boolean
Defined in packages/spectral/src/util.ts:254
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
isObjectFieldMap
▸ isObjectFieldMap(value
: unknown): value is ObjectFieldMap
Defined in packages/spectral/src/util.ts:83
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The value to test |
Returns: value is ObjectFieldMap
This function returns true if the type of value
is an ObjectFieldMap, or false otherwise.
Const
isObjectSelection
▸ isObjectSelection(value
: unknown): value is ObjectSelection
Defined in packages/spectral/src/util.ts:47
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The value to test |
Returns: value is ObjectSelection
This function returns true if the type of value
is an ObjectSelection, or false otherwise.
Const
isObjectWithTruthyKeys
▸ isObjectWithTruthyKeys(value
: unknown, keys
: string[]): boolean
Defined in packages/spectral/src/util.ts:23
Parameters:
Name | Type |
---|---|
value | unknown |
keys | string[] |
Returns: boolean
Const
isPicklist
▸ isPicklist(value
: unknown): boolean
Defined in packages/spectral/src/util.ts:359
This function checks if value is a valid picklist.
util.types.isPicklist(["value", new String("value")])
will returntrue
.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The variable to test. |
Returns: boolean
This function returns true if value
is a valid picklist.
Const
isSchedule
▸ isSchedule(value
: unknown): boolean
Defined in packages/spectral/src/util.ts:371
This function checks if value is a valid schedule.
util.types.isSchedule({value: "00 00 * * 2,3"})
will returntrue
.util.types.isSchedule({value: "00 00 * * 2,3", scheduleType: "week", timeZone: "America/Chicago"})
will returntrue
.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The variable to test. |
Returns: boolean
This function returns true if value
is a valid schedule.
Const
isString
▸ isString(value
: unknown): value is string
Defined in packages/spectral/src/util.ts:486
This function checks if value is a string.
util.types.isString("value")
and util.types.isString(new String("value"))
return true.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The variable to test. |
Returns: value is string
This function returns true or false, depending on if value
is a string.
Const
isUrl
▸ isUrl(value
: string): boolean
Defined in packages/spectral/src/util.ts:349
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:384
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:578
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:299
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:181
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:420
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:478
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:324
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:218
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:564
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
toJSONForm
▸ toJSONForm(value
: unknown): JSONForm
Defined in packages/spectral/src/util.ts:141
This function coerces a provided value into a JSONForm if possible.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The value to coerce to JSONForm. |
Returns: JSONForm
This function returns the the value as a JSONForm if possible.
Const
toNumber
▸ toNumber(value
: unknown, defaultValue?
: undefined | number): number
Defined in packages/spectral/src/util.ts:270
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(null, 5.5)
will return the default value5.5
, sincevalue
wasnull
.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
toObject
▸ toObject(value
: unknown): object
Defined in packages/spectral/src/util.ts:594
This function parses a JSON string (if JSON) and returns an object, or returns the object.
toObject('{"foo":"bar","baz":123}')
will return object{foo: "bar", baz: 123}
toObject({foo:"bar",baz:123})
will return object{foo: "bar", baz: 123}
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The JSON string or object to convert |
Returns: object
This function returns an object, parsing JSON as necessary
Const
toObjectFieldMap
▸ toObjectFieldMap(value
: unknown): ObjectFieldMap
Defined in packages/spectral/src/util.ts:108
This function coerces a provided value into an ObjectFieldMap if possible.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The value to coerce to ObjectFieldMap. |
Returns: ObjectFieldMap
This function returns the the value as an ObjectFieldMap if possible.
Const
toObjectSelection
▸ toObjectSelection(value
: unknown): ObjectSelection
Defined in packages/spectral/src/util.ts:63
This function coerces a provided value into an ObjectSelection if possible.
Parameters:
Name | Type | Description |
---|---|---|
value | unknown | The value to coerce to ObjectSelection. |
Returns: ObjectSelection
This function returns the the value as an ObjectSelection if possible.
Const
toString
▸ toString(value
: unknown, defaultValue
: string): string
Defined in packages/spectral/src/util.ts:501
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.