@modern-js/module-tools 2.0.0-beta.2 → 2.0.0-beta.4

package/compiled/sass/types/options.d.ts

@@ -0,0 +1,435 @@
+import {FileImporter, Importer} 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
+ * [[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 [[compile]] and [[compileString]] in addition
+ * to [[compileAsync]] and [[compileStringAsync]].
+ *
+ * A `CustomFunction<'async'>` may either return synchronously or
+ * asynchronously, but it can only be used with [[compileAsync]] and
+ * [[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 [[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 [[compileAsync]] and
+ * [[compileStringAsync]], not [[compile]] or [[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<sync extends 'sync' | 'async'> = (
+  args: Value[]
+) => PromiseOr<Value, sync>;
+
+/**
+ * Options that can be passed to [[compile]], [[compileAsync]],
+ * [[compileString]], or [[compileStringAsync]].
+ *
+ * @typeParam sync - This lets the TypeScript checker verify that asynchronous
+ * [[Importer]]s, [[FileImporter]]s, and [[CustomFunction]]s aren't passed to
+ * [[compile]] or [[compileString]].
+ *
+ * @category Options
+ */
+export interface Options<sync extends 'sync' | 'async'> {
+  /**
+   * 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 `<style>` tags. (The output will
+   * still be UTF-8.)
+   *
+   * @defaultValue `true`
+   * @category Output
+   * @compatibility dart: "1.54.0", node: false
+   */
+  charset?: boolean;
+
+  /**
+   * Additional built-in Sass functions that are available in all stylesheets.
+   * This option takes an object whose keys are Sass function signatures like
+   * you'd write for the [`@function
+   * rule`](https://sass-lang.com/documentation/at-rules/function) and whose
+   * values are [[CustomFunction]]s.
+   *
+   * Functions are passed JavaScript representations of [Sass value
+   * types](https://sass-lang.com/documentation/js-api#value-types), and must
+   * return the same.
+   *
+   * When writing custom functions, it's important to make them as user-friendly
+   * and as close to the standards set by Sass's core functions as possible. Some
+   * good guidelines to follow include:
+   *
+   * * Use `Value.assert*` methods, like [[Value.assertString]], to cast untyped
+   *   `Value` objects to more specific types. For values that were passed
+   *   directly as arguments, pass in the argument name as well. This ensures
+   *   that the user gets good error messages when they pass in the wrong type
+   *   to your function.
+   *
+   * * Individual classes may have more specific `assert*` methods, like
+   *   [[SassNumber.assertInt]], which should be used when possible.
+   *
+   * * In Sass, every value counts as a list. Rather than trying to detect the
+   *   [[SassList]] type, you should use [[Value.asList]] to treat all values as
+   *   lists.
+   *
+   * * When manipulating values like lists, strings, and numbers that have
+   *   metadata (comma versus space separated, bracketed versus unbracketed,
+   *   quoted versus unquoted, units), the output metadata should match the
+   *   input metadata.
+   *
+   * * When in doubt, lists should default to comma-separated, strings should
+   *   default to quoted, and numbers should default to unitless.
+   *
+   * * In Sass, lists and strings use one-based indexing and use negative
+   *   indices to index from the end of value. Functions should follow these
+   *   conventions. [[Value.sassIndexToListIndex]] and
+   *   [[SassString.sassIndexToStringIndex]] can be used to do this
+   *   automatically.
+   *
+   * * String indexes in Sass refer to Unicode code points while JavaScript
+   *   string indices refer to UTF-16 code units. For example, the character
+   *   U+1F60A SMILING FACE WITH SMILING EYES is a single Unicode code point but
+   *   is represented in UTF-16 as two code units (`0xD83D` and `0xDE0A`). So in
+   *   JavaScript, `"a😊b".charCodeAt(1)` returns `0xD83D`, whereas in Sass
+   *   `str-slice("a😊b", 1, 1)` returns `"😊"`. Functions should follow Sass's
+   *   convention. [[SassString.sassIndexToStringIndex]] can be used to do this
+   *   automatically, and the [[SassString.sassLength]] getter can be used to
+   *   access a string's length in code points.
+   *
+   * @example
+   *
+   * ```js
+   * sass.compileString(`
+   * h1 {
+   *   font-size: pow(2, 5) * 1px;
+   * }`, {
+   *   functions: {
+   *     // Note: in real code, you should use `math.pow()` from the built-in
+   *     // `sass:math` module.
+   *     'pow($base, $exponent)': function(args) {
+   *       const base = args[0].assertNumber('base').assertNoUnits('base');
+   *       const exponent =
+   *           args[1].assertNumber('exponent').assertNoUnits('exponent');
+   *
+   *       return new sass.SassNumber(Math.pow(base.value, exponent.value));
+   *     }
+   *   }
+   * });
+   * ```
+   *
+   * @category Plugins
+   */
+  functions?: Record<string, CustomFunction<sync>>;
+
+  /**
+   * Custom importers that control how Sass resolves loads from rules like
+   * [`@use`](https://sass-lang.com/documentation/at-rules/use) and
+   * [`@import`](https://sass-lang.com/documentation/at-rules/import).
+   *
+   * Loads are resolved by trying, in order:
+   *
+   * - The importer that was used to load the current stylesheet, with the
+   *   loaded URL resolved relative to the current stylesheet's canonical URL.
+   *
+   * - Each [[Importer]] or [[FileImporter]] in [[importers]], in order.
+   *
+   * - Each load path in [[loadPaths]], in order.
+   *
+   * If none of these return a Sass file, the load fails and Sass throws an
+   * error.
+   *
+   * @category Plugins
+   */
+  importers?: (Importer<sync> | FileImporter<sync>)[];
+
+  /**
+   * Paths in which to look for stylesheets loaded by rules like
+   * [`@use`](https://sass-lang.com/documentation/at-rules/use) and
+   * [`@import`](https://sass-lang.com/documentation/at-rules/import).
+   *
+   * A load path `loadPath` is equivalent to the following [[FileImporter]]:
+   *
+   * ```js
+   * {
+   *   findFileUrl(url) {
+   *     // Load paths only support relative URLs.
+   *     if (/^[a-z]+:/i.test(url)) return null;
+   *     return new URL(url, pathToFileURL(loadPath));
+   *   }
+   * }
+   * ```
+   *
+   * @category Input
+   */
+  loadPaths?: string[];
+
+  /**
+   * 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
+   */
+  logger?: Logger;
+
+  /**
+   * 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 <em>also</em> notify your dependencies of the deprecations
+   * so that they can get fixed as soon as possible!
+   *
+   * **Heads up!** If [[compileString]] or [[compileStringAsync]] is called
+   * without [[StringWithoutImporter.url]], <em>all</em> 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
+   */
+  quietDeps?: boolean;
+
+  /**
+   * Whether or not Sass should generate a source map. If it does, the source
+   * map will be available as [[CompileResult.sourceMap]].
+   *
+   * **Heads up!** Sass doesn't automatically add a `sourceMappingURL` comment
+   * to the generated CSS. It's up to callers to do that, since callers have
+   * full knowledge of where the CSS and the source map will exist in relation
+   * to one another and how they'll be served to the browser.
+   *
+   * @defaultValue `false`
+   * @category Output
+   */
+  sourceMap?: boolean;
+
+  /**
+   * Whether Sass should include the sources in the generated source map.
+   *
+   * This option has no effect if [[sourceMap]] is `false`.
+   *
+   * @defaultValue `false`
+   * @category Output
+   */
+  sourceMapIncludeSources?: boolean;
+
+  /**
+   * The [[OutputStyle]] of the compiled CSS.
+   *
+   * @example
+   *
+   * ```js
+   * const source = `
+   * h1 {
+   *   font-size: 40px;
+   *   code {
+   *     font-face: Roboto Mono;
+   *   }
+   * }`;
+   *
+   * let result = sass.compileString(source, {style: "expanded"});
+   * console.log(result.css.toString());
+   * // h1 {
+   * //   font-size: 40px;
+   * // }
+   * // h1 code {
+   * //   font-face: Roboto Mono;
+   * // }
+   *
+   * result = sass.compileString(source, {style: "compressed"})
+   * console.log(result.css.toString());
+   * // h1{font-size:40px}h1 code{font-face:Roboto Mono}
+   * ```
+   *
+   * @category Output
+   */
+  style?: OutputStyle;
+
+  /**
+   * 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
+   */
+  verbose?: boolean;
+}
+
+/**
+ * Options that can be passed to [[compileString]] or [[compileStringAsync]].
+ *
+ * If the [[StringOptionsWithImporter.importer]] field isn't passed, the
+ * entrypoint file can load files relative to itself if a `file://` URL is
+ * passed to the [[url]] field.
+ *
+ * @typeParam sync - This lets the TypeScript checker verify that asynchronous
+ * [[Importer]]s, [[FileImporter]]s, and [[CustomFunction]]s aren't passed to
+ * [[compile]] or [[compileString]].
+ *
+ * @category Options
+ */
+export interface StringOptionsWithoutImporter<sync extends 'sync' | 'async'>
+  extends Options<sync> {
+  /**
+   * The [[Syntax]] to use to parse the entrypoint stylesheet.
+   *
+   * @default `'scss'`
+   *
+   * @category Input
+   */
+  syntax?: Syntax;
+
+  /**
+   * The canonical URL of the entrypoint stylesheet.
+   *
+   * A relative load's URL is first resolved relative to [[url]], then resolved
+   * to a file on disk if it's a `file://` URL. If it can't be resolved to a
+   * file on disk, it's then passed to [[importers]] and [[loadPaths]].
+   *
+   * @category Input
+   */
+  url?: URL;
+}
+
+/**
+ * Options that can be passed to [[compileString]] or [[compileStringAsync]].
+ *
+ * If the [[StringOptionsWithImporter.importer]] field is passed, the entrypoint
+ * file uses it to load files relative to itself and the [[url]] field is
+ * mandatory.
+ *
+ * @typeParam sync - This lets the TypeScript checker verify that asynchronous
+ * [[Importer]]s, [[FileImporter]]s, and [[CustomFunction]]s aren't passed to
+ * [[compile]] or [[compileString]].
+ *
+ * @category Options
+ */
+export interface StringOptionsWithImporter<sync extends 'sync' | 'async'>
+  extends StringOptionsWithoutImporter<sync> {
+  /**
+   * The importer to use to handle loads that are relative to the entrypoint
+   * stylesheet.
+   *
+   * A relative load's URL is first resolved relative to [[url]], then passed to
+   * [[importer]]. If the importer doesn't recognize it, it's then passed to
+   * [[importers]] and [[loadPaths]].
+   *
+   * @category Input
+   */
+  importer: Importer<sync> | FileImporter<sync>;
+
+  /**
+   * The canonical URL of the entrypoint stylesheet. If this is passed along
+   * with [[importer]], it's used to resolve relative loads in the entrypoint
+   * stylesheet.
+   *
+   * @category Input
+   */
+  url: URL;
+}
+
+/**
+ * Options that can be passed to [[compileString]] or [[compileStringAsync]].
+ *
+ * This is a [[StringOptionsWithImporter]] if it has a
+ * [[StringOptionsWithImporter.importer]] field, and a
+ * [[StringOptionsWithoutImporter]] otherwise.
+ *
+ * @typeParam sync - This lets the TypeScript checker verify that asynchronous
+ * [[Importer]]s, [[FileImporter]]s, and [[CustomFunction]]s aren't passed to
+ * [[compile]] or [[compileString]].
+ *
+ * @category Options
+ */
+export type StringOptions<sync extends 'sync' | 'async'> =
+  | StringOptionsWithImporter<sync>
+  | StringOptionsWithoutImporter<sync>;

package/compiled/sass/types/util/promise_or.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A utility type for choosing between synchronous and asynchronous return
+ * values.
+ *
+ * This is used as the return value for plugins like [[CustomFunction]],
+ * [[Importer]], and [[FileImporter]] so that TypeScript enforces that
+ * asynchronous plugins are only passed to [[compileAsync]] and
+ * [[compileStringAsync]], not [[compile]] or [[compileString]].
+ *
+ * @typeParam sync - If this is `'sync'`, this can only be a `T`. If it's
+ * `'async'`, this can be either a `T` or a `Promise<T>`.
+ *
+ * @category Other
+ */
+export type PromiseOr<T, sync extends 'sync' | 'async'> = sync extends 'async'
+  ? T | Promise<T>
+  : T;

package/compiled/sass/types/value/argument_list.d.ts

@@ -0,0 +1,47 @@
+import {List, OrderedMap} from 'immutable';
+
+import {Value} from './index';
+import {SassList, ListSeparator} from './list';
+
+/**
+ * Sass's [argument list
+ * type](https://sass-lang.com/documentation/values/lists#argument-lists).
+ *
+ * An argument list comes from a rest argument. It's distinct from a normal
+ * [[SassList]] in that it may contain a keyword map as well as the positional
+ * arguments.
+ *
+ * @category Custom Function
+ */
+export class SassArgumentList extends SassList {
+  /**
+   * Creates a new argument list.
+   *
+   * @param contents - The positional arguments that make up the primary
+   * contents of the list. This may be either a plain JavaScript array or an
+   * immutable [[List]] from the [`immutable`
+   * package](https://immutable-js.com/).
+   *
+   * @param keywords - The keyword arguments attached to this argument list,
+   * whose names should exclude `$`. This can be either a plain JavaScript
+   * object with argument names as fields, or an immutable [[OrderedMap]] from
+   * the [`immutable` package](https://immutable-js.com/)
+   *
+   * @param separator - The separator for this list. Defaults to `','`.
+   */
+  constructor(
+    contents: Value[] | List<Value>,
+    keywords: Record<string, Value> | OrderedMap<string, Value>,
+    separator?: ListSeparator
+  );
+
+  /**
+   * The keyword arguments attached to this argument list.
+   *
+   * The argument names don't include `$`.
+   *
+   * @returns An immutable [[OrderedMap]] from the [`immutable`
+   * package](https://immutable-js.com/).
+   */
+  get keywords(): OrderedMap<string, Value>;
+}

package/compiled/sass/types/value/boolean.d.ts

@@ -0,0 +1,29 @@
+import {Value} from './index';
+
+/**
+ * Sass's [`true` value](https://sass-lang.com/documentation/values/booleans).
+ *
+ * @category Custom Function
+ */
+export const sassTrue: SassBoolean;
+
+/**
+ * Sass's [`false` value](https://sass-lang.com/documentation/values/booleans).
+ *
+ * @category Custom Function
+ */
+export const sassFalse: SassBoolean;
+
+/**
+ * Sass's [boolean type](https://sass-lang.com/documentation/values/booleans).
+ *
+ * @category Custom Function
+ */
+export class SassBoolean extends Value {
+  private constructor();
+
+  /**
+   * Whether this value is `true` or `false`.
+   */
+  get value(): boolean;
+}

package/compiled/sass/types/value/color.d.ts

@@ -0,0 +1,107 @@
+import {Value} from './index';
+
+/**
+ * Sass's [color type](https://sass-lang.com/documentation/values/colors).
+ *
+ * No matter what representation was originally used to create this color, all
+ * of its channels are accessible.
+ *
+ * @category Custom Function
+ */
+export class SassColor extends Value {
+  /**
+   * Creates an RGB color.
+   *
+   * @throws `Error` if `red`, `green`, and `blue` aren't between `0` and
+   * `255`, or if `alpha` isn't between `0` and `1`.
+   */
+  constructor(options: {
+    red: number;
+    green: number;
+    blue: number;
+    alpha?: number;
+  });
+
+  /**
+   * Creates an HSL color.
+   *
+   * @throws `Error` if `saturation` or `lightness` aren't between `0` and
+   * `100`, or if `alpha` isn't between `0` and `1`.
+   */
+  constructor(options: {
+    hue: number;
+    saturation: number;
+    lightness: number;
+    alpha?: number;
+  });
+
+  /**
+   * Creates an HWB color.
+   *
+   * @throws `Error` if `whiteness` or `blackness` aren't between `0` and `100`,
+   * or if `alpha` isn't between `0` and `1`.
+   */
+  constructor(options: {
+    hue: number;
+    whiteness: number;
+    blackness: number;
+    alpha?: number;
+  });
+
+  /** This color's red channel, between `0` and `255`. */
+  get red(): number;
+
+  /** This color's green channel, between `0` and `255`. */
+  get green(): number;
+
+  /** This color's blue channel, between `0` and `255`. */
+  get blue(): number;
+
+  /** This color's hue, between `0` and `360`. */
+  get hue(): number;
+
+  /** This color's saturation, between `0` and `100`. */
+  get saturation(): number;
+
+  /** This color's lightness, between `0` and `100`. */
+  get lightness(): number;
+
+  /** This color's whiteness, between `0` and `100`. */
+  get whiteness(): number;
+
+  /** This color's blackness, between `0` and `100`. */
+  get blackness(): number;
+
+  /** This color's alpha channel, between `0` and `1`. */
+  get alpha(): number;
+
+  /**
+   * Changes one or more of this color's RGB channels and returns the result.
+   */
+  change(options: {
+    red?: number;
+    green?: number;
+    blue?: number;
+    alpha?: number;
+  }): SassColor;
+
+  /**
+   * Changes one or more of this color's HSL channels and returns the result.
+   */
+  change(options: {
+    hue?: number;
+    saturation?: number;
+    lightness?: number;
+    alpha?: number;
+  }): SassColor;
+
+  /**
+   * Changes one or more of this color's HWB channels and returns the result.
+   */
+  change(options: {
+    hue?: number;
+    whiteness?: number;
+    blackness?: number;
+    alpha?: number;
+  }): SassColor;
+}

package/compiled/sass/types/value/function.d.ts

@@ -0,0 +1,22 @@
+import {Value} from './index';
+
+/**
+ * Sass's [function type](https://sass-lang.com/documentation/values/functions).
+ *
+ * **Heads up!** Although first-class Sass functions can be processed by custom
+ * functions, there's no way to invoke them outside of a Sass stylesheet.
+ *
+ * @category Custom Function
+ */
+export class SassFunction extends Value {
+  /**
+   * Creates a new first-class function that can be invoked using
+   * [`meta.call()`](https://sass-lang.com/documentation/modules/meta#call).
+   *
+   * @param signature - The function signature, like you'd write for the
+   * [`@function rule`](https://sass-lang.com/documentation/at-rules/function).
+   * @param callback - The callback that's invoked when this function is called,
+   * just like for a [[CustomFunction]].
+   */
+  constructor(signature: string, callback: (args: Value[]) => Value);
+}