@gringow/gringow 0.2.1 → 0.3.0

package/README.md

@@ -335,14 +335,15 @@ pnpm run test
 pnpm run test:watch
 ```
 
-## Integrations
+## Related Packages
 
-Gringow has official integrations for modern web frameworks:
+Gringow provides a complete ecosystem for AI-powered translation:
 
-- **[@gringow/gringow-cli](https://www.npmjs.com/package/@gringow/gringow-cli)** - Command-line interface for cache management and translations
-- **[@gringow/gringow-vite](https://www.npmjs.com/package/@gringow/gringow-vite)** - Vite plugin for build-time translation extraction
+- **[@gringow/gringow](https://www.npmjs.com/package/@gringow/gringow)** - Core translation library
+- **[@gringow/gringow-vite](https://www.npmjs.com/package/@gringow/gringow-vite)** - Vite plugin for build-time extraction
 - **[@gringow/gringow-react](https://www.npmjs.com/package/@gringow/gringow-react)** - React hooks and components
-- **[@gringow/gringow-shadow](https://www.npmjs.com/package/@gringow/gringow-shadow)** - Web Component layer (vanilla JS)
+- **[@gringow/gringow-shadow](https://www.npmjs.com/package/@gringow/gringow-shadow)** - Web Component layer
+- **[@gringow/gringow-cli](https://www.npmjs.com/package/@gringow/gringow-cli)** - CLI tool
 - **[@gringow/gringow-nextjs](https://www.npmjs.com/package/@gringow/gringow-nextjs)** - Next.js plugin (experimental)
 
 ## Related Resources

package/dist/browser.d.mts

@@ -1,5 +1,4 @@
 export { createCacheId } from './create-cache-id.mjs';
-export { flatTemplateString } from './flat-template-string.mjs';
 export { interpolateTemplate } from './interpolate-template.mjs';
 
 declare const GRINGOW_IO_URL = "https://gringow.io";

package/dist/browser.mjs

@@ -44,42 +44,43 @@ function md5(input) {
   return state.map(toHex).join("");
 }
 
-// src/create-cache-id.ts
-function createCacheId(text) {
-  const hexHash = md5(text);
-  const cacheId = `gid_${hexHash}`;
-  return cacheId;
-}
-
-// src/flat-template-string.ts
-function flatTemplateString(givenStrings, givenValues) {
-  const strings = [...givenStrings.raw];
-  const values = [...givenValues];
-  const flatted = strings.reduce((acc, item, index) => {
+// src/interpolate-template.ts
+function ifArray(template, givenValues) {
+  const strings = [...template.raw];
+  const hasValues = givenValues !== void 0;
+  return strings.reduce((acc, item, index) => {
     acc += String(item ?? "");
-    if (index < values.length) {
-      const value = values[index];
-      acc += String(value ?? "");
+    if (index < strings.length - 1) {
+      acc += hasValues ? String(givenValues[index] ?? "") : `\${${index}}`;
     }
     return acc;
   }, "");
-  return flatted;
 }
-
-// src/interpolate-template.ts
-function interpolateTemplate(template, values) {
-  if (!values || values.length === 0) return template;
+function ifString(template, givenValues) {
+  if (template?.indexOf("${") === -1) return template;
   let valueIndex = 0;
   return template.replace(/\$\{[^}]*\}/g, () => {
-    if (valueIndex < values.length) {
-      const value = values[valueIndex++];
-      return value === null || value === void 0 ? "" : String(value);
-    }
-    return "";
+    const value = givenValues?.[valueIndex];
+    const output = value === null || value === void 0 ? `\${${valueIndex}}` : String(value);
+    valueIndex++;
+    return output;
   });
 }
+function interpolateTemplate(template, givenValues) {
+  if (typeof template === "string") return ifString(template, givenValues);
+  if (Array.isArray(template)) return ifArray(template, givenValues);
+  throw new Error("Template must be a string or TemplateStringsArray");
+}
+
+// src/create-cache-id.ts
+function createCacheId(text) {
+  const interpolatedText = interpolateTemplate(text);
+  const hexHash = md5(interpolatedText);
+  const cacheId = `gid_${hexHash}`;
+  return cacheId;
+}
 
 // src/browser.ts
 var GRINGOW_IO_URL = "https://gringow.io";
 
-export { GRINGOW_IO_URL, createCacheId, flatTemplateString, interpolateTemplate };
+export { GRINGOW_IO_URL, createCacheId, interpolateTemplate };

package/dist/config.d.mts

@@ -41,12 +41,12 @@ declare const awaitedConfig: Promise<{
     llm: {
         provider: "anthropic" | "gemini" | "openai" | "groq" | "mistral" | "ollama" | "xai" | "deepseek" | "openrouter" | "cerebras" | "lmstudio" | "azure" | "meta";
         model: string | null;
+        prePrompt?: string | undefined;
+        postPrompt?: string | undefined;
         apiKey?: string | undefined;
         baseURL?: string | undefined;
         temperature?: number | undefined;
         sleep?: number | undefined;
-        prePrompt?: string | undefined;
-        postPrompt?: string | undefined;
         prePromptReplace?: string | undefined;
         postPromptReplace?: string | undefined;
         prePromptAppend?: string | undefined;

package/dist/create-cache-id.mjs

@@ -44,9 +44,37 @@ function md5(input) {
   return state.map(toHex).join("");
 }
 
+// src/interpolate-template.ts
+function ifArray(template, givenValues) {
+  const strings = [...template.raw];
+  return strings.reduce((acc, item, index) => {
+    acc += String(item ?? "");
+    if (index < strings.length - 1) {
+      acc += `\${${index}}`;
+    }
+    return acc;
+  }, "");
+}
+function ifString(template, givenValues) {
+  if (template?.indexOf("${") === -1) return template;
+  let valueIndex = 0;
+  return template.replace(/\$\{[^}]*\}/g, () => {
+    const value = givenValues?.[valueIndex];
+    const output = value === null || value === void 0 ? `\${${valueIndex}}` : String(value);
+    valueIndex++;
+    return output;
+  });
+}
+function interpolateTemplate(template, givenValues) {
+  if (typeof template === "string") return ifString(template, givenValues);
+  if (Array.isArray(template)) return ifArray(template);
+  throw new Error("Template must be a string or TemplateStringsArray");
+}
+
 // src/create-cache-id.ts
 function createCacheId(text) {
-  const hexHash = md5(text);
+  const interpolatedText = interpolateTemplate(text);
+  const hexHash = md5(interpolatedText);
   const cacheId = `gid_${hexHash}`;
   return cacheId;
 }

package/dist/create-cache-id.test.mjs

@@ -18164,9 +18164,36 @@ function md5(input) {
   return state.map(toHex).join("");
 }
 
+// src/interpolate-template.ts
+function ifArray(template, givenValues) {
+  const strings = [...template.raw];
+  return strings.reduce((acc, item, index) => {
+    acc += String(item ?? "");
+    if (index < strings.length - 1) {
+      acc += `\${${index}}`;
+    }
+    return acc;
+  }, "");
+}
+function ifString(template, givenValues) {
+  if (template?.indexOf("${") === -1) return template;
+  let valueIndex = 0;
+  return template.replace(/\$\{[^}]*\}/g, () => {
+    const output = `\${${valueIndex}}` ;
+    valueIndex++;
+    return output;
+  });
+}
+function interpolateTemplate(template, givenValues) {
+  if (typeof template === "string") return ifString(template);
+  if (Array.isArray(template)) return ifArray(template);
+  throw new Error("Template must be a string or TemplateStringsArray");
+}
+
 // src/create-cache-id.ts
 function createCacheId(text) {
-  const hexHash = md5(text);
+  const interpolatedText = interpolateTemplate(text);
+  const hexHash = md5(interpolatedText);
   const cacheId = `gid_${hexHash}`;
   return cacheId;
 }

package/dist/data/check-cache.d.mts

@@ -6,4 +6,4 @@ import '../schemas/config.shcema.mjs';
 import '../create-cache-id.mjs';
 import './clear-cache.mjs';
 import './get-cache.mjs';
-import '../flat-template-string.mjs';
+import '../interpolate-template.mjs';

package/dist/data/check-cache.mjs

@@ -1,11 +1,11 @@
-import fs from 'fs/promises';
 import { cosmiconfig } from 'cosmiconfig';
 import merge from 'lodash.merge';
 import { z } from 'zod';
+import fs from 'fs/promises';
 import { dirname, resolve, parse } from 'path';
 import { mkdir, stat, statSync, mkdirSync } from 'fs';
 
-// src/data/get-cache.ts
+// src/config.ts
 
 // src/constants/default-config.ts
 var defaultConfig = {
@@ -425,8 +425,9 @@ async function getOrCreateCache() {
 // src/data/check-cache.ts
 async function checkCache(cacheId) {
   const cache = await getOrCreateCache();
+  const config = await awaitedConfig;
   if (cache?.[cacheId]) {
-    console.log(`Cache hit, id:${cacheId}`);
+    if (config.debug) console.log(`Cache hit, id:${cacheId}`);
     return cache[cacheId];
   }
   return void 0;

package/dist/data/delete-cache-item.d.mts

@@ -6,4 +6,4 @@ import '../schemas/config.shcema.mjs';
 import '../create-cache-id.mjs';
 import './clear-cache.mjs';
 import './get-cache.mjs';
-import '../flat-template-string.mjs';
+import '../interpolate-template.mjs';

package/dist/data/get-or-create-cache.d.mts

@@ -6,4 +6,4 @@ import '../schemas/config.shcema.mjs';
 import '../create-cache-id.mjs';
 import './clear-cache.mjs';
 import './get-cache.mjs';
-import '../flat-template-string.mjs';
+import '../interpolate-template.mjs';

package/dist/data/save-cache.d.mts

@@ -6,7 +6,7 @@ import '../schemas/config.shcema.mjs';
 import '../create-cache-id.mjs';
 import './clear-cache.mjs';
 import './get-cache.mjs';
-import '../flat-template-string.mjs';
+import '../interpolate-template.mjs';
 
 /**
  * Saves the cache to disk.

package/dist/data/write-cache-to-disk.d.mts

@@ -6,4 +6,4 @@ import '../schemas/config.shcema.mjs';
 import '../create-cache-id.mjs';
 import './clear-cache.mjs';
 import './get-cache.mjs';
-import '../flat-template-string.mjs';
+import '../interpolate-template.mjs';

package/dist/gringow.d.mts

@@ -6,4 +6,4 @@ import './schemas/config.shcema.mjs';
 import './create-cache-id.mjs';
 import './data/clear-cache.mjs';
 import './data/get-cache.mjs';
-import './flat-template-string.mjs';
+import './interpolate-template.mjs';

package/dist/gringow.mjs

@@ -215,9 +215,38 @@ function md5(input) {
   return state.map(toHex).join("");
 }
 
+// src/interpolate-template.ts
+function ifArray(template, givenValues) {
+  const strings = [...template.raw];
+  const hasValues = givenValues !== void 0;
+  return strings.reduce((acc, item, index) => {
+    acc += String(item ?? "");
+    if (index < strings.length - 1) {
+      acc += hasValues ? String(givenValues[index] ?? "") : `\${${index}}`;
+    }
+    return acc;
+  }, "");
+}
+function ifString(template, givenValues) {
+  if (template?.indexOf("${") === -1) return template;
+  let valueIndex = 0;
+  return template.replace(/\$\{[^}]*\}/g, () => {
+    const value = givenValues?.[valueIndex];
+    const output = value === null || value === void 0 ? `\${${valueIndex}}` : String(value);
+    valueIndex++;
+    return output;
+  });
+}
+function interpolateTemplate(template, givenValues) {
+  if (typeof template === "string") return ifString(template, givenValues);
+  if (Array.isArray(template)) return ifArray(template, givenValues);
+  throw new Error("Template must be a string or TemplateStringsArray");
+}
+
 // src/create-cache-id.ts
 function createCacheId(text) {
-  const hexHash = md5(text);
+  const interpolatedText = interpolateTemplate(text);
+  const hexHash = md5(interpolatedText);
   const cacheId = `gid_${hexHash}`;
   return cacheId;
 }
@@ -479,8 +508,9 @@ async function getOrCreateCache() {
 // src/data/check-cache.ts
 async function checkCache(cacheId) {
   const cache = await getOrCreateCache();
+  const config = await awaitedConfig;
   if (cache?.[cacheId]) {
-    console.log(`Cache hit, id:${cacheId}`);
+    if (config.debug) console.log(`Cache hit, id:${cacheId}`);
     return cache[cacheId];
   }
   return void 0;
@@ -493,21 +523,6 @@ async function writeCacheToDisk(cacheId, cached) {
   await saveCache(cache);
   return cache[cacheId];
 }
-
-// src/flat-template-string.ts
-function flatTemplateString(givenStrings, givenValues) {
-  const strings = [...givenStrings.raw];
-  const values = [...givenValues];
-  const flatted = strings.reduce((acc, item, index) => {
-    acc += String(item ?? "");
-    if (index < values.length) {
-      const value = values[index];
-      acc += String(value ?? "");
-    }
-    return acc;
-  }, "");
-  return flatted;
-}
 var providerEngineMap = {
   anthropic: "anthropic",
   gemini: "google",
@@ -596,15 +611,10 @@ async function rebuild(cacheId) {
   }
   return { cacheId, translation: output };
 }
-async function Gringow(strings, ...values) {
+async function Gringow(text, ...values) {
   const config = await awaitedConfig;
-  let flatten;
-  if (typeof strings === "string") {
-    flatten = String(strings ?? "");
-  } else {
-    flatten = flatTemplateString(strings, values);
-  }
-  const cacheId = createCacheId(flatten);
+  const interpolated = interpolateTemplate(text.trim(), values);
+  const cacheId = createCacheId(interpolated);
   const cached = await checkCache(cacheId);
   if (cached !== void 0 && cached.original !== "undefined" && !cached.rebuild) {
     return { cacheId, translation: cached };
@@ -614,7 +624,7 @@ async function Gringow(strings, ...values) {
     console.log(`asking::prepend ${cacheId}:`, { prepend });
     console.log(`asking::append ${cacheId}:`, { append });
   }
-  const translation = await askLLM(flatten, prepend, append);
+  const translation = await askLLM(interpolated, prepend, append);
   const output = {
     ...translation,
     prepend: cached?.prepend ?? void 0,

package/dist/index.d.mts

@@ -2,7 +2,7 @@ export { awaitedConfig, getConfigSource, isLocalConfigFound } from './config.mjs
 export { createCacheId } from './create-cache-id.mjs';
 export { clearCache } from './data/clear-cache.mjs';
 export { getCache } from './data/get-cache.mjs';
-export { flatTemplateString } from './flat-template-string.mjs';
+export { interpolateTemplate } from './interpolate-template.mjs';
 export { GringowConfig } from './constants/default-config.mjs';
 import 'zod';
 import './schemas/config.shcema.mjs';
@@ -77,10 +77,10 @@ declare function rebuild(cacheId: string): Promise<GringowResponse>;
  * Gringow is a function that translates a string or a template string into a
  * translated string.
  *
- * @param strings - The string or template string to translate.
+ * @param text - The string or template string to translate.
  * @param values - The values to interpolate into the string.
  * @returns The translated string.
  */
-declare function Gringow(strings: TemplateStringsArray | string, ...values: Array<unknown>): Promise<GringowResponse>;
+declare function Gringow(text: string, ...values: Array<unknown>): Promise<GringowResponse>;
 
 export { type GringowCache, type GringowCacheItem, type GringowError, type GringowResponse, type GringowTranslation, checkCache, Gringow as default, deleteCacheItem, getOrCreateCache, rebuild, writeCacheToDisk };

package/dist/index.mjs

@@ -221,9 +221,38 @@ function md5(input) {
   return state.map(toHex).join("");
 }
 
+// src/interpolate-template.ts
+function ifArray(template, givenValues) {
+  const strings = [...template.raw];
+  const hasValues = givenValues !== void 0;
+  return strings.reduce((acc, item, index) => {
+    acc += String(item ?? "");
+    if (index < strings.length - 1) {
+      acc += hasValues ? String(givenValues[index] ?? "") : `\${${index}}`;
+    }
+    return acc;
+  }, "");
+}
+function ifString(template, givenValues) {
+  if (template?.indexOf("${") === -1) return template;
+  let valueIndex = 0;
+  return template.replace(/\$\{[^}]*\}/g, () => {
+    const value = givenValues?.[valueIndex];
+    const output = value === null || value === void 0 ? `\${${valueIndex}}` : String(value);
+    valueIndex++;
+    return output;
+  });
+}
+function interpolateTemplate(template, givenValues) {
+  if (typeof template === "string") return ifString(template, givenValues);
+  if (Array.isArray(template)) return ifArray(template, givenValues);
+  throw new Error("Template must be a string or TemplateStringsArray");
+}
+
 // src/create-cache-id.ts
 function createCacheId(text) {
-  const hexHash = md5(text);
+  const interpolatedText = interpolateTemplate(text);
+  const hexHash = md5(interpolatedText);
   const cacheId = `gid_${hexHash}`;
   return cacheId;
 }
@@ -485,8 +514,9 @@ async function getOrCreateCache() {
 // src/data/check-cache.ts
 async function checkCache(cacheId) {
   const cache = await getOrCreateCache();
+  const config = await awaitedConfig;
   if (cache?.[cacheId]) {
-    console.log(`Cache hit, id:${cacheId}`);
+    if (config.debug) console.log(`Cache hit, id:${cacheId}`);
     return cache[cacheId];
   }
   return void 0;
@@ -515,21 +545,6 @@ async function writeCacheToDisk(cacheId, cached) {
   await saveCache(cache);
   return cache[cacheId];
 }
-
-// src/flat-template-string.ts
-function flatTemplateString(givenStrings, givenValues) {
-  const strings = [...givenStrings.raw];
-  const values = [...givenValues];
-  const flatted = strings.reduce((acc, item, index) => {
-    acc += String(item ?? "");
-    if (index < values.length) {
-      const value = values[index];
-      acc += String(value ?? "");
-    }
-    return acc;
-  }, "");
-  return flatted;
-}
 var providerEngineMap = {
   anthropic: "anthropic",
   gemini: "google",
@@ -618,15 +633,10 @@ async function rebuild(cacheId) {
   }
   return { cacheId, translation: output };
 }
-async function Gringow(strings, ...values) {
+async function Gringow(text, ...values) {
   const config = await awaitedConfig;
-  let flatten;
-  if (typeof strings === "string") {
-    flatten = String(strings ?? "");
-  } else {
-    flatten = flatTemplateString(strings, values);
-  }
-  const cacheId = createCacheId(flatten);
+  const interpolated = interpolateTemplate(text.trim(), values);
+  const cacheId = createCacheId(interpolated);
   const cached = await checkCache(cacheId);
   if (cached !== void 0 && cached.original !== "undefined" && !cached.rebuild) {
     return { cacheId, translation: cached };
@@ -636,7 +646,7 @@ async function Gringow(strings, ...values) {
     console.log(`asking::prepend ${cacheId}:`, { prepend });
     console.log(`asking::append ${cacheId}:`, { append });
   }
-  const translation = await askLLM(flatten, prepend, append);
+  const translation = await askLLM(interpolated, prepend, append);
   const output = {
     ...translation,
     prepend: cached?.prepend ?? void 0,
@@ -648,4 +658,4 @@ async function Gringow(strings, ...values) {
   return { cacheId, translation: output };
 }
 
-export { awaitedConfig, checkCache, clearCache, createCacheId, Gringow as default, deleteCacheItem, flatTemplateString, getCache, getConfigSource, getOrCreateCache, isLocalConfigFound, rebuild, writeCacheToDisk };
+export { awaitedConfig, checkCache, clearCache, createCacheId, Gringow as default, deleteCacheItem, getCache, getConfigSource, getOrCreateCache, interpolateTemplate, isLocalConfigFound, rebuild, writeCacheToDisk };

package/dist/interpolate-template.d.mts

@@ -1,3 +1,3 @@
-declare function interpolateTemplate(template: string, values: unknown[]): string;
+declare function interpolateTemplate(template: TemplateStringsArray | string, givenValues?: unknown[]): string;
 
 export { interpolateTemplate };

package/dist/interpolate-template.mjs

@@ -1,14 +1,29 @@
 // src/interpolate-template.ts
-function interpolateTemplate(template, values) {
-  if (!values || values.length === 0) return template;
+function ifArray(template, givenValues) {
+  const strings = [...template.raw];
+  const hasValues = givenValues !== void 0;
+  return strings.reduce((acc, item, index) => {
+    acc += String(item ?? "");
+    if (index < strings.length - 1) {
+      acc += hasValues ? String(givenValues[index] ?? "") : `\${${index}}`;
+    }
+    return acc;
+  }, "");
+}
+function ifString(template, givenValues) {
+  if (template?.indexOf("${") === -1) return template;
   let valueIndex = 0;
   return template.replace(/\$\{[^}]*\}/g, () => {
-    if (valueIndex < values.length) {
-      const value = values[valueIndex++];
-      return value === null || value === void 0 ? "" : String(value);
-    }
-    return "";
+    const value = givenValues?.[valueIndex];
+    const output = value === null || value === void 0 ? `\${${valueIndex}}` : String(value);
+    valueIndex++;
+    return output;
   });
 }
+function interpolateTemplate(template, givenValues) {
+  if (typeof template === "string") return ifString(template, givenValues);
+  if (Array.isArray(template)) return ifArray(template, givenValues);
+  throw new Error("Template must be a string or TemplateStringsArray");
+}
 
 export { interpolateTemplate };

package/dist/{flat-template-string.test.mjs → interpolate-template.test.mjs}

@@ -18118,105 +18118,121 @@ function getImporter(name) {
 // ../node_modules/.pnpm/vitest@2.1.9_@types+node@22.16.4_lightningcss@1.30.2_msw@2.12.8_@types+node@22.16.4_typescript@5.7.3__terser@5.44.1/node_modules/vitest/dist/index.js
 __toESM(require_dist(), 1);
 
-// src/flat-template-string.ts
-function flatTemplateString(givenStrings, givenValues) {
-  const strings = [...givenStrings.raw];
-  const values = [...givenValues];
-  const flatted = strings.reduce((acc, item, index) => {
+// src/interpolate-template.ts
+function ifArray(template, givenValues) {
+  const strings = [...template.raw];
+  const hasValues = givenValues !== void 0;
+  return strings.reduce((acc, item, index) => {
     acc += String(item ?? "");
-    if (index < values.length) {
-      const value = values[index];
-      acc += String(value ?? "");
+    if (index < strings.length - 1) {
+      acc += hasValues ? String(givenValues[index] ?? "") : `\${${index}}`;
     }
     return acc;
   }, "");
-  return flatted;
+}
+function ifString(template, givenValues) {
+  if (template?.indexOf("${") === -1) return template;
+  let valueIndex = 0;
+  return template.replace(/\$\{[^}]*\}/g, () => {
+    const value = givenValues?.[valueIndex];
+    const output = value === null || value === void 0 ? `\${${valueIndex}}` : String(value);
+    valueIndex++;
+    return output;
+  });
+}
+function interpolateTemplate(template, givenValues) {
+  if (typeof template === "string") return ifString(template, givenValues);
+  if (Array.isArray(template)) return ifArray(template, givenValues);
+  throw new Error("Template must be a string or TemplateStringsArray");
 }
 
-// src/flat-template-string.test.ts
-function createTemplateStringsArray(strings) {
+// src/interpolate-template.test.ts
+function tpl(strings) {
   return Object.assign(strings, { raw: [...strings] });
 }
-describe("flatTemplateString", () => {
-  it("should concatenate simple strings without values", () => {
-    const result = flatTemplateString(createTemplateStringsArray(["Hello World"]), []);
-    globalExpect(result).toBe("Hello World");
-  });
-  it("should interpolate simple values", () => {
-    const result = flatTemplateString(createTemplateStringsArray(["Hello ", "!"]), ["World"]);
-    globalExpect(result).toBe("Hello World!");
-  });
-  it("should interpolate multiple values", () => {
-    const result = flatTemplateString(createTemplateStringsArray(["Hello ", ", you are ", " years old"]), ["John", 25]);
-    globalExpect(result).toBe("Hello John, you are 25 years old");
-  });
-  it("should handle null and undefined values", () => {
-    const result = flatTemplateString(createTemplateStringsArray(["Value: ", ", null: ", ", undefined: "]), [
-      null,
-      null,
-      void 0
-    ]);
-    globalExpect(result).toBe("Value: , null: , undefined: ");
-  });
-  it("should convert numbers to string", () => {
-    const result = flatTemplateString(createTemplateStringsArray(["Number: ", ""]), [42]);
-    globalExpect(result).toBe("Number: 42");
-  });
-  it("should convert booleans to string", () => {
-    const result = flatTemplateString(createTemplateStringsArray(["Boolean: ", ", false: "]), [true, false]);
-    globalExpect(result).toBe("Boolean: true, false: false");
-  });
-  it("should handle objects by converting to string", () => {
-    const obj = { name: "John", age: 30 };
-    const result = flatTemplateString(createTemplateStringsArray(["Object: ", ""]), [obj]);
-    globalExpect(result).toBe("Object: [object Object]");
-  });
-  it("should handle arrays by converting to string", () => {
-    const arr = [1, 2, 3];
-    const result = flatTemplateString(createTemplateStringsArray(["Array: ", ""]), [arr]);
-    globalExpect(result).toBe("Array: 1,2,3");
-  });
-  it("should handle empty strings", () => {
-    const result = flatTemplateString(createTemplateStringsArray(["", "middle", ""]), ["start", "end"]);
-    globalExpect(result).toBe("startmiddleend");
-  });
-  it("should handle complex template string", () => {
-    const name = "Alice";
-    const age = 28;
-    const city = "S\xE3o Paulo";
-    const result = flatTemplateString(
-      createTemplateStringsArray(["Ol\xE1, meu nome \xE9 ", ", tenho ", " anos e moro em ", "."]),
-      [name, age, city]
-    );
-    globalExpect(result).toBe("Ol\xE1, meu nome \xE9 Alice, tenho 28 anos e moro em S\xE3o Paulo.");
-  });
-  it("should handle values that are empty strings", () => {
-    const result = flatTemplateString(createTemplateStringsArray(["Start", "Middle", "End"]), ["", ""]);
-    globalExpect(result).toBe("StartMiddleEnd");
-  });
-  it("should preserve whitespace and line breaks", () => {
-    const result = flatTemplateString(createTemplateStringsArray(["Line 1\n", "Line 2\n", "Line 3"]), ["", ""]);
-    globalExpect(result).toBe("Line 1\nLine 2\nLine 3");
+describe("interpolateTemplate", () => {
+  describe("string only \u2014 no ${...}", () => {
+    it("returns the string as-is", () => {
+      globalExpect(interpolateTemplate("Hello World")).toBe("Hello World");
+    });
+    it("returns empty string as-is", () => {
+      globalExpect(interpolateTemplate("")).toBe("");
+    });
   });
-  it("should handle special characters", () => {
-    const result = flatTemplateString(createTemplateStringsArray(["Special: ", ""]), ["@#$%^&*()"]);
-    globalExpect(result).toBe("Special: @#$%^&*()");
+  describe("string only \u2014 with ${...}", () => {
+    it("replaces single placeholder with index notation", () => {
+      globalExpect(interpolateTemplate("Hello ${name}!")).toBe("Hello ${0}!");
+    });
+    it("replaces multiple placeholders with sequential index notation", () => {
+      globalExpect(interpolateTemplate("${greeting}, ${name}! You are ${age} years old.")).toBe(
+        "${0}, ${1}! You are ${2} years old."
+      );
+    });
+    it("replaces placeholder regardless of variable name inside ${}", () => {
+      globalExpect(interpolateTemplate("Value: ${someRandomVarName}")).toBe("Value: ${0}");
+    });
   });
-  it("should handle emojis", () => {
-    const result = flatTemplateString(createTemplateStringsArray(["Hello ", "!"]), ["\u{1F44B}"]);
-    globalExpect(result).toBe("Hello \u{1F44B}!");
+  describe("TemplateStringsArray only \u2014 no values", () => {
+    it("joins parts with index notation for each slot", () => {
+      globalExpect(interpolateTemplate(tpl(["Hello ", "!"]))).toBe("Hello ${0}!");
+    });
+    it("handles multiple slots", () => {
+      globalExpect(interpolateTemplate(tpl(["", ", ", "! You are ", " years old."]))).toBe(
+        "${0}, ${1}! You are ${2} years old."
+      );
+    });
+    it("handles a single string part with no slots", () => {
+      globalExpect(interpolateTemplate(tpl(["Hello World"]))).toBe("Hello World");
+    });
   });
-  it("should handle template string without values (strings only)", () => {
-    const result = flatTemplateString(createTemplateStringsArray(["Apenas", "texto", "simples"]), []);
-    globalExpect(result).toBe("Apenastextosimples");
+  describe("string + values \u2014 no ${...}", () => {
+    it("returns string as-is and ignores values", () => {
+      globalExpect(interpolateTemplate("Hello World", ["John", 42])).toBe("Hello World");
+    });
   });
-  it("should handle more values than strings", () => {
-    const result = flatTemplateString(createTemplateStringsArray(["Start", "End"]), ["Middle1", "Middle2", "Extra"]);
-    globalExpect(result).toBe("StartMiddle1EndMiddle2");
+  describe("string + values \u2014 with ${...}", () => {
+    it("replaces placeholder with provided value", () => {
+      globalExpect(interpolateTemplate("Hello ${name}!", ["John"])).toBe("Hello John!");
+    });
+    it("replaces multiple placeholders with sequential values", () => {
+      globalExpect(interpolateTemplate("${greeting}, ${name}! You are ${age} years old.", ["Hi", "Alice", 30])).toBe(
+        "Hi, Alice! You are 30 years old."
+      );
+    });
+    it("falls back to index notation when value is undefined", () => {
+      globalExpect(interpolateTemplate("${a} and ${b}", [void 0, "world"])).toBe("${0} and world");
+    });
+    it("falls back to index notation when value is null", () => {
+      globalExpect(interpolateTemplate("${a} and ${b}", [null, "world"])).toBe("${0} and world");
+    });
+    it("converts number values to string", () => {
+      globalExpect(interpolateTemplate("Value: ${n}", [42])).toBe("Value: 42");
+    });
+    it("converts boolean values to string", () => {
+      globalExpect(interpolateTemplate("Flag: ${f}", [true])).toBe("Flag: true");
+    });
   });
-  it("should handle fewer values than strings", () => {
-    const result = flatTemplateString(createTemplateStringsArray(["Start", "Middle", "End"]), ["Value"]);
-    globalExpect(result).toBe("StartValueMiddleEnd");
+  describe("TemplateStringsArray + values", () => {
+    it("interpolates with provided values", () => {
+      globalExpect(interpolateTemplate(tpl(["Hello ", "!"]), ["World"])).toBe("Hello World!");
+    });
+    it("interpolates multiple values", () => {
+      globalExpect(interpolateTemplate(tpl(["Hello ", ", you are ", " years old"]), ["John", 25])).toBe(
+        "Hello John, you are 25 years old"
+      );
+    });
+    it("handles null values as empty string", () => {
+      globalExpect(interpolateTemplate(tpl(["Value: ", ", null: "]), [null, null])).toBe("Value: , null: ");
+    });
+    it("handles undefined values as empty string", () => {
+      globalExpect(interpolateTemplate(tpl(["Start: ", ", end"]), [void 0])).toBe("Start: , end");
+    });
+    it("converts number values to string", () => {
+      globalExpect(interpolateTemplate(tpl(["Number: ", ""]), [42])).toBe("Number: 42");
+    });
+    it("converts boolean values to string", () => {
+      globalExpect(interpolateTemplate(tpl(["Boolean: ", ""]), [true])).toBe("Boolean: true");
+    });
   });
 });
 /*! Bundled license information:

package/dist/io/ask-llm.d.mts

@@ -6,7 +6,7 @@ import '../schemas/config.shcema.mjs';
 import '../create-cache-id.mjs';
 import '../data/clear-cache.mjs';
 import '../data/get-cache.mjs';
-import '../flat-template-string.mjs';
+import '../interpolate-template.mjs';
 
 /**
  * Asks an LLM for a response using multi-llm-ts.

package/dist/schemas/config.shcema.d.mts

@@ -46,12 +46,12 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         provider: "anthropic" | "gemini" | "openai" | "groq" | "mistral" | "ollama" | "xai" | "deepseek" | "openrouter" | "cerebras" | "lmstudio" | "azure" | "meta";
         model: string | null;
+        prePrompt?: string | undefined;
+        postPrompt?: string | undefined;
         apiKey?: string | undefined;
         baseURL?: string | undefined;
         temperature?: number | undefined;
         sleep?: number | undefined;
-        prePrompt?: string | undefined;
-        postPrompt?: string | undefined;
         prePromptReplace?: string | undefined;
         postPromptReplace?: string | undefined;
         prePromptAppend?: string | undefined;
@@ -59,12 +59,12 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     }, {
         provider: "anthropic" | "gemini" | "openai" | "groq" | "mistral" | "ollama" | "xai" | "deepseek" | "openrouter" | "cerebras" | "lmstudio" | "azure" | "meta";
         model: string | null;
+        prePrompt?: string | undefined;
+        postPrompt?: string | undefined;
         apiKey?: string | undefined;
         baseURL?: string | undefined;
         temperature?: number | undefined;
         sleep?: number | undefined;
-        prePrompt?: string | undefined;
-        postPrompt?: string | undefined;
         prePromptReplace?: string | undefined;
         postPromptReplace?: string | undefined;
         prePromptAppend?: string | undefined;
@@ -87,12 +87,12 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     llm: {
         provider: "anthropic" | "gemini" | "openai" | "groq" | "mistral" | "ollama" | "xai" | "deepseek" | "openrouter" | "cerebras" | "lmstudio" | "azure" | "meta";
         model: string | null;
+        prePrompt?: string | undefined;
+        postPrompt?: string | undefined;
         apiKey?: string | undefined;
         baseURL?: string | undefined;
         temperature?: number | undefined;
         sleep?: number | undefined;
-        prePrompt?: string | undefined;
-        postPrompt?: string | undefined;
         prePromptReplace?: string | undefined;
         postPromptReplace?: string | undefined;
         prePromptAppend?: string | undefined;
@@ -116,12 +116,12 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     llm: {
         provider: "anthropic" | "gemini" | "openai" | "groq" | "mistral" | "ollama" | "xai" | "deepseek" | "openrouter" | "cerebras" | "lmstudio" | "azure" | "meta";
         model: string | null;
+        prePrompt?: string | undefined;
+        postPrompt?: string | undefined;
         apiKey?: string | undefined;
         baseURL?: string | undefined;
         temperature?: number | undefined;
         sleep?: number | undefined;
-        prePrompt?: string | undefined;
-        postPrompt?: string | undefined;
         prePromptReplace?: string | undefined;
         postPromptReplace?: string | undefined;
         prePromptAppend?: string | undefined;
@@ -145,12 +145,12 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     llm: {
         provider: "anthropic" | "gemini" | "openai" | "groq" | "mistral" | "ollama" | "xai" | "deepseek" | "openrouter" | "cerebras" | "lmstudio" | "azure" | "meta";
         model: string | null;
+        prePrompt?: string | undefined;
+        postPrompt?: string | undefined;
         apiKey?: string | undefined;
         baseURL?: string | undefined;
         temperature?: number | undefined;
         sleep?: number | undefined;
-        prePrompt?: string | undefined;
-        postPrompt?: string | undefined;
         prePromptReplace?: string | undefined;
         postPromptReplace?: string | undefined;
         prePromptAppend?: string | undefined;
@@ -174,12 +174,12 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     llm: {
         provider: "anthropic" | "gemini" | "openai" | "groq" | "mistral" | "ollama" | "xai" | "deepseek" | "openrouter" | "cerebras" | "lmstudio" | "azure" | "meta";
         model: string | null;
+        prePrompt?: string | undefined;
+        postPrompt?: string | undefined;
         apiKey?: string | undefined;
         baseURL?: string | undefined;
         temperature?: number | undefined;
         sleep?: number | undefined;
-        prePrompt?: string | undefined;
-        postPrompt?: string | undefined;
         prePromptReplace?: string | undefined;
         postPromptReplace?: string | undefined;
         prePromptAppend?: string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gringow/gringow",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
@@ -10,10 +10,10 @@
       "require": "./dist/index.mjs",
       "import": "./dist/index.mjs"
     },
-    "./flat-template-string": {
-      "types": "./dist/flat-template-string.d.mts",
-      "require": "./dist/flat-template-string.mjs",
-      "import": "./dist/flat-template-string.mjs"
+    "./interpolate-template": {
+      "types": "./dist/interpolate-template.d.mts",
+      "require": "./dist/interpolate-template.mjs",
+      "import": "./dist/interpolate-template.mjs"
     },
     "./browser": {
       "types": "./dist/browser.d.mts",

package/dist/flat-template-string.d.mts

@@ -1,14 +0,0 @@
-/**
- * Flattens a template string with its values into a single flat string
- *
- * @param givenStrings - The template strings
- * @param givenValues - The values to be interpolated
- * @returns The flattened string
- *
- * @example
- * const result = flatTemplateString`Hello ${name}!`
- * // result = 'Hello John!'
- */
-declare function flatTemplateString(givenStrings: TemplateStringsArray, givenValues: Array<unknown>): string;
-
-export { flatTemplateString };

package/dist/flat-template-string.mjs

@@ -1,16 +0,0 @@
-// src/flat-template-string.ts
-function flatTemplateString(givenStrings, givenValues) {
-  const strings = [...givenStrings.raw];
-  const values = [...givenValues];
-  const flatted = strings.reduce((acc, item, index) => {
-    acc += String(item ?? "");
-    if (index < values.length) {
-      const value = values[index];
-      acc += String(value ?? "");
-    }
-    return acc;
-  }, "");
-  return flatted;
-}
-
-export { flatTemplateString };