@crawlee/core 3.0.0-alpha.2 → 3.0.0-alpha.3

package/dist/storages/key_value_store.d.ts

@@ -0,0 +1,242 @@
+import { Configuration } from '../configuration';
+import { Awaitable } from '../typedefs';
+import { StorageManagerOptions } from './storage_manager';
+import { StorageClient } from './storage';
+/**
+ * Helper function to possibly stringify value if options.contentType is not set.
+ *
+ * @ignore
+ */
+export declare const maybeStringify: <T>(value: T, options: {
+    contentType?: string;
+}) => T;
+/**
+ * The `KeyValueStore` class represents a key-value store, a simple data storage that is used
+ * for saving and reading data records or files. Each data record is
+ * represented by a unique key and associated with a MIME content type. Key-value stores are ideal
+ * for saving screenshots, actor inputs and outputs, web pages, PDFs or to persist the state of crawlers.
+ *
+ * Do not instantiate this class directly, use the
+ * {@link KeyValueStore.open} function instead.
+ *
+ * Each actor run is associated with a default key-value store, which is created exclusively
+ * for the run. By convention, the actor input and output are stored into the
+ * default key-value store under the `INPUT` and `OUTPUT` key, respectively.
+ * Typically, input and output are JSON files, although it can be any other format.
+ * To access the default key-value store directly, you can use the
+ * {@link Actor.getValue} and {@link Actor.setValue} convenience functions.
+ *
+ * To access the input, you can also use the {@link Actor.getInput} convenience function.
+ *
+ * `KeyValueStore` stores its data either on local disk or in the Apify cloud,
+ * depending on whether the [`APIFY_IS_AT_HOME`](/docs/guides/environment-variables#apify_is_at_home)
+ * environment variable is set.
+ *
+ * If the `APIFY_LOCAL_STORAGE_DIR` environment variable is set, the data is stored in
+ * the local directory in the following files:
+ * ```
+ * {APIFY_LOCAL_STORAGE_DIR}/key_value_stores/{STORE_ID}/{INDEX}.{EXT}
+ * ```
+ * Note that `{STORE_ID}` is the name or ID of the key-value store. The default key-value store has ID: `default`,
+ * unless you override it by setting the `APIFY_DEFAULT_KEY_VALUE_STORE_ID` environment variable.
+ * The `{KEY}` is the key of the record and `{EXT}` corresponds to the MIME content type of the data value.
+ *
+ * If the [`APIFY_TOKEN`](/docs/guides/environment-variables#apify_token) environment variable is set but
+ * [`APIFY_LOCAL_STORAGE_DIR`](/docs/guides/environment-variables#apify_local_storage_dir) not,
+ * the data is stored in the [Apify Key-value store](https://docs.apify.com/storage/key-value-store)
+ * cloud storage. Note that you can force usage of the cloud storage also by passing the `forceCloud`
+ * option to {@link KeyValueStore.open} function, even if the
+ * [`APIFY_LOCAL_STORAGE_DIR`](/docs/guides/environment-variables#apify_local_storage_dir) variable is set.
+ *
+ * **Example usage:**
+ *
+ * ```javascript
+ * // Get actor input from the default key-value store.
+ * const input = await Actor.getInput();
+ * // Get some value from the default key-value store.
+ * const otherValue = await Actor.getValue('my-key');
+ *
+ * // Write actor output to the default key-value store.
+ * await Actor.setValue('OUTPUT', { myResult: 123 });
+ *
+ * // Open a named key-value store
+ * const store = await KeyValueStore.open('some-name');
+ *
+ * // Write a record. JavaScript object is automatically converted to JSON,
+ * // strings and binary buffers are stored as they are
+ * await store.setValue('some-key', { foo: 'bar' });
+ *
+ * // Read a record. Note that JSON is automatically parsed to a JavaScript object,
+ * // text data returned as a string and other data is returned as binary buffer
+ * const value = await store.getValue('some-key');
+ *
+ *  // Drop (delete) the store
+ * await store.drop();
+ * ```
+ * @category Result Stores
+ */
+export declare class KeyValueStore {
+    readonly config: Configuration;
+    readonly id: string;
+    readonly name?: string;
+    private client;
+    /**
+     * @internal
+     */
+    constructor(options: KeyValueStoreOptions, config?: Configuration);
+    /**
+     * Gets a value from the key-value store.
+     *
+     * The function returns a `Promise` that resolves to the record value,
+     * whose JavaScript type depends on the MIME content type of the record.
+     * Records with the `application/json`
+     * content type are automatically parsed and returned as a JavaScript object.
+     * Similarly, records with `text/plain` content types are returned as a string.
+     * For all other content types, the value is returned as a raw
+     * [`Buffer`](https://nodejs.org/api/buffer.html) instance.
+     *
+     * If the record does not exist, the function resolves to `null`.
+     *
+     * To save or delete a value in the key-value store, use the
+     * {@link KeyValueStore.setValue} function.
+     *
+     * **Example usage:**
+     *
+     * ```javascript
+     * const store = await KeyValueStore.open();
+     * const buffer = await store.getValue('screenshot1.png');
+     * ```
+     * @param key
+     *   Unique key of the record. It can be at most 256 characters long and only consist
+     *   of the following characters: `a`-`z`, `A`-`Z`, `0`-`9` and `!-_.'()`
+     * @returns
+     *   Returns a promise that resolves to an object, string
+     *   or [`Buffer`](https://nodejs.org/api/buffer.html), depending
+     *   on the MIME content type of the record.
+     */
+    getValue<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Saves or deletes a record in the key-value store.
+     * The function returns a promise that resolves once the record has been saved or deleted.
+     *
+     * **Example usage:**
+     *
+     * ```javascript
+     * const store = await KeyValueStore.open();
+     * await store.setValue('OUTPUT', { foo: 'bar' });
+     * ```
+     *
+     * Beware that the key can be at most 256 characters long and only contain the following characters: `a-zA-Z0-9!-_.'()`
+     *
+     * By default, `value` is converted to JSON and stored with the
+     * `application/json; charset=utf-8` MIME content type.
+     * To store the value with another content type, pass it in the options as follows:
+     * ```javascript
+     * const store = await KeyValueStore.open('my-text-store');
+     * await store.setValue('RESULTS', 'my text data', { contentType: 'text/plain' });
+     * ```
+     * If you set custom content type, `value` must be either a string or
+     * [`Buffer`](https://nodejs.org/api/buffer.html), otherwise an error will be thrown.
+     *
+     * If `value` is `null`, the record is deleted instead. Note that the `setValue()` function succeeds
+     * regardless whether the record existed or not.
+     *
+     * To retrieve a value from the key-value store, use the
+     * {@link KeyValueStore.getValue} function.
+     *
+     * **IMPORTANT:** Always make sure to use the `await` keyword when calling `setValue()`,
+     * otherwise the actor process might finish before the value is stored!
+     *
+     * @param key
+     *   Unique key of the record. It can be at most 256 characters long and only consist
+     *   of the following characters: `a`-`z`, `A`-`Z`, `0`-`9` and `!-_.'()`
+     * @param value
+     *   Record data, which can be one of the following values:
+     *    - If `null`, the record in the key-value store is deleted.
+     *    - If no `options.contentType` is specified, `value` can be any JavaScript object and it will be stringified to JSON.
+     *    - If `options.contentType` is set, `value` is taken as is and it must be a `String` or [`Buffer`](https://nodejs.org/api/buffer.html).
+     *   For any other value an error will be thrown.
+     * @param [options] Record options.
+     */
+    setValue<T>(key: string, value: T | null, options?: RecordOptions): Promise<void>;
+    /**
+     * Removes the key-value store either from the Apify cloud storage or from the local directory,
+     * depending on the mode of operation.
+     */
+    drop(): Promise<void>;
+    /**
+     * Returns a URL for the given key that may be used to publicly
+     * access the value in the remote key-value store.
+     */
+    getPublicUrl(key: string): string;
+    /**
+     * Iterates over key-value store keys, yielding each in turn to an `iteratee` function.
+     * Each invocation of `iteratee` is called with three arguments: `(key, index, info)`, where `key`
+     * is the record key, `index` is a zero-based index of the key in the current iteration
+     * (regardless of `options.exclusiveStartKey`) and `info` is an object that contains a single property `size`
+     * indicating size of the record in bytes.
+     *
+     * If the `iteratee` function returns a Promise then it is awaited before the next call.
+     * If it throws an error, the iteration is aborted and the `forEachKey` function throws the error.
+     *
+     * **Example usage**
+     * ```javascript
+     * const keyValueStore = await KeyValueStore.open();
+     * await keyValueStore.forEachKey(async (key, index, info) => {
+     *   console.log(`Key at ${index}: ${key} has size ${info.size}`);
+     * });
+     * ```
+     *
+     * @param iteratee A function that is called for every key in the key-value store.
+     * @param [options] All `forEachKey()` parameters.
+     */
+    forEachKey(iteratee: KeyConsumer, options?: KeyValueStoreIteratorOptions): Promise<void>;
+    private _forEachKey;
+    /**
+     * Opens a key-value store and returns a promise resolving to an instance of the {@link KeyValueStore} class.
+     *
+     * Key-value stores are used to store records or files, along with their MIME content type.
+     * The records are stored and retrieved using a unique key.
+     * The actual data is stored either on a local filesystem or in the Apify cloud.
+     *
+     * For more details and code examples, see the {@link KeyValueStore} class.
+     *
+     * @param [storeIdOrName]
+     *   ID or name of the key-value store to be opened. If `null` or `undefined`,
+     *   the function returns the default key-value store associated with the actor run.
+     * @param [options] Storage manager options.
+     */
+    static open(storeIdOrName?: string | null, options?: StorageManagerOptions): Promise<KeyValueStore>;
+}
+/**
+ * User-function used in the  {@link KeyValueStore.forEachKey} method.
+ */
+export interface KeyConsumer {
+    /**
+     * @param key Current {KeyValue} key being processed.
+     * @param index Position of the current key in {@link KeyValueStore}.
+     * @param info Information about the current {@link KeyValueStore} entry.
+     * @param info.size Size of the value associated with the current key in bytes.
+     */
+    (key: string, index: number, info: {
+        size: number;
+    }): Awaitable<void>;
+}
+export interface KeyValueStoreOptions {
+    id: string;
+    name?: string;
+    client: StorageClient;
+}
+export interface RecordOptions {
+    /**
+     * Specifies a custom MIME content type of the record.
+     */
+    contentType?: string;
+}
+export interface KeyValueStoreIteratorOptions {
+    /**
+     * All keys up to this one (including) are skipped from the result.
+     */
+    exclusiveStartKey?: string;
+}
+//# sourceMappingURL=key_value_store.d.ts.map

package/dist/storages/key_value_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key_value_store.d.ts","sourceRoot":"","sources":["../../src/storages/key_value_store.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AACpD,OAAO,EAAkB,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAuB,MAAM,WAAW,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,cAAc,yBAA0B;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,MAwB5E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,qBAAa,aAAa;IAQqB,QAAQ,CAAC,MAAM;IAP1D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,MAAM,CAAsB;IAEpC;;OAEG;gBACS,OAAO,EAAE,oBAAoB,EAAW,MAAM,gBAAkC;IAM5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAO3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACG,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IA4B3F;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B;;;OAGG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAKjC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,GAAE,4BAAiC,GAAG,OAAO,CAAC,IAAI,CAAC;YAIpF,WAAW;IAiBzB;;;;;;;;;;;;;OAaG;WACU,IAAI,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,aAAa,CAAC;CAShH;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB;;;;;OAKG;IACH,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;CACzE;AAED,MAAM,WAAW,oBAAoB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC1B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,4BAA4B;IACzC;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC9B"}

package/dist/storages/key_value_store.js

@@ -0,0 +1,319 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyValueStore = exports.maybeStringify = void 0;
+const tslib_1 = require("tslib");
+const consts_1 = require("@apify/consts");
+const utilities_1 = require("@apify/utilities");
+const ow_1 = tslib_1.__importStar(require("ow"));
+const configuration_1 = require("../configuration");
+const storage_manager_1 = require("./storage_manager");
+/**
+ * Helper function to possibly stringify value if options.contentType is not set.
+ *
+ * @ignore
+ */
+const maybeStringify = (value, options) => {
+    // If contentType is missing, value will be stringified to JSON
+    if (options.contentType === null || options.contentType === undefined) {
+        options.contentType = 'application/json; charset=utf-8';
+        try {
+            // Format JSON to simplify debugging, the overheads with compression is negligible
+            value = (0, utilities_1.jsonStringifyExtended)(value, null, 2);
+        }
+        catch (e) {
+            const error = e;
+            // Give more meaningful error message
+            if (error.message?.indexOf('Invalid string length') >= 0) {
+                error.message = 'Object is too large';
+            }
+            throw new Error(`The "value" parameter cannot be stringified to JSON: ${error.message}`);
+        }
+        if (value === undefined) {
+            throw new Error('The "value" parameter was stringified to JSON and returned undefined. '
+                + 'Make sure you\'re not trying to stringify an undefined value.');
+        }
+    }
+    return value;
+};
+exports.maybeStringify = maybeStringify;
+/**
+ * The `KeyValueStore` class represents a key-value store, a simple data storage that is used
+ * for saving and reading data records or files. Each data record is
+ * represented by a unique key and associated with a MIME content type. Key-value stores are ideal
+ * for saving screenshots, actor inputs and outputs, web pages, PDFs or to persist the state of crawlers.
+ *
+ * Do not instantiate this class directly, use the
+ * {@link KeyValueStore.open} function instead.
+ *
+ * Each actor run is associated with a default key-value store, which is created exclusively
+ * for the run. By convention, the actor input and output are stored into the
+ * default key-value store under the `INPUT` and `OUTPUT` key, respectively.
+ * Typically, input and output are JSON files, although it can be any other format.
+ * To access the default key-value store directly, you can use the
+ * {@link Actor.getValue} and {@link Actor.setValue} convenience functions.
+ *
+ * To access the input, you can also use the {@link Actor.getInput} convenience function.
+ *
+ * `KeyValueStore` stores its data either on local disk or in the Apify cloud,
+ * depending on whether the [`APIFY_IS_AT_HOME`](/docs/guides/environment-variables#apify_is_at_home)
+ * environment variable is set.
+ *
+ * If the `APIFY_LOCAL_STORAGE_DIR` environment variable is set, the data is stored in
+ * the local directory in the following files:
+ * ```
+ * {APIFY_LOCAL_STORAGE_DIR}/key_value_stores/{STORE_ID}/{INDEX}.{EXT}
+ * ```
+ * Note that `{STORE_ID}` is the name or ID of the key-value store. The default key-value store has ID: `default`,
+ * unless you override it by setting the `APIFY_DEFAULT_KEY_VALUE_STORE_ID` environment variable.
+ * The `{KEY}` is the key of the record and `{EXT}` corresponds to the MIME content type of the data value.
+ *
+ * If the [`APIFY_TOKEN`](/docs/guides/environment-variables#apify_token) environment variable is set but
+ * [`APIFY_LOCAL_STORAGE_DIR`](/docs/guides/environment-variables#apify_local_storage_dir) not,
+ * the data is stored in the [Apify Key-value store](https://docs.apify.com/storage/key-value-store)
+ * cloud storage. Note that you can force usage of the cloud storage also by passing the `forceCloud`
+ * option to {@link KeyValueStore.open} function, even if the
+ * [`APIFY_LOCAL_STORAGE_DIR`](/docs/guides/environment-variables#apify_local_storage_dir) variable is set.
+ *
+ * **Example usage:**
+ *
+ * ```javascript
+ * // Get actor input from the default key-value store.
+ * const input = await Actor.getInput();
+ * // Get some value from the default key-value store.
+ * const otherValue = await Actor.getValue('my-key');
+ *
+ * // Write actor output to the default key-value store.
+ * await Actor.setValue('OUTPUT', { myResult: 123 });
+ *
+ * // Open a named key-value store
+ * const store = await KeyValueStore.open('some-name');
+ *
+ * // Write a record. JavaScript object is automatically converted to JSON,
+ * // strings and binary buffers are stored as they are
+ * await store.setValue('some-key', { foo: 'bar' });
+ *
+ * // Read a record. Note that JSON is automatically parsed to a JavaScript object,
+ * // text data returned as a string and other data is returned as binary buffer
+ * const value = await store.getValue('some-key');
+ *
+ *  // Drop (delete) the store
+ * await store.drop();
+ * ```
+ * @category Result Stores
+ */
+class KeyValueStore {
+    /**
+     * @internal
+     */
+    constructor(options, config = configuration_1.Configuration.getGlobalConfig()) {
+        Object.defineProperty(this, "config", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config
+        });
+        Object.defineProperty(this, "id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "client", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.id = options.id;
+        this.name = options.name;
+        this.client = options.client.keyValueStore(this.id);
+    }
+    /**
+     * Gets a value from the key-value store.
+     *
+     * The function returns a `Promise` that resolves to the record value,
+     * whose JavaScript type depends on the MIME content type of the record.
+     * Records with the `application/json`
+     * content type are automatically parsed and returned as a JavaScript object.
+     * Similarly, records with `text/plain` content types are returned as a string.
+     * For all other content types, the value is returned as a raw
+     * [`Buffer`](https://nodejs.org/api/buffer.html) instance.
+     *
+     * If the record does not exist, the function resolves to `null`.
+     *
+     * To save or delete a value in the key-value store, use the
+     * {@link KeyValueStore.setValue} function.
+     *
+     * **Example usage:**
+     *
+     * ```javascript
+     * const store = await KeyValueStore.open();
+     * const buffer = await store.getValue('screenshot1.png');
+     * ```
+     * @param key
+     *   Unique key of the record. It can be at most 256 characters long and only consist
+     *   of the following characters: `a`-`z`, `A`-`Z`, `0`-`9` and `!-_.'()`
+     * @returns
+     *   Returns a promise that resolves to an object, string
+     *   or [`Buffer`](https://nodejs.org/api/buffer.html), depending
+     *   on the MIME content type of the record.
+     */
+    async getValue(key) {
+        (0, ow_1.default)(key, ow_1.default.string.nonEmpty);
+        const record = await this.client.getRecord(key);
+        return record?.value ?? null;
+    }
+    /**
+     * Saves or deletes a record in the key-value store.
+     * The function returns a promise that resolves once the record has been saved or deleted.
+     *
+     * **Example usage:**
+     *
+     * ```javascript
+     * const store = await KeyValueStore.open();
+     * await store.setValue('OUTPUT', { foo: 'bar' });
+     * ```
+     *
+     * Beware that the key can be at most 256 characters long and only contain the following characters: `a-zA-Z0-9!-_.'()`
+     *
+     * By default, `value` is converted to JSON and stored with the
+     * `application/json; charset=utf-8` MIME content type.
+     * To store the value with another content type, pass it in the options as follows:
+     * ```javascript
+     * const store = await KeyValueStore.open('my-text-store');
+     * await store.setValue('RESULTS', 'my text data', { contentType: 'text/plain' });
+     * ```
+     * If you set custom content type, `value` must be either a string or
+     * [`Buffer`](https://nodejs.org/api/buffer.html), otherwise an error will be thrown.
+     *
+     * If `value` is `null`, the record is deleted instead. Note that the `setValue()` function succeeds
+     * regardless whether the record existed or not.
+     *
+     * To retrieve a value from the key-value store, use the
+     * {@link KeyValueStore.getValue} function.
+     *
+     * **IMPORTANT:** Always make sure to use the `await` keyword when calling `setValue()`,
+     * otherwise the actor process might finish before the value is stored!
+     *
+     * @param key
+     *   Unique key of the record. It can be at most 256 characters long and only consist
+     *   of the following characters: `a`-`z`, `A`-`Z`, `0`-`9` and `!-_.'()`
+     * @param value
+     *   Record data, which can be one of the following values:
+     *    - If `null`, the record in the key-value store is deleted.
+     *    - If no `options.contentType` is specified, `value` can be any JavaScript object and it will be stringified to JSON.
+     *    - If `options.contentType` is set, `value` is taken as is and it must be a `String` or [`Buffer`](https://nodejs.org/api/buffer.html).
+     *   For any other value an error will be thrown.
+     * @param [options] Record options.
+     */
+    async setValue(key, value, options = {}) {
+        (0, ow_1.default)(key, 'key', ow_1.default.string.nonEmpty);
+        (0, ow_1.default)(key, ow_1.default.string.validate((k) => ({
+            validator: ow_1.default.isValid(k, ow_1.default.string.matches(consts_1.KEY_VALUE_STORE_KEY_REGEX)),
+            message: 'The "key" argument must be at most 256 characters long and only contain the following characters: a-zA-Z0-9!-_.\'()',
+        })));
+        if (options.contentType && !ow_1.default.isValid(value, ow_1.default.any(ow_1.default.string, ow_1.default.buffer))) {
+            throw new ow_1.ArgumentError('The "value" parameter must be a String or Buffer when "options.contentType" is specified.', this.setValue);
+        }
+        (0, ow_1.default)(options, ow_1.default.object.exactShape({
+            contentType: ow_1.default.optional.string.nonEmpty,
+        }));
+        // Make copy of options, don't update what user passed.
+        const optionsCopy = { ...options };
+        // In this case delete the record.
+        if (value === null)
+            return this.client.deleteRecord(key);
+        value = (0, exports.maybeStringify)(value, optionsCopy);
+        return this.client.setRecord({
+            key,
+            value,
+            contentType: optionsCopy.contentType,
+        });
+    }
+    /**
+     * Removes the key-value store either from the Apify cloud storage or from the local directory,
+     * depending on the mode of operation.
+     */
+    async drop() {
+        await this.client.delete();
+        const manager = new storage_manager_1.StorageManager(KeyValueStore, this.config);
+        manager.closeStorage(this);
+    }
+    /**
+     * Returns a URL for the given key that may be used to publicly
+     * access the value in the remote key-value store.
+     */
+    getPublicUrl(key) {
+        // FIXME how should this work? should we remove this method or provide a way to configure the base url?
+        return `https://api.apify.com/v2/key-value-stores/${this.id}/records/${key}`;
+    }
+    /**
+     * Iterates over key-value store keys, yielding each in turn to an `iteratee` function.
+     * Each invocation of `iteratee` is called with three arguments: `(key, index, info)`, where `key`
+     * is the record key, `index` is a zero-based index of the key in the current iteration
+     * (regardless of `options.exclusiveStartKey`) and `info` is an object that contains a single property `size`
+     * indicating size of the record in bytes.
+     *
+     * If the `iteratee` function returns a Promise then it is awaited before the next call.
+     * If it throws an error, the iteration is aborted and the `forEachKey` function throws the error.
+     *
+     * **Example usage**
+     * ```javascript
+     * const keyValueStore = await KeyValueStore.open();
+     * await keyValueStore.forEachKey(async (key, index, info) => {
+     *   console.log(`Key at ${index}: ${key} has size ${info.size}`);
+     * });
+     * ```
+     *
+     * @param iteratee A function that is called for every key in the key-value store.
+     * @param [options] All `forEachKey()` parameters.
+     */
+    async forEachKey(iteratee, options = {}) {
+        return this._forEachKey(iteratee, options);
+    }
+    async _forEachKey(iteratee, options = {}, index = 0) {
+        const { exclusiveStartKey } = options;
+        (0, ow_1.default)(iteratee, ow_1.default.function);
+        (0, ow_1.default)(options, ow_1.default.object.exactShape({
+            exclusiveStartKey: ow_1.default.optional.string,
+        }));
+        const response = await this.client.listKeys({ exclusiveStartKey });
+        const { nextExclusiveStartKey, isTruncated, items } = response;
+        for (const item of items) {
+            await iteratee(item.key, index++, { size: item.size });
+        }
+        return isTruncated
+            ? this._forEachKey(iteratee, { exclusiveStartKey: nextExclusiveStartKey }, index)
+            : undefined; // [].forEach() returns undefined.
+    }
+    /**
+     * Opens a key-value store and returns a promise resolving to an instance of the {@link KeyValueStore} class.
+     *
+     * Key-value stores are used to store records or files, along with their MIME content type.
+     * The records are stored and retrieved using a unique key.
+     * The actual data is stored either on a local filesystem or in the Apify cloud.
+     *
+     * For more details and code examples, see the {@link KeyValueStore} class.
+     *
+     * @param [storeIdOrName]
+     *   ID or name of the key-value store to be opened. If `null` or `undefined`,
+     *   the function returns the default key-value store associated with the actor run.
+     * @param [options] Storage manager options.
+     */
+    static async open(storeIdOrName, options = {}) {
+        (0, ow_1.default)(storeIdOrName, ow_1.default.optional.string);
+        (0, ow_1.default)(options, ow_1.default.object.exactShape({
+            config: ow_1.default.optional.object.instanceOf(configuration_1.Configuration),
+        }));
+        const manager = new storage_manager_1.StorageManager(KeyValueStore, options.config);
+        return manager.openStorage(storeIdOrName);
+    }
+}
+exports.KeyValueStore = KeyValueStore;
+//# sourceMappingURL=key_value_store.js.map

package/dist/storages/key_value_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key_value_store.js","sourceRoot":"","sources":["../../src/storages/key_value_store.ts"],"names":[],"mappings":"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"}