From cc412f90216956a722b7ddd19e08c76eb5e5a902 Mon Sep 17 00:00:00 2001 From: Natalie Weizenbaum Date: Thu, 13 May 2021 16:44:38 -0700 Subject: [PATCH] Add a specification for the JS API importer's `this` context (#3052) This will allow me to write a fast-track proposal to add metadata about whether a load is coming from `@import` or not, to address webpack-contrib/sass-loader#905. --- spec/js-api.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 spec/js-api.md diff --git a/spec/js-api.md b/spec/js-api.md new file mode 100644 index 0000000000..c0afa15c6d --- /dev/null +++ b/spec/js-api.md @@ -0,0 +1,47 @@ +# JavaScript API + +Sass implementations that are available for use via JavaScript must expose the +following JavaScript API. As with the rest of this specification, they must not +add custom extensions that aren't shared across all implementations. + +> Having a shared, consistent API makes it easy for users to move between Sass +> implementations with minimal disruption, and for build system plugins to +> seamlessly work with multiple implementations. + +As with other sections of this specification, the specification of the JS API is +incomplete, and is added to *lazily*. This means that portions of the spec are +only written when they're necessary as background for new API proposals. + +## Table of Contents + +* [Importers](#importers) + * [`this` Context](#this-context) + +## Importers + +### `this` Context + +When running an importer callback, JavaScript's `this` must refer to an object +with an `options` field. This field's value must be an object with the following +fields: + +* `file`: The `file` option passed to the `render()` call. +* `data`: The `data` option passed to the `render()` call. +* `includePaths`: A string that contains the current working directory followed + by strings passed in the `includePaths` option, separated by `";"` on Windows + and `":"` elsewhere. +* `precision`: The number 10. +* `style`: An integer. The specific semantics of this are left up to the + implementation. (The reference implementation always returns 1.) +* `indentType`: The number 1 if the `indentType` option was `tab`. The number 0 + otherwise. +* `indentWidth`: An integer indicating the number of spaces or tabs emitted by + the compiler for each level of indentation. +* `linefeed`: A string indicating the linefeed character or character sequence + emitted by the compiler at the end of each line. +* `result`: An object with a `stats` field, whose value is an object with the + following fields: + * `start`: The number of milliseconds since the Unix epoch (1 January 1970 + 00:00:00 UT) at the point at which the user called `render()`. + * `entry`: The `file` option passed to the `render()` call, or the string + `"data"` if no file was passed.