Add string utility function: truncate (#70)

This PR adds the essential `truncate` string utility function from the
VS Code codebase to enhance the javascript-utils library.

## New Function

### `truncate(value, maxLength, suffix?)`
Truncates a string to a maximum length, adding an optional suffix
(default empty string) if truncated.

```typescript
truncate("hello world", 8)           // "hello wo"
truncate("hello world", 15)          // "hello world"
truncate("hello", 3, "...")          // "hel..."
```

## Features

- **Robust null/undefined handling**: Function gracefully handles null
and undefined inputs
- **Comprehensive test coverage**: Extensive test cases covering edge
cases and various input scenarios
- **TypeScript type safety**: Proper type definitions with union types
for null/undefined safety
- **Code style compliance**: Follows project linting rules and
formatting standards
- **Consistent API**: Follows the same patterns as existing utility
functions in the library

## Implementation Notes

The function is based on the VS Code source implementation but adapted
to match this library's patterns for null/undefined handling and error
recovery. The function returns sensible defaults rather than throwing
errors for invalid inputs.

- [x] Implement truncate function with proper null/undefined handling
- [x] Add comprehensive test coverage including edge cases
- [x] Update changelog with new function
- [x] Ensure code style compliance and linting passes
- [x] Add test group for truncate without suffix parameter

Fixes #29.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: drebrez <1611547+drebrez@users.noreply.github.com>
Co-authored-by: manni497 <65862280+manni497@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `truncate` string utility function
+
 ## [1.5.0] - 2025-07-07
 
 ### Added

src/lib/string.spec.ts

@@ -1,4 +1,4 @@
-import { isNullOrEmpty, isNullOrWhitespace, capitalize, uncapitalize } from "./string";
+import { isNullOrEmpty, isNullOrWhitespace, capitalize, uncapitalize, truncate } from "./string";
 
 describe("string tests", () => {
   test.each([
@@ -84,4 +84,40 @@ describe("string tests", () => {
   ])("uncapitalize", (value, expected) => {
     expect(uncapitalize(value)).toBe(expected);
   });
+
+  test.each([
+    [null as unknown as string, 10, "", null],
+    [undefined as unknown as string, 10, "", undefined],
+    ["", 10, "", ""],
+    ["hello", 10, "", "hello"],
+    ["hello", 5, "", "hello"],
+    ["hello world", 5, "", "hello"],
+    ["hello world", 8, "", "hello wo"],
+    ["hello world", 11, "", "hello world"],
+    ["hello world", 0, "", ""],
+    ["hello", 3, ">>", "hel>>"],
+    ["test", 2, "", "te"],
+    ["hello world", 5, "...", "hello..."],
+    ["hello world", 8, "...", "hello wo..."],
+    ["hello world", 0, "...", "..."],
+  ])("truncate", (value, maxLength, suffix, expected) => {
+    expect(truncate(value, maxLength, suffix)).toBe(expected);
+  });
+
+  test.each([
+    [null as unknown as string, 10, null],
+    [undefined as unknown as string, 10, undefined],
+    ["", 10, ""],
+    ["hello", 10, "hello"],
+    ["hello", 5, "hello"],
+    ["hello world", 5, "hello"],
+    ["hello world", 8, "hello wo"],
+    ["hello world", 11, "hello world"],
+    ["hello world", 0, ""],
+    ["test", 2, "te"],
+    ["a very long string", 6, "a very"],
+    ["short", 10, "short"],
+  ])("truncate without suffix parameter", (value, maxLength, expected) => {
+    expect(truncate(value, maxLength)).toBe(expected);
+  });
 });

src/lib/string.ts

@@ -45,3 +45,22 @@ export function uncapitalize(value?: string): string | undefined {
 
   return value.charAt(0).toLowerCase() + value.slice(1);
 }
+
+/**
+ * Truncates a string to a maximum length, adding a suffix if truncated
+ * @param value The string to truncate
+ * @param maxLength The maximum length of the resulting string
+ * @param suffix The suffix to append if truncated (default: "")
+ * @returns The truncated string
+ */
+export function truncate(value: string | undefined, maxLength: number, suffix = ""): string | undefined {
+  if (!value || isNullOrWhitespace(value)) {
+    return value;
+  }
+
+  if (value.length <= maxLength) {
+    return value;
+  }
+
+  return `${value.slice(0, maxLength)}${suffix}`;
+}