Non‑void returning assertion functions

Search Terms

assertion function non-void return type
assertion function non-void return
assertion function generic return
assertion function custom return

Suggestion

A way to type a function that is both an assertion function and returning a value that is not void.

Use Cases

This is necessary to correctly type Jest’s expect(…) matchers, which have a generic return type of R.

Examples

declare const expect: <T>(actual: T): JestMatchers<T>;

type JestMatchers<T> = JestMatchersShape<
	Matchers<void, T>,
	Matchers<
		Promise<void>,
		T extends PromiseLike<infer U>
			? U
			: Exclude<T, PromiseLike<any>>
	>
>;

type JestMatchersShape<TNonPromise extends {} = {}, TPromise extends {} = {}> = {
	resolves: AndNot<TPromise>;
	rejects: AndNot<TPromise>;
} & AndNot<TNonPromise>

type AndNot<T> = T & { not: T };

interface Matchers<R, T = {}> {
	toBe<E>(expected: E): R & (asserts T is E);
}

declare const foo: unknown;
expect(foo).toBe("foo");
foo; // $ExpectType "foo"

// Some typings for engine262's Completion Record handling:
type UnwrapNormalCompletion<T>
	= unknown extends T ? Value | undefined
	: T extends NormalCompletion<infer V>
		? (unknown extends V ? Value | undefined : V)
	: T extends Completion ? never
	: T;

/** @see https://tc39.es/ecma262/#sec-returnifabrupt */
export declare function ReturnIfAbrupt<T>(completion: T):
	(UnwrapNormalCompletion<T>)
	& (asserts completion is UnwrapNormalCompletion<T>);

/** @see https://tc39.es/ecma262/#sec-returnifabrupt-shorthands */
export { ReturnIfAbrupt as Q };

/**
 * The type signature is the same, but `AssertNormalCompletion` causes an error to be thrown at runtime
 * if `argument` is an AbruptCompletion, whereas `ReturnIfAbrupt` gets replaced with code that causes
 * the caller to return the AbruptCompletion by engine262's build system:
 *
 * @see https://tc39.es/ecma262/#sec-returnifabrupt
 * @see https://tc39.es/ecma262/#sec-returnifabrupt-shorthands
 */
declare function AssertNormalCompletion<T>(completion: T):
	(UnwrapNormalCompletion<T>)
	& (asserts completion is UnwrapNormalCompletion<T>);
export { AssertNormalCompletion as X };

Checklist

My suggestion meets these guidelines:

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, etc.)
This feature would agree with the rest of TypeScript's Design Goals.

duplicate of or related to #34636

Note that the duplicate #34636 (which got here first) has 39 👍 at the time of writing, and this one has only 9 👍. If these are used for prioritization, perhaps this one should be closed and the other should be reopened?

Here's a simpler example that doesn't require any 3rd party libraries:

type ValidRawData = { foo: string; };
declare function assertIsValidRawData(value: unknown): asserts value is ValidRawData;

// Ideal return type would be some like:
// ParsedData & asserts data is ValidRawData
function parseData(data: unknown) {
    assertIsValidRawData(
        data !== null &&
        typeof data === "object" &&
        Object.hasOwn(data, "foo") &&
        typeof data.foo === "string"
    );
    ...
}

const rawData: unknown = {};
const data = parseData(rawData);
const foo = rawData.foo; // <== Not currently valid. `parseData` called above should be able to assert that rawData is of type ValidRawData.

Playground link.

One footgun this avoids is it can avoid unused variables:

const val = api.value
ensureExists(val)
// if you never use val for rest of file, but linter is happy

const val = ensureExists(api.value)
// if you never use val for rest of file, linter will complain / editor will show unused

Nate Wienert (@natew)

Nate Wienert (@natew) If you never use val, why define it? just call the function.

ensureExists(api.value)

You miss the whole point of the post... This can happen if you use val for something valid, then clean up some code below it that removes all the references to it, for example. You miss seeing its not necessary anymore because it tricks the linter. Whereas the assign pattern if I remove all references below I’ll clearly see it’s dangling.

…

On May 20, 2022, at 11:25 AM, Rebecca Stevens ***@***.***> wrote: @natew If you never use val, why define it? just call the function. ensureExists(api.value) — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.

Would love for this feature to exist. Not only would it be useful for some mutating functions like Object.assign and the jest functions above, but I think it also enables some novel compile-time safe patterns for mutable structures that aren't possible to represent currently.

For example, a state machine that can assert that a transition is changing the underlying object to a new state, and return information about the transition itself.

Imagine this example:

myMachine = createMachine();

myMachine.stopExport(); // error: stopExport does not exist on type MachineReady

myMachine.startExport() // returns returns a promise to await the export AND asserts that myMachine is in a different state
myMachine.startExport() // error: startExport does not exist on MachineStarted

Collin Irwin (@irwincollin)

I agree that this would be a helpful feature. In addition to the Object.assign() scenario that Collin Irwin (@irwincollin) mentioned above, there may be situations where a developer wants to mutate an array in place in order to avoid the performance overhead that comes from methods like Array.map. (Array.map would consume additional memory unnecessarily since it always creates a new array, and this can be problematic if the array is very large.)

The problem with returning something like T & U (like Object.assign()) is that such a return type won't communicate that the original variable which was passed to the function was mutated. And the problem with asserts is that it can't be used to return the mutated object for convenience.

A syntax like

function mapArrayInPlace<T, U>(array: T[], func: (items: T) => U): mutates array to U[];

could be helpful. I would hope that this would be fairly simple since TypeScript already has a way to assert and a way to return generic types. We'd just be adding 2 new keywords, and it would look familiar to what we have in other situations:

function predicate(arg: unknown): arg is number;
function asserter(arg: unknown): asserts arg is number;
function mutator(arg: unknown): mutates arg to number;

This seems to be related to #17181, though it comes from the opposite angle. A library that rigorously identifies its mutating functions in the way described above could satisfy some of the requirements of that issue if I'm understanding correctly. (I only skimmed the issue.)

This is also related to #22865.

Another extremely big use case is that this would finally open the door for mutable object argument type, a concept from Rust that makes typescript type system so much inferior...

function popKey<T extends object, TKey extends keyof T>(
  obj: T, key: TKey
): T[TKey], asserts obj is Omit<T, TKey> {
  const value = obj[key];
  delete obj[key];
  return value;
}

const obj = { a: 1, b: 2 };
const b = popKey(obj, 'b');
// should be a type error since we informed the compiler that `b` key was removed
obj.b.toFixed(2);

I guess you can kind of emulate it with an extra output mutable variable, but it would be awfully awkward.

Navigation Menu

Repository navigation

Non‑`void` returning assertion functions #40562

Search Terms

Suggestion

Use Cases

Examples

Checklist

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Non‑void returning assertion functions #40562

Description

Search Terms

Suggestion

Use Cases

Examples

Checklist

Activity

jcalz commented on Sep 15, 2020

ttencate commented on Jul 11, 2021

RebeccaStevens commented on Nov 30, 2021

natew commented on May 20, 2022

RebeccaStevens commented on May 20, 2022

natew commented on May 21, 2022

irwincollin commented on May 7, 2024

ITenthusiasm commented on Jun 7, 2024

ITenthusiasm commented on Jun 7, 2024

mkantor commented on Jan 22, 2026

artur-klesun-st commented on Mar 29, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Non‑`void` returning assertion functions #40562