@hardlydifficult/text 1.0.10 → 1.0.12

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/text
 
-Text utilities for error formatting, template replacement, chunking, and line numbering.
+Text utilities for error formatting, template replacement, chunking, slugification, duration formatting, YAML/JSON conversion, linkification, and line numbering.
 
 ## Installation
 
@@ -8,25 +8,35 @@ Text utilities for error formatting, template replacement, chunking, and line nu
 npm install @hardlydifficult/text
 ```
 
-## API
+## Usage
+
+```typescript
+import * as text from "@hardlydifficult/text";
+
+// Quick example
+const output = text.replaceTemplate("Hello {{name}}!", { name: "World" });
+console.log(output); // "Hello World!"
+```
+
+## Error Handling
 
 ### `getErrorMessage(err: unknown): string`
 
-Extract a message string from an unknown error. Returns `err.message` for `Error` instances, `String(err)` otherwise.
+Extract a message string from an unknown error.
 
 ```typescript
 import { getErrorMessage } from "@hardlydifficult/text";
 
 try {
-  await riskyOperation();
+  throw new Error("Something went wrong");
 } catch (err) {
-  console.error(getErrorMessage(err));
+  console.error(getErrorMessage(err)); // "Something went wrong"
 }
 ```
 
 ### `formatError(err: unknown, context?: string): string`
 
-Format an error for user-facing output. Prepends an optional context prefix.
+Format an error with an optional context prefix.
 
 ```typescript
 import { formatError } from "@hardlydifficult/text";
@@ -37,11 +47,19 @@ 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.
+Format an error for logging. Returns `err.message` for `Error` instances, `String(err)` otherwise.
+
+```typescript
+import { formatErrorForLog } from "@hardlydifficult/text";
+
+formatErrorForLog(new Error("Database error")); // "Database error"
+```
+
+## Template Replacement
 
 ### `replaceTemplate(template: string, values: Record<string, string>): string`
 
-Replace `{{variable}}` placeholders with provided values. Unmatched placeholders are left as-is.
+Replace `{{variable}}` placeholders with provided values.
 
 ```typescript
 import { replaceTemplate } from "@hardlydifficult/text";
@@ -55,7 +73,7 @@ replaceTemplate("Hello {{name}}, welcome to {{place}}!", {
 
 ### `extractPlaceholders(template: string): string[]`
 
-Extract all unique placeholder names from a template.
+Extract all unique placeholder names from a template string.
 
 ```typescript
 import { extractPlaceholders } from "@hardlydifficult/text";
@@ -63,33 +81,49 @@ import { extractPlaceholders } from "@hardlydifficult/text";
 extractPlaceholders("{{name}} is in {{place}}"); // ["name", "place"]
 ```
 
+## Text Processing
+
 ### `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.
+Split text into chunks of at most `maxLength` characters, preferring line breaks and spaces.
 
 ```typescript
 import { chunkText } from "@hardlydifficult/text";
 
-const chunks = chunkText(longMessage, 2000);
-for (const chunk of chunks) {
-  await channel.send(chunk);
-}
+const text = "Line 1\nLine 2\nThis is a very long line that needs to be chunked.";
+const chunks = chunkText(text, 20);
+// ["Line 1\nLine 2", "This is a very", "long line that", "needs to be", "chunked."]
 ```
 
 ### `slugify(input: string, maxLength?: number): string`
 
-Convert a string to a URL/filename-safe slug. Lowercases, replaces non-alphanumeric runs with hyphens, truncates at word boundaries.
+Convert a string to a URL/filename-safe slug.
 
 ```typescript
 import { slugify } from "@hardlydifficult/text";
 
 slugify("My Feature Name!"); // "my-feature-name"
 slugify("My Feature Name!", 10); // "my-feature"
+slugify("  spaces & symbols!  "); // "spaces-symbols"
+```
+
+### `formatWithLineNumbers(content: string, startLine?: number): string`
+
+Format text content with right-aligned line numbers.
+
+```typescript
+import { formatWithLineNumbers } from "@hardlydifficult/text";
+
+formatWithLineNumbers("foo\nbar\nbaz");
+// " 1: foo\n 2: bar\n 3: baz"
+
+formatWithLineNumbers("hello\nworld", 10);
+// "10: hello\n11: world"
 ```
 
 ### `formatDuration(ms: number): string`
 
-Format milliseconds as a short human-readable duration. Shows at most two units, skipping trailing zeros.
+Format milliseconds as a human-readable duration string.
 
 ```typescript
 import { formatDuration } from "@hardlydifficult/text";
@@ -100,9 +134,11 @@ formatDuration(500);       // "<1s"
 formatDuration(90_000_000); // "1d 1h"
 ```
 
-### `convertFormat(content: string, to: TextFormat): string`
+## Format Conversion
 
-Convert between JSON and YAML string formats. Auto-detects the input format and serializes to the requested output format.
+### `convertFormat(content: string, to: "json" | "yaml"): string`
+
+Convert between JSON and YAML string formats with automatic input detection.
 
 ```typescript
 import { convertFormat } from "@hardlydifficult/text";
@@ -120,74 +156,72 @@ convertFormat("name: Alice\nage: 30", "json");
 // }
 ```
 
-The function tries to parse as JSON first, then falls back to YAML. Returns pretty-printed JSON with 2-space indent or clean YAML. Throws a descriptive error if the input is neither valid JSON nor YAML.
-
-### `formatWithLineNumbers(content: string, startLine?: number): string`
+### `formatYaml(data: any): string`
 
-Format text content with right-aligned line numbers. Each line is prefixed with its line number, padded to align properly based on the maximum line number.
+Serialize data to clean YAML, using block literals for long strings containing colons.
 
 ```typescript
-import { formatWithLineNumbers } from "@hardlydifficult/text";
+import { formatYaml } from "@hardlydifficult/text";
 
-// Default: starts at line 1
-formatWithLineNumbers("foo\nbar\nbaz");
-// 1: foo
-// 2: bar
-// 3: baz
+formatYaml({ message: "Hello: World" });
+// "message: >\n  Hello: World"
+```
 
-// Custom starting line for displaying file ranges
-formatWithLineNumbers("hello\nworld", 10);
-// 10: hello
-// 11: world
+### `healYaml(dirtyYaml: string): string`
 
-// Proper alignment for larger line numbers
-formatWithLineNumbers("line 1\nline 2\n...\nline 100", 98);
-//  98: line 1
-//  99: line 2
-// 100: ...
-// 101: line 100
+Clean malformed YAML by stripping code fences and quoting problematic scalars containing colons.
+
+```typescript
+import { healYaml } from "@hardlydifficult/text";
+
+healYaml('message: "Hello: World"'); // "message: >\n  Hello: World"
 ```
 
-This is useful for displaying code snippets, file contents, or log output with line numbers for reference.
+## Link Generation
 
-### `createLinker(rules?)`
+### `createLinker(rules?: LinkRule[]): { linkText(text: string, options?: LinkOptions): string; apply: typeof linkText }`
 
-Create a reusable linker that turns matched text patterns into platform-specific links.
+Create a configurable linker to transform text patterns into platform-specific links.
 
 Supports:
-
-- plain strings
-- idempotent re-runs (won't double-link existing linked text)
-- skipping code spans/backticks and existing links by default
-- deterministic conflict handling (priority, then longest match, then rule order)
+- Plain strings
+- Idempotent re-runs
+- Automatic skipping of code spans and existing links
+- Deterministic conflict resolution (priority, then longest match, then rule order)
 
 ```typescript
 import { createLinker } from "@hardlydifficult/text";
 
 const linker = createLinker()
   .linear("fairmint")
-  .githubPr("Fairmint/api")
-  .custom(/\bINC-\d+\b/g, ({ match }) => `https://incident.io/${match}`);
+  .githubPr("Fairmint/api");
 
-const slack = linker.linkText("Fix ENG-533 and PR#42", { format: "slack" });
+linker.linkText("Fix ENG-533 and PR#42", { format: "slack" });
 // "Fix <https://linear.app/fairmint/issue/ENG-533|ENG-533> and <https://github.com/Fairmint/api/pull/42|PR#42>"
+
+linker.linkText("Fix ENG-533 and PR#42", { format: "markdown" });
+// "[ENG-533](https://linear.app/fairmint/issue/ENG-533) and [PR#42](https://github.com/Fairmint/api/pull/42)"
 ```
 
-You can also pass rules up front:
+Supported formats: `slack` (`<url|text>`), `markdown`/`discord` (`[text](url)`), `plaintext` (raw URL).
+
+## File Tree Rendering
+
+### `buildFileTree(files: string[], options?: FileTreeOptions): string`
+
+Build and render a hierarchical file tree with depth-based truncation and directory collapsing.
 
 ```typescript
-const linker = createLinker([
-  {
-    pattern: /\b([A-Z]{2,6}-\d+)\b/g,
-    href: "https://linear.app/fairmint/issue/$1",
-  },
-]);
-```
+import { buildFileTree } from "@hardlydifficult/text";
 
-Formats:
+const files = [
+  "src/index.ts",
+  "src/utils.ts",
+  "src/components/Button.tsx",
+];
 
-- `slack` → `<url|text>`
-- `markdown` / `discord` → `[text](url)`
-- `plaintext` → raw `url`
+buildFileTree(files);
+// "src/\n├── index.ts\n├── utils.ts\n└── components/\n   └── Button.tsx"
+```
 
-`linker.apply(text, options)` is an alias of `linker.linkText(text, options)`.
+Options include `maxDepth`, `maxDirectories`, and `collapseDirectories` for controlling tree rendering behavior.

package/dist/formatYaml.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Serialize data to clean YAML with minimal quoting.
+ *
+ * Long strings containing `: ` are rendered as block-literal (`|`) scalars
+ * instead of double-quoted strings, improving readability for descriptive text.
+ * Short strings, numbers, booleans, and other values use default styling.
+ */
+export declare function formatYaml(data: unknown): string;
+//# sourceMappingURL=formatYaml.d.ts.map

package/dist/formatYaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatYaml.d.ts","sourceRoot":"","sources":["../src/formatYaml.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAgBhD"}

package/dist/formatYaml.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatYaml = formatYaml;
+const yaml_1 = require("yaml");
+/**
+ * Serialize data to clean YAML with minimal quoting.
+ *
+ * Long strings containing `: ` are rendered as block-literal (`|`) scalars
+ * instead of double-quoted strings, improving readability for descriptive text.
+ * Short strings, numbers, booleans, and other values use default styling.
+ */
+function formatYaml(data) {
+    const doc = new yaml_1.Document(data);
+    (0, yaml_1.visit)(doc, {
+        Scalar(_key, node) {
+            if (typeof node.value === "string" &&
+                node.value.includes(": ") &&
+                node.value.length > 60) {
+                node.type = yaml_1.Scalar.BLOCK_LITERAL;
+            }
+        },
+    });
+    return doc.toString({ lineWidth: 0 });
+}
+//# sourceMappingURL=formatYaml.js.map

package/dist/formatYaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatYaml.js","sourceRoot":"","sources":["../src/formatYaml.ts"],"names":[],"mappings":";;AASA,gCAgBC;AAzBD,+BAA+C;AAE/C;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,IAAa;IACtC,MAAM,GAAG,GAAG,IAAI,eAAQ,CAAC,IAAI,CAAC,CAAC;IAE/B,IAAA,YAAK,EAAC,GAAG,EAAE;QACT,MAAM,CAAC,IAAI,EAAE,IAAI;YACf,IACE,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;gBAC9B,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;gBACzB,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,EAAE,EACtB,CAAC;gBACD,IAAI,CAAC,IAAI,GAAG,aAAM,CAAC,aAAa,CAAC;YACnC,CAAC;QACH,CAAC;KACF,CAAC,CAAC;IAEH,OAAO,GAAG,CAAC,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;AACxC,CAAC"}

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export type { BuildTreeOptions } from "./buildFileTree.js";
 export { convertFormat } from "./convertFormat.js";
 export type { TextFormat } from "./convertFormat.js";
 export { formatWithLineNumbers } from "./formatWithLineNumbers.js";
+export { formatYaml } from "./formatYaml.js";
 export { healYaml } from "./healYaml.js";
 export { Linker, createLinker, type LinkRule, type LinkHrefBuilder, type LinkMatchContext, type LinkerApplyOptions, type LinkerPlatform, } from "./linker.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,MAAM,EACN,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC"}
+{"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;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,MAAM,EACN,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createLinker = exports.Linker = exports.healYaml = exports.formatWithLineNumbers = exports.convertFormat = exports.FILE_TREE_DEFAULTS = exports.buildFileTree = exports.formatDuration = exports.slugify = exports.chunkText = exports.extractPlaceholders = exports.replaceTemplate = exports.formatErrorForLog = exports.formatError = exports.getErrorMessage = void 0;
+exports.createLinker = exports.Linker = exports.healYaml = exports.formatYaml = exports.formatWithLineNumbers = exports.convertFormat = exports.FILE_TREE_DEFAULTS = exports.buildFileTree = exports.formatDuration = exports.slugify = 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; } });
@@ -21,6 +21,8 @@ var convertFormat_js_1 = require("./convertFormat.js");
 Object.defineProperty(exports, "convertFormat", { enumerable: true, get: function () { return convertFormat_js_1.convertFormat; } });
 var formatWithLineNumbers_js_1 = require("./formatWithLineNumbers.js");
 Object.defineProperty(exports, "formatWithLineNumbers", { enumerable: true, get: function () { return formatWithLineNumbers_js_1.formatWithLineNumbers; } });
+var formatYaml_js_1 = require("./formatYaml.js");
+Object.defineProperty(exports, "formatYaml", { enumerable: true, get: function () { return formatYaml_js_1.formatYaml; } });
 var healYaml_js_1 = require("./healYaml.js");
 Object.defineProperty(exports, "healYaml", { enumerable: true, get: function () { return healYaml_js_1.healYaml; } });
 var linker_js_1 = require("./linker.js");

package/dist/index.js.map

@@ -1 +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;AAClB,2CAAuC;AAA9B,qGAAA,OAAO,OAAA;AAChB,yDAAqD;AAA5C,mHAAA,cAAc,OAAA;AACvB,uDAAuE;AAA9D,iHAAA,aAAa,OAAA;AAAE,sHAAA,kBAAkB,OAAA;AAE1C,uDAAmD;AAA1C,iHAAA,aAAa,OAAA;AAEtB,uEAAmE;AAA1D,iIAAA,qBAAqB,OAAA;AAC9B,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA;AACjB,yCAQqB;AAPnB,mGAAA,MAAM,OAAA;AACN,yGAAA,YAAY,OAAA"}
+{"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;AAClB,2CAAuC;AAA9B,qGAAA,OAAO,OAAA;AAChB,yDAAqD;AAA5C,mHAAA,cAAc,OAAA;AACvB,uDAAuE;AAA9D,iHAAA,aAAa,OAAA;AAAE,sHAAA,kBAAkB,OAAA;AAE1C,uDAAmD;AAA1C,iHAAA,aAAa,OAAA;AAEtB,uEAAmE;AAA1D,iIAAA,qBAAqB,OAAA;AAC9B,iDAA6C;AAApC,2GAAA,UAAU,OAAA;AACnB,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA;AACjB,yCAQqB;AAPnB,mGAAA,MAAM,OAAA;AACN,yGAAA,YAAY,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/text",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [