@bitrix24/b24jssdk/dist/cjs/tools/batch-ref-v3.cjs.map

Bitrix24 REST API JavaScript SDK

{"version":3,"file":"batch-ref-v3.cjs","sources":["../../../src/tools/batch-ref-v3.ts"],"sourcesContent":["import { SdkError } from '../core/sdk-error'\n\n/**\n * A `$ref` substitution marker: pulls a single value from an earlier batch\n * command's context by dotted path (reference §8).\n */\nexport interface BatchRef { $ref: string }\n\n/**\n * A `$refArray` substitution marker: collects one field across the `items[]` of\n * an earlier list/tail command into an array (reference §8).\n */\nexport interface BatchRefArray { $refArray: string }\n\nfunction assertPath(path: string, who: string): void {\n  if (typeof path !== 'string' || path.length === 0) {\n    throw new SdkError({\n      code: 'JSSDK_BATCH_REF_V3_INVALID_PATH',\n      description: `${who}: path must be a non-empty dotted string (e.g. \"tasks.id\").`,\n      status: 400\n    })\n  }\n}\n\n/**\n * Helpers for the v3 batch `$ref` / `$refArray` substitution markers (reference\n * §8). The **server** performs the substitution: these helpers just build the\n * marker objects you drop into a later command's `params` (the SDK forwards\n * `params` to the wire `query`), with a little client-side validation. Reference\n * an earlier command by its `as` alias — or by its numeric index if you omit `as`.\n * Only `item` (get) and `items` (list/tail) results land in context; `add` → id\n * and `update` → bool results do not.\n *\n * **v3 only.** Substitution is a v3 batch feature. Dropped into a v2 batch\n * (`actions.v2.batch.make`) the markers are NOT substituted — they are encoded\n * as literal filter values and silently yield wrong/empty results.\n *\n * **Security:** the `path` selects from the batch's own response context, but do\n * not build it from untrusted end-user input — a crafted path could read context\n * the caller did not intend to expose to the next command.\n *\n * @example\n * import { BatchRefV3 as R } from '@bitrix24/b24jssdk'\n *\n * const response = await b24.actions.v3.batch.make({\n *   calls: [\n *     { method: 'tasks.task.list', as: 'tasks', params: { select: ['id'] } },\n *     {\n *       method: 'tasks.task.comment.list',\n *       // server substitutes the array of ids collected from the first command's items[]\n *       params: { filter: [['taskId', 'in', R.refArray('tasks.id')]] }\n *     }\n *   ]\n * })\n */\nexport const BatchRefV3 = Object.freeze({\n  /**\n   * `{ $ref: path }` — substitute a single value from context, e.g.\n   * `ref('newTask.item.id')`. `add` → id / `update` → bool results are NOT in\n   * context (reference §8); only `item` (get) and `items` (list/tail) are.\n   */\n  ref(path: string): BatchRef {\n    assertPath(path, 'BatchRefV3.ref')\n    return { $ref: path }\n  },\n  /**\n   * `{ $refArray: path }` — collect one field across the `items[]` of an earlier\n   * list/tail command, e.g. `refArray('tasks.id')`. The path MUST contain a dot\n   * (`alias.field`); the server rejects a dot-less path with INVALIDSELECTEXCEPTION.\n   */\n  refArray(path: string): BatchRefArray {\n    assertPath(path, 'BatchRefV3.refArray')\n    if (!path.includes('.')) {\n      throw new SdkError({\n        code: 'JSSDK_BATCH_REF_V3_INVALID_REF_ARRAY',\n        description: `BatchRefV3.refArray: path \"${path}\" must contain a dot (\"alias.field\") — the server collects <field> across the alias's items[].`,\n        status: 400\n      })\n    }\n    return { $refArray: path }\n  }\n})\n"],"names":["SdkError"],"mappings":";;;;;;;;;;;;;;AAcA,SAAS,UAAA,CAAW,MAAc,GAAA,EAAmB;AACnD,EAAA,IAAI,OAAO,IAAA,KAAS,QAAA,IAAY,IAAA,CAAK,WAAW,CAAA,EAAG;AACjD,IAAA,MAAM,IAAIA,iBAAA,CAAS;AAAA,MACjB,IAAA,EAAM,iCAAA;AAAA,MACN,WAAA,EAAa,GAAG,GAAG,CAAA,2DAAA,CAAA;AAAA,MACnB,MAAA,EAAQ;AAAA,KACT,CAAA;AAAA,EACH;AACF;AARS,MAAA,CAAA,UAAA,EAAA,YAAA,CAAA;AAyCF,MAAM,UAAA,GAAa,OAAO,MAAA,CAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMtC,IAAI,IAAA,EAAwB;AAC1B,IAAA,UAAA,CAAW,MAAM,gBAAgB,CAAA;AACjC,IAAA,OAAO,EAAE,MAAM,IAAA,EAAK;AAAA,EACtB,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,SAAS,IAAA,EAA6B;AACpC,IAAA,UAAA,CAAW,MAAM,qBAAqB,CAAA;AACtC,IAAA,IAAI,CAAC,IAAA,CAAK,QAAA,CAAS,GAAG,CAAA,EAAG;AACvB,MAAA,MAAM,IAAIA,iBAAA,CAAS;AAAA,QACjB,IAAA,EAAM,sCAAA;AAAA,QACN,WAAA,EAAa,8BAA8B,IAAI,CAAA,mGAAA,CAAA;AAAA,QAC/C,MAAA,EAAQ;AAAA,OACT,CAAA;AAAA,IACH;AACA,IAAA,OAAO,EAAE,WAAW,IAAA,EAAK;AAAA,EAC3B;AACF,CAAC;;;;"}