@bitrix24/b24jssdk/dist/esm/tools/filter-v3.mjs.map

Bitrix24 REST API JavaScript SDK

{"version":3,"file":"filter-v3.mjs","sources":["../../../src/tools/filter-v3.ts"],"sourcesContent":["import { SdkError } from '../core/sdk-error'\n\n/**\n * The eight — and only eight — comparison operators the Bitrix24 REST API v3\n * filter grammar accepts. Anything else is rejected server-side with\n * `UNKNOWNFILTEROPERATOREXCEPTION`.\n */\nexport type FilterV3Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'in' | 'between'\n\nconst FILTER_V3_OPERATORS: readonly FilterV3Operator[] = ['=', '!=', '>', '>=', '<', '<=', 'in', 'between']\n\n/**\n * A single condition in short-form: `[field, operator, value]`.\n */\nexport type FilterV3Condition = [string, FilterV3Operator, unknown]\n\n/**\n * A logical group of conditions / nested groups. `logic` defaults to `'and'`;\n * `negative: true` wraps the whole group in a NOT.\n */\nexport interface FilterV3Group {\n  logic?: 'and' | 'or'\n  negative?: boolean\n  conditions: FilterV3Node[]\n}\n\nexport type FilterV3Node = FilterV3Condition | FilterV3Group\n\nfunction condition(field: string, operator: FilterV3Operator, value: unknown): FilterV3Condition {\n  if (typeof field !== 'string' || field.length === 0) {\n    throw new SdkError({\n      code: 'JSSDK_FILTER_V3_INVALID_FIELD',\n      description: `FilterV3: field name must be a non-empty string, got ${JSON.stringify(field)}.`,\n      status: 400\n    })\n  }\n  if (!FILTER_V3_OPERATORS.includes(operator)) {\n    throw new SdkError({\n      code: 'JSSDK_FILTER_V3_INVALID_OPERATOR',\n      description: `FilterV3: operator \"${operator}\" is not one of ${FILTER_V3_OPERATORS.join(' ')}.`,\n      status: 400\n    })\n  }\n  return [field, operator, value]\n}\n\n/**\n * Typed builder for Bitrix24 REST API **v3** filters (the array-of-triples\n * dialect with AND/OR/NOT groups — see the v3 reference §3). Produces exactly\n * the structures the server accepts, so a bad operator or a malformed\n * `in` / `between` value fails fast on the client instead of as a server 400.\n *\n * @example\n * import { FilterV3 as F } from '@bitrix24/b24jssdk'\n *\n * // status = NEW  AND  (id in [1,2]  OR  id > 100)\n * const filter = F.build(\n *   F.eq('status', 'NEW'),\n *   F.or(\n *     F.in('id', [1, 2]),\n *     F.gt('id', 100)\n *   )\n * )\n * await b24.actions.v3.call.make({ method: 'tasks.task.list', params: { filter } })\n */\nexport const FilterV3 = Object.freeze({\n  /** `field = value` */\n  eq(field: string, value: unknown): FilterV3Condition {\n    return condition(field, '=', value)\n  },\n  /** `field != value` */\n  ne(field: string, value: unknown): FilterV3Condition {\n    return condition(field, '!=', value)\n  },\n  /** `field > value` */\n  gt(field: string, value: unknown): FilterV3Condition {\n    return condition(field, '>', value)\n  },\n  /** `field >= value` */\n  ge(field: string, value: unknown): FilterV3Condition {\n    return condition(field, '>=', value)\n  },\n  /** `field < value` */\n  lt(field: string, value: unknown): FilterV3Condition {\n    return condition(field, '<', value)\n  },\n  /** `field <= value` */\n  le(field: string, value: unknown): FilterV3Condition {\n    return condition(field, '<=', value)\n  },\n  /** `field in [values]` — `values` must be a non-empty array. */\n  in(field: string, values: unknown[]): FilterV3Condition {\n    if (!Array.isArray(values) || values.length === 0) {\n      throw new SdkError({\n        code: 'JSSDK_FILTER_V3_INVALID_IN',\n        description: `FilterV3.in(\"${field}\"): value must be a non-empty array.`,\n        status: 400\n      })\n    }\n    return condition(field, 'in', values)\n  },\n  /** `field between [from, to]` — inclusive range of exactly two defined operands. */\n  between(field: string, from: unknown, to: unknown): FilterV3Condition {\n    if (from === undefined || from === null || to === undefined || to === null) {\n      throw new SdkError({\n        code: 'JSSDK_FILTER_V3_INVALID_BETWEEN',\n        description: `FilterV3.between(\"${field}\"): both range operands must be defined (got [${String(from)}, ${String(to)}]).`,\n        status: 400\n      })\n    }\n    return condition(field, 'between', [from, to])\n  },\n\n  /** Combine nodes with AND (for nesting inside an OR; the top level is already AND). */\n  and(...conditions: FilterV3Node[]): FilterV3Group {\n    return { logic: 'and', conditions }\n  },\n  /** Combine nodes with OR. */\n  or(...conditions: FilterV3Node[]): FilterV3Group {\n    return { logic: 'or', conditions }\n  },\n  /**\n   * Negate a condition or group (wraps it in a NOT). A bare condition is wrapped\n   * in a single-item AND group so the `negative` flag has somewhere to live.\n   * Returns a fresh group (the input's `conditions` array is copied, not shared).\n   */\n  not(node: FilterV3Node): FilterV3Group {\n    if (isGroup(node)) {\n      return { ...node, conditions: [...node.conditions], negative: true }\n    }\n    return { logic: 'and', negative: true, conditions: [node] }\n  },\n\n  /**\n   * Assemble the top-level filter array (its elements are AND-joined) ready to\n   * pass as `params.filter`. Falsy nodes are skipped, so you can inline\n   * conditionals: `F.build(F.eq('a', 1), flag && F.gt('b', 2))`.\n   *\n   * Always wrap with `build` (or an array) even for a single condition —\n   * `params.filter` must be an array, so pass `build(F.eq('a', 1))`, not the bare\n   * `F.eq('a', 1)`. Each surviving node is shape-checked, so a forgotten spread\n   * (`build([F.eq(...)])`) or a hand-rolled malformed triple fails fast here\n   * instead of as an opaque server error.\n   */\n  build(...nodes: Array<FilterV3Node | false | null | undefined>): FilterV3Node[] {\n    const result = nodes.filter(Boolean) as FilterV3Node[]\n    for (const node of result) {\n      assertNode(node)\n    }\n    return result\n  }\n})\n\nfunction isGroup(node: unknown): node is FilterV3Group {\n  return !Array.isArray(node) && typeof node === 'object' && node !== null && 'conditions' in node\n}\n\nfunction assertNode(node: FilterV3Node): void {\n  if (isGroup(node)) {\n    return\n  }\n  const ok = Array.isArray(node)\n    && node.length === 3\n    && typeof node[0] === 'string'\n    && FILTER_V3_OPERATORS.includes(node[1] as FilterV3Operator)\n  if (!ok) {\n    throw new SdkError({\n      code: 'JSSDK_FILTER_V3_INVALID_NODE',\n      description: `FilterV3.build: each node must be a [field, operator, value] condition or a group — got ${JSON.stringify(node)}. Did you forget to spread (build(...nodes)) or build a condition with FilterV3 helpers?`,\n      status: 400\n    })\n  }\n}\n"],"names":[],"mappings":"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"}