thespyder / rescript-nodejs

Node bindings for ReScript

rescript-nodejs

Node.js bindings for ReScript

Requirements

Works on ReScript 10 or above. Supports uncurried mode in ReScript 11.

Installation

npm install rescript-nodejs

or

yarn add rescript-nodejs

Then add rescript-nodejs to bsconfig.json:

  "bs-dependencies": [
    "rescript-nodejs"
  ],

Goal of this library

Help all ReScript Node.js apps and libraries to be built faster by reducing the time spent on hand written bindings.

Non-Goals

• Have 100% coverage of Node.js api surface - Due to lack of testing and time for maintenance, it should only have enough surface to cover all common use cases. But it should have enough coverage that developers only rarely have to write a custom binding.
• PRs welcome if there's something you use a lot and think others will too.
• This library should be as low-level as possible (i.e. zero-cost) to allow for minimal context switching between offical Node.js documentation and the ReScript equilvalent. Due to the dynamic nature of the JS API, bending it to be idiomatic ReScript will lead to a ton of bikeshedding in design as well as sacrificing maintainability.

Principles

• When available, prefer binding to the promise version of the library instead of the callback version to reduce binding surface. Js.Promise2 is the new improved API.
• Use subtyping only where the benefit is substantial. Subtyping is used for various APIs that implement Node Streams, such as HTTP Request and Response, FileSystem streams, Crypto streams, and etc. This provides a single set of functions to manipulate and combine streams across different modules. For example:

Stream a file into stdout:

open NodeJs

Fs.createReadStream("/path")
  ->Stream.pipe(Process.stdout(Process.process))
  ->Stream.onError(_ => Js.log("handleError"))

Echo server:

open NodeJs

Http.createServer((request, response) => {
  request->Stream.onData(data => Js.log(data))
  request->Stream.pipe(response)->ignore
});

Contributing

We welcome and encourage anyone to contribute! In order to minimize confusion and avoid any wasted effort, here are some recommendations:

• If you notice a bug or a typo feel free to create an issue or submit a PR to fix it.
• If you want to request a feature/improvement, it's best to create an issue first and start a discussion. Don't spend a lot of valuable time and energy creating a pull request when it might not fit in with the project goals. Your PR may still be merged if it isn't based on an issue but expect to have a discussion first.
• If you notice gaps in the documentation and want to help fill them in, feel free to go straight to PR. Or create an issue and provide a draft of the docs you want to add.
• If you have concerns about implementation style or design decisions (e.g. type soundness, complexity, ergonomics, edge cases, etc.), please submit an issue voicing your concerns. Critique from the community is welcome. This library is only useful so long as it works for everyone!
• A changelog has finally been added, managed by changie. Please use this tool (available via yarn changie new) to add changelog entries.

License and Credits

All code is licensed as MIT. See LICENSE.

This project was forked from reason-nodejs after it was (or appeared to be) abandoned. If the original authors would like to re-engage please email me.

rescript-nodejs's Issues

How to use `Readline`?

Hi there,

I just started learning ReScript and I would like to use it for a NodeJS application. I'm trying to port this piece of NodeJS code to ReScript using rescript-nodejs but I can't find a way to use Readline module:

const fs = require('fs');
const readline = require('readline');

const rl = readline.createInterface({
  input: fs.createReadStream('sample.txt'),
  crlfDelay: Infinity
});

rl.on('line', (line) => {
  console.log(`Line from file: ${line}`);
});

I couldn't find any documentation on Readline module. Can you give me some hints? I just want to read a text file line by line.

If this is not the right place, where should I ask this kind of question?
Thanks.

Support uncurried mode

The biggest issue I had with uncurried was a compiler bug: rescript-lang/rescript-compiler#6517. This hasn't been released yet but I've confirmed it with a local compiler build.

However there is a limitation that doesn't seem like it can be fixed: rescript-lang/rescript-compiler#6531

The solution is just to offer multi-arg function types in the Event module.

rescript-nodejs/src/Event.res

Lines 24 to 25 in 83e9eba

	external fromString: string => t<'a => 'b, 'ty> = "%identity"
	external fromSymbol: Js.Types.symbol => t<'a => 'b, 'ty> = "%identity"

NodeJS.Stream.Readable.push should have bool return type

First, thank you for taking the time to make these bindings. They are extremely useful.

I see that push is defined with unit return type. It should have bool return type. The return value is needed for back-pressure.

Multi-arg event handling doesn't work

To support uncurried mode I patched the multi-argument event handler in a test. Turns out it was never actually used, so it triggers a compile failure
rescript-lang/rescript-compiler#6531 (comment)

It needs to be deleted unless someone finds an actual use for this and then I'll figure out how to implement it properly.

Version 14.3.0

Currently, the greatest version is 14.3.0 and the latest version is 14.2.1. Because of this, if a user sets their rescript-nodejs version to "^14.2.1", they will receive the older 14.3.0.

Publishing the current head of main as version 14.3.1 to resolve this issue.

Also, I noticed that the change here isn't backwards-compatible. Publishing the change as 14.3.0 from 14.2.0 violated NPM's semantic versioning convention.

Update to Rescript compiler v10.1?

I would like to use async/await from the 10.1 version of the compiler.

Can you provide instructions to build it or are you planning on updating the package soon?

types of Fs.stat and Fs.lstat different

According to Nodejs Document: lstat() is identical to stat(), except that if path is a symbolic link, then the link itself is stat-ed, not the file that it refers to ,The signatures should be same, But actually it is string => Js.Promise.t<Stats.t> = "lstat" for lstat and FileHandle.t => Js.Promise.t<Stats.t> = "stat" for stat

This code seems not to work with rescript 11.beta.2 and 3

I get the following error after newly adding this package to a new project:

> [email protected] build /home/jasoons/Documents/code/envio/envio-operator
> rescript build

Dependency on @ryyppy/rescript-promise
rescript: [5/5] src/Promise.cmj
rescript: [7/7] install.stamp
Dependency on rescript-nodejs
rescript: [58/118] src/Module-NodeJs.cmj
FAILED: src/Module-NodeJs.cmj

  We've found a bug for you!
  /home/jasoons/Documents/code/envio/envio-operator/node_modules/.pnpm/[email protected]/node_modules/rescript-nodejs/src/Module.res:1:9-19

  1 │ include Node_module
  2 │ 

  The module or file Node_module can't be found.
  - If it's a third-party dependency:
    - Did you list it in bsconfig.json?
    - Did you run `rescript build` instead of `rescript build -with-deps`
      (latter builds third-parties)?
  - Did you include the file's directory in bsconfig.json?

rescript: [79/118] src/Buffer-NodeJs.cmj
FAILED: src/Buffer-NodeJs.cmj

  We've found a bug for you!
  /home/jasoons/Documents/code/envio/envio-operator/node_modules/.pnpm/[email protected]/node_modules/rescript-nodejs/src/Buffer.res:1:10-20

  1 │ type t = Node.buffer
  2 │ open Js.TypedArray2
  3 │ 

  The module or file Node can't be found.
  - If it's a third-party dependency:
    - Did you list it in bsconfig.json?
    - Did you run `rescript build` instead of `rescript build -with-deps`
      (latter builds third-parties)?
  - Did you include the file's directory in bsconfig.json?

rescript: [97/118] src/Assert-NodeJs.cmj
FAILED: cannot make progress due to previous errors.
Failure: /home/jasoons/Documents/code/envio/envio-operator/node_modules/.pnpm/[email protected]/node_modules/rescript/linux/ninja.exe 
Location: /home/jasoons/Documents/code/envio/envio-operator/node_modules/rescript-nodejs/lib/bs
 ELIFECYCLE  Command failed with exit code 1.

I'll clone locally and investigate a bit - seems strange - but I also don't know what Node_module is.

Not compatible with Rescript V10

rescript: [27/118] src/Http2.ast
FAILED: src/Http2.ast

  We've found a bug for you!
  /Users/dsiu/code/playground/rescript-snippets/node_modules/rescript-nodejs/src/Http2.res:3:1-11:24

   1 │ type settingsObject
   2 │ 
   3 │ external settingsObject: (
   4 │   ~headerTableSize: int=?,
   . │ ...
  10 │   ~enableConnectProtocol: bool=?,
  11 │ ) => settingsObject = ""
  12 │ 
  13 │ module Http2Stream = {

  Not a valid global name 

How to use Process module?

Unless I am not seeing something very obvious, why is everything in Process module typed (t, ...) => ...?

Something as seemingly trivial as NodeJs.Process.exit(0) just wouldn't work.

NodeJS 16 API changes

It looks like timers/promises is the only new API:
https://epnovate.com/blog/whats-new-in-node-v16/

https://nodejs.org/api/timers.html#timers-promises-api

This will be a good chance to release the first of some breaking changes that are long overdue to leverage new ReScript capabilities.

Support rescript 11

FAILED: src/Module-NodeJs.cmj

  We've found a bug for you!
  /[[ project path ]]/node_modules/rescript-nodejs/src/Module.res:1:9-19

  1 │ include Node_module
  2 │ 

  The module or file Node_module can't be found.
  - If it's a third-party dependency:
    - Did you list it in bsconfig.json?
    - Did you run `rescript build` instead of `rescript build -with-deps`
      (latter builds third-parties)?
  - Did you include the file's directory in bsconfig.json?

rescript: [74/118] src/Buffer-NodeJs.cmj
FAILED: src/Buffer-NodeJs.cmj

  We've found a bug for you!
  /[[ project path  ]]/node_modules/rescript-nodejs/src/Buffer.res:1:10-20

  1 │ type t = Node.buffer
  2 │ open Js.TypedArray2
  3 │ 

readFileSyncWith should return string

--- a/src/Fs.res
+++ b/src/Fs.res
@@ -248,7 +248,7 @@ external openSyncWith: (string, ~flag: Flag.t=?, ~mode: int=?) => fd = "openSync
 @module("node:fs")
 external readFileSync: string => Buffer.t = "readFileSync"
 @module("node:fs")
-external readFileSyncWith: (string, readFileOptions) => Buffer.t = "readFileSync"
+external readFileSyncWith: (string, readFileOptions) => string = "readFileSync"

 @module("node:fs") external existsSync: string => bool = "existsSync"