pte-interpolation-core 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordan Lawrence
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# pte-interpolation-core
+
+[![npm version](https://img.shields.io/npm/v/pte-interpolation-core.svg?style=flat-square)](https://www.npmjs.com/package/pte-interpolation-core)
+
+Framework-agnostic utilities for [Portable Text](https://portabletext.org/) variable interpolation. Extract variable keys from PTE blocks and resolve them to plain strings - with zero dependencies.
+
+Part of [sanity-pte-interpolation](https://github.com/jordanl17/sanity-pte-interpolation). For adding variable picker inline blocks to Sanity Studio, see [`sanity-plugin-pte-interpolation`](https://www.npmjs.com/package/sanity-plugin-pte-interpolation). For React rendering with rich text output, see [`pte-interpolation-react`](https://www.npmjs.com/package/pte-interpolation-react).
+
+## Install
+
+```sh
+npm install pte-interpolation-core
+```
+
+No peer dependencies required.
+
+## When to Use
+
+Use this package when you need plain string output from interpolated Portable Text - without a React dependency. Common use cases include:
+
+- Email templates (server-side rendering)
+- PDF generation
+- Node.js scripts and background jobs
+- SMS or push notification text
+- Any non-React framework (Vue, Svelte, Angular, etc.)
+
+If you are rendering in React and want rich text output, use [`pte-interpolation-react`](https://www.npmjs.com/package/pte-interpolation-react) instead - it re-exports everything from this package, so you get both APIs without installing core separately.
+
+## Usage
+
+### Extract variable keys
+
+`extractVariableKeys` returns the unique variable keys found in an array of PTE blocks, in first-occurrence order:
+
+```ts
+import {extractVariableKeys} from 'pte-interpolation-core'
+
+const keys = extractVariableKeys(blocks)
+// ['firstName', 'email']
+```
+
+### Interpolate to a plain string
+
+`interpolateToString` resolves PTE blocks to a plain string, substituting variable blocks with the provided values:
+
+```ts
+import {interpolateToString} from 'pte-interpolation-core'
+
+const text = interpolateToString(blocks, {
+  firstName: 'Alice',
+  email: 'alice@example.com',
+})
+// "Hello, Alice! Your email is alice@example.com."
+```
+
+### Custom fallback for missing values
+
+By default, unresolved variables render as `{variableKey}` (e.g. `{firstName}`). Provide a fallback function to customise this:
+
+```ts
+const text = interpolateToString(blocks, {}, (variableKey) => `[${variableKey}]`)
+// "Hello, [firstName]! Your email is [email]."
+```
+
+## Authoring Variables in Sanity Studio
+
+This package handles **resolution** of variable blocks that already exist in Portable Text. To add the variable picker to Sanity Studio's Portable Text Editor, use [`sanity-plugin-pte-interpolation`](https://www.npmjs.com/package/sanity-plugin-pte-interpolation):
+
+```ts
+import {interpolationVariables} from 'sanity-plugin-pte-interpolation'
+
+defineField({
+  name: 'body',
+  type: 'array',
+  of: [
+    interpolationVariables([
+      {id: 'firstName', name: 'First name'},
+      {id: 'email', name: 'Email address'},
+    ]),
+  ],
+})
+```
+
+## Data Shape
+
+Variable blocks in stored Portable Text look like this:
+
+```json
+{
+  "_type": "block",
+  "children": [
+    {"_type": "span", "text": "Hello, "},
+    {"_type": "pteInterpolationVariable", "variableKey": "firstName"},
+    {"_type": "span", "text": "!"}
+  ]
+}
+```
+
+The `variableKey` maps to the `id` defined in the Studio variable definitions and the keys in the values record passed to `interpolateToString`.
+
+## API Reference
+
+### `extractVariableKeys(blocks)`
+
+Returns the unique variable keys from an array of PTE blocks, in first-occurrence order.
+
+| Parameter | Type                      | Description                  |
+| --------- | ------------------------- | ---------------------------- |
+| `blocks`  | `PortableTextBlockLike[]` | Portable Text blocks to scan |
+
+Returns `string[]`.
+
+### `interpolateToString(blocks, values, fallback?)`
+
+Resolves PTE blocks to a plain string, replacing variable blocks with the corresponding values. Multiple blocks are joined with newlines.
+
+| Parameter  | Type                              | Description                                                              |
+| ---------- | --------------------------------- | ------------------------------------------------------------------------ |
+| `blocks`   | `PortableTextBlockLike[]`         | Portable Text blocks to resolve                                          |
+| `values`   | `Record<string, string>`          | Map of variable IDs to their resolved values                             |
+| `fallback` | `(variableKey: string) => string` | Optional function for unresolved variables (defaults to `{variableKey}`) |
+
+Returns `string`.
+
+### `VARIABLE_TYPE_PREFIX`
+
+The constant `'pteInterpolationVariable'` - the `_type` string used for variable inline blocks in stored Portable Text. Exported for advanced use cases.
+
+### Types
+
+| Type                            | Description                                           |
+| ------------------------------- | ----------------------------------------------------- |
+| `PortableTextBlockLike`         | Minimal block shape with optional `children` array    |
+| `PortableTextChild`             | A child node within a block (span or variable)        |
+| `PteInterpolationVariableBlock` | A variable inline block with `variableKey`            |
+| `InterpolationValues`           | `Record<string, string>` - variable ID to value map   |
+| `InterpolationFallback`         | `(variableKey: string) => string` - fallback function |
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: !0 });
+const VARIABLE_TYPE_PREFIX = "pteInterpolationVariable";
+function extractVariableKeys(blocks) {
+  const seen = /* @__PURE__ */ new Set();
+  return blocks.reduce((keys, block) => (block.children ?? []).reduce((accumulated, child) => {
+    if (child._type !== VARIABLE_TYPE_PREFIX) return accumulated;
+    const variableKey = child.variableKey;
+    return typeof variableKey != "string" || seen.has(variableKey) ? accumulated : (seen.add(variableKey), [...accumulated, variableKey]);
+  }, keys), []);
+}
+function defaultFallback(variableKey) {
+  return `{${variableKey}}`;
+}
+function interpolateToString(blocks, values, fallback = defaultFallback) {
+  return blocks.map((block) => (block.children ?? []).map((child) => {
+    if (child._type === VARIABLE_TYPE_PREFIX) {
+      const variableKey = child.variableKey;
+      return values[variableKey] !== void 0 ? values[variableKey] : fallback(variableKey);
+    }
+    return typeof child.text == "string" ? child.text : "";
+  }).join("")).join(`
+`);
+}
+exports.VARIABLE_TYPE_PREFIX = VARIABLE_TYPE_PREFIX;
+exports.extractVariableKeys = extractVariableKeys;
+exports.interpolateToString = interpolateToString;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/constants.ts","../src/extractVariableKeys.ts","../src/interpolateToString.ts"],"sourcesContent":["/** @public */\nexport const VARIABLE_TYPE_PREFIX = 'pteInterpolationVariable'\n","import {VARIABLE_TYPE_PREFIX} from './constants'\nimport type {PortableTextBlockLike} from './types'\n\n/** @public */\nexport function extractVariableKeys(blocks: PortableTextBlockLike[]): string[] {\n  const seen = new Set<string>()\n\n  return blocks.reduce<string[]>((keys, block) => {\n    const children = block.children ?? []\n\n    return children.reduce((accumulated, child) => {\n      if (child._type !== VARIABLE_TYPE_PREFIX) return accumulated\n\n      const variableKey = child.variableKey\n      if (typeof variableKey !== 'string') return accumulated\n      if (seen.has(variableKey)) return accumulated\n\n      seen.add(variableKey)\n      return [...accumulated, variableKey]\n    }, keys)\n  }, [])\n}\n","import {VARIABLE_TYPE_PREFIX} from './constants'\nimport type {InterpolationFallback, InterpolationValues, PortableTextBlockLike} from './types'\n\nfunction defaultFallback(variableKey: string): string {\n  return `{${variableKey}}`\n}\n\n/** @public */\nexport function interpolateToString(\n  blocks: PortableTextBlockLike[],\n  values: InterpolationValues,\n  fallback: InterpolationFallback = defaultFallback,\n): string {\n  return blocks\n    .map((block) => {\n      const children = block.children ?? []\n\n      return children\n        .map((child) => {\n          if (child._type === VARIABLE_TYPE_PREFIX) {\n            const variableKey = child.variableKey as string\n            return values[variableKey] !== undefined ? values[variableKey] : fallback(variableKey)\n          }\n\n          return typeof child.text === 'string' ? child.text : ''\n        })\n        .join('')\n    })\n    .join('\\n')\n}\n"],"names":[],"mappings":";;AACO,MAAM,uBAAuB;ACG7B,SAAS,oBAAoB,QAA2C;AAC7E,QAAM,2BAAW,IAAA;AAEjB,SAAO,OAAO,OAAiB,CAAC,MAAM,WACnB,MAAM,YAAY,CAAA,GAEnB,OAAO,CAAC,aAAa,UAAU;AAC7C,QAAI,MAAM,UAAU,qBAAsB,QAAO;AAEjD,UAAM,cAAc,MAAM;AAE1B,WADI,OAAO,eAAgB,YACvB,KAAK,IAAI,WAAW,IAAU,eAElC,KAAK,IAAI,WAAW,GACb,CAAC,GAAG,aAAa,WAAW;AAAA,EACrC,GAAG,IAAI,GACN,EAAE;AACP;AClBA,SAAS,gBAAgB,aAA6B;AACpD,SAAO,IAAI,WAAW;AACxB;AAGO,SAAS,oBACd,QACA,QACA,WAAkC,iBAC1B;AACR,SAAO,OACJ,IAAI,CAAC,WACa,MAAM,YAAY,CAAA,GAGhC,IAAI,CAAC,UAAU;AACd,QAAI,MAAM,UAAU,sBAAsB;AACxC,YAAM,cAAc,MAAM;AAC1B,aAAO,OAAO,WAAW,MAAM,SAAY,OAAO,WAAW,IAAI,SAAS,WAAW;AAAA,IACvF;AAEA,WAAO,OAAO,MAAM,QAAS,WAAW,MAAM,OAAO;AAAA,EACvD,CAAC,EACA,KAAK,EAAE,CACX,EACA,KAAK;AAAA,CAAI;AACd;;;;"}

package/dist/index.d.cts

@@ -0,0 +1,42 @@
+/** @public */
+export declare function extractVariableKeys(blocks: PortableTextBlockLike[]): string[]
+
+/** @public */
+export declare function interpolateToString(
+  blocks: PortableTextBlockLike[],
+  values: InterpolationValues,
+  fallback?: InterpolationFallback,
+): string
+
+/** @public */
+export declare type InterpolationFallback = (variableKey: string) => string
+
+/** @public */
+export declare type InterpolationValues = Record<string, string>
+
+/** @public */
+export declare interface PortableTextBlockLike {
+  _type: string
+  _key?: string
+  children?: PortableTextChild[]
+}
+
+/** @public */
+export declare interface PortableTextChild {
+  _type: string
+  _key?: string
+  text?: string
+  variableKey?: string
+}
+
+/** @public */
+export declare interface PteInterpolationVariableBlock {
+  _type: 'pteInterpolationVariable'
+  _key: string
+  variableKey: string
+}
+
+/** @public */
+export declare const VARIABLE_TYPE_PREFIX = 'pteInterpolationVariable'
+
+export {}

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/** @public */
+export declare function extractVariableKeys(blocks: PortableTextBlockLike[]): string[]
+
+/** @public */
+export declare function interpolateToString(
+  blocks: PortableTextBlockLike[],
+  values: InterpolationValues,
+  fallback?: InterpolationFallback,
+): string
+
+/** @public */
+export declare type InterpolationFallback = (variableKey: string) => string
+
+/** @public */
+export declare type InterpolationValues = Record<string, string>
+
+/** @public */
+export declare interface PortableTextBlockLike {
+  _type: string
+  _key?: string
+  children?: PortableTextChild[]
+}
+
+/** @public */
+export declare interface PortableTextChild {
+  _type: string
+  _key?: string
+  text?: string
+  variableKey?: string
+}
+
+/** @public */
+export declare interface PteInterpolationVariableBlock {
+  _type: 'pteInterpolationVariable'
+  _key: string
+  variableKey: string
+}
+
+/** @public */
+export declare const VARIABLE_TYPE_PREFIX = 'pteInterpolationVariable'
+
+export {}

package/dist/index.js

@@ -0,0 +1,28 @@
+const VARIABLE_TYPE_PREFIX = "pteInterpolationVariable";
+function extractVariableKeys(blocks) {
+  const seen = /* @__PURE__ */ new Set();
+  return blocks.reduce((keys, block) => (block.children ?? []).reduce((accumulated, child) => {
+    if (child._type !== VARIABLE_TYPE_PREFIX) return accumulated;
+    const variableKey = child.variableKey;
+    return typeof variableKey != "string" || seen.has(variableKey) ? accumulated : (seen.add(variableKey), [...accumulated, variableKey]);
+  }, keys), []);
+}
+function defaultFallback(variableKey) {
+  return `{${variableKey}}`;
+}
+function interpolateToString(blocks, values, fallback = defaultFallback) {
+  return blocks.map((block) => (block.children ?? []).map((child) => {
+    if (child._type === VARIABLE_TYPE_PREFIX) {
+      const variableKey = child.variableKey;
+      return values[variableKey] !== void 0 ? values[variableKey] : fallback(variableKey);
+    }
+    return typeof child.text == "string" ? child.text : "";
+  }).join("")).join(`
+`);
+}
+export {
+  VARIABLE_TYPE_PREFIX,
+  extractVariableKeys,
+  interpolateToString
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/constants.ts","../src/extractVariableKeys.ts","../src/interpolateToString.ts"],"sourcesContent":["/** @public */\nexport const VARIABLE_TYPE_PREFIX = 'pteInterpolationVariable'\n","import {VARIABLE_TYPE_PREFIX} from './constants'\nimport type {PortableTextBlockLike} from './types'\n\n/** @public */\nexport function extractVariableKeys(blocks: PortableTextBlockLike[]): string[] {\n  const seen = new Set<string>()\n\n  return blocks.reduce<string[]>((keys, block) => {\n    const children = block.children ?? []\n\n    return children.reduce((accumulated, child) => {\n      if (child._type !== VARIABLE_TYPE_PREFIX) return accumulated\n\n      const variableKey = child.variableKey\n      if (typeof variableKey !== 'string') return accumulated\n      if (seen.has(variableKey)) return accumulated\n\n      seen.add(variableKey)\n      return [...accumulated, variableKey]\n    }, keys)\n  }, [])\n}\n","import {VARIABLE_TYPE_PREFIX} from './constants'\nimport type {InterpolationFallback, InterpolationValues, PortableTextBlockLike} from './types'\n\nfunction defaultFallback(variableKey: string): string {\n  return `{${variableKey}}`\n}\n\n/** @public */\nexport function interpolateToString(\n  blocks: PortableTextBlockLike[],\n  values: InterpolationValues,\n  fallback: InterpolationFallback = defaultFallback,\n): string {\n  return blocks\n    .map((block) => {\n      const children = block.children ?? []\n\n      return children\n        .map((child) => {\n          if (child._type === VARIABLE_TYPE_PREFIX) {\n            const variableKey = child.variableKey as string\n            return values[variableKey] !== undefined ? values[variableKey] : fallback(variableKey)\n          }\n\n          return typeof child.text === 'string' ? child.text : ''\n        })\n        .join('')\n    })\n    .join('\\n')\n}\n"],"names":[],"mappings":"AACO,MAAM,uBAAuB;ACG7B,SAAS,oBAAoB,QAA2C;AAC7E,QAAM,2BAAW,IAAA;AAEjB,SAAO,OAAO,OAAiB,CAAC,MAAM,WACnB,MAAM,YAAY,CAAA,GAEnB,OAAO,CAAC,aAAa,UAAU;AAC7C,QAAI,MAAM,UAAU,qBAAsB,QAAO;AAEjD,UAAM,cAAc,MAAM;AAE1B,WADI,OAAO,eAAgB,YACvB,KAAK,IAAI,WAAW,IAAU,eAElC,KAAK,IAAI,WAAW,GACb,CAAC,GAAG,aAAa,WAAW;AAAA,EACrC,GAAG,IAAI,GACN,EAAE;AACP;AClBA,SAAS,gBAAgB,aAA6B;AACpD,SAAO,IAAI,WAAW;AACxB;AAGO,SAAS,oBACd,QACA,QACA,WAAkC,iBAC1B;AACR,SAAO,OACJ,IAAI,CAAC,WACa,MAAM,YAAY,CAAA,GAGhC,IAAI,CAAC,UAAU;AACd,QAAI,MAAM,UAAU,sBAAsB;AACxC,YAAM,cAAc,MAAM;AAC1B,aAAO,OAAO,WAAW,MAAM,SAAY,OAAO,WAAW,IAAI,SAAS,WAAW;AAAA,IACvF;AAEA,WAAO,OAAO,MAAM,QAAS,WAAW,MAAM,OAAO;AAAA,EACvD,CAAC,EACA,KAAK,EAAE,CACX,EACA,KAAK;AAAA,CAAI;AACd;"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "pte-interpolation-core",
+  "version": "1.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Framework-agnostic utilities for Portable Text variable interpolation",
+  "keywords": [
+    "portable-text",
+    "interpolation",
+    "variables"
+  ],
+  "homepage": "https://github.com/jordanl17/sanity-pte-interpolation#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jordanl17/sanity-pte-interpolation.git",
+    "directory": "packages/pte-interpolation-core"
+  },
+  "bugs": {
+    "url": "https://github.com/jordanl17/sanity-pte-interpolation/issues"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "browserslist": "extends @sanity/browserslist-config",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@sanity/pkg-utils": "^10.4.4",
+    "rimraf": "^6.1.3",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "build": "pkg-utils build --strict --check --clean",
+    "clean": "rimraf dist",
+    "link-watch": "pkg-utils watch --tsconfig tsconfig.build.json",
+    "type-check": "tsc --noEmit",
+    "yalc:publish": "npx yalc publish"
+  }
+}

package/src/__tests__/extractVariableKeys.test.ts

@@ -0,0 +1,46 @@
+import {describe, expect, it} from 'vitest'
+import {extractVariableKeys} from '../extractVariableKeys'
+import {
+  blockWithNoChildren,
+  blockWithNonStringVariableKey,
+  consecutiveVariablesBlock,
+  duplicateVariableBlock,
+  emptyBlocksContent,
+  multipleVariablesBlock,
+  plainTextBlock,
+  singleVariableBlock,
+} from './fixtures'
+
+describe('extractVariableKeys', () => {
+  it('returns an empty array for empty blocks', () => {
+    expect(extractVariableKeys(emptyBlocksContent)).toEqual([])
+  })
+
+  it('returns an empty array when no variables exist', () => {
+    expect(extractVariableKeys(plainTextBlock)).toEqual([])
+  })
+
+  it('extracts a single variable key', () => {
+    expect(extractVariableKeys(singleVariableBlock)).toEqual(['firstName'])
+  })
+
+  it('extracts multiple variable keys in order', () => {
+    expect(extractVariableKeys(multipleVariablesBlock)).toEqual(['firstName', 'lastName', 'email'])
+  })
+
+  it('extracts consecutive variable keys', () => {
+    expect(extractVariableKeys(consecutiveVariablesBlock)).toEqual(['firstName', 'lastName'])
+  })
+
+  it('deduplicates variable keys preserving first-occurrence order', () => {
+    expect(extractVariableKeys(duplicateVariableBlock)).toEqual(['firstName'])
+  })
+
+  it('handles blocks with no children property', () => {
+    expect(extractVariableKeys(blockWithNoChildren)).toEqual([])
+  })
+
+  it('skips children with non-string variableKey', () => {
+    expect(extractVariableKeys(blockWithNonStringVariableKey)).toEqual([])
+  })
+})

package/src/__tests__/fixtures.ts

@@ -0,0 +1,94 @@
+import type {PortableTextBlockLike} from '../types'
+
+export const singleVariableBlock: PortableTextBlockLike[] = [
+  {
+    _type: 'block',
+    _key: 'block-1',
+    children: [
+      {_type: 'span', _key: 'span-1', text: 'Hello, '},
+      {_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 'firstName'},
+      {_type: 'span', _key: 'span-2', text: '!'},
+    ],
+  },
+]
+
+export const multipleVariablesBlock: PortableTextBlockLike[] = [
+  {
+    _type: 'block',
+    _key: 'block-1',
+    children: [
+      {_type: 'span', _key: 'span-1', text: 'Name: '},
+      {_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 'firstName'},
+      {_type: 'span', _key: 'span-2', text: ' '},
+      {_type: 'pteInterpolationVariable', _key: 'var-2', variableKey: 'lastName'},
+      {_type: 'span', _key: 'span-3', text: ', Email: '},
+      {_type: 'pteInterpolationVariable', _key: 'var-3', variableKey: 'email'},
+    ],
+  },
+]
+
+export const plainTextBlock: PortableTextBlockLike[] = [
+  {
+    _type: 'block',
+    _key: 'block-1',
+    children: [{_type: 'span', _key: 'span-1', text: 'No variables here.'}],
+  },
+]
+
+export const consecutiveVariablesBlock: PortableTextBlockLike[] = [
+  {
+    _type: 'block',
+    _key: 'block-1',
+    children: [
+      {_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 'firstName'},
+      {_type: 'pteInterpolationVariable', _key: 'var-2', variableKey: 'lastName'},
+    ],
+  },
+]
+
+export const multiBlockContent: PortableTextBlockLike[] = [
+  {
+    _type: 'block',
+    _key: 'block-1',
+    children: [
+      {_type: 'span', _key: 'span-1', text: 'Dear '},
+      {_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 'firstName'},
+      {_type: 'span', _key: 'span-2', text: ','},
+    ],
+  },
+  {
+    _type: 'block',
+    _key: 'block-2',
+    children: [
+      {_type: 'span', _key: 'span-3', text: 'Your email is '},
+      {_type: 'pteInterpolationVariable', _key: 'var-2', variableKey: 'email'},
+      {_type: 'span', _key: 'span-4', text: '.'},
+    ],
+  },
+]
+
+export const duplicateVariableBlock: PortableTextBlockLike[] = [
+  {
+    _type: 'block',
+    _key: 'block-1',
+    children: [
+      {_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 'firstName'},
+      {_type: 'span', _key: 'span-1', text: ' and '},
+      {_type: 'pteInterpolationVariable', _key: 'var-2', variableKey: 'firstName'},
+    ],
+  },
+]
+
+export const blockWithNoChildren: PortableTextBlockLike[] = [{_type: 'block', _key: 'block-1'}]
+
+export const blockWithNonStringVariableKey: PortableTextBlockLike[] = [
+  {
+    _type: 'block',
+    _key: 'block-1',
+    children: [
+      {_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 123 as unknown as string},
+    ],
+  },
+]
+
+export const emptyBlocksContent: PortableTextBlockLike[] = []

package/src/__tests__/interpolateToString.test.ts

@@ -0,0 +1,59 @@
+import {describe, expect, it} from 'vitest'
+import {interpolateToString} from '../interpolateToString'
+import {
+  consecutiveVariablesBlock,
+  emptyBlocksContent,
+  multiBlockContent,
+  multipleVariablesBlock,
+  plainTextBlock,
+  singleVariableBlock,
+} from './fixtures'
+
+describe('interpolateToString', () => {
+  it('returns an empty string for empty blocks', () => {
+    expect(interpolateToString(emptyBlocksContent, {})).toBe('')
+  })
+
+  it('returns plain text unchanged', () => {
+    expect(interpolateToString(plainTextBlock, {})).toBe('No variables here.')
+  })
+
+  it('resolves a single variable from values', () => {
+    expect(interpolateToString(singleVariableBlock, {firstName: 'Alice'})).toBe('Hello, Alice!')
+  })
+
+  it('uses default fallback for missing variables', () => {
+    expect(interpolateToString(singleVariableBlock, {})).toBe('Hello, {firstName}!')
+  })
+
+  it('uses a custom fallback for missing variables', () => {
+    const customFallback = (variableKey: string) => `[${variableKey}]`
+    expect(interpolateToString(singleVariableBlock, {}, customFallback)).toBe('Hello, [firstName]!')
+  })
+
+  it('uses the value when it is an empty string', () => {
+    expect(interpolateToString(singleVariableBlock, {firstName: ''})).toBe('Hello, !')
+  })
+
+  it('resolves consecutive variables', () => {
+    expect(
+      interpolateToString(consecutiveVariablesBlock, {firstName: 'Alice', lastName: 'Smith'}),
+    ).toBe('AliceSmith')
+  })
+
+  it('joins multiple blocks with newlines', () => {
+    expect(
+      interpolateToString(multiBlockContent, {firstName: 'Alice', email: 'alice@example.com'}),
+    ).toBe('Dear Alice,\nYour email is alice@example.com.')
+  })
+
+  it('resolves multiple variables in one block', () => {
+    expect(
+      interpolateToString(multipleVariablesBlock, {
+        firstName: 'Alice',
+        lastName: 'Smith',
+        email: 'alice@example.com',
+      }),
+    ).toBe('Name: Alice Smith, Email: alice@example.com')
+  })
+})

package/src/constants.ts

@@ -0,0 +1,2 @@
+/** @public */
+export const VARIABLE_TYPE_PREFIX = 'pteInterpolationVariable'

package/src/extractVariableKeys.ts

@@ -0,0 +1,22 @@
+import {VARIABLE_TYPE_PREFIX} from './constants'
+import type {PortableTextBlockLike} from './types'
+
+/** @public */
+export function extractVariableKeys(blocks: PortableTextBlockLike[]): string[] {
+  const seen = new Set<string>()
+
+  return blocks.reduce<string[]>((keys, block) => {
+    const children = block.children ?? []
+
+    return children.reduce((accumulated, child) => {
+      if (child._type !== VARIABLE_TYPE_PREFIX) return accumulated
+
+      const variableKey = child.variableKey
+      if (typeof variableKey !== 'string') return accumulated
+      if (seen.has(variableKey)) return accumulated
+
+      seen.add(variableKey)
+      return [...accumulated, variableKey]
+    }, keys)
+  }, [])
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export {VARIABLE_TYPE_PREFIX} from './constants'
+export {extractVariableKeys} from './extractVariableKeys'
+export {interpolateToString} from './interpolateToString'
+export type {
+  InterpolationFallback,
+  InterpolationValues,
+  PortableTextBlockLike,
+  PortableTextChild,
+  PteInterpolationVariableBlock,
+} from './types'

package/src/interpolateToString.ts

@@ -0,0 +1,30 @@
+import {VARIABLE_TYPE_PREFIX} from './constants'
+import type {InterpolationFallback, InterpolationValues, PortableTextBlockLike} from './types'
+
+function defaultFallback(variableKey: string): string {
+  return `{${variableKey}}`
+}
+
+/** @public */
+export function interpolateToString(
+  blocks: PortableTextBlockLike[],
+  values: InterpolationValues,
+  fallback: InterpolationFallback = defaultFallback,
+): string {
+  return blocks
+    .map((block) => {
+      const children = block.children ?? []
+
+      return children
+        .map((child) => {
+          if (child._type === VARIABLE_TYPE_PREFIX) {
+            const variableKey = child.variableKey as string
+            return values[variableKey] !== undefined ? values[variableKey] : fallback(variableKey)
+          }
+
+          return typeof child.text === 'string' ? child.text : ''
+        })
+        .join('')
+    })
+    .join('\n')
+}

package/src/types.ts

@@ -0,0 +1,27 @@
+/** @public */
+export interface PortableTextChild {
+  _type: string
+  _key?: string
+  text?: string
+  variableKey?: string
+}
+
+/** @public */
+export interface PortableTextBlockLike {
+  _type: string
+  _key?: string
+  children?: PortableTextChild[]
+}
+
+/** @public */
+export interface PteInterpolationVariableBlock {
+  _type: 'pteInterpolationVariable'
+  _key: string
+  variableKey: string
+}
+
+/** @public */
+export type InterpolationValues = Record<string, string>
+
+/** @public */
+export type InterpolationFallback = (variableKey: string) => string