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

Issue with decorators not functioning in the latest alpha version of Sequelize v7

Accessing data from an API and showcasing information on a chart using Angular

Is there an alternative method to incorporate the 'environment.ts' file into a JSON file?

Tips on using Visual Studio Code to troubleshoot Angular 4 unit tests

Encountering an issue while attempting to initiate a nested array: "Cannot assign a value to an optional property access in the left-hand side of an assignment expression."

Confirm the Keycloak token by checking it against two separate URLs

What kind of Antd type should be used for the form's onFinish event?

In TypeScript, there is a curious phenomenon where private properties seem to be mimicking the

The issue of losing context when using Papaparse with an Angular 4 function

When employing GraphQL Apollo refetch with React, the update will extend to various other components as well

The error message "Property 'then' is not available on type 'void' within Ionic 2" is displayed

Setting an expiry date for Firestore documents

Unable to retrieve selected value from Flowbite-React Datepicker due to malfunctioning props change event

Display a free Admob banner within an Ionic 3 application

Angular 5 with Typescript encountered a failure in webpack due to the absence of the property "data" on the Response

Can we verify if this API response is accurate?

`transpilePackages` in Next.js causing Webpack issue when used with Styled Components

What could be the reason for typescript not issuing a warning regarding the return type in this specific function?

RxJS pipe operation ignoring observable

Displaying data from an Angular subscription in a user interface form