Improve typescript typings

* Add an additional parameter to Container to clarify that Root can
  only contain Selectors as immediate children and Selector cannot
  contain Selectors as immediate children.

* Use polymorphic `this` types for Container methods that return the
  same object.

* Narrow the type for Container.walk*() to indicate that only nodes of
  the given type will be passed to the callback.

* Fix the type of Container.reduce() to match the type of
  Iterable.reduce().

Author: nex3

postcss-selector-parser.d.ts

@@ -14,6 +14,9 @@
  */
 export = parser;
 
+// A type that's T but not U.
+type Diff<T, U> = T extends U ? never : T;
+
 // TODO: Conditional types in TS 1.8 will really clean this up.
 declare function parser(): parser.Processor<never>;
 declare function parser<Transform>(processor: parser.AsyncProcessor<Transform>): parser.Processor<Transform, never>;
@@ -203,11 +206,14 @@ declare namespace parser {
     interface ContainerOptions extends NodeOptions {
         nodes?: Array<Node>;
     }
-    interface Container<Value extends string | undefined = string> extends Base<Value> {
-        nodes: Array<Node>;
-        append(selector: Selector): Container;
-        prepend(selector: Selector): Container;
-        at(index: number): Node;
+    interface Container<
+        Value extends string | undefined = string,
+        Child extends Node = Node
+    > extends Base<Value> {
+        nodes: Array<Child>;
+        append(selector: Selector): this;
+        prepend(selector: Selector): this;
+        at(index: number): Child;
         /**
          * Return the most specific node at the line and column number given.
          * The source location is based on the original parsed location, locations aren't
@@ -221,33 +227,74 @@ declare namespace parser {
          * @param line The line number of the node to find. (1-based index)
          * @param col  The column number of the node to find. (1-based index)
          */
-        atPosition(line: number, column: number): Node;
-        index(child: Node): number;
-        readonly first: Node;
-        readonly last: Node;
+        atPosition(line: number, column: number): Child;
+        index(child: Child): number;
+        readonly first: Child;
+        readonly last: Child;
         readonly length: number;
-        removeChild(child: Node): Container;
+        removeChild(child: Child): this;
         removeAll(): Container;
         empty(): Container;
-        insertAfter(oldNode: Node, newNode: Node): Container;
-        insertBefore(oldNode: Node, newNode: Node): Container;
-        each(callback: (node: Node) => boolean | void): boolean | undefined;
-        walk(callback: (node: Node) => boolean | void): boolean | undefined;
-        walkAttributes(callback: (node: Node) => boolean | void): boolean | undefined;
-        walkClasses(callback: (node: Node) => boolean | void): boolean | undefined;
-        walkCombinators(callback: (node: Node) => boolean | void): boolean | undefined;
-        walkComments(callback: (node: Node) => boolean | void): boolean | undefined;
-        walkIds(callback: (node: Node) => boolean | void): boolean | undefined;
-        walkNesting(callback: (node: Node) => boolean | void): boolean | undefined;
-        walkPseudos(callback: (node: Node) => boolean | void): boolean | undefined;
-        walkTags(callback: (node: Node) => boolean | void): boolean | undefined;
-        split(callback: (node: Node) => boolean): [Node[], Node[]];
-        map(callback: (node: Node) => Node): Node[];
-        reduce<T>(callback: (node: Node) => Node, memo: T): T;
-        every(callback: (node: Node) => boolean): boolean;
-        some(callback: (node: Node) => boolean): boolean;
-        filter(callback: (node: Node) => boolean): Node[];
-        sort(callback: (nodeA: Node, nodeB: Node) => number): Node[];
+        insertAfter(oldNode: Child, newNode: Child): this;
+        insertBefore(oldNode: Child, newNode: Child): this;
+        each(callback: (node: Child) => boolean | void): boolean | undefined;
+        walk(
+            callback: (node: Node) => boolean | void
+        ): boolean | undefined;
+        walkAttributes(
+            callback: (node: Attribute) => boolean | void
+        ): boolean | undefined;
+        walkClasses(
+            callback: (node: ClassName) => boolean | void
+        ): boolean | undefined;
+        walkCombinators(
+            callback: (node: Combinator) => boolean | void
+        ): boolean | undefined;
+        walkComments(
+            callback: (node: Comment) => boolean | void
+        ): boolean | undefined;
+        walkIds(
+            callback: (node: Identifier) => boolean | void
+        ): boolean | undefined;
+        walkNesting(
+            callback: (node: Nesting) => boolean | void
+        ): boolean | undefined;
+        walkPseudos(
+            callback: (node: Pseudo) => boolean | void
+        ): boolean | undefined;
+        walkTags(callback: (node: Tag) => boolean | void): boolean | undefined;
+        split(callback: (node: Child) => boolean): [Child[], Child[]];
+        map<T>(callback: (node: Child) => T): T[];
+        reduce(
+            callback: (
+                previousValue: Child,
+                currentValue: Child,
+                currentIndex: number,
+                array: readonly Child[]
+            ) => Child
+        ): Child;
+        reduce(
+            callback: (
+                previousValue: Child,
+                currentValue: Child,
+                currentIndex: number,
+                array: readonly Child[]
+            ) => Child,
+            initialValue: Child
+        ): Child;
+        reduce<T>(
+            callback: (
+                previousValue: T,
+                currentValue: Child,
+                currentIndex: number,
+                array: readonly Child[]
+            ) => T,
+            initialValue: T
+        ): T;
+        every(callback: (node: Child) => boolean): boolean;
+        some(callback: (node: Child) => boolean): boolean;
+        filter(callback: (node: Child) => boolean): Child[];
+        sort(callback: (nodeA: Child, nodeB: Child) => number): Child[];
         toString(): string;
     }
     function isContainer(node: any): node is Root | Selector | Pseudo;
@@ -273,7 +320,7 @@ declare namespace parser {
     }
     function isNamespace(node: any): node is Attribute | Tag;
 
-    interface Root extends Container<undefined> {
+    interface Root extends Container<undefined, Selector> {
         type: "root";
         /**
          * Raises an error, if the processor is invoked on
@@ -285,7 +332,7 @@ declare namespace parser {
     function root(opts: ContainerOptions): Root;
     function isRoot(node: any): node is Root;
 
-    interface Selector extends Container {
+    interface Selector extends Container<string, Diff<Node, Selector>> {
         type: "selector";
     }
     function selector(opts: ContainerOptions): Selector;
@@ -439,7 +486,7 @@ declare namespace parser {
     function attribute(opts: AttributeOptions): Attribute;
     function isAttribute(node: any): node is Attribute;
 
-    interface Pseudo extends Container {
+    interface Pseudo extends Container<string, Selector> {
         type: "pseudo";
     }
     function pseudo(opts: ContainerOptions): Pseudo;