truncate

truncate is a small, dependency-free JavaScript utility for cutting text down to a maximum length without breaking apart the URLs or email addresses inside it. Rather than naively slicing a string at a character count, it scans for URL and mailto patterns as it truncates and extends the cut point so a link is either kept whole or dropped entirely, appending a configurable ellipsis (the default is an ellipsis character, or none) only when content is actually shortened.

It ships as a single file with no runtime dependencies, works equally in Node (via require(‘truncate’)) and the browser (as a String.truncate global), and includes a hand-written TypeScript declaration file so consumers get type safety without an extra @types package. The test suite covers common truncation cases plus a dedicated regression test guarding against catastrophic regex backtracking (ReDoS) in the URL-matching logic.

What You Get

• Single truncate() function - one default export, truncate(string, maxLength, options), with no configuration ceremony.
• URL and email-safe truncation - URLs and mailto addresses are matched via regex and either kept whole or cut cleanly, never left dangling mid-link.
• Configurable ellipsis - pass options.ellipsis to swap the default character for a custom string or disable it entirely with null or an empty string.
• Dual Node/browser support with shipped TypeScript types - works as a CommonJS export or a global String.truncate, with a bundled .d.ts for TypeScript consumers.

Common Use Cases

• Chat and comment previews - a messaging or comment UI truncates long messages for a preview line without cutting a shared link in half.
• Social feed excerpts - a feed or notification list shortens post text to a fixed length while keeping any embedded URL intact and clickable.
• Email/notification digests - a digest email trims quoted or forwarded text but preserves full links and email addresses so recipients can still follow them.
• Legacy Node services adding safe text truncation - a service picks up a zero-dependency utility instead of hand-rolling truncation plus URL-detection regex.

Under The Hood

Architecture truncate.js is a single-file UMD module wrapping one exported truncate function and a private __appendEllipsis helper. The core loop repeatedly runs a shared URL_REGEX against the input string, tracking lastIndex to walk forward through matches, and decides at each step whether a detected URL or mailto address fits within the remaining length budget; if not, it falls back to a plain substring cut. There is no internal layering beyond this one function — the entire library’s behavior hinges on that regex-scanning loop, so any change to the URL-matching pattern directly changes truncation behavior everywhere.

Tech Stack Plain ES5-style JavaScript with 'use strict', zero runtime dependencies declared in package.json. Development tooling is limited to nodeunit (test runner), npm-release (release automation), and yuidocjs (documentation generation). There is no bundler or build step; the package ships the raw truncate.js as main alongside a hand-written truncate.d.ts for TypeScript consumers. GitHub Actions CI runs npm test across a small matrix of Node versions on every push and pull request.

Code Quality The test suite, run via nodeunit, covers plain-length truncation, URL-preservation edge cases at various length boundaries, and a dedicated regression test that measures elapsed time against a pathological input string to confirm the URL regex resists catastrophic backtracking (ReDoS). There is no TypeScript source, linter, or formatter configuration; naming follows a terse ES5 convention. Error handling is minimal, limited to explicit short-circuiting on empty or null input, which matches the narrow scope of the function.

API Design The public surface is a single default export with the call signature truncate(string, maxLength, options), mirroring the intuitive feel of a built-in string method, and it is usable identically as a CommonJS import or as a browser global. Type definitions ship inside the package itself so TypeScript users need no separate types package. Its differentiator over a generic substring truncation helper is the deliberate, tested URL-preservation logic combined with explicit ReDoS hardening, rather than any broader feature set.