'identity' modifier to indicate a function's parameter-less returns should be narrowed like a value

[JoshuaKGoldberg]

🔍 Search Terms

indicate function returns identical value cached memoized signals

✅ Viability Checklist

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

⭐ Suggestion

Many apps today are built on the concept of using small "getter" functions as wrappers around values. For example, Signals as implemented in Angular, Solid, and the stage 1 TC39 Signals proposal often look something like:

declare const value: () => string | undefined;

if (value() !== undefined) {
  console.log(value().toUpperCase());
}

Signals users have struggled with using them in TypeScript because, at present, there isn't a way to get that code block to type check without type errors. Signals users know that the result of value() must be string inside the if, but TypeScript doesn't have a way to note that the result should be type narrowed. Common workarounds today include !, ?., and refactoring to store intermediate values. All of which are at best unnecessary verbosity, and at worst conflict with frameworks.

Request: can we have a keyword -or, failing that, built-in / intrinsic type- to indicate that calls to a function produce a referentially equal, structurally unchanging value? In other words, that the function call (value()) should be treated by type narrowing as if it was just a variable reference (value)?

Proposal: how about an identity modifier keyword for function types that goes before the ()? It would be treated in syntax space similarly to other modifier keywords such as abstract and readonly.

📃 Motivating Example

When an identity function is called, it is given the same type narrowing as variables. Code like this would now type check without type errors, as if value was declared as const value: string | undefined:

declare const value: identity () => string | undefined;

if (value() !== undefined) {
  value();
  // Before: string | undefined
  // Now: string

  console.log(value().toUpperCase());
  // Before:  ~~~~~~~ Object is possibly 'undefined'.
  // Now: ✅
}

Narrowing would be cleared the same as variables when, say, a new closure/scope can't be guaranteed to preserve narrowing:

declare const value: identity () => string | undefined;

if (value() !== undefined) {
  setTimeout(() => {
    value();
    // Still: string | undefined

    console.log(value().toUpperCase());
    // Still:   ~~~~~~~ Object is possibly 'undefined'.
  });
}

💻 Use Cases

One difficult-to-answer design question is: how could identity handle functions with parameters? I propose the modifier not be allowed on function signaturess with parameters to start. It should produce a type error for now. The vast majority of Signals users wouldn't need signatures with parameters, so I don't think solidifying that needs to block this proposal. IMO that can always be worked on later.

Furthermore, it's common for frameworks to set up functions with a parameter-less "getter" signature and a single-parameter "setter" signature. I propose for an initial version of the feature, calling any other methods or setting to any properties on the type should clear type narrowing:

declare const value: {
  identity (): string | undefined;
  (newValue: string | undefined): void;
}

if (value() !== undefined) {
  value("...");

  value();
  // Still: string | undefined

  console.log(value().toUpperCase());
  // Still:   ~~~~~~~ Object is possibly 'undefined'.
}

More details on the difficulties of signals with TypeScript:

• Angular: signals: TypeScript and nullability angular/angular#49161
• Solid: Signals are troublesome with Typescript solidjs/solid#1575
  • Also on Solid: Allow type narrowing to be specified as always-on or always-off #57725 (comment)

If a new modifier keyword isn't palatable, a fallback proposal could be a built-in type like Identity<T>. This wouldn't be a new utility type (FAQ: no new utility types); it'd be closer to the built-in template string manipulation types.

[fabiospampinato]

Keeping the narrowing inside the if seems problematic if any function could be executing before our second call to value() here, as that could result in the type checker telling us something incorrect:

declare const value: () => string | undefined;

if (value() !== undefined) {
  whatever();
  console.log(value().toUpperCase());
}

Also this working only in getter/setter-style signals is potentially limiting, for example I use unified signals, with a single function that is both a getter and a setter, because there are many benefits to doing that in a typed codebase (which essentially prevents the common issues of this approach from happening), and if this worked only for getters it would be of no use to me, basically.

In general the deeper problem seems about somehow detecting when various types of narrowing should be invalidated, which seems very hard to express and very difficult for the type checker to check for.

Worth exploring this area though, as signals are getting more popular.

[Andarist]

Keeping the narrowing inside the if seems problematic if any function could be executing before our second call to value() here, as that could result in the type checker telling us something incorrect:

The same already happens with property narrowing so this wouldn't be a new problem at all. This would just use the same tradeoffs as the ones mentioned in #9998

[RyanCavanaugh]

Isn't the core problem in this example that value is incorrectly declared? If it were

declare const value: (() => string) | (() => undefined);

if (value() !== undefined) {
  console.log(value().toUpperCase());
}

Then there's a very straightforward path to adding a narrowing rule that allows a normal interpretation of narrowing value to the () => string constituent.

[RyanCavanaugh]

Also an ELI5 explanation for why it's not correct to write const v = value(); would be appreciated

[alxhub]

Isn't the core problem in this example that value is incorrectly declared?

Such a type might work for the simple case, but isn't really generalizable. If you consider the most basic implementation of a signal-like type:

class Signal<T> {
  constructor(private value: T) {}

  get(): T { return this.value; }
  set(value: T): void { this.value = value }
}

it would be very difficult / infeasible to type get into a union of all possible function types expressing the different narrowed shapes of T, without knowing the specific T. This is also a combinatorial problem: if T is something like {id: string|number, value: Data|undefined}, both id and value can be narrowed independently and encoding that into the get type would result in 4 different function types (assuming that even works).

Also an ELI5 explanation for why it's not correct to write const v = value(); would be appreciated

It's overhead compared to the experience with plain properties. Sometimes you have multiple levels of operations or multiple reads, which would result in a proliferation of temporary variables.

More critically, while value() is stable in the sense that repeated calls will return the same value, it may not be side-effect free. In the following chain:

if (x()) {
  createNewContext();
  x().value;
}

it might be important to record that x() is invoked after createNewContext(). Extracting to a temporary variable fixes the narrowing, but may alter the behavior in a breaking way.

[RyanCavanaugh]

A distributive conditional type would be correct, though you would only be able to narrow a union (string | number), not a specific value (if T is string you still couldn't narrow to 0)

type PossibleFuncs<T> = T extends unknown ? () => T : never;
declare class Signal<T> {
  constructor(value: T) {}

  get: PossibleFuncs<T>
  set(value: T): void;
}

[ryansolid]

Since where the read(function execution) happens matters in Signals libraries hoisting is incredibly clunky for a lot of cases. Especially in templating. Like think of JSX where everything is an expression not a statement. Most templating languages are effectively similar. Signal libraries tend to be granular in their rendering so components/templates don't re-run on a whole. Only parts that change re-execute. So the Signal function needs to be accessed in a very specific scope to trigger the right execution.

Not sure of people's familiarity but this is why often these sort of libraries can't destructure props. Because you can't access the getters at the top of the component but instead in the expression closest to where they are used. Different problem but part of the same mechanisms that are present here.

You don't always have a place to define variables and access the signal that might need to be used way nested down in your template. Places that are conditionally rendered, or parts of loops. A map function atleast can be made a block statement to be fair but even inside it there will be nested expressions so it can become onerous.

This is a fundamental aspect of Signals and the more granular people leverage them the more inevitable it will come that it will be painful to try to hoist stuff.

[Monkatraz]

A distributive conditional type would be correct, though you would only be able to narrow a union (string | number), not a specific value (if T is string you still couldn't narrow to 0)

type PossibleFuncs = T extends unknown ? () => T : never;
declare class Signal {
constructor(value: T) {}

get: PossibleFuncs
set(value: T): void;
}

How do you actually write this in non-declaration code?

This fails to type, and doesn't actually put get on the prototype:

type PossibleFuncs<T> = T extends unknown ? () => T : never;

class Signal<T> {
  private value: T;

  constructor(value: T) {
    this.value = value;
  }

  get: PossibleFuncs<T> = () => {
    return this.value;
  }

  set(value: T): void {
    this.value = value;
  }
}

You can do this instead, but value is considered unused, and it looks a little absurd:

type PossibleFuncs<T> = T extends unknown ? () => T : never;

interface Signal<T> {
  get: PossibleFuncs<T>;
}

class Signal<T> {
  private value: T;

  constructor(value: T) {
    this.value = value;
  }

  set(value: T): void {
    this.value = value;
  }
}

Signal.prototype.get = function () {
  return this.value;
}

As a side-note, Solid calls these kinds of functions Accessors

[alxhub]

A distributive conditional type would be correct, though you would only be able to narrow a union (string | number), not a specific value (if T is string you still couldn't narrow to 0)

This also only works for types in the top-level union. If a property of T is itself a union, it can't be narrowed via selecting a specific variant of PossibleFuncs<T>.

[RyanCavanaugh]

Wait, if the idea is that get "always returns the same value", why is there a set method in the first place? Doesn't this imply the need for additional syntax to identify which functions/methods invalidate the narrowing?

[Monkatraz]

Wait, if the idea is that get "always returns the same value", why is there a set method in the first place? Doesn't this imply the need for additional syntax to identify which functions/methods invalidate the narrowing?

I mean, this violates the spirit of your argument as well:

class Foo {
  value: number | null = null

  reset() {
    this.value = null
  }
}

const foo = new Foo()
foo.value = 123
foo.reset()

// not a type error
foo.value.toFixed()

[Monkatraz]

I suppose if you're building with explicitly TypeScript in mind the ideal implementation is something like this:

class Signal<T> {
  private _value: T;

  constructor(value: T) {
    this._value = value;
  }

  get value(): T {
    // ... signal tracking logic

    return this._value;
  }

  set value(value: T) {
    // ... signal tracking logic

    this._value = value;
  }
}

But this wouldn't work for e.g. Solid, which just has accessors like foo() with no property access. Also, most consumers of the signal library won't be given signals directly and will instead have something wrapped around them, like useState in React or createSignal in Solid, both of which do not return an object that you do property access on.

EDIT: Also, the explicit function call syntax (so signal.get()) gets across that the access actually has side effects a little better.

[RyanCavanaugh]

I mean, this violates the spirit of your argument as well:

Okay, but it seems extremely nearsighted to ship a new CFA feature that is going to immediately run into another feature request before it's considered useful. Bringing up the current CFA trade-offs as relates to properties doesn't seem like a useful way to address this concern.

[Monkatraz]

Okay, but it seems extremely nearsighted to ship a new CFA feature that is going to immediately run into another feature request before it's considered useful. Bringing up the current CFA trade-offs as relates to properties doesn't seem like a useful way to address this concern.

You're not wrong, but I think the feature would still be helpful regardless. The trade-offs are a "known quantity" to me, and this doesn't introduce anymore of them, right? It would be basically identical to how getters behave (except with no setter, I guess)

EDIT: I think with this feature it would be important for the naming and docs to get across it's intended for accessors, so as long as you don't yield to anything, you will know what the value is and it can't change on you (...usually), like a property.