Improve types

index.d.ts

@@ -1,29 +1,41 @@
 /**
  * Converts invisible characters to a commonly recognizable visible form.
- * @param str - The string with invisibles to convert.
- * @returns The converted string.
+ * @param {string} str - The string with invisibles to convert.
+ * @returns {string} The converted string.
  */
 export function showInvisibles(str: string): string;
 
-export interface Difference {
-  operation: 'insert' | 'delete' | 'replace';
-  offset: number;
-  insertText?: string | undefined;
-  deleteText?: string | undefined;
-}
+export type Difference =
+  | {
+      operation: 'insert';
+      insertText: string;
+      offset: number;
+    }
+  | {
+      operation: 'delete';
+      deleteText: string;
+      offset: number;
+    }
+  | {
+      operation: 'replace';
+      insertText: string;
+      deleteText: string;
+      offset: number;
+    };
 
-export interface GenerateDifferences {
-  /**
-   * Generate results for differences between source code and formatted version.
-   *
-   * @param source - The original source.
-   * @param prettierSource - The Prettier formatted source.
-   * @returns An array containing { operation, offset, insertText, deleteText }
-   */
-  (source: string, prettierSource: string): Difference[];
-  INSERT: 'insert';
-  DELETE: 'delete';
-  REPLACE: 'replace';
+/**
+ * Generate results for differences between source code and formatted version.
+ *
+ * @param {string} source - The original source.
+ * @param {string} prettierSource - The Prettier formatted source.
+ * @returns {Difference[]} - An array containing { operation, offset, insertText, deleteText }
+ */
+export function generateDifferences(
+  source: string,
+  prettierSource: string
+): Difference[];
+export namespace generateDifferences {
+  let INSERT: 'insert';
+  let DELETE: 'delete';
+  let REPLACE: 'replace';
 }
-
-export const generateDifferences: GenerateDifferences;

index.js

@@ -31,12 +31,14 @@ function showInvisibles(str) {
   return ret;
 }
 
+/** @typedef {({operation: 'insert'; insertText: string; offset: number;} | {operation: 'delete'; deleteText: string; offset: number;} | {operation: 'replace'; insertText: string; deleteText: string; offset: number;})} Difference */
+
 /**
  * Generate results for differences between source code and formatted version.
  *
  * @param {string} source - The original source.
  * @param {string} prettierSource - The Prettier formatted source.
- * @returns {Array} - An array containing { operation, offset, insertText, deleteText }
+ * @returns {Difference[]} - An array containing { operation, offset, insertText, deleteText }
  */
 function generateDifferences(source, prettierSource) {
   // fast-diff returns the differences between two texts as a series of
@@ -54,12 +56,15 @@ function generateDifferences(source, prettierSource) {
   // on contiguous lines).
 
   const results = diff(source, prettierSource);
+
+  /** @type {Difference[]} */
   const differences = [];
 
+  /** @type {typeof results} */
   const batch = [];
   let offset = 0; // NOTE: INSERT never advances the offset.
   while (results.length) {
-    const result = results.shift();
+    const result = /** @type {typeof results[number]} */ (results.shift());
     const op = result[0];
     const text = result[1];
     switch (op) {
@@ -95,7 +100,7 @@ function generateDifferences(source, prettierSource) {
     let aheadDeleteText = '';
     let aheadInsertText = '';
     while (batch.length) {
-      const next = batch.shift();
+      const next = /** @type {typeof batch[number]} */ (batch.shift());
       const op = next[0];
       const text = next[1];
       switch (op) {
@@ -135,9 +140,9 @@ function generateDifferences(source, prettierSource) {
   }
 }
 
-generateDifferences.INSERT = 'insert';
-generateDifferences.DELETE = 'delete';
-generateDifferences.REPLACE = 'replace';
+generateDifferences.INSERT = /** @type {const} */ ('insert');
+generateDifferences.DELETE = /** @type {const} */ ('delete');
+generateDifferences.REPLACE = /** @type {const} */ ('replace');
 
 module.exports = {
   showInvisibles,