feat: Node#assign

The `assign` function lets authors assign multiple properties to a node from a single object.

This can improve code clarity when updating multiple properties while offering a helpful typing experience.

lib/at-rule.d.ts

@@ -37,8 +37,11 @@ interface AtRuleRaws {
 }
 
 export interface AtRuleProps extends ContainerProps {
+  /** Name of the at-rule. */
   name: string
+  /** Parameters following the name of the at-rule. */
   params?: string | number
+  /** Information used to generate byte-to-byte equal node string as it was in the origin input. */
   raws?: AtRuleRaws
 }
 
@@ -95,6 +98,7 @@ export default class AtRule extends Container {
   params: string
 
   constructor(defaults?: AtRuleProps)
+  assign(overrides: object | AtRuleProps): this
   clone(overrides?: Partial<AtRuleProps>): this
   cloneBefore(overrides?: Partial<AtRuleProps>): this
   cloneAfter(overrides?: Partial<AtRuleProps>): this

lib/comment.d.ts

@@ -18,7 +18,9 @@ interface CommentRaws {
 }
 
 export interface CommentProps extends NodeProps {
+  /** Content of the comment. */
   text: string
+  /** Information used to generate byte-to-byte equal node string as it was in the origin input. */
   raws?: CommentRaws
 }
 
@@ -45,6 +47,7 @@ export default class Comment extends Node {
   text: string
 
   constructor(defaults?: CommentProps)
+  assign(overrides: object | CommentProps): this
   clone(overrides?: Partial<CommentProps>): this
   cloneBefore(overrides?: Partial<CommentProps>): this
   cloneAfter(overrides?: Partial<CommentProps>): this

lib/declaration.d.ts

@@ -27,8 +27,13 @@ interface DeclarationRaws {
 }
 
 export interface DeclarationProps {
+  /** Name of the declaration. */
   prop: string
+  /** Value of the declaration. */
   value: string
+  /** Whether the declaration has an `!important` annotation. */
+  important: boolean
+  /** Information used to generate byte-to-byte equal node string as it was in the origin input. */
   raws?: DeclarationRaws
 }
 
@@ -110,6 +115,7 @@ export default class Declaration extends Node {
   variable: boolean
 
   constructor(defaults?: DeclarationProps)
+  assign(overrides: object | DeclarationProps): this
   clone(overrides?: Partial<DeclarationProps>): this
   cloneBefore(overrides?: Partial<DeclarationProps>): this
   cloneAfter(overrides?: Partial<DeclarationProps>): this

lib/node.d.ts

@@ -251,6 +251,18 @@ export default abstract class Node {
    */
   toString(stringifier?: Stringifier | Syntax): string
 
+  /**
+   * Assigns properties to the current node.
+   *
+   * ```js
+   * decl.assign({ prop: 'word-wrap', value: 'break-word' })
+   * ```
+   *
+   * @param overrides New properties to override the node.
+   * @return Current node to methods chain.
+   */
+  assign(overrides: object): this
+
   /**
    * Returns an exact clone of the node.
    *

lib/node.js

@@ -84,6 +84,13 @@ class Node {
     return result
   }
 
+  assign(overrides = {}) {
+    for (let name in overrides) {
+      this[name] = overrides[name]
+    }
+    return this
+  }
+
   clone(overrides = {}) {
     let cloned = cloneNode(this)
     for (let name in overrides) {

lib/root.d.ts

@@ -15,6 +15,7 @@ interface RootRaws {
 }
 
 export interface RootProps extends ContainerProps {
+  /** Information used to generate byte-to-byte equal node string as it was in the origin input. */
   raws?: RootRaws
 }
 
@@ -32,8 +33,6 @@ export default class Root extends Container {
   parent: undefined
   raws: RootRaws
 
-  constructor(defaults?: RootProps)
-
   /**
    * Returns a `Result` instance representing the root’s CSS.
    *
@@ -48,4 +47,7 @@ export default class Root extends Container {
    * @return Result with current root’s CSS.
    */
   toResult(options?: ProcessOptions): Result
+
+  constructor(defaults?: RootProps)
+  assign(overrides: object | RootProps): this
 }

lib/rule.d.ts

@@ -37,8 +37,11 @@ interface RuleRaws {
 }
 
 export interface RuleProps extends ContainerProps {
+  /** Selector or selectors of the rule. */
   selector?: string
+  /** Selectors of the rule represented as an array of strings. */
   selectors?: string[]
+  /** Information used to generate byte-to-byte equal node string as it was in the origin input. */
   raws?: RuleRaws
 }
 
@@ -93,6 +96,7 @@ export default class Rule extends Container {
   selectors: string[]
 
   constructor(defaults?: RuleProps)
+  assign(overrides: object | RuleProps): this
   clone(overrides?: Partial<RuleProps>): this
   cloneBefore(overrides?: Partial<RuleProps>): this
   cloneAfter(overrides?: Partial<RuleProps>): this