Problem Description

You need to create a higher-order function called once that takes a function fn as input and returns a new modified version of that function. The modified function should have special behavior regarding how many times it can execute:

Key Requirements:

1. The returned function should only execute the original function fn the first time it's called
2. When called for the first time, it should return the exact same result that fn would return with the given arguments
3. On all subsequent calls (second, third, etc.), the function should return undefined without executing fn at all

Example Behavior:

If you have a function that adds three numbers:

• fn = (a, b, c) => (a + b + c)
• Create a "once" version: onceFn = once(fn)
• First call: onceFn(1, 2, 3) returns 6 (executes the addition)
• Second call: onceFn(2, 3, 6) returns undefined (doesn't execute the addition)
• Any further calls also return undefined

This pattern is useful when you want to ensure a function's side effects or computations only happen once, regardless of how many times the function is invoked. Common use cases include initialization functions, event handlers that should only fire once, or preventing duplicate API calls.

The solution uses a closure with a boolean flag called to track whether the function has been executed. When called is false, the function executes and sets the flag to true. All subsequent calls check this flag and return undefined without executing the original function.

Intuition

The core challenge here is creating a function that "remembers" whether it has been called before. This immediately suggests we need some form of persistent state that survives between function calls.

Think about what we need to track: has the function been called or not? This is a simple yes/no question, which naturally maps to a boolean variable. We need this boolean to persist across multiple invocations of our returned function.

This leads us to the concept of a closure - a function that has access to variables from its outer (enclosing) scope even after the outer function has returned. When we return a function from once(), that returned function can still access and modify variables defined in once()'s scope.

Here's the thought process:

1. We need a flag (called) that starts as false
2. This flag must be accessible to the returned function but not directly modifiable from outside
3. When the returned function executes, it checks this flag:
   • If false: Run the original function, save its result, flip the flag to true, and return the result
   • If true: Don't run anything, just return undefined

The beauty of this approach is that each call to once() creates its own independent closure with its own called variable. So if you create multiple "once" versions of different functions (or even the same function), they each maintain their own state independently.

This pattern leverages JavaScript's closure mechanism to create a simple state machine with two states: "not yet called" and "already called". The transition happens exactly once, and there's no way to reset it - perfectly matching our requirements.

Solution Approach

Let's walk through the implementation step by step:

1. Function Signature Setup:

function once(fn: Function): OnceFn

The once function accepts any function fn as a parameter and returns a new function of type OnceFn that can handle JSONValue arguments.

2. Creating the Closure State:

let called = false;

Inside once, we declare a boolean variable called initialized to false. This variable will live in the closure and track whether the function has been invoked.

3. Returning the Modified Function:

return function (...args) {
    // function body
}

We return an anonymous function that accepts any number of arguments using the rest parameter syntax ...args. This returned function has access to both called and the original fn through closure.

4. Implementing the Conditional Logic:

if (!called) {
    called = true;
    return fn(...args);
}

Inside the returned function:

• We check if called is still false (using !called)
• If it's the first call:
  • Set called = true to mark that the function has been executed
  • Call the original function fn with all the provided arguments using spread syntax fn(...args)
  • Return the result from fn
• If called is already true (subsequent calls):
  • The if block is skipped
  • The function implicitly returns undefined (JavaScript functions return undefined by default when no explicit return statement is reached)

Key Implementation Details:

• Closure Mechanism: Each call to once() creates a new closure with its own called variable, ensuring different "once-ified" functions don't interfere with each other
• Spread/Rest Operators: The ...args pattern allows the wrapper function to accept any number of arguments and pass them through to the original function unchanged
• Implicit undefined Return: No need for an explicit else block since JavaScript functions automatically return undefined when no return value is specified

This implementation is both memory-efficient (only stores a single boolean) and performant (simple boolean check on each call).

Example Walkthrough

Let's walk through a concrete example to see how the once function works:

Step 1: Create a simple function to wrap

const greet = (name, time) => {
    console.log(`Good ${time}, ${name}!`);
    return `Greeted ${name}`;
};

Step 2: Create a "once" version using our implementation

const greetOnce = once(greet);
// At this point, a closure is created with called = false

Step 3: First invocation

const result1 = greetOnce("Alice", "morning");
// Inside greetOnce:
// - Check: called is false ✓
// - Set: called = true
// - Execute: greet("Alice", "morning")
// - Console outputs: "Good morning, Alice!"
// - Returns: "Greeted Alice"
// result1 = "Greeted Alice"

Step 4: Second invocation (with different arguments)

const result2 = greetOnce("Bob", "evening");
// Inside greetOnce:
// - Check: called is true ✗
// - Skip the if block
// - No console output
// - Returns: undefined
// result2 = undefined

Step 5: All subsequent invocations

const result3 = greetOnce("Charlie", "afternoon");
// Same as step 4:
// - called is still true
// - Returns: undefined
// result3 = undefined

Visualizing the closure state:

Initial state:     called = false
After first call:  called = true  (permanently changed)
All future calls:  called = true  (no further changes)

This example demonstrates how the closure maintains the called flag across multiple invocations, ensuring the original function only executes once while all subsequent calls return undefined.

Solution Implementation

Time and Space Complexity

Time Complexity: O(1) for the wrapper function execution. The actual time complexity depends on the wrapped function fn, but the overhead introduced by the once wrapper is constant - it only performs a boolean check and potentially updates a boolean flag.

Space Complexity: O(1) for the closure created by the once function. The wrapper maintains only a single boolean variable called in its closure scope. The space required doesn't grow with input size, making it constant space. However, if we consider the wrapped function fn being stored in the closure, it's still O(1) additional space overhead relative to the original function.

Detailed Analysis:

• The once function creates a closure that captures two variables: the boolean flag called and the original function fn
• Each call to the returned function performs:
  • One boolean check (if (!called))
  • Potentially one boolean assignment (called = true)
  • Potentially one function call (fn(...args))
• All these operations are constant time O(1)
• The memory overhead is fixed regardless of how many times the returned function is called or the size of arguments passed

Common Pitfalls

1. Shared State Across Different Instances

A common mistake is accidentally sharing the called flag between different instances of once-wrapped functions. This happens when the flag is placed in the wrong scope:

Incorrect Implementation:

# WRONG: Global flag shared by all once-wrapped functions
has_been_called = False

def once(fn):
    def wrapper(*args):
        global has_been_called
        if not has_been_called:
            has_been_called = True
            return fn(*args)
        return None
    return wrapper

# Problem demonstration:
add = once(lambda x, y: x + y)
multiply = once(lambda x, y: x * y)

print(add(2, 3))       # Returns 5
print(multiply(4, 5))  # Returns None (Wrong! Should return 20)

Solution: Keep the flag in the closure scope (as shown in the correct implementation) so each wrapped function has its own independent state.

2. Mutable Default Arguments Confusion

When wrapping functions with mutable default arguments, developers might incorrectly assume the once wrapper affects the default argument behavior:

def append_item(lst=[]):
    lst.append(1)
    return lst

once_append = once(append_item)

# The once wrapper doesn't prevent the mutable default argument issue
result1 = once_append()  # Returns [1]
result2 = once_append()  # Returns None, but the original function's default list still exists

Solution: Be aware that once only controls execution frequency, not the underlying function's behavior with mutable defaults.

3. Expecting Cached Return Values

A frequent misconception is thinking that once caches the first result and returns it on subsequent calls:

What developers expect (but doesn't happen):

expensive_computation = once(lambda x: x ** 1000000)
result1 = expensive_computation(2)  # Returns large number
result2 = expensive_computation(3)  # They expect the same large number, but get None

Solution: If you need caching behavior, implement a memoization wrapper instead:

def once_with_cache(fn):
    has_been_called = False
    cached_result = None
  
    def wrapper(*args):
        nonlocal has_been_called, cached_result
        if not has_been_called:
            has_been_called = True
            cached_result = fn(*args)
        return cached_result
  
    return wrapper

4. Thread Safety Issues

In multi-threaded environments, the basic implementation isn't thread-safe. Two threads could both pass the if not has_been_called check before either sets it to True:

import threading

counter = 0

def increment():
    global counter
    counter += 1
    return counter

once_increment = once(increment)

# Multiple threads calling simultaneously
threads = [threading.Thread(target=once_increment) for _ in range(10)]
for t in threads:
    t.start()
for t in threads:
    t.join()

# counter might be > 1 due to race condition

Solution: Use thread synchronization:

import threading

def thread_safe_once(fn):
    lock = threading.Lock()
    has_been_called = False
  
    def wrapper(*args):
        nonlocal has_been_called
        with lock:
            if not has_been_called:
                has_been_called = True
                return fn(*args)
        return None
  
    return wrapper

5. Loss of Function Metadata

The wrapper function loses the original function's metadata (name, docstring, etc.):

def important_function():
    """This function does something important."""
    return 42

wrapped = once(important_function)
print(wrapped.__name__)  # Prints 'wrapper', not 'important_function'
print(wrapped.__doc__)   # Prints wrapper's docstring, not original

Solution: Use functools.wraps decorator:

from functools import wraps

def once(fn):
    has_been_called = False
  
    @wraps(fn)  # Preserves original function metadata
    def wrapper(*args):
        nonlocal has_been_called
        if not has_been_called:
            has_been_called = True
            return fn(*args)
        return None
  
    return wrapper