refactor: Added TypeScript Type Definitions

package.json

@@ -1,6 +1,6 @@
 {
   "name": "d3-force-3d",
-  "version": "3.0.5",
+  "version": "3.0.6",
   "description": "Force-directed graph layout in 1D, 2D or 3D using velocity Verlet integration.",
   "homepage": "https://github.com/vasturiano/d3-force-3d",
   "repository": {
@@ -25,14 +25,16 @@
   },
   "type": "module",
   "files": [
-    "src/**/*.js",
-    "dist/**/*.js"
+    "src/**/*",
+    "dist/**/*"
   ],
   "module": "src/index.js",
   "main": "src/index.js",
   "jsdelivr": "dist/d3-force-3d.min.js",
   "unpkg": "dist/d3-force-3d.min.js",
+  "types": "dist/d3-force-3d.d.ts",
   "exports": {
+    "types": "./dist/d3-force-3d.d.ts",
     "umd": "./dist/d3-force-3d.min.js",
     "default": "./src/index.js"
   },
@@ -47,9 +49,15 @@
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^15.0.1",
     "@rollup/plugin-terser": "^0.4.0",
+    "@types/d3-force": "^3.0.9",
     "eslint": "^8.33.0",
     "mocha": "^10.2.0",
-    "rollup": "^3.14.0"
+    "rollup": "^3.14.0",
+    "rollup-plugin-dts": "^6.1.0",
+    "typescript": "^5.4.4"
+  },
+  "peerDependencies": {
+    "@types/d3-force": "^3.0.9"
   },
   "scripts": {
     "test": "mocha 'test/**/*-test.js' && eslint src test",

rollup.config.js

@@ -1,20 +1,28 @@
 import nodeResolve from '@rollup/plugin-node-resolve';
-import terser from "@rollup/plugin-terser";
+import terser from '@rollup/plugin-terser';
+import dts from 'rollup-plugin-dts';
 import meta from './package.json' assert { type: 'json' };
 
 const config = {
-  input: "src/index.js",
-  external: Object.keys(meta.dependencies || {}).filter(key => /^d3-/.test(key)),
+  input: 'src/index.js',
+  external: Object.keys(meta.dependencies || {}).filter((key) =>
+    /^d3-/.test(key)
+  ),
   output: {
     file: `dist/${meta.name}.js`,
-    name: "d3",
-    format: "umd",
+    name: 'd3',
+    format: 'umd',
     indent: false,
     extend: true,
     banner: `// ${meta.homepage} v${meta.version}`,
-    globals: Object.assign({}, ...Object.keys(meta.dependencies || {}).filter(key => /^d3-/.test(key)).map(key => ({[key]: "d3"})))
+    globals: Object.assign(
+      {},
+      ...Object.keys(meta.dependencies || {})
+        .filter((key) => /^d3-/.test(key))
+        .map((key) => ({ [key]: 'd3' }))
+    ),
   },
-  plugins: []
+  plugins: [],
 };
 
 export default [
@@ -23,16 +31,26 @@ export default [
     ...config,
     output: {
       ...config.output,
-      file: `dist/${meta.name}.min.js`
+      file: `dist/${meta.name}.min.js`,
     },
     plugins: [
       ...config.plugins,
       nodeResolve({ jsnext: true }),
       terser({
         output: {
-          preamble: config.output.banner
-        }
-      })
-    ]
-  }
+          preamble: config.output.banner,
+        },
+      }),
+    ],
+  },
+  {
+    input: 'src/index.d.ts',
+    output: [
+      {
+        file: `dist/${meta.name}.d.ts`,
+        format: 'es',
+      },
+    ],
+    plugins: [dts()],
+  },
 ];

src/index.d.ts

@@ -0,0 +1,254 @@
+import type {
+  SimulationNodeDatum as _SimulationNodeDatum,
+  SimulationLinkDatum,
+  Simulation as _Simulation,
+  Force,
+  ForceCenter,
+  forceCenter,
+  ForceCollide,
+  forceCollide,
+  ForceLink,
+  forceLink,
+  ForceManyBody,
+  forceManyBody,
+  ForceRadial,
+  forceRadial,
+  ForceX,
+  forceX,
+  ForceY,
+  forceY,
+} from 'd3-force';
+
+export {
+  SimulationLinkDatum,
+  Force,
+  ForceCenter,
+  forceCenter,
+  ForceCollide,
+  forceCollide,
+  ForceLink,
+  forceLink,
+  ForceManyBody,
+  forceManyBody,
+  ForceRadial,
+  forceRadial,
+  ForceX,
+  forceX,
+  ForceY,
+  forceY,
+};
+
+type Dimensions = 1 | 2 | 3;
+
+export interface SimulationNodeDatum extends _SimulationNodeDatum {
+  /**
+   * Node’s current z-position
+   */
+  z?: number | undefined;
+  /**
+   * Node’s current z-velocity
+   */
+  vz?: number | undefined;
+  /**
+   * Node’s fixed z-position (if position was fixed)
+   */
+  fz?: number | null | undefined;
+}
+
+/**
+ * Create a new simulation with the specified array of nodes and no forces.
+ * If nodes is not specified, it defaults to the empty array.
+ * The simulator starts automatically; use simulation.on to listen for tick events as the simulation runs.
+ * If you wish to run the simulation manually instead, call simulation.stop, and then call simulation.tick as desired.
+ *
+ * Use this signature, when creating a simulation WITHOUT link force(s).
+ *
+ * The generic refers to the type of the data for a node.
+ *
+ * @param nodesData Optional array of nodes data, defaults to empty array.
+ */
+export function forceSimulation<NodeDatum extends SimulationNodeDatum>(
+  nodesData?: NodeDatum[],
+  numDimensions?: Dimensions
+): Simulation<NodeDatum, undefined>;
+/**
+ * Create a new simulation with the specified array of nodes and no forces.
+ * If nodes is not specified, it defaults to the empty array.
+ * The simulator starts automatically; use simulation.on to listen for tick events as the simulation runs.
+ * If you wish to run the simulation manually instead, call simulation.stop, and then call simulation.tick as desired.
+ *
+ * Use this signature, when creating a simulation WITH link force(s).
+ *
+ * The first generic refers to the type of data for a node.
+ * The second generic refers to the type of data for a link.
+ *
+ * @param nodesData Optional array of nodes data, defaults to empty array.
+ */
+export function forceSimulation<
+  NodeDatum extends SimulationNodeDatum,
+  LinkDatum extends SimulationLinkDatum<NodeDatum>
+>(
+  nodesData?: NodeDatum[],
+  numDimensions?: Dimensions
+): Simulation<NodeDatum, LinkDatum>;
+
+/**
+ * A Force Simulation
+ *
+ * The first generic refers to the type of the datum associated with a node in the simulation.
+ * The second generic refers to the type of the datum associated with a link in the simulation, if applicable.
+ */
+export interface Simulation<
+  NodeDatum extends SimulationNodeDatum,
+  LinkDatum extends SimulationLinkDatum<NodeDatum> | undefined
+> extends _Simulation<NodeDatum, LinkDatum> {
+  /**
+   * Return the current dimensions of the simulation, which defaults to 2.
+   */
+  numDimensions(): Dimensions;
+  /**
+   * Sets the simulation’s number of dimensions to use (1, 2 or 3) and return this simulation.
+   * The default is 2.
+   *
+   * A one-dimensional simulation will only consider and manipulate the x and vx coordinate attributes,
+   * while a two-dimensional will extend the domain to y and vy, and a three-dimensional to z and vz.
+   *
+   * @param nDim Current dimensions of simulation.
+   */
+  numDimensions(nDim: Dimensions): this;
+}
+
+/**
+ * The z-positioning force pushes nodes towards a desired position along the given dimension with a configurable strength.
+ * The strength of the force is proportional to the one-dimensional distance between the node’s position and the target position.
+ * While this force can be used to position individual nodes, it is intended primarily for global forces that apply to all (or most) nodes.
+ *
+ * The generic refers to the type of data for a node.
+ */
+export interface ForceZ<NodeDatum extends SimulationNodeDatum>
+  extends Force<NodeDatum, any> {
+  /**
+   * Supplies the array of nodes and random source to this force. This method is called when a force is bound to a simulation via simulation.force
+   * and when the simulation’s nodes change via simulation.nodes.
+   *
+   * A force may perform necessary work during initialization, such as evaluating per-node parameters, to avoid repeatedly performing work during each application of the force.
+   */
+  initialize(nodes: NodeDatum[], random: () => number): void;
+
+  /**
+   *  Returns the current strength accessor, which defaults to a constant strength for all nodes of 0.1.
+   */
+  strength(): (d: NodeDatum, i: number, data: NodeDatum[]) => number;
+  /**
+   * Set the strength accessor to the specified constant strength for all nodes, re-evaluates the strength accessor for each node, and returns this force.
+   *
+   * The strength determines how much to increment the node’s z-velocity: (z - node.z) × strength.
+   *
+   * For example, a value of 0.1 indicates that the node should move a tenth of the way from its current z-position to the target z-position with each application.
+   * Higher values moves nodes more quickly to the target position, often at the expense of other forces or constraints.
+   *
+   * A value outside the range [0,1] is not recommended.
+   *
+   * The constant is internally wrapped into a strength accessor function.
+   *
+   * The strength accessor is invoked for each node in the simulation, being passed the node, its zero-based index and the complete array of nodes.
+   * The resulting number is then stored internally, such that the strength of each node is only recomputed when the force is initialized or
+   * when this method is called with a new strength, and not on every application of the force.
+   *
+   * @param strength Constant value of strength to be used for all nodes.
+   */
+  strength(strength: number): this;
+  /**
+   * Set the strength accessor to the specified function, re-evaluates the strength accessor for each node, and returns this force.
+   *
+   * The strength determines how much to increment the node’s z-velocity: (z - node.z) × strength.
+   *
+   * For example, a value of 0.1 indicates that the node should move a tenth of the way from its current z-position to the target z-position with each application.
+   * Higher values moves nodes more quickly to the target position, often at the expense of other forces or constraints.
+   *
+   * A value outside the range [0,1] is not recommended.
+   *
+   * The strength accessor is invoked for each node in the simulation, being passed the node, its zero-based index and the complete array of nodes.
+   * The resulting number is then stored internally, such that the strength of each node is only recomputed when the force is initialized or
+   * when this method is called with a new strength, and not on every application of the force.
+   *
+   * @param strength A strength accessor function which is invoked for each node in the simulation, being passed the node, its zero-based index and the complete array of nodes.
+   * The function returns the strength.
+   */
+  strength(
+    strength: (d: NodeDatum, i: number, data: NodeDatum[]) => number
+  ): this;
+
+  /**
+   * Return the current z-accessor, which defaults to a function returning 0 for all nodes.
+   */
+  z(): (d: NodeDatum, i: number, data: NodeDatum[]) => number;
+  /**
+   * Set the z-coordinate accessor to the specified number, re-evaluates the z-accessor for each node,
+   * and returns this force.
+   *
+   * The constant is internally wrapped into an z-coordinate accessor function.
+   *
+   * The z-accessor is invoked for each node in the simulation, being passed the node, its zero-based index and the complete array of nodes.
+   * The resulting number is then stored internally, such that the target z-coordinate of each node is only recomputed when the force is initialized or
+   * when this method is called with a new z, and not on every application of the force.
+   *
+   * @param z Constant z-coordinate to be used for all nodes.
+   */
+  z(z: number): this;
+  /**
+   * Set the z-coordinate accessor to the specified function, re-evaluates the z-accessor for each node,
+   * and returns this force.
+   *
+   * The z-accessor is invoked for each node in the simulation, being passed the node, its zero-based index and the complete array of nodes.
+   * The resulting number is then stored internally, such that the target z-coordinate of each node is only recomputed when the force is initialized or
+   * when this method is called with a new z, and not on every application of the force.
+   *
+   * @param z A z-coordinate accessor function which is invoked for each node in the simulation, being passed the node, its zero-based index and the complete array of nodes.
+   * The function returns the z-coordinate.
+   */
+  z(z: (d: NodeDatum, i: number, data: NodeDatum[]) => number): this;
+}
+
+/**
+ * Create a new positioning force along the z-axis towards the given position z which is defaulted to a constant 0 for all nodes.
+ *
+ * The z-positioning force pushes nodes towards a desired position along the given dimension with a configurable strength.
+ * The strength of the force is proportional to the one-dimensional distance between the node’s position and the target position.
+ * While this force can be used to position individual nodes, it is intended primarily for global forces that apply to all (or most) nodes.
+ *
+ * The generic refers to the type of data for a node.
+ */
+export function forceZ<
+  NodeDatum extends SimulationNodeDatum
+>(): ForceZ<NodeDatum>;
+/**
+ * Create a new positioning force along the z-axis towards the given position z which is constant for all nodes.
+ *
+ * The z-positioning force pushes nodes towards a desired position along the given dimension with a configurable strength.
+ * The strength of the force is proportional to the one-dimensional distance between the node’s position and the target position.
+ * While this force can be used to position individual nodes, it is intended primarily for global forces that apply to all (or most) nodes.
+ *
+ * The generic refers to the type of data for a node.
+ *
+ * @param z Constant z-coordinate to be used for all nodes.
+ */
+export function forceZ<NodeDatum extends SimulationNodeDatum>(
+  z: number
+): ForceZ<NodeDatum>;
+/**
+ * Create a new positioning force along the z-axis towards the position z given by evaluating the specified z-coordinate accessor
+ * for each node.
+ *
+ * The z-positioning force pushes nodes towards a desired position along the given dimension with a configurable strength.
+ * The strength of the force is proportional to the one-dimensional distance between the node’s position and the target position.
+ * While this force can be used to position individual nodes, it is intended primarily for global forces that apply to all (or most) nodes.
+ *
+ * The generic refers to the type of data for a node.
+ *
+ * @param z A z-coordinate accessor function which is invoked for each node in the simulation, being passed the node and its zero-based index.
+ * The function returns the z-coordinate.
+ */
+export function forceZ<NodeDatum extends SimulationNodeDatum>(
+  z: (d: NodeDatum, i: number, data: NodeDatum[]) => number
+): ForceZ<NodeDatum>;