estree-util-attach-comments - npm Package Compare versions

Comparing version 2.1.1 to 3.0.0

index.d.ts

@@ -1,1 +0,1 @@
-export {attachComments} from './lib/index.js'
+export { attachComments } from "./lib/index.js";

lib/index.d.ts

@@ -22,33 +22,39 @@ /**
  *
- * @template {EstreeNode} Tree
+ * @template {Nodes} Tree
  *   Node type.
  * @param {Tree} tree
  *   Tree to attach to.
- * @param {Array<EstreeComment> | null | undefined} [comments]
- *   List of comments.
- * @returns {Tree}
- *   Given tree.
+ * @param {Array<Comment> | null | undefined} [comments]
+ *   List of comments (optional).
+ * @returns {undefined}
+ *   Nothing.
  */
-export function attachComments<Tree extends import('estree').BaseNode>(
-  tree: Tree,
-  comments?: Array<EstreeComment> | null | undefined
-): Tree
-export type EstreeNode = import('estree').BaseNode
-export type EstreeComment = import('estree').Comment
+export function attachComments<Tree extends import("estree").Node>(tree: Tree, comments?: Array<Comment> | null | undefined): undefined;
+export type Comment = import('estree').Comment;
+export type Nodes = import('estree').Node;
 /**
+ * Fields.
+ */
+export type Fields = {
+    /**
+     *   Whether it’s leading.
+     */
+    leading: boolean;
+    /**
+     *   Whether it’s trailing.
+     */
+    trailing: boolean;
+};
+/**
  * Info passed around.
  */
 export type State = {
-  /**
-   * Comments.
-   */
-  comments: Array<EstreeComment>
-  /**
-   * Index of comment.
-   */
-  index: number
-}
-export type Fields = {
-  leading: boolean
-  trailing: boolean
-}
+    /**
+     *   Comments.
+     */
+    comments: Array<Comment>;
+    /**
+     *   Index of comment.
+     */
+    index: number;
+};

lib/index.js

 /**
- * @typedef {import('estree').BaseNode} EstreeNode
- * @typedef {import('estree').Comment} EstreeComment
+ * @typedef {import('estree').Comment} Comment
+ * @typedef {import('estree').Node} Nodes
+ */
+
+/**
+ * @typedef Fields
+ *   Fields.
+ * @property {boolean} leading
+ *   Whether it’s leading.
+ * @property {boolean} trailing
+ *   Whether it’s trailing.
  *
  * @typedef State
  *   Info passed around.
- * @property {Array<EstreeComment>} comments
+ * @property {Array<Comment>} comments
  *   Comments.
  * @property {number} index
  *   Index of comment.
- *
- * @typedef Fields
- * @property {boolean} leading
- * @property {boolean} trailing
  */
@@ -19,2 +24,5 @@
 
+/** @type {Array<Comment>} */
+const emptyComments = []
+
 /**
@@ -41,16 +49,14 @@ * Attach semistandard estree comment nodes to the tree.
  *
- * @template {EstreeNode} Tree
+ * @template {Nodes} Tree
  *   Node type.
  * @param {Tree} tree
  *   Tree to attach to.
- * @param {Array<EstreeComment> | null | undefined} [comments]
- *   List of comments.
- * @returns {Tree}
- *   Given tree.
+ * @param {Array<Comment> | null | undefined} [comments]
+ *   List of comments (optional).
+ * @returns {undefined}
+ *   Nothing.
  */
-// To do: next major: don’t return given `tree`.
 export function attachComments(tree, comments) {
-  const list = (comments || []).concat().sort(compare)
+  const list = comments ? [...comments].sort(compare) : emptyComments
   if (list.length > 0) walk(tree, {comments: list, index: 0})
-  return tree
 }
@@ -61,7 +67,7 @@
  *
- * @param {EstreeNode} node
+ * @param {Nodes} node
  *   Node.
  * @param {State} state
  *   Info passed around.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
@@ -75,5 +81,5 @@ */
 
-  /** @type {Array<EstreeNode>} */
+  /** @type {Array<Nodes>} */
   const children = []
-  /** @type {Array<EstreeComment>} */
+  /** @type {Array<Comment>} */
   const comments = []
@@ -86,3 +92,3 @@ /** @type {string} */
     if (own.call(node, key)) {
-      /** @type {EstreeNode | Array<EstreeNode>} */
+      /** @type {Array<Nodes> | Nodes} */
       // @ts-expect-error: indexable.
@@ -137,3 +143,3 @@ const value = node[key]
  *   Info passed around.
- * @param {EstreeNode} node
+ * @param {Nodes} node
  *   Node.
@@ -144,7 +150,7 @@ * @param {boolean} compareEnd
  *   Fields.
- * @returns {Array<EstreeComment>}
+ * @returns {Array<Comment>}
  *   Slice from `state.comments`.
  */
 function slice(state, node, compareEnd, fields) {
-  /** @type {Array<EstreeComment>} */
+  /** @type {Array<Comment>} */
   const result = []
@@ -165,8 +171,9 @@
  *
- * @param {EstreeNode | EstreeComment} left
+ * @param {Comment | Nodes} left
  *   A node.
- * @param {EstreeNode | EstreeComment} right
+ * @param {Comment | Nodes} right
  *   The other node.
  * @param {boolean | undefined} [compareEnd=false]
- *   Compare on `end` of `right`, default is to compare on `start`.
+ *   Compare on `end` of `right`, default is to compare on `start` (default:
+ *   `false`).
  * @returns {number}
@@ -173,0 +180,0 @@ *   Sorting.

package.json

 {
   "name": "estree-util-attach-comments",
-  "version": "2.1.1",
+  "version": "3.0.0",
   "description": "Attach comments to estree nodes",
@@ -29,4 +29,3 @@ "license": "MIT",
   "type": "module",
-  "main": "index.js",
-  "types": "index.d.ts",
+  "exports": "./index.js",
   "files": [
@@ -42,13 +41,13 @@ "lib/",
     "@types/acorn": "^4.0.0",
-    "@types/node": "^18.0.0",
+    "@types/node": "^20.0.0",
     "acorn": "^8.0.0",
-    "c8": "^7.0.0",
-    "estree-util-visit": "^1.0.0",
-    "prettier": "^2.0.0",
-    "recast": "^0.22.0",
+    "c8": "^8.0.0",
+    "estree-util-visit": "^2.0.0",
+    "prettier": "^3.0.0",
+    "recast": "^0.23.0",
     "remark-cli": "^11.0.0",
     "remark-preset-wooorm": "^9.0.0",
     "type-coverage": "^2.0.0",
-    "typescript": "^4.0.0",
-    "xo": "^0.53.0"
+    "typescript": "^5.0.0",
+    "xo": "^0.55.0"
   },
@@ -58,24 +57,18 @@ "scripts": {
     "build": "tsc --build --clean && tsc --build && type-coverage",
-    "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
+    "format": "remark . -qfo && prettier . -w --log-level warn && xo --fix",
     "test-api": "node --conditions development test.js",
-    "test-coverage": "c8 --check-coverage --100 --reporter lcov npm run test-api",
+    "test-coverage": "c8 --100 --reporter lcov npm run test-api",
     "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
-    "tabWidth": 2,
-    "useTabs": false,
-    "singleQuote": true,
     "bracketSpacing": false,
     "semi": false,
-    "trailingComma": "none"
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "none",
+    "useTabs": false
   },
-  "xo": {
-    "prettier": true,
-    "rules": {
-      "max-depth": "off"
-    }
-  },
   "remarkConfig": {
     "plugins": [
-      "preset-wooorm"
+      "remark-preset-wooorm"
     ]
@@ -86,4 +79,11 @@ },
     "detail": true,
+    "ignoreCatch": true,
     "strict": true
+  },
+  "xo": {
+    "prettier": true,
+    "rules": {
+      "max-depth": "off"
+    }
   }
 }

readme.md

@@ -47,3 +47,3 @@ # estree-util-attach-comments
 This package is [ESM only][esm].
-In Node.js (version 14.14+ and 16.0+), install with [npm][]:
+In Node.js (version 16+), install with [npm][]:
 
@@ -57,3 +57,3 @@ ```sh
 ```js
-import {attachComments} from 'https://esm.sh/estree-util-attach-comments@2'
+import {attachComments} from 'https://esm.sh/estree-util-attach-comments@3'
 ```
@@ -65,3 +65,3 @@
 <script type="module">
-  import {attachComments} from 'https://esm.sh/estree-util-attach-comments@2?bundle'
+  import {attachComments} from 'https://esm.sh/estree-util-attach-comments@3?bundle'
 </script>
@@ -72,6 +72,8 @@ ```
 
-Say our document `index.js` contains:
+Say our document `x.js` contains:
 
 ```js
-/* 1 */ function /* 2 */ a /* 3 */ (/* 4 */b) /* 5 */ { /* 6 */ return /* 7 */ b + /* 8 */ 1 /* 9 */ }
+/* 1 */ function /* 2 */ a /* 3 */(/* 4 */ b) /* 5 */ {
+  /* 6 */ return /* 7 */ b + /* 8 */ 1 /* 9 */
+}
 ```
@@ -83,9 +85,13 @@
 import fs from 'node:fs/promises'
-import * as acorn from 'acorn'
+import {parse} from 'acorn'
+import {attachComments} from 'estree-util-attach-comments'
 import recast from 'recast'
-import {attachComments} from 'estree-util-attach-comments'
 
-const code = String(await fs.readFile('index.js'))
+const code = String(await fs.readFile('x.js'))
 const comments = []
-const tree = acorn.parse(code, {ecmaVersion: 2020, onComment: comments})
+const tree = parse(code, {
+  sourceType: 'module',
+  ecmaVersion: 'latest',
+  onComment: comments
+})
 
@@ -122,3 +128,3 @@ attachComments(tree, comments)
 
-This package exports the identifier [`attachComments`][attachcomments].
+This package exports the identifier [`attachComments`][api-attach-comments].
 There is no default export.
@@ -157,3 +163,3 @@
 
-The given `tree` ([`Program`][program]).
+Nothing (`undefined`).
 
@@ -167,7 +173,10 @@ ## Types
 
-Projects maintained by the unified collective are compatible with all maintained
+Projects maintained by the unified collective are compatible with maintained
 versions of Node.js.
-As of now, that is Node.js 14.14+ and 16.0+.
-Our projects sometimes work with older versions, but this is not guaranteed.
 
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`estree-util-attach-comments@^3`, compatible with Node.js 16.
+
 ## Contribute
@@ -201,5 +210,5 @@
 
-[size-badge]: https://img.shields.io/bundlephobia/minzip/estree-util-attach-comments.svg
+[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=estree-util-attach-comments
 
-[size]: https://bundlephobia.com/result?p=estree-util-attach-comments
+[size]: https://bundlejs.com/?q=estree-util-attach-comments
 
@@ -242,2 +251,2 @@ [sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
 
-[attachcomments]: #attachcommentstree-comments
+[api-attach-comments]: #attachcommentstree-comments

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

16463

increased by1.79%

Lines of code

236

increased by4.89%

Number of lines in readme file

243

increased by3.85%

Number of medium supply chain risk alerts

0

decreased by-100%

No dependency changes