contextual-trim

String manipulation utilities that preserve position and context information.

Installation

npm install contextual-trim

Features

• Context-aware trimming: Remove whitespace while tracking what was removed and where
• Position tracking: Know the exact position of processed strings in the original text
• Chainable operations: All functions accept both strings and StringResult objects
• TypeScript support: Full type definitions included

Usage

Basic Trimming

import { cTrim, cTrimLeft, cTrimRight } from 'contextual-trim';

// Trim both ends
const result = cTrim('  hello world  ');
console.log(result);
// {
//   value: 'hello world',
//   left: '  ',
//   right: '  ',
//   position: 2
// }

// Trim left only
const leftResult = cTrimLeft('  hello world  ');
console.log(leftResult);
// {
//   value: 'hello world  ',
//   left: '  ',
//   right: '',
//   position: 2
// }

// Trim right only
const rightResult = cTrimRight('  hello world  ');
console.log(rightResult);
// {
//   value: '  hello world',
//   left: '',
//   right: '  ',
//   position: 0
// }

String Splitting with Context

import { cSplit } from 'contextual-trim';

const parts = cSplit('apple,banana,cherry', ',');
console.log(parts);
// [
//   { value: 'apple', position: 0, left: '', right: ',banana,cherry' },
//   { value: 'banana', position: 6, left: 'apple,', right: ',cherry' },
//   { value: 'cherry', position: 13, left: 'apple,banana,', right: '' }
// ]

Chaining Operations

All functions accept StringResult objects, allowing you to chain operations while maintaining accurate position tracking:

import { cTrim, cSplit } from 'contextual-trim';

// Chain trim and split operations
const text = '  apple, banana, cherry  ';
const trimmed = cTrim(text);
const parts = cSplit(trimmed, ',');

console.log(parts);
// Each part maintains position relative to the original text
// [
//   { value: 'apple', position: 2, left: '  ', right: ', banana, cherry  ' },
//   { value: ' banana', position: 8, left: '  apple,', right: ', cherry  ' },
//   { value: ' cherry', position: 16, left: '  apple, banana,', right: '  ' }
// ]

// Further process each part
const cleanParts = parts.map(part => cTrim(part));
console.log(cleanParts);
// [
//   { value: 'apple', position: 2, left: '  ', right: ', banana, cherry  ' },
//   { value: 'banana', position: 9, left: '  apple, ', right: ', cherry  ' },
//   { value: 'cherry', position: 17, left: '  apple, banana, ', right: '  ' }
// ]

API Reference

Types

StringResult

interface StringResult {
  value: string;      // The processed string value
  left: string;       // Text that was to the left (removed or context)
  right: string;      // Text that was to the right (removed or context)
  position: number;   // Position in the original string
}

Functions

cTrim(text: string | StringResult): StringResult

Removes whitespace from both ends of a string.

Parameters:

• text: The string or StringResult to trim

Returns: StringResult with trimmed value and context information

cTrimLeft(text: string | StringResult): StringResult

Removes whitespace from the left end of a string.

Parameters:

• text: The string or StringResult to trim

Returns: StringResult with left-trimmed value and context information

cTrimRight(text: string | StringResult): StringResult

Removes whitespace from the right end of a string.

Parameters:

• text: The string or StringResult to trim

Returns: StringResult with right-trimmed value and context information

cSplit(text: string | StringResult, delimiter: string): StringResult[]

Splits a string by delimiter while tracking positions and context.

Parameters:

• text: The string or StringResult to split
• delimiter: The delimiter to split by

Returns: Array of StringResult objects, one for each split part

License

MIT