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;