8889841cfunction.d.ts000066600000054104150537553630007207 0ustar00import {LegacyPluginThis} from './plugin_this'; /** * A synchronous callback that implements a custom Sass function. This can be * passed to [[LegacySharedOptions.functions]] for either [[render]] or * [[renderSync]]. * * If this throws an error, Sass will treat that as the function failing with * that error message. * * ```js * const result = sass.renderSync({ * file: 'style.scss', * functions: { * "sum($arg1, $arg2)": (arg1, arg2) => { * if (!(arg1 instanceof sass.types.Number)) { * throw new Error("$arg1: Expected a number"); * } else if (!(arg2 instanceof sass.types.Number)) { * throw new Error("$arg2: Expected a number"); * } * return new sass.types.Number(arg1.getValue() + arg2.getValue()); * } * } * }); * ``` * * @param args - One argument for each argument that's declared in the signature * that's passed to [[LegacySharedOptions.functions]]. If the signature [takes * arbitrary arguments](https://sass-lang.com/documentation/at-rules/function#taking-arbitrary-arguments), * they're passed as a single argument list in the last argument. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[CustomFunction]] with [[compile]], [[compileString]], * [[compileAsync]], and [[compileStringAsync]] instead. */ export type LegacySyncFunction = ( this: LegacyPluginThis, ...args: LegacyValue[] ) => LegacyValue; /** * An asynchronous callback that implements a custom Sass function. This can be * passed to [[LegacySharedOptions.functions]], but only for [[render]]. * * An asynchronous function must return `undefined`. Its final argument will * always be a callback, which it should call with the result of the function * once it's done running. * * If this throws an error, Sass will treat that as the function failing with * that error message. * * ```js * sass.render({ * file: 'style.scss', * functions: { * "sum($arg1, $arg2)": (arg1, arg2, done) => { * if (!(arg1 instanceof sass.types.Number)) { * throw new Error("$arg1: Expected a number"); * } else if (!(arg2 instanceof sass.types.Number)) { * throw new Error("$arg2: Expected a number"); * } * done(new sass.types.Number(arg1.getValue() + arg2.getValue())); * } * } * }, (result, error) => { * // ... * }); * ``` * * This is passed one argument for each argument that's declared in the * signature that's passed to [[LegacySharedOptions.functions]]. If the * signature [takes arbitrary * arguments](https://sass-lang.com/documentation/at-rules/function#taking-arbitrary-arguments), * they're passed as a single argument list in the last argument before the * callback. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[CustomFunction]] with [[compile]], [[compileString]], * [[compileAsync]], and [[compileStringAsync]] instead. */ export type LegacyAsyncFunction = | ((this: LegacyPluginThis, done: (result: LegacyValue) => void) => void) | (( this: LegacyPluginThis, arg1: LegacyValue, done: LegacyAsyncFunctionDone ) => void) | (( this: LegacyPluginThis, arg1: LegacyValue, arg2: LegacyValue, done: LegacyAsyncFunctionDone ) => void) | (( this: LegacyPluginThis, arg1: LegacyValue, arg2: LegacyValue, arg3: LegacyValue, done: LegacyAsyncFunctionDone ) => void) | (( this: LegacyPluginThis, arg1: LegacyValue, arg2: LegacyValue, arg3: LegacyValue, arg4: LegacyValue, done: LegacyAsyncFunctionDone ) => void) | (( this: LegacyPluginThis, arg1: LegacyValue, arg2: LegacyValue, arg3: LegacyValue, arg4: LegacyValue, arg5: LegacyValue, done: LegacyAsyncFunctionDone ) => void) | (( this: LegacyPluginThis, arg1: LegacyValue, arg2: LegacyValue, arg3: LegacyValue, arg4: LegacyValue, arg5: LegacyValue, arg6: LegacyValue, done: LegacyAsyncFunctionDone ) => void) | (( this: LegacyPluginThis, ...args: [...LegacyValue[], LegacyAsyncFunctionDone] ) => void); /** * The function called by a [[LegacyAsyncFunction]] to indicate that it's * finished. * * @param result - If this is a [[LegacyValue]], that indicates that the * function call completed successfully. If it's a [[types.Error]], that * indicates that the function call failed. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[CustomFunction]] with [[compile]], [[compileString]], * [[compileAsync]], and [[compileStringAsync]] instead. */ export type LegacyAsyncFunctionDone = ( result: LegacyValue | types.Error ) => void; /** * A callback that implements a custom Sass function. For [[renderSync]], this * must be a [[LegacySyncFunction]] which returns its result directly; for * [[render]], it may be either a [[LegacySyncFunction]] or a * [[LegacyAsyncFunction]] which calls a callback with its result. * * See [[LegacySharedOptions.functions]] for more details. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[CustomFunction]] with [[compile]], [[compileString]], * [[compileAsync]], and [[compileStringAsync]] instead. */ export type LegacyFunction = sync extends 'async' ? LegacySyncFunction | LegacyAsyncFunction : LegacySyncFunction; /** * A type representing all the possible values that may be passed to or returned * from a [[LegacyFunction]]. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[Value]] with [[compile]], [[compileString]], [[compileAsync]], * and [[compileStringAsync]] instead. */ export type LegacyValue = | types.Null | types.Number | types.String | types.Boolean | types.Color | types.List | types.Map; /** * A shorthand for `sass.types.Boolean.TRUE`. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[sassTrue]] with [[compile]], [[compileString]], [[compileAsync]], * and [[compileStringAsync]] instead. */ export const TRUE: types.Boolean; /** * A shorthand for `sass.types.Boolean.FALSE`. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[sassFalse]] with [[compile]], [[compileString]], [[compileAsync]], * and [[compileStringAsync]] instead. */ export const FALSE: types.Boolean; /** * A shorthand for `sass.types.Null.NULL`. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[sassNull]] with [[compile]], [[compileString]], [[compileAsync]], * and [[compileStringAsync]] instead. */ export const NULL: types.Null; /** * The namespace for value types used in the legacy function API. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[Value]] with [[compile]], [[compileString]], [[compileAsync]], * and [[compileStringAsync]] instead. */ export namespace types { /** * The class for Sass's singleton [`null` * value](https://sass-lang.com/documentation/values/null). The value itself * can be accessed through the [[NULL]] field. */ export class Null { /** Sass's singleton `null` value. */ static readonly NULL: Null; } /** * Sass's [number type](https://sass-lang.com/documentation/values/numbers). */ export class Number { /** * @param value - The numeric value of the number. * * @param unit - If passed, the number's unit. * * Complex units can be represented as * `**.../**...`, with numerator units on the * left-hand side of the `/` and denominator units on the right. A number * with only numerator units may omit the `/` and the units after it, and a * number with only denominator units may be represented * with no units before the `/`. * * @example * * ```scss * new sass.types.Number(0.5); // == 0.5 * new sass.types.Number(10, "px"); // == 10px * new sass.types.Number(10, "px*px"); // == 10px * 1px * new sass.types.Number(10, "px/s"); // == math.div(10px, 1s) * new sass.types.Number(10, "px*px/s*s"); // == 10px * math.div(math.div(1px, 1s), 1s) * ``` */ constructor(value: number, unit?: string); /** * Returns the value of the number, ignoring units. * * **Heads up!** This means that `96px` and `1in` will return different * values, even though they represent the same length. * * @example * * ```js * const number = new sass.types.Number(10, "px"); * number.getValue(); // 10 * ``` */ getValue(): number; /** * Destructively modifies this number by setting its numeric value to * `value`, independent of its units. * * @deprecated Use [[constructor]] instead. */ setValue(value: number): void; /** * Returns a string representation of this number's units. Complex units are * returned in the same format that [[constructor]] accepts them. * * @example * * ```js * // number is `10px`. * number.getUnit(); // "px" * * // number is `math.div(10px, 1s)`. * number.getUnit(); // "px/s" * ``` */ getUnit(): string; /** * Destructively modifies this number by setting its units to `unit`, * independent of its numeric value. Complex units are specified in the same * format as [[constructor]]. * * @deprecated Use [[constructor]] instead. */ setUnit(unit: string): void; } /** * Sass's [string type](https://sass-lang.com/documentation/values/strings). * * **Heads up!** This API currently provides no way of distinguishing between * a [quoted](https://sass-lang.com/documentation/values/strings#quoted) and * [unquoted](https://sass-lang.com/documentation/values/strings#unquoted) * string. */ export class String { /** * Creates an unquoted string with the given contents. * * **Heads up!** This API currently provides no way of creating a * [quoted](https://sass-lang.com/documentation/values/strings#quoted) * string. */ constructor(value: string); /** * Returns the contents of the string. If the string contains escapes, * those escapes are included literally if it’s * [unquoted](https://sass-lang.com/documentation/values/strings#unquoted), * while the values of the escapes are included if it’s * [quoted](https://sass-lang.com/documentation/values/strings#quoted). * * @example * * ``` * // string is `Arial`. * string.getValue(); // "Arial" * * // string is `"Helvetica Neue"`. * string.getValue(); // "Helvetica Neue" * * // string is `\1F46D`. * string.getValue(); // "\\1F46D" * * // string is `"\1F46D"`. * string.getValue(); // "👭" * ``` */ getValue(): string; /** * Destructively modifies this string by setting its numeric value to * `value`. * * **Heads up!** Even if the string was originally quoted, this will cause * it to become unquoted. * * @deprecated Use [[constructor]] instead. */ setValue(value: string): void; } /** * Sass's [boolean type](https://sass-lang.com/documentation/values/booleans). * * Custom functions should respect Sass’s notion of * [truthiness](https://sass-lang.com/documentation/at-rules/control/if#truthiness-and-falsiness) * by treating `false` and `null` as falsey and everything else as truthy. * * **Heads up!** Boolean values can't be constructed, they can only be * accessed through the [[TRUE]] and [[FALSE]] constants. */ export class Boolean { /** * Returns `true` if this is Sass's `true` value and `false` if this is * Sass's `false` value. * * @example * * ```js * // boolean is `true`. * boolean.getValue(); // true * boolean === sass.types.Boolean.TRUE; // true * * // boolean is `false`. * boolean.getValue(); // false * boolean === sass.types.Boolean.FALSE; // true * ``` */ getValue(): T; /** Sass's `true` value. */ static readonly TRUE: Boolean; /** Sass's `false` value. */ static readonly FALSE: Boolean; } /** * Sass's [color type](https://sass-lang.com/documentation/values/colors). */ export class Color { /** * Creates a new Sass color with the given red, green, blue, and alpha * channels. The red, green, and blue channels must be integers between 0 * and 255 (inclusive), and alpha must be between 0 and 1 (inclusive). * * @example * * ```js * new sass.types.Color(107, 113, 127); // #6b717f * new sass.types.Color(0, 0, 0, 0); // rgba(0, 0, 0, 0) * ``` */ constructor(r: number, g: number, b: number, a?: number); /** * Creates a new Sass color with alpha, red, green, and blue channels taken * from respective two-byte chunks of a hexidecimal number. * * @example * * ```js * new sass.types.Color(0xff6b717f); // #6b717f * new sass.types.Color(0x00000000); // rgba(0, 0, 0, 0) * ``` */ constructor(argb: number); /** * Returns the red channel of the color as an integer from 0 to 255. * * @example * * ```js * // color is `#6b717f`. * color.getR(); // 107 * * // color is `#b37399`. * color.getR(); // 179 * ``` */ getR(): number; /** * Sets the red channel of the color. The value must be an integer between 0 * and 255 (inclusive). * * @deprecated Use [[constructor]] instead. */ setR(value: number): void; /** * Returns the green channel of the color as an integer from 0 to 255. * * @example * * ```js * // color is `#6b717f`. * color.getG(); // 113 * * // color is `#b37399`. * color.getG(); // 115 * ``` */ getG(): number; /** * Sets the green channel of the color. The value must be an integer between * 0 and 255 (inclusive). * * @deprecated Use [[constructor]] instead. */ setG(value: number): void; /** * Returns the blue channel of the color as an integer from 0 to 255. * * @example * * ```js * // color is `#6b717f`. * color.getB(); // 127 * * // color is `#b37399`. * color.getB(); // 153 * ``` */ getB(): number; /** * Sets the blue channel of the color. The value must be an integer between * 0 and 255 (inclusive). * * @deprecated Use [[constructor]] instead. */ setB(value: number): void; /** * Returns the alpha channel of the color as a number from 0 to 1. * * @example * * ```js * // color is `#6b717f`. * color.getA(); // 1 * * // color is `transparent`. * color.getA(); // 0 * ``` */ getA(): number; /** * Sets the alpha channel of the color. The value must be between 0 and 1 * (inclusive). * * @deprecated Use [[constructor]] instead. */ setA(value: number): void; } /** * Sass's [list type](https://sass-lang.com/documentation/values/lists). * * **Heads up!** This list type’s methods use 0-based indexing, even though * within Sass lists use 1-based indexing. These methods also don’t support * using negative numbers to index backwards from the end of the list. */ export class List { /** * Creates a new Sass list. * * **Heads up!** The initial values of the list elements are undefined. * These elements must be set using [[setValue]] before accessing them or * passing the list back to Sass. * * @example * * ```js * const list = new sass.types.List(3); * list.setValue(0, new sass.types.Number(10, "px")); * list.setValue(1, new sass.types.Number(15, "px")); * list.setValue(2, new sass.types.Number(32, "px")); * list; // 10px, 15px, 32px * ``` * * @param length - The number of (initially undefined) elements in the list. * @param commaSeparator - If `true`, the list is comma-separated; otherwise, * it's space-separated. Defaults to `true`. */ constructor(length: number, commaSeparator?: boolean); /** * Returns the element at `index`, or `undefined` if that value hasn't yet * been set. * * @example * * ```js * // list is `10px, 15px, 32px` * list.getValue(0); // 10px * list.getValue(2); // 32px * ``` * * @param index - A (0-based) index into this list. * @throws `Error` if `index` is less than 0 or greater than or equal to the * number of elements in this list. */ getValue(index: number): LegacyValue | undefined; /** * Sets the element at `index` to `value`. * * @example * * ```js * // list is `10px, 15px, 32px` * list.setValue(1, new sass.types.Number(18, "px")); * list; // 10px, 18px, 32px * ``` * * @param index - A (0-based) index into this list. * @throws `Error` if `index` is less than 0 or greater than or equal to the * number of elements in this list. */ setValue(index: number, value: LegacyValue): void; /** * Returns `true` if this list is comma-separated and `false` otherwise. * * @example * * ```js * // list is `10px, 15px, 32px` * list.getSeparator(); // true * * // list is `1px solid` * list.getSeparator(); // false * ``` */ getSeparator(): boolean; /** * Sets whether the list is comma-separated. * * @param isComma - `true` to make the list comma-separated, `false` otherwise. */ setSeparator(isComma: boolean): void; /** * Returns the number of elements in the list. * * @example * * ```js * // list is `10px, 15px, 32px` * list.getLength(); // 3 * * // list is `1px solid` * list.getLength(); // 2 * ``` */ getLength(): number; } /** * Sass's [map type](https://sass-lang.com/documentation/values/maps). * * **Heads up!** This map type is represented as a list of key-value pairs * rather than a mapping from keys to values. The only way to find the value * associated with a given key is to iterate through the map checking for that * key. Maps created through this API are still forbidden from having duplicate * keys. */ export class Map { /** * Creates a new Sass map. * * **Heads up!** The initial keys and values of the map are undefined. They * must be set using [[setKey]] and [[setValue]] before accessing them or * passing the map back to Sass. * * @example * * ```js * const map = new sass.types.Map(2); * map.setKey(0, new sass.types.String("width")); * map.setValue(0, new sass.types.Number(300, "px")); * map.setKey(1, new sass.types.String("height")); * map.setValue(1, new sass.types.Number(100, "px")); * map; // (width: 300px, height: 100px) * ``` * * @param length - The number of (initially undefined) key/value pairs in the map. */ constructor(length: number); /** * Returns the value in the key/value pair at `index`. * * @example * * ```js * // map is `(width: 300px, height: 100px)` * map.getValue(0); // 300px * map.getValue(1); // 100px * ``` * * @param index - A (0-based) index of a key/value pair in this map. * @throws `Error` if `index` is less than 0 or greater than or equal to the * number of pairs in this map. */ getValue(index: number): LegacyValue; /** * Sets the value in the key/value pair at `index` to `value`. * * @example * * ```js * // map is `("light": 200, "medium": 400, "bold": 600)` * map.setValue(1, new sass.types.Number(300)); * map; // ("light": 200, "medium": 300, "bold": 600) * ``` * * @param index - A (0-based) index of a key/value pair in this map. * @throws `Error` if `index` is less than 0 or greater than or equal to the * number of pairs in this map. */ setValue(index: number, value: LegacyValue): void; /** * Returns the key in the key/value pair at `index`. * * @example * * ```js * // map is `(width: 300px, height: 100px)` * map.getKey(0); // width * map.getKey(1); // height * ``` * * @param index - A (0-based) index of a key/value pair in this map. * @throws `Error` if `index` is less than 0 or greater than or equal to the * number of pairs in this map. */ getKey(index: number): LegacyValue; /** * Sets the value in the key/value pair at `index` to `value`. * * @example * * ```js * // map is `("light": 200, "medium": 400, "bold": 600)` * map.setValue(1, new sass.types.String("lighter")); * map; // ("lighter": 200, "medium": 300, "bold": 600) * ``` * * @param index - A (0-based) index of a key/value pair in this map. * @throws `Error` if `index` is less than 0 or greater than or equal to the * number of pairs in this map. */ setKey(index: number, key: LegacyValue): void; /** * Returns the number of key/value pairs in this map. * * @example * * ```js * // map is `("light": 200, "medium": 400, "bold": 600)` * map.getLength(); // 3 * * // map is `(width: 300px, height: 100px)` * map.getLength(); // 2 * ``` */ getLength(): number; } /** * An error that can be returned from a Sass function to signal that it * encountered an error. This is the only way to signal an error * asynchronously from a [[LegacyAsyncFunction]]. */ export class Error { constructor(message: string); } } plugin_this.d.ts000066600000003744150537553630007713 0ustar00/** * The value of `this` in the context of a [[LegacyImporter]] or * [[LegacyFunction]] callback. * * @category Legacy * @deprecated This is only used by the legacy [[render]] and [[renderSync]] * APIs. Use [[compile]], [[compileString]], [[compileAsync]], and * [[compileStringAsync]] instead. */ export interface LegacyPluginThis { /** * A partial representation of the options passed to [[render]] or * [[renderSync]]. */ options: { /** The same [[LegacyPluginThis]] instance that contains this object. */ context: LegacyPluginThis; /** * The value passed to [[LegacyFileOptions.file]] or * [[LegacyStringOptions.file]]. */ file?: string; /** The value passed to [[LegacyStringOptions.data]]. */ data?: string; /** * The value passed to [[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 [[LegacySharedOptions.indentType]] was `"tab"`, 0 otherwise. */ indentType: 1 | 0; /** * The value passed to [[LegacySharedOptions.indentWidth]], or `2` otherwise. */ indentWidth: number; /** * The value passed to [[LegacySharedOptions.linefeed]], or `"\n"` * otherwise. */ linefeed: '\r' | '\r\n' | '\n' | '\n\r'; /** A partially-constructed [[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; /** * [[LegacyFileOptions.file]] if it was passed, otherwise the string * `"data"`. */ entry: string; }; }; }; } exception.d.ts000066600000003415150537553630007357 0ustar00/** * The exception type thrown by [[renderSync]] and passed as the error to * [[render]]'s callback. * * @category Legacy * @deprecated This is only thrown by the legacy [[render]] and [[renderSync]] * APIs. Use [[compile]], [[compileString]], [[compileAsync]], and * [[compileStringAsync]] instead. */ export interface LegacyException extends Error { /** * The error message. For Dart Sass, when possible this includes a highlighted * indication of where in the source file the error occurred as well as the * Sass stack trace. */ message: string; /** * The error message. For Dart Sass, this is the same as the result of calling * [[toString]], which is itself the same as [[message]] but with the prefix * "Error:". */ formatted: string; /** * The (1-based) line number on which the error occurred, if this exception is * associated with a specific Sass file location. */ line?: number; /** * The (1-based) column number within [[line]] at which the error occurred, if * this exception is associated with a specific Sass file location. */ column?: number; /** * Analogous to the exit code for an executable. `1` for an error caused by a * Sass file, `3` for any other type of error. */ status: number; /** * If this exception was caused by an error in a Sass file, this will * represent the Sass file's location. It can be in one of three formats: * * * If the Sass file was loaded from disk, this is the path to that file. * * If the Sass file was generated by an importer, this is its canonical URL. * * If the Sass file was passed as [[LegacyStringOptions.data]] without a * corresponding [[LegacyStringOptions.file]], this is the special string * `"stdin"`. */ file?: string; } options.d.ts000066600000047115150537553630007061 0ustar00import {Logger} from '../logger'; import {LegacyImporter} from './importer'; import {LegacyFunction} from './function'; /** * Options for [[render]] and [[renderSync]] that are shared between * [[LegacyFileOptions]] and [[LegacyStringOptions]]. * * @typeParam sync - This lets the TypeScript checker verify that * [[LegacyAsyncImporter]]s and [[LegacyAsyncFunction]]s aren't passed to * [[renderSync]]. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[Options]] with [[compile]], [[compileString]], [[compileAsync]], * and [[compileStringAsync]] instead. */ export interface LegacySharedOptions { /** * This array of strings option provides [load * paths](https://sass-lang.com/documentation/at-rules/import#load-paths) for * Sass to look for stylesheets. Earlier load paths will take precedence over * later ones. * * ```js * sass.renderSync({ * file: "style.scss", * includePaths: ["node_modules/bootstrap/dist/css"] * }); * ``` * * Load paths are also loaded from the `SASS_PATH` environment variable, if * it’s set. This variable should be a list of paths separated by `;` (on * Windows) or `:` (on other operating systems). Load paths from the * `includePaths` option take precedence over load paths from `SASS_PATH`. * * ```sh * $ SASS_PATH=node_modules/bootstrap/dist/css sass style.scss style.css * ``` * * @category Input * @compatibility feature: "SASS_PATH", dart: "1.15.0", node: "3.9.0" * * Earlier versions of Dart Sass and Node Sass didn’t support the `SASS_PATH` * environment variable. */ includePaths?: string[]; /** * Whether the generated CSS should use spaces or tabs for indentation. * * ```js * const result = sass.renderSync({ * file: "style.scss", * indentType: "tab", * indentWidth: 1 * }); * * result.css.toString(); * // "h1 {\n\tfont-size: 40px;\n}\n" * ``` * * @defaultValue `'space'` * @category Output * @compatibility dart: true, node: "3.0.0" */ indentType?: 'space' | 'tab'; /** * How many spaces or tabs (depending on [[indentType]]) should be used per * indentation level in the generated CSS. It must be between 0 and 10 * (inclusive). * * @defaultValue `2` * @category Output * @compatibility dart: true, node: "3.0.0" */ indentWidth?: number; /** * Which character sequence to use at the end of each line in the generated * CSS. It can have the following values: * * * `'lf'` uses U+000A LINE FEED. * * `'lfcr'` uses U+000A LINE FEED followed by U+000D CARRIAGE RETURN. * * `'cr'` uses U+000D CARRIAGE RETURN. * * `'crlf'` uses U+000D CARRIAGE RETURN followed by U+000A LINE FEED. * * @defaultValue `'lf'` * @category Output * @compatibility dart: true, node: "3.0.0" */ linefeed?: 'cr' | 'crlf' | 'lf' | 'lfcr'; /** * If `true`, Sass won't add a link from the generated CSS to the source map. * * ```js * const result = sass.renderSync({ * file: "style.scss", * sourceMap: "out.map", * omitSourceMapUrl: true * }) * console.log(result.css.toString()); * // h1 { * // font-size: 40px; * // } * ``` * * @defaultValue `false` * @category Source Maps */ omitSourceMapUrl?: boolean; /** * The location that Sass expects the generated CSS to be saved to. It’s used * to determine the URL used to link from the generated CSS to the source map, * and from the source map to the Sass source files. * * **Heads up!** Despite the name, Sass does *not* write the CSS output to * this file. The caller must do that themselves. * * ```js * result = sass.renderSync({ * file: "style.scss", * sourceMap: true, * outFile: "out.css" * }) * console.log(result.css.toString()); * // h1 { * // font-size: 40px; * // } * // /*# sourceMappingURL=out.css.map * / * ``` * * @category Source Maps */ outFile?: string; /** * The output style of the compiled CSS. There are four possible output styles: * * * `"expanded"` (the default for Dart Sass) writes each selector and * declaration on its own line. * * * `"compressed"` removes as many extra characters as possible, and writes * the entire stylesheet on a single line. * * * `"nested"` (the default for Node Sass, not supported by Dart Sass) * indents CSS rules to match the nesting of the Sass source. * * * `"compact"` (not supported by Dart Sass) puts each CSS rule on its own single line. * * @example * * ```js * const source = ` * h1 { * font-size: 40px; * code { * font-face: Roboto Mono; * } * }`; * * let result = sass.renderSync({ * data: source, * outputStyle: "expanded" * }); * console.log(result.css.toString()); * // h1 { * // font-size: 40px; * // } * // h1 code { * // font-face: Roboto Mono; * // } * * result = sass.renderSync({ * data: source, * outputStyle: "compressed" * }); * console.log(result.css.toString()); * // h1{font-size:40px}h1 code{font-face:Roboto Mono} * * result = sass.renderSync({ * data: source, * outputStyle: "nested" * }); * console.log(result.css.toString()); * // h1 { * // font-size: 40px; } * // h1 code { * // font-face: Roboto Mono; } * * result = sass.renderSync({ * data: source, * outputStyle: "compact" * }); * console.log(result.css.toString()); * // h1 { font-size: 40px; } * // h1 code { font-face: Roboto Mono; } * ``` * * @category Output */ outputStyle?: 'compressed' | 'expanded' | 'nested' | 'compact'; /** * Whether or not Sass should generate a source map. If it does, the source * map will be available as [[LegacyResult.map]] (unless [[sourceMapEmbed]] is * `true`). * * If this option is a string, it’s the path that the source map is expected * to be written to, which is used to link to the source map from the * generated CSS and to link *from* the source map to the Sass source files. * Note that if `sourceMap` is a string and [[outFile]] isn’t passed, Sass * assumes that the CSS will be written to the same directory as the file * option if it’s passed. * * If this option is `true`, the path is assumed to be [[outFile]] with `.map` * added to the end. If it’s `true` and [[outFile]] isn’t passed, it has no * effect. * * @example * * ```js * let result = sass.renderSync({ * file: "style.scss", * sourceMap: "out.map" * }) * console.log(result.css.toString()); * // h1 { * // font-size: 40px; * // } * // /*# sourceMappingURL=out.map * / * * result = sass.renderSync({ * file: "style.scss", * sourceMap: true, * outFile: "out.css" * }) * console.log(result.css.toString()); * // h1 { * // font-size: 40px; * // } * // /*# sourceMappingURL=out.css.map * / * ``` * * @defaultValue `false` * @category Source Maps */ sourceMap?: boolean | string; /** * Whether to embed the entire contents of the Sass files that contributed to * the generated CSS in the source map. This may produce very large source * maps, but it guarantees that the source will be available on any computer * no matter how the CSS is served. * * @example * * ```js * sass.renderSync({ * file: "style.scss", * sourceMap: "out.map", * sourceMapContents: true * }) * ``` * * @defaultValue `false` * @category Source Maps */ sourceMapContents?: boolean; /** * Whether to embed the contents of the source map file in the generated CSS, * rather than creating a separate file and linking to it from the CSS. * * @example * * ```js * sass.renderSync({ * file: "style.scss", * sourceMap: "out.map", * sourceMapEmbed: true * }); * ``` * * @defaultValue `false` * @category Source Maps */ sourceMapEmbed?: boolean; /** * If this is passed, it's prepended to all the links from the source map to * the Sass source files. * * @category Source Maps */ sourceMapRoot?: string; /** * Additional handler(s) for loading files when a [`@use` * rule](https://sass-lang.com/documentation/at-rules/use) or an [`@import` * rule](https://sass-lang.com/documentation/at-rules/import) is encountered. * It can either be a single [[LegacyImporter]] function, or an array of * [[LegacyImporter]]s. * * Importers take the URL of the `@import` or `@use` rule and return a * [[LegacyImporterResult]] indicating how to handle that rule. For more * details, see [[LegacySyncImporter]] and [[LegacyAsyncImporter]]. * * Loads are resolved by trying, in order: * * * Loading a file from disk relative to the file in which the `@use` or * `@import` appeared. * * * Each custom importer. * * * Loading a file relative to the current working directory. * * * Each load path in [[includePaths]]. * * * Each load path specified in the `SASS_PATH` environment variable, which * should be semicolon-separated on Windows and colon-separated elsewhere. * * @example * * ```js * sass.render({ * file: "style.scss", * importer: [ * // This importer uses the synchronous API, and can be passed to either * // renderSync() or render(). * function(url, prev) { * // This generates a stylesheet from scratch for `@use "big-headers"`. * if (url != "big-headers") return null; * * return { * contents: ` * h1 { * font-size: 40px; * }` * }; * }, * * // This importer uses the asynchronous API, and can only be passed to * // render(). * function(url, prev, done) { * // Convert `@use "foo/bar"` to "node_modules/foo/sass/bar". * const components = url.split('/'); * const innerPath = components.slice(1).join('/'); * done({ * file: `node_modules/${components.first}/sass/${innerPath}` * }); * } * ] * }, function(err, result) { * // ... * }); * ``` * * @category Plugins * @compatibility dart: true, node: "3.0.0" * * Versions of Node Sass before 3.0.0 don’t support arrays of importers, nor * do they support importers that return `Error` objects. * * Versions of Node Sass before 2.0.0 don’t support the `importer` option at * all. * * @compatibility feature: "Import order", dart: "1.20.2", node: false * * Versions of Dart Sass before 1.20.2 preferred resolving imports using * [[includePaths]] before resolving them using custom importers. * * All versions of Node Sass currently pass imports to importers before * loading them relative to the file in which the `@import` appears. This * behavior is considered incorrect and should not be relied on because it * violates the principle of *locality*, which says that it should be possible * to reason about a stylesheet without knowing everything about how the * entire system is set up. If a user tries to import a stylesheet relative to * another stylesheet, that import should *always* work. It shouldn’t be * possible for some configuration somewhere else to break it. */ importer?: LegacyImporter | LegacyImporter[]; /** * Additional built-in Sass functions that are available in all stylesheets. * This option takes an object whose keys are Sass function signatures and * whose values are [[LegacyFunction]]s. Each function should take the same * arguments as its signature. * * Functions are passed JavaScript representations of [Sass value * types](https://sass-lang.com/documentation/js-api#value-types), and must * return the same. * * **Heads up!** When writing custom functions, it’s important to ensure that * all the arguments are the types you expect. Otherwise, users’ stylesheets * could crash in hard-to-debug ways or, worse, compile to meaningless CSS. * * @example * * ```js * sass.render({ * data: ` * h1 { * font-size: pow(2, 5) * 1px; * }`, * functions: { * // This function uses the synchronous API, and can be passed to either * // renderSync() or render(). * 'pow($base, $exponent)': function(base, exponent) { * if (!(base instanceof sass.types.Number)) { * throw "$base: Expected a number."; * } else if (base.getUnit()) { * throw "$base: Expected a unitless number."; * } * * if (!(exponent instanceof sass.types.Number)) { * throw "$exponent: Expected a number."; * } else if (exponent.getUnit()) { * throw "$exponent: Expected a unitless number."; * } * * return new sass.types.Number( * Math.pow(base.getValue(), exponent.getValue())); * }, * * // This function uses the asynchronous API, and can only be passed to * // render(). * 'sqrt($number)': function(number, done) { * if (!(number instanceof sass.types.Number)) { * throw "$number: Expected a number."; * } else if (number.getUnit()) { * throw "$number: Expected a unitless number."; * } * * done(new sass.types.Number(Math.sqrt(number.getValue()))); * } * } * }, function(err, result) { * console.log(result.css.toString()); * // h1 { * // font-size: 32px; * // } * }); * ``` * * @category Plugins */ functions?: {[key: string]: LegacyFunction}; /** * By default, if the CSS document contains non-ASCII characters, Sass adds a * `@charset` declaration (in expanded output mode) or a byte-order mark (in * compressed mode) to indicate its encoding to browsers or other consumers. * If `charset` is `false`, these annotations are omitted. * * @category Output * @compatibility dart: "1.39.0", node: false */ charset?: boolean; /** * If this option is set to `true`, Sass won’t print warnings that are caused * by dependencies. A “dependency” is defined as any file that’s loaded * through [[loadPaths]] or [[importer]]. Stylesheets that are imported * relative to the entrypoint are not considered dependencies. * * This is useful for silencing deprecation warnings that you can’t fix on * your own. However, please also notify your dependencies of the deprecations * so that they can get fixed as soon as possible! * * **Heads up!** If [[render]] or [[renderSync]] is called without * [[LegacyFileOptions.file]] or [[LegacyStringOptions.file]], all * stylesheets it loads will be considered dependencies. Since it doesn’t have * a path of its own, everything it loads is coming from a load path rather * than a relative import. * * @defaultValue `false` * @category Messages * @compatibility dart: "1.35.0", node: false */ quietDeps?: boolean; /** * By default, Dart Sass will print only five instances of the same * deprecation warning per compilation to avoid deluging users in console * noise. If you set `verbose` to `true`, it will instead print every * deprecation warning it encounters. * * @defaultValue `false` * @category Messages * @compatibility dart: "1.35.0", node: false */ verbose?: boolean; /** * An object to use to handle warnings and/or debug messages from Sass. * * By default, Sass emits warnings and debug messages to standard error, but * if [[Logger.warn]] or [[Logger.debug]] is set, this will invoke them * instead. * * The special value [[Logger.silent]] can be used to easily silence all * messages. * * @category Messages * @compatibility dart: "1.43.0", node: false */ logger?: Logger; } /** * If [[file]] is passed without [[data]], Sass will load the stylesheet at * [[file]] and compile it to CSS. * * @typeParam sync - This lets the TypeScript checker verify that * [[LegacyAsyncImporter]]s and [[LegacyAsyncFunction]]s aren't passed to * [[renderSync]]. */ export interface LegacyFileOptions extends LegacySharedOptions { /** * The path to the file for Sass to load and compile. If the file’s extension * is `.scss`, it will be parsed as SCSS; if it’s `.sass`, it will be parsed * as the indented syntax; and if it’s `.css`, it will be parsed as plain CSS. * If it has no extension, it will be parsed as SCSS. * * @example * * ```js * sass.renderSync({file: "style.scss"}); * ``` * * @category Input * @compatibility feature: "Plain CSS files", dart: "1.11.0", node: "partial" * * Node Sass and older versions of Dart Sass support loading files with the * extension `.css`, but contrary to the specification they’re treated as SCSS * files rather than being parsed as CSS. This behavior has been deprecated * and should not be relied on. Any files that use Sass features should use * the `.scss` extension. * * All versions of Node Sass and Dart Sass otherwise support the file option * as described below. */ file: string; /** * See [[LegacyStringOptions.file]] for documentation of passing [[file]] along * with [[data]]. * * @category Input */ data?: never; } /** * If [[data]] is passed, Sass will use it as the contents of the stylesheet to * compile. * * @typeParam sync - This lets the TypeScript checker verify that * [[LegacyAsyncImporter]]s and [[LegacyAsyncFunction]]s aren't passed to * [[renderSync]]. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[StringOptions]] with [[compile]], [[compileString]], * [[compileAsync]], and [[compileStringAsync]] instead. */ export interface LegacyStringOptions extends LegacySharedOptions { /** * The contents of the stylesheet to compile. Unless [[file]] is passed as * well, the stylesheet’s URL is set to `"stdin"`. * * By default, this stylesheet is parsed as SCSS. This can be controlled using * [[indentedSyntax]]. * * @example * * ```js * sass.renderSync({ * data: ` * h1 { * font-size: 40px; * }` * }); * ``` * * @category Input */ data: string; /** * If `file` and [[data]] are both passed, `file` is used as the path of the * stylesheet for error reporting, but [[data]] is used as the contents of the * stylesheet. In this case, `file`’s extension is not used to determine the * syntax of the stylesheet. * * @category Input */ file?: string; /** * This flag controls whether [[data]] is parsed as the indented syntax or * not. * * @example * * ```js * sass.renderSync({ * data: ` * h1 * font-size: 40px`, * indentedSyntax: true * }); * ``` * * @defaultValue `false` * @category Input */ indentedSyntax?: boolean; } /** * Options for [[render]] and [[renderSync]]. This can either be * [[LegacyFileOptions]] to load a file from disk, or [[LegacyStringOptions]] to * compile a string of Sass code. * * See [[LegacySharedOptions]] for options that are shared across both file and * string inputs. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[Options]] with [[compile]], [[compileString]], [[compileAsync]], * and [[compileStringAsync]] instead. */ export type LegacyOptions = | LegacyFileOptions | LegacyStringOptions; render.d.ts000066600000007734150537553630006650 0ustar00import {LegacyException} from './exception'; import {LegacyOptions} from './options'; /** * The object returned by [[render]] and [[renderSync]] after a successful * compilation. * * @category Legacy * @deprecated This is only used by the legacy [[render]] and [[renderSync]] * APIs. Use [[compile]], [[compileString]], [[compileAsync]], and * [[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 * * * [[LegacySharedOptions.sourceMap]] is a string; or * * [[LegacySharedOptions.sourceMap]] is `true` and * [[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 * [[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 [[LegacyFileOptions.file]] or * [[LegacyStringOptions.file]], or `"data"` if [[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 [[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. * * @example * * ```js * const sass = require('sass'); // or require('node-sass'); * * const result = sass.renderSync({file: "style.scss"}); * // ... * ``` * * @category Legacy * @deprecated Use [[compile]] or [[compileString]] instead. */ export function renderSync(options: LegacyOptions<'sync'>): LegacyResult; /** * This function asynchronously compiles a Sass file to CSS, and calls * `callback` with a [[LegacyResult]] if compilation succeeds or * [[LegacyException]] if it fails. * * **Heads up!** When using Dart Sass, **[[renderSync]] is almost twice as fast * as [[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 [[compileAsync]] or [[compileStringAsync]] instead. */ export function render( options: LegacyOptions<'async'>, callback: (exception?: LegacyException, result?: LegacyResult) => void ): void; importer.d.ts000066600000014003150537553630007215 0ustar00import {LegacyPluginThis} from './plugin_this'; /** * The value of `this` in the context of a [[LegacyImporter]] function. * * @category Legacy * @deprecated This is only used by the legacy [[render]] and [[renderSync]] * APIs. Use [[Importer]] with [[compile]], [[compileString]], [[compileAsync]], * and [[compileStringAsync]] instead. */ interface LegacyImporterThis extends LegacyPluginThis { /** * Whether the importer is being invoked because of a Sass `@import` rule, as * opposed to a `@use` or `@forward` rule. * * This should *only* be used for determining whether or not to load * [import-only files](https://sass-lang.com/documentation/at-rules/import#import-only-files). * * @compatibility dart: "1.33.0", node: false */ fromImport: boolean; } /** * The result of running a [[LegacyImporter]]. It must be one of the following * types: * * * An object with the key `contents` whose value is the contents of a stylesheet * (in SCSS syntax). This causes Sass to load that stylesheet’s contents. * * * An object with the key `file` whose value is a path on disk. This causes Sass * to load that file as though it had been imported directly. * * * `null`, which indicates that it doesn’t recognize the URL and another * importer should be tried instead. * * * An [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) * object, indicating that importing failed. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[ImporterResult]] with [[compile]], [[compileString]], * [[compileAsync]], and [[compileStringAsync]] instead. */ export type LegacyImporterResult = | {file: string} | {contents: string} | Error | null; /** * A synchronous callback that implements custom Sass loading logic for * [`@import` rules](https://sass-lang.com/documentation/at-rules/import) and * [`@use` rules](https://sass-lang.com/documentation/at-rules/use). This can be * passed to [[LegacySharedOptions.importer]] for either [[render]] or * [[renderSync]]. * * See [[LegacySharedOptions.importer]] for more detailed documentation. * * ```js * sass.renderSync({ * file: "style.scss", * importer: [ * function(url, prev) { * if (url != "big-headers") return null; * * return { * contents: 'h1 { font-size: 40px; }' * }; * } * ] * }); * ``` * * @param url - The `@use` or `@import` rule’s URL as a string, exactly as it * appears in the stylesheet. * * @param prev - A string identifying the stylesheet that contained the `@use` * or `@import`. This string’s format depends on how that stylesheet was loaded: * * * If the stylesheet was loaded from the filesystem, it’s the absolute path of * its file. * * If the stylesheet was loaded from an importer that returned its contents, * it’s the URL of the `@use` or `@import` rule that loaded it. * * If the stylesheet came from the data option, it’s the string "stdin". * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[Importer]] with [[compile]], [[compileString]], [[compileAsync]], * and [[compileStringAsync]] instead. */ type LegacySyncImporter = ( this: LegacyImporterThis, url: string, prev: string ) => LegacyImporterResult; /** * An asynchronous callback that implements custom Sass loading logic for * [`@import` rules](https://sass-lang.com/documentation/at-rules/import) and * [`@use` rules](https://sass-lang.com/documentation/at-rules/use). This can be * passed to [[LegacySharedOptions.importer]] for either [[render]] or * [[renderSync]]. * * An asynchronous importer must return `undefined`, and then call `done` with * the result of its [[LegacyImporterResult]] once it's done running. * * See [[LegacySharedOptions.importer]] for more detailed documentation. * * ```js * sass.render({ * file: "style.scss", * importer: [ * function(url, prev, done) { * if (url != "big-headers") done(null); * * done({ * contents: 'h1 { font-size: 40px; }' * }); * } * ] * }); * ``` * * @param url - The `@use` or `@import` rule’s URL as a string, exactly as it * appears in the stylesheet. * * @param prev - A string identifying the stylesheet that contained the `@use` * or `@import`. This string’s format depends on how that stylesheet was loaded: * * * If the stylesheet was loaded from the filesystem, it’s the absolute path of * its file. * * If the stylesheet was loaded from an importer that returned its contents, * it’s the URL of the `@use` or `@import` rule that loaded it. * * If the stylesheet came from the data option, it’s the string "stdin". * * @param done - The callback to call once the importer has finished running. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[Importer]] with [[compile]], [[compileString]], [[compileAsync]], * and [[compileStringAsync]] instead. */ type LegacyAsyncImporter = ( this: LegacyImporterThis, url: string, prev: string, done: (result: LegacyImporterResult) => void ) => void; /** * A callback that implements custom Sass loading logic for [`@import` * rules](https://sass-lang.com/documentation/at-rules/import) and [`@use` * rules](https://sass-lang.com/documentation/at-rules/use). For [[renderSync]], * this must be a [[LegacySyncImporter]] which returns its result directly; for * [[render]], it may be either a [[LegacySyncImporter]] or a * [[LegacyAsyncImporter]] which calls a callback with its result. * * See [[LegacySharedOptions.importer]] for more details. * * @category Legacy * @deprecated This only works with the legacy [[render]] and [[renderSync]] * APIs. Use [[Importer]] with [[compile]], [[compileString]], [[compileAsync]], * and [[compileStringAsync]] instead. */ export type LegacyImporter = sync extends 'async' ? LegacySyncImporter | LegacyAsyncImporter : LegacySyncImporter;