5

TL;DR I want to create TypeScript typings for compiled PureScript modules, and distribute them in my npm package. I'm more than happy to maintain these typings manually, I just can't figure out what I need to put in tsconfig.json (up and downstream) and package.json.

I have a project where the core functionality is implemented in PureScript with a TypeScript CLI, and all of this is ultimately distributed as JavaScript via npm. I've created a similar project with a simpler layout:

.
├── cli                   # TypeScript CLI project
│   ├── main.ts
│   └── tsconfig.json
│
├── output                # Compiled PureScript modules
│   └── People
│       ├── externs.json
│       └── index.js
│
├── src                   # PureScript source
│   └── People.purs
│
└── types                 # TypeScript types for PureScript modules
    └── People.d.ts

In src/People.purs I define the core functionality:

module People where

type Person = { name :: String }

david :: Person
david = { name: "David "}

In types/People.d.ts I define TypeScript types for PureScript modules so I can safely use them from TypeScript:

declare module "People" {
    export interface Person {
        name: string;
    }

    export const david: Person;
}

Finally, in cli/main.ts, I want to import the compiled PureScript modules with the TypeScript types I've defined:

import * as People from "People";

console.log(People.david);

I can get this to build, but when I try to run the ultimate JavaScript (node cli/main.js), the require calls generated by tsc fail because they don't use absolute paths--require("People") should be require("./People") in this case. Making the import statements in TypeScript relative disassociates the typings.

I'm having a hard time meeting these goals:

  • Maintain TypeScript typings for all PureScript modules imported from TypeScript.
  • Ensure that TypeScript typechecks.
  • Ensure that require calls for PureScript modules resolve at runtime.
  • Distribute TypeScript typings with npm package, so that TypeScript consumers can use these typings as well.

If you have experience requiring PureScript modules from TypeScript, and distributing all of this via npm, I would really appreciate some guidance!

David Siegel
  • 1,604
  • 11
  • 13

3 Answers3

2

Your Purescript module is called "Person", but should be "People". I think with relative path importing you might get partially there, but i don't think there's such thing as relative path typing in d.ts files.

I checked out your project and renamed the module, then I set allowJs to true and typed the module inline:

import * as OutputPeople from "../output/People";

type Person = {
  name: string;
};

type PeopleModule = {
  david: Person
}

const People: PeopleModule = OutputPeople

console.log(People.david);

I put my modifications up on a branch here: https://github.com/justinwoo/ps-js-ts-interop/commit/fc7c1239f9d1bac1cf2bea35f7a07d30c46a5f64

kakigoori
  • 1,218
  • 10
  • 20
  • Ah, yes, I see the typo but that's not the issue. I tried the manual casting that you suggest and it worked, but the typings were not distributed with the npm, so clients of my library didn't get the types. – David Siegel Sep 30 '17 at 19:39
2

If you definitely need to use the absolute path to require your PureScript packages (e.g. import * as People from 'People'), I think you will need to hack around the node module resolution algorithm (by placing your PureScript output in a node_modules subdirectory of ./output, for example).

But if that is not as important and you're fine with relative imports (like import * as People from './People'), you can do the following:

  1. Use relative imports for PureScript modules:

    cli/main.ts:

    import * as People from './People';

  2. Place your PureScript types side by side with your TypeScript sources:

    .
├── People
│   └── index.d.ts
├── main.ts
└── tsconfig.json

  3. Change your PureScript types to be local module declarations instead of global:

    cli/People/index.d.ts:

    export interface Person {
    name: string;
}

export const david: Person;

  4. Now, to make it work with Node module resolution, you need to place your JS output from both compilers in the same directory. We also want for TypeScript to emit type declarations for our TS files (to be consumable when published on npm). We're also removing the paths TS compiler option (no longer needed), and adding global type reference for Node types.

    cli/tsconfig.json:

    {
  "compilerOptions": {
    "target": "es5",
    "lib": ["es2015"],
    "moduleResolution": "node",
    "baseUrl": ".",
    "outDir": "./../output",
    "types": [
      "node"
    ],
    "declaration": true
  },
  "include": [
      "*.ts"
  ]
}

  5. Almost done. Now, we need to make sure that type definitions for PureScript modules end up in the output directory to be available for consumption. TypeScript will not copy .d.ts files in its output when generating type definition output (since these were not created by the TS compiler) – we need to compensate for that. I don't know whether this is the best (or even a good?) way to achieve this, but the following worked for me:

    package.json:

    "scripts": {
  "build": "pulp build && tsc -P cli/tsconfig.json && cd cli && rsync -am --include='*.d.ts' -f 'hide,! */' . ./../output"
},
...

  6. Last but not least, we need to specify the entry point for JS and for type definitions for npm consumers:

    package.json:

    "main": "output/main.js",
"typings": "output/main.d.ts",
"files": [
  "output/"
]
...

I believe this does not cover all the details of creating a mixed-language and mixed-type npm package, but hopefully this can serve as a starting point.

MisterMetaphor
  • 5,900
  • 3
  • 24
  • 31
  • Yeah, this is definitely the way this gets done in other setups as far as I know. And for making sure you have the correct types for individual types, I think some approach like using my Typescript codegen library would be best, like so: https://github.com/justinwoo/ps-js-ts-interop/tree/ohyes-codegen – kakigoori Oct 01 '17 at 22:40
  • Ah, perhaps this 'local modules' concept would be better than my namespaces approach? Are there advantages to one over the other? – David Siegel Oct 03 '17 at 00:01
  • @DavidSiegel The approach from my answer allows you have 1-to-1 mapping of modules and the file system – as if you would write these in TypeScript or JavaScript. It's also the correct mapping wr/t how you would import these modules from TypeScript (the correct way to import in your case is still `import * as People from './People'`). Your approach with namespaces makes them globally available (e.g. importable at top level modules from anywhere), which is probably not what you want if you're going to have a not completely flat module structure (naming conflicts, namespace pollution). – MisterMetaphor Oct 03 '17 at 05:06
0

Declaring namespaces rather than modules makes everything work. For example, in types/People.d.ts:

declare namespace People {
    export interface Person {
        name: string;
    }

    export const david: Person;
}

export = People;
export as namespace People;

After compiling PureScript modules and before compiling TypeScript, I cp types/People.d.ts output/People/index.d.ts. This makes the TypeScript code happy with the same absolute imports (e.g. import * as People from "People";), and TypeScript libraries also see these types without additional configuration.

A few issues remain, though:

  • I still have to relativize the PureScript module imports in the compiled TypeScript (by prepending ../ in a post-build step); consumers of my library don't have to do this, though, since it goes through npm and that magically makes it work.
  • I can't figure out how to export namespaces with periods, so modules like Data.Maybe are represented by namespaces like Data_Maybe.
  • I don't know much about namespaces vs. modules, so there may be other caveats.
David Siegel
  • 1,604
  • 11
  • 13