Improve usability of `@rescript/std` as a pure js library

[bobzhang]

• install interface file as a reference
• take advantage of gentype to generate typescript declaration files

[johnridesabike]

Would it make sense to add an "exports" field to package.json? https://nodejs.org/api/packages.html#packages_conditional_exports

{
  "exports": {
    "./package.json": "./package.json",
    "./belt_Array": {
      "import": "./lib/es6/belt_Array.mjs",
      "require": "./lib/js/belt_Array.js"
    },
    "./belt_List": {
      "import": "./lib/es6/belt_List.mjs",
      "require": "./lib/js/belt_List.js"
    }
   // etc
  }
}

I'm not sure how much of a maintenance burden that would add, but it may be nice if we expect JS users to access the library. They could import modules like this:

import * as Array from "@rescript/std/belt_Array";
// or
const Array = require("@rescript/std/belt_Array");

You can also include a catch-all export so users can still access files directly:

{
  "exports": {
    // other exports go here
    "./lib/*": "./lib/*"
  }
}

[Coobaha]

Hi! I would love to know if there are plans to step even further towards publishing Rescript packages for public use in JS ecosystems?

Current state from my point of view is that in RE world authors are publishing .re* files as is, so consumers of this libs usually have to build it again with the correct version of compiler. I think this is a big game stopper for adoption of Rescript in JS ecosystem.

In comparison tsc generates interface files .d.ts and transpiled js code and knows how just read .d.ts without actual source

How it can be Compiler outputs JS file, type interfaces for Flow/TS and special file, like D.REI that will contain all type information which is needed and maybe some meta, like compiler compatibility.

• When working in JS -> workflow is normal, people just require JS files and use type interfaces for Flow and TS
• When using in RE scope -> compiler reads this special .D.REI files without compilation step and uses JS files in runtime as they have interface defined in .D.REI.

Probably you are very aware of this problem and publishing stdlib to own package is a step towards this, but it would be nice if compiler provides ways of publishing arbitrary package with transitive RE deps without worrying that consumers will need to build it again.

Gentype related issue https://github.com/reason-association/genType/issues/462

cc @bobzhang @cristianoc

Maybe @kitten Also can comment this as https://github.com/kitten/wonka is an outstanding example how packages should be published without the need to build them again. I can assume that it brings a lot of limitations to project

[bobzhang]

from my point of view is that in RE world authors are publishing .re* files as is

Actually we always recommend to check in the generated js files. It builds confidence when you upgrade the compiler and check the diffs.

Something I wish is that we can generate .d.ts from .rei so that works better with code editors

[Coobaha]

Actually we always recommend to check in the generated js files. It builds confidence when you upgrade the compiler and check the diffs.

I very agree with it, but with this recommendation in my mind - how one consumes RES dependencies in RES project (in other words benefits from type system instead of writing bindings) and produces JS for users outside of RES? TS solves this by reading .d.ts without compilation

There could be breaking changes in runtime representations between compiler versions obviously, but it could be restricted to consume only valid version range or bailing with incompatibility error?

Even with @rescript/std - Imagine, if at some point there will be a need to include dependency from npm registry that is published as Rescript project (for instance std will be split into multiple packages and there will be one package that core consumes some or all of them) - it won't be possible to use it directly, as it will force end users to re-build @rescript/std. Currently only viable option is to vendor RES code (or writing bindings but this is meh and obviously not viable at all)

[bobzhang]

There could be breaking changes in runtime representations between compiler versions obviously, but it could be restricted to consume only valid version range or bailing with incompatibility error?

Indeed. Some suggestions: if you maintain the downstream actively, such breakage is ok since you can fix it quickly. Otherwise, create a compatibility package which only exports things you need. This seems a language agnostic thing, isn't it?

re-build @rescript/std

What does it mean?

[Coobaha]

Indeed. Some suggestions: if you maintain the downstream actively, such breakage is ok since you can fix it quickly. Otherwise, create a compatibility package which only exports things you need. This seems a language agnostic thing, isn't it?

Yes for sure, just good to keep this in mind and thought that it is worth to mention :)

re-build @rescript/std What does it mean?

So for example, imagine if @rescript/std will be at some point split to:

• core std
• heavy extra std (for instance streams like wonka or rxjs)

Streams will be consuming core std, as it has nice primitives and utilities. What are the options to use it now?

• install std as JS package, write FFI bindings, no bsconfig dependencies.
• install it as Rescript package, add to bsconfig.json, force end users to pull compiler chain and build this package to use it.

What will be a real game changer for ReScript packages published to JS ecosystem is the way to consume ReScript packages without building them and just trusting some special interface file. This is currently a blocker for wide adoption of ReScript at Wolt. It feels wrong to publish packages to registry and asking users to build them again.

Quoting ReScript intro headline:

ReScript is the language for folks who don't necessarily love JavaScript, but who still acknowledge its importance. ReScript looks like JavaScript, works like JavaScript, works with JavaScript, and compiles to the highest quality of clean, readable and performant JavaScript, directly runnable in the browser and Node.js.

I believe improving publishing story will really help with this mission and will result in a much wider adoption rate. Language is nice and end users will be just using performant and runtime safe JS output produced by compiler. Adding bsconfig and compiler to every project pulling this back in my opinion. Also for library authors this adds lots of limitations and is a big headache.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.