Skip to content
nexus-dialogs
GitHub npm

Contracts

What each public function returns and why. The signatures are pinned by the compiler (test/tipos/contratos.ts): if what a function returns changes, npm run typecheck fails and the change must be announced as a "breaking change" (see limitations and versions).

#The rule: three families

1. Dialogs → DialogResult<T>. Everything that opens a "full" dialog (alerts, confirmations, prompt, forms, wizards, tables, import) always resolves with the same object and never rejects:

{ confirmed: boolean, denied: boolean, value: T | undefined, reason: CloseReason }

It reads the same everywhere: if (r.confirmed) use(r.value). reason says how it was closed (confirm, cancel, escape, backdrop, deny, timer, program or the id of a custom button).

2. Recipes (nexus-dialogs/patterns) → the value you need, without a wrapper. These are one-line decisions, so they return the answer directly:

FunctionReturns
confirmDeleteboolean (true = delete)
choosethe chosen value, or null if cancelled
unsavedChanges'save', 'discard' or 'keep'
sessionTimeout'extend', 'logout' or 'expired'
loadingwhatever your task returns (propagates its error)

3. Recipes with a structured result → their own documented object. When the answer has several parts:

FunctionReturns
approval{ decision: 'approved' | 'rejected' | 'info' | 'cancelled', comment, reason? }
bulkAction{ confirmed, done[], failed[{ item, error }], skipped[{ item, … }] }

#Why not everything is a DialogResult

A recipe like confirmDelete exists so you can write if (await confirmDelete(...)) remove(). Forcing you to read .confirmed in each of the 30 screens of a system adds nothing. When you need more detail (why it was closed, what value it had), use the base dialog (dialog.confirm, form), which always returns DialogResult.

#Other conventions