Overhaul JS Function API

[nex3]

• Proposal
• Tests
• Documentation
• Dart Sass
• Node Host

---

The JavaScript function API shared by Dart Sass and Node Sass needs an overhaul. The current API has a number of issues:

• Values are mutable. This goes against the grain of how values work within Sass, and makes it difficult to implement the API efficiently in Dart Sass.

• It's hard to verify argument types with a nice error. Compare to Dart Sass's assert*() functions.

• It's hard to follow Sass's conventions for dealing with objects, such as:

  • Treating false and null as falsey and everything else as truthy.
  • Treating all values as lists, and treating maps as lists of pairs.
  • Treating empty lists and empty maps as the same value.
  • Using 1-based indexes for lists and strings, and negative indexes to count from the back.
  • Indexing the Unicode codepoints of strings rather than UTF-16 code units.

• There's no representation of first-class function values.

• There's no representation of an argument list value that may contain keyword arguments.

• Maps are represented as a list of pairs, without any way of accessing a value using its key other than iterating through the entire list.

• Numbers represent their units as a single string in an undocumented format, making it very difficult to work with them if they have more than just a single numerator unit.

• The this context includes a bunch of undocumented information without a clear use-case.

We should design a new API that addresses these issues and makes it easy to write importers that work similarly to built-in Sass functions.

[nex3]

Reopening since we still need to track the progress and implementation of the proposal.

[nex3]

This proposal is now officially out for review. It will remain that way for at least a month (potentially longer depending on discussion), at which point we'll move on to implementation.

[nex3]

It's been a month and there have been no objections, so I'm going to mark the proposal as accepted and start merging it into the main spec directory.

[nex3]

This is now usable in Dart Sass 1.45.0-rc.1! We'd love people's feedback on it before we launch a full stable release some time next week.