sass - npm Package Compare versions

Comparing version 1.69.7 to 1.70.0

package.json

@@ -1,1 +0,1 @@
-{"name":"sass","description":"A pure JavaScript implementation of Sass.","license":"MIT","bugs":"https://github.com/sass/dart-sass/issues","homepage":"https://github.com/sass/dart-sass","repository":{"type":"git","url":"https://github.com/sass/dart-sass"},"author":{"name":"Natalie Weizenbaum","email":"[e-mail]","url":"https://github.com/nex3"},"engines":{"node":">=14.0.0"},"dependencies":{"chokidar":">=3.0.0 <4.0.0","immutable":"^4.0.0","source-map-js":">=0.6.2 <2.0.0"},"keywords":["style","scss","sass","preprocessor","css"],"types":"types/index.d.ts","exports":{"types":"./types/index.d.ts","node":{"require":"./sass.node.js","default":"./sass.node.mjs"},"default":{"require":"./sass.default.cjs","default":"./sass.default.js"}},"version":"1.69.7","bin":{"sass":"sass.js"},"main":"sass.node.js"}
+{"name":"sass","description":"A pure JavaScript implementation of Sass.","license":"MIT","bugs":"https://github.com/sass/dart-sass/issues","homepage":"https://github.com/sass/dart-sass","repository":{"type":"git","url":"https://github.com/sass/dart-sass"},"author":{"name":"Natalie Weizenbaum","email":"[e-mail]","url":"https://github.com/nex3"},"engines":{"node":">=14.0.0"},"dependencies":{"chokidar":">=3.0.0 <4.0.0","immutable":"^4.0.0","source-map-js":">=0.6.2 <2.0.0"},"keywords":["style","scss","sass","preprocessor","css"],"types":"types/index.d.ts","exports":{"types":"./types/index.d.ts","node":{"require":"./sass.node.js","default":"./sass.node.mjs"},"default":{"require":"./sass.default.cjs","default":"./sass.default.js"}},"version":"1.70.0","bin":{"sass":"sass.js"},"main":"sass.node.js"}

sass.default.js

@@ -13,2 +13,6 @@ import * as immutable from "immutable"
 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;
@@ -15,0 +19,0 @@ export const SassArgumentList = _cliPkgExports.SassArgumentList;

types/compile.d.ts

@@ -41,2 +41,100 @@ import {RawSourceMap} from 'source-map-js';
 /**
+ * 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
@@ -48,7 +146,13 @@ * returns a {@link CompileResult}, and if it fails it throws an {@link
  *
- * **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
@@ -104,4 +208,4 @@ *
  *
- * **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
@@ -111,2 +215,8 @@ * messaging with worker threads and concurrent compilations being blocked on
  *
+ * 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
@@ -169,1 +279,69 @@ *
 ): 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>;

types/index.d.ts

@@ -6,3 +6,5 @@ // This is a mirror of the JS API definitions in `spec/js-api`, but with comments
 export {
+  AsyncCompiler,
   CompileResult,
+  Compiler,
   compile,
@@ -12,2 +14,4 @@ compileAsync,
   compileStringAsync,
+  initCompiler,
+  initAsyncCompiler,
 } from './compile';
@@ -14,0 +18,0 @@ export {Exception} from './exception';

No alert changes

Improved metrics

Total package byte prevSize

5197661

increased by0.42%

Lines of code

5309

increased by3.83%

Published versions last week

2

increased by100%

No dependency changes