19a487ee8cff9d61b20bb418b9df4448df33da8a16384f0853ccf72ec12443236849ae4be448378b3f74fdb82829a7ef20a25ad09fa34795a652f3e9553fb5 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342
  1. import {RawSourceMap} from 'source-map-js';
  2. import {Options, StringOptions} from './options';
  3. /**
  4. * The result of compiling Sass to CSS. Returned by {@link compile}, {@link
  5. * compileAsync}, {@link compileString}, and {@link compileStringAsync}.
  6. *
  7. * @category Compile
  8. */
  9. export interface CompileResult {
  10. /**
  11. * The generated CSS.
  12. *
  13. * Note that this *never* includes a `sourceMapUrl` comment—it's up to the
  14. * caller to determine where to save the source map and how to link to it from
  15. * the stylesheet.
  16. */
  17. css: string;
  18. /**
  19. * The canonical URLs of all the stylesheets that were loaded during the
  20. * Sass compilation. The order of these URLs is not guaranteed.
  21. */
  22. loadedUrls: URL[];
  23. /**
  24. * The object representation of the source map that maps locations in the
  25. * generated CSS back to locations in the Sass source code.
  26. *
  27. * This typically uses absolute `file:` URLs to refer to Sass files, although
  28. * this can be controlled by having a custom {@link Importer} return {@link
  29. * ImporterResult.sourceMapUrl}.
  30. *
  31. * This is set if and only if {@link Options.sourceMap} is `true`.
  32. */
  33. sourceMap?: RawSourceMap;
  34. }
  35. /**
  36. * The result of creating a synchronous compiler. Returned by
  37. * {@link initCompiler}.
  38. *
  39. * @category Compile
  40. */
  41. export class Compiler {
  42. /**
  43. * Throws an error if constructed directly, instead of via
  44. * {@link initCompiler}.
  45. */
  46. private constructor();
  47. /**
  48. * The {@link compile} method exposed through a Compiler instance while it is
  49. * active. If this is called after {@link dispose} on the Compiler
  50. * instance, an error will be thrown.
  51. *
  52. * During the Compiler instance's lifespan, given the same input, this will
  53. * return an identical result to the {@link compile} method exposed at the
  54. * module root.
  55. */
  56. compile(path: string, options?: Options<'sync'>): CompileResult;
  57. /**
  58. * The {@link compileString} method exposed through a Compiler instance while
  59. * it is active. If this is called after {@link dispose} on the Compiler
  60. * instance, an error will be thrown.
  61. *
  62. * During the Compiler instance's lifespan, given the same input, this will
  63. * return an identical result to the {@link compileString} method exposed at
  64. * the module root.
  65. */
  66. compileString(source: string, options?: StringOptions<'sync'>): CompileResult;
  67. /**
  68. * Ends the lifespan of this Compiler instance. After this is invoked, all
  69. * calls to the Compiler instance's {@link compile} or {@link compileString}
  70. * methods will result in an error.
  71. */
  72. dispose(): void;
  73. }
  74. /**
  75. * The result of creating an asynchronous compiler. Returned by
  76. * {@link initAsyncCompiler}.
  77. *
  78. * @category Compile
  79. */
  80. export class AsyncCompiler {
  81. /**
  82. * Throws an error if constructed directly, instead of via
  83. * {@link initAsyncCompiler}.
  84. */
  85. private constructor();
  86. /**
  87. * The {@link compileAsync} method exposed through an Async Compiler instance
  88. * while it is active. If this is called after {@link dispose} on the Async
  89. * Compiler instance, an error will be thrown.
  90. *
  91. * During the Async Compiler instance's lifespan, given the same input, this
  92. * will return an identical result to the {@link compileAsync} method exposed
  93. * at the module root.
  94. */
  95. compileAsync(
  96. path: string,
  97. options?: Options<'async'>
  98. ): Promise<CompileResult>;
  99. /**
  100. * The {@link compileStringAsync} method exposed through an Async Compiler
  101. * instance while it is active. If this is called after {@link dispose} on the
  102. * Async Compiler instance, an error will be thrown.
  103. *
  104. * During the Async Compiler instance's lifespan, given the same input, this
  105. * will return an identical result to the {@link compileStringAsync} method
  106. * exposed at the module root.
  107. */
  108. compileStringAsync(
  109. source: string,
  110. options?: StringOptions<'async'>
  111. ): Promise<CompileResult>;
  112. /**
  113. * Ends the lifespan of this Async Compiler instance. After this is invoked,
  114. * all subsequent calls to the Compiler instance's `compileAsync` or
  115. * `compileStringAsync` methods will result in an error.
  116. *
  117. * Any compilations that are submitted before `dispose` will not be cancelled,
  118. * and will be allowed to settle.
  119. *
  120. * After all compilations have been settled and Sass completes any internal
  121. * task cleanup, `dispose` will resolve its promise.
  122. */
  123. dispose(): Promise<void>;
  124. }
  125. /**
  126. * Synchronously compiles the Sass file at `path` to CSS. If it succeeds it
  127. * returns a {@link CompileResult}, and if it fails it throws an {@link
  128. * Exception}.
  129. *
  130. * This only allows synchronous {@link Importer}s and {@link CustomFunction}s.
  131. *
  132. * **Heads up!** When using the [sass-embedded] npm package for single
  133. * compilations, **{@link compileAsync} is almost always faster than
  134. * {@link compile}**, due to the overhead of emulating synchronous messaging
  135. * with worker threads and concurrent compilations being blocked on main thread.
  136. *
  137. * If you are running multiple compilations with the [sass-embedded] npm
  138. * package, using a {@link Compiler} will provide some speed improvements over
  139. * the module-level methods, and an {@link AsyncCompiler} will be much faster.
  140. *
  141. * [sass-embedded]: https://www.npmjs.com/package/sass-embedded
  142. *
  143. * @example
  144. *
  145. * ```js
  146. * const sass = require('sass');
  147. *
  148. * const result = sass.compile("style.scss");
  149. * console.log(result.css);
  150. * ```
  151. *
  152. * @category Compile
  153. * @compatibility dart: "1.45.0", node: false
  154. */
  155. export function compile(path: string, options?: Options<'sync'>): CompileResult;
  156. /**
  157. * Asynchronously compiles the Sass file at `path` to CSS. Returns a promise
  158. * that resolves with a {@link CompileResult} if it succeeds and rejects with an
  159. * {@link Exception} if it fails.
  160. *
  161. * This only allows synchronous or asynchronous {@link Importer}s and
  162. * {@link CustomFunction}s.
  163. *
  164. * **Heads up!** When using the `sass` npm package, **{@link compile} is almost
  165. * twice as fast as {@link compileAsync}**, due to the overhead of making the
  166. * entire evaluation process asynchronous.
  167. *
  168. * @example
  169. *
  170. * ```js
  171. * const sass = require('sass');
  172. *
  173. * const result = await sass.compileAsync("style.scss");
  174. * console.log(result.css);
  175. * ```
  176. *
  177. * @category Compile
  178. * @compatibility dart: "1.45.0", node: false
  179. */
  180. export function compileAsync(
  181. path: string,
  182. options?: Options<'async'>
  183. ): Promise<CompileResult>;
  184. /**
  185. * Synchronously compiles a stylesheet whose contents is `source` to CSS. If it
  186. * succeeds it returns a {@link CompileResult}, and if it fails it throws an
  187. * {@link Exception}.
  188. *
  189. * This only allows synchronous {@link Importer}s and {@link CustomFunction}s.
  190. *
  191. * **Heads up!** When using the [sass-embedded] npm package for single
  192. * compilations, **{@link compileStringAsync} is almost always faster than
  193. * {@link compileString}**, due to the overhead of emulating synchronous
  194. * messaging with worker threads and concurrent compilations being blocked on
  195. * main thread.
  196. *
  197. * If you are running multiple compilations with the [sass-embedded] npm
  198. * package, using a {@link Compiler} will provide some speed improvements over
  199. * the module-level methods, and an {@link AsyncCompiler} will be much faster.
  200. *
  201. * [sass-embedded]: https://www.npmjs.com/package/sass-embedded
  202. *
  203. * @example
  204. *
  205. * ```js
  206. * const sass = require('sass');
  207. *
  208. * const result = sass.compileString(`
  209. * h1 {
  210. * font-size: 40px;
  211. * code {
  212. * font-face: Roboto Mono;
  213. * }
  214. * }`);
  215. * console.log(result.css);
  216. * ```
  217. *
  218. * @category Compile
  219. * @compatibility dart: "1.45.0", node: false
  220. */
  221. export function compileString(
  222. source: string,
  223. options?: StringOptions<'sync'>
  224. ): CompileResult;
  225. /**
  226. * Asynchronously compiles a stylesheet whose contents is `source` to CSS.
  227. * Returns a promise that resolves with a {@link CompileResult} if it succeeds
  228. * and rejects with an {@link Exception} if it fails.
  229. *
  230. * This only allows synchronous or asynchronous {@link Importer}s and {@link
  231. * CustomFunction}s.
  232. *
  233. * **Heads up!** When using the `sass` npm package, **{@link compileString} is
  234. * almost twice as fast as {@link compileStringAsync}**, due to the overhead
  235. * of making the entire evaluation process asynchronous.
  236. *
  237. * @example
  238. *
  239. * ```js
  240. * const sass = require('sass');
  241. *
  242. * const result = await sass.compileStringAsync(`
  243. * h1 {
  244. * font-size: 40px;
  245. * code {
  246. * font-face: Roboto Mono;
  247. * }
  248. * }`);
  249. * console.log(result.css);
  250. * ```
  251. *
  252. * @category Compile
  253. * @compatibility dart: "1.45.0", node: false
  254. */
  255. export function compileStringAsync(
  256. source: string,
  257. options?: StringOptions<'async'>
  258. ): Promise<CompileResult>;
  259. /**
  260. * Creates a synchronous {@link Compiler}. Each compiler instance exposes the
  261. * {@link compile} and {@link compileString} methods within the lifespan of the
  262. * Compiler. Given identical input, these methods will return results identical
  263. * to their counterparts exposed at the module root. To use asynchronous
  264. * compilation, use {@link initAsyncCompiler}.
  265. *
  266. * When calling the compile functions multiple times, using a compiler instance
  267. * with the [sass-embedded] npm package is much faster than using the top-level
  268. * compilation methods or the [sass] npm package.
  269. *
  270. * [sass-embedded]: https://www.npmjs.com/package/sass-embedded
  271. *
  272. * [sass]: https://www.npmjs.com/package/sass
  273. *
  274. * @example
  275. *
  276. * ```js
  277. * const sass = require('sass');
  278. * function setup() {
  279. * const compiler = sass.initCompiler();
  280. * const result1 = compiler.compileString('a {b: c}').css;
  281. * const result2 = compiler.compileString('a {b: c}').css;
  282. * compiler.dispose();
  283. *
  284. * // throws error
  285. * const result3 = sass.compileString('a {b: c}').css;
  286. * }
  287. * ```
  288. * @category Compile
  289. * @compatibility dart: "1.70.0", node: false
  290. */
  291. export function initCompiler(): Compiler;
  292. /**
  293. * Creates an asynchronous {@link AsyncCompiler}. Each compiler
  294. * instance exposes the {@link compileAsync} and {@link compileStringAsync}
  295. * methods within the lifespan of the Compiler. Given identical input, these
  296. * methods will return results identical to their counterparts exposed at the
  297. * module root. To use synchronous compilation, use {@link initCompiler};
  298. *
  299. * When calling the compile functions multiple times, using a compiler instance
  300. * with the [sass-embedded] npm package is much faster than using the top-level
  301. * compilation methods or the [sass] npm package.
  302. *
  303. * [sass-embedded]: https://www.npmjs.com/package/sass-embedded
  304. *
  305. * [sass]: https://www.npmjs.com/package/sass
  306. *
  307. * @example
  308. *
  309. * ```js
  310. * const sass = require('sass');
  311. * async function setup() {
  312. * const compiler = await sass.initAsyncCompiler();
  313. * const result1 = await compiler.compileStringAsync('a {b: c}').css;
  314. * const result2 = await compiler.compileStringAsync('a {b: c}').css;
  315. * await compiler.dispose();
  316. *
  317. * // throws error
  318. * const result3 = await sass.compileStringAsync('a {b: c}').css;
  319. * }
  320. * ```
  321. * @category Compile
  322. * @compatibility dart: "1.70.0", node: false
  323. */
  324. export function initAsyncCompiler(): Promise<AsyncCompiler>;