feat: migrate to TypeScript

[kentcdodds]

What: Migrate to TypeScript!!! 🔥

Why: Because TypeScript is great

How: Lots of clicky-clack on my keyboard

Checklist:

• Documentation
• Tests
• Ready to be merged
  

BREAKING CHANGE: the API for baseSort arguments now uses rankedValue instead of rankedItem
BREAKING CHANGE: Now using String.prototype.{startsWith,includes}. Older browsers must have a polyfill for these modern APIs.

[codecov]

Codecov Report

Merging #107 (1f2d9b4) into master (7158295) will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff            @@
##            master      #107   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            1         1           
  Lines          114       137   +23     
  Branches        28        31    +3     
=========================================
+ Hits           114       137   +23     

Impacted Files	Coverage Δ
src/index.ts	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7158295...1f2d9b4. Read the comment docs.

[kentcdodds]

I think I'm going to build-in a few things in kcd-scripts before merging this so I don't have to have that tsconfig.build.json file just to generate the type declarations.

[weyert]

Maybe specify a default type?

[rbusquet]

with interfaces (or even just &, but the interface API is cleaner IMO), you can get rid of this dependency:

interface RankingInfo {
  rankedValue: string
  rank: number
  keyIndex: number
  keyThreshold: number | undefined
}
interface IndexedItem<ItemType> {
  item: ItemType
  index: number
}
interface RankedItem<ItemType> extends RankingInfo, IndexedItem<ItemType> {}

declare function baseSortFn<ItemType>(
  a: RankedItem<ItemType>,
  b: RankedItem<ItemType>,
): number

[rbusquet]

for the declare function, I'd also prefer going with an interface. Unfortunately(? or maybe it's fine), this will cause a couple of other types you're exporting to be generics (but it's not terrible);

interface ValueGetterKey<ItemType> {
  (item: ItemType): string
}

interface BaseSorter<ItemType> {
  (a: RankedItem<ItemType>, b: RankedItem<ItemType>): number
}

interface KeyAttributesOptions<ItemType> {
  key?: string | ValueGetterKey<ItemType>
  threshold?: number
  maxRanking?: number
  minRanking?: number
}

type KeyOption<ItemType> =
  | KeyAttributesOptions<ItemType>
  | ValueGetterKey<ItemType>
  | string

// ItemType = unknown allowed me to make these changes without the need to change the current tests
interface MatchSorterOptions<ItemType = unknown> {
  keys?: Array<KeyOption<ItemType>>
  threshold?: number
  baseSort?: BaseSorter<ItemType>
  keepDiacritics?: boolean
}
// ...
function matchSorter<ItemType>(
  items: Array<ItemType>,
  value: string,
  options: MatchSorterOptions<ItemType> = {}, // I make sure to pass `ItemType` to the type I defaulted to unknown to get proper type inference
): Array<ItemType> {

[rbusquet]

here's the full patch I worked on https://gist.github.com/rbusquet/17a593712ebcc9ea973b18d0dfeea034

[jensmeindertsma]

I'd suggest making sure types are imported separately using the import type syntax 👍.

[marcosvega91]

💪 you are great !!

[kentcdodds]

I'm trying to figure out how to make this work for my UMD build (globals). Here's the generated type defs (I haven't applied the suggested changes yet):

import type { Merge } from 'type-fest';
declare type KeyAttributes = {
    threshold?: number;
    maxRanking: number;
    minRanking: number;
};
declare type RankingInfo = {
    rankedValue: string;
    rank: number;
    keyIndex: number;
    keyThreshold: number | undefined;
};
declare function valueGetterKey<ItemType>(item: ItemType): string;
declare function baseSortFn<ItemType>(a: Merge<RankingInfo, {
    item: ItemType;
    index: number;
}>, b: Merge<RankingInfo, {
    item: ItemType;
    index: number;
}>): number;
declare type KeyAttributesOptions = {
    key?: string | typeof valueGetterKey;
    threshold?: number;
    maxRanking?: number;
    minRanking?: number;
};
declare type KeyOption = KeyAttributesOptions | typeof valueGetterKey | string;
declare type MatchSorterOptions = {
    keys?: Array<KeyOption>;
    threshold?: number;
    baseSort?: typeof baseSortFn;
    keepDiacritics?: boolean;
};
declare const rankings: {
    CASE_SENSITIVE_EQUAL: number;
    EQUAL: number;
    STARTS_WITH: number;
    WORD_STARTS_WITH: number;
    CONTAINS: number;
    ACRONYM: number;
    MATCHES: number;
    NO_MATCH: number;
};
/**
 * Takes an array of items and a value and returns a new array with the items that match the given value
 * @param {Array} items - the items to sort
 * @param {String} value - the value to use for ranking
 * @param {Object} options - Some options to configure the sorter
 * @return {Array} - the new sorted array
 */
declare function matchSorter<ItemType>(items: Array<ItemType>, value: string, options?: MatchSorterOptions): Array<ItemType>;
declare namespace matchSorter {
    var rankings: {
        CASE_SENSITIVE_EQUAL: number;
        EQUAL: number;
        STARTS_WITH: number;
        WORD_STARTS_WITH: number;
        CONTAINS: number;
        ACRONYM: number;
        MATCHES: number;
        NO_MATCH: number;
    };
}
export { matchSorter, rankings, MatchSorterOptions, KeyAttributesOptions, KeyOption, KeyAttributes, RankingInfo, baseSortFn, valueGetterKey, };

How do I expose those to the global namespace? I tried following these instructions: https://mariusschulz.com/blog/declaring-global-variables-in-typescript But couldn't figure out why it wasn't working 🤔

[rbusquet]

@kentcdodds I don't know how it helps but I get TS to recognize types correctly if I add "types": "./dist/index.d.ts", to my package.json. Have you tried that?

[kentcdodds]

Yeah, that works. Though, if someone wants to import one of the bundled files that will not work, so I think for projects that use the --bundle flag for kcd-scripts build, I'll duplicate and rename that file to be a .d.ts for each of the built/bundled files so it "just works" even if they import a bundled file directly.

Also, I think I'll skip the UMD build for this.

From here, I think I know what changes need to be made in kcd-scripts to support this, so I'll do that and upgrade it here before continuing. Thanks!

[kentcdodds]

I think this will work very well: kentcdodds/kcd-scripts#176

Feedback welcome :)

[kentcdodds]

I figured out the best way to solve the bundling issue by simply generating the type defs, and then creating a match-sorter.cjs.d.ts, match-sorter.esm.d.ts, etc... that simply contains:

export * from ".";

Which will simply re-export the types in index.d.ts. Everything will just work™️

[kentcdodds]

@all-contributors please add @rbusquet for ideas and review

[allcontributors]

@kentcdodds

I've put up a pull request to add @rbusquet! 🎉

[kentcdodds]

@all-contributors please add @weyert for ideas and review

[allcontributors]

@kentcdodds

I've put up a pull request to add @weyert! 🎉

[kentcdodds]

@all-contributors please add @MichaelDeBoey for review

[allcontributors]

@kentcdodds

I've put up a pull request to add @MichaelDeBoey! 🎉

[github-actions]

🎉 This PR is included in version 6.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀