feat: add trimWhitespace option (#97)

Adds a `trimWhitespace` option which decides if we trim the leading and
trailing whitespace of the result.

Draft until the issue is accepting PRs

## PR Checklist

- [x] Addresses an existing open issue: fixes #96 
- [x] That issue was marked as [`status: accepting
prs`](https://github.com/dmnd/dedent/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22)
- [x] Steps in
[CONTRIBUTING.md](https://github.com/dmnd/dedent/blob/main/.github/CONTRIBUTING.md)
were taken

---------

Co-authored-by: Josh Goldberg ✨ <[email protected]>

Author: 43081j

README.md

@@ -135,6 +135,31 @@ dedent.withOptions({ escapeSpecialCharacters: true })`
 
 For more context, see [🚀 Feature: Add an option to disable special character escaping](https://github.com/dmnd/dedent/issues/63).
 
+### `trimWhitespace`
+
+By default, dedent will trim leading and trailing whitespace from the overall string.
+
+This can be disabled by setting `trimWhitespace: false`.
+
+```js
+import dedent from "dedent";
+
+// "hello!"
+dedent`
+  hello! 
+`;
+
+// "\nhello! \n"
+dedent.withOptions({ trimWhitespace: false })`
+  hello! 
+`;
+
+// "hello!"
+dedent.withOptions({ trimWhitespace: true })`
+  hello! 
+`;
+```
+
 ## License
 
 MIT

src/__snapshots__/dedent.test.ts.snap

@@ -96,6 +96,52 @@ exports[`dedent string tag character escapes with escapeSpecialCharacters undefi
 
 exports[`dedent string tag character escapes with escapeSpecialCharacters undefined opening braces 1`] = `"{"`;
 
+exports[`dedent with trimWhitespace false with leading whitespace 1`] = `
+"
+
+
+foo
+"
+`;
+
+exports[`dedent with trimWhitespace false with trailing whitespace 1`] = `
+"
+foo   
+bar   
+"
+`;
+
+exports[`dedent with trimWhitespace false without trailing whitespace 1`] = `
+"
+foo
+bar
+"
+`;
+
+exports[`dedent with trimWhitespace true with leading whitespace 1`] = `"foo"`;
+
+exports[`dedent with trimWhitespace true with trailing whitespace 1`] = `
+"foo   
+bar"
+`;
+
+exports[`dedent with trimWhitespace true without trailing whitespace 1`] = `
+"foo
+bar"
+`;
+
+exports[`dedent with trimWhitespace undefined with leading whitespace 1`] = `"foo"`;
+
+exports[`dedent with trimWhitespace undefined with trailing whitespace 1`] = `
+"foo   
+bar"
+`;
+
+exports[`dedent with trimWhitespace undefined without trailing whitespace 1`] = `
+"foo
+bar"
+`;
+
 exports[`dedent works with blank first line 1`] = `
 "Some text that I might want to indent:
 	* reasons

src/dedent.test.ts

@@ -152,6 +152,43 @@ describe("dedent", () => {
 		);
 	});
 
+	describe.each([undefined, false, true])(
+		"with trimWhitespace %s",
+		(trimWhitespace) => {
+			test("with trailing whitespace", () => {
+				expect(
+					dedent.withOptions({ trimWhitespace })(
+						`
+						foo---
+						bar---
+					`.replace(/-/g, " "),
+					),
+				).toMatchSnapshot();
+			});
+
+			test("without trailing whitespace", () => {
+				expect(
+					dedent.withOptions({ trimWhitespace })(
+						`
+						foo
+						bar
+					`.replace(/-/g, " "),
+					),
+				).toMatchSnapshot();
+			});
+
+			test("with leading whitespace", () => {
+				expect(
+					dedent.withOptions({ trimWhitespace })(`
+
+
+						foo
+					`),
+				).toMatchSnapshot();
+			});
+		},
+	);
+
 	describe("string tag character escapes", () => {
 		describe("default behavior", () => {
 			it("escapes backticks", () => {

src/dedent.ts

@@ -19,7 +19,10 @@ function createDedent(options: DedentOptions) {
 		...values: unknown[]
 	) {
 		const raw = typeof strings === "string" ? [strings] : strings.raw;
-		const { escapeSpecialCharacters = Array.isArray(strings) } = options;
+		const {
+			escapeSpecialCharacters = Array.isArray(strings),
+			trimWhitespace = true,
+		} = options;
 
 		// first, perform interpolation
 		let result = "";
@@ -69,9 +72,12 @@ function createDedent(options: DedentOptions) {
 		}
 
 		// dedent eats leading and trailing whitespace too
-		result = result.trim();
+		if (trimWhitespace) {
+			result = result.trim();
+		}
+
+		// handle escaped newlines at the end to ensure they don't get stripped too
 		if (escapeSpecialCharacters) {
-			// handle escaped newlines at the end to ensure they don't get stripped too
 			result = result.replace(/\\n/g, "\n");
 		}
 

src/types.ts

@@ -1,5 +1,6 @@
 export interface DedentOptions {
 	escapeSpecialCharacters?: boolean;
+	trimWhitespace?: boolean;
 }
 
 export interface Dedent {