Helper library

To access data from within an EdgeWorkers function, you need to use the JavaScript helper library provided by ​Akamai​. This library uses an EdgeWorkers HTTP sub-request within an EdgeWorkers event handler to access EdgeKV data.

Review the table below for details about the supported operations and EdgeKV JavaScript APIs for each event handler.

Event handler

Supported EdgeKV operations

Supported EdgeKV JavaScript APIs

responseProvider
onClientResponse
OnOriginRequest
OnOriginResponse
onClientRequest

Read/Write/Delete

getText()
getJson()
putText()
putTextNoWait
putJson()
putJsonNoWait()
delete()

To learn more about the specific HTTP events that can execute an EdgeWorkers script go to the Event handler functions section in the EdgeWorkers documentation.

Error format

When an operation is not successful an error object in the following format is thrown.

{
    "failed": "whatFailed",
    "status": responseStatusCode,
    "body": "descriptionOfFailure"
}

Constructor

Use this Constructor to set the default namespace and group. You can make individual GET, PUT, and DELETE operations to override these default values.

new EdgeKV(namespace = "default", group = "default", num_retries_on_timeout = 0)

Parameter

Type

Description

Default Value

namespace

String

The default namespace to use for all GET, PUT, and DELETE operations.

Refer to the Limits that apply to namespaces.

"default"

group

String

The default group to use for all GET, PUT, and DELETE operations.

Refer to the Limits that apply to groups.

"default"

num_retries_on_timeout

Number

Specifies the number of retries to attempt when executing the getText() and getJson() methods.

You can specify this parameter as a common value in the EdgeKV Constructor, or each time getText() or getJson() are invoked. If you specify it in the getText() or getJson() invocation it overrides any setting in the Constructor for that specific invocation.

0
(indicates no retries)

When using this parameter the recommended number of retries is 1 to 3.

Library helper methods

getText()

Gets a text value from an item in the EdgeKV database (async).

Parameters

async getText({ namespace = this.#namespace, group = this.#group, item, default_value = null, timeout = null })

Parameter

Type

Description

Default value

namespace

String

Specifies a namespace other than the default.

Default value specified in Constructor.

group

String

Specifies a group other than the default.

Default value specified in Constructor.

item

String

The item key to get from the EdgeKV database.

default_value

String

The default value to return if a 404 response is returned from EdgeKV.

null

timeout

Number

The maximum time, between 1 and 1000 milliseconds, to wait for the response.

null

num_retries_on_timeout

Number

Specifies the number of retries to attempt when executing the getText() method.

You can specify this parameter as a common value in the EdgeKV Constructor, or each time getText() is invoked. If you specify it in the getText() invocation it overrides any setting in the Constructor for that specific invocation. For more information see the note below.

null
(indicates no retries)

When using this parameter the recommended number of retries is 1 to 3.

📘

Each retry request is a separate, billable read request. Retry requests are not available for write (PUT) or delete (DELETE) requests. If you do not require confirmation when a request completes, you should use the NoWait variants, putTextNoWait(), putJsonNoWait(), and deleteNoWait() to avoid any EdgeWorkers timeout issues.

try {
    const edgeKv = new EdgeKV({ group: "ProductSalePrice" }); // the namespace will be "default" since it is not provided
    let salePrice = await edgeKv.getText({ item: productId, default_value: "N/A" });
    // use the salePrice in the page
} catch (error) {
    // do something in case of an error
}

getJson()

Gets a JSON value from an item in the EdgeKV database (async).

Parameters

getJson({ namespace = this.#namespace, group = this.#group, item, default_value = null, timeout = null, num_retries_on_timeout = null})

Parameter

Type

Description

Default value

namespace

String

Specifies a namespace other than the default.

Default value specified in Constructor.

group

String

Specifies a group other than the default.

Default value specified in Constructor.

item

String

The item key to get from the EdgeKV database.

default_value

String

The default value to return if a 404 response is returned from EdgeKV.

null

timeout

Number

The maximum time, between 1 and 1000 milliseconds, to wait for the response.

null

num_retries_on_timeout

Number

Specifies the number of retries to attempt when executing the getJson() method.

You can specify this parameter as a common value in the EdgeKV Constructor, or each time getJson() is invoked. If you specify it in the getJson() invocation it overrides any setting in the Constructor for that specific invocation. For more information see the note below.

null
(indicates no retries)

When using this parameter the recommended number of retries is 1 to 3.

📘

Each retry request is a separate, billable read request. Retry requests are not available for write (PUT) or delete (DELETE) requests. If you do not require confirmation when a request completes, you should use the NoWait variants, putTextNoWait(), putJsonNoWait(), and deleteNoWait() to avoid any EdgeWorkers timeout issues.

putText()

Asynchronously inserts a text value into an item if it does not already exist, or updates a value if it does exist (upsert).

Parameters

putText({ namespace = this.#namespace, group = this.#group, item, value, timeout = null })

Parameter

Type

Description

Default value

namespace

String

Specifies a namespace other than the default.

Default value specified in Constructor.

group

String

Specifies a group other than the default.

Default value specified in Constructor.

item

String

The item key to put into the EdgeKV database.

value

String

The item text value to assign to the item in the EdgeKV database.

timeout

Number

The maximum time, between 1 and 1000 milliseconds, to wait for the response.

null

try {
    const edgeKv = new EdgeKV({ group: "LastUpdated" });
    let date = new Date().toString();
    await edgeKv.putText({ item: productId, value: date });
    // this information can then be used to see when a product was last updated
} catch (error) {
    // do something in case of an error
}

putTextNoWait()

Upserts a text value into an item in the EdgeKV database while only waiting for the request to send and not for the response.

Parameters

putTextNoWait({ namespace = this.#namespace, group = this.#group, item, value })

Parameter

Type

Description

namespace

String

Specifies a namespace other than the default.

Default value specified in Constructor.

group

String

Specifies a group other than the default.

Default value specified in Constructor.

item

String

The item key to put into the EdgeKV database.

value

String

The item text value to assign to the item in the EdgeKV database.

try {
    const edgeKv = new EdgeKV({ group: "LastUpdated" });
    let date = new Date().toString();
    edgeKv.putTextNoWait({ item: productId, value: date });
    // this information can then be used to see when a product was last updated
} catch (error) {
    // do something in case of an error
}

putJson()

Upserts a JSON value into an item in the EdgeKV database (async).

Parameters

putJson({ namespace = this.#namespace, group = this.#group, item, value, timeout = null })

Parameters

Type

Description

Default value

namespace

String

Specifies a namespace other than the default.

Default value specified in Constructor.

group

Specifies a group other than the default.

Default value specified in Constructor.

item

String

The item key to put into the EdgeKV database.

value

JSON object

The item json value to assign to the item in the EdgeKV database.

timeout

Number

The maximum time, between 1 and 1000 milliseconds, to wait for the response.

null

try {
    const edgeKv = new EdgeKV({ group: "LastUpdated" });
    let obj = {prop1:"someValue",prop2:42};
    await edgeKv.putJson({ item: productId, value: obj });
    // this json object can later be pulled out using getJson
} catch (error) {
    // do something in case of an error
}

putJsonNoWait()

Upserts a JSON value into an item in the EdgeKV database while only waiting for the request to send and not for the response.

Parameters

putJsonNoWait({ namespace = this.#namespace, group = this.#group, item, value })

Parameter

Type

Description

Default value

namespace

String

Specifies a namespace other than the default.

Default value specified in Constructor.

group

String

Specifies a group other than the default.

Default value specified in Constructor.

item

String

The item key to put into the EdgeKV database.

value

JSON object

The item json value to assign to the item in the EdgeKV database.

try {
    const edgeKv = new EdgeKV({ group: "LastUpdated" });
    let obj = {prop1:"someValue",prop2:42};
    edgeKv.putJsonNoWait({ item: productId, value: obj });
    // this json object can later be pulled out using getJson
} catch (error) {
    // do something in case of an error
}

delete()

Deletes the named item from the EdgeKV database.

Parameters

delete({ namespace = this.#namespace, group = this.#group, item, timeout = null })

Parameter

Type

Description

Default value

namespace

String

Specifies a namespace other than the default.

Default value specified in Constructor.

group

String

Specifies a group other than the default.

Default value specified in Constructor.

item

String

Item key to delete from the database.

timeout

Number

The maximum time, between 1 and 1000 milliseconds, to wait for the response.

null

try {
    const edgeKv = new EdgeKV({ group: "LastUpdated" });
    await edgeKv.delete({ item: productId });
} catch (error) {
    // do something in case of an error
}

deleteNoWait()

Deletes the named item from the EdgeKV database while only waiting for the request to send and not for the response.

Parameters

deleteNoWait({ namespace = this.#namespace, group = this.#group, item } = {}) {

Parameter

Type

Description

Default value

namespace

String

Specifies a namespace other than the default.

Default value specified in Constructor.

group

String

Specifies a group other than the default.

Default value specified in Constructor.

item

String

Item key to delete from the database.

try {
    const edgeKv = new EdgeKV({ group: "LastUpdated" });
    edgeKv.deleteNoWait({ item: productId });
} catch (error) {
    // do something in case of an error
}

Did this page help you?