postcss 8.3.9 → 8.4.31

package/lib/postcss.js

@@ -27,22 +27,27 @@ function postcss(...plugins) {
 }
 
 postcss.plugin = function plugin(name, initializer) {
-  if (console && console.warn) {
-    console.warn(
-      name +
-        ': postcss.plugin was deprecated. Migration guide:\n' +
-        'https://evilmartians.com/chronicles/postcss-8-plugin-migration'
-    )
-    if (process.env.LANG && process.env.LANG.startsWith('cn')) {
-      // istanbul ignore next
+  let warningPrinted = false
+  function creator(...args) {
+    // eslint-disable-next-line no-console
+    if (console && console.warn && !warningPrinted) {
+      warningPrinted = true
+      // eslint-disable-next-line no-console
       console.warn(
         name +
-          ': 里面 postcss.plugin 被弃用. 迁移指南:\n' +
-          'https://www.w3ctech.com/topic/2226'
+          ': postcss.plugin was deprecated. Migration guide:\n' +
+          'https://evilmartians.com/chronicles/postcss-8-plugin-migration'
       )
+      if (process.env.LANG && process.env.LANG.startsWith('cn')) {
+        /* c8 ignore next 7 */
+        // eslint-disable-next-line no-console
+        console.warn(
+          name +
+            ': 里面 postcss.plugin 被弃用. 迁移指南:\n' +
+            'https://www.w3ctech.com/topic/2226'
+        )
+      }
     }
-  }
-  function creator(...args) {
     let transformer = initializer(...args)
     transformer.postcssPlugin = name
     transformer.postcssVersion = new Processor().version
@@ -79,6 +84,7 @@ postcss.document = defaults => new Document(defaults)
 postcss.CssSyntaxError = CssSyntaxError
 postcss.Declaration = Declaration
 postcss.Container = Container
+postcss.Processor = Processor
 postcss.Document = Document
 postcss.Comment = Comment
 postcss.Warning = Warning

package/lib/postcss.mjs

@@ -18,6 +18,7 @@ export const root = postcss.root
 export const CssSyntaxError = postcss.CssSyntaxError
 export const Declaration = postcss.Declaration
 export const Container = postcss.Container
+export const Processor = postcss.Processor
 export const Document = postcss.Document
 export const Comment = postcss.Comment
 export const Warning = postcss.Warning

package/lib/previous-map.d.ts

@@ -2,6 +2,11 @@ import { SourceMapConsumer } from 'source-map-js'
 
 import { ProcessOptions } from './postcss.js'
 
+declare namespace PreviousMap {
+  // eslint-disable-next-line @typescript-eslint/no-use-before-define
+  export { PreviousMap_ as default }
+}
+
 /**
  * Source map information from input CSS.
  * For example, source map after Sass compiler.
@@ -14,37 +19,37 @@ import { ProcessOptions } from './postcss.js'
  * root.input.map //=> PreviousMap
  * ```
  */
-export default class PreviousMap {
+declare class PreviousMap_ {
   /**
-   * Was source map inlined by data-uri to input CSS.
+   * `sourceMappingURL` content.
    */
-  inline: boolean
+  annotation?: string
 
   /**
-   * `sourceMappingURL` content.
+   * The CSS source identifier. Contains `Input#file` if the user
+   * set the `from` option, or `Input#id` if they did not.
    */
-  annotation?: string
+  file?: string
 
   /**
-   * Source map file content.
+   * Was source map inlined by data-uri to input CSS.
    */
-  text?: string
+  inline: boolean
 
   /**
-   * The directory with source map file, if source map is in separated file.
+   * Path to source map file.
    */
-  root?: string
+  mapFile?: string
 
   /**
-   * The CSS source identifier. Contains `Input#file` if the user
-   * set the `from` option, or `Input#id` if they did not.
+   * The directory with source map file, if source map is in separated file.
    */
-  file?: string
+  root?: string
 
   /**
-   * Path to source map file.
+   * Source map file content.
    */
-  mapFile?: string
+  text?: string
 
   /**
    * @param css  Input CSS source.
@@ -70,3 +75,7 @@ export default class PreviousMap {
    */
   withContent(): boolean
 }
+
+declare class PreviousMap extends PreviousMap_ {}
+
+export = PreviousMap

package/lib/previous-map.js

@@ -8,7 +8,7 @@ function fromBase64(str) {
   if (Buffer) {
     return Buffer.from(str, 'base64').toString()
   } else {
-    // istanbul ignore next
+    /* c8 ignore next 2 */
     return window.atob(str)
   }
 }
@@ -35,39 +35,6 @@ class PreviousMap {
     return this.consumerCache
   }
 
-  withContent() {
-    return !!(
-      this.consumer().sourcesContent &&
-      this.consumer().sourcesContent.length > 0
-    )
-  }
-
-  startWith(string, start) {
-    if (!string) return false
-    return string.substr(0, start.length) === start
-  }
-
-  getAnnotationURL(sourceMapString) {
-    return sourceMapString
-      .match(/\/\*\s*# sourceMappingURL=((?:(?!sourceMappingURL=).)*)\*\//)[1]
-      .trim()
-  }
-
-  loadAnnotation(css) {
-    let annotations = css.match(
-      /\/\*\s*# sourceMappingURL=(?:(?!sourceMappingURL=).)*\*\//gm
-    )
-
-    if (annotations && annotations.length > 0) {
-      // Locate the last sourceMappingURL to avoid picking up
-      // sourceMappingURLs from comments, strings, etc.
-      let lastAnnotation = annotations[annotations.length - 1]
-      if (lastAnnotation) {
-        this.annotation = this.getAnnotationURL(lastAnnotation)
-      }
-    }
-  }
-
   decodeInline(text) {
     let baseCharsetUri = /^data:application\/json;charset=utf-?8;base64,/
     let baseUri = /^data:application\/json;base64,/
@@ -86,6 +53,33 @@ class PreviousMap {
     throw new Error('Unsupported source map encoding ' + encoding)
   }
 
+  getAnnotationURL(sourceMapString) {
+    return sourceMapString.replace(/^\/\*\s*# sourceMappingURL=/, '').trim()
+  }
+
+  isMap(map) {
+    if (typeof map !== 'object') return false
+    return (
+      typeof map.mappings === 'string' ||
+      typeof map._mappings === 'string' ||
+      Array.isArray(map.sections)
+    )
+  }
+
+  loadAnnotation(css) {
+    let comments = css.match(/\/\*\s*# sourceMappingURL=/gm)
+    if (!comments) return
+
+    // sourceMappingURLs from comments, strings, etc.
+    let start = css.lastIndexOf(comments.pop())
+    let end = css.indexOf('*/', start)
+
+    if (start > -1 && end > -1) {
+      // Locate the last sourceMappingURL to avoid pickin
+      this.annotation = this.getAnnotationURL(css.substring(start, end))
+    }
+  }
+
   loadFile(path) {
     this.root = dirname(path)
     if (existsSync(path)) {
@@ -131,12 +125,15 @@ class PreviousMap {
     }
   }
 
-  isMap(map) {
-    if (typeof map !== 'object') return false
-    return (
-      typeof map.mappings === 'string' ||
-      typeof map._mappings === 'string' ||
-      Array.isArray(map.sections)
+  startWith(string, start) {
+    if (!string) return false
+    return string.substr(0, start.length) === start
+  }
+
+  withContent() {
+    return !!(
+      this.consumer().sourcesContent &&
+      this.consumer().sourcesContent.length > 0
     )
   }
 }

package/lib/processor.d.ts

@@ -1,51 +1,85 @@
+import Document from './document.js'
+import LazyResult from './lazy-result.js'
+import NoWorkResult from './no-work-result.js'
 import {
   AcceptedPlugin,
   Plugin,
   ProcessOptions,
-  Transformer,
-  TransformCallback
+  TransformCallback,
+  Transformer
 } from './postcss.js'
-import LazyResult from './lazy-result.js'
 import Result from './result.js'
 import Root from './root.js'
 
+declare namespace Processor {
+  // eslint-disable-next-line @typescript-eslint/no-use-before-define
+  export { Processor_ as default }
+}
+
 /**
  * Contains plugins to process CSS. Create one `Processor` instance,
  * initialize its plugins, and then use that instance on numerous CSS files.
  *
  * ```js
- * const processor = postcss([autoprefixer, precss])
+ * const processor = postcss([autoprefixer, postcssNested])
  * processor.process(css1).then(result => console.log(result.css))
  * processor.process(css2).then(result => console.log(result.css))
  * ```
  */
-export default class Processor {
+declare class Processor_ {
   /**
-   * Current PostCSS version.
+   * Plugins added to this processor.
    *
    * ```js
-   * if (result.processor.version.split('.')[0] !== '6') {
-   *   throw new Error('This plugin works only with PostCSS 6')
-   * }
+   * const processor = postcss([autoprefixer, postcssNested])
+   * processor.plugins.length //=> 2
    * ```
    */
-  version: string
+  plugins: (Plugin | TransformCallback | Transformer)[]
 
   /**
-   * Plugins added to this processor.
+   * Current PostCSS version.
    *
    * ```js
-   * const processor = postcss([autoprefixer, precss])
-   * processor.plugins.length //=> 2
+   * if (result.processor.version.split('.')[0] !== '6') {
+   *   throw new Error('This plugin works only with PostCSS 6')
+   * }
    * ```
    */
-  plugins: (Plugin | Transformer | TransformCallback)[]
+  version: string
 
   /**
    * @param plugins PostCSS plugins
    */
   constructor(plugins?: AcceptedPlugin[])
 
+  /**
+   * Parses source CSS and returns a `LazyResult` Promise proxy.
+   * Because some plugins can be asynchronous it doesn’t make
+   * any transformations. Transformations will be applied
+   * in the `LazyResult` methods.
+   *
+   * ```js
+   * processor.process(css, { from: 'a.css', to: 'a.out.css' })
+   *   .then(result => {
+   *      console.log(result.css)
+   *   })
+   * ```
+   *
+   * @param css String with input CSS or any object with a `toString()` method,
+   *            like a Buffer. Optionally, send a `Result` instance
+   *            and the processor will take the `Root` from it.
+   * @param opts Options.
+   * @return Promise proxy.
+   */
+  process(
+    css: { toString(): string } | LazyResult | Result | Root | string
+  ): LazyResult | NoWorkResult
+  process<RootNode extends Document | Root = Root>(
+    css: { toString(): string } | LazyResult | Result | Root | string,
+    options: ProcessOptions<RootNode>
+  ): LazyResult<RootNode>
+
   /**
    * Adds a plugin to be used as a CSS processor.
    *
@@ -53,7 +87,7 @@ export default class Processor {
    * * A plugin in `Plugin` format.
    * * A plugin creator function with `pluginCreator.postcss = true`.
    *   PostCSS will call this function without argument to get plugin.
-   * * A function. PostCSS will pass the function a @{link Root}
+   * * A function. PostCSS will pass the function a {@link Root}
    *   as the first argument and current `Result` instance
    *   as the second.
    * * Another `Processor` instance. PostCSS will copy plugins
@@ -67,35 +101,15 @@ export default class Processor {
    * ```js
    * const processor = postcss()
    *   .use(autoprefixer)
-   *   .use(precss)
+   *   .use(postcssNested)
    * ```
    *
    * @param plugin PostCSS plugin or `Processor` with plugins.
-   * @return {Processes} Current processor to make methods chain.
+   * @return Current processor to make methods chain.
    */
   use(plugin: AcceptedPlugin): this
-
-  /**
-   * Parses source CSS and returns a `LazyResult` Promise proxy.
-   * Because some plugins can be asynchronous it doesn’t make
-   * any transformations. Transformations will be applied
-   * in the `LazyResult` methods.
-   *
-   * ```js
-   * processor.process(css, { from: 'a.css', to: 'a.out.css' })
-   *   .then(result => {
-   *      console.log(result.css)
-   *   })
-   * ```
-   *
-   * @param css String with input CSS or any object with a `toString()` method,
-   *            like a Buffer. Optionally, senda `Result` instance
-   *            and the processor will take the `Root` from it.
-   * @param opts Options.
-   * @return Promise proxy.
-   */
-  process(
-    css: string | { toString(): string } | Result | LazyResult | Root,
-    options?: ProcessOptions
-  ): LazyResult
 }
+
+declare class Processor extends Processor_ {}
+
+export = Processor

package/lib/processor.js

@@ -1,41 +1,16 @@
 'use strict'
 
+let NoWorkResult = require('./no-work-result')
 let LazyResult = require('./lazy-result')
 let Document = require('./document')
 let Root = require('./root')
 
 class Processor {
   constructor(plugins = []) {
-    this.version = '8.3.9'
+    this.version = '8.4.31'
     this.plugins = this.normalize(plugins)
   }
 
-  use(plugin) {
-    this.plugins = this.plugins.concat(this.normalize([plugin]))
-    return this
-  }
-
-  process(css, opts = {}) {
-    if (
-      this.plugins.length === 0 &&
-      typeof opts.parser === 'undefined' &&
-      typeof opts.stringifier === 'undefined' &&
-      typeof opts.syntax === 'undefined' &&
-      !opts.hideNothingWarning
-    ) {
-      if (process.env.NODE_ENV !== 'production') {
-        if (typeof console !== 'undefined' && console.warn) {
-          console.warn(
-            'You did not set any plugins, parser, or stringifier. ' +
-              'Right now, PostCSS does nothing. Pick plugins for your case ' +
-              'on https://www.postcss.parts/ and use them in postcss.config.js.'
-          )
-        }
-      }
-    }
-    return new LazyResult(this, css, opts)
-  }
-
   normalize(plugins) {
     let normalized = []
     for (let i of plugins) {
@@ -65,6 +40,24 @@ class Processor {
     }
     return normalized
   }
+
+  process(css, opts = {}) {
+    if (
+      this.plugins.length === 0 &&
+      typeof opts.parser === 'undefined' &&
+      typeof opts.stringifier === 'undefined' &&
+      typeof opts.syntax === 'undefined'
+    ) {
+      return new NoWorkResult(this, css, opts)
+    } else {
+      return new LazyResult(this, css, opts)
+    }
+  }
+
+  use(plugin) {
+    this.plugins = this.plugins.concat(this.normalize([plugin]))
+    return this
+  }
 }
 
 module.exports = Processor

package/lib/result.d.ts

@@ -1,40 +1,47 @@
 import {
-  ProcessOptions,
+  Document,
+  Node,
   Plugin,
+  ProcessOptions,
+  Root,
   SourceMap,
   TransformCallback,
-  Root,
-  Node,
   Warning,
   WarningOptions
 } from './postcss.js'
 import Processor from './processor.js'
 
-export interface Message {
-  /**
-   * Message type.
-   */
-  type: string
-
-  /**
-   * Source PostCSS plugin name.
-   */
-  plugin?: string
-
-  [others: string]: any
-}
-
-export interface ResultOptions extends ProcessOptions {
-  /**
-   * The CSS node that was the source of the warning.
-   */
-  node?: Node
-
-  /**
-   * Name of plugin that created this warning. `Result#warn` will fill it
-   * automatically with `Plugin#postcssPlugin` value.
-   */
-  plugin?: string
+declare namespace Result {
+  export interface Message {
+    [others: string]: any
+
+    /**
+     * Source PostCSS plugin name.
+     */
+    plugin?: string
+
+    /**
+     * Message type.
+     */
+    type: string
+  }
+
+  export interface ResultOptions extends ProcessOptions {
+    /**
+     * The CSS node that was the source of the warning.
+     */
+    node?: Node
+
+    /**
+     * Name of plugin that created this warning. `Result#warn` will fill it
+     * automatically with `Plugin#postcssPlugin` value.
+     */
+    plugin?: string
+  }
+
+
+  // eslint-disable-next-line @typescript-eslint/no-use-before-define
+  export { Result_ as default }
 }
 
 /**
@@ -53,19 +60,36 @@ export interface ResultOptions extends ProcessOptions {
  * const result2 = postcss.parse(css).toResult()
  * ```
  */
-export default class Result {
+declare class Result_<RootNode = Document | Root> {
   /**
-   * The Processor instance used for this transformation.
+   * A CSS string representing of `Result#root`.
    *
    * ```js
-   * for (const plugin of result.processor.plugins) {
-   *   if (plugin.postcssPlugin === 'postcss-bad') {
-   *     throw 'postcss-good is incompatible with postcss-bad'
-   *   }
-   * })
+   * postcss.parse('a{}').toResult().css //=> "a{}"
    * ```
    */
-  processor: Processor
+  css: string
+
+  /**
+   * Last runned PostCSS plugin.
+   */
+  lastPlugin: Plugin | TransformCallback
+
+  /**
+   * An instance of `SourceMapGenerator` class from the `source-map` library,
+   * representing changes to the `Result#root` instance.
+   *
+   * ```js
+   * result.map.toJSON() //=> { version: 3, file: 'a.css', … }
+   * ```
+   *
+   * ```js
+   * if (result.map) {
+   *   fs.writeFileSync(result.opts.to + '.map', result.map.toString())
+   * }
+   * ```
+   */
+  map: SourceMap
 
   /**
    * Contains messages from plugins (e.g., warnings or custom messages).
@@ -85,16 +109,7 @@ export default class Result {
    * }
    * ```
    */
-  messages: Message[]
-
-  /**
-   * Root node after all transformations.
-   *
-   * ```js
-   * root.toResult().root === root
-   * ```
-   */
-  root: Root
+  messages: Result.Message[]
 
   /**
    * Options from the `Processor#process` or `Root#toResult` call
@@ -104,54 +119,36 @@ export default class Result {
    * root.toResult(opts).opts === opts
    * ```
    */
-  opts: ResultOptions
+  opts: Result.ResultOptions
 
   /**
-   * A CSS string representing of `Result#root`.
+   * The Processor instance used for this transformation.
    *
    * ```js
-   * postcss.parse('a{}').toResult().css //=> "a{}"
+   * for (const plugin of result.processor.plugins) {
+   *   if (plugin.postcssPlugin === 'postcss-bad') {
+   *     throw 'postcss-good is incompatible with postcss-bad'
+   *   }
+   * })
    * ```
    */
-  css: string
+  processor: Processor
 
   /**
-   * An instance of `SourceMapGenerator` class from the `source-map` library,
-   * representing changes to the `Result#root` instance.
-   *
-   * ```js
-   * result.map.toJSON() //=> { version: 3, file: 'a.css', … }
-   * ```
+   * Root node after all transformations.
    *
    * ```js
-   * if (result.map) {
-   *   fs.writeFileSync(result.opts.to + '.map', result.map.toString())
-   * }
+   * root.toResult().root === root
    * ```
    */
-  map: SourceMap
-
-  /**
-   * Last runned PostCSS plugin.
-   */
-  lastPlugin: Plugin | TransformCallback
+  root: RootNode
 
   /**
    * @param processor Processor used for this transformation.
    * @param root      Root node after all transformations.
    * @param opts      Options from the `Processor#process` or `Root#toResult`.
    */
-  constructor(processor: Processor, root: Root, opts: ResultOptions)
-
-  /**
-   * An alias for the `Result#css` property.
-   * Use it with syntaxes that generate non-CSS output.
-   *
-   * ```js
-   * result.css === result.content
-   * ```
-   */
-  get content(): string
+  constructor(processor: Processor, root: RootNode, opts: Result.ResultOptions)
 
   /**
    * Returns for `Result#css` content.
@@ -192,4 +189,18 @@ export default class Result {
    * @return Warnings from plugins.
    */
   warnings(): Warning[]
+
+  /**
+   * An alias for the `Result#css` property.
+   * Use it with syntaxes that generate non-CSS output.
+   *
+   * ```js
+   * result.css === result.content
+   * ```
+   */
+  get content(): string
 }
+
+declare class Result<RootNode = Document | Root> extends Result_<RootNode> {}
+
+export = Result