pte-interpolation-core 1.1.1 → 1.2.0

package/README.md

@@ -4,7 +4,7 @@
 
 ![Demo](https://raw.githubusercontent.com/jordanl17/sanity-pte-interpolation/main/.github/assets/demo.png)
 
-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.
+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. Use this package when you need plain string output without a React dependency: email templates, PDF generation, Node.js scripts, SMS or push notifications, or any non-React framework (Vue, Svelte, Angular, etc.). For React rendering with rich text output, use [`pte-interpolation-react`](https://www.npmjs.com/package/pte-interpolation-react) instead - it re-exports everything from this package.
 
 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).
 
@@ -16,18 +16,6 @@ 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
@@ -38,7 +26,7 @@ If you are rendering in React and want rich text output, use [`pte-interpolation
 import {extractVariableKeys} from 'pte-interpolation-core'
 
 const keys = extractVariableKeys(blocks)
-// ['firstName', 'email']
+// ['firstName', 'vouchersRemaining']
 ```
 
 ### Interpolate to a plain string
@@ -49,10 +37,10 @@ const keys = extractVariableKeys(blocks)
 import {interpolateToString} from 'pte-interpolation-core'
 
 const text = interpolateToString(blocks, {
-  firstName: 'Alice',
-  email: 'alice@example.com',
+  firstName: 'Sarah',
+  vouchersRemaining: '3',
 })
-// "Hello, Alice! Your email is alice@example.com."
+// "Hi, Sarah! You have 3 vouchers remaining."
 ```
 
 ### Custom fallback for missing values
@@ -61,23 +49,37 @@ By default, unresolved variables render as `{variableKey}` (e.g. `{firstName}`).
 
 ```ts
 const text = interpolateToString(blocks, {}, (variableKey) => `[${variableKey}]`)
-// "Hello, [firstName]! Your email is [email]."
+// "Hi, [firstName]! You have [vouchersRemaining] vouchers remaining."
 ```
 
-## Authoring Variables in Sanity Studio
+### Detect missing variables
+
+`getMissingVariableKeys` returns the variable keys present in PTE content but absent from the provided values map - useful for validating before sending emails, notifications, or other interpolated content:
+
+```ts
+import {getMissingVariableKeys} from 'pte-interpolation-core'
+
+const missing = getMissingVariableKeys(blocks, {firstName: 'Sarah'})
+// ['vouchersRemaining']
+```
+
+## Related Packages
 
 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 {defineField} from 'sanity'
 import {interpolationVariables} from 'sanity-plugin-pte-interpolation'
 
 defineField({
-  name: 'body',
+  name: 'message',
   type: 'array',
   of: [
     interpolationVariables([
       {id: 'firstName', name: 'First name'},
-      {id: 'email', name: 'Email address'},
+      {id: 'vouchersRemaining', name: 'Vouchers remaining'},
+      {id: 'totalVouchers', name: 'Total vouchers'},
+      {id: 'expiryDate', name: 'Expiry date'},
     ]),
   ],
 })
@@ -91,9 +93,9 @@ Variable blocks in stored Portable Text look like this:
 {
   "_type": "block",
   "children": [
-    {"_type": "span", "text": "Hello, "},
+    {"_type": "span", "text": "Hi, "},
     {"_type": "pteInterpolationVariable", "variableKey": "firstName"},
-    {"_type": "span", "text": "!"}
+    {"_type": "span", "text": ","}
   ]
 }
 ```
@@ -112,6 +114,17 @@ Returns the unique variable keys from an array of PTE blocks, in first-occurrenc
 
 Returns `string[]`.
 
+### `getMissingVariableKeys(blocks, values)`
+
+Returns the variable keys present in PTE content but absent from the provided values map. Keys are deduplicated and returned in first-occurrence order. An empty string `""` is considered a provided value.
+
+| Parameter | Type                      | Description                         |
+| --------- | ------------------------- | ----------------------------------- |
+| `blocks`  | `PortableTextBlockLike[]` | Portable Text blocks to scan        |
+| `values`  | `Record<string, string>`  | Map of variable IDs to their values |
+
+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.

package/dist/index.cjs

@@ -9,6 +9,9 @@ function extractVariableKeys(blocks) {
     return typeof variableKey != "string" || seen.has(variableKey) ? accumulated : (seen.add(variableKey), [...accumulated, variableKey]);
   }, keys), []);
 }
+function getMissingVariableKeys(blocks, values) {
+  return extractVariableKeys(blocks).filter((key) => values[key] === void 0);
+}
 function defaultFallback(variableKey) {
   return `{${variableKey}}`;
 }
@@ -24,5 +27,6 @@ function interpolateToString(blocks, values, fallback = defaultFallback) {
 }
 exports.VARIABLE_TYPE_PREFIX = VARIABLE_TYPE_PREFIX;
 exports.extractVariableKeys = extractVariableKeys;
+exports.getMissingVariableKeys = getMissingVariableKeys;
 exports.interpolateToString = interpolateToString;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +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;;;;"}
+{"version":3,"file":"index.cjs","sources":["../src/constants.ts","../src/extractVariableKeys.ts","../src/getMissingVariableKeys.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 {extractVariableKeys} from './extractVariableKeys'\nimport type {InterpolationValues, PortableTextBlockLike} from './types'\n\n/** @public */\nexport function getMissingVariableKeys(\n  blocks: PortableTextBlockLike[],\n  values: InterpolationValues,\n): string[] {\n  return extractVariableKeys(blocks).filter((key) => values[key] === undefined)\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;ACjBO,SAAS,uBACd,QACA,QACU;AACV,SAAO,oBAAoB,MAAM,EAAE,OAAO,CAAC,QAAQ,OAAO,GAAG,MAAM,MAAS;AAC9E;ACNA,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

@@ -1,6 +1,12 @@
 /** @public */
 export declare function extractVariableKeys(blocks: PortableTextBlockLike[]): string[]
 
+/** @public */
+export declare function getMissingVariableKeys(
+  blocks: PortableTextBlockLike[],
+  values: InterpolationValues,
+): string[]
+
 /** @public */
 export declare function interpolateToString(
   blocks: PortableTextBlockLike[],

package/dist/index.d.ts

@@ -1,6 +1,12 @@
 /** @public */
 export declare function extractVariableKeys(blocks: PortableTextBlockLike[]): string[]
 
+/** @public */
+export declare function getMissingVariableKeys(
+  blocks: PortableTextBlockLike[],
+  values: InterpolationValues,
+): string[]
+
 /** @public */
 export declare function interpolateToString(
   blocks: PortableTextBlockLike[],

package/dist/index.js

@@ -7,6 +7,9 @@ function extractVariableKeys(blocks) {
     return typeof variableKey != "string" || seen.has(variableKey) ? accumulated : (seen.add(variableKey), [...accumulated, variableKey]);
   }, keys), []);
 }
+function getMissingVariableKeys(blocks, values) {
+  return extractVariableKeys(blocks).filter((key) => values[key] === void 0);
+}
 function defaultFallback(variableKey) {
   return `{${variableKey}}`;
 }
@@ -23,6 +26,7 @@ function interpolateToString(blocks, values, fallback = defaultFallback) {
 export {
   VARIABLE_TYPE_PREFIX,
   extractVariableKeys,
+  getMissingVariableKeys,
   interpolateToString
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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;"}
+{"version":3,"file":"index.js","sources":["../src/constants.ts","../src/extractVariableKeys.ts","../src/getMissingVariableKeys.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 {extractVariableKeys} from './extractVariableKeys'\nimport type {InterpolationValues, PortableTextBlockLike} from './types'\n\n/** @public */\nexport function getMissingVariableKeys(\n  blocks: PortableTextBlockLike[],\n  values: InterpolationValues,\n): string[] {\n  return extractVariableKeys(blocks).filter((key) => values[key] === undefined)\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;ACjBO,SAAS,uBACd,QACA,QACU;AACV,SAAO,oBAAoB,MAAM,EAAE,OAAO,CAAC,QAAQ,OAAO,GAAG,MAAM,MAAS;AAC9E;ACNA,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

@@ -1,6 +1,6 @@
 {
   "name": "pte-interpolation-core",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "type": "module",
   "license": "MIT",
   "description": "Framework-agnostic utilities for Portable Text variable interpolation",

package/src/__tests__/fixtures.ts

@@ -85,9 +85,7 @@ export const blockWithNonStringVariableKey: PortableTextBlockLike[] = [
   {
     _type: 'block',
     _key: 'block-1',
-    children: [
-      {_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 123 as unknown as string},
-    ],
+    children: [{_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 123} as never],
   },
 ]
 

package/src/__tests__/getMissingVariableKeys.test.ts

@@ -0,0 +1,88 @@
+import {describe, expect, it} from 'vitest'
+import {getMissingVariableKeys} from '../getMissingVariableKeys'
+import {
+  blockWithNoChildren,
+  blockWithNonStringVariableKey,
+  consecutiveVariablesBlock,
+  duplicateVariableBlock,
+  emptyBlocksContent,
+  multiBlockContent,
+  multipleVariablesBlock,
+  plainTextBlock,
+  singleVariableBlock,
+} from './fixtures'
+
+describe('getMissingVariableKeys', () => {
+  it('returns empty array for empty blocks', () => {
+    expect(getMissingVariableKeys(emptyBlocksContent, {})).toEqual([])
+  })
+
+  it('returns empty array when no variables exist', () => {
+    expect(getMissingVariableKeys(plainTextBlock, {})).toEqual([])
+  })
+
+  it('returns empty array when all variables provided', () => {
+    expect(getMissingVariableKeys(singleVariableBlock, {firstName: 'Alice'})).toEqual([])
+  })
+
+  it('returns empty array when all multiple variables provided', () => {
+    expect(
+      getMissingVariableKeys(multipleVariablesBlock, {
+        firstName: 'Alice',
+        lastName: 'Smith',
+        email: 'a@b.com',
+      }),
+    ).toEqual([])
+  })
+
+  it('returns missing key when value not provided', () => {
+    expect(getMissingVariableKeys(singleVariableBlock, {})).toEqual(['firstName'])
+  })
+
+  it('returns only missing keys when some values provided', () => {
+    expect(getMissingVariableKeys(multipleVariablesBlock, {firstName: 'Alice'})).toEqual([
+      'lastName',
+      'email',
+    ])
+  })
+
+  it('does not treat empty string as missing', () => {
+    expect(getMissingVariableKeys(singleVariableBlock, {firstName: ''})).toEqual([])
+  })
+
+  it('returns missing keys across multiple blocks', () => {
+    expect(getMissingVariableKeys(multiBlockContent, {firstName: 'Alice'})).toEqual(['email'])
+  })
+
+  it('deduplicates missing keys', () => {
+    expect(getMissingVariableKeys(duplicateVariableBlock, {})).toEqual(['firstName'])
+  })
+
+  it('handles blocks with no children property', () => {
+    expect(getMissingVariableKeys(blockWithNoChildren, {})).toEqual([])
+  })
+
+  it('skips children with non-string variableKey', () => {
+    expect(getMissingVariableKeys(blockWithNonStringVariableKey, {})).toEqual([])
+  })
+
+  it('returns missing keys for consecutive variables', () => {
+    expect(getMissingVariableKeys(consecutiveVariablesBlock, {firstName: 'Alice'})).toEqual([
+      'lastName',
+    ])
+  })
+
+  it('ignores extra values not in blocks', () => {
+    expect(
+      getMissingVariableKeys(singleVariableBlock, {firstName: 'Alice', extraKey: 'ignored'}),
+    ).toEqual([])
+  })
+
+  it('preserves first-occurrence order of missing keys', () => {
+    expect(getMissingVariableKeys(multipleVariablesBlock, {})).toEqual([
+      'firstName',
+      'lastName',
+      'email',
+    ])
+  })
+})

package/src/getMissingVariableKeys.ts

@@ -0,0 +1,10 @@
+import {extractVariableKeys} from './extractVariableKeys'
+import type {InterpolationValues, PortableTextBlockLike} from './types'
+
+/** @public */
+export function getMissingVariableKeys(
+  blocks: PortableTextBlockLike[],
+  values: InterpolationValues,
+): string[] {
+  return extractVariableKeys(blocks).filter((key) => values[key] === undefined)
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 export {VARIABLE_TYPE_PREFIX} from './constants'
 export {extractVariableKeys} from './extractVariableKeys'
+export {getMissingVariableKeys} from './getMissingVariableKeys'
 export {interpolateToString} from './interpolateToString'
 export type {
   InterpolationFallback,