esupgrade 2025.17.0 → 2025.18.0

package/.pre-commit-config.yaml

@@ -32,7 +32,7 @@ repos:
       - id: write-good
         args: [--no-passive]
   - repo: https://github.com/pre-commit/mirrors-eslint
-    rev: v10.3.0
+    rev: v10.4.0
     hooks:
       - id: eslint
         args: ["--fix"]

package/README.md

@@ -550,6 +550,37 @@ The transformer handles cases where `Array.from(arguments)` has already been con
 
 Note: The `x = x || defaultValue` pattern is NOT transformed as it has different semantics (triggers on any falsy value, instead of `undefined`).
 
+#### Manual property extraction → [Destructuring parameters][mdn-destructuring]
+
+```diff
+-function fn(obj) {
+-  const x = obj.x;
+-  const y = obj.y;
+-  // use x and y
+-}
++function fn({x, y}) {
++  // use x and y
++}
+```
+
+Transforms functions where the body begins by extracting properties from a parameter into object destructuring in the parameter list. Aliased extractions use longhand syntax:
+
+```diff
+-function fn(obj) {
+-  const myX = obj.x;
+-}
++function fn({x: myX}) {
++}
+```
+
+Transforms when:
+
+- The parameter is a simple identifier (not already destructured or a rest parameter)
+- Leading statements are variable declarations extracting non-computed properties from that parameter
+- The original parameter identifier is not referenced after the extraction zone
+
+TypeScript type annotations on the original parameter are preserved on the resulting destructuring pattern.
+
 #### Promise chains → [async/await][mdn-async-await]
 
 ```diff
@@ -809,6 +840,7 @@ Furthermore, esupgrade supports JavaScript, TypeScript, and more, while lebab is
 [mdn-console]: https://developer.mozilla.org/en-US/docs/Web/API/console
 [mdn-const]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const
 [mdn-default-parameters]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters
+[mdn-destructuring]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment
 [mdn-endswith]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith
 [mdn-exponentiation]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Exponentiation
 [mdn-find]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esupgrade",
-  "version": "2025.17.0",
+  "version": "2025.18.0",
   "description": "Auto-upgrade your JavaScript syntax",
   "type": "module",
   "main": "src/index.js",

package/src/jQuery/nextToNextElementSibling.js

@@ -11,8 +11,7 @@ export function nextToNextElementSibling(root) {
   let modified = false
   root
     .find(j.CallExpression)
-    .filter((path) => {
-      const node = path.node
+    .filter(({ node }) => {
       if (!j.MemberExpression.check(node.callee)) return false
       if (!j.Identifier.check(node.callee.property)) return false
       if (node.callee.property.name !== "next") return false

package/src/jQuery/prevToPreviousElementSibling.js

@@ -11,8 +11,7 @@ export function prevToPreviousElementSibling(root) {
   let modified = false
   root
     .find(j.CallExpression)
-    .filter((path) => {
-      const node = path.node
+    .filter(({ node }) => {
       if (!j.MemberExpression.check(node.callee)) return false
       if (!j.Identifier.check(node.callee.property)) return false
       if (node.callee.property.name !== "prev") return false

package/src/jQuery/readyToDOMContentLoaded.js

@@ -12,8 +12,7 @@ export function readyToDOMContentLoaded(root) {
     .find(j.CallExpression, {
       callee: { type: "MemberExpression" },
     })
-    .filter((path) => {
-      const node = path.node
+    .filter(({ node }) => {
       const callee = node.callee
       if (!j.Identifier.check(callee.property)) return false
       if (callee.property.name !== "ready") return false

package/src/jQuery/siblingsToSiblingsArray.js

@@ -11,8 +11,7 @@ export function siblingsToSiblingsArray(root) {
   let modified = false
   root
     .find(j.CallExpression)
-    .filter((path) => {
-      const node = path.node
+    .filter(({ node }) => {
       if (!j.MemberExpression.check(node.callee)) return false
       if (!j.Identifier.check(node.callee.property)) return false
       if (node.callee.property.name !== "siblings") return false

package/src/types.js

@@ -504,9 +504,9 @@ export class NodeTest {
    */
   hasSideEffects() {
     const paramNames = new Set(
-      this.node.params.flatMap((param) =>
-        Array.from(new NodeTest(param).extractIdentifiersFromPattern()),
-      ),
+      this.node.params.flatMap((param) => [
+        ...new NodeTest(param).extractIdentifiersFromPattern(),
+      ]),
     )
     return this.#hasNodeSideEffects(this.node.body, paramNames)
   }
@@ -1066,8 +1066,7 @@ export function processMultipleDeclarators(root, path) {
  * @param {string} name - Name to check for shadowing
  * @returns {boolean} True if the identifier is shadowed
  */
-export function isShadowed(path, name) {
-  let scope = path.scope
+export function isShadowed({ scope }, name) {
   while (scope) {
     if (scope.getBindings()[name]) {
       return true

package/src/widelyAvailable/argumentsToRestParameters.js

@@ -24,8 +24,7 @@ export function argumentsToRestParameters(root) {
     ...root.find(j.FunctionExpression).paths(),
   ]
 
-  functionNodes.forEach((path) => {
-    const func = path.node
+  functionNodes.forEach(({ node: func }) => {
     if (
       (func.params.length > 0 &&
         j.RestElement.check(func.params[func.params.length - 1])) ||

package/src/widelyAvailable/arrayConcatToSpread.js

@@ -13,9 +13,7 @@ export function arrayConcatToSpread(root) {
 
   root
     .find(j.CallExpression)
-    .filter((path) => {
-      const node = path.node
-
+    .filter(({ node }) => {
       // Check if this is a .concat() call
       if (
         !j.MemberExpression.check(node.callee) ||

package/src/widelyAvailable/arrayFilterToFind.js

@@ -14,9 +14,7 @@ export function arrayFilterToFind(root) {
 
   root
     .find(j.MemberExpression)
-    .filter((path) => {
-      const node = path.node
-
+    .filter(({ node }) => {
       // Must be computed access: expr[0]
       if (!node.computed) {
         return false

package/src/widelyAvailable/arrayFromForEachToForOf.js

@@ -13,8 +13,7 @@ export function arrayFromForEachToForOf(root) {
 
   root
     .find(j.CallExpression)
-    .filter((path) => {
-      const node = path.node
+    .filter(({ node }) => {
       // Check if this is a forEach call
       if (
         !j.MemberExpression.check(node.callee) ||

package/src/widelyAvailable/arraySliceToSpread.js

@@ -13,9 +13,7 @@ export function arraySliceToSpread(root) {
 
   root
     .find(j.CallExpression)
-    .filter((path) => {
-      const node = path.node
-
+    .filter(({ node }) => {
       // Check if this is a .slice() call
       if (
         !j.MemberExpression.check(node.callee) ||

package/src/widelyAvailable/consoleLogToInfo.js

@@ -12,8 +12,7 @@ export function consoleLogToInfo(root) {
 
   root
     .find(j.CallExpression)
-    .filter((path) => {
-      const node = path.node
+    .filter(({ node }) => {
       // Check if this is a console.log() call
       if (
         !j.MemberExpression.check(node.callee) ||
@@ -27,9 +26,7 @@ export function consoleLogToInfo(root) {
 
       return true
     })
-    .forEach((path) => {
-      const node = path.node
-
+    .forEach(({ node }) => {
       // Replace the property name from 'log' to 'info'
       node.callee.property.name = "info"
 

package/src/widelyAvailable/constructorToClass.js

@@ -61,8 +61,7 @@ export function constructorToClass(root) {
     // Pattern 1: ConstructorName.prototype.methodName = ...
     root
       .find(j.ExpressionStatement)
-      .filter((path) => {
-        const node = path.node
+      .filter(({ node }) => {
         if (!j.AssignmentExpression.check(node.expression)) {
           return false
         }
@@ -105,8 +104,7 @@ export function constructorToClass(root) {
     // Pattern 2: ConstructorName.prototype = { methodName: function() {...}, ... }
     root
       .find(j.ExpressionStatement)
-      .filter((path) => {
-        const node = path.node
+      .filter(({ node }) => {
         if (!j.AssignmentExpression.check(node.expression)) {
           return false
         }

package/src/widelyAvailable/defaultParameterValues.js

@@ -27,9 +27,7 @@ export function defaultParameterValues(root) {
     ...root.find(j.ArrowFunctionExpression).paths(),
   ]
 
-  functionNodes.forEach((path) => {
-    const func = path.node
-
+  functionNodes.forEach(({ node: func }) => {
     // Skip if function body is not a block statement
     if (!j.BlockStatement.check(func.body)) {
       return

package/src/widelyAvailable/forLoopToForOf.js

@@ -14,9 +14,7 @@ export function forLoopToForOf(root) {
 
   root
     .find(j.ForStatement)
-    .filter((path) => {
-      const node = path.node
-
+    .filter(({ node }) => {
       // Check init: must be let/const i = 0
       if (!j.VariableDeclaration.check(node.init)) {
         return false

package/src/widelyAvailable/globalContextToGlobalThis.js

@@ -14,8 +14,7 @@ export function globalContextToGlobalThis(root) {
 
   root
     .find(j.CallExpression)
-    .filter((path) => {
-      const node = path.node
+    .filter(({ node }) => {
       // Check if this is a call to Function constructor
       if (
         !j.Identifier.check(node.callee) ||

package/src/widelyAvailable/indexOfToIncludes.js

@@ -16,9 +16,7 @@ export function indexOfToIncludes(root) {
 
   root
     .find(j.BinaryExpression)
-    .filter((path) => {
-      const node = path.node
-
+    .filter(({ node }) => {
       // Check for comparison operators: !==, ===, >, >=, <, <=
       if (!["!==", "===", ">", ">=", "<", "<="].includes(node.operator)) {
         return false

package/src/widelyAvailable/indexOfToStartsWith.js

@@ -14,9 +14,7 @@ export function indexOfToStartsWith(root) {
 
   root
     .find(j.BinaryExpression)
-    .filter((path) => {
-      const node = path.node
-
+    .filter(({ node }) => {
       // Check for === or !== operators
       if (!["===", "!=="].includes(node.operator)) {
         return false

package/src/widelyAvailable/iterableForEachToForOf.js

@@ -31,8 +31,7 @@ export function iterableForEachToForOf(root) {
 
   root
     .find(j.CallExpression)
-    .filter((path) => {
-      const node = path.node
+    .filter(({ node }) => {
       // Check if this is a forEach call
       if (
         !j.MemberExpression.check(node.callee) ||

package/src/widelyAvailable/lastIndexOfToEndsWith.js

@@ -15,9 +15,7 @@ export function lastIndexOfToEndsWith(root) {
 
   root
     .find(j.BinaryExpression)
-    .filter((path) => {
-      const node = path.node
-
+    .filter(({ node }) => {
       // Check for === or !== operators
       if (!["===", "!=="].includes(node.operator)) {
         return false

package/src/widelyAvailable/namedArrowFunctionToNamedFunction.js

@@ -27,9 +27,7 @@ export function namedArrowFunctionToNamedFunction(root) {
 
   root
     .find(j.VariableDeclaration)
-    .filter((path) => {
-      const node = path.node
-
+    .filter(({ node }) => {
       // Must have exactly one declarator
       if (node.declarations.length !== 1) {
         return false

package/src/widelyAvailable/nullishCoalescingOperator.js

@@ -13,9 +13,7 @@ export function nullishCoalescingOperator(root) {
 
   root
     .find(j.ConditionalExpression)
-    .filter((path) => {
-      const node = path.node
-
+    .filter(({ node }) => {
       // Test must be a logical AND expression
       if (!j.LogicalExpression.check(node.test) || node.test.operator !== "&&") {
         return false

package/src/widelyAvailable/objectKeysForEachToEntries.js

@@ -15,9 +15,7 @@ export function objectKeysForEachToEntries(root) {
 
   root
     .find(j.CallExpression)
-    .filter((path) => {
-      const node = path.node
-
+    .filter(({ node }) => {
       // Check if this is a forEach call
       if (
         !j.MemberExpression.check(node.callee) ||

package/src/widelyAvailable/objectKeysMapToValues.js

@@ -48,9 +48,7 @@ export function objectKeysMapToValues(root) {
 
   root
     .find(j.CallExpression)
-    .filter((path) => {
-      const node = path.node
-
+    .filter(({ node }) => {
       if (
         !j.MemberExpression.check(node.callee) ||
         !j.Identifier.check(node.callee.property) ||

package/src/widelyAvailable/objectPropertyExtractionToDestructuring.js

@@ -0,0 +1,342 @@
+import { default as j } from "jscodeshift"
+
+const SKIP_KEYS = new Set(["loc", "start", "end", "tokens", "comments"])
+
+/**
+ * Transform manual property extraction to destructuring in function parameters.
+ * Converts patterns where a function body begins with property extractions from a
+ * parameter into an object destructuring pattern in the parameter list.
+ *
+ * Only transforms when:
+ * - The parameter is a simple identifier (not already destructured or rest)
+ * - Leading statements are `const`/`let`/`var` declarations extracting non-computed
+ *   properties from that parameter
+ * - The original parameter identifier is not referenced after the extraction zone
+ *
+ * @param {import("jscodeshift").Collection} root - The root AST collection
+ * @returns {boolean} True if code was modified
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment
+ */
+export function objectPropertyExtractionToDestructuring(root) {
+  let modified = false
+
+  const functionNodes = [
+    ...root.find(j.FunctionDeclaration).paths(),
+    ...root.find(j.FunctionExpression).paths(),
+    ...root.find(j.ArrowFunctionExpression).paths(),
+  ]
+
+  functionNodes.forEach(({ node: func }) => {
+    if (!j.BlockStatement.check(func.body)) {
+      return
+    }
+
+    const body = func.body
+
+    func.params.forEach((param, paramIndex) => {
+      if (!j.Identifier.check(param)) {
+        return
+      }
+
+      const paramName = param.name
+      const result = findExtractions(body, paramName)
+
+      if (result.extractions.length === 0) {
+        return
+      }
+
+      if (isParamUsedAfterExtractions(body, paramName, result)) {
+        return
+      }
+
+      if (isParamReferencedInOtherParams(func.params, paramIndex, paramName)) {
+        return
+      }
+
+      if (wouldPromoteDirective(body, result)) {
+        return
+      }
+
+      func.params[paramIndex] = buildObjectPattern(result.extractions, param)
+      removeExtractionDeclarators(body, result.extractions)
+      modified = true
+    })
+  })
+
+  return modified
+}
+
+/**
+ * Find leading property extractions from a named parameter in a function body.
+ *
+ * @param {import("ast-types").namedTypes.BlockStatement} body - The function body
+ * @param {string} paramName - The parameter identifier name to extract from
+ * @returns {{ extractions: Array<{localName: string, propertyName: string, statementIndex: number, declaratorIndex: number}>, boundary: number }}
+ */
+function findExtractions(body, paramName) {
+  const extractions = []
+  let boundary = 0
+
+  for (let i = 0; i < body.body.length; i++) {
+    const statement = body.body[i]
+
+    if (!j.VariableDeclaration.check(statement)) {
+      break
+    }
+
+    let hasExtractionInStatement = false
+
+    statement.declarations.forEach((declarator, declaratorIndex) => {
+      if (isPropertyExtractionFrom(declarator, paramName)) {
+        extractions.push({
+          localName: declarator.id.name,
+          propertyName: declarator.init.property.name,
+          statementIndex: i,
+          declaratorIndex,
+        })
+        hasExtractionInStatement = true
+      }
+    })
+
+    if (!hasExtractionInStatement) {
+      break
+    }
+
+    boundary = i + 1
+  }
+
+  return { extractions, boundary }
+}
+
+/**
+ * Check if a variable declarator is a non-computed property access from a named identifier.
+ *
+ * @param {import("ast-types").namedTypes.VariableDeclarator} declarator - The declarator to check
+ * @param {string} paramName - The identifier name to check against
+ * @returns {boolean} True if the declarator extracts a property from paramName
+ */
+function isPropertyExtractionFrom(declarator, paramName) {
+  return (
+    j.Identifier.check(declarator.id) &&
+    j.MemberExpression.check(declarator.init) &&
+    !declarator.init.computed &&
+    j.Identifier.check(declarator.init.object) &&
+    declarator.init.object.name === paramName &&
+    j.Identifier.check(declarator.init.property)
+  )
+}
+
+/**
+ * Check if the original parameter identifier is still referenced after the extraction zone.
+ * Uses deep traversal that crosses nested function boundaries, since the parameter
+ * name is in the outer scope and closures may reference it.
+ *
+ * @param {import("ast-types").namedTypes.BlockStatement} body - The function body
+ * @param {string} paramName - The parameter identifier name
+ * @param {{ extractions: Array, boundary: number }} result - Result from findExtractions
+ * @returns {boolean} True if the parameter is used after the extractions
+ */
+function isParamUsedAfterExtractions(body, paramName, result) {
+  const remainingStatements = body.body.slice(result.boundary)
+
+  if (remainingStatements.some((stmt) => deepContainsIdentifier(stmt, paramName))) {
+    return true
+  }
+
+  return isMixedDeclaratorUsingParam(body, paramName, result.extractions)
+}
+
+/**
+ * Check if any non-extraction declarator in the extraction zone references the parameter.
+ *
+ * @param {import("ast-types").namedTypes.BlockStatement} body - The function body
+ * @param {string} paramName - The parameter identifier name
+ * @param {Array<{statementIndex: number, declaratorIndex: number}>} extractions - The found extractions
+ * @returns {boolean} True if the parameter is used in a non-extraction declarator
+ */
+function isMixedDeclaratorUsingParam(body, paramName, extractions) {
+  const extractionSet = new Set(
+    extractions.map(
+      ({ statementIndex, declaratorIndex }) => `${statementIndex}:${declaratorIndex}`,
+    ),
+  )
+
+  return body.body.some((statement, statementIndex) => {
+    if (!j.VariableDeclaration.check(statement)) {
+      return false
+    }
+
+    return statement.declarations.some((declarator, declaratorIndex) => {
+      if (extractionSet.has(`${statementIndex}:${declaratorIndex}`)) {
+        return false
+      }
+
+      if (!declarator.init) {
+        return false
+      }
+
+      return deepContainsIdentifier(declarator.init, paramName)
+    })
+  })
+}
+
+/**
+ * Check if removing extraction statements would promote a "use strict" string literal
+ * to a function directive. Non-simple parameter lists (destructuring) cannot have a
+ * "use strict" directive.
+ *
+ * @param {import("ast-types").namedTypes.BlockStatement} body - The function body
+ * @param {{ extractions: Array<{statementIndex: number, declaratorIndex: number}>, boundary: number }} result - Result from findExtractions
+ * @returns {boolean} True if the transformation would produce an illegal directive
+ */
+function wouldPromoteDirective(body, result) {
+  const extractionSet = new Set(
+    result.extractions.map(
+      ({ statementIndex, declaratorIndex }) => `${statementIndex}:${declaratorIndex}`,
+    ),
+  )
+
+  for (let i = 0; i < result.boundary; i++) {
+    const statement = body.body[i]
+    const hasRemainingDeclarators = statement.declarations.some(
+      (_, di) => !extractionSet.has(`${i}:${di}`),
+    )
+
+    if (hasRemainingDeclarators) {
+      return false
+    }
+  }
+
+  const nextStatement = body.body[result.boundary]
+
+  return (
+    nextStatement !== undefined &&
+    j.ExpressionStatement.check(nextStatement) &&
+    isStringLiteralNode(nextStatement.expression) &&
+    nextStatement.expression.value === "use strict"
+  )
+}
+
+/**
+ * Check if the parameter identifier is referenced in any other parameter in the list.
+ * Covers default values such as `function fn(obj, y = obj.x)`.
+ *
+ * @param {Array<import("ast-types").ASTNode>} params - The full parameter list
+ * @param {number} paramIndex - Index of the parameter being transformed
+ * @param {string} paramName - The parameter identifier name
+ * @returns {boolean} True if the identifier appears in another parameter
+ */
+function isParamReferencedInOtherParams(params, paramIndex, paramName) {
+  return params.some(
+    (param, i) => i !== paramIndex && deepContainsIdentifier(param, paramName),
+  )
+}
+
+/**
+ * Deeply check if an identifier name appears anywhere in an AST subtree,
+ * including inside nested functions and arrow functions.
+ *
+ * @param {import("ast-types").ASTNode | null | undefined} node - The node to search
+ * @param {string} name - The identifier name to search for
+ * @returns {boolean} True if the identifier is found anywhere in the subtree
+ */
+function deepContainsIdentifier(node, name) {
+  if (!node || typeof node !== "object") {
+    return false
+  }
+
+  if (node.type === "Identifier" && node.name === name) {
+    return true
+  }
+
+  for (const key in node) {
+    if (SKIP_KEYS.has(key)) {
+      continue
+    }
+
+    const value = node[key]
+
+    if (Array.isArray(value)) {
+      if (value.some((item) => deepContainsIdentifier(item, name))) {
+        return true
+      }
+    } else if (value && typeof value === "object") {
+      if (deepContainsIdentifier(value, name)) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+/**
+ * Check if a node is a string literal.
+ *
+ * @param {import("ast-types").ASTNode} node - The node to check
+ * @returns {boolean} True if the node is a string literal
+ */
+function isStringLiteralNode(node) {
+  return j.StringLiteral.check(node)
+}
+
+/**
+ * Build an ObjectPattern AST node from a list of property extractions.
+ * Preserves TypeScript type annotations from the original parameter.
+ *
+ * @param {Array<{localName: string, propertyName: string}>} extractions - The extractions to build from
+ * @param {import("ast-types").namedTypes.Identifier} originalParam - The original parameter node
+ * @returns {import("ast-types").namedTypes.ObjectPattern} The destructuring pattern
+ */
+function buildObjectPattern(extractions, originalParam) {
+  const properties = extractions.map(({ localName, propertyName }) => {
+    const key = j.identifier(propertyName)
+    const value = j.identifier(localName)
+    const isShorthand = localName === propertyName
+    const prop = j.objectProperty(key, value)
+    prop.shorthand = isShorthand
+    return prop
+  })
+
+  const pattern = j.objectPattern(properties)
+
+  if (originalParam.typeAnnotation) {
+    pattern.typeAnnotation = originalParam.typeAnnotation
+  }
+
+  return pattern
+}
+
+/**
+ * Remove extraction declarators from the function body, removing empty statements.
+ *
+ * @param {import("ast-types").namedTypes.BlockStatement} body - The function body to modify
+ * @param {Array<{statementIndex: number, declaratorIndex: number}>} extractions - The extractions to remove
+ */
+function removeExtractionDeclarators(body, extractions) {
+  const statementMap = new Map()
+
+  extractions.forEach(({ statementIndex, declaratorIndex }) => {
+    if (!statementMap.has(statementIndex)) {
+      statementMap.set(statementIndex, [])
+    }
+    statementMap.get(statementIndex).push(declaratorIndex)
+  })
+
+  for (const [statementIndex, declaratorIndices] of [...statementMap.entries()].sort(
+    (a, b) => b[0] - a[0],
+  )) {
+    const statement = body.body[statementIndex]
+
+    declaratorIndices
+      .slice()
+      .sort((a, b) => b - a)
+      .forEach((di) => {
+        statement.declarations.splice(di, 1)
+      })
+
+    if (statement.declarations.length === 0) {
+      body.body.splice(statementIndex, 1)
+    }
+  }
+}

package/src/widelyAvailable/removeUseStrictFromModules.js

@@ -26,9 +26,7 @@ export function removeUseStrictFromModules(root) {
   }
 
   // Find and remove 'use strict' directives
-  root.find(j.Program).forEach((programPath) => {
-    const program = programPath.node
-
+  root.find(j.Program).forEach(({ node: program }) => {
     // Check directives array (Babel/TSX parser stores directives here)
     if (program.directives && Array.isArray(program.directives)) {
       let i = 0

package/src/widelyAvailable/substrToSlice.js

@@ -17,9 +17,7 @@ export function substrToSlice(root) {
 
   root
     .find(j.CallExpression)
-    .filter((path) => {
-      const node = path.node
-
+    .filter(({ node }) => {
       // Check if this is a .substr() call
       if (
         !j.MemberExpression.check(node.callee) ||

package/src/widelyAvailable/substringToStartsWith.js

@@ -15,9 +15,7 @@ export function substringToStartsWith(root) {
 
   root
     .find(j.BinaryExpression)
-    .filter((path) => {
-      const node = path.node
-
+    .filter(({ node }) => {
       // Check for === or !== operators
       if (!["===", "!=="].includes(node.operator)) {
         return false

package/src/widelyAvailable.js

@@ -21,6 +21,7 @@ export { nullishCoalescingOperator } from "./widelyAvailable/nullishCoalescingOp
 export { objectAssignToSpread } from "./widelyAvailable/objectAssignToSpread.js"
 export { objectKeysForEachToEntries } from "./widelyAvailable/objectKeysForEachToEntries.js"
 export { objectKeysMapToValues } from "./widelyAvailable/objectKeysMapToValues.js"
+export { objectPropertyExtractionToDestructuring } from "./widelyAvailable/objectPropertyExtractionToDestructuring.js"
 export { optionalChaining } from "./widelyAvailable/optionalChaining.js"
 export { promiseToAsyncAwait } from "./widelyAvailable/promiseToAsyncAwait.js"
 export { removeUseStrictFromModules } from "./widelyAvailable/removeUseStrictFromModules.js"

package/tests/widelyAvailable/object-property-extraction-to-destructuring.test.js

@@ -0,0 +1,314 @@
+import assert from "node:assert/strict"
+import { describe, suite, test } from "node:test"
+import { transform } from "../../src/index.js"
+
+suite("widely-available", () => {
+  describe("objectPropertyExtractionToDestructuring", () => {
+    test("single property extraction in function declaration", () => {
+      const result = transform(`
+function fn(obj) {
+  const x = obj.x;
+  return x;
+}
+      `)
+
+      assert(result.modified, "transform single property extraction")
+      assert.match(result.code, /function fn\(\s*\{\s*x\s*\}/)
+      assert.doesNotMatch(result.code, /const x = obj\.x/)
+    })
+
+    test("multiple property extractions", () => {
+      const result = transform(`
+function fn(obj) {
+  const x = obj.x;
+  const y = obj.y;
+  return x + y;
+}
+      `)
+
+      assert(result.modified, "transform multiple property extractions")
+      assert.match(result.code, /function fn\(\s*\{\s*x,\s*y\s*\}/)
+      assert.doesNotMatch(result.code, /const x = obj\.x/)
+      assert.doesNotMatch(result.code, /const y = obj\.y/)
+    })
+
+    test("aliased extraction uses longhand destructuring", () => {
+      const result = transform(`
+function fn(obj) {
+  const myX = obj.x;
+  return myX;
+}
+      `)
+
+      assert(result.modified, "transform aliased property extraction")
+      assert.match(result.code, /function fn\(\s*\{\s*x:\s*myX\s*\}/)
+      assert.doesNotMatch(result.code, /const myX = obj\.x/)
+    })
+
+    test("skip when parameter is used after extractions", () => {
+      const result = transform(`
+function fn(obj) {
+  const x = obj.x;
+  console.log(obj);
+}
+      `)
+
+      assert.match(result.code, /const x = obj\.x/)
+      assert.match(result.code, /function fn\(obj\)/)
+    })
+
+    test("skip when parameter property is accessed after extractions", () => {
+      const result = transform(`
+function fn(obj) {
+  const x = obj.x;
+  return x + obj.z;
+}
+      `)
+
+      assert.match(result.code, /const x = obj\.x/)
+      assert.match(result.code, /function fn\(obj\)/)
+    })
+
+    test("skip computed property access", () => {
+      const result = transform(`
+function fn(obj) {
+  const x = obj[key];
+  return x;
+}
+      `)
+
+      assert(!result.modified, "skip computed property access")
+    })
+
+    test("skip already-destructured parameter", () => {
+      const result = transform(`
+function fn({x}) {
+  return x;
+}
+      `)
+
+      assert(!result.modified, "skip already-destructured parameter")
+    })
+
+    test("skip rest parameter", () => {
+      const result = transform(`
+function fn(...args) {
+  return args;
+}
+      `)
+
+      assert(!result.modified, "skip rest parameter")
+    })
+
+    test("skip non-leading extraction", () => {
+      const result = transform(`
+function fn(obj) {
+  const z = 42;
+  const x = obj.x;
+  return x + z;
+}
+      `)
+
+      assert.match(result.code, /const x = obj\.x/)
+      assert.match(result.code, /function fn\(obj\)/)
+    })
+
+    test("stop at non-extraction in leading statements", () => {
+      const result = transform(`
+function fn(obj) {
+  const x = obj.x;
+  const z = 42;
+  const y = obj.y;
+  return x + y + z;
+}
+      `)
+
+      assert.match(result.code, /const x = obj\.x/)
+    })
+
+    test("function expression", () => {
+      const result = transform(`
+const fn = function(obj) {
+  const x = obj.x;
+  return x;
+};
+      `)
+
+      assert(result.modified, "transform function expression")
+      assert.match(result.code, /\{\s*x\s*\}/)
+      assert.doesNotMatch(result.code, /const x = obj\.x/)
+    })
+
+    test("arrow function", () => {
+      const result = transform(`
+const fn = (obj) => {
+  const x = obj.x;
+  return x;
+};
+      `)
+
+      assert(result.modified, "transform arrow function")
+      assert.match(result.code, /\{\s*x\s*\}/)
+      assert.doesNotMatch(result.code, /const x = obj\.x/)
+    })
+
+    test("multiple parameters transformed independently", () => {
+      const result = transform(`
+function fn(a, b) {
+  const x = a.x;
+  const y = b.y;
+  return x + y;
+}
+      `)
+
+      assert(result.modified, "transform multiple parameters")
+      assert.doesNotMatch(result.code, /const x = a\.x/)
+      assert.doesNotMatch(result.code, /const y = b\.y/)
+    })
+
+    test("mixed declarator statement preserves non-extraction", () => {
+      const result = transform(`
+function fn(obj) {
+  const x = obj.x, z = 42;
+  return x + z;
+}
+      `)
+
+      assert(result.modified, "transform mixed declarator")
+      assert.match(result.code, /const z = 42/)
+      assert.doesNotMatch(result.code, /obj/)
+    })
+
+    test("TypeScript type annotation is preserved", () => {
+      const result = transform(`
+function fn(obj: MyType) {
+  const x = obj.x;
+  return x;
+}
+      `)
+
+      assert(result.modified, "transform TypeScript typed parameter")
+      assert.match(result.code, /\{\s*x\s*\}:\s*MyType/)
+      assert.doesNotMatch(result.code, /const x = obj\.x/)
+    })
+
+    test("TypeScript inline type annotation is preserved", () => {
+      const result = transform(`
+function fn(obj: { x: number }) {
+  const x = obj.x;
+  return x;
+}
+      `)
+
+      assert(result.modified, "transform TypeScript inline typed parameter")
+      assert.match(result.code, /x: number/)
+      assert.doesNotMatch(result.code, /const x = obj\.x/)
+    })
+
+    test("skip mixed declarator where non-extraction uses the param", () => {
+      const result = transform(`
+function fn(obj) {
+  const x = obj.x, ref = obj;
+  return x;
+}
+      `)
+
+      assert.match(result.code, /function fn\(obj\)/)
+      assert.match(result.code, /const x = obj\.x/)
+    })
+
+    test("uninitialised variable declaration does not crash", () => {
+      const result = transform(`
+function fn(obj) {
+  const x = obj.x;
+  let y;
+  return x;
+}
+      `)
+
+      assert(result.modified, "transform with uninitialised variable in body")
+      assert.match(result.code, /function fn\(\s*\{\s*x\s*\}/)
+      assert.doesNotMatch(result.code, /const x = obj\.x/)
+    })
+
+    test("skip when nested function closes over the parameter", () => {
+      const result = transform(`
+function fn(obj) {
+  const x = obj.x;
+  return () => obj;
+}
+      `)
+
+      assert(
+        !result.modified,
+        "should not transform when nested function closes over parameter",
+      )
+      assert.match(result.code, /function fn\(obj\)/)
+      assert.match(result.code, /const x = obj\.x/)
+    })
+
+    test("skip when extraction removal would promote use strict to a directive", () => {
+      const result = transform(`
+function fn(obj) {
+  const x = obj.x;
+  "use strict";
+  return x;
+}
+      `)
+
+      assert(
+        !result.modified,
+        "should not transform when removal would promote use strict directive",
+      )
+      assert.match(result.code, /function fn\(obj\)/)
+      assert.match(result.code, /const x = obj\.x/)
+    })
+
+    test("transform when non-use-strict string literal follows extractions", () => {
+      const result = transform(`
+function fn(obj) {
+  const x = obj.x;
+  "@jsx";
+  return x;
+}
+      `)
+
+      assert(result.modified, "should transform when string literal is not use strict")
+      assert.match(result.code, /function fn\(\s*\{\s*x\s*\}/)
+      assert.doesNotMatch(result.code, /const x = obj\.x/)
+    })
+
+    test("skip when parameter is referenced in another parameter's default value", () => {
+      const result = transform(`
+function fn(obj, y = obj.x) {
+  const x = obj.x;
+  return x + y;
+}
+      `)
+
+      assert(
+        !result.modified,
+        "should not transform when param used in other param default",
+      )
+      assert.match(result.code, /function fn\(obj,/)
+      assert.match(result.code, /const x = obj\.x/)
+    })
+
+    test("skip when body contains sparse array pattern referencing parameter", () => {
+      const result = transform(`
+function fn(obj) {
+  const x = obj.x;
+  const [, b] = obj.arr;
+  return x + b;
+}
+      `)
+
+      assert(
+        !result.modified,
+        "should not transform when obj is used after extractions",
+      )
+      assert.match(result.code, /function fn\(obj\)/)
+      assert.match(result.code, /const x = obj\.x/)
+    })
+  })
+})