@uipath/maestro-builder-sdk 6.6.1 → 6.7.0

package/dist/core/actions.js

@@ -891,71 +891,118 @@ export function dynamicExtract(inputs) {
     return builtinActionSpec({ kind: 'dynamicExtract', inputs });
 }
 /**
- * Read ONE entity record from Data Fabric (`core.datafabric.read`). The record
+ * Query entity records from Data Fabric (`core.datafabric.read`). The result
  * publishes to the step's `output`; downstream references re-fetch fresh data
  * at activation time (the engine re-runs the query rather than caching).
  *
  * @remarks
- * **Prefer the connector for Data Fabric work during the transition.**
- * `core.datafabric.*` has exactly two verbs — this one and
- * {@link dataFabricUpdate} — and neither declares an output schema. Create,
- * delete, get-by-id, a multi-record query with a row limit, file record fields
- * and entity events are NOT in this family: they are operations on the SAME
- * product reached through its Integration Service connector,
+ * This node is **read-one AND query-many**, on its 1.4 definition: `resultMode:
+ * 'multiple'` publishes the matching records under `output.results`, and the
+ * platform renames the node "Query entity records" to say so. The SDK still
+ * pins 1.0 — read-one — as the no-`{ version }` default, so passing
+ * `resultMode` is what selects 1.4; see {@link DataFabricReadInputs.resultMode}.
+ *
+ * The native family covers all four CRUD verbs: this one,
+ * {@link dataFabricCreate}, {@link dataFabricUpdate} and
+ * {@link dataFabricDelete}. What it does NOT cover is get-by-id, a query row
+ * limit, file record fields, and entity events — those are operations on the
+ * SAME product reached through its Integration Service connector,
  * `uipath-uipath-dataservice` (the tenant displays it as **UiPath Data
- * Fabric**), which covers every verb including the two here.
- *
- * Taking this node for the one verb that has a native form leaves the rest of
- * the same entity on the connector — two connection bindings and two payload
- * shapes in one flow. So route entity work through the connector unless the
- * scenario names these nodes; native forms for the remaining verbs are the
- * direction of travel, and this guidance changes when they land. `check` does
- * not reject a native node — this is a routing default, not a rule:
+ * Fabric**). So a flow that needs one of those still straddles two surfaces,
+ * and the connector remains the one surface that covers everything:
  *
  * ```ts
- * .step('create', connector('uipath-uipath-dataservice', 'create-entity-record',
- *   { entityName: 'Contracts', contractTitle: 'Q3 renewal' }, { connection: 'df' }))
+ * .step('byId', connector('uipath-uipath-dataservice', 'get-entity-record-by-id',
+ *   { entityName: 'Contracts', recordId: input('id') }, { connection: 'df' }))
  * ```
  *
- * That operation's body fields come from the entity, so the library cannot
- * carry them: run `npx flow-sdk registry prepare uipath-uipath-dataservice
- * create-entity-record -f entityName=<Entity>` first (`uip maestro registry
- * prepare …` is the same command when you are driving through the UiPath CLI). The routing table is in
- * the `data-fabric.md` reference and the parent-field loop in
- * `connector-params.md` — cited by name rather than linked, because this
+ * A connector operation's body fields come from the entity, so the library
+ * cannot carry them: run `npx flow-sdk registry prepare uipath-uipath-dataservice
+ * get-entity-record-by-id -f entityName=<Entity>` first (`uip maestro registry
+ * prepare …` is the same command when you are driving through the UiPath CLI).
+ * The routing table is in the `data-fabric.md` reference and the parent-field
+ * loop in `connector-params.md` — cited by name rather than linked, because this
  * comment renders both into the flat corpus, where those files sit alongside
  * it, and onto the site, where each symbol is its own page and a relative
  * `./data-fabric` resolves to nothing.
  *
- * @param inputs - The entity, optional filter rows, and folder scope.
+ * @param inputs - The entity, optional filter rows, result mode, and folder scope.
  * @returns An action spec to pass to `.step(name, …)`.
  */
 export function dataFabricRead(inputs) {
     return builtinActionSpec({ kind: 'dataFabricRead', inputs });
 }
+/**
+ * Create an entity record in Data Fabric (`core.datafabric.create`). The new
+ * record publishes to the step's `output`, so a following
+ * {@link dataFabricUpdate} or {@link dataFabricDelete} can read its id.
+ *
+ * @remarks
+ * `values` must name at least one column — the node's schema rejects an empty
+ * field list rather than inserting a blank row, and `check` says so before the
+ * platform does. Field names are the ENTITY's, so copy them from the scenario
+ * or the tenant; nothing offline can tell a real column from a typo.
+ *
+ * See {@link dataFabricRead} for what the native family still does not cover
+ * and which connector operation covers it.
+ *
+ * @param inputs - The entity, the columns the record starts with, and folder scope.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function dataFabricCreate(inputs) {
+    return builtinActionSpec({ kind: 'dataFabricCreate', inputs });
+}
 /**
  * Update an entity record in Data Fabric (`core.datafabric.update`). Target the
  * record by id or through an earlier {@link dataFabricRead} step; downstream
  * reads of this step observe the record AFTER the write.
  *
  * @remarks
- * The second and last verb of the native family — see {@link dataFabricRead}
- * for what the family does NOT cover, which connector operation covers it
- * instead, and why entity work routes through the connector during the
- * transition. For an update whose flow also creates, gets or deletes on the
- * same entity, use `connector(…, 'update-entity-record', …)` so the flow keeps
- * one surface.
+ * `set` must write at least one column: an empty `set` is a no-op the platform
+ * reports as success, so `check` rejects it.
+ *
+ * See {@link dataFabricRead} for what the native family still does not cover
+ * and which connector operation covers it.
  *
  * @param inputs - The entity, the record selector, and the columns to write.
  * @returns An action spec to pass to `.step(name, …)`.
  */
 export function dataFabricUpdate(inputs) {
-    const byId = inputs.record?.byId !== undefined;
-    const fromRead = typeof inputs.record?.fromRead === 'string';
+    assertOneRecordRef(inputs.record, 'dataFabricUpdate');
+    return builtinActionSpec({ kind: 'dataFabricUpdate', inputs });
+}
+/**
+ * Delete an entity record from Data Fabric (`core.datafabric.delete`). Target
+ * the record by id or through an earlier {@link dataFabricRead} step, exactly
+ * as {@link dataFabricUpdate} does.
+ *
+ * @remarks
+ * A delete **publishes nothing** — its definition declares no output — so
+ * `$vars.<step>.output` is undefined at run time and `check` rejects a read of
+ * it. Take what you need off the read step that found the record, before the
+ * delete.
+ *
+ * See {@link dataFabricRead} for what the native family still does not cover
+ * and which connector operation covers it.
+ *
+ * @param inputs - The entity, the record selector, and folder scope.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function dataFabricDelete(inputs) {
+    assertOneRecordRef(inputs.record, 'dataFabricDelete');
+    return builtinActionSpec({ kind: 'dataFabricDelete', inputs });
+}
+/**
+ * `record` names exactly ONE of `{ byId }` / `{ fromRead }`. Both forms are
+ * optional properties on the same object type, so TypeScript alone cannot
+ * refuse `{}` — and an empty selector compiles into a write with no target.
+ */
+function assertOneRecordRef(record, factory) {
+    const byId = record?.byId !== undefined;
+    const fromRead = typeof record?.fromRead === 'string';
     if (byId === fromRead) {
-        throw new Error("dataFabricUpdate() targets exactly ONE of record: { byId } or record: { fromRead: '<step>' }.");
+        throw new Error(`${factory}() targets exactly ONE of record: { byId } or record: { fromRead: '<step>' }.`);
     }
-    return builtinActionSpec({ kind: 'dataFabricUpdate', inputs });
 }
 /**
  * Declare an Orchestrator QUEUE ITEM step.