rivetkit 2.0.42 → 2.1.0-rc.1

package/src/actor/contexts/create-conn-state.ts

@@ -1,5 +1,6 @@
 import type { AnyDatabaseProvider } from "../database";
 import type { ActorDefinition, AnyActorDefinition } from "../definition";
+import type { EventSchemaConfig, QueueSchemaConfig } from "../schema";
 import { ConnInitContext } from "./base/conn-init";
 
 /**
@@ -11,7 +12,9 @@ export class CreateConnStateContext<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
-> extends ConnInitContext<TState, TVars, TInput, TDatabase> {}
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
+> extends ConnInitContext<TState, TVars, TInput, TDatabase, TEvents, TQueues> {}
 
 export type CreateConnStateContextOf<AD extends AnyActorDefinition> =
 	AD extends ActorDefinition<
@@ -21,7 +24,9 @@ export type CreateConnStateContextOf<AD extends AnyActorDefinition> =
 		infer V,
 		infer I,
 		infer DB extends AnyDatabaseProvider,
+		infer E extends EventSchemaConfig,
+		infer Q extends QueueSchemaConfig,
 		any
 	>
-		? CreateConnStateContext<S, V, I, DB>
+		? CreateConnStateContext<S, V, I, DB, E, Q>
 		: never;

package/src/actor/contexts/create-vars.ts

@@ -1,5 +1,6 @@
 import type { AnyDatabaseProvider } from "../database";
 import type { ActorDefinition, AnyActorDefinition } from "../definition";
+import type { EventSchemaConfig, QueueSchemaConfig } from "../schema";
 import { ActorContext } from "./base/actor";
 
 /**
@@ -9,8 +10,18 @@ export class CreateVarsContext<
 	TState,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
-> extends ActorContext<TState, never, never, never, TInput, TDatabase> {}
-
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
+> extends ActorContext<
+	TState,
+	never,
+	never,
+	never,
+	TInput,
+	TDatabase,
+	TEvents,
+	TQueues
+> {}
 
 export type CreateVarsContextOf<AD extends AnyActorDefinition> =
 	AD extends ActorDefinition<
@@ -20,7 +31,9 @@ export type CreateVarsContextOf<AD extends AnyActorDefinition> =
 		any,
 		infer I,
 		infer DB extends AnyDatabaseProvider,
+		infer E extends EventSchemaConfig,
+		infer Q extends QueueSchemaConfig,
 		any
 	>
-		? CreateVarsContext<S, I, DB>
+		? CreateVarsContext<S, I, DB, E, Q>
 		: never;

package/src/actor/contexts/create.ts

@@ -1,5 +1,6 @@
 import type { AnyDatabaseProvider } from "../database";
 import type { ActorDefinition, AnyActorDefinition } from "../definition";
+import type { EventSchemaConfig, QueueSchemaConfig } from "../schema";
 import { ActorContext } from "./base/actor";
 
 /**
@@ -9,8 +10,18 @@ export class CreateContext<
 	TState,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
-> extends ActorContext<TState, never, never, never, TInput, TDatabase> {}
-
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
+> extends ActorContext<
+	TState,
+	never,
+	never,
+	never,
+	TInput,
+	TDatabase,
+	TEvents,
+	TQueues
+> {}
 
 export type CreateContextOf<AD extends AnyActorDefinition> =
 	AD extends ActorDefinition<
@@ -20,7 +31,9 @@ export type CreateContextOf<AD extends AnyActorDefinition> =
 		any,
 		infer I,
 		infer DB extends AnyDatabaseProvider,
+		infer E extends EventSchemaConfig,
+		infer Q extends QueueSchemaConfig,
 		any
 	>
-		? CreateContext<S, I, DB>
+		? CreateContext<S, I, DB, E, Q>
 		: never;

package/src/actor/contexts/destroy.ts

@@ -1,5 +1,6 @@
 import type { AnyDatabaseProvider } from "../database";
 import type { ActorDefinition, AnyActorDefinition } from "../definition";
+import type { EventSchemaConfig, QueueSchemaConfig } from "../schema";
 import { ActorContext } from "./base/actor";
 
 /**
@@ -12,16 +13,19 @@ export class DestroyContext<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
 > extends ActorContext<
 	TState,
 	TConnParams,
 	TConnState,
 	TVars,
 	TInput,
-	TDatabase
+	TDatabase,
+	TEvents,
+	TQueues
 > {}
 
-
 export type DestroyContextOf<AD extends AnyActorDefinition> =
 	AD extends ActorDefinition<
 		infer S,
@@ -30,7 +34,9 @@ export type DestroyContextOf<AD extends AnyActorDefinition> =
 		infer V,
 		infer I,
 		infer DB extends AnyDatabaseProvider,
+		infer E extends EventSchemaConfig,
+		infer Q extends QueueSchemaConfig,
 		any
 	>
-		? DestroyContext<S, CP, CS, V, I, DB>
+		? DestroyContext<S, CP, CS, V, I, DB, E, Q>
 		: never;

package/src/actor/contexts/disconnect.ts

@@ -1,6 +1,7 @@
 import type { Conn } from "../conn/mod";
-import type { ActorDefinition, AnyActorDefinition } from "../definition";
 import type { AnyDatabaseProvider } from "../database";
+import type { ActorDefinition, AnyActorDefinition } from "../definition";
+import type { EventSchemaConfig, QueueSchemaConfig } from "../schema";
 import { ActorContext } from "./base/actor";
 
 /**
@@ -13,16 +14,19 @@ export class DisconnectContext<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
 > extends ActorContext<
 	TState,
 	TConnParams,
 	TConnState,
 	TVars,
 	TInput,
-	TDatabase
+	TDatabase,
+	TEvents,
+	TQueues
 > {}
 
-
 export type DisconnectContextOf<AD extends AnyActorDefinition> =
 	AD extends ActorDefinition<
 		infer S,
@@ -31,7 +35,9 @@ export type DisconnectContextOf<AD extends AnyActorDefinition> =
 		infer V,
 		infer I,
 		infer DB extends AnyDatabaseProvider,
+		infer E extends EventSchemaConfig,
+		infer Q extends QueueSchemaConfig,
 		any
 	>
-		? DisconnectContext<S, CP, CS, V, I, DB>
+		? DisconnectContext<S, CP, CS, V, I, DB, E, Q>
 		: never;

package/src/actor/contexts/index.ts

@@ -1,10 +1,10 @@
 // Base contexts
-export { ActorContext, type ActorContextOf } from "./base/actor";
-export { ConnContext, type ConnContextOf } from "./base/conn";
-export { ConnInitContext, type ConnInitContextOf } from "./base/conn-init";
 
 // Lifecycle contexts
 export { ActionContext, type ActionContextOf } from "./action";
+export { ActorContext, type ActorContextOf } from "./base/actor";
+export { ConnContext, type ConnContextOf } from "./base/conn";
+export { ConnInitContext, type ConnInitContextOf } from "./base/conn-init";
 export {
 	BeforeActionResponseContext,
 	type BeforeActionResponseContextOf,
@@ -23,6 +23,7 @@ export { CreateVarsContext, type CreateVarsContextOf } from "./create-vars";
 export { DestroyContext, type DestroyContextOf } from "./destroy";
 export { DisconnectContext, type DisconnectContextOf } from "./disconnect";
 export { RequestContext, type RequestContextOf } from "./request";
+export { RunContext, type RunContextOf } from "./run";
 export { SleepContext, type SleepContextOf } from "./sleep";
 export {
 	StateChangeContext,

package/src/actor/contexts/request.ts

@@ -1,7 +1,8 @@
 import type { Conn } from "../conn/mod";
-import type { ActorDefinition, AnyActorDefinition } from "../definition";
 import type { AnyDatabaseProvider } from "../database";
+import type { ActorDefinition, AnyActorDefinition } from "../definition";
 import type { ActorInstance } from "../instance/mod";
+import type { EventSchemaConfig, QueueSchemaConfig } from "../schema";
 import { ConnContext } from "./base/conn";
 
 /**
@@ -14,13 +15,17 @@ export class RequestContext<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
 > extends ConnContext<
 	TState,
 	TConnParams,
 	TConnState,
 	TVars,
 	TInput,
-	TDatabase
+	TDatabase,
+	TEvents,
+	TQueues
 > {
 	/**
 	 * The incoming HTTP request.
@@ -38,9 +43,20 @@ export class RequestContext<
 			TConnState,
 			TVars,
 			TInput,
-			TDatabase
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+		conn: Conn<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
 		>,
-		conn: Conn<TState, TConnParams, TConnState, TVars, TInput, TDatabase>,
 		request?: Request,
 	) {
 		super(actor, conn);
@@ -48,7 +64,6 @@ export class RequestContext<
 	}
 }
 
-
 export type RequestContextOf<AD extends AnyActorDefinition> =
 	AD extends ActorDefinition<
 		infer S,
@@ -57,7 +72,9 @@ export type RequestContextOf<AD extends AnyActorDefinition> =
 		infer V,
 		infer I,
 		infer DB extends AnyDatabaseProvider,
+		infer E extends EventSchemaConfig,
+		infer Q extends QueueSchemaConfig,
 		any
 	>
-		? RequestContext<S, CP, CS, V, I, DB>
+		? RequestContext<S, CP, CS, V, I, DB, E, Q>
 		: never;

package/src/actor/contexts/run.ts

@@ -0,0 +1,47 @@
+import type { AnyDatabaseProvider } from "../database";
+import type { ActorDefinition, AnyActorDefinition } from "../definition";
+import type { EventSchemaConfig, QueueSchemaConfig } from "../schema";
+import { ActorContext } from "./base/actor";
+
+/**
+ * Context for the run lifecycle hook.
+ *
+ * This context is passed to the `run` handler which executes after the actor
+ * starts. It does not block actor startup and is intended for background tasks.
+ *
+ * Use `c.aborted` to detect when the actor is stopping and gracefully exit.
+ */
+export class RunContext<
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
+> extends ActorContext<
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase,
+	TEvents,
+	TQueues
+> {}
+
+export type RunContextOf<AD extends AnyActorDefinition> =
+	AD extends ActorDefinition<
+		infer S,
+		infer CP,
+		infer CS,
+		infer V,
+		infer I,
+		infer DB extends AnyDatabaseProvider,
+		infer E extends EventSchemaConfig,
+		infer Q extends QueueSchemaConfig,
+		any
+	>
+		? RunContext<S, CP, CS, V, I, DB, E, Q>
+		: never;

package/src/actor/contexts/sleep.ts

@@ -1,5 +1,6 @@
 import type { AnyDatabaseProvider } from "../database";
 import type { ActorDefinition, AnyActorDefinition } from "../definition";
+import type { EventSchemaConfig, QueueSchemaConfig } from "../schema";
 import { ActorContext } from "./base/actor";
 
 /**
@@ -12,16 +13,19 @@ export class SleepContext<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
 > extends ActorContext<
 	TState,
 	TConnParams,
 	TConnState,
 	TVars,
 	TInput,
-	TDatabase
+	TDatabase,
+	TEvents,
+	TQueues
 > {}
 
-
 export type SleepContextOf<AD extends AnyActorDefinition> =
 	AD extends ActorDefinition<
 		infer S,
@@ -30,7 +34,9 @@ export type SleepContextOf<AD extends AnyActorDefinition> =
 		infer V,
 		infer I,
 		infer DB extends AnyDatabaseProvider,
+		infer E extends EventSchemaConfig,
+		infer Q extends QueueSchemaConfig,
 		any
 	>
-		? SleepContext<S, CP, CS, V, I, DB>
+		? SleepContext<S, CP, CS, V, I, DB, E, Q>
 		: never;

package/src/actor/contexts/state-change.ts

@@ -1,5 +1,6 @@
 import type { AnyDatabaseProvider } from "../database";
 import type { ActorDefinition, AnyActorDefinition } from "../definition";
+import type { EventSchemaConfig, QueueSchemaConfig } from "../schema";
 import { ActorContext } from "./base/actor";
 
 /**
@@ -12,16 +13,19 @@ export class StateChangeContext<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
 > extends ActorContext<
 	TState,
 	TConnParams,
 	TConnState,
 	TVars,
 	TInput,
-	TDatabase
+	TDatabase,
+	TEvents,
+	TQueues
 > {}
 
-
 export type StateChangeContextOf<AD extends AnyActorDefinition> =
 	AD extends ActorDefinition<
 		infer S,
@@ -30,7 +34,9 @@ export type StateChangeContextOf<AD extends AnyActorDefinition> =
 		infer V,
 		infer I,
 		infer DB extends AnyDatabaseProvider,
+		infer E extends EventSchemaConfig,
+		infer Q extends QueueSchemaConfig,
 		any
 	>
-		? StateChangeContext<S, CP, CS, V, I, DB>
+		? StateChangeContext<S, CP, CS, V, I, DB, E, Q>
 		: never;

package/src/actor/contexts/wake.ts

@@ -1,5 +1,6 @@
 import type { AnyDatabaseProvider } from "../database";
 import type { ActorDefinition, AnyActorDefinition } from "../definition";
+import type { EventSchemaConfig, QueueSchemaConfig } from "../schema";
 import { ActorContext } from "./base/actor";
 
 /**
@@ -12,16 +13,19 @@ export class WakeContext<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
 > extends ActorContext<
 	TState,
 	TConnParams,
 	TConnState,
 	TVars,
 	TInput,
-	TDatabase
+	TDatabase,
+	TEvents,
+	TQueues
 > {}
 
-
 export type WakeContextOf<AD extends AnyActorDefinition> =
 	AD extends ActorDefinition<
 		infer S,
@@ -30,7 +34,9 @@ export type WakeContextOf<AD extends AnyActorDefinition> =
 		infer V,
 		infer I,
 		infer DB extends AnyDatabaseProvider,
+		infer E extends EventSchemaConfig,
+		infer Q extends QueueSchemaConfig,
 		any
 	>
-		? WakeContext<S, CP, CS, V, I, DB>
+		? WakeContext<S, CP, CS, V, I, DB, E, Q>
 		: never;

package/src/actor/contexts/websocket.ts

@@ -1,7 +1,8 @@
 import type { Conn } from "../conn/mod";
-import type { ActorDefinition, AnyActorDefinition } from "../definition";
 import type { AnyDatabaseProvider } from "../database";
+import type { ActorDefinition, AnyActorDefinition } from "../definition";
 import type { ActorInstance } from "../instance/mod";
+import type { EventSchemaConfig, QueueSchemaConfig } from "../schema";
 import { ConnContext } from "./base/conn";
 
 /**
@@ -14,13 +15,17 @@ export class WebSocketContext<
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
 > extends ConnContext<
 	TState,
 	TConnParams,
 	TConnState,
 	TVars,
 	TInput,
-	TDatabase
+	TDatabase,
+	TEvents,
+	TQueues
 > {
 	/**
 	 * The incoming HTTP request that initiated the WebSocket upgrade.
@@ -38,9 +43,20 @@ export class WebSocketContext<
 			TConnState,
 			TVars,
 			TInput,
-			TDatabase
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+		conn: Conn<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
 		>,
-		conn: Conn<TState, TConnParams, TConnState, TVars, TInput, TDatabase>,
 		request?: Request,
 	) {
 		super(actor, conn);
@@ -48,7 +64,6 @@ export class WebSocketContext<
 	}
 }
 
-
 export type WebSocketContextOf<AD extends AnyActorDefinition> =
 	AD extends ActorDefinition<
 		infer S,
@@ -57,7 +72,9 @@ export type WebSocketContextOf<AD extends AnyActorDefinition> =
 		infer V,
 		infer I,
 		infer DB extends AnyDatabaseProvider,
+		infer E extends EventSchemaConfig,
+		infer Q extends QueueSchemaConfig,
 		any
 	>
-		? WebSocketContext<S, CP, CS, V, I, DB>
+		? WebSocketContext<S, CP, CS, V, I, DB, E, Q>
 		: never;

package/src/actor/database.ts

@@ -1,23 +1,13 @@
+import type {
+	AnyDatabaseProvider,
+	DatabaseProvider,
+	RawDatabaseClient,
+	DrizzleDatabaseClient,
+} from "@/db/config";
+
 export type InferDatabaseClient<DBProvider extends AnyDatabaseProvider> =
 	DBProvider extends DatabaseProvider<any>
 		? Awaited<ReturnType<DBProvider["createClient"]>>
 		: never;
 
-export type AnyDatabaseProvider = DatabaseProvider<any> | undefined;
-
-export type DatabaseProvider<DB extends { execute: (query: string) => any }> = {
-	/**
-	 * Creates a new database client for the actor.
-	 * The result is passed to the actor context as `c.db`.
-	 * @experimental
-	 */
-	createClient: (ctx: {
-		getDatabase: () => Promise<string | unknown>;
-	}) => Promise<DB>;
-	/**
-	 * Runs before the actor has started.
-	 * Use this to run migrations or other setup tasks.
-	 * @experimental
-	 */
-	onMigrate: (client: DB) => void | Promise<void>;
-};
+export type { AnyDatabaseProvider, DatabaseProvider, RawDatabaseClient, DrizzleDatabaseClient };

package/src/actor/definition.ts

@@ -1,9 +1,10 @@
 import type { RegistryConfig } from "@/registry/config";
+import { DeepMutable } from "@/utils";
 import type { Actions, ActorConfig } from "./config";
 import type { ActionContextOf, ActorContext } from "./contexts";
 import type { AnyDatabaseProvider } from "./database";
 import { ActorInstance } from "./instance/mod";
-import { DeepMutable } from "@/utils";
+import type { EventSchemaConfig, QueueSchemaConfig } from "./schema";
 
 export type AnyActorDefinition = ActorDefinition<
 	any,
@@ -12,6 +13,8 @@ export type AnyActorDefinition = ActorDefinition<
 	any,
 	any,
 	any,
+	any,
+	any,
 	any
 >;
 
@@ -22,19 +25,30 @@ export class ActorDefinition<
 	V,
 	I,
 	DB extends AnyDatabaseProvider,
-	R extends Actions<S, CP, CS, V, I, DB>,
+	E extends EventSchemaConfig = Record<never, never>,
+	Q extends QueueSchemaConfig = Record<never, never>,
+	R extends Actions<S, CP, CS, V, I, DB, E, Q> = Actions<
+		S,
+		CP,
+		CS,
+		V,
+		I,
+		DB,
+		E,
+		Q
+	>,
 > {
-	#config: ActorConfig<S, CP, CS, V, I, DB>;
+	#config: ActorConfig<S, CP, CS, V, I, DB, E, Q>;
 
-	constructor(config: ActorConfig<S, CP, CS, V, I, DB>) {
+	constructor(config: ActorConfig<S, CP, CS, V, I, DB, E, Q>) {
 		this.#config = config;
 	}
 
-	get config(): ActorConfig<S, CP, CS, V, I, DB> {
+	get config(): ActorConfig<S, CP, CS, V, I, DB, E, Q> {
 		return this.#config;
 	}
 
-	instantiate(): ActorInstance<S, CP, CS, V, I, DB> {
+	instantiate(): ActorInstance<S, CP, CS, V, I, DB, E, Q> {
 		return new ActorInstance(this.#config);
 	}
 }

package/src/actor/driver.ts

@@ -3,7 +3,12 @@ import type { AnyClient } from "@/client/client";
 import type { ManagerDriver } from "@/manager/driver";
 import { type AnyConn } from "./conn/mod";
 import type { AnyActorInstance } from "./instance/mod";
-import { RegistryConfig } from "@/registry/config";
+import type { RegistryConfig } from "@/registry/config";
+import type {
+	RawDatabaseClient,
+} from "@/db/config";
+import type { SqliteVfs } from "@rivetkit/sqlite-vfs";
+import { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
 
 export type ActorDriverBuilder = (
 	config: RegistryConfig,
@@ -46,10 +51,34 @@ export interface ActorDriver {
 
 	// Database
 	/**
+	 * Override the default raw database client for the actor.
+	 * If not provided, rivetkit will construct a KV-backed SQLite client.
 	 * @experimental
-	 * This is an experimental API that may change in the future.
 	 */
-	getDatabase(actorId: string): Promise<unknown | undefined>;
+	overrideRawDatabaseClient?(
+		actorId: string,
+	): Promise<RawDatabaseClient | undefined>;
+
+	/**
+	 * Override the default Drizzle database client for the actor.
+	 * If not provided, rivetkit will construct a KV-backed Drizzle client.
+	 * @experimental
+	 */
+	overrideDrizzleDatabaseClient?(
+		actorId: string,
+	): Promise<BaseSQLiteDatabase<any,any,any,any> | undefined>;
+
+	/**
+	 * Creates a SQLite VFS instance for creating KV-backed databases.
+	 * If not provided, the database provider will need an override.
+	 *
+	 * @rivetkit/sqlite's async build is not re-entrant per module instance. Drivers
+	 * should return a new instance per call for actor-level isolation.
+	 *
+	 * This is a method (not a property) so drivers can use dynamic imports,
+	 * keeping the core driver tree-shakeable from @rivetkit/sqlite.
+	 */
+	createSqliteVfs?(): SqliteVfs | Promise<SqliteVfs>;
 
 	/**
 	 * Requests the actor to go to sleep.