d3-dispatch: Update type definition (#25387)

* Update d3-dispatch type definition

on(type) may return undefined
add jsDoc
use ExpectError

* Typos in jsDoc

types/d3-dispatch/d3-dispatch-tests.ts

@@ -16,6 +16,9 @@ interface Datum {
 }
 
 let dispatch: d3Dispatch.Dispatch<HTMLElement>;
+let callback: (this: HTMLElement, ...args: any[]) => void;
+let callbackOrUndef: ((this: HTMLElement, ...args: any[]) => void) | undefined;
+let undef: undefined;
 
 // Signature Tests ----------------------------------------
 
@@ -33,9 +36,15 @@ function cbFn2(this: SVGElement, d: Datum, i: number) {
 }
 
 dispatch.on('foo', cbFn);
-// dispatch.on('foo', cbFn2); // test fails as 'this' context type is mismatched between dispatch and callback function
+// $ExpectError
+dispatch.on('foo', cbFn2); // test fails as 'this' context type is mismatched between dispatch and callback function
 
-dispatch.on('bar', dispatch.on('bar'));
+callback = dispatch.on('bar')!;
+callbackOrUndef = dispatch.on('bar');
+callbackOrUndef = dispatch.on('unknown');
+undef = dispatch.on('unknown') as undefined;
+
+dispatch.on('bar', dispatch.on('bar')!);
 
 dispatch.call('foo');
 dispatch.call('foo', document.body);
@@ -49,4 +58,5 @@ dispatch.on('bar', null);
 
 // Copy dispatch -----------------------------------------------
 const copy: d3Dispatch.Dispatch<HTMLElement> = dispatch.copy();
-// const copy2: d3Dispatch.Dispatch<SVGElement> = dispatch.copy(); // test fails type mismatch of underlying event target
+// $ExpectError
+const copy2: d3Dispatch.Dispatch<SVGElement> = dispatch.copy(); // test fails type mismatch of underlying event target

types/d3-dispatch/index.d.ts

@@ -1,18 +1,74 @@
 // Type definitions for D3JS d3-dispatch module 1.0
 // Project: https://github.com/d3/d3-dispatch/
-// Definitions by: Tom Wanzek <https://github.com/tomwanzek>, Alex Ford <https://github.com/gustavderdrache>, Boris Yankov <https://github.com/borisyankov>
+// Definitions by: Tom Wanzek <https://github.com/tomwanzek>
+//                 Alex Ford <https://github.com/gustavderdrache>
+//                 Boris Yankov <https://github.com/borisyankov>
+//                 denisname <https://github.com/denisname>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 
-// Last module patch version validated against: 1.0.1
+// Last module patch version validated against: 1.0.3
 
 export interface Dispatch<T extends EventTarget> {
+    /**
+     * Like `function.apply`, invokes each registered callback for the specified type,
+     * passing the callback the specified arguments, with `that` as the `this` context.
+     *
+     * @param type A specified event type.
+     * @param that The `this` context for the callback.
+     * @param args Additional arguments to be passed to the callback.
+     * @throws "unknown type" on unknown event type.
+     */
     apply(type: string, that?: T, args?: any[]): void;
-    call(type: string, that?: T, ...args: any[]): void;
+
+    /**
+     * Like `function.call`, invokes each registered callback for the specified type,
+     * passing the callback the specified arguments, with `that` as the `this` context.
+     * See dispatch.apply for more information.
+     *
+     * @param type A specified event type.
+     * @param that The `this` context for the callback.
+     * @param args Additional arguments to be passed to the callback.
+     * @throws "unknown type" on unknown event type.
+     */
+     call(type: string, that?: T, ...args: any[]): void;
+
+    /**
+     * Returns a copy of this dispatch object.
+     * Changes to this dispatch do not affect the returned copy and vice versa.
+     */
     copy(): Dispatch<T>;
 
-    on(typenames: string): (this: T, ...args: any[]) => void;
+    /**
+     * Returns the callback for the specified typenames, if any.
+     * If multiple typenames are specified, the first matching callback is returned.
+     *
+     * @param types An event typename.
+     * @param callback A callback.
+     */
+    on(typenames: string): ((this: T, ...args: any[]) => void) | undefined;
+    /**
+     * Removes the callback for the specified typenames.
+     * To remove all callbacks for a given name `foo`, say `dispatch.on(".foo", null).`
+     *
+     * @param types An event typename.
+     */
     on(typenames: string, callback: null): this;
+    /**
+     * Adds the callback for the specified typenames.
+     * The callback is registered for the specified (fully-qualified) typenames.
+     * If a callback was already registered for the given typenames,
+     * the existing callback is removed before the new callback is added.
+     *
+     * @param types An event typename.
+     * @param callback A callback.
+     */
     on(typenames: string, callback: (this: T, ...args: any[]) => void): this;
 }
 
+/**
+ * Creates a new dispatch for the specified event types. Each type is a string, such as "start" or "end".
+ *
+ * @param types The event types.
+ * @throws "illegal type" on empty string or duplicated event types.
+ */
 export function dispatch<T extends EventTarget>(...types: string[]): Dispatch<T>;

types/d3-dispatch/tsconfig.json

@@ -7,7 +7,7 @@
         ],
         "noImplicitAny": true,
         "noImplicitThis": true,
-        "strictNullChecks": false,
+        "strictNullChecks": true,
         "strictFunctionTypes": true,
         "baseUrl": "../",
         "typeRoots": [