fix: reject empty dependsOn arrays and improve flowInput access patterns

[jumski]

Prevent empty dependsOn arrays in Flow steps

This PR improves type safety by rejecting empty dependsOn: [] arrays at compile time. Empty dependency arrays are semantically meaningless (if a step has no dependencies, it should omit dependsOn entirely) and create a type mismatch between TypeScript and runtime behavior.

The changes:

1. Modified the Flow DSL type definitions to require at least one dependency in dependsOn arrays using the [Deps, ...Deps[]] syntax
2. Added type tests to verify that empty dependency arrays are rejected at compile time
3. Updated documentation to clarify that ctx.flowInput is lazy-loaded and should be awaited
4. Improved examples in documentation to show the proper pattern of const flowInput = await ctx.flowInput
5. Enhanced the array processing documentation to explain the performance implications of accessing flow input in map handlers

This change helps prevent a subtle bug where TypeScript would infer an empty object type for dependencies with dependsOn: [], but at runtime the step would receive the flow input instead.

[changeset-bot]

⚠️ No Changeset found

Latest commit: a086d35

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 no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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]

• docs: add note about CONNECT_TIMEOUT fix using jsr:@oscar6echo/postgres fork #562
• fix: reject empty dependsOn arrays and improve flowInput access patterns #561 👈 (View in Graphite)
• feat: make flowInput lazy-loaded to prevent data duplication in map steps #560
• 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 a086d35

Command	Status	Duration	Result
nx test:types:health dsl	✅ Succeeded	11s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-12-30 12:03:53 UTC

[github-actions]

🔍 Preview Deployment: Website

✅ Deployment successful!

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

📝 Details:

• Branch: 12-25-fix_various_pr_commends_from_runkey_stack
• Commit: 3fe287b272012784978d66d7a10904fc5cfb4ff8
• View Logs

_Last updated: _

[jumski]

Merge activity

• Dec 30, 11:24 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Dec 30, 12:02 PM UTC: Graphite rebased this pull request as part of a merge.
• Dec 30, 12:03 PM UTC: @jumski merged this pull request with Graphite.

[github-actions]

🚀 Production Deployment: Website

✅ Successfully deployed to production!

🔗 Production URL: https://pgflow.dev

📝 Details:

• Commit: a990bb4a03cfe7bf0ca232d618f704730c672176
• View Logs

Deployed at: 2025-12-30T13:03:26+01:00