@ls-stack/utils 3.19.0 → 3.20.0

package/docs/_media/modules.md

@@ -17,7 +17,7 @@
 - [conversions](conversions.md)
 - [createThrottleController](createThrottleController/README.md)
 - [debounce](debounce.md)
-- [dedent](dedent.md)
+- [dedent](dedent/README.md)
 - [deepEqual](deepEqual.md)
 - [enhancedMap](enhancedMap.md)
 - [exhaustiveMatch](exhaustiveMatch/README.md)

package/docs/dedent/-internal-.md

@@ -0,0 +1,17 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / [dedent](README.md) / \<internal\>
+
+# \<internal\>
+
+## Type Aliases
+
+### InterpolationValue
+
+```ts
+type InterpolationValue = string | number | boolean | null | undefined;
+```
+
+Defined in: [packages/utils/src/dedent.ts:30](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L30)

package/docs/dedent/README.md

@@ -0,0 +1,204 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / dedent
+
+# dedent
+
+## Modules
+
+- [\<internal\>](-internal-.md)
+
+## Interfaces
+
+### Dedent()
+
+Defined in: [packages/utils/src/dedent.ts:35](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L35)
+
+Dedent function interface that can be used both as a template tag and a regular function
+
+#### Call Signature
+
+```ts
+Dedent(literals): string;
+```
+
+Defined in: [packages/utils/src/dedent.ts:39](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L39)
+
+Dedent function interface that can be used both as a template tag and a regular function
+
+##### Parameters
+
+###### literals
+
+`string`
+
+##### Returns
+
+`string`
+
+#### Call Signature
+
+```ts
+Dedent(strings, ...values): string;
+```
+
+Defined in: [packages/utils/src/dedent.ts:43](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L43)
+
+Dedent function interface that can be used both as a template tag and a regular function
+
+##### Parameters
+
+###### strings
+
+`TemplateStringsArray`
+
+###### values
+
+...[`InterpolationValue`](-internal-.md#interpolationvalue)[]
+
+##### Returns
+
+`string`
+
+#### Properties
+
+##### withOptions
+
+```ts
+withOptions: CreateDedent;
+```
+
+Defined in: [packages/utils/src/dedent.ts:47](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L47)
+
+Create a new dedent function with custom options
+
+***
+
+### DedentOptions
+
+Defined in: [packages/utils/src/dedent.ts:4](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L4)
+
+Configuration options for the dedent function behavior
+
+#### Properties
+
+##### escapeSpecialCharacters?
+
+```ts
+optional escapeSpecialCharacters: boolean;
+```
+
+Defined in: [packages/utils/src/dedent.ts:10](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L10)
+
+Whether to process escape sequences like \n, `, \$, and {
+When true, allows using escaped characters in template literals
+
+###### Default
+
+```ts
+true for template literals, false for plain strings
+```
+
+##### identInterpolations?
+
+```ts
+optional identInterpolations: boolean;
+```
+
+Defined in: [packages/utils/src/dedent.ts:21](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L21)
+
+Whether to preserve relative indentation of interpolated multi-line values
+When true, multi-line interpolations are re-indented to match the surrounding context
+
+###### Default
+
+```ts
+true
+```
+
+##### showNullishOrFalseValues?
+
+```ts
+optional showNullishOrFalseValues: boolean;
+```
+
+Defined in: [packages/utils/src/dedent.ts:27](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L27)
+
+Whether to display nullish or false values (false, null, undefined) in interpolations
+When false, nullish or false values are skipped entirely
+
+###### Default
+
+```ts
+false
+```
+
+##### trimWhitespace?
+
+```ts
+optional trimWhitespace: boolean;
+```
+
+Defined in: [packages/utils/src/dedent.ts:15](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L15)
+
+Whether to trim leading and trailing whitespace from the final result
+
+###### Default
+
+```ts
+true
+```
+
+## Type Aliases
+
+### CreateDedent()
+
+```ts
+type CreateDedent = (options) => Dedent;
+```
+
+Defined in: [packages/utils/src/dedent.ts:53](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L53)
+
+Factory function type for creating dedent functions with custom options
+
+#### Parameters
+
+##### options
+
+[`DedentOptions`](#dedentoptions)
+
+#### Returns
+
+[`Dedent`](#dedent)
+
+## Variables
+
+### dedent
+
+```ts
+const dedent: Dedent;
+```
+
+Defined in: [packages/utils/src/dedent.ts:75](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L75)
+
+Remove common leading indentation from multi-line strings while preserving relative indentation.
+Can be used as a tagged template literal or called with a plain string.
+
+By default, it will dedent interpolated multi-line strings to match the surrounding context.
+And it will not show falsy values.
+
+#### Example
+
+```typescript
+const text = dedent`
+  function hello() {
+    console.log('world');
+  }
+`;
+// Result:
+"function hello() {
+  console.log('world');
+}"
+```

package/docs/modules.md

@@ -17,7 +17,7 @@
 - [conversions](conversions.md)
 - [createThrottleController](createThrottleController/README.md)
 - [debounce](debounce.md)
-- [dedent](dedent.md)
+- [dedent](dedent/README.md)
 - [deepEqual](deepEqual.md)
 - [enhancedMap](enhancedMap.md)
 - [exhaustiveMatch](exhaustiveMatch/README.md)

package/lib/dedent.cjs

@@ -23,7 +23,9 @@ __export(dedent_exports, {
   dedent: () => dedent
 });
 module.exports = __toCommonJS(dedent_exports);
-var dedent = createDedent({});
+var dedent = createDedent({
+  identInterpolations: true
+});
 function createDedent(options) {
   d.withOptions = (newOptions) => createDedent({ ...options, ...newOptions });
   return d;
@@ -31,7 +33,9 @@ function createDedent(options) {
     const raw = typeof strings === "string" ? [strings] : strings.raw;
     const {
       escapeSpecialCharacters = Array.isArray(strings),
-      trimWhitespace = true
+      trimWhitespace = true,
+      identInterpolations = true,
+      showNullishOrFalseValues = false
     } = options;
     let result = "";
     for (let i = 0; i < raw.length; i++) {
@@ -41,7 +45,24 @@ function createDedent(options) {
       }
       result += next;
       if (i < values.length) {
-        result += values[i];
+        let val = values[i];
+        if (!showNullishOrFalseValues && (val === false || val === null || val === void 0)) {
+          continue;
+        }
+        val = String(val);
+        if (identInterpolations && val.includes("\n")) {
+          let withIdent = val;
+          const currentIndent = getCurrentIndent(result);
+          if (currentIndent && withIdent) {
+            const lines2 = withIdent.split("\n");
+            withIdent = lines2.map((line, index) => {
+              return index === 0 || line === "" ? line : currentIndent + line;
+            }).join("\n");
+          }
+          result += withIdent;
+        } else {
+          result += val;
+        }
       }
     }
     const lines = result.split("\n");
@@ -70,6 +91,13 @@ function createDedent(options) {
     return result;
   }
 }
+function getCurrentIndent(str) {
+  const lines = str.split("\n");
+  const lastLine = lines[lines.length - 1];
+  if (!lastLine) return "";
+  const match = lastLine.match(/^(\s*)/);
+  return match ? match[1] : "";
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   dedent

package/lib/dedent.d.cts

@@ -1,13 +1,73 @@
+/**
+ * Configuration options for the dedent function behavior
+ */
 interface DedentOptions {
+    /**
+     * Whether to process escape sequences like \n, \`, \$, and \{
+     * When true, allows using escaped characters in template literals
+     * @default true for template literals, false for plain strings
+     */
     escapeSpecialCharacters?: boolean;
+    /**
+     * Whether to trim leading and trailing whitespace from the final result
+     * @default true
+     */
     trimWhitespace?: boolean;
+    /**
+     * Whether to preserve relative indentation of interpolated multi-line values
+     * When true, multi-line interpolations are re-indented to match the surrounding context
+     * @default true
+     */
+    identInterpolations?: boolean;
+    /**
+     * Whether to display nullish or false values (false, null, undefined) in interpolations
+     * When false, nullish or false values are skipped entirely
+     * @default false
+     */
+    showNullishOrFalseValues?: boolean;
 }
+type InterpolationValue = string | number | boolean | null | undefined;
+/**
+ * Dedent function interface that can be used both as a template tag and a regular function
+ */
 interface Dedent {
+    /**
+     * Process a plain string to remove common indentation
+     */
     (literals: string): string;
-    (strings: TemplateStringsArray, ...values: unknown[]): string;
+    /**
+     * Process a template literal to remove common indentation while handling interpolations
+     */
+    (strings: TemplateStringsArray, ...values: InterpolationValue[]): string;
+    /**
+     * Create a new dedent function with custom options
+     */
     withOptions: CreateDedent;
 }
+/**
+ * Factory function type for creating dedent functions with custom options
+ */
 type CreateDedent = (options: DedentOptions) => Dedent;
+/**
+ * Remove common leading indentation from multi-line strings while preserving relative indentation.
+ * Can be used as a tagged template literal or called with a plain string.
+ *
+ * By default, it will dedent interpolated multi-line strings to match the surrounding context.
+ * And it will not show falsy values.
+ *
+ * @example
+ * ```typescript
+ * const text = dedent`
+ *   function hello() {
+ *     console.log('world');
+ *   }
+ * `;
+ * // Result:
+ * "function hello() {
+ *   console.log('world');
+ * }"
+ * ```
+ */
 declare const dedent: Dedent;
 
 export { type CreateDedent, type Dedent, type DedentOptions, dedent };

package/lib/dedent.d.ts

@@ -1,13 +1,73 @@
+/**
+ * Configuration options for the dedent function behavior
+ */
 interface DedentOptions {
+    /**
+     * Whether to process escape sequences like \n, \`, \$, and \{
+     * When true, allows using escaped characters in template literals
+     * @default true for template literals, false for plain strings
+     */
     escapeSpecialCharacters?: boolean;
+    /**
+     * Whether to trim leading and trailing whitespace from the final result
+     * @default true
+     */
     trimWhitespace?: boolean;
+    /**
+     * Whether to preserve relative indentation of interpolated multi-line values
+     * When true, multi-line interpolations are re-indented to match the surrounding context
+     * @default true
+     */
+    identInterpolations?: boolean;
+    /**
+     * Whether to display nullish or false values (false, null, undefined) in interpolations
+     * When false, nullish or false values are skipped entirely
+     * @default false
+     */
+    showNullishOrFalseValues?: boolean;
 }
+type InterpolationValue = string | number | boolean | null | undefined;
+/**
+ * Dedent function interface that can be used both as a template tag and a regular function
+ */
 interface Dedent {
+    /**
+     * Process a plain string to remove common indentation
+     */
     (literals: string): string;
-    (strings: TemplateStringsArray, ...values: unknown[]): string;
+    /**
+     * Process a template literal to remove common indentation while handling interpolations
+     */
+    (strings: TemplateStringsArray, ...values: InterpolationValue[]): string;
+    /**
+     * Create a new dedent function with custom options
+     */
     withOptions: CreateDedent;
 }
+/**
+ * Factory function type for creating dedent functions with custom options
+ */
 type CreateDedent = (options: DedentOptions) => Dedent;
+/**
+ * Remove common leading indentation from multi-line strings while preserving relative indentation.
+ * Can be used as a tagged template literal or called with a plain string.
+ *
+ * By default, it will dedent interpolated multi-line strings to match the surrounding context.
+ * And it will not show falsy values.
+ *
+ * @example
+ * ```typescript
+ * const text = dedent`
+ *   function hello() {
+ *     console.log('world');
+ *   }
+ * `;
+ * // Result:
+ * "function hello() {
+ *   console.log('world');
+ * }"
+ * ```
+ */
 declare const dedent: Dedent;
 
 export { type CreateDedent, type Dedent, type DedentOptions, dedent };

package/lib/dedent.js

@@ -1,5 +1,7 @@
 // src/dedent.ts
-var dedent = createDedent({});
+var dedent = createDedent({
+  identInterpolations: true
+});
 function createDedent(options) {
   d.withOptions = (newOptions) => createDedent({ ...options, ...newOptions });
   return d;
@@ -7,7 +9,9 @@ function createDedent(options) {
     const raw = typeof strings === "string" ? [strings] : strings.raw;
     const {
       escapeSpecialCharacters = Array.isArray(strings),
-      trimWhitespace = true
+      trimWhitespace = true,
+      identInterpolations = true,
+      showNullishOrFalseValues = false
     } = options;
     let result = "";
     for (let i = 0; i < raw.length; i++) {
@@ -17,7 +21,24 @@ function createDedent(options) {
       }
       result += next;
       if (i < values.length) {
-        result += values[i];
+        let val = values[i];
+        if (!showNullishOrFalseValues && (val === false || val === null || val === void 0)) {
+          continue;
+        }
+        val = String(val);
+        if (identInterpolations && val.includes("\n")) {
+          let withIdent = val;
+          const currentIndent = getCurrentIndent(result);
+          if (currentIndent && withIdent) {
+            const lines2 = withIdent.split("\n");
+            withIdent = lines2.map((line, index) => {
+              return index === 0 || line === "" ? line : currentIndent + line;
+            }).join("\n");
+          }
+          result += withIdent;
+        } else {
+          result += val;
+        }
       }
     }
     const lines = result.split("\n");
@@ -46,6 +67,13 @@ function createDedent(options) {
     return result;
   }
 }
+function getCurrentIndent(str) {
+  const lines = str.split("\n");
+  const lastLine = lines[lines.length - 1];
+  if (!lastLine) return "";
+  const match = lastLine.match(/^(\s*)/);
+  return match ? match[1] : "";
+}
 export {
   dedent
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ls-stack/utils",
   "description": "Universal TypeScript utilities for browser and Node.js",
-  "version": "3.19.0",
+  "version": "3.20.0",
   "license": "MIT",
   "files": [
     "lib",

package/docs/dedent.md

@@ -1,117 +0,0 @@
-[**@ls-stack/utils**](README.md)
-
-***
-
-[@ls-stack/utils](modules.md) / dedent
-
-# dedent
-
-## Interfaces
-
-### Dedent()
-
-Defined in: [packages/utils/src/dedent.ts:6](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L6)
-
-#### Call Signature
-
-```ts
-Dedent(literals): string;
-```
-
-Defined in: [packages/utils/src/dedent.ts:7](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L7)
-
-##### Parameters
-
-###### literals
-
-`string`
-
-##### Returns
-
-`string`
-
-#### Call Signature
-
-```ts
-Dedent(strings, ...values): string;
-```
-
-Defined in: [packages/utils/src/dedent.ts:8](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L8)
-
-##### Parameters
-
-###### strings
-
-`TemplateStringsArray`
-
-###### values
-
-...`unknown`[]
-
-##### Returns
-
-`string`
-
-#### Properties
-
-##### withOptions
-
-```ts
-withOptions: CreateDedent;
-```
-
-Defined in: [packages/utils/src/dedent.ts:9](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L9)
-
-***
-
-### DedentOptions
-
-Defined in: [packages/utils/src/dedent.ts:1](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L1)
-
-#### Properties
-
-##### escapeSpecialCharacters?
-
-```ts
-optional escapeSpecialCharacters: boolean;
-```
-
-Defined in: [packages/utils/src/dedent.ts:2](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L2)
-
-##### trimWhitespace?
-
-```ts
-optional trimWhitespace: boolean;
-```
-
-Defined in: [packages/utils/src/dedent.ts:3](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L3)
-
-## Type Aliases
-
-### CreateDedent()
-
-```ts
-type CreateDedent = (options) => Dedent;
-```
-
-Defined in: [packages/utils/src/dedent.ts:12](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L12)
-
-#### Parameters
-
-##### options
-
-[`DedentOptions`](#dedentoptions)
-
-#### Returns
-
-[`Dedent`](#dedent)
-
-## Variables
-
-### dedent
-
-```ts
-const dedent: Dedent;
-```
-
-Defined in: [packages/utils/src/dedent.ts:14](https://github.com/lucasols/utils/blob/main/packages/utils/src/dedent.ts#L14)