chore(rivetkit): specialize context types for better compiler errors

[NathanFlurry]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
rivet-site	Ready	Preview, Comment	Jan 6, 2026 2:34am
rivetkit-serverless	Error		Jan 6, 2026 2:34am

2 Skipped Deployments

Project	Deployment	Review	Updated (UTC)
rivet-cloud	Ignored		Jan 6, 2026 2:34am
rivet-inspector	Ignored	Preview	Jan 6, 2026 2:34am

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(engine): return error for pending actors #3730 : 2 dependent PRs (#3675 , #3740 )
• chore(gas): add support for find_workflows #3739
• chore(docs): document abort signal #3673
• chore(rivetkit): clean up logging configuration #3672
• chore(rivetkit): RIVET_EXPOSE_ERRORS #3671
• chore(rivetkit): specialize context types for better compiler errors #3669 👈 (View in Graphite)
• fix(rivetkit): fix c.client not respecting correct origin #3668
• fix(rivetkit): allow providing no args to createRivetKit #3667
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: Specialize Context Types for Better Compiler Errors

This PR improves TypeScript developer experience by creating specialized context types for each lifecycle hook, replacing the generic ActorContext type. This provides better type checking and clearer error messages.

✅ Strengths

1. Excellent Type Safety Improvements

• Using never for unavailable generic parameters in specialized contexts (e.g., CreateContext<TState, never, never, never, TInput, TDatabase>) properly prevents access to properties that don't exist at that lifecycle stage
• Conditional return types in ActorContext getters (state, vars, db) now return never when not available, providing compile-time safety
• The *ContextOf utility types enable extracting context types from ActorDefinition, improving reusability

2. Well-Organized Structure

• Clear separation into base/ (ActorContext, ConnContext, ConnInitContext) and lifecycle-specific contexts
• Consolidated exports in contexts/index.ts improve discoverability
• Consistent naming pattern (CreateContext, DestroyContext, etc.) makes the API intuitive

3. Good Documentation

• JSDoc comments explain when properties are unavailable (e.g., "This property is not available in createState since the state hasn't been created yet")
• Appropriate use of @experimental tags

⚠️ Issues & Concerns

1. Type Casting Safety (base/actor.ts:50-62)

get state(): TState extends never ? never : TState {
    return this.#actor.state as TState extends never ? never : TState;
}

• The type cast is necessary but could mask runtime issues if #actor.state is actually undefined/null when TState is not never
• Recommendation: Consider adding runtime validation in development mode:

get state(): TState extends never ? never : TState {
    if (process.env.NODE_ENV === 'development') {
        if (this.#actor.state === undefined && /* TState is not never check */) {
            throw new Error('State accessed before initialization');
        }
    }
    return this.#actor.state as TState extends never ? never : TState;
}

2. Type Casting in Constructors (base/conn-init.ts:32)

super(actor as any);

• Using as any defeats TypeScript's type checking
• Recommendation: This appears necessary because ConnInitContext uses never for TConnParams and TConnState, but the ActorInstance has concrete types. Consider if there's a way to make this type-safe, or add a comment explaining why the cast is necessary:

// Cast needed because ConnInitContext specializes with never for TConnParams/TConnState
// while ActorInstance has concrete types
super(actor as any);

3. Trailing Whitespace
Several files have trailing blank lines that should be removed for consistency:

• create-vars.ts:14 (blank line before export)
• create.ts:14 (blank line before export)
• destroy.ts:24 (blank line before export)
• disconnect.ts:24 (blank line before export)
• request.ts:50 (blank line before export)
• sleep.ts:24 (blank line before export)
• state-change.ts:24 (blank line before export)
• wake.ts:24 (blank line before export)
• websocket.ts:50 (blank line before export)

4. Import Organization (config.ts:4-20)
The import list is long but well-organized. Good use of multi-line imports for clarity.

🔍 Potential Improvements

1. Consider Generic Constraint Helper Type
The AnyDatabaseProvider constraint is repeated many times. Consider a helper type:

type DatabaseConstraint = AnyDatabaseProvider;

This would make signatures more concise, though it might reduce clarity.

2. Test Coverage

• The diff shows minimal test changes (actor-types.test.ts)
• Recommendation: Add tests that verify:
  • Accessing state in CreateContext produces a TypeScript error
  • Accessing vars in CreateVarsContext produces a TypeScript error
  • The *ContextOf utility types correctly extract types from ActorDefinition

3. Documentation Migration
Great that documentation was updated in website/src/content/docs/actors/:

• helper-types.mdx reduced from 71 to 0 additions
• New types.mdx added with 77 lines
• Verify all code examples compile with the new types

🎯 Summary

This is a well-executed refactoring that significantly improves type safety and developer experience. The main concerns are:

1. Critical: Add comments explaining the as any casts
2. Medium: Consider adding runtime validation for state/vars/db access in development mode
3. Minor: Remove trailing whitespace for consistency
4. Nice-to-have: Add comprehensive type-checking tests

The architectural pattern is sound, and the benefits outweigh the minor issues. Once the as any casts are documented and trailing whitespace is cleaned up, this should be good to merge.

Action Items

• Add explanatory comments for as any casts
• Remove trailing blank lines in lifecycle context files
• Consider adding runtime validation guards (optional)
• Verify documentation examples compile (appears done)
• Add type-checking tests for the new context system (recommended)

---

Review generated by Claude Code

[graphite-app]

Merge activity

• Jan 6, 2:19 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Jan 6, 2:20 AM UTC: The Graphite merge queue removed this pull request due to downstack failures on PR #3667.
• Jan 6, 2:20 AM UTC: The Graphite merge queue removed this pull request due to downstack failures on PR #3667.
• Jan 6, 2:21 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Jan 6, 2:22 AM UTC: The Graphite merge queue removed this pull request due to downstack failures on PR #3667.
• Jan 6, 2:22 AM UTC: The Graphite merge queue removed this pull request due to downstack failures on PR #3667.
• Jan 6, 2:31 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Jan 6, 2:31 AM UTC: CI is running for this pull request on a draft pull request (#3754) due to your merge queue CI optimization settings.
• Jan 6, 2:32 AM UTC: Merged by the Graphite merge queue via draft PR: #3754.