@hardlydifficult/text 1.0.0

package/README.md

@@ -0,0 +1,77 @@
+# @hardlydifficult/text
+
+Text utilities for error formatting, template replacement, and chunking.
+
+## Installation
+
+```bash
+npm install @hardlydifficult/text
+```
+
+## API
+
+### `getErrorMessage(err: unknown): string`
+
+Extract a message string from an unknown error. Returns `err.message` for `Error` instances, `String(err)` otherwise.
+
+```typescript
+import { getErrorMessage } from "@hardlydifficult/text";
+
+try {
+  await riskyOperation();
+} catch (err) {
+  console.error(getErrorMessage(err));
+}
+```
+
+### `formatError(err: unknown, context?: string): string`
+
+Format an error for user-facing output. Prepends an optional context prefix.
+
+```typescript
+import { formatError } from "@hardlydifficult/text";
+
+formatError(new Error("not found"), "User lookup"); // "User lookup: not found"
+formatError(new Error("not found")); // "not found"
+```
+
+### `formatErrorForLog(err: unknown): string`
+
+Format an error for logging. Returns the message for `Error` instances, `String(err)` otherwise.
+
+### `replaceTemplate(template: string, values: Record<string, string>): string`
+
+Replace `{{variable}}` placeholders with provided values. Unmatched placeholders are left as-is.
+
+```typescript
+import { replaceTemplate } from "@hardlydifficult/text";
+
+replaceTemplate("Hello {{name}}, welcome to {{place}}!", {
+  name: "Alice",
+  place: "Wonderland",
+});
+// "Hello Alice, welcome to Wonderland!"
+```
+
+### `extractPlaceholders(template: string): string[]`
+
+Extract all unique placeholder names from a template.
+
+```typescript
+import { extractPlaceholders } from "@hardlydifficult/text";
+
+extractPlaceholders("{{name}} is in {{place}}"); // ["name", "place"]
+```
+
+### `chunkText(text: string, maxLength: number): string[]`
+
+Split text into chunks of at most `maxLength` characters. Prefers breaking on newlines, then spaces, and falls back to hard breaks.
+
+```typescript
+import { chunkText } from "@hardlydifficult/text";
+
+const chunks = chunkText(longMessage, 2000);
+for (const chunk of chunks) {
+  await channel.send(chunk);
+}
+```

package/dist/chunkText.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Split text into chunks that respect a maximum length.
+ * Prefers breaking on newlines, then spaces, and falls back to hard breaks.
+ */
+/**
+ * Split text into chunks of at most `maxLength` characters.
+ *
+ * @param text - The text to split
+ * @param maxLength - Maximum length of each chunk
+ * @returns Array of text chunks
+ */
+export declare function chunkText(text: string, maxLength: number): string[];
+//# sourceMappingURL=chunkText.d.ts.map

package/dist/chunkText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunkText.d.ts","sourceRoot":"","sources":["../src/chunkText.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAwBnE"}

package/dist/chunkText.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Split text into chunks that respect a maximum length.
+ * Prefers breaking on newlines, then spaces, and falls back to hard breaks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chunkText = chunkText;
+/**
+ * Split text into chunks of at most `maxLength` characters.
+ *
+ * @param text - The text to split
+ * @param maxLength - Maximum length of each chunk
+ * @returns Array of text chunks
+ */
+function chunkText(text, maxLength) {
+    const chunks = [];
+    let remaining = text;
+    while (remaining.length > 0) {
+        if (remaining.length <= maxLength) {
+            chunks.push(remaining);
+            break;
+        }
+        // Find a good break point (newline or space)
+        let breakPoint = remaining.lastIndexOf("\n", maxLength);
+        if (breakPoint === -1 || breakPoint < maxLength / 2) {
+            breakPoint = remaining.lastIndexOf(" ", maxLength);
+        }
+        if (breakPoint === -1 || breakPoint < maxLength / 2) {
+            breakPoint = maxLength;
+        }
+        chunks.push(remaining.slice(0, breakPoint));
+        remaining = remaining.slice(breakPoint).trimStart();
+    }
+    return chunks;
+}
+//# sourceMappingURL=chunkText.js.map

package/dist/chunkText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunkText.js","sourceRoot":"","sources":["../src/chunkText.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AASH,8BAwBC;AA/BD;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,IAAY,EAAE,SAAiB;IACvD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,SAAS,GAAG,IAAI,CAAC;IAErB,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,IAAI,SAAS,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;YAClC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACvB,MAAM;QACR,CAAC;QAED,6CAA6C;QAC7C,IAAI,UAAU,GAAG,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACxD,IAAI,UAAU,KAAK,CAAC,CAAC,IAAI,UAAU,GAAG,SAAS,GAAG,CAAC,EAAE,CAAC;YACpD,UAAU,GAAG,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACrD,CAAC;QACD,IAAI,UAAU,KAAK,CAAC,CAAC,IAAI,UAAU,GAAG,SAAS,GAAG,CAAC,EAAE,CAAC;YACpD,UAAU,GAAG,SAAS,CAAC;QACzB,CAAC;QAED,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;QAC5C,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,SAAS,EAAE,CAAC;IACtD,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Error utilities - consistent error handling across the codebase
+ */
+/**
+ * Extract a message string from an unknown error
+ */
+export declare function getErrorMessage(err: unknown): string;
+/**
+ * Format an error for user-facing output
+ */
+export declare function formatError(err: unknown, context?: string): string;
+/**
+ * Format an error for logging (includes more detail for non-Error types)
+ */
+export declare function formatErrorForLog(err: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAKpD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAMlE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAKtD"}

package/dist/errors.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Error utilities - consistent error handling across the codebase
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getErrorMessage = getErrorMessage;
+exports.formatError = formatError;
+exports.formatErrorForLog = formatErrorForLog;
+/**
+ * Extract a message string from an unknown error
+ */
+function getErrorMessage(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
+/**
+ * Format an error for user-facing output
+ */
+function formatError(err, context) {
+    const message = getErrorMessage(err);
+    if (context !== undefined && context !== "") {
+        return `${context}: ${message}`;
+    }
+    return message;
+}
+/**
+ * Format an error for logging (includes more detail for non-Error types)
+ */
+function formatErrorForLog(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA;;GAEG;;AAKH,0CAKC;AAKD,kCAMC;AAKD,8CAKC;AA7BD;;GAEG;AACH,SAAgB,eAAe,CAAC,GAAY;IAC1C,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,OAAO,GAAG,CAAC,OAAO,CAAC;IACrB,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,SAAgB,WAAW,CAAC,GAAY,EAAE,OAAgB;IACxD,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QAC5C,OAAO,GAAG,OAAO,KAAK,OAAO,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAAC,GAAY;IAC5C,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,OAAO,GAAG,CAAC,OAAO,CAAC;IACrB,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { getErrorMessage, formatError, formatErrorForLog } from "./errors.js";
+export { replaceTemplate, extractPlaceholders } from "./template.js";
+export { chunkText } from "./chunkText.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chunkText = exports.extractPlaceholders = exports.replaceTemplate = exports.formatErrorForLog = exports.formatError = exports.getErrorMessage = void 0;
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "getErrorMessage", { enumerable: true, get: function () { return errors_js_1.getErrorMessage; } });
+Object.defineProperty(exports, "formatError", { enumerable: true, get: function () { return errors_js_1.formatError; } });
+Object.defineProperty(exports, "formatErrorForLog", { enumerable: true, get: function () { return errors_js_1.formatErrorForLog; } });
+var template_js_1 = require("./template.js");
+Object.defineProperty(exports, "replaceTemplate", { enumerable: true, get: function () { return template_js_1.replaceTemplate; } });
+Object.defineProperty(exports, "extractPlaceholders", { enumerable: true, get: function () { return template_js_1.extractPlaceholders; } });
+var chunkText_js_1 = require("./chunkText.js");
+Object.defineProperty(exports, "chunkText", { enumerable: true, get: function () { return chunkText_js_1.chunkText; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yCAA8E;AAArE,4GAAA,eAAe,OAAA;AAAE,wGAAA,WAAW,OAAA;AAAE,8GAAA,iBAAiB,OAAA;AACxD,6CAAqE;AAA5D,8GAAA,eAAe,OAAA;AAAE,kHAAA,mBAAmB,OAAA;AAC7C,+CAA2C;AAAlC,yGAAA,SAAS,OAAA"}

package/dist/template.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Simple template utility for placeholder replacement.
+ * Replaces {{variable}} placeholders with provided values.
+ */
+/**
+ * Replace template placeholders with values
+ *
+ * @param template - The template string with {{variable}} placeholders
+ * @param values - Object mapping variable names to their values
+ * @returns The template with placeholders replaced
+ */
+export declare function replaceTemplate(template: string, values: Record<string, string>): string;
+/**
+ * Extract all placeholder names from a template
+ *
+ * @param template - The template string with {{variable}} placeholders
+ * @returns Array of unique placeholder names
+ */
+export declare function extractPlaceholders(template: string): string[];
+//# sourceMappingURL=template.d.ts.map

package/dist/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,MAAM,CAOR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAW9D"}

package/dist/template.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Simple template utility for placeholder replacement.
+ * Replaces {{variable}} placeholders with provided values.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.replaceTemplate = replaceTemplate;
+exports.extractPlaceholders = extractPlaceholders;
+/**
+ * Replace template placeholders with values
+ *
+ * @param template - The template string with {{variable}} placeholders
+ * @param values - Object mapping variable names to their values
+ * @returns The template with placeholders replaced
+ */
+function replaceTemplate(template, values) {
+    return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+        if (Object.prototype.hasOwnProperty.call(values, key)) {
+            return values[key] ?? match;
+        }
+        return match;
+    });
+}
+/**
+ * Extract all placeholder names from a template
+ *
+ * @param template - The template string with {{variable}} placeholders
+ * @returns Array of unique placeholder names
+ */
+function extractPlaceholders(template) {
+    const matches = template.matchAll(/\{\{(\w+)\}\}/g);
+    const placeholders = new Set();
+    for (const match of matches) {
+        if (match[1]) {
+            placeholders.add(match[1]);
+        }
+    }
+    return Array.from(placeholders);
+}
+//# sourceMappingURL=template.js.map

package/dist/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AASH,0CAUC;AAQD,kDAWC;AApCD;;;;;;GAMG;AACH,SAAgB,eAAe,CAC7B,QAAgB,EAChB,MAA8B;IAE9B,OAAO,QAAQ,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,KAAK,EAAE,GAAW,EAAE,EAAE;QAC/D,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;YACtD,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC;QAC9B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,QAAgB;IAClD,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IACpD,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IAEvC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACb,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;AAClC,CAAC"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@hardlydifficult/text",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.31",
+    "typescript": "5.8.3",
+    "vitest": "1.6.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}