use ValidatedEvent type instead of defineEvent

[ianmacartney]

Support both, but point people more towards using a type, which is less surprising to spread, etc.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Summary by CodeRabbit

• Documentation

  • Updated guidance to recommend using shared object event definitions instead of the previous pattern.

• New Features

  • Added a workflow example showcasing an approval flow and conditional handling.

• Improvements

  • Introduced a reusable, validated event pattern and stronger typing for events to improve safety and reuse across workflows; updated event send/await usage accordingly.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The patch introduces a new exported ValidatedEvent type, relaxes defineEvent's validator generic, and replaces function-based defineEvent(...) usage with shared plain-object event declarations (using as const + satisfies ValidatedEvent) across README and example workflow code.

Changes

Cohort / File(s)	Summary
Type System & API Surface src/client/index.ts	Added exported ValidatedEvent<Name, V> type (name and validator). Relaxed defineEvent generic from Validator<..., "required", string> to Validator<..., "required", any>.
Documentation README.md	Replaced guidance and examples: instructs using a shared plain object event (as const + satisfies ValidatedEvent) instead of defineEvent(...); updated example usages to awaitEvent(approvalEvent) and spreading approvalEvent into sendEvent.
Example / Workflow example/convex/userConfirmation.ts	Replaced defineEvent(...) with exported const approvalEvent = { name: "approval" as const, validator: ... } satisfies ValidatedEvent;. Added/exported confirmationWorkflow via workflow.define(...). Adjusted import and the order of spreading ...approvalEvent in workflow.sendEvent payload (semantics unchanged).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hopped through types and fields today,
Swapped calls for objects along the way.
"satisfies" hugged my tiny event with care,
Validators snug, events shared everywhere.
A little rabbit cheers — typed and fair!

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: introducing a ValidatedEvent type as an alternative to defineEvent, which is the primary focus of the changeset across all modified files.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6c8d67c and b3de97a.

📒 Files selected for processing (3)

• README.md
• example/convex/userConfirmation.ts
• src/client/index.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/client/index.ts

🧰 Additional context used

🧬 Code graph analysis (1)

example/convex/userConfirmation.ts (1)

src/client/index.ts (1)

• ValidatedEvent (354-364)

🔇 Additional comments (4)

README.md (1)

470-477: LGTM! Clear documentation of the new event definition pattern.

The transition from defineEvent to a plain object with satisfies ValidatedEvent is well-documented. The use of as const for the name ensures a literal type, and the satisfies operator provides type checking without type widening. This pattern is indeed "less surprising to spread" as mentioned in the PR objectives, since the structure is explicit and visible.

example/convex/userConfirmation.ts (3)

1-5: LGTM! Import correctly updated to use ValidatedEvent type.

The import change from defineEvent (function) to ValidatedEvent (type) is consistent with the new event definition pattern using satisfies.

---

10-16: LGTM! Well-structured event definition with proper type constraints.

The approvalEvent definition correctly implements the new pattern:

• as const on the name ensures a literal type for better type inference
• The union validator provides discriminated union type safety (approved: true requires choice, approved: false requires reason)
• satisfies ValidatedEvent ensures type correctness without widening the type

This is a good example of a more complex validator compared to the simplified README example.

---

49-59: LGTM! Correct usage of the new event definition pattern.

The sendEvent call correctly spreads approvalEvent to include the name and validator properties. The explicit value field properly matches one branch of the discriminated union (approved: true with choice: number).

The property spread order is fine since there are no overlapping keys between the explicit properties and the spread.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/get-convex/workflow/@convex-dev/workflow@181

commit: b3de97a

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

README.md (1)

490-490: Minor typo: "event" should be "name".

The note mentions { event, validator } but the actual type fields are { name, validator }.

🔎 Suggested fix

-Note: this is just a convenience to create a typed { event, validator } pair.
+Note: this is just a convenience to create a typed { name, validator } pair.

🧹 Nitpick comments (1)

example/convex/userConfirmation.ts (1)

52-56: Consider consistent spread order with README example.

The README shows { ...approvalEvent, workflowId, value } while this code uses { workflowId, value, ...approvalEvent }. While functionally equivalent (no property conflicts), matching the README pattern improves consistency.

🔎 Optional: Align with README pattern

     await workflow.sendEvent(ctx, {
+      ...approvalEvent,
       workflowId: args.workflowId,
       value: { approved: true, choice: args.choice },
-      ...approvalEvent,
     });

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b1aaaba and 6c8d67c.

📒 Files selected for processing (3)

• README.md (1 hunks)
• example/convex/userConfirmation.ts (2 hunks)
• src/client/index.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

example/convex/userConfirmation.ts (1)

src/client/index.ts (1)

• ValidatedEvent (354-364)

🔇 Additional comments (5)

src/client/index.ts (2)

347-352: LGTM! The defineEvent function is preserved for backward compatibility.

The generic parameter change from Validator<unknown, "required", string> to Validator<unknown, "required", any> broadens compatibility with various validator configurations.

---

354-364: Clean type definition that enables the object literal pattern.

The ValidatedEvent type with sensible defaults allows users to define events as plain objects with satisfies ValidatedEvent, making them easier to spread in sendEvent calls compared to the function-based defineEvent approach.

README.md (1)

470-485: Clear documentation of the new pattern.

The example effectively demonstrates the recommended approach using satisfies ValidatedEvent with as const for proper type narrowing on the event name.

example/convex/userConfirmation.ts (2)

10-16: Good migration to the ValidatedEvent pattern.

The as const assertion on name is essential for preserving the literal type "approval", enabling proper type inference when the event is used in awaitEvent and sendEvent.

---

20-39: Well-structured workflow example.

The workflow demonstrates the complete approval flow pattern with proper type annotations and error handling for both approved and rejected cases.