hobots 5.2.0 → 6.0.0

package/dist/index.d.cts

@@ -270,14 +270,17 @@ interface RunItemOptions extends RunItemImageOptions {
     id?: string;
 }
 /**
- * O item em processamento dentro de `items.each`: o desfecho (`succeeded`/`failed`/
+ * O item em processamento dentro de `items.each` — o único argumento do handler: o elemento
+ * em `value`, a posição em `index`, o desfecho (`succeeded`/`failed`/
  * `occurrence`) com o `id` e o payload base já resolvidos, e o handle `step` da etapa do
  * item (`warning`/`image`/`data`), e `data(...)` para ir guardando o payload do item sem
  * decidir o desfecho. Sub-etapas: `hobots.step(...)` dentro do handler já
  * aninha na etapa do item. Sem chamada explícita, o SDK decide: retornou → `succeeded`;
  * lançou → `failed` com a mensagem do erro.
  */
-interface RunItemHandle {
+interface RunItemHandle<T = unknown> {
+    /** O elemento da lista — o mesmo em todas as tentativas. */
+    readonly value: T;
     /** Posição do elemento na lista (0-based). */
     readonly index: number;
     /** Identidade do item: a resolvida por `options.id` ou, sem ela, uma gerada pelo SDK — a mesma em todas as tentativas. */
@@ -313,8 +316,13 @@ interface RunItemsEachOptions<T> {
      * no elemento é erro do bot (lança e interrompe o loop).
      */
     id?: string | readonly string[] | ((element: T, index: number) => string | number | null | undefined) | null;
-    /** Atributos base do item (viram colunas no app) — presentes em qualquer desfecho, inclusive falha. */
-    payload?: (element: T, index: number) => Record<string, unknown> | undefined;
+    /**
+     * Atributos base do item (viram colunas no app) — presentes em qualquer desfecho, inclusive falha.
+     * Omitido: os campos do próprio elemento quando ele é um objeto simples (`{ id, cliente, … }`,
+     * cópia rasa); instância de classe, array e primitivo ficam sem payload base. Uma função substitui
+     * esse padrão (escolhe/renomeia as colunas); `false` desliga.
+     */
+    payload?: ((element: T, index: number) => Record<string, unknown> | undefined) | false;
     /** `op` da etapa de cada item no waterfall. Default: 'item'. */
     op?: string;
     /** Descrição da etapa de cada item. Default: o `id`, senão `#<posição>`. */
@@ -351,7 +359,11 @@ interface RunItemsEachResult {
     /** Já concluídos neste trabalho (reexecução): não rodaram, mas contam no `total`. */
     skipped: number;
 }
-type RunItemsEachHandler<T> = (element: T, item: RunItemHandle, index: number) => unknown;
+/**
+ * Handler do `items.each` (6.0.0): `(item, index)` — o elemento em `item.value`; `index` (0-based,
+ * o mesmo que `item.index`) é opcional, declare só se usar.
+ */
+type RunItemsEachHandler<T> = (item: RunItemHandle<T>, index: number) => unknown;
 /**
  * Registro dos itens que a execução processou/gerou (a entrega do bot: notas
  * fiscais baixadas, boletos emitidos...). Chamadas são síncronas — os itens são

package/dist/index.d.ts

@@ -270,14 +270,17 @@ interface RunItemOptions extends RunItemImageOptions {
     id?: string;
 }
 /**
- * O item em processamento dentro de `items.each`: o desfecho (`succeeded`/`failed`/
+ * O item em processamento dentro de `items.each` — o único argumento do handler: o elemento
+ * em `value`, a posição em `index`, o desfecho (`succeeded`/`failed`/
  * `occurrence`) com o `id` e o payload base já resolvidos, e o handle `step` da etapa do
  * item (`warning`/`image`/`data`), e `data(...)` para ir guardando o payload do item sem
  * decidir o desfecho. Sub-etapas: `hobots.step(...)` dentro do handler já
  * aninha na etapa do item. Sem chamada explícita, o SDK decide: retornou → `succeeded`;
  * lançou → `failed` com a mensagem do erro.
  */
-interface RunItemHandle {
+interface RunItemHandle<T = unknown> {
+    /** O elemento da lista — o mesmo em todas as tentativas. */
+    readonly value: T;
     /** Posição do elemento na lista (0-based). */
     readonly index: number;
     /** Identidade do item: a resolvida por `options.id` ou, sem ela, uma gerada pelo SDK — a mesma em todas as tentativas. */
@@ -313,8 +316,13 @@ interface RunItemsEachOptions<T> {
      * no elemento é erro do bot (lança e interrompe o loop).
      */
     id?: string | readonly string[] | ((element: T, index: number) => string | number | null | undefined) | null;
-    /** Atributos base do item (viram colunas no app) — presentes em qualquer desfecho, inclusive falha. */
-    payload?: (element: T, index: number) => Record<string, unknown> | undefined;
+    /**
+     * Atributos base do item (viram colunas no app) — presentes em qualquer desfecho, inclusive falha.
+     * Omitido: os campos do próprio elemento quando ele é um objeto simples (`{ id, cliente, … }`,
+     * cópia rasa); instância de classe, array e primitivo ficam sem payload base. Uma função substitui
+     * esse padrão (escolhe/renomeia as colunas); `false` desliga.
+     */
+    payload?: ((element: T, index: number) => Record<string, unknown> | undefined) | false;
     /** `op` da etapa de cada item no waterfall. Default: 'item'. */
     op?: string;
     /** Descrição da etapa de cada item. Default: o `id`, senão `#<posição>`. */
@@ -351,7 +359,11 @@ interface RunItemsEachResult {
     /** Já concluídos neste trabalho (reexecução): não rodaram, mas contam no `total`. */
     skipped: number;
 }
-type RunItemsEachHandler<T> = (element: T, item: RunItemHandle, index: number) => unknown;
+/**
+ * Handler do `items.each` (6.0.0): `(item, index)` — o elemento em `item.value`; `index` (0-based,
+ * o mesmo que `item.index`) é opcional, declare só se usar.
+ */
+type RunItemsEachHandler<T> = (item: RunItemHandle<T>, index: number) => unknown;
 /**
  * Registro dos itens que a execução processou/gerou (a entrega do bot: notas
  * fiscais baixadas, boletos emitidos...). Chamadas são síncronas — os itens são

package/dist/index.js

@@ -4,7 +4,7 @@ import {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "5.2.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "6.0.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -1857,13 +1857,15 @@ function thrownMessage(error) {
   return safeString(error);
 }
 var ItemHandle = class {
-  constructor(index, id, step, basePayload, sink) {
+  constructor(value, index, id, step, basePayload2, sink) {
+    this.value = value;
     this.index = index;
     this.step = step;
-    this.basePayload = basePayload;
+    this.basePayload = basePayload2;
     this.sink = sink;
     this.id = id ?? uuid4();
   }
+  value;
   index;
   step;
   basePayload;
@@ -1906,6 +1908,18 @@ var ItemHandle = class {
     this.sink.report(status, message, Object.keys(merged).length > 0 ? merged : void 0, this.id, image3);
   }
 };
+function defaultPayload(element) {
+  if (typeof element !== "object" || element === null) return void 0;
+  const proto = Object.getPrototypeOf(element);
+  if (proto !== Object.prototype && proto !== null) return void 0;
+  const copy = { ...element };
+  return Object.keys(copy).length > 0 ? copy : void 0;
+}
+function basePayload(spec, element, index) {
+  if (spec === false) return void 0;
+  if (spec === void 0) return defaultPayload(element);
+  return spec(element, index);
+}
 function field(element, name) {
   if (typeof element !== "object" || element === null) return { present: false, value: void 0 };
   const record = element;
@@ -1966,7 +1980,7 @@ async function eachItem(list, handler, options, sink) {
     }
     const description = options.description?.(element, index) ?? id ?? `#${index + 1}`;
     const step = sink.startStep(options.op ?? "item", description);
-    const handle = new ItemHandle(index, id, step, options.payload?.(element, index), sink);
+    const handle = new ItemHandle(element, index, id, step, basePayload(options.payload, element, index), sink);
     const current = index;
     let attempts = 0;
     let lastFailure;
@@ -1975,7 +1989,7 @@ async function eachItem(list, handler, options, sink) {
         (attempt) => {
           attempts = attempt;
           if (attempt > 1) handle._nextAttempt(attempt);
-          return sink.stepScope(step, async () => handler(element, handle, current));
+          return sink.stepScope(step, async () => handler(handle, current));
         },
         {
           retries: totalRetries,