@bitrix24/b24jssdk
Version:
Bitrix24 REST API JavaScript SDK
139 lines (136 loc) • 5.92 kB
JavaScript
/**
* @package @bitrix24/b24jssdk
* @version 1.3.0
* @copyright (c) 2026 Bitrix24
* @license MIT
* @see https://github.com/bitrix24/b24jssdk
* @see https://bitrix24.github.io/b24jssdk/
*/
import { AbstractAction } from '../abstract-action.mjs';
import { Result } from '../../result.mjs';
var __defProp = Object.defineProperty;
var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
class CallListV3 extends AbstractAction {
static {
__name(this, "CallListV3");
}
/**
* Fast data retrieval without counting the total number of records.
*
* @template T - The type of the elements of the returned array (default is `unknown`).
*
* @param {ActionCallListV3} options - parameters for executing the request.
* - `method: string` - The name of the REST API method that returns a list of data (for example: `crm.item.list`, `tasks.task.list`)
* - `params?: Omit<TypeCallParams, 'pagination' | 'order'>` - Request parameters, excluding the `pagination` and `order` parameters,
* since the method is designed to obtain all data in one call.
* Note: Use `filter`, `order`, and `select` to control the selection.
* - `idKey?: string` - The name of the id field as it appears in each RESPONSE item; its value
* drives the cursor. Default is 'id'. Set it to match the id field the method returns.
* - `cursorIdKey?: string` - The field name used in the REQUEST for `order` and the
* `[field, '>', n]` page filter. Defaults to `idKey`. Set it only when the sortable /
* filterable field name differs from the response field name (e.g. an uppercase request
* field but a lowercase response id): pass `idKey: 'id', cursorIdKey: 'ID'`.
* - `customKeyForResult: string` - A custom key indicating that the response REST API will be
* grouped by this field.
* Example: `items` to group a list of CRM items.
* - `requestId?: string` - Unique request identifier for tracking. Used for query deduplication and debugging.
* - `limit?: number` - How many records to retrieve at a time. Default is `50`. Maximum is `1000`.
*
* @returns {Promise<Result<T[]>>} A promise that resolves to the result of an REST API call.
*
* @example
* import { Text } from '@bitrix24/b24jssdk'
*
* interface MainEventLogItem { id: number, userId: number }
* const sixMonthAgo = new Date()
* sixMonthAgo.setMonth((new Date()).getMonth() - 6)
* sixMonthAgo.setHours(0, 0, 0)
* const response = await b24.actions.v3.callList.make<MainEventLogItem>({
* method: 'main.eventlog.list',
* params: {
* filter: [
* ['timestampX', '>=', Text.toB24Format(sixMonthAgo)] // created at least 6 months ago
* ],
* select: ['id', 'userId']
* },
* idKey: 'id',
* customKeyForResult: 'items',
* requestId: 'eventlog-123',
* limit: 60
* })
* if (!response.isSuccess) {
* throw new Error(`Problem: ${response.getErrorMessages().join('; ')}`)
* }
* const list = response.getData()
* console.log(`Result: ${list?.length}`) // Number of items received
*/
async make(options) {
const batchSize = options?.limit ?? 50;
const result = new Result();
const idKey = options?.idKey ?? "id";
const cursorIdKey = options?.cursorIdKey ?? idKey;
const customKeyForResult = options?.customKeyForResult ?? null;
const params = options?.params ?? {};
if ("order" in params && params["order"]) {
this._logger.warning("callList.make: user-provided `order` parameter is ignored because cursor-based pagination requires ordering by cursorIdKey. Use `filter` to narrow results instead.");
}
const { order: _ignoredOrder, ...restParams } = params;
const requestParams = {
...restParams,
order: { [cursorIdKey]: "ASC" },
filter: [...params["filter"] || []],
pagination: { page: 0, limit: batchSize }
};
let allItems = [];
let isContinue = true;
let nextId = 0;
do {
const sendParams = { ...requestParams, filter: [...requestParams.filter] };
sendParams.filter.push([cursorIdKey, ">", nextId]);
const response = await this._b24.actions.v3.call.make({
method: options.method,
params: sendParams,
requestId: options.requestId
});
if (!response.isSuccess) {
this._logger.error("callFastListMethod", {
method: options.method,
requestId: options.requestId,
messages: response.getErrorMessages()
});
for (const [index, error] of response.errors) {
result.addError(error, index);
}
isContinue = false;
break;
}
const responseData = response.getData();
if (!responseData) {
isContinue = false;
break;
}
const resultData = responseData.result[customKeyForResult];
if (resultData.length === 0) {
isContinue = false;
break;
}
allItems = [...allItems, ...resultData];
if (resultData.length < batchSize) {
isContinue = false;
break;
}
const lastItem = resultData[resultData.length - 1];
const cursorValue = lastItem ? Number.parseInt(lastItem[idKey], 10) : Number.NaN;
if (Number.isFinite(cursorValue)) {
nextId = cursorValue;
} else {
this._logger.warning(`callList.make: pagination stops here \u2014 no numeric id could be read from the returned items via idKey "${idKey}". Make sure idKey matches the id field in the response; if the sortable field name differs from it, also set cursorIdKey (e.g. idKey: 'id', cursorIdKey: 'ID').`);
isContinue = false;
break;
}
} while (isContinue);
return result.setData(allItems);
}
}
export { CallListV3 };
//# sourceMappingURL=call-list.mjs.map