Function call expression
The function call expression syntax evaluates a function's body using the given arguments and returns the result.
Try it
function getRectArea(width, height) {
return width * height;
}
console.log(getRectArea(3, 4));
// Expected output: 12
Syntax
fn()
fn(arg1)
fn(arg1, arg2)
fn(arg1, arg2, /* …, */ argN)
Parameters
fn-
An expression with precedence 17 (access and call) or above. The result must be a callable function. Usually an identifier, a property access, or a function literal expression (the IIFE pattern).
arg1, …,argNOptional-
Each argument can be a spread argument or an expression with precedence 2 (assignment) or above.
Return value
- If the function is a normal function, its whole body is evaluated. The call expression evaluates to its return value, or
undefinedif the end of the function body is reached without encountering areturnstatement. - If the function is an async function, its body is evaluated up to the first
awaitexpression or the function's completion. The call expression evaluates to a pendingPromiseif anawaitis encountered, or a promise resolved to the return value if the function exits without encounteringawait. - If the function is a generator function, the call expression evaluates to a new
Generatorobject. The function body starts executing on the first call to the generator'snext()method. - If the function is an async generator function, the call expression evaluates to a new
AsyncGeneratorobject. The function body starts executing on the first call to the generator'snext()method, which returns a promise for the next iterator result.
Exceptions
TypeError-
Thrown if
fnis not callable, which includes cases where it isn't a function (typeof fn !== "function"), it's a class, or it throws unconditionally when called (likeMap(), which must be constructed withnewinstead).
The call expression also propagates uncaught errors from evaluating the function body:
- If the function is a normal function, uncaught errors thrown from the function body become errors of the call expression.
- If the function is an async function, uncaught errors cause the returned promise to reject.
- If the function is a generator function, uncaught errors become errors of the
next()method. - If the function is an async generator function, uncaught errors cause the promise returned by the
next()method to reject.
Description
When evaluating a function call, the fn expression is evaluated first, and then each argument expression in order, expanding spread arguments as they are encountered. Only when all expressions are evaluated does it check whether fn is callable. For example:
1(console.log("Hi")); // Logs "Hi"
// Uncaught TypeError: 1 is not a function
Although 1 is not callable, the side effect of the argument is still generated.
This contrasts with optional chaining, which does not evaluate the arguments if fn is already null or undefined.
null?.(console.log("Hi")); // Nothing logged
The arguments list may not match the parameters the function has declared to accept. If fewer arguments are provided than the function expects, those parameters get the value undefined. If more arguments are provided, they are still evaluated and are accessible inside the function via the arguments object.
Arguments are always passed by value and never passed by reference. This means that if a function reassigns a parameter, the value won't change outside the function. More precisely, object arguments are passed by sharing, which means if the object's properties are mutated, the change will impact the outside of the function. See the functions guide for more information.
The call expression supplies the this context to the function body. The this context is established by using a (possibly parenthesized) property accessor. For example, in [].push(1);, [].push is the function value that gets called, while [] is the this value.
Examples
>Calling a normal function
Normal functions return JavaScript values directly (which may be undefined).
function completes(a, b) {
console.log(a, b);
}
function returns(a, b) {
return a + b;
}
function throws(a, b) {
throw new Error(`${a} and ${b}`);
}
console.log(completes(1, 2)); // Logs 1 2; returns undefined
console.log(returns(3, 4)); // 7
console.log(throws(5, 6)); // Error: 5 and 6
Calling an async function
Async functions return Promise objects.
async function awaits(a, b) {
console.log("awaits() starts");
await new Promise((resolve) => setTimeout(resolve, 10));
return a + b;
}
async function returns(a, b) {
console.log("returns() starts");
return a + b;
}
async function throws(a, b) {
console.log("throws() starts");
throw new Error(`${a} and ${b}`);
}
awaits(1, 2).then(console.log);
returns(3, 4).then(console.log);
throws(5, 6).catch(console.error);
Promise.resolve().then(() => console.log("Promise.resolve"));
console.log("All functions called");
This outputs:
awaits() starts returns() starts throws() starts All functions called 7 Error: 5 and 6 Promise.resolve 3
As you can see, all functions start executing synchronously. The promises returned by returns(3, 4) and throws(5, 6) settle as soon as they return because they contain no await, so the output is logged before Promise.resolve. The settled result of awaits() is only received after the setTimeout finishes after 10ms.
Calling a generator function
Generator functions return Generator objects. The function execution is suspended until next() is called.
function* yieldTwo(a, b) {
yield a;
yield b;
return "done";
}
const gen = yieldTwo(1, 2);
console.log(gen.next()); // {value: 1, done: false}
console.log(gen.next()); // {value: 2, done: false}
console.log(gen.next()); // {value: "done", done: true}
See the Iterators and generators guide for more information about how they work.
Calling an async generator function
Async generator functions return AsyncGenerator objects. The function execution is suspended until next() is called.
async function* yieldTwo(a, b) {
await new Promise((resolve) => setTimeout(resolve, 10));
yield a;
await new Promise((resolve) => setTimeout(resolve, 10));
yield b;
await new Promise((resolve) => setTimeout(resolve, 10));
return "done";
}
const gen = yieldTwo(1, 2);
console.log(await gen.next()); // {value: 1, done: false}
console.log(await gen.next()); // {value: 2, done: false}
console.log(await gen.next()); // {value: "done", done: true}