@sass/types 1.93.2

package/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2016, Google Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,6 @@
+# @sass/types
+
+This package is a dual-publish of the [Sass JS API](https://sass-lang.com/documentation/js-api/)
+types. The `sass` and `sass-embedded` packages **still contain types**. This package is for
+users who _only_ need the Sass JS types (such as for `@types/gulp-sass`). It is published
+alongside every release of `sass` and `sass-embedded`, so you can always use the same version.

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@sass/types",
+  "version": "1.93.2",
+  "description": "A standalone types package for the Sass JS API",
+  "repository": "sass/sass",
+  "author": "Google Inc.",
+  "license": "MIT",
+  "exports": {
+    "types": "./types/index.d.ts"
+  },
+  "types": "types/index.d.ts",
+  "files": [
+    "types/**/*.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/types/compile.d.ts

@@ -0,0 +1,342 @@
+import {RawSourceMap} from 'source-map-js';
+
+import {Options, StringOptions} from './options';
+
+/**
+ * The result of compiling Sass to CSS. Returned by {@link compile}, {@link
+ * compileAsync}, {@link compileString}, and {@link compileStringAsync}.
+ *
+ * @category Compile
+ */
+export interface CompileResult {
+  /**
+   * The generated CSS.
+   *
+   * Note that this *never* includes a `sourceMapUrl` comment—it's up to the
+   * caller to determine where to save the source map and how to link to it from
+   * the stylesheet.
+   */
+  css: string;
+
+  /**
+   * The canonical URLs of all the stylesheets that were loaded during the
+   * Sass compilation. The order of these URLs is not guaranteed.
+   */
+  loadedUrls: URL[];
+
+  /**
+   * The object representation of the source map that maps locations in the
+   * generated CSS back to locations in the Sass source code.
+   *
+   * This typically uses absolute `file:` URLs to refer to Sass files, although
+   * this can be controlled by having a custom {@link Importer} return {@link
+   * ImporterResult.sourceMapUrl}.
+   *
+   * This is set if and only if {@link Options.sourceMap} is `true`.
+   */
+  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
+ * Exception}.
+ *
+ * This only allows synchronous {@link Importer}s and {@link CustomFunction}s.
+ *
+ * **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
+ *
+ * ```js
+ * const sass = require('sass');
+ *
+ * const result = sass.compile("style.scss");
+ * console.log(result.css);
+ * ```
+ *
+ * @category Compile
+ * @compatibility dart: "1.45.0", node: false
+ */
+export function compile(path: string, options?: Options<'sync'>): CompileResult;
+
+/**
+ * Asynchronously compiles the Sass file at `path` to CSS. Returns a promise
+ * that resolves with a {@link CompileResult} if it succeeds and rejects with an
+ * {@link Exception} if it fails.
+ *
+ * This only allows synchronous or asynchronous {@link Importer}s and
+ * {@link CustomFunction}s.
+ *
+ * **Heads up!** When using the `sass` npm package, **{@link compile} is almost
+ * twice as fast as {@link compileAsync}**, due to the overhead of making the
+ * entire evaluation process asynchronous.
+ *
+ * @example
+ *
+ * ```js
+ * const sass = require('sass');
+ *
+ * const result = await sass.compileAsync("style.scss");
+ * console.log(result.css);
+ * ```
+ *
+ * @category Compile
+ * @compatibility dart: "1.45.0", node: false
+ */
+export function compileAsync(
+  path: string,
+  options?: Options<'async'>
+): Promise<CompileResult>;
+
+/**
+ * Synchronously compiles a stylesheet whose contents is `source` to CSS. If it
+ * succeeds it returns a {@link CompileResult}, and if it fails it throws an
+ * {@link Exception}.
+ *
+ * This only allows synchronous {@link Importer}s and {@link CustomFunction}s.
+ *
+ * **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
+ * const sass = require('sass');
+ *
+ * const result = sass.compileString(`
+ * h1 {
+ *   font-size: 40px;
+ *   code {
+ *     font-face: Roboto Mono;
+ *   }
+ * }`);
+ * console.log(result.css);
+ * ```
+ *
+ * @category Compile
+ * @compatibility dart: "1.45.0", node: false
+ */
+export function compileString(
+  source: string,
+  options?: StringOptions<'sync'>
+): CompileResult;
+
+/**
+ * Asynchronously compiles a stylesheet whose contents is `source` to CSS.
+ * Returns a promise that resolves with a {@link CompileResult} if it succeeds
+ * and rejects with an {@link Exception} if it fails.
+ *
+ * This only allows synchronous or asynchronous {@link Importer}s and {@link
+ * CustomFunction}s.
+ *
+ * **Heads up!** When using the `sass` npm package, **{@link compileString} is
+ * almost twice as fast as {@link compileStringAsync}**, due to the overhead
+ * of making the entire evaluation process asynchronous.
+ *
+ * @example
+ *
+ * ```js
+ * const sass = require('sass');
+ *
+ * const result = await sass.compileStringAsync(`
+ * h1 {
+ *   font-size: 40px;
+ *   code {
+ *     font-face: Roboto Mono;
+ *   }
+ * }`);
+ * console.log(result.css);
+ * ```
+ *
+ * @category Compile
+ * @compatibility dart: "1.45.0", node: false
+ */
+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/deprecations.d.ts

@@ -0,0 +1,290 @@
+/**
+ * All of the deprecation types currently used by Sass.
+ *
+ * Any of these IDs or the deprecation objects they point to can be passed to
+ * `fatalDeprecations`, `futureDeprecations`, or `silenceDeprecations`.
+ */
+export interface Deprecations {
+  // START AUTOGENERATED LIST
+  // Checksum: 0d3df25297a4e76b865aee1e908baf355e26d665
+
+  /**
+   * Deprecation for passing a string directly to meta.call().
+   *
+   * This deprecation was active in the first version of Dart Sass.
+   */
+  'call-string': Deprecation<'call-string'>;
+
+  /**
+   * Deprecation for @elseif.
+   *
+   * This deprecation became active in Dart Sass 1.3.2.
+   */
+  elseif: Deprecation<'elseif'>;
+
+  /**
+   * Deprecation for @-moz-document.
+   *
+   * This deprecation became active in Dart Sass 1.7.2.
+   */
+  'moz-document': Deprecation<'moz-document'>;
+
+  /**
+   * Deprecation for imports using relative canonical URLs.
+   *
+   * This deprecation became active in Dart Sass 1.14.2.
+   */
+  'relative-canonical': Deprecation<'relative-canonical'>;
+
+  /**
+   * Deprecation for declaring new variables with !global.
+   *
+   * This deprecation became active in Dart Sass 1.17.2.
+   */
+  'new-global': Deprecation<'new-global'>;
+
+  /**
+   * Deprecation for using color module functions in place of plain CSS functions.
+   *
+   * This deprecation became active in Dart Sass 1.23.0.
+   */
+  'color-module-compat': Deprecation<'color-module-compat'>;
+
+  /**
+   * Deprecation for / operator for division.
+   *
+   * This deprecation became active in Dart Sass 1.33.0.
+   */
+  'slash-div': Deprecation<'slash-div'>;
+
+  /**
+   * Deprecation for leading, trailing, and repeated combinators.
+   *
+   * This deprecation became active in Dart Sass 1.54.0.
+   */
+  'bogus-combinators': Deprecation<'bogus-combinators'>;
+
+  /**
+   * Deprecation for ambiguous + and - operators.
+   *
+   * This deprecation became active in Dart Sass 1.55.0.
+   */
+  'strict-unary': Deprecation<'strict-unary'>;
+
+  /**
+   * Deprecation for passing invalid units to built-in functions.
+   *
+   * This deprecation became active in Dart Sass 1.56.0.
+   */
+  'function-units': Deprecation<'function-units'>;
+
+  /**
+   * Deprecation for using !default or !global multiple times for one variable.
+   *
+   * This deprecation became active in Dart Sass 1.62.0.
+   */
+  'duplicate-var-flags': Deprecation<'duplicate-var-flags'>;
+
+  /**
+   * Deprecation for passing null as alpha in the JS API.
+   *
+   * This deprecation became active in Dart Sass 1.62.3.
+   */
+  'null-alpha': Deprecation<'null-alpha'>;
+
+  /**
+   * Deprecation for passing percentages to the Sass abs() function.
+   *
+   * This deprecation became active in Dart Sass 1.65.0.
+   */
+  'abs-percent': Deprecation<'abs-percent'>;
+
+  /**
+   * Deprecation for using the current working directory as an implicit load path.
+   *
+   * This deprecation became active in Dart Sass 1.73.0.
+   */
+  'fs-importer-cwd': Deprecation<'fs-importer-cwd'>;
+
+  /**
+   * Deprecation for function and mixin names beginning with --.
+   *
+   * This deprecation became active in Dart Sass 1.76.0.
+   */
+  'css-function-mixin': Deprecation<'css-function-mixin'>;
+
+  /**
+   * Deprecation for declarations after or between nested rules.
+   *
+   * This deprecation became active in Dart Sass 1.77.7.
+   * It became obsolete in Dart Sass 1.92.0.
+   */
+  'mixed-decls': Deprecation<'mixed-decls'>;
+
+  /**
+   * Deprecation for meta.feature-exists
+   *
+   * This deprecation became active in Dart Sass 1.78.0.
+   */
+  'feature-exists': Deprecation<'feature-exists'>;
+
+  /**
+   * Deprecation for certain uses of built-in sass:color functions.
+   *
+   * This deprecation became active in Dart Sass 1.79.0.
+   */
+  'color-4-api': Deprecation<'color-4-api'>;
+
+  /**
+   * Deprecation for using global color functions instead of sass:color.
+   *
+   * This deprecation became active in Dart Sass 1.79.0.
+   */
+  'color-functions': Deprecation<'color-functions'>;
+
+  /**
+   * Deprecation for legacy JS API.
+   *
+   * This deprecation became active in Dart Sass 1.79.0.
+   */
+  'legacy-js-api': Deprecation<'legacy-js-api'>;
+
+  /**
+   * Deprecation for @import rules.
+   *
+   * This deprecation became active in Dart Sass 1.80.0.
+   */
+  import: Deprecation<'import'>;
+
+  /**
+   * Deprecation for global built-in functions that are available in sass: modules.
+   *
+   * This deprecation became active in Dart Sass 1.80.0.
+   */
+  'global-builtin': Deprecation<'global-builtin'>;
+
+  /**
+   * Deprecation for functions named "type".
+   *
+   * This deprecation became active in Dart Sass 1.86.0.
+   * It became obsolete in Dart Sass 1.92.0.
+   */
+  'type-function': Deprecation<'type-function'>;
+
+  /**
+   * Deprecation for passing a relative url to compileString().
+   *
+   * This deprecation became active in Dart Sass 1.88.0.
+   */
+  'compile-string-relative-url': Deprecation<'compile-string-relative-url'>;
+
+  /**
+   * Deprecation for a rest parameter before a positional or named parameter.
+   *
+   * This deprecation became active in Dart Sass 1.91.0.
+   */
+  'misplaced-rest': Deprecation<'misplaced-rest'>;
+
+  /**
+   * Deprecation for configuring private variables in @use, @forward, or load-css().
+   *
+   * This deprecation became active in Dart Sass 1.92.0.
+   */
+  'with-private': Deprecation<'with-private'>;
+
+  // END AUTOGENERATED LIST
+
+  /**
+   * Used for any user-emitted deprecation warnings.
+   */
+  'user-authored': Deprecation<'user-authored', 'user'>;
+}
+
+/**
+ * Either a deprecation or its ID, either of which can be passed to any of
+ * the relevant compiler options.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export type DeprecationOrId = Deprecation | keyof Deprecations;
+
+/**
+ * The possible statuses that each deprecation can have.
+ *
+ * "active" deprecations are currently emitting deprecation warnings.
+ * "future" deprecations are not yet active, but will be in the future.
+ * "obsolete" deprecations were once active, but no longer are.
+ *
+ * The only "user" deprecation is "user-authored", which is used for deprecation
+ * warnings coming from user code.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export type DeprecationStatus = 'active' | 'user' | 'future' | 'obsolete';
+
+/**
+ * A deprecated feature in the language.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export interface Deprecation<
+  id extends keyof Deprecations = keyof Deprecations,
+  status extends DeprecationStatus = DeprecationStatus
+> {
+  /** The unique ID of this deprecation. */
+  id: id;
+
+  /** The current status of this deprecation. */
+  status: status;
+
+  /** A human-readable description of this deprecation. */
+  description?: string;
+
+  /** The version this deprecation first became active in. */
+  deprecatedIn: status extends 'future' | 'user' ? null : Version;
+
+  /** The version this deprecation became obsolete in. */
+  obsoleteIn: status extends 'obsolete' ? Version : null;
+}
+
+/**
+ * A semantic version of the compiler.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export class Version {
+  /**
+   * Constructs a new version.
+   *
+   * All components must be non-negative integers.
+   *
+   * @param major - The major version.
+   * @param minor - The minor version.
+   * @param patch - The patch version.
+   */
+  constructor(major: number, minor: number, patch: number);
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+
+  /**
+   * Parses a version from a string.
+   *
+   * This throws an error if a valid version can't be parsed.
+   *
+   * @param version - A string in the form "major.minor.patch".
+   */
+  static parse(version: string): Version;
+}
+
+/**
+ * An object containing all deprecation types.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export const deprecations: Deprecations;