import {DeprecationOrId, Version} from './deprecations'; import {FileImporter, Importer, NodePackageImporter} from './importer'; import {Logger} from './logger'; import {Value} from './value'; import {PromiseOr} from './util/promise_or'; /** * Syntaxes supported by Sass: * * - `'scss'` is the [SCSS * syntax](https://sass-lang.com/documentation/syntax#scss). * - `'indented'` is the [indented * syntax](https://sass-lang.com/documentation/syntax#the-indented-syntax) * - `'css'` is plain CSS, which is parsed like SCSS but forbids the use of any * special Sass features. * * @category Options */ export type Syntax = 'scss' | 'indented' | 'css'; /** * Possible output styles for the compiled CSS: * * - `"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. * * @category Options */ export type OutputStyle = 'expanded' | 'compressed'; /** * A callback that implements a custom Sass function. This can be passed to * {@link Options.functions}. * * ```js * const result = sass.compile('style.scss', { * functions: { * "sum($arg1, $arg2)": (args) => { * const arg1 = args[0].assertNumber('arg1'); * const value1 = arg1.value; * const value2 = args[1].assertNumber('arg2') * .convertValueToMatch(arg1, 'arg2', 'arg1'); * return new sass.SassNumber(value1 + value2).coerceToMatch(arg1); * } * } * }); * ``` * * @typeParam sync - A `CustomFunction<'sync'>` must return synchronously, but * in return it can be passed to {@link compile} and {@link compileString} in * addition to {@link compileAsync} and {@link compileStringAsync}. * * A `CustomFunction<'async'>` may either return synchronously or * asynchronously, but it can only be used with {@link compileAsync} and {@link * compileStringAsync}. * * @param args - An array of arguments passed by the function's caller. If the * function takes [arbitrary * arguments](https://sass-lang.com/documentation/at-rules/function#taking-arbitrary-arguments), * the last element will be a {@link SassArgumentList}. * * @returns The function's result. This may be in the form of a `Promise`, but * if it is the function may only be passed to {@link compileAsync} and {@link * compileStringAsync}, not {@link compile} or {@link compileString}. * * @throws any - This function may throw an error, which the Sass compiler will * treat as the function call failing. If the exception object has a `message` * property, it will be used as the wrapped exception's message; otherwise, the * exception object's `toString()` will be used. This means it's safe for custom * functions to throw plain strings. * * @category Custom Function */ export type CustomFunction = ( args: Value[] ) => PromiseOr; /** * Options that can be passed to {@link compile}, {@link compileAsync}, {@link * compileString}, or {@link compileStringAsync}. * * @typeParam sync - This lets the TypeScript checker verify that asynchronous * {@link Importer}s, {@link FileImporter}s, and {@link CustomFunction}s aren't * passed to {@link compile} or {@link compileString}. * * @category Options */ export interface Options { /** * If this is `true`, the compiler will exclusively use ASCII characters in * its error and warning messages. Otherwise, it may use non-ASCII Unicode * characters as well. * * @defaultValue `false` * @category Messages */ alertAscii?: boolean; /** * If this is `true`, the compiler will use ANSI color escape codes in its * error and warning messages. If it's `false`, it won't use these. If it's * undefined, the compiler will determine whether or not to use colors * depending on whether the user is using an interactive terminal. * * @category Messages */ alertColor?: boolean; /** * If `true`, the compiler may prepend `@charset "UTF-8";` or U+FEFF * (byte-order marker) if it outputs non-ASCII CSS. * * If `false`, the compiler never emits these byte sequences. This is ideal * when concatenating or embedding in HTML `