Repository: TypeScript
Issue: Allow defering type check of default value for generic-typed function parameter until instantiation
Labels: Suggestion,Experimentation Needed

### 🔍 Search Terms

TS2322, generic-typed function, default parameter

### ✅ Viability Checklist

- [X] This wouldn't be a breaking change in existing TypeScript/JavaScript code
- [X] This wouldn't change the runtime behavior of existing JavaScript code
- [X] This could be implemented without emitting different JS based on the types of the expressions
- [X] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
- [X] This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
- [X] This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

### ⭐ Suggestion

I've read https://github.com/microsoft/TypeScript/issues/49158 but I think my motivating example (and suggested solution) are different enough that it makes sense to open a new issue.

In essence, I think it would be nice to have a way to avoid `TS2322` ("Type 'X' is not assignable to type 'Y'.  'Y' could be instantiated with an arbitrary type which could be unrelated to 'X'.") on default function parameters by deferring the check until the call site.  In essence: at each caller, the caller is obligated to do one of the following:
 - instantiate the generic with a type (possibly inferred) which permits the default value to the parameter; or
 - provide a different value for the parameter which does satisfy the user's chosen type

It would even be reasonable to require that the default value of the parameter would allow the type parameter to be inferred (ie: so that "naive" uses of the call without specifying the type parameter nor the function parameter) would be valid.

Here's a very simple idea of how the feature would work:

```ts
// function definition (currently a violation of TS2322)
function x<T extends boolean>(arg1: T = false): T {
    return arg1;
}

// call site
x(); // OK: return type is false
x(true); // OK: return type is true
x<false>(); // OK
x<false>(false); // OK
x<true>(true); // OK

x<true>(); // must not be OK — I want the compiler to give me an error here, instead of at the site of the function definition.
```

Note in particular that it's not possible to use optional parameters to accomplish the above.  We need the `x<true>()` case to fail, because the default value is `false, after all.

### 📃 Motivating Example

[Cockpit](https://github.com/cockpit-project/cockpit) is an interface for performing admin tasks on Linux servers.  We essentially allow the Javascript running in the browser to interact with a set of APIs on the server via "Channels".  There's channels for reading files, creating files, connecting to sockets, spawning commands, making D-Bus calls, etc.  Channels can be opened in binary or text mode, which is controlled by passing `{ binary: true }` as part of the options object passed when creating a given channel.

The various channel subtypes have higher-level APIs which wrap the raw channel implementation.  Those in turn are sometimes wrapped by even higher level APIs which pass through the options object.  For example, `cockpit.spawn()` will spawn a command, and we have a wrapper `cockpit.python()` which will pass a given Python script via the `-c` argument and capture the result.

In most of these "wrapping" cases, the presence/value of the `binary` option on the options object will impact the return type of the function.

At first we did something like this:

```ts
    function spawn(
        args: string[],
        options?: SpawnOptions & { binary?: false }
    ): ProcessHandle<string>;
    function spawn(
        args: string[],
        options: SpawnOptions & { binary: true }
    ): ProcessHandle<Uint8Array>;

```
which produced the correct effect.  The options object is mandatory if you want binary, and it must contain `binary: true`.

It's very difficult to "wrap" such APIs, though: each wrapper needs to provide its own set of overloaded definitions, and convincing TypeScript that the internal call (to the "next layer") is correct is very difficult.

More recently I've come up with something like this simplified example, which works reasonably OK:

```ts
interface Channel<T> {
    get(): T;
}

type Opts = {
    binary?: boolean
}

type Payload<T extends Opts | undefined> = T extends { binary: true } ? Uint8Array : string;

function open<T extends Opts | undefined>(options?: T): Channel<Payload<T>> {
    console.log('options', options);
    throw new Error("NotImplementedError");
}

function wrap<T extends Opts | undefined>(options?: T): Channel<Payload<T>> {
    return open(options);
}

// all of these work
export const open_default: () => string = () => open().get();
export const open_string: () => string = () => open({ binary: false }).get();
export const open_binary: () => Uint8Array = () => open({ binary: true }).get();

export const wrap_default: () => string = () => wrap().get();
export const wrap_string: () => string = () => wrap({ binary: false }).get();
export const wrap_binary: () => Uint8Array = () => wrap({ binary: true }).get();
```

The problem here, though, is that because the `options` array is optional, you can force a different type for the function and omit the options:

```ts
// this should fail, but it doesn't
export const open_inv: () => Uint8Array = () => open<{ binary: true }>().get();
```

I've gone through a bunch of different approaches to try to figure out a way to approach this but it all comes down to the fact that an optional parameter of the generic type cannot possibly constrain the instantiated type of the function call by its *absence*.  You can always instantiate with your chosen type and the absent parameter will satisfy it (since it's optional, after all).

This is where the idea with default values comes in.  I don't actually want the parameter to be optional: I want to specify its default value, and I want that default value to be checked at the call site to match the instantiated type of the function call.

### 💻 Use Cases

1. What do you want to use this for?
 - see the motivating example
2. What shortcomings exist with current approaches?
 - the example I gave is unsound
3. What workarounds are you using in the meantime?
 - I'll probably use the unsound approach because it more or less works when you don't try to force it to do something wrong