hast-util-truncate

hast utility to truncate the tree to a certain number of characters.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • truncate(tree[, options])
  • Options
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package is a utility that takes a hast (HTML) syntax tree and truncates it to a certain number of characters, 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.

This utility is similar to hast-util-excerpt, which truncates a tree to a certain comment.

The rehype plugin rehype-infer-description-meta wraps both this utility and hast-util-excerpt to figure out a description of a document, for use with rehype-meta.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install hast-util-truncate

In Deno with esm.sh:

import {truncate} from 'https://esm.sh/hast-util-truncate@2'

In browsers with esm.sh:

<script type="module">
  import {truncate} from 'https://esm.sh/hast-util-truncate@2?bundle'
</script>

Use

Say our module example.js looks as follows:

import {h} from 'hastscript'
import {truncate} from 'hast-util-truncate'

const tree = h('p', [
  'Lorem ipsum dolor sit amet, ',
  h('em', 'consectetur'),
  'adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud'
])

console.log(truncate(tree, {ellipsis: '…'}));

…now running node example.js yields:

{
  type: 'element',
  tagName: 'p',
  properties: {},
  children: [
    {type: 'text', value: 'Lorem ipsum dolor sit amet, '},
    {
      type: 'element',
      tagName: 'em',
      properties: {},
      children: [{type: 'text', value: 'consectetur'}]
    },
    {
      type: 'text',
      value: 'adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim…'
    }
  ]
}

API

This package exports the identifier truncate. There is no default export.

truncate(tree[, options])

Truncate the tree to a certain number of characters.

Parameters

• tree (Node) — tree to truncate
• options (Options, optional) — configuration

Returns

Truncated copy of tree (Node).

Options

Configuration (TypeScript type).

Fields

options.size

Number of characters to truncate to (number, default: 140).

options.ellipsis

Value to use at truncation point (string, optional).

options.maxCharacterStrip

How far to walk back (number, default: 30). The algorithm attempts to break right after a word rather than the exact size. Take for example the |, which is the actual break defined by size, and the … is the location where the ellipsis is placed: This… an|d that. Breaking at | would at best look bad but could likely result in things such as ass… for assignment, which is not ideal. maxCharacterStrip defines how far back the algorithm will walk to find a pretty word break. This prevents a potential slow operation on larger sizes without any whitespace. If maxCharacterStrip characters are walked back and no nice break point is found, the bad break point is used. Set maxCharacterStrip: 0 to not find a nice break.

options.ignore

Nodes to exclude from the resulting tree (Array<Node>). These are not counted towards size.

Types

This package is fully typed with TypeScript. It exports the additional type Options.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

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, hast-util-truncate@^2, compatible with Node.js 16.

Security

Use of hast-util-truncate should be safe if the tree is already safe and you’re not using user content in options. When in doubt, use hast-util-sanitize.

Related

• hast-util-excerpt — truncate the tree to a comment
• rehype-infer-description-meta — infer file metadata from the contents of the document
• rehype-meta — add metadata to the head of a document

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer