add S.create for creating Sanctuary modules with custom environments

[davidchambers]

Closes #188

I'd like to receive feedback from at least two people before merging this pull request, as this is a significant API change.

[kedashoe]

Played around with this for a bit. Because of sanctuary-js/sanctuary-def#52, sanctuary already tolerates many things not in its environment, right? Some notes while playing around:

• How about moving the "Type Checking" section above the "Type" section, renaming it "Getting Started", and adding a bit more meat to it. The "Type" section is great but it is pretty dense I feel. Might be nice to have a full example that included adding some type to the env that users could just copy paste (or of course play around with in the repl)
• What can a user add to the environment? If I have

var Car = function(make, model) {...}
Car.prototype = {...}

can I do const S = S.create(true, S.env.concat([Car]));?

• Followup: what does this give me as a user? Catch more errors? Better error messages?
• I think this might have been discussed a bit already, but what about using an options object for S.create? A couple things in favor:
  • the 2nd parameter feels pretty awkward when it is S.env, which might be pretty common?
  • passing booleans to functions feels awkward to me, I like having the keys, S.create({checkTypes: true});
  • easily extendable
• Only loosely related to this PR, but it would be cool if $.RecordType returned a constructor/type rather than just a type.

const Point = $.RecordType({x: Number, y: Number});
S = S.create(true, S.env.concat([Point]));
let p = Point(10, 20);

I think this would also help sanctuary-def know that it actually received a type rather than just some StrMap if the keys are homogenous?

[kedashoe]

Another thought: a section about using sanctuary and sanctuary-def with and without eachother (of course sanctuary itself depends on sanctuary-def, but from a users perspective). Can I use them alone? What would that look like? Why might I? Do they play well together? What does

MaybeType :: Type -> Type
A UnaryType for use with sanctuary-def.

mean? etc..

[davidchambers]

Thank you for the thoughtful feedback, Kevin. The reason I haven't yet responded is that I haven't yet had time to write an equally thoughtful response.

[davidchambers]

[W]hat about using an options object for S.create?

⚡

[davidchambers]

How about moving the "Type Checking" section above the "Type" section, renaming it "Getting Started", and adding a bit more meat to it. The "Type" section is great but it is pretty dense I feel.

Understanding S.create should not be necessary in order to get started with Sanctuary; const S = require('sanctuary'); should suffice.

The position of the "Type Checking" section is appropriate for what I consider to be advanced material.

Might be nice to have a full example that included adding some type to the env that users could just copy paste (or of course play around with in the repl)

I love this suggestion. I've added such an example to the S.create documentation. Let me know what you think. :)

What can a user add to the environment? [Do constructor functions act as types?]

Perhaps it's better to cover this in the sanctuary-def documentation. What do you think?

Followup: what does this give me as a user? Catch more errors? Better error messages?

In most cases custom types needn't be included in the environment, as the environment is only necessary for resolving type variables. I'd like users to assume that the default environment is fine, and only provide a custom environment if the need arises.

This pull request is ready for final review. We're close to a v0.11.0 release. :)

[kedashoe]

I've added such an example to the S.create documentation. Let me know what you think. :)

Good old identity :) It's a bit hard for me to imagine how it will all look without seeing it on the site, but I like it.

Understanding S.create should not be necessary in order to get started with Sanctuary; const S = require('sanctuary'); should suffice.

Perhaps it's better to cover this in the sanctuary-def documentation. What do you think?

I think you are probably right on both counts. I just kind of get the feeling I want to really understand sanctuary-def to better use sanctuary. Something like the sanctuary-def docs would be pretty dry, API-like, while sanctuary.org really explains everything, including sanctuary-def. It is difficult though to balance getting started vs kitchen sink. In any event, I'm not trying to delay 0.11, I'm sure we don't need to really nail down where all this stuff should go to get it out the door

thumbs up!

[svozza]

We should S.keys here. 😉

[davidchambers]

Good point!

[davidchambers]

We can't actually use S.keys here, since S is not a member of StrMap a. I've replaced R.keys with Object.keys (which reads nicely for getting the names of a record's fields).

[Avaq]

I've looked over the code of this PR many times (every time I get a notification) and started writing this comment almost as often. Every time I try I end up writing massive comments that when proof reading seem to always diverge too much from the subject matter and have no clear point. I keep deciding in the end not to post. I should though, because @davidchambers is waiting for a second reviewer.

I'll try to summarize:

• I think this is a step in the right direction
• I have many slightly related ideas, but it seems I can't quite express them without being vague. I need to think some more about them, and once the thoughts are coherent I'll create issues for them in sanctuary-def. ;)
• The code looks good to me 👍

[davidchambers]

Thanks for your comment, @Avaq.

I have many slightly related ideas, but it seems I can't quite express them without being vague. I need to think some more about them, and once the thoughts are coherent I'll create issues for them in sanctuary-def.

Sounds great! The thoughts you've shared regarding extensible environments are intriguing.

[Avaq]

I took the time to write down those ideas I mentioned: sanctuary-js/sanctuary-def#74