@synstack/text 1.1.9 → 1.2.1

package/README.md

@@ -4,9 +4,6 @@
 
 This is a strongly opinionated implementation of string templating. It's basically JSX for text and solves many quirks of string interpolation and formatting.
 
-> [!WARNING]
-> This package is included in the [@synstack/synscript](https://github.com/pAIrprogioio/synscript) package. It is not recommended to install both packages at the same time.
-
 ## What is it for ?
 
 Turns this:

package/dist/text.index.cjs

@@ -59,8 +59,10 @@ var Text = class _Text {
         const value = values2[i];
         let wrappedValue = "";
         if (Array.isArray(value)) {
-          wrappedValue = value.filter((inner) => inner !== null || inner !== void 0).map(_Text.wrapValue).join(this._options.joinString);
-        } else {
+          wrappedValue = value.filter(
+            (inner) => inner !== null && inner !== void 0 && inner !== false
+          ).map(_Text.wrapValue).join(this._options.joinString);
+        } else if (value !== null && value !== void 0 && value !== false) {
           wrappedValue = _Text.wrapValue(value);
         }
         const nextString = template[i + 1];
@@ -72,7 +74,7 @@ var Text = class _Text {
     }).$;
   }
   static wrapValue(value) {
-    if (value === null || value === void 0) return "";
+    if (value === null || value === void 0 || value === false) return "";
     if (typeof value === "object") {
       if (!Object.hasOwn(value, "type")) {
         throw new Error(

package/dist/text.index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/text.index.ts","../src/text.lib.ts"],"sourcesContent":["export * from \"./text.bundle.ts\";\nexport { TextParseExtraItemException } from \"./text.lib.ts\";\nexport type { Text } from \"./text.lib.ts\";\n","import { json } from \"@synstack/json\";\nimport { resolvable, type Resolvable } from \"@synstack/resolved\";\nimport { callable, type CallableResolvable } from \"@synstack/resolved/callable\";\nimport { str } from \"@synstack/str\";\nimport { type MaybeArray } from \"../../shared/src/ts.utils.ts\";\n\nexport class Text {\n  private static EXTRA_OBJECT_PREFIX = \"%STR_EXTRA%\";\n  private static EXTRA_OBJECT_SUFFIX = \"%!STR_EXTRA%\";\n\n  private readonly _options: {\n    joinString: string;\n  };\n\n  private constructor(options: Text.Options = {}) {\n    this._options = {\n      joinString: options.joinString ?? \"\\n\",\n    };\n  }\n\n  public static options(this: void, config: Text.Options = {}) {\n    return new Text(config);\n  }\n\n  public options(config: Text.Options) {\n    return new Text({ ...this._options, ...config });\n  }\n\n  public static t<T extends Array<Text.TemplateValue.Base>>(\n    this: void,\n    template: TemplateStringsArray,\n    ...values: T\n  ): Text.Return<T> {\n    return Text.options().t(template, ...values);\n  }\n\n  public t<T extends Array<Text.TemplateValue.Base>>(\n    template: TemplateStringsArray,\n    ...values: T\n  ): Text.Return<T> {\n    // @ts-expect-error - Of course the default value is \"\"\n    if (template.length === 0) return \"\";\n\n    const resolvedValues = callable.resolveNested(values);\n    return resolvable.pipe(resolvedValues)._((values) => {\n      let text = template[0];\n\n      for (let i = 0; i < values.length; i++) {\n        const value = values[i];\n        let wrappedValue = \"\";\n\n        if (Array.isArray(value)) {\n          wrappedValue = value\n            .filter((inner) => inner !== null || inner !== undefined)\n            .map(Text.wrapValue)\n            .join(this._options.joinString);\n        } else {\n          wrappedValue = Text.wrapValue(value);\n        }\n        const nextString = template[i + 1];\n        const lastLine = str(text).lastLine();\n        const indentation = lastLine.isEmpty()\n          ? lastLine.leadingSpacesCount()\n          : 0;\n        text =\n          str(text).chopEnd(indentation).toString() +\n          str(wrappedValue).indent(indentation).toString() +\n          nextString;\n      }\n\n      return str(text)\n        .chopEmptyLinesStart()\n        .trimEnd()\n        .dedent()\n        .trimEmptyLines()\n        .chopRepeatNewlines(2)\n        .toString() as string & {\n        __extra: Text.ExtraObject.Infer<T>;\n      };\n    }).$ as Text.Return<T>;\n  }\n\n  private static wrapValue(this: void, value: Text.Value.Base) {\n    if (value === null || value === undefined) return \"\";\n    if (typeof value === \"object\") {\n      if (!Object.hasOwn(value, \"type\")) {\n        throw new Error(\n          'Text templating only supports objects with a \"type\" property',\n        );\n      }\n      return `${Text.EXTRA_OBJECT_PREFIX}${JSON.stringify(value)}${\n        Text.EXTRA_OBJECT_SUFFIX\n      }`;\n    }\n    return value;\n  }\n\n  public static parse<E extends Text.ExtraObject.Base>(\n    this: void,\n    text: Text.String<E>,\n  ): Array<string | E> {\n    const regex = new RegExp(\n      Text.EXTRA_OBJECT_PREFIX + \"(.*?)\" + Text.EXTRA_OBJECT_SUFFIX,\n      \"g\",\n    );\n    const parts: Array<string | E> = [];\n    let lastIndex = 0;\n    let match;\n\n    while ((match = regex.exec(text)) !== null) {\n      // Add the text before the match\n      if (match.index > lastIndex) {\n        parts.push(text.slice(lastIndex, match.index));\n      }\n\n      // Parse and add the JSON object\n      try {\n        const jsonObject = json.deserialize<E>(match[1]);\n        parts.push(jsonObject);\n      } catch (error) {\n        throw new TextParseExtraItemException(match[1], error);\n      }\n\n      lastIndex = regex.lastIndex;\n    }\n\n    // Add any remaining text after the last match\n    if (lastIndex < text.length) {\n      parts.push(text.slice(lastIndex));\n    }\n\n    return parts;\n  }\n}\n\nexport declare namespace Text {\n  export type Options = {\n    joinString?: string;\n  };\n\n  export type OptionalString = string | undefined | null;\n\n  export type String<TExtraObject extends Text.ExtraObject.Base = never> =\n    string & {\n      __extra: TExtraObject;\n    };\n\n  export namespace ExtraObject {\n    export type Base = { type: string };\n\n    type InferExtraObjectValue<T> = T extends Text.OptionalString ? never : T;\n    type InferExtraObjectCallableResolvable<T> = InferExtraObjectValue<\n      CallableResolvable.Infer<T>\n    >;\n    type InferExtraArrayable<T> =\n      T extends Array<any>\n        ? { [K in keyof T]: InferExtraObjectCallableResolvable<T[K]> }[number]\n        : InferExtraObjectCallableResolvable<T>;\n\n    export type Infer<T extends any[]> = {\n      // Check if it's an array\n      [K in keyof T]: InferExtraArrayable<T[K]>;\n    }[number];\n  }\n\n  export type Value<TExtraObject extends Text.ExtraObject.Base = never> =\n    | Text.OptionalString\n    | TExtraObject;\n\n  export namespace Value {\n    export type Base = OptionalString | ExtraObject.Base;\n  }\n\n  export type TemplateValue<\n    TExtraObject extends Text.ExtraObject.Base = never,\n  > = CallableResolvable.MaybeArray<Value<TExtraObject>>;\n\n  export namespace TemplateValue {\n    export type Base = TemplateValue<ExtraObject.Base>;\n\n    export type Resolved<TExtraObject extends Text.ExtraObject.Base = never> =\n      MaybeArray<Value<TExtraObject>>;\n    export namespace Resolved {\n      export type Base = Resolved<ExtraObject.Base>;\n    }\n  }\n\n  export type Return<T extends Array<Text.TemplateValue.Base>> =\n    true extends CallableResolvable.MaybeArray.ArrayOf.IsPromise<T>\n      ? Promise<string & { __extra: ExtraObject.Infer<T> }>\n      : string & { __extra: ExtraObject.Infer<T> };\n}\n\nexport class TextParseExtraItemException extends Error {\n  constructor(itemString: string, cause: any) {\n    super(\n      `\nFailed to parse extra item serialized value\n\nValue:\n${str(itemString).indent(2).toString()}\n\nCause:\n${str(cause instanceof Error ? cause.message : (cause as string))\n  .indent(2)\n  .toString()}\n\n`.trimStart(),\n      { cause },\n    );\n  }\n}\n\n/**\n * @param condition - The condition to check, can be:\n * - primitive values\n * - promise of a primitive value\n * @returns The result of the template string if the resolved value is true, otherwise an empty string\n *\n * @example\n * ```ts\n * const text = tIf(true)`Hello World`;\n * assert.equal(text, \"Hello World\");\n * ```\n */\nexport const tIf =\n  <CHECK extends Resolvable<any>>(condition: CHECK) =>\n  <TValues extends Array<Text.TemplateValue.Base>>(\n    template: TemplateStringsArray,\n    ...args: TValues\n  ): CHECK extends Promise<any>\n    ? // CHECK is a promise\n      Text.Return<TValues> extends Promise<any>\n      ? // Text.Return<TValues> is a promise as well, so we don't need to wrap it in a promise\n        Text.Return<TValues>\n      : // Text.Return<TValues> is not a promise, so we need to wrap it in a promise\n        Promise<Text.Return<TValues>>\n    : // Neither are promises, so we don't need to wrap the return value in a promise\n      Text.Return<TValues> => {\n    if (!condition) return \"\" as any;\n\n    if (condition instanceof Promise)\n      return condition.then((c) =>\n        c ? t(template, ...args) : (\"\" as any),\n      ) as any;\n\n    return t(template, ...args) as any;\n  };\n\n/**\n * Serializes and formats a template string with values into a single string while preserving extra values typings\n * @returns The serialized and formatted string\n *\n * @features\n * - Promises even nested in arrays are resolved in parallel\n * - Array values are joined with a newline\n * - Text is trimmed\n * - Base indentation is removed\n * - Nested indentation is preserved for multi-line values\n * - Returned value is either a string or a promise of a string based on interpolated values\n * - Extra values are serialized and added to the returned value type\n *\n * @example\n * For the following template:\n * ```ts\n * const text: string = t`\n *     Hello\n *       ${\"- Item 1\\n- Item 2\"}\n *     World\n * `;\n * ```\n *\n * The output will be:\n * ```plain\n * Hello\n *   - Item 1\n *   - Item 2\n * World\n * ```\n */\nexport const t = Text.t;\n\n/**\n * Deserializes a serialized string with extra values\n *\n * @param text - The text string to parse\n * @returns Array of strings and extra objects\n *\n * @example\n * ```ts\n * const text = t`Hello ${{type: \"item\", value: \"World\"}}`;\n * assert.equal(tParse(text), [\"Hello\", { type: \"item\", value: \"World\" }]);\n * ```\n */\nexport const tParse = Text.parse;\n"],"mappings":"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","names":["values"]}
+{"version":3,"sources":["../src/text.index.ts","../src/text.lib.ts"],"sourcesContent":["export * from \"./text.bundle.ts\";\nexport { TextParseExtraItemException } from \"./text.lib.ts\";\nexport type { Text } from \"./text.lib.ts\";\n","import { json } from \"@synstack/json\";\nimport { resolvable, type Resolvable } from \"@synstack/resolved\";\nimport { callable, type CallableResolvable } from \"@synstack/resolved/callable\";\nimport { str } from \"@synstack/str\";\nimport { type MaybeArray } from \"../../shared/src/ts.utils.ts\";\n\nexport class Text {\n  private static EXTRA_OBJECT_PREFIX = \"%STR_EXTRA%\";\n  private static EXTRA_OBJECT_SUFFIX = \"%!STR_EXTRA%\";\n\n  private readonly _options: {\n    joinString: string;\n  };\n\n  private constructor(options: Text.Options = {}) {\n    this._options = {\n      joinString: options.joinString ?? \"\\n\",\n    };\n  }\n\n  public static options(this: void, config: Text.Options = {}) {\n    return new Text(config);\n  }\n\n  public options(config: Text.Options) {\n    return new Text({ ...this._options, ...config });\n  }\n\n  public static t<T extends Array<Text.TemplateValue.Base>>(\n    this: void,\n    template: TemplateStringsArray,\n    ...values: T\n  ): Text.Return<T> {\n    return Text.options().t(template, ...values);\n  }\n\n  public t<T extends Array<Text.TemplateValue.Base>>(\n    template: TemplateStringsArray,\n    ...values: T\n  ): Text.Return<T> {\n    // @ts-expect-error - Of course the default value is \"\"\n    if (template.length === 0) return \"\";\n\n    const resolvedValues = callable.resolveNested(values);\n    return resolvable.pipe(resolvedValues)._((values) => {\n      let text = template[0];\n\n      for (let i = 0; i < values.length; i++) {\n        const value = values[i];\n        let wrappedValue = \"\";\n\n        if (Array.isArray(value)) {\n          wrappedValue = value\n            .filter(\n              (inner) =>\n                inner !== null && inner !== undefined && inner !== false,\n            )\n            .map(Text.wrapValue)\n            .join(this._options.joinString);\n        } else if (value !== null && value !== undefined && value !== false) {\n          wrappedValue = Text.wrapValue(value);\n        }\n        const nextString = template[i + 1];\n        const lastLine = str(text).lastLine();\n        const indentation = lastLine.isEmpty()\n          ? lastLine.leadingSpacesCount()\n          : 0;\n        text =\n          str(text).chopEnd(indentation).toString() +\n          str(wrappedValue).indent(indentation).toString() +\n          nextString;\n      }\n\n      return str(text)\n        .chopEmptyLinesStart()\n        .trimEnd()\n        .dedent()\n        .trimEmptyLines()\n        .chopRepeatNewlines(2)\n        .toString() as string & {\n        __extra: Text.ExtraObject.Infer<T>;\n      };\n    }).$ as Text.Return<T>;\n  }\n\n  private static wrapValue(this: void, value: Text.Value.Base): string {\n    if (value === null || value === undefined || value === false) return \"\";\n    if (typeof value === \"object\") {\n      if (!Object.hasOwn(value, \"type\")) {\n        throw new Error(\n          'Text templating only supports objects with a \"type\" property',\n        );\n      }\n      return `${Text.EXTRA_OBJECT_PREFIX}${JSON.stringify(value)}${\n        Text.EXTRA_OBJECT_SUFFIX\n      }`;\n    }\n    return value;\n  }\n\n  public static parse<E extends Text.ExtraObject.Base>(\n    this: void,\n    text: Text.String<E>,\n  ): Array<string | E> {\n    const regex = new RegExp(\n      Text.EXTRA_OBJECT_PREFIX + \"(.*?)\" + Text.EXTRA_OBJECT_SUFFIX,\n      \"g\",\n    );\n    const parts: Array<string | E> = [];\n    let lastIndex = 0;\n    let match;\n\n    while ((match = regex.exec(text)) !== null) {\n      // Add the text before the match\n      if (match.index > lastIndex) {\n        parts.push(text.slice(lastIndex, match.index));\n      }\n\n      // Parse and add the JSON object\n      try {\n        const jsonObject = json.deserialize<E>(match[1]);\n        parts.push(jsonObject);\n      } catch (error) {\n        throw new TextParseExtraItemException(match[1], error);\n      }\n\n      lastIndex = regex.lastIndex;\n    }\n\n    // Add any remaining text after the last match\n    if (lastIndex < text.length) {\n      parts.push(text.slice(lastIndex));\n    }\n\n    return parts;\n  }\n}\n\nexport declare namespace Text {\n  export type Options = {\n    joinString?: string;\n  };\n\n  export type OptionalString = string | undefined | null | false;\n\n  export type String<TExtraObject extends Text.ExtraObject.Base = never> =\n    string & {\n      __extra: TExtraObject;\n    };\n\n  export namespace ExtraObject {\n    export type Base = { type: string };\n\n    type InferExtraObjectValue<T> = T extends Text.OptionalString ? never : T;\n    type InferExtraObjectCallableResolvable<T> = InferExtraObjectValue<\n      CallableResolvable.Infer<T>\n    >;\n    type InferExtraArrayable<T> =\n      T extends Array<any>\n        ? { [K in keyof T]: InferExtraObjectCallableResolvable<T[K]> }[number]\n        : InferExtraObjectCallableResolvable<T>;\n\n    export type Infer<T extends any[]> = {\n      // Check if it's an array\n      [K in keyof T]: InferExtraArrayable<T[K]>;\n    }[number];\n  }\n\n  export type Value<TExtraObject extends Text.ExtraObject.Base = never> =\n    | Text.OptionalString\n    | TExtraObject;\n\n  export namespace Value {\n    export type Base = OptionalString | ExtraObject.Base;\n  }\n\n  export type TemplateValue<\n    TExtraObject extends Text.ExtraObject.Base = never,\n  > = CallableResolvable.MaybeArray<Value<TExtraObject>>;\n\n  export namespace TemplateValue {\n    export type Base = TemplateValue<ExtraObject.Base>;\n\n    export type Resolved<TExtraObject extends Text.ExtraObject.Base = never> =\n      MaybeArray<Value<TExtraObject>>;\n    export namespace Resolved {\n      export type Base = Resolved<ExtraObject.Base>;\n    }\n  }\n\n  export type Return<T extends Array<Text.TemplateValue.Base>> =\n    true extends CallableResolvable.MaybeArray.ArrayOf.IsPromise<T>\n      ? Promise<string & { __extra: ExtraObject.Infer<T> }>\n      : string & { __extra: ExtraObject.Infer<T> };\n}\n\nexport class TextParseExtraItemException extends Error {\n  constructor(itemString: string, cause: any) {\n    super(\n      `\nFailed to parse extra item serialized value\n\nValue:\n${str(itemString).indent(2).toString()}\n\nCause:\n${str(cause instanceof Error ? cause.message : (cause as string))\n  .indent(2)\n  .toString()}\n\n`.trimStart(),\n      { cause },\n    );\n  }\n}\n\n/**\n * @deprecated\n * Use the `&&` operator instead. `t` will filter out null, undefined, and false values.\n * Conditions are prefered over `tIf` because with `tIf` the interpolated values are still executed even if the value is falsy and the condition is not met.\n * `tIf` also doesn't support type narrowing to the interpolated values so this will trigger a type error:\n * ```ts\n * tIf(typeof value === \"string\")`${value}` // Likely type error as the type of value is not narrowed to a string\n * ```\n *\n * @param condition - The condition to check, can be:\n * - primitive values\n * - promise of a primitive value\n *\n * @returns The result of the template string if the resolved value is true, otherwise an empty string\n *\n * @example\n * ```ts\n * const text = tIf(true)`Hello World`;\n * assert.equal(text, \"Hello World\");\n * ```\n */\nexport const tIf =\n  <CHECK extends Resolvable<any>>(condition: CHECK) =>\n  <TValues extends Array<Text.TemplateValue.Base>>(\n    template: TemplateStringsArray,\n    ...args: TValues\n  ): CHECK extends Promise<any>\n    ? // CHECK is a promise\n      Text.Return<TValues> extends Promise<any>\n      ? // Text.Return<TValues> is a promise as well, so we don't need to wrap it in a promise\n        Text.Return<TValues>\n      : // Text.Return<TValues> is not a promise, so we need to wrap it in a promise\n        Promise<Text.Return<TValues>>\n    : // Neither are promises, so we don't need to wrap the return value in a promise\n      Text.Return<TValues> => {\n    if (!condition) return \"\" as any;\n\n    if (condition instanceof Promise)\n      return condition.then((c) =>\n        c ? t(template, ...args) : (\"\" as any),\n      ) as any;\n\n    return t(template, ...args) as any;\n  };\n\n/**\n * Serializes and formats a template string with values into a single string while preserving extra values typings\n * @returns The serialized and formatted string\n *\n * @features\n * - Promises even nested in arrays are resolved in parallel\n * - Array values are joined with a newline\n * - Text is trimmed\n * - Base indentation is removed\n * - Nested indentation is preserved for multi-line values\n * - Returned value is either a string or a promise of a string based on interpolated values\n * - Extra values are serialized and added to the returned value type\n *\n * @example\n * For the following template:\n * ```ts\n * const text: string = t`\n *     Hello\n *       ${\"- Item 1\\n- Item 2\"}\n *     World\n * `;\n * ```\n *\n * The output will be:\n * ```plain\n * Hello\n *   - Item 1\n *   - Item 2\n * World\n * ```\n */\nexport const t = Text.t;\n\n/**\n * Deserializes a serialized string with extra values\n *\n * @param text - The text string to parse\n * @returns Array of strings and extra objects\n *\n * @example\n * ```ts\n * const text = t`Hello ${{type: \"item\", value: \"World\"}}`;\n * assert.equal(tParse(text), [\"Hello\", { type: \"item\", value: \"World\" }]);\n * ```\n */\nexport const tParse = Text.parse;\n"],"mappings":"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","names":["values"]}

package/dist/text.index.d.cts

@@ -1,3 +1,4 @@
+import { Resolvable } from '@synstack/resolved';
 import { CallableResolvable } from '@synstack/resolved/callable';
 
 /**
@@ -21,7 +22,7 @@ declare namespace Text {
     type Options = {
         joinString?: string;
     };
-    type OptionalString = string | undefined | null;
+    type OptionalString = string | undefined | null | false;
     type String<TExtraObject extends Text.ExtraObject.Base = never> = string & {
         __extra: TExtraObject;
     };
@@ -60,9 +61,18 @@ declare class TextParseExtraItemException extends Error {
     constructor(itemString: string, cause: any);
 }
 /**
+ * @deprecated
+ * Use the `&&` operator instead. `t` will filter out null, undefined, and false values.
+ * Conditions are prefered over `tIf` because with `tIf` the interpolated values are still executed even if the value is falsy and the condition is not met.
+ * `tIf` also doesn't support type narrowing to the interpolated values so this will trigger a type error:
+ * ```ts
+ * tIf(typeof value === "string")`${value}` // Likely type error as the type of value is not narrowed to a string
+ * ```
+ *
  * @param condition - The condition to check, can be:
  * - primitive values
  * - promise of a primitive value
+ *
  * @returns The result of the template string if the resolved value is true, otherwise an empty string
  *
  * @example
@@ -71,7 +81,7 @@ declare class TextParseExtraItemException extends Error {
  * assert.equal(text, "Hello World");
  * ```
  */
-declare const tIf: <CHECK extends unknown>(condition: CHECK) => <TValues extends Array<Text.TemplateValue.Base>>(template: TemplateStringsArray, ...args: TValues) => CHECK extends Promise<any> ? Text.Return<TValues> extends Promise<any> ? Text.Return<TValues> : Promise<Text.Return<TValues>> : Text.Return<TValues>;
+declare const tIf: <CHECK extends Resolvable<any>>(condition: CHECK) => <TValues extends Array<Text.TemplateValue.Base>>(template: TemplateStringsArray, ...args: TValues) => CHECK extends Promise<any> ? Text.Return<TValues> extends Promise<any> ? Text.Return<TValues> : Promise<Text.Return<TValues>> : Text.Return<TValues>;
 /**
  * Serializes and formats a template string with values into a single string while preserving extra values typings
  * @returns The serialized and formatted string

package/dist/text.index.d.ts

@@ -1,3 +1,4 @@
+import { Resolvable } from '@synstack/resolved';
 import { CallableResolvable } from '@synstack/resolved/callable';
 
 /**
@@ -21,7 +22,7 @@ declare namespace Text {
     type Options = {
         joinString?: string;
     };
-    type OptionalString = string | undefined | null;
+    type OptionalString = string | undefined | null | false;
     type String<TExtraObject extends Text.ExtraObject.Base = never> = string & {
         __extra: TExtraObject;
     };
@@ -60,9 +61,18 @@ declare class TextParseExtraItemException extends Error {
     constructor(itemString: string, cause: any);
 }
 /**
+ * @deprecated
+ * Use the `&&` operator instead. `t` will filter out null, undefined, and false values.
+ * Conditions are prefered over `tIf` because with `tIf` the interpolated values are still executed even if the value is falsy and the condition is not met.
+ * `tIf` also doesn't support type narrowing to the interpolated values so this will trigger a type error:
+ * ```ts
+ * tIf(typeof value === "string")`${value}` // Likely type error as the type of value is not narrowed to a string
+ * ```
+ *
  * @param condition - The condition to check, can be:
  * - primitive values
  * - promise of a primitive value
+ *
  * @returns The result of the template string if the resolved value is true, otherwise an empty string
  *
  * @example
@@ -71,7 +81,7 @@ declare class TextParseExtraItemException extends Error {
  * assert.equal(text, "Hello World");
  * ```
  */
-declare const tIf: <CHECK extends unknown>(condition: CHECK) => <TValues extends Array<Text.TemplateValue.Base>>(template: TemplateStringsArray, ...args: TValues) => CHECK extends Promise<any> ? Text.Return<TValues> extends Promise<any> ? Text.Return<TValues> : Promise<Text.Return<TValues>> : Text.Return<TValues>;
+declare const tIf: <CHECK extends Resolvable<any>>(condition: CHECK) => <TValues extends Array<Text.TemplateValue.Base>>(template: TemplateStringsArray, ...args: TValues) => CHECK extends Promise<any> ? Text.Return<TValues> extends Promise<any> ? Text.Return<TValues> : Promise<Text.Return<TValues>> : Text.Return<TValues>;
 /**
  * Serializes and formats a template string with values into a single string while preserving extra values typings
  * @returns The serialized and formatted string

package/dist/text.index.js

@@ -30,8 +30,10 @@ var Text = class _Text {
         const value = values2[i];
         let wrappedValue = "";
         if (Array.isArray(value)) {
-          wrappedValue = value.filter((inner) => inner !== null || inner !== void 0).map(_Text.wrapValue).join(this._options.joinString);
-        } else {
+          wrappedValue = value.filter(
+            (inner) => inner !== null && inner !== void 0 && inner !== false
+          ).map(_Text.wrapValue).join(this._options.joinString);
+        } else if (value !== null && value !== void 0 && value !== false) {
           wrappedValue = _Text.wrapValue(value);
         }
         const nextString = template[i + 1];
@@ -43,7 +45,7 @@ var Text = class _Text {
     }).$;
   }
   static wrapValue(value) {
-    if (value === null || value === void 0) return "";
+    if (value === null || value === void 0 || value === false) return "";
     if (typeof value === "object") {
       if (!Object.hasOwn(value, "type")) {
         throw new Error(

package/dist/text.index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/text.lib.ts"],"sourcesContent":["import { json } from \"@synstack/json\";\nimport { resolvable, type Resolvable } from \"@synstack/resolved\";\nimport { callable, type CallableResolvable } from \"@synstack/resolved/callable\";\nimport { str } from \"@synstack/str\";\nimport { type MaybeArray } from \"../../shared/src/ts.utils.ts\";\n\nexport class Text {\n  private static EXTRA_OBJECT_PREFIX = \"%STR_EXTRA%\";\n  private static EXTRA_OBJECT_SUFFIX = \"%!STR_EXTRA%\";\n\n  private readonly _options: {\n    joinString: string;\n  };\n\n  private constructor(options: Text.Options = {}) {\n    this._options = {\n      joinString: options.joinString ?? \"\\n\",\n    };\n  }\n\n  public static options(this: void, config: Text.Options = {}) {\n    return new Text(config);\n  }\n\n  public options(config: Text.Options) {\n    return new Text({ ...this._options, ...config });\n  }\n\n  public static t<T extends Array<Text.TemplateValue.Base>>(\n    this: void,\n    template: TemplateStringsArray,\n    ...values: T\n  ): Text.Return<T> {\n    return Text.options().t(template, ...values);\n  }\n\n  public t<T extends Array<Text.TemplateValue.Base>>(\n    template: TemplateStringsArray,\n    ...values: T\n  ): Text.Return<T> {\n    // @ts-expect-error - Of course the default value is \"\"\n    if (template.length === 0) return \"\";\n\n    const resolvedValues = callable.resolveNested(values);\n    return resolvable.pipe(resolvedValues)._((values) => {\n      let text = template[0];\n\n      for (let i = 0; i < values.length; i++) {\n        const value = values[i];\n        let wrappedValue = \"\";\n\n        if (Array.isArray(value)) {\n          wrappedValue = value\n            .filter((inner) => inner !== null || inner !== undefined)\n            .map(Text.wrapValue)\n            .join(this._options.joinString);\n        } else {\n          wrappedValue = Text.wrapValue(value);\n        }\n        const nextString = template[i + 1];\n        const lastLine = str(text).lastLine();\n        const indentation = lastLine.isEmpty()\n          ? lastLine.leadingSpacesCount()\n          : 0;\n        text =\n          str(text).chopEnd(indentation).toString() +\n          str(wrappedValue).indent(indentation).toString() +\n          nextString;\n      }\n\n      return str(text)\n        .chopEmptyLinesStart()\n        .trimEnd()\n        .dedent()\n        .trimEmptyLines()\n        .chopRepeatNewlines(2)\n        .toString() as string & {\n        __extra: Text.ExtraObject.Infer<T>;\n      };\n    }).$ as Text.Return<T>;\n  }\n\n  private static wrapValue(this: void, value: Text.Value.Base) {\n    if (value === null || value === undefined) return \"\";\n    if (typeof value === \"object\") {\n      if (!Object.hasOwn(value, \"type\")) {\n        throw new Error(\n          'Text templating only supports objects with a \"type\" property',\n        );\n      }\n      return `${Text.EXTRA_OBJECT_PREFIX}${JSON.stringify(value)}${\n        Text.EXTRA_OBJECT_SUFFIX\n      }`;\n    }\n    return value;\n  }\n\n  public static parse<E extends Text.ExtraObject.Base>(\n    this: void,\n    text: Text.String<E>,\n  ): Array<string | E> {\n    const regex = new RegExp(\n      Text.EXTRA_OBJECT_PREFIX + \"(.*?)\" + Text.EXTRA_OBJECT_SUFFIX,\n      \"g\",\n    );\n    const parts: Array<string | E> = [];\n    let lastIndex = 0;\n    let match;\n\n    while ((match = regex.exec(text)) !== null) {\n      // Add the text before the match\n      if (match.index > lastIndex) {\n        parts.push(text.slice(lastIndex, match.index));\n      }\n\n      // Parse and add the JSON object\n      try {\n        const jsonObject = json.deserialize<E>(match[1]);\n        parts.push(jsonObject);\n      } catch (error) {\n        throw new TextParseExtraItemException(match[1], error);\n      }\n\n      lastIndex = regex.lastIndex;\n    }\n\n    // Add any remaining text after the last match\n    if (lastIndex < text.length) {\n      parts.push(text.slice(lastIndex));\n    }\n\n    return parts;\n  }\n}\n\nexport declare namespace Text {\n  export type Options = {\n    joinString?: string;\n  };\n\n  export type OptionalString = string | undefined | null;\n\n  export type String<TExtraObject extends Text.ExtraObject.Base = never> =\n    string & {\n      __extra: TExtraObject;\n    };\n\n  export namespace ExtraObject {\n    export type Base = { type: string };\n\n    type InferExtraObjectValue<T> = T extends Text.OptionalString ? never : T;\n    type InferExtraObjectCallableResolvable<T> = InferExtraObjectValue<\n      CallableResolvable.Infer<T>\n    >;\n    type InferExtraArrayable<T> =\n      T extends Array<any>\n        ? { [K in keyof T]: InferExtraObjectCallableResolvable<T[K]> }[number]\n        : InferExtraObjectCallableResolvable<T>;\n\n    export type Infer<T extends any[]> = {\n      // Check if it's an array\n      [K in keyof T]: InferExtraArrayable<T[K]>;\n    }[number];\n  }\n\n  export type Value<TExtraObject extends Text.ExtraObject.Base = never> =\n    | Text.OptionalString\n    | TExtraObject;\n\n  export namespace Value {\n    export type Base = OptionalString | ExtraObject.Base;\n  }\n\n  export type TemplateValue<\n    TExtraObject extends Text.ExtraObject.Base = never,\n  > = CallableResolvable.MaybeArray<Value<TExtraObject>>;\n\n  export namespace TemplateValue {\n    export type Base = TemplateValue<ExtraObject.Base>;\n\n    export type Resolved<TExtraObject extends Text.ExtraObject.Base = never> =\n      MaybeArray<Value<TExtraObject>>;\n    export namespace Resolved {\n      export type Base = Resolved<ExtraObject.Base>;\n    }\n  }\n\n  export type Return<T extends Array<Text.TemplateValue.Base>> =\n    true extends CallableResolvable.MaybeArray.ArrayOf.IsPromise<T>\n      ? Promise<string & { __extra: ExtraObject.Infer<T> }>\n      : string & { __extra: ExtraObject.Infer<T> };\n}\n\nexport class TextParseExtraItemException extends Error {\n  constructor(itemString: string, cause: any) {\n    super(\n      `\nFailed to parse extra item serialized value\n\nValue:\n${str(itemString).indent(2).toString()}\n\nCause:\n${str(cause instanceof Error ? cause.message : (cause as string))\n  .indent(2)\n  .toString()}\n\n`.trimStart(),\n      { cause },\n    );\n  }\n}\n\n/**\n * @param condition - The condition to check, can be:\n * - primitive values\n * - promise of a primitive value\n * @returns The result of the template string if the resolved value is true, otherwise an empty string\n *\n * @example\n * ```ts\n * const text = tIf(true)`Hello World`;\n * assert.equal(text, \"Hello World\");\n * ```\n */\nexport const tIf =\n  <CHECK extends Resolvable<any>>(condition: CHECK) =>\n  <TValues extends Array<Text.TemplateValue.Base>>(\n    template: TemplateStringsArray,\n    ...args: TValues\n  ): CHECK extends Promise<any>\n    ? // CHECK is a promise\n      Text.Return<TValues> extends Promise<any>\n      ? // Text.Return<TValues> is a promise as well, so we don't need to wrap it in a promise\n        Text.Return<TValues>\n      : // Text.Return<TValues> is not a promise, so we need to wrap it in a promise\n        Promise<Text.Return<TValues>>\n    : // Neither are promises, so we don't need to wrap the return value in a promise\n      Text.Return<TValues> => {\n    if (!condition) return \"\" as any;\n\n    if (condition instanceof Promise)\n      return condition.then((c) =>\n        c ? t(template, ...args) : (\"\" as any),\n      ) as any;\n\n    return t(template, ...args) as any;\n  };\n\n/**\n * Serializes and formats a template string with values into a single string while preserving extra values typings\n * @returns The serialized and formatted string\n *\n * @features\n * - Promises even nested in arrays are resolved in parallel\n * - Array values are joined with a newline\n * - Text is trimmed\n * - Base indentation is removed\n * - Nested indentation is preserved for multi-line values\n * - Returned value is either a string or a promise of a string based on interpolated values\n * - Extra values are serialized and added to the returned value type\n *\n * @example\n * For the following template:\n * ```ts\n * const text: string = t`\n *     Hello\n *       ${\"- Item 1\\n- Item 2\"}\n *     World\n * `;\n * ```\n *\n * The output will be:\n * ```plain\n * Hello\n *   - Item 1\n *   - Item 2\n * World\n * ```\n */\nexport const t = Text.t;\n\n/**\n * Deserializes a serialized string with extra values\n *\n * @param text - The text string to parse\n * @returns Array of strings and extra objects\n *\n * @example\n * ```ts\n * const text = t`Hello ${{type: \"item\", value: \"World\"}}`;\n * assert.equal(tParse(text), [\"Hello\", { type: \"item\", value: \"World\" }]);\n * ```\n */\nexport const tParse = Text.parse;\n"],"mappings":"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","names":["values"]}
+{"version":3,"sources":["../src/text.lib.ts"],"sourcesContent":["import { json } from \"@synstack/json\";\nimport { resolvable, type Resolvable } from \"@synstack/resolved\";\nimport { callable, type CallableResolvable } from \"@synstack/resolved/callable\";\nimport { str } from \"@synstack/str\";\nimport { type MaybeArray } from \"../../shared/src/ts.utils.ts\";\n\nexport class Text {\n  private static EXTRA_OBJECT_PREFIX = \"%STR_EXTRA%\";\n  private static EXTRA_OBJECT_SUFFIX = \"%!STR_EXTRA%\";\n\n  private readonly _options: {\n    joinString: string;\n  };\n\n  private constructor(options: Text.Options = {}) {\n    this._options = {\n      joinString: options.joinString ?? \"\\n\",\n    };\n  }\n\n  public static options(this: void, config: Text.Options = {}) {\n    return new Text(config);\n  }\n\n  public options(config: Text.Options) {\n    return new Text({ ...this._options, ...config });\n  }\n\n  public static t<T extends Array<Text.TemplateValue.Base>>(\n    this: void,\n    template: TemplateStringsArray,\n    ...values: T\n  ): Text.Return<T> {\n    return Text.options().t(template, ...values);\n  }\n\n  public t<T extends Array<Text.TemplateValue.Base>>(\n    template: TemplateStringsArray,\n    ...values: T\n  ): Text.Return<T> {\n    // @ts-expect-error - Of course the default value is \"\"\n    if (template.length === 0) return \"\";\n\n    const resolvedValues = callable.resolveNested(values);\n    return resolvable.pipe(resolvedValues)._((values) => {\n      let text = template[0];\n\n      for (let i = 0; i < values.length; i++) {\n        const value = values[i];\n        let wrappedValue = \"\";\n\n        if (Array.isArray(value)) {\n          wrappedValue = value\n            .filter(\n              (inner) =>\n                inner !== null && inner !== undefined && inner !== false,\n            )\n            .map(Text.wrapValue)\n            .join(this._options.joinString);\n        } else if (value !== null && value !== undefined && value !== false) {\n          wrappedValue = Text.wrapValue(value);\n        }\n        const nextString = template[i + 1];\n        const lastLine = str(text).lastLine();\n        const indentation = lastLine.isEmpty()\n          ? lastLine.leadingSpacesCount()\n          : 0;\n        text =\n          str(text).chopEnd(indentation).toString() +\n          str(wrappedValue).indent(indentation).toString() +\n          nextString;\n      }\n\n      return str(text)\n        .chopEmptyLinesStart()\n        .trimEnd()\n        .dedent()\n        .trimEmptyLines()\n        .chopRepeatNewlines(2)\n        .toString() as string & {\n        __extra: Text.ExtraObject.Infer<T>;\n      };\n    }).$ as Text.Return<T>;\n  }\n\n  private static wrapValue(this: void, value: Text.Value.Base): string {\n    if (value === null || value === undefined || value === false) return \"\";\n    if (typeof value === \"object\") {\n      if (!Object.hasOwn(value, \"type\")) {\n        throw new Error(\n          'Text templating only supports objects with a \"type\" property',\n        );\n      }\n      return `${Text.EXTRA_OBJECT_PREFIX}${JSON.stringify(value)}${\n        Text.EXTRA_OBJECT_SUFFIX\n      }`;\n    }\n    return value;\n  }\n\n  public static parse<E extends Text.ExtraObject.Base>(\n    this: void,\n    text: Text.String<E>,\n  ): Array<string | E> {\n    const regex = new RegExp(\n      Text.EXTRA_OBJECT_PREFIX + \"(.*?)\" + Text.EXTRA_OBJECT_SUFFIX,\n      \"g\",\n    );\n    const parts: Array<string | E> = [];\n    let lastIndex = 0;\n    let match;\n\n    while ((match = regex.exec(text)) !== null) {\n      // Add the text before the match\n      if (match.index > lastIndex) {\n        parts.push(text.slice(lastIndex, match.index));\n      }\n\n      // Parse and add the JSON object\n      try {\n        const jsonObject = json.deserialize<E>(match[1]);\n        parts.push(jsonObject);\n      } catch (error) {\n        throw new TextParseExtraItemException(match[1], error);\n      }\n\n      lastIndex = regex.lastIndex;\n    }\n\n    // Add any remaining text after the last match\n    if (lastIndex < text.length) {\n      parts.push(text.slice(lastIndex));\n    }\n\n    return parts;\n  }\n}\n\nexport declare namespace Text {\n  export type Options = {\n    joinString?: string;\n  };\n\n  export type OptionalString = string | undefined | null | false;\n\n  export type String<TExtraObject extends Text.ExtraObject.Base = never> =\n    string & {\n      __extra: TExtraObject;\n    };\n\n  export namespace ExtraObject {\n    export type Base = { type: string };\n\n    type InferExtraObjectValue<T> = T extends Text.OptionalString ? never : T;\n    type InferExtraObjectCallableResolvable<T> = InferExtraObjectValue<\n      CallableResolvable.Infer<T>\n    >;\n    type InferExtraArrayable<T> =\n      T extends Array<any>\n        ? { [K in keyof T]: InferExtraObjectCallableResolvable<T[K]> }[number]\n        : InferExtraObjectCallableResolvable<T>;\n\n    export type Infer<T extends any[]> = {\n      // Check if it's an array\n      [K in keyof T]: InferExtraArrayable<T[K]>;\n    }[number];\n  }\n\n  export type Value<TExtraObject extends Text.ExtraObject.Base = never> =\n    | Text.OptionalString\n    | TExtraObject;\n\n  export namespace Value {\n    export type Base = OptionalString | ExtraObject.Base;\n  }\n\n  export type TemplateValue<\n    TExtraObject extends Text.ExtraObject.Base = never,\n  > = CallableResolvable.MaybeArray<Value<TExtraObject>>;\n\n  export namespace TemplateValue {\n    export type Base = TemplateValue<ExtraObject.Base>;\n\n    export type Resolved<TExtraObject extends Text.ExtraObject.Base = never> =\n      MaybeArray<Value<TExtraObject>>;\n    export namespace Resolved {\n      export type Base = Resolved<ExtraObject.Base>;\n    }\n  }\n\n  export type Return<T extends Array<Text.TemplateValue.Base>> =\n    true extends CallableResolvable.MaybeArray.ArrayOf.IsPromise<T>\n      ? Promise<string & { __extra: ExtraObject.Infer<T> }>\n      : string & { __extra: ExtraObject.Infer<T> };\n}\n\nexport class TextParseExtraItemException extends Error {\n  constructor(itemString: string, cause: any) {\n    super(\n      `\nFailed to parse extra item serialized value\n\nValue:\n${str(itemString).indent(2).toString()}\n\nCause:\n${str(cause instanceof Error ? cause.message : (cause as string))\n  .indent(2)\n  .toString()}\n\n`.trimStart(),\n      { cause },\n    );\n  }\n}\n\n/**\n * @deprecated\n * Use the `&&` operator instead. `t` will filter out null, undefined, and false values.\n * Conditions are prefered over `tIf` because with `tIf` the interpolated values are still executed even if the value is falsy and the condition is not met.\n * `tIf` also doesn't support type narrowing to the interpolated values so this will trigger a type error:\n * ```ts\n * tIf(typeof value === \"string\")`${value}` // Likely type error as the type of value is not narrowed to a string\n * ```\n *\n * @param condition - The condition to check, can be:\n * - primitive values\n * - promise of a primitive value\n *\n * @returns The result of the template string if the resolved value is true, otherwise an empty string\n *\n * @example\n * ```ts\n * const text = tIf(true)`Hello World`;\n * assert.equal(text, \"Hello World\");\n * ```\n */\nexport const tIf =\n  <CHECK extends Resolvable<any>>(condition: CHECK) =>\n  <TValues extends Array<Text.TemplateValue.Base>>(\n    template: TemplateStringsArray,\n    ...args: TValues\n  ): CHECK extends Promise<any>\n    ? // CHECK is a promise\n      Text.Return<TValues> extends Promise<any>\n      ? // Text.Return<TValues> is a promise as well, so we don't need to wrap it in a promise\n        Text.Return<TValues>\n      : // Text.Return<TValues> is not a promise, so we need to wrap it in a promise\n        Promise<Text.Return<TValues>>\n    : // Neither are promises, so we don't need to wrap the return value in a promise\n      Text.Return<TValues> => {\n    if (!condition) return \"\" as any;\n\n    if (condition instanceof Promise)\n      return condition.then((c) =>\n        c ? t(template, ...args) : (\"\" as any),\n      ) as any;\n\n    return t(template, ...args) as any;\n  };\n\n/**\n * Serializes and formats a template string with values into a single string while preserving extra values typings\n * @returns The serialized and formatted string\n *\n * @features\n * - Promises even nested in arrays are resolved in parallel\n * - Array values are joined with a newline\n * - Text is trimmed\n * - Base indentation is removed\n * - Nested indentation is preserved for multi-line values\n * - Returned value is either a string or a promise of a string based on interpolated values\n * - Extra values are serialized and added to the returned value type\n *\n * @example\n * For the following template:\n * ```ts\n * const text: string = t`\n *     Hello\n *       ${\"- Item 1\\n- Item 2\"}\n *     World\n * `;\n * ```\n *\n * The output will be:\n * ```plain\n * Hello\n *   - Item 1\n *   - Item 2\n * World\n * ```\n */\nexport const t = Text.t;\n\n/**\n * Deserializes a serialized string with extra values\n *\n * @param text - The text string to parse\n * @returns Array of strings and extra objects\n *\n * @example\n * ```ts\n * const text = t`Hello ${{type: \"item\", value: \"World\"}}`;\n * assert.equal(tParse(text), [\"Hello\", { type: \"item\", value: \"World\" }]);\n * ```\n */\nexport const tParse = Text.parse;\n"],"mappings":"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","names":["values"]}

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.1.9",
+  "version": "1.2.1",
   "description": "String templating as it was meant to be",
   "keywords": [
     "string",
@@ -50,19 +50,19 @@
     }
   },
   "dependencies": {
-    "@synstack/json": "1.1.6",
-    "@synstack/resolved": "1.2.3",
-    "@synstack/str": "1.2.5"
+    "@synstack/json": "1.1.7",
+    "@synstack/resolved": "1.2.4",
+    "@synstack/str": "1.2.6"
   },
   "devDependencies": {
     "@types/node": "^22.10.1",
     "tsup": "^8.4.0",
-    "typescript": "^5.7.3"
+    "typescript": "^5.8.2"
   },
   "files": [
     "src/**/*.ts",
     "!src/**/*.test.ts",
     "dist/**/*"
   ],
-  "gitHead": "9351f651b39cf757bc37c3e2ab9c516c0e2ed127"
+  "gitHead": "4aae6e86f7664e5b928ecb3a492ec035307168d1"
 }

package/src/text.lib.ts

@@ -51,10 +51,13 @@ export class Text {
 
         if (Array.isArray(value)) {
           wrappedValue = value
-            .filter((inner) => inner !== null || inner !== undefined)
+            .filter(
+              (inner) =>
+                inner !== null && inner !== undefined && inner !== false,
+            )
             .map(Text.wrapValue)
             .join(this._options.joinString);
-        } else {
+        } else if (value !== null && value !== undefined && value !== false) {
           wrappedValue = Text.wrapValue(value);
         }
         const nextString = template[i + 1];
@@ -80,8 +83,8 @@ export class Text {
     }).$ as Text.Return<T>;
   }
 
-  private static wrapValue(this: void, value: Text.Value.Base) {
-    if (value === null || value === undefined) return "";
+  private static wrapValue(this: void, value: Text.Value.Base): string {
+    if (value === null || value === undefined || value === false) return "";
     if (typeof value === "object") {
       if (!Object.hasOwn(value, "type")) {
         throw new Error(
@@ -138,7 +141,7 @@ export declare namespace Text {
     joinString?: string;
   };
 
-  export type OptionalString = string | undefined | null;
+  export type OptionalString = string | undefined | null | false;
 
   export type String<TExtraObject extends Text.ExtraObject.Base = never> =
     string & {
@@ -212,9 +215,18 @@ ${str(cause instanceof Error ? cause.message : (cause as string))
 }
 
 /**
+ * @deprecated
+ * Use the `&&` operator instead. `t` will filter out null, undefined, and false values.
+ * Conditions are prefered over `tIf` because with `tIf` the interpolated values are still executed even if the value is falsy and the condition is not met.
+ * `tIf` also doesn't support type narrowing to the interpolated values so this will trigger a type error:
+ * ```ts
+ * tIf(typeof value === "string")`${value}` // Likely type error as the type of value is not narrowed to a string
+ * ```
+ *
  * @param condition - The condition to check, can be:
  * - primitive values
  * - promise of a primitive value
+ *
  * @returns The result of the template string if the resolved value is true, otherwise an empty string
  *
  * @example