add api option to allow switching to sass modern compiler

[marcalexiei]

New api option

• Close Deprecation Warning: The legacy JS API is deprecated and will be removed in Dart Sass 2.0.0 #159
• Close Spike: Support modern sass importer functions #154
• Related to Support sass-embedded #152

Add new optional api option to allow opt-in for sass modern compiler API.
Allowed values are:

• legacy (defaultOne) to preserve backward compatibility (consider to change this in a new major)
• modern uses compileStringAsync to compile sass code to css. The compile result transformations are the same of legacy option value.

Due to the new API structure the two syntax are handled inside a switch with two different blocks.

Code examples

// should default to legacy when `api` is not specified
sass({ options: { data: '', outputStyle: 'compact' } });

// should error when LegacyOptions are used with `api: 'modern'`
// @ts-expect-error
sass({ api: 'modern', options: { data: '', outputStyle: 'compact' } });

// should only accept api parameter
sass({ api: 'modern' });

// should correctly infer modern API options
sass({ api: 'modern', options: { style: 'compressed' } });

---

Refactors

In order to support the new syntax and retain backward compatibility different refactors have been made:

• processRenderResponse has been moved in a separate file inside utils
• getImporterList has been moved in a separate file inside utils and renamed to getImporterListLegacy, the same file houses the modern function variant: getImporterListModern
• src/types
  • removed unused rollup types
  • removed sass types aliases, now sass related types are imported from sass
  • RollupPluginSassOptions now is a type due the new api option
    • relevant unit tests are added
  • PluginState has been renamed to RollupPluginSassState and moved here
• src/utils/index content has been divided into 2 files with self-explanatory names:
  • src/utils/logger
  • src/utils/helpers
• Plugin transform function now is an async function

Pending PR tasks

• find a way to dedupe test code (use macro)
• silence deprecation warning in legacy tests used sass 1.78 which doesn't have legacy-js-api warning
• update README documentation
  • add api option
  • add reference to NodePackageImporter
• check logger function usages and consider to a prefix so user can clearly understand that they are coming from the plugin (e.g.: [rollup-plugin-sass]:) can be done in a separate PR

---

Follow up

• Check Suggestions: package improvements #140
  • drop old versions of node
  • convert package to ESM
  • add support to other sass runtimes using dynamic resolve (see web pack)
  • ...
• Consider using a modern package to resolve files (e.g.: import-meta-resolve)

---

Warning

Pending PRs:

• test(insertStyle): ensures that tests are run in sequence #165
• feat: output insertStyle as part of rollup bundle #163
• chore(CI): add Node 22 and Windows to test matrix #169

[elycruz]

LG - merging for further review.

[elycruz]

Good job @marcalexiei - One thing - I noticed you're using async here - Since we're (currently) supporting node versions ">= 10" I'm not sure we can just assume that all clients have support for async/await - Seems we may have to release a new (major) version of the plugin that makes this change. Thoughts?

[elycruz]

Also, when I say "we're supporting..." I mean by way of our 'package.json' file.

[marcalexiei]

From MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function#browser_compatibility

Async functions are supported from Node version 7.6.0. so this shouldn't be a breaking change.
(I haven't tested it out 😅).

Anyway if we are releasing this as a breaking change I would consider to make api: modern the default value.

---

Created a new issue #173

Also I would like to do another change before the next release:
I'm trying to use processor to generate CSS modules:

    sass({
      processor: async (styles, filePath) => {
        let scopedClassNames = {};
        const postcssProcessResult = await postcss([
          postcssModules({
            getJSON: (_, json) => {
              if (json) scopedClassNames = json;
            },
          }),
        ]).process(styles, {
          from: filePath,
        });

        return { ...scopedClassNames, css: postcssProcessResult.css };
      },

Right now the plugin always returns the css string as export default and I haven't found a clean solution to change it that using processor options.
Have you implemented something similar that I can use or do you know another way?

My possible solution is to allow processor output a new property (e.g.: cssModuleMap) that, if present will be used as default export. What do you think?

If you want to discuss this further I will open a separate issue since it is out of scope in this PR 😁.