@synstack/text 1.1.5 → 1.1.6

package/README.md

@@ -46,7 +46,6 @@ List of items:
 
 **What's baked in ?**
 
-- Functions are called
 - Promises even nested in arrays are resolved in parallel
 - Array values are joined with a newline
 - Text is trimmed
@@ -165,9 +164,6 @@ const textFail: Text.String<{ type: "extra"; value: string }> =
 const text: string & { __extra: { type: "extra"; value: string } } =
   t`Hello ${{ type: "extra" as const, value: "Hello" }} World`;
 
-console.log(text);
-// Hello %STR_EXTRA%{"type":"extra","value":"Hello"}%!STR_EXTRA% World
-
 console.log(tParse(text));
 // ["Hello ", { type: "extra", value: "Hello" }, " World"]
 ```

package/dist/text.index.cjs

@@ -22,6 +22,7 @@ var text_index_exports = {};
 __export(text_index_exports, {
   TextParseExtraItemException: () => TextParseExtraItemException,
   t: () => t,
+  tIf: () => tIf,
   tParse: () => tParse
 });
 module.exports = __toCommonJS(text_index_exports);
@@ -125,12 +126,21 @@ ${(0, import_str.str)(cause instanceof Error ? cause.message : cause).indent(2).
     );
   }
 };
+var tIf = (condition) => (template, ...args) => {
+  if (!condition) return "";
+  if (condition instanceof Promise)
+    return condition.then(
+      (c) => c ? t(template, ...args) : ""
+    );
+  return t(template, ...args);
+};
 var t = Text.t;
 var tParse = Text.parse;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   TextParseExtraItemException,
   t,
+  tIf,
   tParse
 });
 //# sourceMappingURL=text.index.cjs.map

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 } 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\nexport const t = Text.t;\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((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"]}

package/dist/text.index.d.cts

@@ -59,7 +59,63 @@ declare namespace Text {
 declare class TextParseExtraItemException extends Error {
     constructor(itemString: string, cause: any);
 }
+/**
+ * @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
+ * ```ts
+ * const text = tIf(true)`Hello World`;
+ * 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>;
+/**
+ * Serializes and formats a template string with values into a single string while preserving extra values typings
+ * @returns The serialized and formatted string
+ *
+ * @features
+ * - Promises even nested in arrays are resolved in parallel
+ * - Array values are joined with a newline
+ * - Text is trimmed
+ * - Base indentation is removed
+ * - Nested indentation is preserved for multi-line values
+ * - Returned value is either a string or a promise of a string based on interpolated values
+ * - Extra values are serialized and added to the returned value type
+ *
+ * @example
+ * For the following template:
+ * ```ts
+ * const text: string = t`
+ *     Hello
+ *       ${"- Item 1\n- Item 2"}
+ *     World
+ * `;
+ * ```
+ *
+ * The output will be:
+ * ```plain
+ * Hello
+ *   - Item 1
+ *   - Item 2
+ * World
+ * ```
+ */
 declare const t: typeof Text.t;
+/**
+ * Deserializes a serialized string with extra values
+ *
+ * @param text - The text string to parse
+ * @returns Array of strings and extra objects
+ *
+ * @example
+ * ```ts
+ * const text = t`Hello ${{type: "item", value: "World"}}`;
+ * assert.equal(tParse(text), ["Hello", { type: "item", value: "World" }]);
+ * ```
+ */
 declare const tParse: typeof Text.parse;
 
-export { Text, TextParseExtraItemException, t, tParse };
+export { Text, TextParseExtraItemException, t, tIf, tParse };

package/dist/text.index.d.ts

@@ -59,7 +59,63 @@ declare namespace Text {
 declare class TextParseExtraItemException extends Error {
     constructor(itemString: string, cause: any);
 }
+/**
+ * @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
+ * ```ts
+ * const text = tIf(true)`Hello World`;
+ * 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>;
+/**
+ * Serializes and formats a template string with values into a single string while preserving extra values typings
+ * @returns The serialized and formatted string
+ *
+ * @features
+ * - Promises even nested in arrays are resolved in parallel
+ * - Array values are joined with a newline
+ * - Text is trimmed
+ * - Base indentation is removed
+ * - Nested indentation is preserved for multi-line values
+ * - Returned value is either a string or a promise of a string based on interpolated values
+ * - Extra values are serialized and added to the returned value type
+ *
+ * @example
+ * For the following template:
+ * ```ts
+ * const text: string = t`
+ *     Hello
+ *       ${"- Item 1\n- Item 2"}
+ *     World
+ * `;
+ * ```
+ *
+ * The output will be:
+ * ```plain
+ * Hello
+ *   - Item 1
+ *   - Item 2
+ * World
+ * ```
+ */
 declare const t: typeof Text.t;
+/**
+ * Deserializes a serialized string with extra values
+ *
+ * @param text - The text string to parse
+ * @returns Array of strings and extra objects
+ *
+ * @example
+ * ```ts
+ * const text = t`Hello ${{type: "item", value: "World"}}`;
+ * assert.equal(tParse(text), ["Hello", { type: "item", value: "World" }]);
+ * ```
+ */
 declare const tParse: typeof Text.parse;
 
-export { Text, TextParseExtraItemException, t, tParse };
+export { Text, TextParseExtraItemException, t, tIf, tParse };

package/dist/text.index.js

@@ -97,11 +97,20 @@ ${str(cause instanceof Error ? cause.message : cause).indent(2).toString()}
     );
   }
 };
+var tIf = (condition) => (template, ...args) => {
+  if (!condition) return "";
+  if (condition instanceof Promise)
+    return condition.then(
+      (c) => c ? t(template, ...args) : ""
+    );
+  return t(template, ...args);
+};
 var t = Text.t;
 var tParse = Text.parse;
 export {
   TextParseExtraItemException,
   t,
+  tIf,
   tParse
 };
 //# sourceMappingURL=text.index.js.map

package/dist/text.index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/text.lib.ts"],"sourcesContent":["import { json } from \"@synstack/json\";\nimport { 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\nexport const t = Text.t;\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((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":";AAAA,SAAS,YAAY;AACrB,SAAS,kBAAmC;AAC5C,SAAS,gBAAyC;AAClD,SAAS,WAAW;AAGb,IAAM,OAAN,MAAM,MAAK;AAAA,EAChB,OAAe,sBAAsB;AAAA,EACrC,OAAe,sBAAsB;AAAA,EAEpB;AAAA,EAIT,YAAY,UAAwB,CAAC,GAAG;AAC9C,SAAK,WAAW;AAAA,MACd,YAAY,QAAQ,cAAc;AAAA,IACpC;AAAA,EACF;AAAA,EAEA,OAAc,QAAoB,SAAuB,CAAC,GAAG;AAC3D,WAAO,IAAI,MAAK,MAAM;AAAA,EACxB;AAAA,EAEO,QAAQ,QAAsB;AACnC,WAAO,IAAI,MAAK,EAAE,GAAG,KAAK,UAAU,GAAG,OAAO,CAAC;AAAA,EACjD;AAAA,EAEA,OAAc,EAEZ,aACG,QACa;AAChB,WAAO,MAAK,QAAQ,EAAE,EAAE,UAAU,GAAG,MAAM;AAAA,EAC7C;AAAA,EAEO,EACL,aACG,QACa;AAEhB,QAAI,SAAS,WAAW,EAAG,QAAO;AAElC,UAAM,iBAAiB,SAAS,cAAc,MAAM;AACpD,WAAO,WAAW,KAAK,cAAc,EAAE,EAAE,CAACA,YAAW;AACnD,UAAI,OAAO,SAAS,CAAC;AAErB,eAAS,IAAI,GAAG,IAAIA,QAAO,QAAQ,KAAK;AACtC,cAAM,QAAQA,QAAO,CAAC;AACtB,YAAI,eAAe;AAEnB,YAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,yBAAe,MACZ,OAAO,CAAC,UAAU,UAAU,QAAQ,UAAU,MAAS,EACvD,IAAI,MAAK,SAAS,EAClB,KAAK,KAAK,SAAS,UAAU;AAAA,QAClC,OAAO;AACL,yBAAe,MAAK,UAAU,KAAK;AAAA,QACrC;AACA,cAAM,aAAa,SAAS,IAAI,CAAC;AACjC,cAAM,WAAW,IAAI,IAAI,EAAE,SAAS;AACpC,cAAM,cAAc,SAAS,QAAQ,IACjC,SAAS,mBAAmB,IAC5B;AACJ,eACE,IAAI,IAAI,EAAE,QAAQ,WAAW,EAAE,SAAS,IACxC,IAAI,YAAY,EAAE,OAAO,WAAW,EAAE,SAAS,IAC/C;AAAA,MACJ;AAEA,aAAO,IAAI,IAAI,EACZ,oBAAoB,EACpB,QAAQ,EACR,OAAO,EACP,eAAe,EACf,mBAAmB,CAAC,EACpB,SAAS;AAAA,IAGd,CAAC,EAAE;AAAA,EACL;AAAA,EAEA,OAAe,UAAsB,OAAwB;AAC3D,QAAI,UAAU,QAAQ,UAAU,OAAW,QAAO;AAClD,QAAI,OAAO,UAAU,UAAU;AAC7B,UAAI,CAAC,OAAO,OAAO,OAAO,MAAM,GAAG;AACjC,cAAM,IAAI;AAAA,UACR;AAAA,QACF;AAAA,MACF;AACA,aAAO,GAAG,MAAK,mBAAmB,GAAG,KAAK,UAAU,KAAK,CAAC,GACxD,MAAK,mBACP;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAAA,EAEA,OAAc,MAEZ,MACmB;AACnB,UAAM,QAAQ,IAAI;AAAA,MAChB,MAAK,sBAAsB,UAAU,MAAK;AAAA,MAC1C;AAAA,IACF;AACA,UAAM,QAA2B,CAAC;AAClC,QAAI,YAAY;AAChB,QAAI;AAEJ,YAAQ,QAAQ,MAAM,KAAK,IAAI,OAAO,MAAM;AAE1C,UAAI,MAAM,QAAQ,WAAW;AAC3B,cAAM,KAAK,KAAK,MAAM,WAAW,MAAM,KAAK,CAAC;AAAA,MAC/C;AAGA,UAAI;AACF,cAAM,aAAa,KAAK,YAAe,MAAM,CAAC,CAAC;AAC/C,cAAM,KAAK,UAAU;AAAA,MACvB,SAAS,OAAO;AACd,cAAM,IAAI,4BAA4B,MAAM,CAAC,GAAG,KAAK;AAAA,MACvD;AAEA,kBAAY,MAAM;AAAA,IACpB;AAGA,QAAI,YAAY,KAAK,QAAQ;AAC3B,YAAM,KAAK,KAAK,MAAM,SAAS,CAAC;AAAA,IAClC;AAEA,WAAO;AAAA,EACT;AACF;AA4DO,IAAM,8BAAN,cAA0C,MAAM;AAAA,EACrD,YAAY,YAAoB,OAAY;AAC1C;AAAA,MACE;AAAA;AAAA;AAAA;AAAA,EAIJ,IAAI,UAAU,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC;AAAA;AAAA;AAAA,EAGpC,IAAI,iBAAiB,QAAQ,MAAM,UAAW,KAAgB,EAC7D,OAAO,CAAC,EACR,SAAS,CAAC;AAAA;AAAA,EAEX,UAAU;AAAA,MACN,EAAE,MAAM;AAAA,IACV;AAAA,EACF;AACF;AAcO,IAAM,MACX,CAAgC,cAChC,CACE,aACG,SASuB;AAC1B,MAAI,CAAC,UAAW,QAAO;AAEvB,MAAI,qBAAqB;AACvB,WAAO,UAAU;AAAA,MAAK,CAAC,MACrB,IAAI,EAAE,UAAU,GAAG,IAAI,IAAK;AAAA,IAC9B;AAEF,SAAO,EAAE,UAAU,GAAG,IAAI;AAC5B;AAiCK,IAAM,IAAI,KAAK;AAcf,IAAM,SAAS,KAAK;","names":["values"]}

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "String templating as it was meant to be",
   "keywords": [
     "string",
@@ -50,9 +50,9 @@
     }
   },
   "dependencies": {
-    "@synstack/json": "1.1.3",
-    "@synstack/resolved": "1.2.0",
-    "@synstack/str": "1.2.1"
+    "@synstack/json": "1.1.4",
+    "@synstack/resolved": "1.2.1",
+    "@synstack/str": "1.2.2"
   },
   "devDependencies": {
     "@types/node": "^22.10.1",
@@ -64,5 +64,5 @@
     "!src/**/*.test.ts",
     "dist/**/*"
   ],
-  "gitHead": "348d1987aba7aee8fbc5469d071e3c71663fc775"
+  "gitHead": "2868de5f8935b959b5b5faa6606a2fa9fcad27ab"
 }

package/src/text.bundle.ts

@@ -1 +1 @@
-export { t, tParse } from "./text.lib.ts";
+export { t, tIf, tParse } from "./text.lib.ts";

package/src/text.lib.ts

@@ -1,5 +1,5 @@
 import { json } from "@synstack/json";
-import { resolvable } from "@synstack/resolved";
+import { resolvable, type Resolvable } from "@synstack/resolved";
 import { callable, type CallableResolvable } from "@synstack/resolved/callable";
 import { str } from "@synstack/str";
 import { type MaybeArray } from "../../shared/src/ts.utils.ts";
@@ -211,5 +211,85 @@ ${str(cause instanceof Error ? cause.message : (cause as 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
+ * ```ts
+ * const text = tIf(true)`Hello World`;
+ * assert.equal(text, "Hello World");
+ * ```
+ */
+export const tIf =
+  <CHECK extends Resolvable<any>>(condition: CHECK) =>
+  <TValues extends Array<Text.TemplateValue.Base>>(
+    template: TemplateStringsArray,
+    ...args: TValues
+  ): CHECK extends Promise<any>
+    ? // CHECK is a promise
+      Text.Return<TValues> extends Promise<any>
+      ? // Text.Return<TValues> is a promise as well, so we don't need to wrap it in a promise
+        Text.Return<TValues>
+      : // Text.Return<TValues> is not a promise, so we need to wrap it in a promise
+        Promise<Text.Return<TValues>>
+    : // Neither are promises, so we don't need to wrap the return value in a promise
+      Text.Return<TValues> => {
+    if (!condition) return "" as any;
+
+    if (condition instanceof Promise)
+      return condition.then((c) =>
+        c ? t(template, ...args) : ("" as any),
+      ) as any;
+
+    return t(template, ...args) as any;
+  };
+
+/**
+ * Serializes and formats a template string with values into a single string while preserving extra values typings
+ * @returns The serialized and formatted string
+ *
+ * @features
+ * - Promises even nested in arrays are resolved in parallel
+ * - Array values are joined with a newline
+ * - Text is trimmed
+ * - Base indentation is removed
+ * - Nested indentation is preserved for multi-line values
+ * - Returned value is either a string or a promise of a string based on interpolated values
+ * - Extra values are serialized and added to the returned value type
+ *
+ * @example
+ * For the following template:
+ * ```ts
+ * const text: string = t`
+ *     Hello
+ *       ${"- Item 1\n- Item 2"}
+ *     World
+ * `;
+ * ```
+ *
+ * The output will be:
+ * ```plain
+ * Hello
+ *   - Item 1
+ *   - Item 2
+ * World
+ * ```
+ */
 export const t = Text.t;
+
+/**
+ * Deserializes a serialized string with extra values
+ *
+ * @param text - The text string to parse
+ * @returns Array of strings and extra objects
+ *
+ * @example
+ * ```ts
+ * const text = t`Hello ${{type: "item", value: "World"}}`;
+ * assert.equal(tParse(text), ["Hello", { type: "item", value: "World" }]);
+ * ```
+ */
 export const tParse = Text.parse;