Please ship TypeScript definitions

[SnarkBoojum]

Some definitions are available here.

Thanks

[ExplodingCabbage]

Looks like there's a process to deprecate the DefinitelyTyped types that we should follow when we do this - see DefinitelyTyped/DefinitelyTyped#20258 for an example.

[Rednas83]

Any updates?

[isaachinman]

@ExplodingCabbage @tmm1 Would you accept a PR to include the types from here directly into this repo?

[ExplodingCabbage]

@isaachinman sure, that'd save me some work figuring out how to do that and be a great start point.

[isaachinman]

Spent about 15 minutes updating the rollup config to emit types based on your JavaScript codebase. Unfortunately, those declarations are completely incorrect. You'd need to either rewrite the entire repo in TS, or at least annotate via jsdoc for proper types.

Until then, I think the straightforward thing to do is basically inline the @types/diff content and just publish it from within this package.

I've opened a PR and tested it against my own consuming application.

[ExplodingCabbage]

So, what I should have done before starting this (over at #591) is just try to correctly type a dummy version of one function like diffChars, specifically making sure it properly handles:

• the callback option (which makes the function return undefined)
• the timeout and maxEditDistance options (which make the function possibly return undefined), and
• the interaction between the two points above (the argument passed to the callback is nullable if and only if timeout or maxEditDistance is provided)

... all complete with some tests to make sure I'm getting it right.

This turns out to be a real pain in the arse, because TypeScript seems to have a lot of bugs with matching calls of overloaded functions to the right overload, and I do not have anything close to a detailed understanding of those bugs.

Here's the test-d.ts file I wrote in a new project (which I then checked with tsd):

import {expectType} from 'tsd';
import {ChangeObject, diffChars} from '.';

const result1 = diffChars('foo', 'bar', {ignoreCase: true});
expectType<ChangeObject<string>[]>(result1);

const result2 = diffChars('foo', 'bar');
expectType<ChangeObject<string>[]>(result2);

const result3 = diffChars('foo', 'bar', {timeout: 100});
expectType<ChangeObject<string>[] | undefined>(result3);

const result4 = diffChars('foo', 'bar', {maxEditDistance: 100});
expectType<ChangeObject<string>[] | undefined>(result4);

const result5 = diffChars('foo', 'bar', cbResult => {
    expectType<ChangeObject<string>[]>(cbResult)
});
expectType<undefined>(result5);

const result6 = diffChars('foo', 'bar', {
    callback: cbResult => {
        expectType<ChangeObject<string>[]>(cbResult);
    }
});
expectType<undefined>(result6);

const result7 = diffChars('foo', 'bar', {
    timeout: 100,
    callback: cbResult => {
        expectType<ChangeObject<string>[] | undefined>(cbResult)
    }
});
expectType<undefined>(result7);

And here's a way to define diffChars, with five overload signatures, that causes the above test file to pass:

export interface ChangeObject<T> {
  value: T
}

interface DiffCharsOptions {
  ignoreCase?: boolean;
}

export interface DiffCharsOptionsNonabortable extends DiffCharsOptions {
  callback?: NonabortableDiffCallback<string>
}

type DiffCharsOptionsAbortable = DiffCharsOptions & AsyncOptions & Partial<AbortableCallbackOption<string>>

interface TimeoutOption {
  timeout: number;
}

interface MaxEditDistanceOption {
  maxEditDistance: number;
}

interface NonabortableCallbackOption<T> {
  callback: NonabortableDiffCallback<T>
}

interface AbortableCallbackOption<T> {
  callback: AbortableDiffCallback<T>
}

export type NonabortableDiffCallback<T> = (result: ChangeObject<T>[]) => void;
export type AbortableDiffCallback<T> = (result: ChangeObject<T>[] | undefined) => void;

type AsyncOptions = TimeoutOption | MaxEditDistanceOption;

export function diffChars(
  oldStr: string,
  newStr: string,
  options: NonabortableDiffCallback<string>
): undefined;
export function diffChars(
  oldStr: string,
  newStr: string,
  options: DiffCharsOptionsAbortable & AbortableCallbackOption<string>
): undefined
export function diffChars(
  oldStr: string,
  newStr: string,
  options: DiffCharsOptionsNonabortable & NonabortableCallbackOption<string>
): undefined
export function diffChars(
  oldStr: string,
  newStr: string,
  options: DiffCharsOptionsAbortable
): ChangeObject<string>[] | undefined
export function diffChars(
  oldStr: string,
  newStr: string,
  options?: DiffCharsOptionsNonabortable
): ChangeObject<string>[]
export function diffChars(
  oldStr: string,
  newStr: string,
  options?: any
): ChangeObject<string>[] | undefined {
  if (typeof options === 'function') {
    setTimeout(() => {
      options([{value: 'bla'}]);
    }, 1000)
  } else {
    return [{value: 'bla'}];
  }
}

This was bizarrely difficult; lots of approaches that seem like they obviously logically should work just don't and I don't know why the fuck not. For example, if you swap the order of the second and third overloads, like this...

export function diffChars(
  oldStr: string,
  newStr: string,
  options: NonabortableDiffCallback<string>
): undefined;
export function diffChars(
  oldStr: string,
  newStr: string,
  options: DiffCharsOptionsNonabortable & NonabortableCallbackOption<string>
): undefined
export function diffChars(
  oldStr: string,
  newStr: string,
  options: DiffCharsOptionsAbortable & AbortableCallbackOption<string>
): undefined
export function diffChars(
  oldStr: string,
  newStr: string,
  options: DiffCharsOptionsAbortable
): ChangeObject<string>[] | undefined
export function diffChars(
  oldStr: string,
  newStr: string,
  options?: DiffCharsOptionsNonabortable
): ChangeObject<string>[]
export function diffChars(
  oldStr: string,
  newStr: string,
  options?: any
): ChangeObject<string>[] | undefined {
  if (typeof options === 'function') {
    setTimeout(() => {
      options([{value: 'bla'}]);
    }, 1000)
  } else {
    return [{value: 'bla'}];
  }
}

... then the test script no longer type checks, complaining that the final call (with timeout and callback) doesn't match any overload:

$ npx tsd

  index.test-d.ts:31:8
  ✖  29:4  No overload matches this call.
  The last overload gave the following error.
    Object literal may only specify known properties, and timeout does not exist in type DiffCharsOptionsNonabortable.  
  ✖  31:8  Parameter type ChangeObject<string>[] | undefined is declared too wide for argument type ChangeObject<string>[].                                                                                   
  ✖  34:0  Parameter type undefined is declared too wide for argument type never.                                                                                                                             

  3 errors

What the fuck, TypeScript? The overloads are literally the same, just in a different order. If an overload matched before, it should match now! How can the order of these overloads possibly matter at all when there's no way for a call to match both of them, and therefore the order in which they're checked against the call logically shouldn't be able to affect which one is chosen?! Yet it does matter - entirely incomprehensibly to me. I don't know how I could ever have known or predicted this; I just had to write comprehensive tests covering every legitimate way of calling the function, then figure out through arbitrary trial and error which ordering of overload signatures would magically make the compiler happy with all those calls. I hate this, but apparently the end result works.

Anyway, now that I've figured that out, it should be simple to fix my PR and get all the functions typed correctly.