fix: align helper data typings with runtime state

Author: azhukaudev

README.md

@@ -81,6 +81,9 @@ export class AppComponent {
 }
 ```
 
+`data()` is typed as `T | undefined`. Handle the initial/skipped state with
+`?.` or `??` until the first successful result arrives.
+
 ### Mutating data
 
 Use `injectMutation` to mutate the database.
@@ -104,6 +107,9 @@ export class AppComponent {
 }
 ```
 
+`data()` is typed as `T | undefined` and stays undefined until the first
+successful mutation result or after `reset()`.
+
 ### Running actions
 
 Use `injectAction` to run actions.
@@ -125,6 +131,9 @@ export class AppComponent {
 }
 ```
 
+`data()` is typed as `T | undefined` and stays undefined until the first
+successful action result or after `reset()`.
+
 ### Paginated queries
 
 Use `injectPaginatedQuery` for infinite scroll or "load more" patterns.

packages/convex-angular/README.md

@@ -81,6 +81,9 @@ export class AppComponent {
 }
 ```
 
+`data()` is typed as `T | undefined`. Handle the initial/skipped state with
+`?.` or `??` until the first successful result arrives.
+
 ### Mutating data
 
 Use `injectMutation` to mutate the database.
@@ -93,9 +96,7 @@ import { api } from '../convex/_generated/api';
 
 @Component({
   selector: 'app-root',
-  template: `
-    <button (click)="addTodoItem()">Add Todo</button>
-  `,
+  template: ` <button (click)="addTodoItem()">Add Todo</button> `,
 })
 export class AppComponent {
   readonly addTodo = injectMutation(api.todos.addTodo);
@@ -113,6 +114,9 @@ export class AppComponent {
 `mutate()` rejects on failure. `error()` and `status()` are still updated, and
 `onError` still runs before the promise rejects.
 
+`data()` is typed as `T | undefined` and stays undefined until the first
+successful mutation result or after `reset()`.
+
 ### Running actions
 
 Use `injectAction` to run actions.
@@ -143,6 +147,9 @@ export class AppComponent {
 `run()` rejects on failure. `error()` and `status()` are still updated, and
 `onError` still runs before the promise rejects.
 
+`data()` is typed as `T | undefined` and stays undefined until the first
+successful action result or after `reset()`.
+
 ### Paginated queries
 
 Use `injectPaginatedQuery` for infinite scroll or "load more" patterns.

packages/convex-angular/src/lib/providers/inject-action.spec.ts

@@ -6,6 +6,13 @@ import { FunctionReference } from 'convex/server';
 import { CONVEX } from '../tokens/convex';
 import { ActionReference, injectAction } from './inject-action';
 
+type Assert<T extends true> = T;
+type IsExact<T, Expected> = [T] extends [Expected]
+  ? [Expected] extends [T]
+    ? true
+    : false
+  : false;
+
 // Mock action function reference
 const mockAction = (() => {}) as unknown as FunctionReference<
   'action',
@@ -66,6 +73,29 @@ describe('injectAction', () => {
       expect(fixture.componentInstance.sendEmail.data()).toBeUndefined();
     });
 
+    it('should type data as action result or undefined', () => {
+      @Component({
+        template: '',
+        standalone: true,
+      })
+      class TestComponent {
+        readonly sendEmail = injectAction(mockAction);
+      }
+
+      const fixture = TestBed.createComponent(TestComponent);
+      fixture.detectChanges();
+
+      type ActionData = ReturnType<TestComponent['sendEmail']['data']>;
+      const assertActionDataType: Assert<
+        IsExact<ActionData, { success: boolean } | undefined>
+      > = true;
+
+      const typedData: ActionData = fixture.componentInstance.sendEmail.data();
+
+      expect(assertActionDataType).toBe(true);
+      expect(typedData).toBeUndefined();
+    });
+
     it('should initialize with no error', () => {
       @Component({
         template: '',

packages/convex-angular/src/lib/providers/inject-action.ts

@@ -48,7 +48,7 @@ export interface ActionResult<Action extends ActionReference> {
    * The data returned by the last successful action call.
    * Undefined until the action completes successfully.
    */
-  data: Signal<FunctionReturnType<Action>>;
+  data: Signal<FunctionReturnType<Action> | undefined>;
 
   /**
    * The error from the last failed action call.
@@ -128,7 +128,7 @@ export function injectAction<Action extends ActionReference>(
   );
 
   // Internal signals for tracking state
-  const data = signal<FunctionReturnType<Action>>(undefined);
+  const data = signal<FunctionReturnType<Action> | undefined>(undefined);
   const error = signal<Error | undefined>(undefined);
   const isLoading = signal(false);
   const currentVersion = signal(0);

packages/convex-angular/src/lib/providers/inject-mutation.spec.ts

@@ -6,6 +6,13 @@ import { FunctionReference } from 'convex/server';
 import { CONVEX } from '../tokens/convex';
 import { MutationReference, injectMutation } from './inject-mutation';
 
+type Assert<T extends true> = T;
+type IsExact<T, Expected> = [T] extends [Expected]
+  ? [Expected] extends [T]
+    ? true
+    : false
+  : false;
+
 // Mock mutation function reference
 const mockMutation = (() => {}) as unknown as FunctionReference<
   'mutation',
@@ -66,6 +73,29 @@ describe('injectMutation', () => {
       expect(fixture.componentInstance.addTodo.data()).toBeUndefined();
     });
 
+    it('should type data as mutation result or undefined', () => {
+      @Component({
+        template: '',
+        standalone: true,
+      })
+      class TestComponent {
+        readonly addTodo = injectMutation(mockMutation);
+      }
+
+      const fixture = TestBed.createComponent(TestComponent);
+      fixture.detectChanges();
+
+      type MutationData = ReturnType<TestComponent['addTodo']['data']>;
+      const assertMutationDataType: Assert<
+        IsExact<MutationData, { id: string } | undefined>
+      > = true;
+
+      const typedData: MutationData = fixture.componentInstance.addTodo.data();
+
+      expect(assertMutationDataType).toBe(true);
+      expect(typedData).toBeUndefined();
+    });
+
     it('should initialize with no error', () => {
       @Component({
         template: '',

packages/convex-angular/src/lib/providers/inject-mutation.ts

@@ -61,7 +61,7 @@ export interface MutationResult<Mutation extends MutationReference> {
    * The data returned by the last successful mutation call.
    * Undefined until the mutation completes successfully.
    */
-  data: Signal<FunctionReturnType<Mutation>>;
+  data: Signal<FunctionReturnType<Mutation> | undefined>;
 
   /**
    * The error from the last failed mutation call.
@@ -148,7 +148,7 @@ export function injectMutation<Mutation extends MutationReference>(
   );
 
   // Internal signals for tracking state
-  const data = signal<FunctionReturnType<Mutation>>(undefined);
+  const data = signal<FunctionReturnType<Mutation> | undefined>(undefined);
   const error = signal<Error | undefined>(undefined);
   const isLoading = signal(false);
   const currentVersion = signal(0);

packages/convex-angular/src/lib/providers/inject-query.spec.ts

@@ -12,6 +12,13 @@ import { skipToken } from '../skip-token';
 import { CONVEX } from '../tokens/convex';
 import { QueryReference, injectQuery } from './inject-query';
 
+type Assert<T extends true> = T;
+type IsExact<T, Expected> = [T] extends [Expected]
+  ? [Expected] extends [T]
+    ? true
+    : false
+  : false;
+
 // Mock getFunctionName to avoid needing a real FunctionReference
 jest.mock('convex/server', () => ({
   ...jest.requireActual('convex/server'),
@@ -96,6 +103,29 @@ describe('injectQuery', () => {
       expect(mockConvexClient.onUpdate).toHaveBeenCalled();
     }));
 
+    it('should type data as query result or undefined', () => {
+      @Component({
+        template: '',
+        standalone: true,
+      })
+      class TestComponent {
+        readonly todos = injectQuery(mockQuery, () => ({ count: 10 }));
+      }
+
+      const fixture = TestBed.createComponent(TestComponent);
+      fixture.detectChanges();
+
+      type TodosData = ReturnType<TestComponent['todos']['data']>;
+      const assertTodosDataType: Assert<
+        IsExact<TodosData, Array<{ _id: string; title: string }> | undefined>
+      > = true;
+
+      const typedData: TodosData = fixture.componentInstance.todos.data();
+
+      expect(assertTodosDataType).toBe(true);
+      expect(typedData).toBeUndefined();
+    });
+
     it('should set isLoading to true initially', fakeAsync(() => {
       @Component({
         template: '',

packages/convex-angular/src/lib/providers/inject-query.ts

@@ -54,10 +54,11 @@ export interface QueryOptions<Query extends QueryReference> {
 export interface QueryResult<Query extends QueryReference> {
   /**
    * The current data from the query subscription.
-   * Initially populated from local cache if available, then updated reactively.
-   * Data is preserved during refetch for better UX.
+   * Undefined until cached data or the first successful result is available.
+   * Data is also undefined when the query is skipped.
+   * The last successful value is preserved during refetch for better UX.
    */
-  data: Signal<FunctionReturnType<Query>>;
+  data: Signal<FunctionReturnType<Query> | undefined>;
 
   /**
    * The current error, if the query subscription failed.
@@ -162,7 +163,7 @@ export function injectQuery<Query extends QueryReference>(
     const destroyRef = inject(DestroyRef);
 
     // Initialize signals
-    const data = signal<FunctionReturnType<Query>>(undefined);
+    const data = signal<FunctionReturnType<Query> | undefined>(undefined);
     const error = signal<Error | undefined>(undefined);
     const isLoading = signal(false);
     const isSkipped = signal(false);