sass 1.69.7 → 1.70.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/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 {