feat: make flowInput lazy-loaded to prevent data duplication in map steps

[jumski]

Asymmetric Handler Signatures for Flow Composition

This PR implements asymmetric handler signatures to simplify flow composition and improve performance:

• Root steps now receive flow input directly: (flowInput, ctx) => ...
• Dependent steps receive only dependency outputs: (deps, ctx) => ...
• Flow input in dependent steps is now accessed via await ctx.flowInput (async/lazy-loaded)
• Lazy loading prevents data duplication for map steps processing large arrays
• Only root non-map steps receive flow_input from SQL to reduce data transfer
• Added FlowInputProvider class to handle caching and lazy loading of flow input
• Updated examples, tests, and documentation to reflect the new pattern

This change enables functional composition and simplifies types for future subflows by making handler signatures more intuitive and reducing unnecessary data duplication.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 878a4d1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes changesets to release 5 packages

Name	Type
@pgflow/core	Minor
@pgflow/dsl	Minor
@pgflow/client	Minor
@pgflow/edge-worker	Minor
pgflow	Minor

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[jumski]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• docs: add note about CONNECT_TIMEOUT fix using jsr:@oscar6echo/postgres fork #562
• fix: reject empty dependsOn arrays and improve flowInput access patterns #561
• feat: make flowInput lazy-loaded to prevent data duplication in map steps #560 👈 (View in Graphite)
• feat: asymmetric handler signatures for simpler flow composition #559
• refactor: simplify step input structure by removing run key and using context.flowInput #558
• refactor: rename input parameters to flowInput and deps for clarity #557
• refactor: change step handler input to use asymmetric pattern for better type safety #556
• feat: add flow_input to StepTaskRecord and context objects #555
• feat: add flow_input field to step_task_record for direct access to original input #554
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 878a4d1

Command	Status	Duration	Result
nx run edge-worker:test:integration	✅ Succeeded	3m 52s	View ↗
nx affected -t verify-exports --base=origin/mai...	✅ Succeeded	3s	View ↗
nx affected -t build --configuration=production...	✅ Succeeded	3s	View ↗
nx affected -t lint typecheck test --parallel -...	✅ Succeeded	2m 10s	View ↗
nx run cli:e2e	✅ Succeeded	4s	View ↗
nx run client:e2e	✅ Succeeded	1m 8s	View ↗
nx run edge-worker:e2e	✅ Succeeded	48s	View ↗
nx run core:pgtap	✅ Succeeded	<1s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-12-25 21:16:27 UTC

[github-actions]

🔍 Preview Deployment: Website

✅ Deployment successful!

🔗 Preview URL: https://pr-560.pgflow.pages.dev

📝 Details:

• Branch: 12-25-feat_lazy_load_ctx.flowinput_to_prevent_data_duplication_for_map_steps
• Commit: cc1eb824710278a574629de63a90c42f0d6ec461
• View Logs

_Last updated: _