@synstack/text 1.0.1-alpha.0

package/README.md

@@ -0,0 +1,173 @@
+# @synstack/text
+
+> String templating as it was meant to be
+
+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:
+
+```ts
+import { t } from "@synstack/text";
+
+const items = ["Hello", "World"];
+
+const text: string = await t`
+    Value: ${items.join(", ")}
+    Promise: ${Promise.resolve(items.join(", "))}
+
+    Callables:
+      Callable: ${() => items.join(", ")}
+      Callable Promise: ${() => Promise.resolve(items.join(", "))}
+
+    List of items:
+      ${() => Promise.resolve(items.map((item) => `- ${item}`))}
+`;
+```
+
+Into this:
+
+```plain
+Value: Hello, World
+Promise: Hello, World
+
+Callables:
+  Callable: Hello, World
+  Callable Promise: Hello, World
+
+List of items:
+  - Hello
+  - World
+```
+
+**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
+- 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
+
+## Installation
+
+```bash
+npm install @synstack/text
+yarn add @synstack/text
+```
+
+## Features
+
+### Text formatting
+
+- `t` will automatically trim unecessary whitespaces and indentations. This allows your code to remain indented and readable while still being able to use the template.
+- `t` will auto-join array values with a newline.
+- `t` will propagate indentation to each line of the nested values.
+
+```ts
+const text: string = t`
+              Hello
+                ${"- Item 1\n- Item 2"}
+              World
+            `;
+```
+
+Will be transformed into:
+
+```plain
+Hello
+  - Item 1
+  - Item 2
+World
+```
+
+### Async support
+
+- `t` automatically detects if the template is async or not and handles it accordingly.
+- When `t` is async, it resolves all values in parralel with a `Promise.all`
+- If you want to force serial execution, use an `await` expression.
+
+```ts
+const sync: string = t`Hello ${"World"}`;
+const async: Promise<string> = t`Hello ${Promise.resolve("World")}`;
+
+/*
+Asuming retrieveUserName and retrieveUserEmail are async functions
+Both queries will be resolved in parallel 
+*/
+const async: Promise<string> = t`Hello ${retrieveUserName()} ${retrieveUserEmail()}`;
+```
+
+### Callable values
+
+- You can use any function without argument as a template value.
+- `t` will call the function and then handle it's `sync` or `async` state through the async support logic.
+
+```ts
+/*
+Asuming retrieveUserName and retrieveUserEmail are async functions with no arguments
+Both queries will be called and resolved in parallel 
+*/
+const async: Promise<string> = t`Hello ${retrieveUserName} ${retrieveUserEmail}`;
+```
+
+### Arrays
+
+- Array values are resolved in parrallel with `Promise.all`
+- The resulting strings are joined with a newline
+- The indentation is preserved for each line
+
+```ts
+const items = [Promise.resolve("Hello"), Promise.resolve("World")];
+
+const text: Promise<string> = t`
+  This is a list of items:
+    ${items}
+`;
+
+console.log(await text);
+```
+
+Will output:
+
+```plain
+This is a list of items:
+  Hello
+  World
+```
+
+### Extra objects
+
+> [!NOTE]
+> This feature was built to seemlessly integrate inline content blocks in LLM messages.
+> e.g. Adding images, tool responses, etc.
+
+- `t` is able to handle non-string objects as values. As long as they have a `type` property.
+  - The value will be `JSON.stringify`ed and added to the template.
+  - The returned value will be `string & { __extra: TExtraObject }`
+- The value can then be accessed through the `tParse(resultingString)` property.
+- You can constrain the type of the extra object by using a type assertion from `Text.String`
+- You can infer the value type of the extra object by using a type assertion from `Text.ExtraObject.Infer`
+
+```ts
+import { t, tParse, type Text } from "@pairprog/text";
+
+// @ts-expect-error - The non-matching extra object will be rejected
+const textFail: Text.String<{ type: "extra"; value: string }> =
+  t`Hello ${{ type: "other-type" as const, value: "Hello" }} World`;
+
+// string & { __extra: { type: "extra"; value: string } } is equivalent to 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

@@ -0,0 +1,136 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/text.index.ts
+var text_index_exports = {};
+__export(text_index_exports, {
+  TextParseExtraItemException: () => TextParseExtraItemException,
+  t: () => t,
+  tParse: () => tParse
+});
+module.exports = __toCommonJS(text_index_exports);
+
+// src/text.lib.ts
+var import_json = require("@synstack/json");
+var import_resolved = require("@synstack/resolved");
+var import_callable = require("@synstack/resolved/callable");
+var import_str = require("@synstack/str");
+var Text = class _Text {
+  static EXTRA_OBJECT_PREFIX = "%STR_EXTRA%";
+  static EXTRA_OBJECT_SUFFIX = "%!STR_EXTRA%";
+  _options;
+  constructor(options = {}) {
+    this._options = {
+      joinString: options.joinString ?? "\n"
+    };
+  }
+  static options(config = {}) {
+    return new _Text(config);
+  }
+  options(config) {
+    return new _Text({ ...this._options, ...config });
+  }
+  static t(template, ...values) {
+    return _Text.options().t(template, ...values);
+  }
+  t(template, ...values) {
+    if (template.length === 0) return "";
+    const resolvedValues = import_callable.callable.resolveNested(values);
+    return import_resolved.resolvable.pipe(resolvedValues)._((values2) => {
+      let text = template[0];
+      for (let i = 0; i < values2.length; i++) {
+        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 = _Text.wrapValue(value);
+        }
+        const nextString = template[i + 1];
+        const lastLine = (0, import_str.str)(text).lastLine();
+        const indentation = lastLine.isEmpty() ? lastLine.leadingSpacesCount() : 0;
+        text = (0, import_str.str)(text).chopEnd(indentation).toString() + (0, import_str.str)(wrappedValue).indent(indentation).toString() + nextString;
+      }
+      return (0, import_str.str)(text).chopEmptyLinesStart().trimEnd().dedent().trimEmptyLines().chopRepeatNewlines(2).toString();
+    }).$;
+  }
+  static wrapValue(value) {
+    if (value === null || value === void 0) return "";
+    if (typeof value === "object") {
+      if (!Object.hasOwn(value, "type")) {
+        throw new Error(
+          'Text templating only supports objects with a "type" property'
+        );
+      }
+      return `${_Text.EXTRA_OBJECT_PREFIX}${JSON.stringify(value)}${_Text.EXTRA_OBJECT_SUFFIX}`;
+    }
+    return value;
+  }
+  static parse(text) {
+    const regex = new RegExp(
+      _Text.EXTRA_OBJECT_PREFIX + "(.*?)" + _Text.EXTRA_OBJECT_SUFFIX,
+      "g"
+    );
+    const parts = [];
+    let lastIndex = 0;
+    let match;
+    while ((match = regex.exec(text)) !== null) {
+      if (match.index > lastIndex) {
+        parts.push(text.slice(lastIndex, match.index));
+      }
+      try {
+        const jsonObject = import_json.json.deserialize(match[1]);
+        parts.push(jsonObject);
+      } catch (error) {
+        throw new TextParseExtraItemException(match[1], error);
+      }
+      lastIndex = regex.lastIndex;
+    }
+    if (lastIndex < text.length) {
+      parts.push(text.slice(lastIndex));
+    }
+    return parts;
+  }
+};
+var TextParseExtraItemException = class extends Error {
+  constructor(itemString, cause) {
+    super(
+      `
+Failed to parse extra item serialized value
+
+Value:
+${(0, import_str.str)(itemString).indent(2).toString()}
+
+Cause:
+${(0, import_str.str)(cause instanceof Error ? cause.message : cause).indent(2).toString()}
+
+`.trimStart(),
+      { cause }
+    );
+  }
+};
+var t = Text.t;
+var tParse = Text.parse;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TextParseExtraItemException,
+  t,
+  tParse
+});
+//# sourceMappingURL=text.index.cjs.map

package/dist/text.index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/text.index.ts","../src/text.lib.ts"],"sourcesContent":["export * from \"./text.bundle\";\nexport { TextParseExtraItemException } from \"./text.lib\";\nexport type { Text } from \"./text.lib\";\n","import { MaybeArray } from \"@shared/src/ts.utils\";\nimport { json } from \"@synstack/json\";\nimport { resolvable } from \"@synstack/resolved\";\nimport { callable, type CallableResolvable } from \"@synstack/resolved/callable\";\nimport { str } from \"@synstack/str\";\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"]}

package/dist/text.index.d.cts

@@ -0,0 +1,65 @@
+import { CallableResolvable } from '@synstack/resolved/callable';
+
+/**
+ * Allows using an array or a single value
+ */
+type MaybeArray<T> = T | T[];
+
+declare class Text {
+    private static EXTRA_OBJECT_PREFIX;
+    private static EXTRA_OBJECT_SUFFIX;
+    private readonly _options;
+    private constructor();
+    static options(this: void, config?: Text.Options): Text;
+    options(config: Text.Options): Text;
+    static t<T extends Array<Text.TemplateValue.Base>>(this: void, template: TemplateStringsArray, ...values: T): Text.Return<T>;
+    t<T extends Array<Text.TemplateValue.Base>>(template: TemplateStringsArray, ...values: T): Text.Return<T>;
+    private static wrapValue;
+    static parse<E extends Text.ExtraObject.Base>(this: void, text: Text.String<E>): Array<string | E>;
+}
+declare namespace Text {
+    type Options = {
+        joinString?: string;
+    };
+    type OptionalString = string | undefined | null;
+    type String<TExtraObject extends Text.ExtraObject.Base = never> = string & {
+        __extra: TExtraObject;
+    };
+    namespace ExtraObject {
+        type Base = {
+            type: string;
+        };
+        type InferExtraObjectValue<T> = T extends Text.OptionalString ? never : T;
+        type InferExtraObjectCallableResolvable<T> = InferExtraObjectValue<CallableResolvable.Infer<T>>;
+        type InferExtraArrayable<T> = T extends Array<any> ? {
+            [K in keyof T]: InferExtraObjectCallableResolvable<T[K]>;
+        }[number] : InferExtraObjectCallableResolvable<T>;
+        type Infer<T extends any[]> = {
+            [K in keyof T]: InferExtraArrayable<T[K]>;
+        }[number];
+    }
+    type Value<TExtraObject extends Text.ExtraObject.Base = never> = Text.OptionalString | TExtraObject;
+    namespace Value {
+        type Base = OptionalString | ExtraObject.Base;
+    }
+    type TemplateValue<TExtraObject extends Text.ExtraObject.Base = never> = CallableResolvable.MaybeArray<Value<TExtraObject>>;
+    namespace TemplateValue {
+        type Base = TemplateValue<ExtraObject.Base>;
+        type Resolved<TExtraObject extends Text.ExtraObject.Base = never> = MaybeArray<Value<TExtraObject>>;
+        namespace Resolved {
+            type Base = Resolved<ExtraObject.Base>;
+        }
+    }
+    type Return<T extends Array<Text.TemplateValue.Base>> = true extends CallableResolvable.MaybeArray.ArrayOf.IsPromise<T> ? Promise<string & {
+        __extra: ExtraObject.Infer<T>;
+    }> : string & {
+        __extra: ExtraObject.Infer<T>;
+    };
+}
+declare class TextParseExtraItemException extends Error {
+    constructor(itemString: string, cause: any);
+}
+declare const t: typeof Text.t;
+declare const tParse: typeof Text.parse;
+
+export { Text, TextParseExtraItemException, t, tParse };

package/dist/text.index.d.ts

@@ -0,0 +1,65 @@
+import { CallableResolvable } from '@synstack/resolved/callable';
+
+/**
+ * Allows using an array or a single value
+ */
+type MaybeArray<T> = T | T[];
+
+declare class Text {
+    private static EXTRA_OBJECT_PREFIX;
+    private static EXTRA_OBJECT_SUFFIX;
+    private readonly _options;
+    private constructor();
+    static options(this: void, config?: Text.Options): Text;
+    options(config: Text.Options): Text;
+    static t<T extends Array<Text.TemplateValue.Base>>(this: void, template: TemplateStringsArray, ...values: T): Text.Return<T>;
+    t<T extends Array<Text.TemplateValue.Base>>(template: TemplateStringsArray, ...values: T): Text.Return<T>;
+    private static wrapValue;
+    static parse<E extends Text.ExtraObject.Base>(this: void, text: Text.String<E>): Array<string | E>;
+}
+declare namespace Text {
+    type Options = {
+        joinString?: string;
+    };
+    type OptionalString = string | undefined | null;
+    type String<TExtraObject extends Text.ExtraObject.Base = never> = string & {
+        __extra: TExtraObject;
+    };
+    namespace ExtraObject {
+        type Base = {
+            type: string;
+        };
+        type InferExtraObjectValue<T> = T extends Text.OptionalString ? never : T;
+        type InferExtraObjectCallableResolvable<T> = InferExtraObjectValue<CallableResolvable.Infer<T>>;
+        type InferExtraArrayable<T> = T extends Array<any> ? {
+            [K in keyof T]: InferExtraObjectCallableResolvable<T[K]>;
+        }[number] : InferExtraObjectCallableResolvable<T>;
+        type Infer<T extends any[]> = {
+            [K in keyof T]: InferExtraArrayable<T[K]>;
+        }[number];
+    }
+    type Value<TExtraObject extends Text.ExtraObject.Base = never> = Text.OptionalString | TExtraObject;
+    namespace Value {
+        type Base = OptionalString | ExtraObject.Base;
+    }
+    type TemplateValue<TExtraObject extends Text.ExtraObject.Base = never> = CallableResolvable.MaybeArray<Value<TExtraObject>>;
+    namespace TemplateValue {
+        type Base = TemplateValue<ExtraObject.Base>;
+        type Resolved<TExtraObject extends Text.ExtraObject.Base = never> = MaybeArray<Value<TExtraObject>>;
+        namespace Resolved {
+            type Base = Resolved<ExtraObject.Base>;
+        }
+    }
+    type Return<T extends Array<Text.TemplateValue.Base>> = true extends CallableResolvable.MaybeArray.ArrayOf.IsPromise<T> ? Promise<string & {
+        __extra: ExtraObject.Infer<T>;
+    }> : string & {
+        __extra: ExtraObject.Infer<T>;
+    };
+}
+declare class TextParseExtraItemException extends Error {
+    constructor(itemString: string, cause: any);
+}
+declare const t: typeof Text.t;
+declare const tParse: typeof Text.parse;
+
+export { Text, TextParseExtraItemException, t, tParse };

package/dist/text.index.js

@@ -0,0 +1,107 @@
+// src/text.lib.ts
+import { json } from "@synstack/json";
+import { resolvable } from "@synstack/resolved";
+import { callable } from "@synstack/resolved/callable";
+import { str } from "@synstack/str";
+var Text = class _Text {
+  static EXTRA_OBJECT_PREFIX = "%STR_EXTRA%";
+  static EXTRA_OBJECT_SUFFIX = "%!STR_EXTRA%";
+  _options;
+  constructor(options = {}) {
+    this._options = {
+      joinString: options.joinString ?? "\n"
+    };
+  }
+  static options(config = {}) {
+    return new _Text(config);
+  }
+  options(config) {
+    return new _Text({ ...this._options, ...config });
+  }
+  static t(template, ...values) {
+    return _Text.options().t(template, ...values);
+  }
+  t(template, ...values) {
+    if (template.length === 0) return "";
+    const resolvedValues = callable.resolveNested(values);
+    return resolvable.pipe(resolvedValues)._((values2) => {
+      let text = template[0];
+      for (let i = 0; i < values2.length; i++) {
+        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 = _Text.wrapValue(value);
+        }
+        const nextString = template[i + 1];
+        const lastLine = str(text).lastLine();
+        const indentation = lastLine.isEmpty() ? lastLine.leadingSpacesCount() : 0;
+        text = str(text).chopEnd(indentation).toString() + str(wrappedValue).indent(indentation).toString() + nextString;
+      }
+      return str(text).chopEmptyLinesStart().trimEnd().dedent().trimEmptyLines().chopRepeatNewlines(2).toString();
+    }).$;
+  }
+  static wrapValue(value) {
+    if (value === null || value === void 0) return "";
+    if (typeof value === "object") {
+      if (!Object.hasOwn(value, "type")) {
+        throw new Error(
+          'Text templating only supports objects with a "type" property'
+        );
+      }
+      return `${_Text.EXTRA_OBJECT_PREFIX}${JSON.stringify(value)}${_Text.EXTRA_OBJECT_SUFFIX}`;
+    }
+    return value;
+  }
+  static parse(text) {
+    const regex = new RegExp(
+      _Text.EXTRA_OBJECT_PREFIX + "(.*?)" + _Text.EXTRA_OBJECT_SUFFIX,
+      "g"
+    );
+    const parts = [];
+    let lastIndex = 0;
+    let match;
+    while ((match = regex.exec(text)) !== null) {
+      if (match.index > lastIndex) {
+        parts.push(text.slice(lastIndex, match.index));
+      }
+      try {
+        const jsonObject = json.deserialize(match[1]);
+        parts.push(jsonObject);
+      } catch (error) {
+        throw new TextParseExtraItemException(match[1], error);
+      }
+      lastIndex = regex.lastIndex;
+    }
+    if (lastIndex < text.length) {
+      parts.push(text.slice(lastIndex));
+    }
+    return parts;
+  }
+};
+var TextParseExtraItemException = class extends Error {
+  constructor(itemString, cause) {
+    super(
+      `
+Failed to parse extra item serialized value
+
+Value:
+${str(itemString).indent(2).toString()}
+
+Cause:
+${str(cause instanceof Error ? cause.message : cause).indent(2).toString()}
+
+`.trimStart(),
+      { cause }
+    );
+  }
+};
+var t = Text.t;
+var tParse = Text.parse;
+export {
+  TextParseExtraItemException,
+  t,
+  tParse
+};
+//# sourceMappingURL=text.index.js.map

package/dist/text.index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/text.lib.ts"],"sourcesContent":["import { MaybeArray } from \"@shared/src/ts.utils\";\nimport { json } from \"@synstack/json\";\nimport { resolvable } from \"@synstack/resolved\";\nimport { callable, type CallableResolvable } from \"@synstack/resolved/callable\";\nimport { str } from \"@synstack/str\";\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":";AACA,SAAS,YAAY;AACrB,SAAS,kBAAkB;AAC3B,SAAS,gBAAyC;AAClD,SAAS,WAAW;AAEb,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;AAEO,IAAM,IAAI,KAAK;AACf,IAAM,SAAS,KAAK;","names":["values"]}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@synstack/text",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "yarn@4.4.0",
+  "version": "1.0.1-alpha.0",
+  "description": "String templating as it was meant to be",
+  "keywords": [
+    "string",
+    "typescript",
+    "ts",
+    "templating",
+    "template",
+    "interpolation",
+    "llm",
+    "prompt",
+    "ai"
+  ],
+  "author": {
+    "name": "pAIrprog",
+    "url": "https://pairprog.io"
+  },
+  "homepage": "https://github.com/pAIrprogio/synscript/tree/main/packages/text",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pAIrprogio/syn-stack.git",
+    "directory": "packages/text"
+  },
+  "license": "Apache-2.0",
+  "scripts": {
+    "publish": "yarn npm publish --access public",
+    "prepublish": "yarn test && yarn build",
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "test:types": "tsc --noEmit",
+    "test:unit": "node --import tsx --test src/**/*.test.ts",
+    "test:unit:watch": "node --import tsx --watch --test src/**/*.test.ts",
+    "test": "yarn test:types && yarn test:unit"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/text.index.d.ts",
+        "default": "./dist/text.index.js"
+      },
+      "require": {
+        "types": "./dist/text.index.d.cts",
+        "default": "./dist/text.index.cjs"
+      }
+    }
+  },
+  "dependencies": {
+    "@synstack/json": "1.0.0",
+    "@synstack/resolved": "1.0.0",
+    "@synstack/str": "1.0.1-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.1",
+    "typescript": "^5.6.2"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "dist/**/*"
+  ],
+  "gitHead": "7a58577491cf08e6aad885b39c70bbd564b721b4"
+}

package/src/text.bundle.ts

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

package/src/text.index.ts

@@ -0,0 +1,3 @@
+export * from "./text.bundle";
+export { TextParseExtraItemException } from "./text.lib";
+export type { Text } from "./text.lib";

package/src/text.lib.ts

@@ -0,0 +1,215 @@
+import { MaybeArray } from "@shared/src/ts.utils";
+import { json } from "@synstack/json";
+import { resolvable } from "@synstack/resolved";
+import { callable, type CallableResolvable } from "@synstack/resolved/callable";
+import { str } from "@synstack/str";
+
+export class Text {
+  private static EXTRA_OBJECT_PREFIX = "%STR_EXTRA%";
+  private static EXTRA_OBJECT_SUFFIX = "%!STR_EXTRA%";
+
+  private readonly _options: {
+    joinString: string;
+  };
+
+  private constructor(options: Text.Options = {}) {
+    this._options = {
+      joinString: options.joinString ?? "\n",
+    };
+  }
+
+  public static options(this: void, config: Text.Options = {}) {
+    return new Text(config);
+  }
+
+  public options(config: Text.Options) {
+    return new Text({ ...this._options, ...config });
+  }
+
+  public static t<T extends Array<Text.TemplateValue.Base>>(
+    this: void,
+    template: TemplateStringsArray,
+    ...values: T
+  ): Text.Return<T> {
+    return Text.options().t(template, ...values);
+  }
+
+  public t<T extends Array<Text.TemplateValue.Base>>(
+    template: TemplateStringsArray,
+    ...values: T
+  ): Text.Return<T> {
+    // @ts-expect-error - Of course the default value is ""
+    if (template.length === 0) return "";
+
+    const resolvedValues = callable.resolveNested(values);
+    return resolvable.pipe(resolvedValues)._((values) => {
+      let text = template[0];
+
+      for (let i = 0; i < values.length; i++) {
+        const value = values[i];
+        let wrappedValue = "";
+
+        if (Array.isArray(value)) {
+          wrappedValue = value
+            .filter((inner) => inner !== null || inner !== undefined)
+            .map(Text.wrapValue)
+            .join(this._options.joinString);
+        } else {
+          wrappedValue = Text.wrapValue(value);
+        }
+        const nextString = template[i + 1];
+        const lastLine = str(text).lastLine();
+        const indentation = lastLine.isEmpty()
+          ? lastLine.leadingSpacesCount()
+          : 0;
+        text =
+          str(text).chopEnd(indentation).toString() +
+          str(wrappedValue).indent(indentation).toString() +
+          nextString;
+      }
+
+      return str(text)
+        .chopEmptyLinesStart()
+        .trimEnd()
+        .dedent()
+        .trimEmptyLines()
+        .chopRepeatNewlines(2)
+        .toString() as string & {
+        __extra: Text.ExtraObject.Infer<T>;
+      };
+    }).$ as Text.Return<T>;
+  }
+
+  private static wrapValue(this: void, value: Text.Value.Base) {
+    if (value === null || value === undefined) return "";
+    if (typeof value === "object") {
+      if (!Object.hasOwn(value, "type")) {
+        throw new Error(
+          'Text templating only supports objects with a "type" property',
+        );
+      }
+      return `${Text.EXTRA_OBJECT_PREFIX}${JSON.stringify(value)}${
+        Text.EXTRA_OBJECT_SUFFIX
+      }`;
+    }
+    return value;
+  }
+
+  public static parse<E extends Text.ExtraObject.Base>(
+    this: void,
+    text: Text.String<E>,
+  ): Array<string | E> {
+    const regex = new RegExp(
+      Text.EXTRA_OBJECT_PREFIX + "(.*?)" + Text.EXTRA_OBJECT_SUFFIX,
+      "g",
+    );
+    const parts: Array<string | E> = [];
+    let lastIndex = 0;
+    let match;
+
+    while ((match = regex.exec(text)) !== null) {
+      // Add the text before the match
+      if (match.index > lastIndex) {
+        parts.push(text.slice(lastIndex, match.index));
+      }
+
+      // Parse and add the JSON object
+      try {
+        const jsonObject = json.deserialize<E>(match[1]);
+        parts.push(jsonObject);
+      } catch (error) {
+        throw new TextParseExtraItemException(match[1], error);
+      }
+
+      lastIndex = regex.lastIndex;
+    }
+
+    // Add any remaining text after the last match
+    if (lastIndex < text.length) {
+      parts.push(text.slice(lastIndex));
+    }
+
+    return parts;
+  }
+}
+
+export declare namespace Text {
+  export type Options = {
+    joinString?: string;
+  };
+
+  export type OptionalString = string | undefined | null;
+
+  export type String<TExtraObject extends Text.ExtraObject.Base = never> =
+    string & {
+      __extra: TExtraObject;
+    };
+
+  export namespace ExtraObject {
+    export type Base = { type: string };
+
+    type InferExtraObjectValue<T> = T extends Text.OptionalString ? never : T;
+    type InferExtraObjectCallableResolvable<T> = InferExtraObjectValue<
+      CallableResolvable.Infer<T>
+    >;
+    type InferExtraArrayable<T> =
+      T extends Array<any>
+        ? { [K in keyof T]: InferExtraObjectCallableResolvable<T[K]> }[number]
+        : InferExtraObjectCallableResolvable<T>;
+
+    export type Infer<T extends any[]> = {
+      // Check if it's an array
+      [K in keyof T]: InferExtraArrayable<T[K]>;
+    }[number];
+  }
+
+  export type Value<TExtraObject extends Text.ExtraObject.Base = never> =
+    | Text.OptionalString
+    | TExtraObject;
+
+  export namespace Value {
+    export type Base = OptionalString | ExtraObject.Base;
+  }
+
+  export type TemplateValue<
+    TExtraObject extends Text.ExtraObject.Base = never,
+  > = CallableResolvable.MaybeArray<Value<TExtraObject>>;
+
+  export namespace TemplateValue {
+    export type Base = TemplateValue<ExtraObject.Base>;
+
+    export type Resolved<TExtraObject extends Text.ExtraObject.Base = never> =
+      MaybeArray<Value<TExtraObject>>;
+    export namespace Resolved {
+      export type Base = Resolved<ExtraObject.Base>;
+    }
+  }
+
+  export type Return<T extends Array<Text.TemplateValue.Base>> =
+    true extends CallableResolvable.MaybeArray.ArrayOf.IsPromise<T>
+      ? Promise<string & { __extra: ExtraObject.Infer<T> }>
+      : string & { __extra: ExtraObject.Infer<T> };
+}
+
+export class TextParseExtraItemException extends Error {
+  constructor(itemString: string, cause: any) {
+    super(
+      `
+Failed to parse extra item serialized value
+
+Value:
+${str(itemString).indent(2).toString()}
+
+Cause:
+${str(cause instanceof Error ? cause.message : (cause as string))
+  .indent(2)
+  .toString()}
+
+`.trimStart(),
+      { cause },
+    );
+  }
+}
+
+export const t = Text.t;
+export const tParse = Text.parse;