[IzaakGough]

Fixes #257.

Calling a wrapped v2 callable from TypeScript required every CallableRequest field, so tests needed as any casts and got any back.

This keeps the callable's request and return types through wrap() and wrapV2(), and makes every request field optional, including data and the request itself.

• Missing data is a runtime error, not a compile error, so tests can pass only auth or headers. This matches how wrapped CloudEvent functions work.

Tested with unit tests and a --strict type check of the published types against firebase-functions 4.9.0.

[gemini-code-assist]

Code Review

This pull request refactors the TypeScript types for wrapping v2 callable Cloud Functions to support generic input and return types (T and Return), replacing the previous usage of any. It introduces a new WrappedV2CallableRequest<T> type to represent the wrapped request object. The reviewer feedback suggests several improvements to enhance usability and safety: making the data property optional when the input type T can be undefined, renaming the parameter of WrappedV2CallableFunction from data to request (and making it optional), and safely handling potential undefined request arguments at runtime within wrapV2 to prevent crashes.

[cabljac]

lgtm with comments

[wandamora]

Left some small suggestions.

[ajperel]

Thanks for putting this together and tackling issue #257.

Stepping back and looking at the current type definition, and after a LOT of discussion with AI, I'd like to propose simplifying this to a permissive, single-optional-parameter model, mirroring how V2 CloudEvents (WrappedV2Function) works across the rest of this library.

---

The Problem with Strict Arity Enforcement

Right now, the PR uses TakesNoData<T> and tuple rest arity (...args: WrappedV2CallableArgs<T>) to conditionally require 1 argument unless T is strictly void or undefined. Because TakesNoData explicitly excludes any (0 extends 1 & T ? false : ...), it introduces noticeable friction for common unit testing patterns:

1. Untyped Callables (onCall((req) => ...) Defaults to T = any):
   In JavaScript and untyped TypeScript, callables default to T = any. Because TakesNoData<any> evaluates to false, developers cannot write:

   await wrapped(); // ❌ TS2554: Expected 1 arguments, but got 0
   await wrapped({ auth: { uid: '123' } }); // ❌ TS2345: Property 'data' is missing

   Instead, they are forced to pass boilerplate { data: undefined } on functions that don't take data.

2. Early-Exit Auth & Permission Testing:
   A common unit test for a callable is testing authorization guards:

   export const transferFunds = https.onCall<{ amount: number }>(async (req) => {
     if (!req.auth) throw new HttpsError('unauthenticated', 'Login required');
     return processTransfer(req.data.amount);
   });

   When testing that unauthenticated users are rejected, the test only cares about auth:

   await expect(wrapped({ auth: undefined })).to.be.rejectedWith('unauthenticated');

   Under strict arity, this fails to compile unless the developer invents dummy payload data ({ auth: undefined, data: { amount: 0 } }), which adds noise and can mask regressions (e.g. if the auth guard is accidentally reordered).

3. Optional Payload Unions (onCall<string | undefined>):
   [string | undefined] extends [undefined | void] evaluates to false, so optional payload functions are also forced to require { data: ... }.

---

Consistency with V2 CloudEvents (WrappedV2Function)

In WrappedV2Function (src/v2.ts), the input parameter is completely optional:

export type WrappedV2Function<T extends CloudEvent<unknown>> = (
  cloudEventPartial?: DeepPartial<T | object>
) => any | Promise<any>;

V2 CloudEvents embraces the philosophy that in a unit testing SDK, permissiveness is key: developers specify only the partial slice of state relevant to the test, and the framework safely handles the rest.

At runtime, wrapV2 already does:

return cloudFunction.run({ data: undefined, ...request } as CallableRequest<any>);

Because the runtime is already 100% crash-safe when called with zero arguments or without data, our TypeScript definitions should match that runtime flexibility.

---

Proposed Minimal Fix

We can drop TakesNoData, WrappedV2CallableArgs, and the DeepPartial<Required<Omit<...>>> workaround, replacing them with a flat, clean interface:

export type WrappedV2CallableRequest<T> = {
  data?: T;
  rawRequest?: Partial<Request>;
  auth?: DeepPartial<CallableRequest['auth']>;
  app?: DeepPartial<CallableRequest['app']>;
  instanceIdToken?: string;
  acceptsStreaming?: boolean;
};

/**
 * A function that can be called with a {@link CallableRequest} for a v2 callable function.
 * Every request field is optional to allow focused unit testing of auth, headers, or payloads.
 */
export type WrappedV2CallableFunction<T = any, Return = any> = (
  request?: WrappedV2CallableRequest<T>
) => Return;

Why this is better:

1. Solves #257 completely: Passing { data: { whatever: "mydata" } } works cleanly, rawRequest accepts Partial<Request>, and payload type checking on data is still enforced if provided (e.g. { data: { a: 'invalid' } } still fails).
2. First-class testing ergonomics: wrapped(), wrapped({ auth: { uid } }), and wrapped({ rawRequest: { headers } }) all compile and run naturally without ceremony.
3. IDE Tooltip Clarity: Hovering over WrappedV2CallableFunction in an editor shows a clean, readable signature with immediate autocompletion, rather than multi-line conditional intersection types.
4. Maintenance & Simplicity: Removes ~30 lines of conditional type gymnastics and compiler tricks (0 extends 1 & T), making the code much easier to maintain as firebase-functions evolves.

In spec/v2.spec.ts, this would simply mean updating the untyped test to verify that wrappedCF() and wrappedCF({ auth: ... }) succeed without arguments (matching onCall<void>), rather than expecting a compile error.

What do you think about adopting this simpler, permissive approach?

[IzaakGough]

@ajperel Thank you for taking the time to work on this! I definitely think going with this simpler/cleaner interface is better. There are three points that I think are worth raising w.r.t this approach, let me know your thoughts on them.

1. DeepPartial<CallableRequest['auth']> does not compile under strict

DeepPartial is constrained to object, and CallableRequest['auth'] is AuthData | undefined. Our tsconfig has strictNullChecks off, so tsc passes locally, but a consumer with strict on and skipLibCheck off gets this from the published .d.ts:

error TS2344: Type 'AuthData | undefined' does not satisfy the constraint 'object'.

AuthData and AppCheckData are not exported from firebase-functions/v2/https, so wrapping in NonNullable is the fix:

export type WrappedV2CallableRequest<T> = {
  data?: T;
  rawRequest?: Partial<Request>;
  auth?: DeepPartial<NonNullable<CallableRequest['auth']>>;
  app?: DeepPartial<NonNullable<CallableRequest['app']>>;
  instanceIdToken?: string;
  acceptsStreaming?: boolean;
};

Do you think this is worth fixing?

2. Missing data becomes a runtime error rather than a compile error

With data?: T, wrapped() and wrapped({ auth: undefined }) compile for onCall<{ a: number }>, and the handler sees data as undefined. That is exactly the trade you describe for auth-guard tests, and it is consistent with auth already being partial, so I am fine with it. It also means untyped callables skip the check again, which came up earlier in review, so I want to make sure we are choosing that deliberately.

3. The field list needs updating when CallableRequest grows

Spelling the fields out by hand reads much better than DeepPartial<Required<Omit<...>>>, so I think it is the right call. The cost is that a field added upstream later will be rejected as an excess property until we add it here, and the as CallableRequest<any> cast means nothing in this repo will flag that. It matches 7.4.0 exactly today, so this is just something to keep in mind when bumping firebase-functions.

[ajperel]

@IzaakGough

1. Great observation on "DeepPartial<CallableRequest['auth']> does not compile under strict" I do think we should go with your suggestion of using NonNullable.

2. Missing data becomes a runtime error rather than a compile error - Yeah... I think this is a judgement call between strict compile time benefits vs. testing flexibility. Given how much cloud events lean towards flexibility and that this is all for testing... I think this is the right tradeoff but I'm open to arguments against it. But yeah, if you're also convinced let's just stick with runtime errors being acceptable.

3. The field list needs updating when CallableRequest grows - Yeah. My hope is that CallableRequest grows very very slowly so this won't be a big deal in practice. Gemini had one suggestion that we could at least catch this via a test so any change to the test library will help surface is this happened and becomes a quickly fixed problem. Something like:

type UnhandledKeys = Exclude<keyof CallableRequest, keyof WrappedV2CallableRequest<any>>;
const _assertAllKeysCovered: UnhandledKeys = undefined as never;

In an appropriate test file.

[IzaakGough]

@ajperel Okay great, yeah I think in 2 this is the right tradeoff as well. I will make the changes for points 1 and 3.

[ajperel]

Nice. Thanks for iterating on this.