apify-client 3.0.0-beta.64 → 3.0.0-beta.65

package/dist/resource_clients/dataset.d.ts

@@ -133,6 +133,11 @@ export declare class DatasetClient<Data extends Record<string | number, any> = R
      * dataset items, this method returns the items serialized to the provided format
      * (JSON, CSV, Excel, etc.) as a Buffer. Useful for exporting data for further processing.
      *
+     * In Node.js you can use the `stream` option to get a Readable stream, so a large export is processed in chunks
+     * without holding all of it in memory. The stream holds its connection open until you consume it to the end or
+     * destroy it. Iterating it with `for await` or passing it to `pipeline()` from `node:stream/promises` does either
+     * one for you.
+     *
      * @param format - Output format: `'json'`, `'jsonl'`, `'csv'`, `'xlsx'`, `'xml'`, `'rss'`, or `'html'`
      * @param options - Download and formatting options (extends all options from {@link listItems})
      * @param options.attachment - If `true`, the response will have `Content-Disposition: attachment` header.
@@ -143,8 +148,12 @@ export declare class DatasetClient<Data extends Record<string | number, any> = R
      * @param options.xmlRow - Name of the XML element for each item. Default is `'item'`.
      * @param options.fields - Array of field names to include in the export.
      * @param options.omit - Array of field names to exclude from the export.
-     * @param options.timeoutSecs - Timeout for the API request. Default is `'long'`.
-     * @returns Buffer containing the serialized data in the specified format
+     * @param options.stream - If `true`, the items are returned as a Readable stream. Node.js only.
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'long'`. With `stream`, it bounds the
+     * wait for the API to start responding; once the stream is returned, it only limits inactivity: the stream errors
+     * if no data arrives for that long. To stop the download early or cap its total duration, destroy the stream or
+     * abort `signal`.
+     * @returns Buffer containing the serialized data in the specified format, or a Readable stream of it with `stream`
      * @see https://docs.apify.com/api/v2/dataset-items-get
      *
      * @example
@@ -165,37 +174,21 @@ export declare class DatasetClient<Data extends Record<string | number, any> = R
      *   xmlRoot: 'products',
      *   xmlRow: 'product'
      * });
-     * ```
-     */
-    downloadItems(format: `${DownloadItemsFormat}`, options?: DatasetClientDownloadItemsOptions): Promise<Buffer>;
-    /**
-     * Downloads dataset items in a specific format as a Readable stream. Only works in Node.js.
-     *
-     * Takes the same arguments as {@link downloadItems}, but resolves to the response body as a stream, so a large
-     * export is processed in chunks without holding all of it in memory.
-     *
-     * The stream holds its connection open until you consume it to the end or destroy it. Iterating it with
-     * `for await` or passing it to `pipeline()` from `node:stream/promises` does either one for you.
-     *
-     * @param format - Output format: `'json'`, `'jsonl'`, `'csv'`, `'xlsx'`, `'xml'`, `'rss'`, or `'html'`
-     * @param options - Download and formatting options, the same as for {@link downloadItems}
-     * @param options.timeoutSecs - Timeout for the API to start responding. Default is `'long'`. Once the stream is
-     * returned, it only limits inactivity: the stream errors if no data arrives for that long. To stop the download
-     * early or cap its total duration, destroy the stream or abort `signal`.
-     * @returns Readable stream of the items serialized to the specified format
-     * @see https://docs.apify.com/api/v2/dataset-items-get
      *
-     * @example
-     * ```javascript
+     * // Stream a CSV export straight to a file
      * const { createWriteStream } = require('node:fs');
      * const { pipeline } = require('node:stream/promises');
-     *
-     * // Write a CSV export straight to a file
-     * const stream = await client.dataset('my-dataset').streamItems('csv', { bom: true });
+     * const stream = await client.dataset('my-dataset').downloadItems('csv', { stream: true });
      * await pipeline(stream, createWriteStream('output.csv'));
      * ```
      */
-    streamItems(format: `${DownloadItemsFormat}`, options?: DatasetClientDownloadItemsOptions): Promise<Readable>;
+    downloadItems(format: `${DownloadItemsFormat}`, options?: DatasetClientDownloadItemsOptions & {
+        stream?: false;
+    }): Promise<Buffer>;
+    downloadItems(format: `${DownloadItemsFormat}`, options: DatasetClientDownloadItemsOptions & {
+        stream: true;
+    }): Promise<Readable>;
+    downloadItems(format: `${DownloadItemsFormat}`, options?: DatasetClientDownloadItemsOptions): Promise<Buffer | Readable>;
     /**
      * Stores one or more items into the dataset.
      *
@@ -347,4 +340,9 @@ export interface DatasetClientDownloadItemsOptions extends Omit<DatasetClientLis
     skipHeaderRow?: boolean;
     xmlRoot?: string;
     xmlRow?: string;
+    /**
+     * If `true`, the items are returned as a Readable stream. Node.js only.
+     * @default false
+     */
+    stream?: boolean;
 }

package/dist/resource_clients/dataset.js

@@ -56,6 +56,7 @@ const downloadItemsOptionsSchema = z.strictObject({
     xmlRoot: z.string().optional(),
     xmlRow: z.string().optional(),
     signature: z.string().optional(),
+    stream: z.boolean().optional(),
     ...timeoutOptionsShape,
 });
 const pushItemsSchema = z.union([itemSchema, z.string(), z.array(itemSchema)]);
@@ -213,95 +214,11 @@ export class DatasetClient extends ResourceClient {
         };
         return this.listPaginatedFromCallback(fetchItems, listOptions);
     }
-    /**
-     * Downloads dataset items in a specific format.
-     *
-     * Unlike {@link listItems} which returns a {@link PaginatedList} with an array of individual
-     * dataset items, this method returns the items serialized to the provided format
-     * (JSON, CSV, Excel, etc.) as a Buffer. Useful for exporting data for further processing.
-     *
-     * @param format - Output format: `'json'`, `'jsonl'`, `'csv'`, `'xlsx'`, `'xml'`, `'rss'`, or `'html'`
-     * @param options - Download and formatting options (extends all options from {@link listItems})
-     * @param options.attachment - If `true`, the response will have `Content-Disposition: attachment` header.
-     * @param options.bom - If `true`, adds UTF-8 BOM to the beginning of the file (useful for Excel compatibility).
-     * @param options.delimiter - CSV delimiter character. Default is `,` (comma).
-     * @param options.skipHeaderRow - If `true`, CSV export will not include the header row with field names.
-     * @param options.xmlRoot - Name of the root XML element. Default is `'items'`.
-     * @param options.xmlRow - Name of the XML element for each item. Default is `'item'`.
-     * @param options.fields - Array of field names to include in the export.
-     * @param options.omit - Array of field names to exclude from the export.
-     * @param options.timeoutSecs - Timeout for the API request. Default is `'long'`.
-     * @returns Buffer containing the serialized data in the specified format
-     * @see https://docs.apify.com/api/v2/dataset-items-get
-     *
-     * @example
-     * ```javascript
-     * // Download as CSV with BOM for Excel compatibility
-     * const csvBuffer = await client.dataset('my-dataset').downloadItems('csv', { bom: true });
-     * require('fs').writeFileSync('output.csv', csvBuffer);
-     *
-     * // Download as Excel with custom options
-     * const xlsxBuffer = await client.dataset('my-dataset').downloadItems('xlsx', {
-     *   fields: ['url', 'title', 'price'],
-     *   skipEmpty: true,
-     *   limit: 1000
-     * });
-     *
-     * // Download as XML with custom element names
-     * const xmlBuffer = await client.dataset('my-dataset').downloadItems('xml', {
-     *   xmlRoot: 'products',
-     *   xmlRow: 'product'
-     * });
-     * ```
-     */
     async downloadItems(format, options = {}) {
         parseArgument(format, itemFormatSchema);
-        const { timeoutSecs = 'long', signal, ...query } = parseArgument(options, downloadItemsOptionsSchema, 'DatasetClientDownloadItemsOptions');
-        const { data } = await this.httpClient.call({
-            url: this.buildUrl('items'),
-            method: 'GET',
-            params: this.buildParams({
-                format,
-                ...query,
-            }),
-            responseType: 'buffer',
-            timeoutSecs,
-            signal,
-        });
-        return cast(data);
-    }
-    /**
-     * Downloads dataset items in a specific format as a Readable stream. Only works in Node.js.
-     *
-     * Takes the same arguments as {@link downloadItems}, but resolves to the response body as a stream, so a large
-     * export is processed in chunks without holding all of it in memory.
-     *
-     * The stream holds its connection open until you consume it to the end or destroy it. Iterating it with
-     * `for await` or passing it to `pipeline()` from `node:stream/promises` does either one for you.
-     *
-     * @param format - Output format: `'json'`, `'jsonl'`, `'csv'`, `'xlsx'`, `'xml'`, `'rss'`, or `'html'`
-     * @param options - Download and formatting options, the same as for {@link downloadItems}
-     * @param options.timeoutSecs - Timeout for the API to start responding. Default is `'long'`. Once the stream is
-     * returned, it only limits inactivity: the stream errors if no data arrives for that long. To stop the download
-     * early or cap its total duration, destroy the stream or abort `signal`.
-     * @returns Readable stream of the items serialized to the specified format
-     * @see https://docs.apify.com/api/v2/dataset-items-get
-     *
-     * @example
-     * ```javascript
-     * const { createWriteStream } = require('node:fs');
-     * const { pipeline } = require('node:stream/promises');
-     *
-     * // Write a CSV export straight to a file
-     * const stream = await client.dataset('my-dataset').streamItems('csv', { bom: true });
-     * await pipeline(stream, createWriteStream('output.csv'));
-     * ```
-     */
-    async streamItems(format, options = {}) {
-        parseArgument(format, itemFormatSchema);
-        const { timeoutSecs = 'long', signal, ...query } = parseArgument(options, downloadItemsOptionsSchema, 'DatasetClientDownloadItemsOptions');
-        if (!runtime.isNode) {
-            throw new Error('The streamItems() method can only be used in Node.js environment.');
+        const { timeoutSecs = 'long', signal, stream, ...query } = parseArgument(options, downloadItemsOptionsSchema, 'DatasetClientDownloadItemsOptions');
+        if (stream && !runtime.isNode) {
+            throw new Error('The stream option can only be used in Node.js environment.');
         }
         const { data } = await this.httpClient.call({
             url: this.buildUrl('items'),
@@ -310,7 +227,7 @@ export class DatasetClient extends ResourceClient {
                 format,
                 ...query,
             }),
-            responseType: 'stream',
+            responseType: stream ? 'stream' : 'buffer',
             timeoutSecs,
             signal,
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apify-client",
-  "version": "3.0.0-beta.64",
+  "version": "3.0.0-beta.65",
   "description": "Apify API client for JavaScript",
   "engines": {
     "node": ">=22.13.0"