TypeScript definitions?

[dead-claudia]

These would be useful IMO. I'm not very familiar with the API here or I would be willing to write a basic set for them, but Google searches are failing me here.

[yoshuawuyts]

@isiahmeadows I think there exist none at this point - the API is pretty stable, so writing them should be a clean process. Reckon if you were to write them, they'd be best put in a seperate repo. Hope this answers your question. Cheers!

[dominictarr]

@isiahmeadows no we don't currently have any typescript definitions. I'd be quite curious to see what this entails, and whether it is useful as, say, a spec etc.

Does typescript have any way of describing how a function will be called in the future? Just the other day I was explaining some distinctions about types of functions: https://github.com/davidchase/pull-dom-events/issues/1#issuecomment-230660629 but that doesn't say anything about their type signatures, but rather, their time signatures (if you will)

What would get added to the repo to add typescript signatures? I think @yoshuawuyts is worried about clutter (in our currently very terse codebase)

[yoshuawuyts]

Oh, perhaps I came off a bit harsh; def didn't mean it that way, apologies! - When I said "other repo" I was thinking about the definitely typed repository, should have linked to that.

[davidchase]

We add them to our repos for mostjs but in a separate directory like so https://github.com/mostjs/create/blob/master/type-definitions/index.d.ts

It seems some people prefer to use something if has those definitions? Im not a 100% sure myself since i don't personally use them.

[dead-claudia]

@dominictarr @yoshuawuyts

You could publish the TypeScript definition file side-by-side with the exported modules themselves, and it would just work. TypeScript is able to resolve npm modules, and that means import pull from 'pull-stream/pull' would load node_modules/pull-stream/pull.d.ts. This is actually now the current recommendation also, since 1. your definitions are also now versioned with the module they're describing, and 2. you don't need to deal with TSD/Typings/etc. to install whatever.

@davidchase It does make things much easier IMO.

[dead-claudia]

@dominictarr @yoshuawuyts BTW, you can see how I did it in my Thallium repo, where I did similar. It's much larger than this and with far fewer modules, but it does have multiple modules in its public API, and for every one of them, I keep a module next to it. For example, see thallium.js (bundle entry) and thallium.d.ts

Also, if you need a custom main, you can also include a custom definitions field in the package.json to refer to the definitions.

[dominictarr]

@isiahmeadows does the definitions field mean that we can have a directory of types that sits along side, say, docs https://github.com/pull-stream/pull-stream/tree/master/docs and has the same internal structure? because that would be tidy, and not feel like clutter to someone who isn't using typescript.

[dead-claudia]

@dominictarr

1. I meant typings, not definitions (I misremembered the name).
2. It works just like normal Node modules, just with .d.ts instead of .js, etc. They are even resolved the same way, just instead to a different file. Sadly, there is no path mapping for library writers (although it exists for end users), and that'll hit this repo pretty hard, given the number of modules. It might be possible to limit the definitions to index.d.ts, pull.d.ts, sources/index.d.ts, throughs/index.d.ts, and sinks/index.d.ts, since the modules are almost all microscopic (about 80% of the API modules from what I found were less than 25 lines of code), and shouldn't become a size burden at all. You could import {concat} from 'pull-stream/sinks' pretty easily, for example.