@lp-labs/text-wrap 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# @lp-labs/text-wrap
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Greedy paragraph-preserving word wrapping with supplied width measurement and explicit long-word policies.
+
+Standalone original implementation; zero runtime, peer, or sibling-package dependencies. Node.js 18+, ESM and CommonJS with separate declaration trees. No browser globals are accessed at import time; compiled runtime uses only standard JavaScript APIs.
+
+## Install
+
+```sh
+npm install @lp-labs/text-wrap
+```
+
+## Quick start
+
+```js
+import { wrapText } from '@lp-labs/text-wrap';
+console.log(wrapText('one two three', { width: 7 })); // ['one two', 'three']
+```
+
+CommonJS exposes the same named exports:
+
+```cjs
+const api = require('@lp-labs/text-wrap');
+```
+
+## Customization
+
+```js
+import { wrapText } from '@lp-labs/text-wrap';
+const measure = (text) => [...text].reduce((n, c) => n + (c === '界' ? 2 : 1), 0);
+console.log(wrapText('界 a b', { width: 4, measure, longWord: 'error' }));
+```
+
+## Semantics, limits and errors
+
+`wrapText(text, options)` returns a fresh string array, without trailing newline characters. CRLF, LF and CR preserve paragraph boundaries, including empty paragraphs. Other whitespace between words is normalized to one ASCII space; leading/trailing whitespace is discarded. Empty text yields one empty line.
+
+`width` is a positive safe integer. Default `measure` counts Unicode code points, **not wcwidth, display cells, graphemes, or terminal escape sequences**. It is called on complete candidate strings, including spaces, and must be deterministic and return a finite nonnegative number, with zero for empty text. Non-additive measurements are accepted, but greedy results need not be optimal.
+
+`longWord` defaults to `split`: split at code-point boundaries; an individual point wider than the target throws. `overflow` retains an overlong word on its own line. `error` rejects it. A combining sequence may be divided. Default `maxInput` is 100,000 UTF-16 units and `maxLines` is 10,000 (both positive integers). Unsupported C0 controls and DEL throw TypeError; horizontal tabs/newlines are supported. Invalid widths, measurements and exhausted line budgets throw RangeError; callbacks propagate their own errors.
+
+Work is greedy, with up to O(n²) total candidate text/measurement work for a long line or word; callback cost is additional. Output space is O(n + lines). No callback or input options are retained.
+
+## Complete public declaration API
+
+The following is the complete public ESM declaration surface; CommonJS has matching declarations and runtime exports. Optional properties are omitted rather than supplied as undefined under exactOptionalPropertyTypes.
+
+```ts
+export interface WrapOptions {
+  width: number;
+  measure?: (text: string) => number;
+  longWord?: 'split' | 'overflow' | 'error';
+  maxInput?: number;
+  maxLines?: number;
+}
+/** Wrap whitespace-separated words; explicit newlines are retained. */
+export declare function wrapText(text: string, options: WrapOptions): string[];
+```
+
+## Development and verification
+
+```sh
+npm ci --offline --ignore-scripts --no-audit --no-fund
+npm run build
+npm run typecheck
+npm test
+npm run format:check
+```
+
+The offline command requires the dev tools already present in npm's cache. TypeScript ^5.9.3 and Prettier ^3.6.2 are dev-only. Build targets ES2022 with strict NodeNext declarations, noUncheckedIndexedAccess, exactOptionalPropertyTypes, noUnused checks, ES2022/DOM libs and no ambient type packages. Runtime tests import the ESM distribution directly and check CommonJS parity. Bare-package .mts/.cts consumer tests include negative type assertions. Published files are only dist, this README, LICENSE and package.json. No publication is performed by tests.
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,9 @@
+export interface WrapOptions {
+    width: number;
+    measure?: (text: string) => number;
+    longWord?: 'split' | 'overflow' | 'error';
+    maxInput?: number;
+    maxLines?: number;
+}
+/** Wrap whitespace-separated words; explicit newlines are retained. */
+export declare function wrapText(text: string, options: WrapOptions): string[];

package/dist/cjs/index.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapText = wrapText;
+/** Wrap whitespace-separated words; explicit newlines are retained. */
+function wrapText(text, options) {
+    const { width, measure = (value) => [...value].length, longWord = 'split', maxInput = 100_000, maxLines = 10_000, } = options;
+    for (const n of [width, maxInput, maxLines])
+        if (!Number.isSafeInteger(n) || n < 1)
+            throw new RangeError('Limits must be positive integers.');
+    if (!['split', 'overflow', 'error'].includes(longWord))
+        throw new TypeError('Unknown longWord policy.');
+    if (typeof text !== 'string' ||
+        text.length > maxInput ||
+        /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(text))
+        throw new TypeError('Invalid or oversized text.');
+    const size = (value) => {
+        const n = measure(value);
+        if (!Number.isFinite(n) || n < 0)
+            throw new RangeError('measure must return a finite nonnegative width.');
+        return n;
+    };
+    if (size('') !== 0)
+        throw new RangeError('Empty text must measure zero.');
+    const result = [];
+    const emit = (line) => {
+        if (result.length >= maxLines)
+            throw new RangeError('Line budget exceeded.');
+        result.push(line);
+    };
+    for (const paragraph of text.split(/\r\n|\r|\n/u)) {
+        let line = '';
+        for (const word of paragraph.split(/[^\S\r\n]+/u).filter(Boolean)) {
+            if (line && size(`${line} ${word}`) <= width) {
+                line += ` ${word}`;
+                continue;
+            }
+            if (line) {
+                emit(line);
+                line = '';
+            }
+            if (size(word) <= width || longWord === 'overflow') {
+                line = word;
+                continue;
+            }
+            if (longWord === 'error')
+                throw new RangeError('Word exceeds width.');
+            for (const point of word) {
+                if (size(point) > width)
+                    throw new RangeError('One code point exceeds width.');
+                if (line && size(line + point) > width) {
+                    emit(line);
+                    line = '';
+                }
+                line += point;
+            }
+        }
+        emit(line);
+    }
+    return result;
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,9 @@
+export interface WrapOptions {
+    width: number;
+    measure?: (text: string) => number;
+    longWord?: 'split' | 'overflow' | 'error';
+    maxInput?: number;
+    maxLines?: number;
+}
+/** Wrap whitespace-separated words; explicit newlines are retained. */
+export declare function wrapText(text: string, options: WrapOptions): string[];

package/dist/esm/index.js

@@ -0,0 +1,57 @@
+/** Wrap whitespace-separated words; explicit newlines are retained. */
+export function wrapText(text, options) {
+    const { width, measure = (value) => [...value].length, longWord = 'split', maxInput = 100_000, maxLines = 10_000, } = options;
+    for (const n of [width, maxInput, maxLines])
+        if (!Number.isSafeInteger(n) || n < 1)
+            throw new RangeError('Limits must be positive integers.');
+    if (!['split', 'overflow', 'error'].includes(longWord))
+        throw new TypeError('Unknown longWord policy.');
+    if (typeof text !== 'string' ||
+        text.length > maxInput ||
+        /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(text))
+        throw new TypeError('Invalid or oversized text.');
+    const size = (value) => {
+        const n = measure(value);
+        if (!Number.isFinite(n) || n < 0)
+            throw new RangeError('measure must return a finite nonnegative width.');
+        return n;
+    };
+    if (size('') !== 0)
+        throw new RangeError('Empty text must measure zero.');
+    const result = [];
+    const emit = (line) => {
+        if (result.length >= maxLines)
+            throw new RangeError('Line budget exceeded.');
+        result.push(line);
+    };
+    for (const paragraph of text.split(/\r\n|\r|\n/u)) {
+        let line = '';
+        for (const word of paragraph.split(/[^\S\r\n]+/u).filter(Boolean)) {
+            if (line && size(`${line} ${word}`) <= width) {
+                line += ` ${word}`;
+                continue;
+            }
+            if (line) {
+                emit(line);
+                line = '';
+            }
+            if (size(word) <= width || longWord === 'overflow') {
+                line = word;
+                continue;
+            }
+            if (longWord === 'error')
+                throw new RangeError('Word exceeds width.');
+            for (const point of word) {
+                if (size(point) > width)
+                    throw new RangeError('One code point exceeds width.');
+                if (line && size(line + point) > width) {
+                    emit(line);
+                    line = '';
+                }
+                line += point;
+            }
+        }
+        emit(line);
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/text-wrap",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Greedy paragraph-preserving word wrapping with supplied width measurement and explicit long-word policies.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build && node scripts/check-types.mjs",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "format": "prettier --write src scripts tests *.json README.md",
+    "format:check": "prettier --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  }
+}