@bitrix24/b24jssdk/dist/cjs/tools/filter-v3.cjs

Bitrix24 REST API JavaScript SDK

/**
 * @package @bitrix24/b24jssdk
 * @version 2.0.0
 * @copyright (c) 2026 Bitrix24
 * @license MIT
 * @see https://github.com/bitrix24/b24jssdk
 * @see https://bitrix24.github.io/b24jssdk/
 */
'use strict';

const sdkError = require('../core/sdk-error.cjs');

var __defProp = Object.defineProperty;
var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
const FILTER_V3_OPERATORS = ["=", "!=", ">", ">=", "<", "<=", "in", "between"];
function condition(field, operator, value) {
  if (typeof field !== "string" || field.length === 0) {
    throw new sdkError.SdkError({
      code: "JSSDK_FILTER_V3_INVALID_FIELD",
      description: `FilterV3: field name must be a non-empty string, got ${JSON.stringify(field)}.`,
      status: 400
    });
  }
  if (!FILTER_V3_OPERATORS.includes(operator)) {
    throw new sdkError.SdkError({
      code: "JSSDK_FILTER_V3_INVALID_OPERATOR",
      description: `FilterV3: operator "${operator}" is not one of ${FILTER_V3_OPERATORS.join(" ")}.`,
      status: 400
    });
  }
  return [field, operator, value];
}
__name(condition, "condition");
const FilterV3 = Object.freeze({
  /** `field = value` */
  eq(field, value) {
    return condition(field, "=", value);
  },
  /** `field != value` */
  ne(field, value) {
    return condition(field, "!=", value);
  },
  /** `field > value` */
  gt(field, value) {
    return condition(field, ">", value);
  },
  /** `field >= value` */
  ge(field, value) {
    return condition(field, ">=", value);
  },
  /** `field < value` */
  lt(field, value) {
    return condition(field, "<", value);
  },
  /** `field <= value` */
  le(field, value) {
    return condition(field, "<=", value);
  },
  /** `field in [values]` — `values` must be a non-empty array. */
  in(field, values) {
    if (!Array.isArray(values) || values.length === 0) {
      throw new sdkError.SdkError({
        code: "JSSDK_FILTER_V3_INVALID_IN",
        description: `FilterV3.in("${field}"): value must be a non-empty array.`,
        status: 400
      });
    }
    return condition(field, "in", values);
  },
  /** `field between [from, to]` — inclusive range of exactly two defined operands. */
  between(field, from, to) {
    if (from === void 0 || from === null || to === void 0 || to === null) {
      throw new sdkError.SdkError({
        code: "JSSDK_FILTER_V3_INVALID_BETWEEN",
        description: `FilterV3.between("${field}"): both range operands must be defined (got [${String(from)}, ${String(to)}]).`,
        status: 400
      });
    }
    return condition(field, "between", [from, to]);
  },
  /** Combine nodes with AND (for nesting inside an OR; the top level is already AND). */
  and(...conditions) {
    return { logic: "and", conditions };
  },
  /** Combine nodes with OR. */
  or(...conditions) {
    return { logic: "or", conditions };
  },
  /**
   * Negate a condition or group (wraps it in a NOT). A bare condition is wrapped
   * in a single-item AND group so the `negative` flag has somewhere to live.
   * Returns a fresh group (the input's `conditions` array is copied, not shared).
   */
  not(node) {
    if (isGroup(node)) {
      return { ...node, conditions: [...node.conditions], negative: true };
    }
    return { logic: "and", negative: true, conditions: [node] };
  },
  /**
   * Assemble the top-level filter array (its elements are AND-joined) ready to
   * pass as `params.filter`. Falsy nodes are skipped, so you can inline
   * conditionals: `F.build(F.eq('a', 1), flag && F.gt('b', 2))`.
   *
   * Always wrap with `build` (or an array) even for a single condition —
   * `params.filter` must be an array, so pass `build(F.eq('a', 1))`, not the bare
   * `F.eq('a', 1)`. Each surviving node is shape-checked, so a forgotten spread
   * (`build([F.eq(...)])`) or a hand-rolled malformed triple fails fast here
   * instead of as an opaque server error.
   */
  build(...nodes) {
    const result = nodes.filter(Boolean);
    for (const node of result) {
      assertNode(node);
    }
    return result;
  }
});
function isGroup(node) {
  return !Array.isArray(node) && typeof node === "object" && node !== null && "conditions" in node;
}
__name(isGroup, "isGroup");
function assertNode(node) {
  if (isGroup(node)) {
    return;
  }
  const ok = Array.isArray(node) && node.length === 3 && typeof node[0] === "string" && FILTER_V3_OPERATORS.includes(node[1]);
  if (!ok) {
    throw new sdkError.SdkError({
      code: "JSSDK_FILTER_V3_INVALID_NODE",
      description: `FilterV3.build: each node must be a [field, operator, value] condition or a group \u2014 got ${JSON.stringify(node)}. Did you forget to spread (build(...nodes)) or build a condition with FilterV3 helpers?`,
      status: 400
    });
  }
}
__name(assertNode, "assertNode");

exports.FilterV3 = FilterV3;
//# sourceMappingURL=filter-v3.cjs.map