sass 1.69.7 → 1.71.0

package/sass.default.js

@@ -10,6 +10,10 @@ export const compile = _cliPkgExports.compile;
 export const compileAsync = _cliPkgExports.compileAsync;
 export const compileString = _cliPkgExports.compileString;
 export const compileStringAsync = _cliPkgExports.compileStringAsync;
+export const initCompiler = _cliPkgExports.initCompiler;
+export const initAsyncCompiler = _cliPkgExports.initAsyncCompiler;
+export const Compiler = _cliPkgExports.Compiler;
+export const AsyncCompiler = _cliPkgExports.AsyncCompiler;
 export const Logger = _cliPkgExports.Logger;
 export const SassArgumentList = _cliPkgExports.SassArgumentList;
 export const SassBoolean = _cliPkgExports.SassBoolean;

package/sass.node.mjs

@@ -4,6 +4,10 @@ export const compile = cjs.compile;
 export const compileAsync = cjs.compileAsync;
 export const compileString = cjs.compileString;
 export const compileStringAsync = cjs.compileStringAsync;
+export const initCompiler = cjs.initCompiler;
+export const initAsyncCompiler = cjs.initAsyncCompiler;
+export const Compiler = cjs.Compiler;
+export const AsyncCompiler = cjs.AsyncCompiler;
 export const Logger = cjs.Logger;
 export const SassArgumentList = cjs.SassArgumentList;
 export const SassBoolean = cjs.SassBoolean;
@@ -59,6 +63,22 @@ export default {
     defaultExportDeprecation();
     return cjs.compileStringAsync;
   },
+  get initCompiler() {
+    defaultExportDeprecation();
+    return cjs.initCompiler;
+  },
+  get initAsyncCompiler() {
+    defaultExportDeprecation();
+    return cjs.initAsyncCompiler;
+  },
+  get Compiler() {
+    defaultExportDeprecation();
+    return cjs.Compiler;
+  },
+  get AsyncCompiler() {
+    defaultExportDeprecation();
+    return cjs.AsyncCompiler;
+  },
   get Logger() {
     defaultExportDeprecation();
     return cjs.Logger;

package/types/compile.d.ts

@@ -37,6 +37,104 @@ export interface CompileResult {
   sourceMap?: RawSourceMap;
 }
 
+/**
+ * The result of creating a synchronous compiler. Returned by
+ * {@link initCompiler}.
+ *
+ * @category Compile
+ */
+export class Compiler {
+  /**
+   * Throws an error if constructed directly, instead of via
+   * {@link initCompiler}.
+   */
+  private constructor();
+
+  /**
+   * The {@link compile} method exposed through a Compiler instance while it is
+   * active. If this is called after {@link dispose} on the Compiler
+   * instance, an error will be thrown.
+   *
+   * During the Compiler instance's lifespan, given the same input, this will
+   * return an identical result to the {@link compile} method exposed at the
+   * module root.
+   */
+  compile(path: string, options?: Options<'sync'>): CompileResult;
+
+  /**
+   * The {@link compileString} method exposed through a Compiler instance while
+   * it is active. If this is called after {@link dispose} on the Compiler
+   * instance, an error will be thrown.
+   *
+   * During the Compiler instance's lifespan, given the same input, this will
+   * return an identical result to the {@link compileString} method exposed at
+   * the module root.
+   */
+  compileString(source: string, options?: StringOptions<'sync'>): CompileResult;
+
+  /**
+   * Ends the lifespan of this Compiler instance. After this is invoked, all
+   * calls to the Compiler instance's {@link compile} or {@link compileString}
+   * methods will result in an error.
+   */
+  dispose(): void;
+}
+
+/**
+ * The result of creating an asynchronous compiler. Returned by
+ * {@link initAsyncCompiler}.
+ *
+ * @category Compile
+ */
+export class AsyncCompiler {
+  /**
+   * Throws an error if constructed directly, instead of via
+   * {@link initAsyncCompiler}.
+   */
+  private constructor();
+
+  /**
+   * The {@link compileAsync} method exposed through an Async Compiler instance
+   * while it is active. If this is called after {@link dispose} on the Async
+   * Compiler instance, an error will be thrown.
+   *
+   * During the Async Compiler instance's lifespan, given the same input, this
+   * will return an identical result to the {@link compileAsync} method exposed
+   * at the module root.
+   */
+  compileAsync(
+    path: string,
+    options?: Options<'async'>
+  ): Promise<CompileResult>;
+
+  /**
+   * The {@link compileStringAsync} method exposed through an Async Compiler
+   * instance while it is active. If this is called after {@link dispose} on the
+   * Async Compiler instance, an error will be thrown.
+   *
+   * During the Async Compiler instance's lifespan, given the same input, this
+   * will return an identical result to the {@link compileStringAsync} method
+   * exposed at the module root.
+   */
+  compileStringAsync(
+    source: string,
+    options?: StringOptions<'async'>
+  ): Promise<CompileResult>;
+
+  /**
+   * Ends the lifespan of this Async Compiler instance. After this is invoked,
+   * all subsequent calls to the Compiler instance's `compileAsync` or
+   * `compileStringAsync` methods will result in an error.
+   *
+   * Any compilations that are submitted before `dispose` will not be cancelled,
+   * and will be allowed to settle.
+   *
+   * After all compilations have been settled and Sass completes any internal
+   * task cleanup, `dispose` will resolve its promise.
+   */
+  dispose(): Promise<void>;
+}
+
 /**
  * Synchronously compiles the Sass file at `path` to CSS. If it succeeds it
  * returns a {@link CompileResult}, and if it fails it throws an {@link
@@ -44,10 +142,16 @@ export interface CompileResult {
  *
  * This only allows synchronous {@link Importer}s and {@link CustomFunction}s.
  *
- * **Heads up!** When using the `sass-embedded` npm package,
- * **{@link compileAsync} is almost always faster than {@link compile}**, due to
- * the overhead of emulating synchronous messaging with worker threads and
- * concurrent compilations being blocked on main thread.
+ * **Heads up!** When using the [sass-embedded] npm package for single
+ * compilations, **{@link compileAsync} is almost always faster than
+ * {@link compile}**, due to the overhead of emulating synchronous messaging
+ * with worker threads and concurrent compilations being blocked on main thread.
+ *
+ * If you are running multiple compilations with the [sass-embedded] npm
+ * package, using a {@link Compiler} will provide some speed improvements over
+ * the module-level methods, and an {@link AsyncCompiler} will be much faster.
+ *
+ * [sass-embedded]: https://www.npmjs.com/package/sass-embedded
  *
  * @example
  *
@@ -99,12 +203,18 @@ export function compileAsync(
  *
  * This only allows synchronous {@link Importer}s and {@link CustomFunction}s.
  *
- * **Heads up!** When using the `sass-embedded` npm package,
- * **{@link compileStringAsync} is almost always faster than
+ * **Heads up!** When using the [sass-embedded] npm package for single
+ * compilations, **{@link compileStringAsync} is almost always faster than
  * {@link compileString}**, due to the overhead of emulating synchronous
  * messaging with worker threads and concurrent compilations being blocked on
  * main thread.
  *
+ * If you are running multiple compilations with the [sass-embedded] npm
+ * package, using a {@link Compiler} will provide some speed improvements over
+ * the module-level methods, and an {@link AsyncCompiler} will be much faster.
+ *
+ * [sass-embedded]: https://www.npmjs.com/package/sass-embedded
+ *
  * @example
  *
  * ```js
@@ -162,3 +272,71 @@ export function compileStringAsync(
   source: string,
   options?: StringOptions<'async'>
 ): Promise<CompileResult>;
+
+/**
+ * Creates a synchronous {@link Compiler}. Each compiler instance exposes the
+ * {@link compile} and {@link compileString} methods within the lifespan of the
+ * Compiler. Given identical input, these methods will return results identical
+ * to their counterparts exposed at the module root. To use asynchronous
+ * compilation, use {@link initAsyncCompiler}.
+ *
+ * When calling the compile functions multiple times, using a compiler instance
+ * with the [sass-embedded] npm package is much faster than using the top-level
+ * compilation methods or the [sass] npm package.
+ *
+ * [sass-embedded]: https://www.npmjs.com/package/sass-embedded
+ *
+ * [sass]: https://www.npmjs.com/package/sass
+ *
+ * @example
+ *
+ * ```js
+ * const sass = require('sass');
+ * function setup() {
+ *   const compiler = sass.initCompiler();
+ *   const result1 = compiler.compileString('a {b: c}').css;
+ *   const result2 = compiler.compileString('a {b: c}').css;
+ *   compiler.dispose();
+ *
+ *   // throws error
+ *   const result3 = sass.compileString('a {b: c}').css;
+ * }
+ * ```
+ * @category Compile
+ * @compatibility dart: "1.70.0", node: false
+ */
+export function initCompiler(): Compiler;
+
+/**
+ * Creates an asynchronous {@link AsyncCompiler}. Each compiler
+ * instance exposes the {@link compileAsync} and {@link compileStringAsync}
+ * methods within the lifespan of the Compiler. Given identical input, these
+ * methods will return results identical to their counterparts exposed at the
+ * module root. To use synchronous compilation, use {@link initCompiler};
+ *
+ * When calling the compile functions multiple times, using a compiler instance
+ * with the [sass-embedded] npm package is much faster than using the top-level
+ * compilation methods or the [sass] npm package.
+ *
+ * [sass-embedded]: https://www.npmjs.com/package/sass-embedded
+ *
+ * [sass]: https://www.npmjs.com/package/sass
+ *
+ * @example
+ *
+ * ```js
+ * const sass = require('sass');
+ * async function setup() {
+ *   const compiler = await sass.initAsyncCompiler();
+ *   const result1 = await compiler.compileStringAsync('a {b: c}').css;
+ *   const result2 = await compiler.compileStringAsync('a {b: c}').css;
+ *   await compiler.dispose();
+ *
+ *   // throws error
+ *   const result3 = await sass.compileStringAsync('a {b: c}').css;
+ * }
+ * ```
+ * @category Compile
+ * @compatibility dart: "1.70.0", node: false
+ */
+export function initAsyncCompiler(): Promise<AsyncCompiler>;

package/types/importer.d.ts

@@ -308,6 +308,139 @@ export interface Importer<sync extends 'sync' | 'async' = 'sync' | 'async'> {
   nonCanonicalScheme?: string | string[];
 }
 
+declare const nodePackageImporterKey: unique symbol;
+
+/**
+ * The built-in Node.js package importer. This loads pkg: URLs from node_modules
+ * according to the standard Node.js resolution algorithm.
+ *
+ * A Node.js package importer is exposed as a class that can be added to the
+ * `importers` option.
+ *
+ *```js
+ * const sass = require('sass');
+ * sass.compileString('@use "pkg:vuetify', {
+ *   importers: [new sass.NodePackageImporter()]
+ * });
+ *```
+ *
+ * ## Writing Sass packages
+ *
+ * Package authors can control what is exposed to their users through their
+ * `package.json` manifest. The recommended method is to add a `sass`
+ * conditional export to `package.json`.
+ *
+ * ```json
+ * // node_modules/uicomponents/package.json
+ * {
+ *   "exports": {
+ *     ".": {
+ *       "sass": "./src/scss/index.scss",
+ *       "import": "./dist/js/index.mjs",
+ *       "default": "./dist/js/index.js"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * This allows a package user to write `@use "pkg:uicomponents"` to load the
+ * file at `node_modules/uicomponents/src/scss/index.scss`.
+ *
+ * The Node.js package importer supports the variety of formats supported by
+ * Node.js [package entry points], allowing authors to expose multiple subpaths.
+ *
+ * [package entry points]:
+ * https://nodejs.org/api/packages.html#package-entry-points
+ *
+ * ```json
+ * // node_modules/uicomponents/package.json
+ * {
+ *   "exports": {
+ *     ".": {
+ *       "sass": "./src/scss/index.scss",
+ *     },
+ *     "./colors": {
+ *       "sass": "./src/scss/_colors.scss",
+ *     },
+ *     "./theme/*": {
+ *       "sass": "./src/scss/theme/*.scss",
+ *     },
+ *   }
+ * }
+ * ```
+ *
+ * This allows a package user to write:
+ *
+ * - `@use "pkg:uicomponents";` to import the root export.
+ * - `@use "pkg:uicomponents/colors";` to import the colors partial.
+ * - `@use "pkg:uicomponents/theme/purple";` to import a purple theme.
+ *
+ * Note that while library users can rely on the importer to resolve
+ * [partials](https://sass-lang.com/documentation/at-rules/use#partials), [index
+ * files](https://sass-lang.com/documentation/at-rules/use#index-files), and
+ * extensions, library authors must specify the entire file path in `exports`.
+ *
+ * In addition to the `sass` condition, the `style` condition is also
+ * acceptable. Sass will match the `default` condition if it's a relevant file
+ * type, but authors are discouraged from relying on this. Notably, the key
+ * order matters, and the importer will resolve to the first value with a key
+ * that is `sass`, `style`, or `default`, so you should always put `default`
+ * last.
+ *
+ * To help package authors who haven't transitioned to package entry points
+ * using the `exports` field, the Node.js package importer provides several
+ * fallback options. If the `pkg:` URL does not have a subpath, the Node.js
+ * package importer will look for a `sass` or `style` key at the root of
+ * `package.json`.
+ *
+ * ```json
+ * // node_modules/uicomponents/package.json
+ * {
+ *   "sass": "./src/scss/index.scss",
+ * }
+ * ```
+ *
+ * This allows a user to write `@use "pkg:uicomponents";` to import the
+ * `index.scss` file.
+ *
+ * Finally, the Node.js package importer will look for an `index` file at the
+ * package root, resolving partials and extensions. For example, if the file
+ * `_index.scss` exists in the package root of `uicomponents`, a user can import
+ * that with `@use "pkg:uicomponents";`.
+ *
+ * If a `pkg:` URL includes a subpath that doesn't have a match in package entry
+ * points, the Node.js importer will attempt to find that file relative to the
+ * package root, resolving for file extensions, partials and index files. For
+ * example, if the file `src/sass/_colors.scss` exists in the `uicomponents`
+ * package, a user can import that file using `@use
+ * "pkg:uicomponents/src/sass/colors";`.
+ *
+ * @compatibility dart: "2.0", node: false
+ * @category Importer
+ */
+export class NodePackageImporter {
+  /** Used to distinguish this type from any arbitrary object. */
+  private readonly [nodePackageImporterKey]: true;
+
+  /**
+   * The NodePackageImporter has an optional `entryPointDirectory` option, which
+   * is the directory where the Node Package Importer should start when
+   * resolving `pkg:` URLs in sources other than files on disk. This will be
+   * used as the `parentURL` in the [Node Module
+   * Resolution](https://nodejs.org/api/esm.html#resolution-algorithm-specification)
+   * algorithm.
+   *
+   * In order to be found by the Node Package Importer, a package will need to
+   * be inside a node_modules folder located in the `entryPointDirectory`, or
+   * one of its parent directories, up to the filesystem root.
+   *
+   * Relative paths will be resolved relative to the current working directory.
+   * If a path is not provided, the default value of `require.main.filename`
+   * will be used.
+   */
+  constructor(entryPointDirectory?: string);
+}
+
 /**
  * The result of successfully loading a stylesheet with an {@link Importer}.
  *

package/types/index.d.ts

@@ -3,11 +3,15 @@
 // implementations.
 
 export {
+  AsyncCompiler,
   CompileResult,
+  Compiler,
   compile,
   compileAsync,
   compileString,
   compileStringAsync,
+  initCompiler,
+  initAsyncCompiler,
 } from './compile';
 export {Exception} from './exception';
 export {
@@ -15,6 +19,7 @@ export {
   FileImporter,
   Importer,
   ImporterResult,
+  NodePackageImporter,
 } from './importer';
 export {Logger, SourceSpan, SourceLocation} from './logger';
 export {

package/types/legacy/options.d.ts

@@ -1,6 +1,7 @@
 import {Logger} from '../logger';
 import {LegacyImporter} from './importer';
 import {LegacyFunction} from './function';
+import {NodePackageImporter} from '../importer';
 
 /**
  * Options for {@link render} and {@link renderSync} that are shared between
@@ -508,6 +509,24 @@ export interface LegacySharedOptions<sync extends 'sync' | 'async'> {
    * @compatibility dart: "1.43.0", node: false
    */
   logger?: Logger;
+
+  /**
+   * If this option is set to an instance of `NodePackageImporter`, Sass will
+   * use the built-in Node.js package importer to resolve Sass files with a
+   * `pkg:` URL scheme. Details for library authors and users can be found in
+   * the {@link NodePackageImporter} documentation.
+   *
+   * @example
+   * ```js
+   * sass.renderSync({
+   *   data: '@use "pkg:vuetify";',
+   *   pkgImporter: new sass.NodePackageImporter()
+   * });
+   * ```
+   * @category Plugins
+   * @compatibility dart: "2.0", node: false
+   */
+  pkgImporter?: NodePackageImporter;
 }
 
 /**

package/types/options.d.ts

@@ -1,4 +1,4 @@
-import {FileImporter, Importer} from './importer';
+import {FileImporter, Importer, NodePackageImporter} from './importer';
 import {Logger} from './logger';
 import {Value} from './value';
 import {PromiseOr} from './util/promise_or';
@@ -208,8 +208,8 @@ export interface Options<sync extends 'sync' | 'async'> {
    * - The importer that was used to load the current stylesheet, with the
    *   loaded URL resolved relative to the current stylesheet's canonical URL.
    *
-   * - Each {@link Importer} or {@link FileImporter} in {@link importers}, in
-   *   order.
+   * - Each {@link Importer}, {@link FileImporter}, or
+   *   {@link NodePackageImporter} in {@link importers}, in order.
    *
    * - Each load path in {@link loadPaths}, in order.
    *
@@ -218,7 +218,7 @@ export interface Options<sync extends 'sync' | 'async'> {
    *
    * @category Plugins
    */
-  importers?: (Importer<sync> | FileImporter<sync>)[];
+  importers?: (Importer<sync> | FileImporter<sync> | NodePackageImporter)[];
 
   /**
    * Paths in which to look for stylesheets loaded by rules like