​

Ziva Best Practices

​

Architecture & code organisation

• Keep task creation in factories/helpers so queues stay readable.
• Group tasks by stage and spin up separate queues for each stage (collect → validate → apply). This makes testing and reuse easier.
• Store references to tasks whose values you need after queue.Run(); their state persists.
• Call ziva.AutoConfigure() plus language setup (SetDefaultLanguage, SetLanguage) in main() before you start creating queues.

​

Queue management

• Enable numbering via WithTasksNumbered(true, "[%02d]") for long scenarios; operators orient themselves faster.
• Disable the final summary (WithOutSummary()) when you already log results elsewhere. Otherwise, add WithSummaryFunction to show key metrics inline.
• Always provide WithTimeout*() defaults for headless runs (CI, SSH). Pick a fallback that is safe for the workflow.
• For dynamic flows, assemble a new Queue, push the generated tasks, and run it after the primary queue.

​

Validation & input

• Keep Description() messages user-friendly — Ziva renders them under the field.
• Mix built-in validators from DefaultValidators with custom types. Compose them for complex rules and cover them with tests.
• Combine WithAllowEmpty(true) with validators that tolerate empty strings (for example OptionalEmail).
• Add a FuncTask right after the input when you need a network check (duplicate email in CRM, external API) and show the outcome to the operator.

​

Styling & localisation

• Customise error colours with ziva.SetErrorColor to match brand requirements; call ResetErrorColors() after experiments.
• On constrained terminals combine EnableEmbeddedMode() and EnableASCIIMode() so the output stays legible.

​

Performance & embedded targets

• Limit completed-task history with the ZIVA_MAX_COMPLETED_TASKS environment variable.
• Monitor memory via ZIVA_MEMORY_PRESSURE_THRESHOLD and periodically purge the string intern cache using ziva.ClearInternCache() for long-lived CLIs.
• Use WithViewport(...) for large lists — it keeps the UI responsive and prevents long jumps.
• Split heavy work into smaller FuncTask steps so users see progress more often.

​

Testing & debugging

• Unit-test task factories: create the task, simulate messages via Update, and verify the final state/result.
• Maintain demo queues under examples/ and run them manually. Capture screenshots/GIFs by disabling WithClearScreen(true) when recording.
• Log critical failures outside of Ziva (e.g. log/zap), especially when queues halt due to WithStopOnError(true).

​

Release-ready checklist

• Timeouts and default values reviewed.
• Tasks grouped by stage; layout fits the target terminal width.
• Validation covers negative cases; complex rules are tested.
• Colour scheme and localisation conform to product requirements.
• Embedded devices verified with AutoConfigure() and embedded mode.