ACTION_ID: csv_to_structured_array_format
NAME: CSV to List
CATEGORY: transform
CREDITS: 0

Convert comma-separated values into a structured array that can be
sectioned downstream.

INDEX:
  1. Inputs
  2. Outputs
  3. How to configure
  4. Key notes
  5. Where it fits in a workflow
  6. When to use
  7. When not to use

================================================================================
1. INPUTS
================================================================================

comma_separated_values (type: string, required) — Comma Separated Values
  Multiple values separated by a comma.

================================================================================
2. OUTPUTS
================================================================================

list (type: structured_array) — Formatted List
  The CSV input split into a structured array, with one row per
  comma-separated value. Per-row fields:
  - value (type: string) — Value
      The individual CSV value for this row.

================================================================================
3. HOW TO CONFIGURE
================================================================================

Configure Action body:

{
  "inputs": {
    "comma_separated_values": "{{llm_models_1.generated_content}}"
  }
}

Pass any comma-separated string as `comma_separated_values`. The
input can be a `{{ref}}` to upstream output or a literal string
(e.g. `"alice,bob,carol"`).

================================================================================
4. KEY NOTES
================================================================================

- Multiple CSV list variables can be combined into a single input by
  joining them with a comma — e.g. "{{step_a.csv}},{{step_b.csv}}"
  produces one merged structured array.

- ⚠ Suspected bug — single-value input returns an empty list.
  When `comma_separated_values` resolves to a string with no commas
  (e.g. `"110"`), the action returns `list: {}` (empty) instead of a
  one-item list `[{value: "110"}]`. Verified for upstream JS formatter
  outputs, LLM outputs, and literal strings; trailing whitespace
  doesn't change the result, only the presence of at least one comma
  does. Likely unintended — a single value is a valid one-item CSV —
  and may be patched. Until then:

    Workaround: append a trailing comma at the upstream step so the
    parser always sees at least one separator. For example, configure
    your upstream formatter to return `value + ","` instead of `value`,
    or in a JS formatter:

      survivors.map(s => s.account_id).join(",") + (survivors.length ? "," : "")

    The downstream `list` becomes `[{value: "<single>"}]` as expected.
    The trailing comma does NOT produce a phantom empty row — Floqer
    drops the empty trailing token automatically.

  Remove this note when verified fixed in the action handler.

================================================================================
5. WHERE IT FITS IN A WORKFLOW
================================================================================

Pattern: llm_models (returns a CSV string) ->
csv_to_structured_array_format -> push_data_to_sheet.

================================================================================
6. WHEN TO USE
================================================================================

Use this action to convert a CSV string into a structured array, so
the values can be pushed into a new sheet as individual rows (one row
per CSV value) for downstream enrichment or processing.

================================================================================
7. WHEN NOT TO USE
================================================================================

Already have a JSON array
  -> raw_to_structured_array
     (https://floqer.com/docs/action-detail/raw_to_structured_array.txt)

Need free-form formatting
  -> format_data_using_js_expression
     (https://floqer.com/docs/action-detail/format_data_using_js_expression.txt)

================================================================================

This file is maintained manually. Last updated: 2026-05-11.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt