hast-util-excerpt - npm Package Compare versions

Comparing version 1.0.1 to 1.0.2

index.d.ts

@@ -1,40 +0,2 @@
-/**
- * Truncate the tree to a certain comment.
- * Returns a copy of the given tree if a comment is found, and `undefined`
- * otherwise.
- *
- * @template {Node} Tree
- * @param {Tree} tree
- * @param {Options} [options]
- * @returns {Tree|undefined}
- */
-export function excerpt<Tree extends Node>(
-  tree: Tree,
-  options?: Options | undefined
-): Tree | undefined
-export type Root = import('hast').Root
-export type Content = import('hast').Content
-export type Text = import('hast').Text
-export type Node = Root | Content
-/**
- * Configuration.
- */
-export type Options = {
-  /**
-   * Comment value to search for.
-   */
-  comment?: string | undefined
-  /**
-   * How far to search for the comment before bailing.
-   * The goal of this project is to find user-defined explicit excerpts, that
-   * are assumed to be somewhat reasonably placed.
-   * This option prevents searching giant documents for some comment
-   * that probably won’t be found at the end.
-   */
-  maxSearchSize?: number | undefined
-  /**
-   * Nodes to exclude from the resulting tree.
-   * These are not counted towards `size`.
-   */
-  ignore?: import('hast').Content[] | undefined
-}
+export {excerpt} from './lib/index.js'
+export type Options = import('./lib/index.js').Options

index.js

 /**
- * @typedef {import('hast').Root} Root
- * @typedef {import('hast').Content} Content
- * @typedef {import('hast').Text} Text
- * @typedef {Root|Content} Node
- *
- * @typedef Options
- *   Configuration.
- * @property {string} [comment='more']
- *   Comment value to search for.
- * @property {number} [maxSearchSize=2048]
- *   How far to search for the comment before bailing.
- *   The goal of this project is to find user-defined explicit excerpts, that
- *   are assumed to be somewhat reasonably placed.
- *   This option prevents searching giant documents for some comment
- *   that probably won’t be found at the end.
- * @property {Content[]} [ignore=[]]
- *   Nodes to exclude from the resulting tree.
- *   These are not counted towards `size`.
+ * @typedef {import('./lib/index.js').Options} Options
  */
 
-import {truncate} from 'hast-util-truncate'
-
-/**
- * Truncate the tree to a certain comment.
- * Returns a copy of the given tree if a comment is found, and `undefined`
- * otherwise.
- *
- * @template {Node} Tree
- * @param {Tree} tree
- * @param {Options} [options]
- * @returns {Tree|undefined}
- */
-export function excerpt(tree, options = {}) {
-  const {comment = 'more', ignore, maxSearchSize = 2048} = options
-  let found = false
-  const result = preorder(truncate(tree, {ignore, size: maxSearchSize}))
-
-  // @ts-expect-error: `result` is most likely a clone of `tree`
-  return found ? result : undefined
-
-  /**
-   * @param {Node} node
-   * @returns {Node|undefined}
-   */
-  function preorder(node) {
-    if (node.type === 'comment' && node.value.trim() === comment) {
-      found = true
-      return
-    }
-
-    if (
-      // @ts-expect-error: integrate w/ `mdast-util-mdx`
-      (node.type === 'mdxFlowExpression' ||
-        // @ts-expect-error
-        node.type === 'mdxTextExpression') &&
-      // @ts-expect-error
-      node.data &&
-      // @ts-expect-error
-      node.data.estree &&
-      // @ts-expect-error
-      node.data.estree.comments &&
-      // @ts-expect-error
-      node.data.estree.comments.some(
-        (/** @type {import('acorn').Comment} */ node) =>
-          node.value.trim() === comment
-      )
-    ) {
-      found = true
-      return
-    }
-
-    /** @type {typeof node} */
-    const replacement = {...node}
-
-    if ('children' in node) {
-      /** @type {Content[]} */
-      const children = []
-      let index = -1
-
-      while (++index < node.children.length && !found) {
-        const result = preorder(node.children[index])
-        // @ts-expect-error: assume content model matches.
-        if (result) children.push(result)
-      }
-
-      // @ts-expect-error: assume content model matches.
-      replacement.children = children
-    }
-
-    return replacement
-  }
-}
+export {excerpt} from './lib/index.js'

package.json

 {
   "name": "hast-util-excerpt",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "hast utility to excerpt the tree to a comment",
@@ -32,2 +32,3 @@ "license": "MIT",
   "files": [
+    "lib/",
     "index.d.ts",
@@ -41,4 +42,3 @@ "index.js"
   "devDependencies": {
-    "@types/acorn": "^4.0.6",
-    "@types/tape": "^4.0.0",
+    "@types/node": "^18.0.0",
     "c8": "^7.0.0",
@@ -48,10 +48,8 @@ "hast-util-select": "^5.0.0",
     "mdast-util-from-markdown": "^1.0.0",
-    "mdast-util-mdx": "^1.0.0",
-    "mdast-util-to-hast": "^11.0.0",
+    "mdast-util-mdx": "^2.0.0",
+    "mdast-util-to-hast": "^12.0.0",
     "micromark-extension-mdxjs": "^1.0.0",
     "prettier": "^2.0.0",
-    "remark-cli": "^10.0.0",
+    "remark-cli": "^11.0.0",
     "remark-preset-wooorm": "^9.0.0",
-    "rimraf": "^3.0.0",
-    "tape": "^5.0.0",
     "type-coverage": "^2.0.0",
@@ -61,10 +59,10 @@ "typescript": "^4.0.0",
     "unist-util-remove-position": "^4.0.0",
-    "xo": "^0.44.0"
+    "xo": "^0.53.0"
   },
   "scripts": {
     "prepack": "npm run build && npm run format",
-    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
+    "build": "tsc --build --clean && tsc --build && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
-    "test-api": "node test.js",
-    "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test.js",
+    "test-api": "node --conditions development test.js",
+    "test-coverage": "c8 --check-coverage --100 --reporter lcov npm run test-api",
     "test": "npm run build && npm run format && npm run test-coverage"
@@ -71,0 +69,0 @@ },

readme.md

@@ -11,11 +11,45 @@ # hast-util-excerpt
 
-**[hast][]** utility to truncate the tree to a comment.
+[hast][] utility to truncate the tree to a comment.
 
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`excerpt(tree[, options])`](#excerpttree-options)
+    *   [`Options`](#options)
+*   [Syntax tree](#syntax-tree)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Security](#security)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [License](#license)
+
+## What is this?
+
+This package is a utility that takes a [hast][] (HTML) syntax tree and truncates
+it to a comment, while otherwise preserving the tree structure.
+
+## When should I use this?
+
+This is a small utility useful when you need to create a shorter version of a
+potentially long document, and want authors to be able to mark where that
+version ends.
+
+This utility is similar to [`hast-util-truncate`][hast-util-truncate], which
+truncates a tree to a certain number of characters.
+
+The rehype plugin
+[`rehype-infer-description-meta`][rehype-infer-description-meta]
+wraps both this utility and `hast-util-truncate` to figure out a description of
+a document, for use with [`rehype-meta`][rehype-meta].
+
 ## Install
 
-This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
-Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
+This package is [ESM only][esm].
+In Node.js (version 14.14+ or 16.0+), install with [npm][]:
 
-[npm][]:
-
 ```sh
@@ -25,5 +59,19 @@ npm install hast-util-excerpt
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {excerpt} from "https://esm.sh/hast-util-excerpt@1"
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {excerpt} from "https://esm.sh/hast-util-excerpt@1?bundle"
+</script>
+```
+
 ## Use
 
-Say we have the following module, `example.js`:
+Say our module `example.js` looks as follows:
 
@@ -46,3 +94,3 @@ ```js
 
-Now, running `node example.js` yields:
+…now running `node example.js` yields:
 
@@ -73,14 +121,32 @@ ```js
 
-This package exports the following identifiers: `excerpt`.
+This package exports the identifier [`excerpt`][excerpt].
 There is no default export.
 
-### `excerpt(tree, options?)`
+### `excerpt(tree[, options])`
 
-Truncate the tree to a comment.
+Truncate `tree` to a certain comment.
 
-###### `options.comment`
+###### Parameters
 
+*   `tree` ([`Node`][node])
+    — tree to truncate
+*   `options` ([`Options`][options])
+    — configuration (optional)
+
+###### Returns
+
+Truncated copy of `tree` ([`Node`][node]) when a comment is found, `undefined`
+otherwise.
+
+### `Options`
+
+Configuration (TypeScript type).
+
+##### Fields
+
+###### `comment`
+
 Comment value to search for (`string`, default: `'more'`).
 
-###### `options.maxSearchSize`
+###### `maxSearchSize`
 
@@ -93,11 +159,23 @@ How far to search for the comment before bailing (`number`, default: `2048`).
 
-###### `options.ignore`
+###### `ignore`
 
-Nodes to exclude from the resulting tree (`Array.<Node>`).
+Nodes to exclude from the resulting tree ([`Array<Node>`][node]).
 These are not counted towards `size`.
 
-###### Returns
+## Syntax tree
 
-`Node?` — Truncated copy of `tree` if there’s a comment, `undefined` otherwise.
+The syntax tree is [hast][].
 
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports the additional type [`Options`][options].
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with all 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.
+
 ## Security
@@ -107,3 +185,3 @@
 you’re not using user content in options.
-When in doubt, use [`hast-util-sanitize`][sanitize].
+When in doubt, use [`hast-util-sanitize`][hast-util-sanitize].
 
@@ -113,8 +191,12 @@ ## Related
 *   [`hast-util-truncate`](https://github.com/syntax-tree/hast-util-truncate)
-    — Truncate the tree to a certain number of characters
+    — truncate the tree to a number of characters
+*   [`rehype-infer-description-meta`][rehype-infer-description-meta]
+    — infer file metadata from the contents of the document
+*   [`rehype-meta`][rehype-meta]
+    — add metadata to the head of a document
 
 ## Contribute
 
-See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
-started.
+See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
+ways to get started.
 See [`support.md`][support] for ways to get help.
@@ -160,2 +242,8 @@
 
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[typescript]: https://www.typescriptlang.org
+
 [license]: license
@@ -165,10 +253,24 @@
 
-[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
+[health]: https://github.com/syntax-tree/.github
 
-[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
+[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
 
-[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
+[support]: https://github.com/syntax-tree/.github/blob/main/support.md
 
-[sanitize]: https://github.com/syntax-tree/hast-util-sanitize
+[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
 
 [hast]: https://github.com/syntax-tree/hast
+
+[hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize
+
+[hast-util-truncate]: https://github.com/syntax-tree/hast-util-truncate
+
+[rehype-infer-description-meta]: https://github.com/rehypejs/rehype-infer-description-meta
+
+[rehype-meta]: https://github.com/rehypejs/rehype-meta
+
+[excerpt]: #excerpttree-options
+
+[options]: #options
+
+[node]: https://github.com/syntax-tree/hast#nodes

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

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

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

Improved metrics

Total package byte prevSize

14569

increased by26.46%

Dev dependency count

16

decreased by-15.79%

Number of package files

7

increased by40%

Lines of code

136

increased by10.57%

Number of lines in readme file

268

increased by61.45%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes