WRNexusJS/docs/application-productivity.md

Application productivity kit

WrNexus applications should declare infrastructure once and keep only domain decisions locally.

Included foundations

1. HTTP routes: defineApiRoute, authorized, requireUser, requirePermission, requireParam, requireJson, and json.
2. CRUD resources: defineResource generates owned list/create/get/update/delete handlers.
3. Seed data: addSeedData, upsertSeedData, seedIfMissing, defineSeed, removeSeedData, and runSeedQuery.
4. Transactional delivery: withOutbox, drainOutbox, and installOutboxSchema.
5. Job state transitions: defineJobStateMachine.
6. SQLite/PostgreSQL/MySQL queue tables: configured storage plus databaseQueueStore.
7. Queue operations: success/failed hooks, dashboard handler and queue CLI.
8. Queue testing: testQueue with deterministic runNext/runAll.
9. Workflows and compensation: durable workflows and defineSaga.
10. Mail: defineMail, defineMailTemplate, sandbox allowlists and queuedMail.
11. Encrypted settings: defineSecretResource.
12. Ledgers: defineLedger with atomic debit and audit entries.
13. Forms: useForm for values, errors, dirty/submitting state, validation and submission.
14. Typed HTTP calls: createApiClient; generated OpenAPI/SDK clients remain available through wrnexus api generate.
15. Full-stack testing: createTestApp, database rollback/factories, and queue test controls.
16. Package migrations: queue/auth/authz packages contribute migrations through the plugin lifecycle.
17. Auth/OAuth: auth and authz plugins own routes, middleware, roles and provider lifecycle.
18. Code generation: wrnexus generate resource <name>.
19. Incremental features: wrnexus add queue|mail|seed|testing|resource.
20. Starter presets: wrnexus create app --preset=saas|email and --features=....

Recommended new-project flow

wrnexus create acme --preset=saas
cd acme && bun install
wrnexus generate resource projects
wrnexus add mail
wrnexus db migrate
wrnexus db seed
wrnexus dev

Use generated resources for ordinary owned CRUD. Use the outbox for business operations that change data and enqueue work together. Use sagas only when a workflow crosses systems that cannot share a transaction. Application code should retain product-specific policy; framework code owns storage, validation, lifecycle, retries, diagnostics and scaffolding.