types/npm-ramda

TypeScript's type definitions for Ramda

Status

Typing compatible with ramda@0.25.0 and typescript@~2.9.2 (strictFunctionTypes: false)

Note: many of the functions in Ramda are still hard to properly type in TypeScript, with issues mainly centered around partial application, currying, and composition, especially so in the presence of generics. And yes, those are probably why you'd be using Ramda in the first place, making these issues particularly problematic to type Ramda for TypeScript.

Features

support placeholder ( R.__ )
support partial import ( import map = require("ramda/src/map") )
support selectable overloads ( use 0-param: R.map<"11", "list">() )

Usage

The following command install the types from the dist branch, which is the newest version and contains selectable and placeholder types.

# using npm
npm install --save-dev types/npm-ramda#dist

# using yarn
yarn add --dev types/npm-ramda#dist

# using jspm
jspm install --dev github:types/npm-ramda@dist

# you can also choose which version to install using #<branch/commit/tag>
yarn add --dev types/npm-ramda#dist-simple # contains basic features
yarn add --dev types/npm-ramda#dist-selectable # contains selectable-overloads
yarn add --dev types/npm-ramda#dist-placeholder # contains placeholder

If you load Ramda via a script tag, install with the --global flag instead.

If not using npm/yarn, you may need to add these typings to paths in tsconfig.json:

For the full package:

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths" : {
       "ramda": [
         "location-of-types/npm-ramda-package/index"
       ]
     }
  }
}

If using partial imports:

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths" : {
       "ramda/src/*": [
         "location-of-types/npm-ramda-package/src/*"
       ]
     }
  }
}

Testing

This project uses dts-jest to test types and values simultaneously, so as to ensure our types are always up to date.

# test
yarn run test

# test with watching mode
yarn run test -- --watch

After you changed some tests/types, you have to run yarn run remap to update the diff-friendly snapshots, and you can see their diff clearly in generated files (./snapshots/*.ts).

(You can also run yarn run remap-watch to use it in watching mode.)

test files:

unit tests: ./tests/*.ts (test types)
integration tests: ./tests/ramda-tests.ts (test types and values)

Building types

# build types (./templates/*.ts -> ./ramda/dist/**/*.d.ts)
yarn run build

# build types with watching mode
yarn run build-watch

FAQ

Why are the typings here not carbon copies of the ones in the Ramda docs?

There are some differences, among which TypeScript's syntax, though the goal differs here as well: while the Ramda docs aim to explain the functions, the goal here is to accurately infer types within TypeScript. Longer version here.

Why does compose not infer well?

TypeScript cannot do backward inference as needed for compose (ref). The pipe variants work a bit better than the compose versions.

Contributing

Pull requests are welcome! If you'd like to help out, two good places to start are the issues as well as the tests.

Do note that all of the typings are now being generated (automatically) using the templates.

FeliciousX/npm-ramda