@sass/types 1.93.2

package/types/legacy/plugin_this.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The value of `this` in the context of a {@link LegacyImporter} or {@link
+ * LegacyFunction} callback.
+ *
+ * @category Legacy
+ * @deprecated This is only used by the legacy {@link render} and {@link
+ * renderSync} APIs. Use {@link compile}, {@link compileString}, {@link
+ * compileAsync}, and {@link compileStringAsync} instead.
+ */
+export interface LegacyPluginThis {
+  /**
+   * A partial representation of the options passed to {@link render} or {@link
+   * renderSync}.
+   */
+  options: {
+    /** The same {@link LegacyPluginThis} instance that contains this object. */
+    context: LegacyPluginThis;
+
+    /**
+     * The value passed to {@link LegacyFileOptions.file} or {@link
+     * LegacyStringOptions.file}.
+     */
+    file?: string;
+
+    /** The value passed to {@link LegacyStringOptions.data}. */
+    data?: string;
+
+    /**
+     * The value passed to {@link LegacySharedOptions.includePaths} separated by
+     * `";"` on Windows or `":"` on other operating systems. This always
+     * includes the current working directory as the first entry.
+     */
+    includePaths: string;
+
+    /** Always the number 10. */
+    precision: 10;
+
+    /** Always the number 1. */
+    style: 1;
+
+    /** 1 if {@link LegacySharedOptions.indentType} was `"tab"`, 0 otherwise. */
+    indentType: 1 | 0;
+
+    /**
+     * The value passed to {@link LegacySharedOptions.indentWidth}, or `2`
+     * otherwise.
+     */
+    indentWidth: number;
+
+    /**
+     * The value passed to {@link LegacySharedOptions.linefeed}, or `"\n"`
+     * otherwise.
+     */
+    linefeed: '\r' | '\r\n' | '\n' | '\n\r';
+
+    /** A partially-constructed {@link LegacyResult} object. */
+    result: {
+      /** Partial information about the compilation in progress. */
+      stats: {
+        /**
+         * The number of milliseconds between 1 January 1970 at 00:00:00 UTC and
+         * the time at which Sass compilation began.
+         */
+        start: number;
+
+        /**
+         * {@link LegacyFileOptions.file} if it was passed, otherwise the string
+         * `"data"`.
+         */
+        entry: string;
+      };
+    };
+  };
+}

package/types/legacy/render.d.ts

@@ -0,0 +1,144 @@
+import {LegacyException} from './exception';
+import {LegacyOptions} from './options';
+
+/**
+ * The object returned by {@link render} and {@link renderSync} after a
+ * successful compilation.
+ *
+ * @category Legacy
+ * @deprecated This is only used by the legacy {@link render} and {@link
+ * renderSync} APIs. Use {@link compile}, {@link compileString}, {@link
+ * compileAsync}, and {@link compileStringAsync} instead.
+ */
+export interface LegacyResult {
+  /**
+   * The compiled CSS. This can be converted to a string by calling
+   * [Buffer.toString](https://nodejs.org/api/buffer.html#buffer_buf_tostring_encoding_start_end).
+   *
+   * @example
+   *
+   * ```js
+   * const result = sass.renderSync({file: "style.scss"});
+   *
+   * console.log(result.css.toString());
+   * ```
+   */
+  css: Buffer;
+
+  /**
+   * The source map that maps the compiled CSS to the source files from which it
+   * was generated. This can be converted to a string by calling
+   * [Buffer.toString](https://nodejs.org/api/buffer.html#buffer_buf_tostring_encoding_start_end).
+   *
+   * This is `undefined` unless either
+   *
+   * * {@link LegacySharedOptions.sourceMap} is a string; or
+   * * {@link LegacySharedOptions.sourceMap} is `true` and
+   *   {@link LegacySharedOptions.outFile} is set.
+   *
+   * The source map uses absolute [`file:`
+   * URLs](https://en.wikipedia.org/wiki/File_URI_scheme) to link to the Sass
+   * source files, except if the source file comes from {@link
+   * LegacyStringOptions.data} in which case it lists its URL as `"stdin"`.
+   *
+   * @example
+   *
+   * ```js
+   * const result = sass.renderSync({
+   *   file: "style.scss",
+   *   sourceMap: true,
+   *   outFile: "style.css"
+   * })
+   *
+   * console.log(result.map.toString());
+   * ```
+   */
+  map?: Buffer;
+
+  /** Additional information about the compilation. */
+  stats: {
+    /**
+     * The absolute path of {@link LegacyFileOptions.file} or {@link
+     * LegacyStringOptions.file}, or `"data"` if {@link
+     * LegacyStringOptions.file} wasn't set.
+     */
+    entry: string;
+
+    /**
+     * The number of milliseconds between 1 January 1970 at 00:00:00 UTC and the
+     * time at which Sass compilation began.
+     */
+    start: number;
+
+    /**
+     * The number of milliseconds between 1 January 1970 at 00:00:00 UTC and the
+     * time at which Sass compilation ended.
+     */
+    end: number;
+
+    /**
+     * The number of milliseconds it took to compile the Sass file. This is
+     * always equal to `start` minus `end`.
+     */
+    duration: number;
+
+    /**
+     * An array of the absolute paths of all Sass files loaded during
+     * compilation. If a stylesheet was loaded from a {@link LegacyImporter}
+     * that returned the stylesheet’s contents, the raw string of the `@use` or
+     * `@import` that loaded that stylesheet included in this array.
+     */
+    includedFiles: string[];
+  };
+}
+
+/**
+ * This function synchronously compiles a Sass file to CSS. If it succeeds, it
+ * returns the result, and if it fails it throws an error.
+ *
+ * **Heads up!** When using the `sass-embedded` npm package, **{@link render}
+ * is almost always faster than {@link renderSync}**, due to the overhead of
+ * emulating synchronous messaging with worker threads and concurrent
+ * compilations being blocked on main thread.
+ *
+ * @example
+ *
+ * ```js
+ * const sass = require('sass'); // or require('node-sass');
+ *
+ * const result = sass.renderSync({file: "style.scss"});
+ * // ...
+ * ```
+ *
+ * @category Legacy
+ * @deprecated Use {@link compile} or {@link compileString} instead.
+ */
+export function renderSync(options: LegacyOptions<'sync'>): LegacyResult;
+
+/**
+
+ * This function asynchronously compiles a Sass file to CSS, and calls
+ * `callback` with a {@link LegacyResult} if compilation succeeds or {@link
+ * LegacyException} if it fails.
+ *
+ * **Heads up!** When using the `sass` npm package, **{@link renderSync} is
+ * almost twice as fast as {@link render}** by default, due to the overhead of
+ * making the entire evaluation process asynchronous.
+ *
+ * ```js
+ * const sass = require('sass'); // or require('node-sass');
+ *
+ * sass.render({
+ *   file: "style.scss"
+ * }, function(err, result) {
+ *   // ...
+ * });
+ * ```
+ *
+ * @category Legacy
+ * @deprecated Use {@link compileAsync} or {@link compileStringAsync} instead.
+ */
+export function render(
+  options: LegacyOptions<'async'>,
+  callback: (exception?: LegacyException, result?: LegacyResult) => void
+): void;

package/types/logger/index.d.ts

@@ -0,0 +1,115 @@
+import {Deprecation} from '../deprecations';
+import {SourceSpan} from './source_span';
+
+export {SourceLocation} from './source_location';
+export {SourceSpan} from './source_span';
+
+/**
+ * The options passed to {@link Logger.warn}.
+ *
+ * * `deprecation`: Whether this is a deprecation warning.
+ *
+ * * `deprecationType`: The type of deprecation. Only set if `deprecation` is
+ *   true.
+ *
+ * * `span`: The location in the Sass source code that generated this warning.
+ *   This may be unset if the warning didn't come from Sass source, for
+ *   example if it's from a deprecated JavaScript option.
+ *
+ * * `stack`: The Sass stack trace at the point the warning was issued. This may
+ *   be unset if the warning didn't come from Sass source, for example if it's
+ *   from a deprecated JavaScript option.
+ *
+ * @category Logger
+ */
+export type LoggerWarnOptions = (
+  | {
+      deprecation: true;
+      deprecationType: Deprecation;
+    }
+  | {deprecation: false}
+) & {
+  span?: SourceSpan;
+  stack?: string;
+};
+
+/**
+ * An object that can be passed to {@link LegacySharedOptions.logger} to control
+ * how Sass emits warnings and debug messages.
+ *
+ * @example
+ *
+ * ```js
+ * const fs = require('fs');
+ * const sass = require('sass');
+ *
+ * let log = "";
+ * sass.renderSync({
+ *   file: 'input.scss',
+ *   logger: {
+ *     warn(message, options) {
+ *       if (options.span) {
+ *         log += `${span.url}:${span.start.line}:${span.start.column}: ` +
+ *             `${message}\n`;
+ *       } else {
+ *         log += `::: ${message}\n`;
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * fs.writeFileSync('log.txt', log);
+ * ```
+ *
+ * @category Logger
+ */
+export interface Logger {
+  /**
+   * This method is called when Sass emits a warning, whether due to a [`@warn`
+   * rule](https://sass-lang.com/documentation/at-rules/warn) or a warning
+   * generated by the Sass compiler.
+   *
+   * If this is `undefined`, Sass will print warnings to standard error.
+   *
+   * `options` may contain the following fields:
+   *
+   * @param message - The warning message.
+   */
+  warn?(message: string, options: LoggerWarnOptions): void;
+
+  /**
+   * This method is called when Sass emits a debug message due to a [`@debug`
+   * rule](https://sass-lang.com/documentation/at-rules/debug).
+   *
+   * If this is `undefined`, Sass will print debug messages to standard error.
+   *
+   * @param message - The debug message.
+   * @param options.span - The location in the Sass source code that generated this
+   * debug message.
+   */
+  debug?(message: string, options: {span: SourceSpan}): void;
+}
+
+/**
+ * A namespace for built-in {@link Logger}s.
+ *
+ * @category Logger
+ * @compatibility dart: "1.43.0", node: false
+ */
+export namespace Logger {
+  /**
+   * A {@link Logger} that silently ignores all warnings and debug messages.
+   *
+   * @example
+   *
+   * ```js
+   * const sass = require('sass');
+   *
+   * const result = sass.renderSync({
+   *   file: 'input.scss',
+   *   logger: sass.Logger.silent,
+   * });
+   * ```
+   */
+  export const silent: Logger;
+}

package/types/logger/source_location.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A specific location within a source file.
+ *
+ * This is always associated with a {@link SourceSpan} which indicates *which*
+ * file it refers to.
+ *
+ * @category Logger
+ */
+export interface SourceLocation {
+  /**
+   * The 0-based index of this location within its source file, in terms of
+   * UTF-16 code units.
+   */
+  offset: number;
+
+  /** The 0-based line number of this location. */
+  line: number;
+
+  /** The 0-based column number of this location. */
+  column: number;
+}

package/types/logger/source_span.d.ts

@@ -0,0 +1,34 @@
+import {SourceLocation} from './source_location';
+
+/**
+ * A span of text within a source file.
+ *
+ * @category Logger
+ */
+export interface SourceSpan {
+  /** The beginning of this span, inclusive. */
+  start: SourceLocation;
+
+  /**
+   * The end of this span, exclusive.
+   *
+   * If {@link start} and {@link end} refer to the same location, the span has
+   * zero length and refers to the point immediately after {@link start} and
+   * before the next character.
+   */
+  end: SourceLocation;
+
+  /** The canonical URL of the file this span refers to. */
+  url?: URL;
+
+  /** The text covered by the span. */
+  text: string;
+
+  /**
+   * Text surrounding the span.
+   *
+   * If this is set, it must include only whole lines, and it must include at
+   * least all line(s) which are partially covered by this span.
+   */
+  context?: string;
+}