feat: add overload for join() to accept FormattableString arrays directly

Author: kravetsone

src/index.ts

@@ -231,18 +231,39 @@ export const customEmoji = buildFormatterWithArgs<[custom_emoji_id: string]>(
  * Separator by default is `, `
  * @example
  * ```ts
+ * join([format`hello`, format`world`], "\n")
  * format`${join(["test", "other"], (x) => format`${bold(x)}`, "\n")}`
  * ```
  */
+export function join(
+	array: (Stringable | false | undefined | null)[],
+	separator?: string,
+): FormattableString;
 export function join<T>(
 	array: T[],
 	iterator: (item: T, index: number) => Stringable | false | undefined | null,
+	separator?: string,
+): FormattableString;
+export function join<T>(
+	array: T[],
+	iteratorOrSeparator?:
+		| ((item: T, index: number) => Stringable | false | undefined | null)
+		| string,
 	separator = ", ",
-) {
+): FormattableString {
 	let text = "";
 	const entities: TelegramMessageEntity[] = [];
 
-	for (const [index, str] of array.map(iterator).entries()) {
+	const items =
+		typeof iteratorOrSeparator === "function"
+			? array.map(iteratorOrSeparator)
+			: array;
+	const sep =
+		typeof iteratorOrSeparator === "string"
+			? iteratorOrSeparator
+			: separator;
+
+	for (const [index, str] of (items as (Stringable | false | undefined | null)[]).entries()) {
 		if (str instanceof FormattableString)
 			entities.push(
 				...str.entities.map((e) => ({
@@ -251,7 +272,7 @@ export function join<T>(
 				})),
 			);
 		if (typeof str !== "undefined" && str !== null && str !== false)
-			text += str.toString() + (index === array.length - 1 ? "" : separator);
+			text += str.toString() + (index === items.length - 1 ? "" : sep);
 	}
 
 	return new FormattableString(text, entities);

tests/index.test.ts

@@ -231,4 +231,31 @@ describe("Usage format`` thing", () => {
 		expect(result.text).toBe("text more");
 		expect(result.entities).toEqual([]);
 	});
+
+	test("join(array, separator) joins FormattableStrings directly", () => {
+		const result = join([format`${bold("a")}`, format`${italic("b")}`], "\n");
+		expect(result.text).toBe("a\nb");
+		expect(result.entities).toEqual([
+			{ type: "bold", offset: 0, length: 1 },
+			{ type: "italic", offset: 2, length: 1 },
+		]);
+	});
+
+	test("join(array, separator) uses default separator', '", () => {
+		const result = join([bold("x"), bold("y")]);
+		expect(result.text).toBe("x, y");
+		expect(result.entities).toEqual([
+			{ type: "bold", offset: 0, length: 1 },
+			{ type: "bold", offset: 3, length: 1 },
+		]);
+	});
+
+	test("join(array, separator) skips falsy values", () => {
+		const result = join([bold("a"), null, undefined, false, bold("b")], " | ");
+		expect(result.text).toBe("a | b");
+		expect(result.entities).toEqual([
+			{ type: "bold", offset: 0, length: 1 },
+			{ type: "bold", offset: 4, length: 1 },
+		]);
+	});
 });