What is the best way to document a collection of generic interfaces while ensuring that they adhere to specific

Question

What is the best way to document a collection of generic interfaces while ensuring that they adhere to specific

I am currently utilizing a parser toolkit called Chevrotain to develop a query language that offers users the ability to enhance its functionality. Despite having all the necessary components in place, I am facing challenges when it comes to defining types for this extended behavior. My goal is to establish a configuration object with typings that enable Typescript users to benefit from convenient IDE assistance in ensuring the accuracy of their input. While it seems achievable (or at least very close), my focus has been on crafting these types rather than resorting to runtime assertions.

Here's a simplistic example showcasing some configuration:

ops: {
  equal: {
    lhs: {
      type: 'string',
      from: v => String(v),
    },
    rhs: {
      type: 'number',
      from: v => v.toString(),
    },
    compare: (lhs, rhs) => lhs === rhs,
  }
  equal: { /*...*/ }
}

The following criteria are what I aim to achieve:

The argument type for from should be linked to the string literal value within the type property. I've successfully accomplished this through various methods, with the most straightforward being a basic type such as:

type ArgTypes = {
  string: string,
  number: number,
  ref: any, // The strings aren't necessarily Typescript types and can involve more complex types
}

The fields lhs and rhs should support distinct types both as inputs and outputs.
The compare function must accept the output of properties lhs and rhs, then return a boolean value.

While I have succeeded in typing things at the level of a single operator (equal), expanding this to an object-bag of operators has proved challenging. In an attempt showcased in a Playground link where I gradually built it up using generics and child types, the type signature for Ops at line 105 seemed problematic. Here's the link to that playground experiment: attempt N. Another approach, inspired by a discussion on avoiding type widening issues when passing object literals as arguments in TypeScript, involved adding type arguments extensively, but encountered difficulties once the "compare" line was uncommented in the type signature. Specifically, the previously narrow types became generalized (e.g., the literal "number" transitioned to string).

Would it be feasible to accomplish this task, or should I consider abandoning it? If so, what would be the best course of action?

typescript typescript-generics type-inference

Answer 1

Answer №1

The issue at hand arises from the limited capability of TypeScript to infer generic type parameters and contextually type function parameters simultaneously. The inference algorithm consists of a set of practical heuristics that works well in many common scenarios, but it falls short as it is not an exhaustive unification algorithm that guarantees accurate assignment of types to all generic type arguments and unannotated values, as suggested in microsoft/TypeScript#30134 (not yet implemented).

While generic type parameters can be successfully inferred in certain cases:

declare function foo<T>(x: (n: number) => T): T
foo((n: number) => ({ a: n })) // Inference successful for T as {a: number}

and similarly unannotated function parameters can also be inferred:

declare function bar(f: (x: { a: number }) => void): void;
bar(x => x.a.toFixed(1)) // Inference successful for x as {a: number}

there are limitations when attempting both simultaneously, especially with multiple function arguments and the inference flow moving from left to right:

declare function baz<T>(x: (n: number) => T, f: (x: T) => void): void;
baz((n) => ({ a: n }), x => x.a.toFixed(1))
// Inference results: n as number, T as {a: number}, x as {a: number}

However, such simultaneous inference sometimes fails. Prior to TypeScript 4.7, a scenario like the following would not correctly infer the desired types:

declare function qux<T>(arg: { x: (n: number) => T, f: (x: T) => void }): void;
qux({ x: (n) => ({ a: n }), f: x => x.a.toFixed(1) })
// TS 4.6: n inferred as number, T failed to infer, x failed to infer
// TS 4.7: n inferred as number, T inferred as {a: number}, x inferred as {a: number}

This was resolved in TypeScript 4.7 with microsoft/TypeScript#48538. However, the algorithm is still not flawless.

In situations involving complex inference paths due to contextual typing, the system may fail to correctly determine types.

Your provided code example faces challenges with mapped types inference and callback parameter inference occurring concurrently, hence leading to errors. For instance:

function ops<T extends { [key: string]: any }, O extends Ops<T>>(spec: O): O {
    return spec;
}

This structure would never work due to generic constraints not serving as inference sites per microsoft/TypeScript#7234. One potential solution could involve adjusting the approach, such as:

function ops<T>(spec: Ops<T>): Ops<T> { // Infer from mapped type
    return spec;
}

resulting in improved inference. Nevertheless, finer tweaks might be necessary to enhance error messages by replacing failures with more suitable types rather than 'never'.

If required, alternative strategies like utilizing a builder pattern to incrementally construct objects through staged inference could offer a workaround that aligns better with the existing capabilities of the inference system.

You do not necessarily need to follow the current path if this is new implementation - solutions that leverage the strengths of the inference mechanism could provide a smoother process.

Answer 2

The issue at hand arises from the limited capability of TypeScript to infer generic type parameters and contextually type function parameters simultaneously. The inference algorithm consists of a set of practical heuristics that works well in many common scenarios, but it falls short as it is not an exhaustive unification algorithm that guarantees accurate assignment of types to all generic type arguments and unannotated values, as suggested in microsoft/TypeScript#30134 (not yet implemented).

While generic type parameters can be successfully inferred in certain cases:

declare function foo<T>(x: (n: number) => T): T
foo((n: number) => ({ a: n })) // Inference successful for T as {a: number}

and similarly unannotated function parameters can also be inferred:

declare function bar(f: (x: { a: number }) => void): void;
bar(x => x.a.toFixed(1)) // Inference successful for x as {a: number}

there are limitations when attempting both simultaneously, especially with multiple function arguments and the inference flow moving from left to right:

declare function baz<T>(x: (n: number) => T, f: (x: T) => void): void;
baz((n) => ({ a: n }), x => x.a.toFixed(1))
// Inference results: n as number, T as {a: number}, x as {a: number}

However, such simultaneous inference sometimes fails. Prior to TypeScript 4.7, a scenario like the following would not correctly infer the desired types:

declare function qux<T>(arg: { x: (n: number) => T, f: (x: T) => void }): void;
qux({ x: (n) => ({ a: n }), f: x => x.a.toFixed(1) })
// TS 4.6: n inferred as number, T failed to infer, x failed to infer
// TS 4.7: n inferred as number, T inferred as {a: number}, x inferred as {a: number}

This was resolved in TypeScript 4.7 with microsoft/TypeScript#48538. However, the algorithm is still not flawless.

In situations involving complex inference paths due to contextual typing, the system may fail to correctly determine types.

Your provided code example faces challenges with mapped types inference and callback parameter inference occurring concurrently, hence leading to errors. For instance:

function ops<T extends { [key: string]: any }, O extends Ops<T>>(spec: O): O {
    return spec;
}

This structure would never work due to generic constraints not serving as inference sites per microsoft/TypeScript#7234. One potential solution could involve adjusting the approach, such as:

function ops<T>(spec: Ops<T>): Ops<T> { // Infer from mapped type
    return spec;
}

resulting in improved inference. Nevertheless, finer tweaks might be necessary to enhance error messages by replacing failures with more suitable types rather than 'never'.

If required, alternative strategies like utilizing a builder pattern to incrementally construct objects through staged inference could offer a workaround that aligns better with the existing capabilities of the inference system.

You do not necessarily need to follow the current path if this is new implementation - solutions that leverage the strengths of the inference mechanism could provide a smoother process.

What is the best way to document a collection of generic interfaces while ensuring that they adhere to specific

Answer №1

Similar questions

Angular 5 is encountering an error with a recursive template, specifically a RangeError stating that the maximum call stack

Guide to setting the order of rendering in React applications

The preflight request in Angular2 is being rejected due to failing the access control check: The requested resource does not have the 'Access-Control-Allow-Origin' header

Angular 6: Issue with displaying data on the user interface

Changing an Angular template.html into a PDF document within an Angular 2 application can be achieved by utilizing

It appears that TypeScript is generating incorrect 'this' code without giving any warning

Having trouble deciding between flatMap and concatMap in rxJs?

Issue with rejecting a promise within a callback function in Ionic 3

Is it possible to toggle between namespace and class using parentheses?

Mistakes following update to Angular 4 from Angular 2

Angular2 and ES6 Promise in JavaScript - tackling the issue of undefined variables

Issue locating name (generics) in Angular 4

Building an interactive menu in Angular: A step-by-step guide

Troubleshooting a deletion request in Angular Http that is returning undefined within the MEAN stack

Assign the chosen option in the Angular 2 dropdown menu to a specific value

Not all generic types specified with an extends clause are appropriately narrowed down as expected

Divide the code into individual components within Angular 2 projects

Passing the value of an Angular component to a different component

Update name of an angular 2 component template

Encountered a React select error following an upgrade: specifically, a TypeError stating that dispatcher.useInsertionEffect is not