feat(rivetkit): add actor run handler

Author: NathanFlurry

rivetkit-typescript/packages/rivetkit/src/actor/config.ts

@@ -50,6 +50,7 @@ export const ActorConfigSchema = z
 	.object({
 		onCreate: zFunction().optional(),
 		onDestroy: zFunction().optional(),
+		run: zFunction().optional(),
 		onWake: zFunction().optional(),
 		onSleep: zFunction().optional(),
 		onStateChange: zFunction().optional(),
@@ -130,6 +131,13 @@ export const ActorConfigSchema = z
 			message: "Cannot define both 'vars' and 'createVars'",
 			path: ["vars"],
 		},
+	)
+	.refine(
+		(data) => !(data.run !== undefined && data.onWake !== undefined),
+		{
+			message: "Cannot define both 'run' and 'onWake'. 'run' is an alias for 'onWake'.",
+			path: ["run"],
+		},
 	);
 
 // Creates state config
@@ -279,6 +287,24 @@ interface BaseActorConfig<
 		>,
 	) => void | Promise<void>;
 
+	/**
+	 * Called when the actor is started and ready to receive connections and actions.
+	 *
+	 * This is an alias for `onWake`. Use either `run` or `onWake`, but not both.
+	 *
+	 * @returns Void or a Promise that resolves when startup is complete
+	 */
+	run?: (
+		c: WakeContext<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase
+		>,
+	) => void | Promise<void>;
+
 	/**
 	 * Called when the actor is started and ready to receive connections and action.
 	 *
@@ -497,6 +523,7 @@ export type ActorConfig<
 	| "actions"
 	| "onCreate"
 	| "onDestroy"
+	| "run"
 	| "onWake"
 	| "onStateChange"
 	| "onBeforeConnect"
@@ -557,6 +584,7 @@ export type ActorConfigInput<
 	| "actions"
 	| "onCreate"
 	| "onDestroy"
+	| "run"
 	| "onWake"
 	| "onSleep"
 	| "onStateChange"

rivetkit-typescript/packages/rivetkit/src/actor/instance/mod.ts

@@ -852,8 +852,10 @@ export class ActorInstance<S, CP, CS, V, I, DB extends AnyDatabaseProvider> {
 
 	async #callOnStart() {
 		this.#rLog.info({ msg: "actor starting" });
-		if (this.#config.onWake) {
-			const result = this.#config.onWake(this.actorContext);
+		// `run` is an alias for `onWake`
+		const onWakeHandler = this.#config.run ?? this.#config.onWake;
+		if (onWakeHandler) {
+			const result = onWakeHandler(this.actorContext);
 			if (result instanceof Promise) {
 				await result;
 			}

website/src/content/docs/actors/lifecycle.mdx

@@ -11,7 +11,7 @@ Actors transition through several states during their lifetime. Each transition
 1. `createState`
 2. `onCreate`
 3. `createVars`
-4. `onWake`
+4. `run`
 
 **On Destroy**
 
@@ -20,7 +20,7 @@ Actors transition through several states during their lifetime. Each transition
 **On Wake** (after sleep, restart, or crash)
 
 1. `createVars`
-2. `onWake`
+2. `run`
 
 **On Sleep** (after idle period)
 
@@ -145,7 +145,7 @@ const gameSession = actor({
 });
 ```
 
-### `onWake`
+### `run`
 
 [API Reference](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html)
 
@@ -162,7 +162,7 @@ const counter = actor({
   state: { count: 0 },
   vars: { intervalId: null as NodeJS.Timeout | null },
 
-  onWake: (c) => {
+  run: (c) => {
     console.log('Actor started with count:', c.state.count);
 
     // Set up interval for automatic counting
@@ -187,6 +187,10 @@ const counter = actor({
 });
 ```
 
+### `onWake`
+
+`onWake` is an alias for [`run`](#run). Use either `run` or `onWake`, but not both.
+
 ### `onSleep`
 
 [API Reference](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html)
@@ -204,7 +208,7 @@ const counter = actor({
   state: { count: 0 },
   vars: { intervalId: null as NodeJS.Timeout | null },
 
-  onWake: (c) => {
+  run: (c) => {
     // Set up interval when actor wakes
     c.vars.intervalId = setInterval(() => {
       c.state.count++;
@@ -649,9 +653,9 @@ import { actor, ActorContextOf } from "rivetkit";
 
 const myActor = actor({
   state: { count: 0 },
-  
+
   // Use external function in lifecycle hook
-  onWake: (c) => logActorStarted(c)
+  run: (c) => logActorStarted(c)
 });
 
 // Simple external function with typed context
@@ -716,7 +720,7 @@ const counter = actor({
   },
 
   // Lifecycle hooks
-  onWake: (c) => {
+  run: (c) => {
     console.log(`Counter "${c.state.name}" started with count:`, c.state.count);
   },