prompt-identifiers-baml 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2026 Leon Wolf
+
+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
+(including the next paragraph) 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,197 @@
+# prompt-identifiers-baml
+
+BAML wrapper for automatic ID encoding/decoding in LLM function calls. Reduces token usage by up to 90% for UUIDs and ULIDs.
+
+## Installation
+
+```bash
+npm install prompt-identifiers-baml prompt-identifiers @boundaryml/baml
+```
+
+## Quick Start
+
+```typescript
+import { wrapBamlFunction } from 'prompt-identifiers-baml';
+import { b } from './baml_client';
+
+// Wrap your BAML function
+const analyzeUser = wrapBamlFunction(b.AnalyzeUser, {
+  config: { inputFormat: 'UUID', outputFormat: 'SafeNumeric' },
+});
+
+// Use normally - IDs are automatically encoded/decoded
+const result = await analyzeUser({
+  user_id: '123e4567-e89b-42d3-a456-426655440000',
+  items: [
+    { id: '987fcdeb-51a2-43f7-8d9c-0123456789ab', name: 'Order 1' },
+  ],
+});
+
+// The BAML function receives:
+// { user_id: '<000>', items: [{ id: '<001>', name: 'Order 1' }] }
+//
+// You receive the response with original UUIDs restored
+```
+
+## How It Works
+
+1. **Before BAML call**: Deep traverses input object and encodes all ID fields
+   - `123e4567-e89b-42d3-a456-426655440000` → `<000>`
+
+2. **After BAML call**: Deep traverses output object and decodes all placeholders
+   - `<000>` → `123e4567-e89b-42d3-a456-426655440000`
+
+This is completely transparent - you work with real IDs, the LLM works with compact placeholders.
+
+## Configuration
+
+```typescript
+wrapBamlFunction(fn, {
+  // Required: encoding configuration
+  config: {
+    inputFormat: 'UUID',      // or 'ULID' or custom RegExp
+    outputFormat: 'SafeNumeric', // or 'Numeric', 'IdToken', { template: '...' }
+  },
+
+  // Optional: specify which fields to encode
+  // If not provided, all matching strings are encoded
+  encodeFields: ['user_id', 'items[].id', 'metadata.owner_id'],
+
+  // Optional: callbacks for logging/debugging
+  onEncode: (result) => {
+    console.log(`Encoded ${result.encodedCount} IDs`);
+    console.log('Mapping:', result.mapping);
+  },
+  onDecode: (result) => {
+    console.log(`Decoded ${result.decodedCount} placeholders`);
+  },
+});
+```
+
+### Field Path Syntax
+
+The `encodeFields` option supports dot notation and array wildcards:
+
+| Pattern | Description | Example Match |
+|---------|-------------|---------------|
+| `user_id` | Top-level field | `{ user_id: '...' }` |
+| `data.user_id` | Nested field | `{ data: { user_id: '...' } }` |
+| `items[].id` | Array item field | `{ items: [{ id: '...' }] }` |
+| `data.users[].profile.id` | Deep nested | `{ data: { users: [{ profile: { id: '...' } }] } }` |
+
+### Input Formats
+
+| Format | Description | Example |
+|--------|-------------|---------|
+| `'UUID'` | RFC 4122 UUIDs | `123e4567-e89b-42d3-a456-426655440000` |
+| `'ULID'` | Crockford Base32 ULIDs | `01ARZ3NDEKTSV4RRFFQ69G5FAV` |
+| `RegExp` | Custom pattern | `/user-\d{6}/gi` |
+
+### Output Formats
+
+| Format | Description | Example |
+|--------|-------------|---------|
+| `'SafeNumeric'` | Collision-safe with angle brackets (recommended) | `<000>`, `<001>` |
+| `'Numeric'` | Simple numeric with smart triplet expansion | `000`, `001` |
+| `'IdToken'` | Base62 encoding | `0`, `A`, `z`, `10` |
+| `{ template: '...' }` | Custom template | `{ template: '[ID:{i}]' }` → `[ID:0]` |
+
+## Streaming Support
+
+Use `wrapBamlStreamingFunction` for BAML streaming functions:
+
+```typescript
+import { wrapBamlStreamingFunction } from 'prompt-identifiers-baml';
+import { b } from './baml_client';
+
+const streamAnalysis = wrapBamlStreamingFunction(b.stream.AnalyzeUser, {
+  config: { inputFormat: 'UUID', outputFormat: 'SafeNumeric' },
+});
+
+// IDs are decoded in real-time as partials arrive
+for await (const partial of streamAnalysis({ user_id: uuid })) {
+  console.log(partial);
+}
+```
+
+## Utility Functions
+
+### encodeObject
+
+Manually encode an object (useful for custom integrations):
+
+```typescript
+import { encodeObject } from 'prompt-identifiers-baml';
+
+const { encoded, mapping } = encodeObject(
+  { user_id: 'uuid-here', data: { owner: 'other-uuid' } },
+  { inputFormat: 'UUID', outputFormat: 'SafeNumeric' }
+);
+
+// encoded: { user_id: '<000>', data: { owner: '<001>' } }
+// mapping: { '<000>': 'uuid-here', '<001>': 'other-uuid' }
+```
+
+### decodeObject
+
+Manually decode an object:
+
+```typescript
+import { decodeObject } from 'prompt-identifiers-baml';
+
+const decoded = decodeObject(
+  { user_id: '<000>', summary: 'User <000> is active' },
+  { '<000>': 'uuid-here' }
+);
+
+// decoded: { user_id: 'uuid-here', summary: 'User uuid-here is active' }
+```
+
+## Type Safety
+
+The wrapper preserves BAML's TypeScript types:
+
+```typescript
+// BAML-generated types are preserved
+const analyzeUser = wrapBamlFunction(b.AnalyzeUser, { config });
+
+// TypeScript knows the input/output types
+const result: AnalyzeUserOutput = await analyzeUser({
+  user_id: '...',  // Type-checked
+  items: [...],
+});
+```
+
+## Auto-Detection vs Explicit Fields
+
+**Auto-detection mode** (no `encodeFields`):
+- Encodes ALL string fields matching the input pattern
+- Simple to use, works for most cases
+- May encode fields you don't want encoded
+
+**Explicit fields** (with `encodeFields`):
+- Only encodes specified fields
+- More precise control
+- Recommended for production use
+
+```typescript
+// Auto-detection: all UUIDs encoded
+const wrapped1 = wrapBamlFunction(fn, {
+  config: { inputFormat: 'UUID', outputFormat: 'SafeNumeric' },
+});
+
+// Explicit: only user_id and item IDs encoded
+const wrapped2 = wrapBamlFunction(fn, {
+  config: { inputFormat: 'UUID', outputFormat: 'SafeNumeric' },
+  encodeFields: ['user_id', 'items[].id'],
+});
+```
+
+## Peer Dependencies
+
+- `prompt-identifiers` >= 0.1.0
+- `@boundaryml/baml` >= 0.70.0 (optional)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,114 @@
+import { EncodeConfig } from 'prompt-identifiers';
+
+/**
+ * prompt-identifiers-baml - BAML wrapper for automatic ID encoding/decoding
+ *
+ * Wraps BAML-generated TypeScript functions to automatically encode IDs
+ * in inputs and decode them in outputs.
+ */
+
+/** Configuration options for the BAML wrapper */
+interface WrapBamlFunctionOptions {
+    /** Encoding configuration (inputFormat and outputFormat) */
+    config: EncodeConfig;
+    /**
+     * Optional: specific field paths to encode.
+     * If not provided, all string fields matching the input pattern are encoded.
+     *
+     * Supports dot notation and array wildcards:
+     * - 'user_id' - top-level field
+     * - 'data.user_id' - nested field
+     * - 'items[].id' - all 'id' fields in 'items' array
+     * - 'data.users[].profile.id' - deeply nested array field
+     *
+     * @example
+     * encodeFields: ['user_id', 'items[].id', 'metadata.owner_id']
+     */
+    encodeFields?: string[];
+    /**
+     * Optional callback fired after encoding IDs in the input.
+     */
+    onEncode?: (result: {
+        mapping: Record<string, string>;
+        encodedCount: number;
+    }) => void;
+    /**
+     * Optional callback fired after decoding IDs in the output.
+     */
+    onDecode?: (result: {
+        decodedCount: number;
+    }) => void;
+}
+/** A BAML function type (sync or async) */
+type BamlFunction<TInput, TOutput> = (input: TInput) => Promise<TOutput>;
+/** A BAML streaming function type */
+type BamlStreamingFunction<TInput, TPartial, TFinal> = (input: TInput) => AsyncGenerator<TPartial, TFinal, unknown>;
+/**
+ * Wrap a BAML function to automatically encode IDs in inputs and decode them in outputs.
+ *
+ * @example
+ * ```typescript
+ * import { wrapBamlFunction } from 'prompt-identifiers-baml';
+ * import { b } from './baml_client';
+ *
+ * const analyzeUser = wrapBamlFunction(b.AnalyzeUser, {
+ *   config: { inputFormat: 'UUID', outputFormat: 'SafeNumeric' },
+ *   encodeFields: ['user_id', 'items[].id'],  // Optional: specific fields
+ * });
+ *
+ * // Use normally - IDs are auto-encoded/decoded
+ * const result = await analyzeUser({
+ *   user_id: '123e4567-e89b-42d3-a456-426655440000',
+ *   items: [{ id: '987fcdeb-51a2-43f7-8d9c-0123456789ab', name: 'test' }]
+ * });
+ * ```
+ */
+declare function wrapBamlFunction<TInput, TOutput>(fn: BamlFunction<TInput, TOutput>, options: WrapBamlFunctionOptions): BamlFunction<TInput, TOutput>;
+/**
+ * Wrap a BAML streaming function to automatically encode IDs in inputs
+ * and decode them in outputs (both partial and final).
+ *
+ * @example
+ * ```typescript
+ * import { wrapBamlStreamingFunction } from 'prompt-identifiers-baml';
+ * import { b } from './baml_client';
+ *
+ * const streamAnalysis = wrapBamlStreamingFunction(b.stream.AnalyzeUser, {
+ *   config: { inputFormat: 'UUID', outputFormat: 'SafeNumeric' },
+ * });
+ *
+ * for await (const partial of streamAnalysis({ user_id: 'uuid-here' })) {
+ *   console.log(partial); // IDs decoded in real-time
+ * }
+ * ```
+ */
+declare function wrapBamlStreamingFunction<TInput, TPartial, TFinal>(fn: BamlStreamingFunction<TInput, TPartial, TFinal>, options: WrapBamlFunctionOptions): BamlStreamingFunction<TInput, TPartial, TFinal>;
+/**
+ * Utility function to encode a plain object (useful for manual encoding).
+ *
+ * @example
+ * ```typescript
+ * const { encoded, mapping } = encodeObject(
+ *   { user_id: 'uuid-here', data: { owner: 'other-uuid' } },
+ *   { inputFormat: 'UUID', outputFormat: 'SafeNumeric' }
+ * );
+ * ```
+ */
+declare function encodeObject<T>(obj: T, config: EncodeConfig, encodeFields?: string[]): {
+    encoded: T;
+    mapping: Record<string, string>;
+};
+/**
+ * Utility function to decode a plain object (useful for manual decoding).
+ *
+ * @example
+ * ```typescript
+ * const decoded = decodeObject(
+ *   { user_id: '«000»', summary: 'User «000» is active' },
+ *   { '«000»': 'uuid-here' }
+ * );
+ * ```
+ */
+declare function decodeObject<T>(obj: T, mapping: Record<string, string>): T;
+
+export { type BamlFunction, type BamlStreamingFunction, type WrapBamlFunctionOptions, decodeObject, encodeObject, wrapBamlFunction, wrapBamlStreamingFunction };

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+import { EncodeConfig } from 'prompt-identifiers';
+
+/**
+ * prompt-identifiers-baml - BAML wrapper for automatic ID encoding/decoding
+ *
+ * Wraps BAML-generated TypeScript functions to automatically encode IDs
+ * in inputs and decode them in outputs.
+ */
+
+/** Configuration options for the BAML wrapper */
+interface WrapBamlFunctionOptions {
+    /** Encoding configuration (inputFormat and outputFormat) */
+    config: EncodeConfig;
+    /**
+     * Optional: specific field paths to encode.
+     * If not provided, all string fields matching the input pattern are encoded.
+     *
+     * Supports dot notation and array wildcards:
+     * - 'user_id' - top-level field
+     * - 'data.user_id' - nested field
+     * - 'items[].id' - all 'id' fields in 'items' array
+     * - 'data.users[].profile.id' - deeply nested array field
+     *
+     * @example
+     * encodeFields: ['user_id', 'items[].id', 'metadata.owner_id']
+     */
+    encodeFields?: string[];
+    /**
+     * Optional callback fired after encoding IDs in the input.
+     */
+    onEncode?: (result: {
+        mapping: Record<string, string>;
+        encodedCount: number;
+    }) => void;
+    /**
+     * Optional callback fired after decoding IDs in the output.
+     */
+    onDecode?: (result: {
+        decodedCount: number;
+    }) => void;
+}
+/** A BAML function type (sync or async) */
+type BamlFunction<TInput, TOutput> = (input: TInput) => Promise<TOutput>;
+/** A BAML streaming function type */
+type BamlStreamingFunction<TInput, TPartial, TFinal> = (input: TInput) => AsyncGenerator<TPartial, TFinal, unknown>;
+/**
+ * Wrap a BAML function to automatically encode IDs in inputs and decode them in outputs.
+ *
+ * @example
+ * ```typescript
+ * import { wrapBamlFunction } from 'prompt-identifiers-baml';
+ * import { b } from './baml_client';
+ *
+ * const analyzeUser = wrapBamlFunction(b.AnalyzeUser, {
+ *   config: { inputFormat: 'UUID', outputFormat: 'SafeNumeric' },
+ *   encodeFields: ['user_id', 'items[].id'],  // Optional: specific fields
+ * });
+ *
+ * // Use normally - IDs are auto-encoded/decoded
+ * const result = await analyzeUser({
+ *   user_id: '123e4567-e89b-42d3-a456-426655440000',
+ *   items: [{ id: '987fcdeb-51a2-43f7-8d9c-0123456789ab', name: 'test' }]
+ * });
+ * ```
+ */
+declare function wrapBamlFunction<TInput, TOutput>(fn: BamlFunction<TInput, TOutput>, options: WrapBamlFunctionOptions): BamlFunction<TInput, TOutput>;
+/**
+ * Wrap a BAML streaming function to automatically encode IDs in inputs
+ * and decode them in outputs (both partial and final).
+ *
+ * @example
+ * ```typescript
+ * import { wrapBamlStreamingFunction } from 'prompt-identifiers-baml';
+ * import { b } from './baml_client';
+ *
+ * const streamAnalysis = wrapBamlStreamingFunction(b.stream.AnalyzeUser, {
+ *   config: { inputFormat: 'UUID', outputFormat: 'SafeNumeric' },
+ * });
+ *
+ * for await (const partial of streamAnalysis({ user_id: 'uuid-here' })) {
+ *   console.log(partial); // IDs decoded in real-time
+ * }
+ * ```
+ */
+declare function wrapBamlStreamingFunction<TInput, TPartial, TFinal>(fn: BamlStreamingFunction<TInput, TPartial, TFinal>, options: WrapBamlFunctionOptions): BamlStreamingFunction<TInput, TPartial, TFinal>;
+/**
+ * Utility function to encode a plain object (useful for manual encoding).
+ *
+ * @example
+ * ```typescript
+ * const { encoded, mapping } = encodeObject(
+ *   { user_id: 'uuid-here', data: { owner: 'other-uuid' } },
+ *   { inputFormat: 'UUID', outputFormat: 'SafeNumeric' }
+ * );
+ * ```
+ */
+declare function encodeObject<T>(obj: T, config: EncodeConfig, encodeFields?: string[]): {
+    encoded: T;
+    mapping: Record<string, string>;
+};
+/**
+ * Utility function to decode a plain object (useful for manual decoding).
+ *
+ * @example
+ * ```typescript
+ * const decoded = decodeObject(
+ *   { user_id: '«000»', summary: 'User «000» is active' },
+ *   { '«000»': 'uuid-here' }
+ * );
+ * ```
+ */
+declare function decodeObject<T>(obj: T, mapping: Record<string, string>): T;
+
+export { type BamlFunction, type BamlStreamingFunction, type WrapBamlFunctionOptions, decodeObject, encodeObject, wrapBamlFunction, wrapBamlStreamingFunction };

package/dist/index.js

@@ -0,0 +1,288 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  decodeObject: () => decodeObject,
+  encodeObject: () => encodeObject,
+  wrapBamlFunction: () => wrapBamlFunction,
+  wrapBamlStreamingFunction: () => wrapBamlStreamingFunction
+});
+module.exports = __toCommonJS(index_exports);
+var import_prompt_identifiers = require("prompt-identifiers");
+function parseFieldPath(path) {
+  const segments = [];
+  let current = "";
+  for (let i = 0; i < path.length; i++) {
+    const char = path[i];
+    if (char === ".") {
+      if (current) {
+        segments.push(current);
+        current = "";
+      }
+    } else if (char === "[" && path[i + 1] === "]") {
+      if (current) {
+        segments.push(current);
+        current = "";
+      }
+      segments.push("[]");
+      i++;
+    } else {
+      current += char;
+    }
+  }
+  if (current) {
+    segments.push(current);
+  }
+  return segments;
+}
+function matchesFieldPath(currentPath, targetSegments) {
+  if (currentPath.length !== targetSegments.length) {
+    return false;
+  }
+  for (let i = 0; i < targetSegments.length; i++) {
+    const target = targetSegments[i];
+    const current = currentPath[i];
+    if (target === "[]") {
+      if (!/^\d+$/.test(current)) {
+        return false;
+      }
+    } else if (target !== current) {
+      return false;
+    }
+  }
+  return true;
+}
+function getInputPattern(inputFormat) {
+  if (inputFormat instanceof RegExp) {
+    const flags = inputFormat.flags.includes("g") ? inputFormat.flags : inputFormat.flags + "g";
+    return new RegExp(inputFormat.source, flags);
+  }
+  if (inputFormat === "UUID") {
+    return /\b[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/gi;
+  }
+  return /\b[0-9A-HJKMNP-TV-Z]{26}\b/gi;
+}
+function formatPlaceholder(outputFormat, index) {
+  if (outputFormat === "SafeNumeric") {
+    const s = index.toString();
+    const width = Math.max(3, Math.ceil(s.length / 3) * 3);
+    return `<${s.padStart(width, "0")}>`;
+  }
+  if (outputFormat === "Numeric") {
+    const s = index.toString();
+    const width = Math.max(3, Math.ceil(s.length / 3) * 3);
+    return s.padStart(width, "0");
+  }
+  if (outputFormat === "IdToken") {
+    const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+    if (index < 62) return BASE62[index];
+    let result = "";
+    let n = index;
+    while (n > 0) {
+      result = BASE62[n % 62] + result;
+      n = Math.floor(n / 62);
+    }
+    return result;
+  }
+  if (outputFormat === "Passthrough") {
+    return "";
+  }
+  if (typeof outputFormat === "function") {
+    return outputFormat(index);
+  }
+  const template = outputFormat.template;
+  const match = template.match(/\{i(?::([^}]+))?\}/);
+  if (!match) return `${index}`;
+  const specifier = match[1];
+  let formatted;
+  if (!specifier) {
+    formatted = index.toString();
+  } else if (specifier === "base62") {
+    const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+    if (index < 62) formatted = BASE62[index];
+    else {
+      formatted = "";
+      let n = index;
+      while (n > 0) {
+        formatted = BASE62[n % 62] + formatted;
+        n = Math.floor(n / 62);
+      }
+    }
+  } else if (specifier === "zeroFilled") {
+    const s = index.toString();
+    const width = Math.max(3, Math.ceil(s.length / 3) * 3);
+    formatted = s.padStart(width, "0");
+  } else {
+    const padMatch = specifier.match(/^(\d+)$/);
+    if (padMatch) {
+      formatted = index.toString().padStart(parseInt(padMatch[1], 10), "0");
+    } else {
+      formatted = index.toString();
+    }
+  }
+  return template.replace(match[0], formatted);
+}
+function encodeStringWithContext(text, ctx) {
+  if (ctx.config.outputFormat === "Passthrough") {
+    return text;
+  }
+  const pattern = getInputPattern(ctx.config.inputFormat);
+  pattern.lastIndex = 0;
+  return text.replace(pattern, (match) => {
+    const id = match.toLowerCase();
+    if (ctx.idToPlaceholder.has(id)) {
+      return ctx.idToPlaceholder.get(id);
+    }
+    const placeholder = formatPlaceholder(ctx.config.outputFormat, ctx.nextIndex);
+    ctx.nextIndex++;
+    ctx.idToPlaceholder.set(id, placeholder);
+    ctx.mapping[placeholder] = id;
+    return placeholder;
+  });
+}
+function deepEncode(value, ctx, path = []) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const shouldEncode = ctx.fieldPaths === null || ctx.fieldPaths.some((fp) => matchesFieldPath(path, fp));
+    if (!shouldEncode) {
+      return value;
+    }
+    return encodeStringWithContext(value, ctx);
+  }
+  if (Array.isArray(value)) {
+    return value.map(
+      (item, index) => deepEncode(item, ctx, [...path, String(index)])
+    );
+  }
+  if (typeof value === "object") {
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = deepEncode(val, ctx, [...path, key]);
+    }
+    return result;
+  }
+  return value;
+}
+function deepDecode(value, mapping, countRef) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const decoded = (0, import_prompt_identifiers.decode)(value, mapping);
+    if (decoded !== value) {
+      countRef.count++;
+    }
+    return decoded;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => deepDecode(item, mapping, countRef));
+  }
+  if (typeof value === "object") {
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = deepDecode(val, mapping, countRef);
+    }
+    return result;
+  }
+  return value;
+}
+function wrapBamlFunction(fn, options) {
+  const { config, encodeFields, onEncode, onDecode } = options;
+  const fieldPaths = encodeFields ? encodeFields.map(parseFieldPath) : null;
+  return async (input) => {
+    const ctx = {
+      config,
+      fieldPaths,
+      idToPlaceholder: /* @__PURE__ */ new Map(),
+      mapping: {},
+      nextIndex: 0
+    };
+    const encodedInput = deepEncode(input, ctx);
+    onEncode?.({
+      mapping: ctx.mapping,
+      encodedCount: Object.keys(ctx.mapping).length
+    });
+    const output = await fn(encodedInput);
+    const countRef = { count: 0 };
+    const decodedOutput = deepDecode(output, ctx.mapping, countRef);
+    onDecode?.({ decodedCount: countRef.count });
+    return decodedOutput;
+  };
+}
+function wrapBamlStreamingFunction(fn, options) {
+  const { config, encodeFields, onEncode, onDecode } = options;
+  const fieldPaths = encodeFields ? encodeFields.map(parseFieldPath) : null;
+  return async function* (input) {
+    const ctx = {
+      config,
+      fieldPaths,
+      idToPlaceholder: /* @__PURE__ */ new Map(),
+      mapping: {},
+      nextIndex: 0
+    };
+    const encodedInput = deepEncode(input, ctx);
+    onEncode?.({
+      mapping: ctx.mapping,
+      encodedCount: Object.keys(ctx.mapping).length
+    });
+    const generator = fn(encodedInput);
+    let totalDecoded = 0;
+    while (true) {
+      const { value, done } = await generator.next();
+      if (done) {
+        const countRef2 = { count: 0 };
+        const decodedValue2 = deepDecode(value, ctx.mapping, countRef2);
+        totalDecoded += countRef2.count;
+        onDecode?.({ decodedCount: totalDecoded });
+        return decodedValue2;
+      }
+      const countRef = { count: 0 };
+      const decodedValue = deepDecode(value, ctx.mapping, countRef);
+      totalDecoded += countRef.count;
+      yield decodedValue;
+    }
+  };
+}
+function encodeObject(obj, config, encodeFields) {
+  const fieldPaths = encodeFields ? encodeFields.map(parseFieldPath) : null;
+  const ctx = {
+    config,
+    fieldPaths,
+    idToPlaceholder: /* @__PURE__ */ new Map(),
+    mapping: {},
+    nextIndex: 0
+  };
+  const encoded = deepEncode(obj, ctx);
+  return { encoded, mapping: ctx.mapping };
+}
+function decodeObject(obj, mapping) {
+  const countRef = { count: 0 };
+  return deepDecode(obj, mapping, countRef);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  decodeObject,
+  encodeObject,
+  wrapBamlFunction,
+  wrapBamlStreamingFunction
+});

package/dist/index.mjs

@@ -0,0 +1,260 @@
+// src/index.ts
+import { decode } from "prompt-identifiers";
+function parseFieldPath(path) {
+  const segments = [];
+  let current = "";
+  for (let i = 0; i < path.length; i++) {
+    const char = path[i];
+    if (char === ".") {
+      if (current) {
+        segments.push(current);
+        current = "";
+      }
+    } else if (char === "[" && path[i + 1] === "]") {
+      if (current) {
+        segments.push(current);
+        current = "";
+      }
+      segments.push("[]");
+      i++;
+    } else {
+      current += char;
+    }
+  }
+  if (current) {
+    segments.push(current);
+  }
+  return segments;
+}
+function matchesFieldPath(currentPath, targetSegments) {
+  if (currentPath.length !== targetSegments.length) {
+    return false;
+  }
+  for (let i = 0; i < targetSegments.length; i++) {
+    const target = targetSegments[i];
+    const current = currentPath[i];
+    if (target === "[]") {
+      if (!/^\d+$/.test(current)) {
+        return false;
+      }
+    } else if (target !== current) {
+      return false;
+    }
+  }
+  return true;
+}
+function getInputPattern(inputFormat) {
+  if (inputFormat instanceof RegExp) {
+    const flags = inputFormat.flags.includes("g") ? inputFormat.flags : inputFormat.flags + "g";
+    return new RegExp(inputFormat.source, flags);
+  }
+  if (inputFormat === "UUID") {
+    return /\b[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/gi;
+  }
+  return /\b[0-9A-HJKMNP-TV-Z]{26}\b/gi;
+}
+function formatPlaceholder(outputFormat, index) {
+  if (outputFormat === "SafeNumeric") {
+    const s = index.toString();
+    const width = Math.max(3, Math.ceil(s.length / 3) * 3);
+    return `<${s.padStart(width, "0")}>`;
+  }
+  if (outputFormat === "Numeric") {
+    const s = index.toString();
+    const width = Math.max(3, Math.ceil(s.length / 3) * 3);
+    return s.padStart(width, "0");
+  }
+  if (outputFormat === "IdToken") {
+    const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+    if (index < 62) return BASE62[index];
+    let result = "";
+    let n = index;
+    while (n > 0) {
+      result = BASE62[n % 62] + result;
+      n = Math.floor(n / 62);
+    }
+    return result;
+  }
+  if (outputFormat === "Passthrough") {
+    return "";
+  }
+  if (typeof outputFormat === "function") {
+    return outputFormat(index);
+  }
+  const template = outputFormat.template;
+  const match = template.match(/\{i(?::([^}]+))?\}/);
+  if (!match) return `${index}`;
+  const specifier = match[1];
+  let formatted;
+  if (!specifier) {
+    formatted = index.toString();
+  } else if (specifier === "base62") {
+    const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+    if (index < 62) formatted = BASE62[index];
+    else {
+      formatted = "";
+      let n = index;
+      while (n > 0) {
+        formatted = BASE62[n % 62] + formatted;
+        n = Math.floor(n / 62);
+      }
+    }
+  } else if (specifier === "zeroFilled") {
+    const s = index.toString();
+    const width = Math.max(3, Math.ceil(s.length / 3) * 3);
+    formatted = s.padStart(width, "0");
+  } else {
+    const padMatch = specifier.match(/^(\d+)$/);
+    if (padMatch) {
+      formatted = index.toString().padStart(parseInt(padMatch[1], 10), "0");
+    } else {
+      formatted = index.toString();
+    }
+  }
+  return template.replace(match[0], formatted);
+}
+function encodeStringWithContext(text, ctx) {
+  if (ctx.config.outputFormat === "Passthrough") {
+    return text;
+  }
+  const pattern = getInputPattern(ctx.config.inputFormat);
+  pattern.lastIndex = 0;
+  return text.replace(pattern, (match) => {
+    const id = match.toLowerCase();
+    if (ctx.idToPlaceholder.has(id)) {
+      return ctx.idToPlaceholder.get(id);
+    }
+    const placeholder = formatPlaceholder(ctx.config.outputFormat, ctx.nextIndex);
+    ctx.nextIndex++;
+    ctx.idToPlaceholder.set(id, placeholder);
+    ctx.mapping[placeholder] = id;
+    return placeholder;
+  });
+}
+function deepEncode(value, ctx, path = []) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const shouldEncode = ctx.fieldPaths === null || ctx.fieldPaths.some((fp) => matchesFieldPath(path, fp));
+    if (!shouldEncode) {
+      return value;
+    }
+    return encodeStringWithContext(value, ctx);
+  }
+  if (Array.isArray(value)) {
+    return value.map(
+      (item, index) => deepEncode(item, ctx, [...path, String(index)])
+    );
+  }
+  if (typeof value === "object") {
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = deepEncode(val, ctx, [...path, key]);
+    }
+    return result;
+  }
+  return value;
+}
+function deepDecode(value, mapping, countRef) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const decoded = decode(value, mapping);
+    if (decoded !== value) {
+      countRef.count++;
+    }
+    return decoded;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => deepDecode(item, mapping, countRef));
+  }
+  if (typeof value === "object") {
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = deepDecode(val, mapping, countRef);
+    }
+    return result;
+  }
+  return value;
+}
+function wrapBamlFunction(fn, options) {
+  const { config, encodeFields, onEncode, onDecode } = options;
+  const fieldPaths = encodeFields ? encodeFields.map(parseFieldPath) : null;
+  return async (input) => {
+    const ctx = {
+      config,
+      fieldPaths,
+      idToPlaceholder: /* @__PURE__ */ new Map(),
+      mapping: {},
+      nextIndex: 0
+    };
+    const encodedInput = deepEncode(input, ctx);
+    onEncode?.({
+      mapping: ctx.mapping,
+      encodedCount: Object.keys(ctx.mapping).length
+    });
+    const output = await fn(encodedInput);
+    const countRef = { count: 0 };
+    const decodedOutput = deepDecode(output, ctx.mapping, countRef);
+    onDecode?.({ decodedCount: countRef.count });
+    return decodedOutput;
+  };
+}
+function wrapBamlStreamingFunction(fn, options) {
+  const { config, encodeFields, onEncode, onDecode } = options;
+  const fieldPaths = encodeFields ? encodeFields.map(parseFieldPath) : null;
+  return async function* (input) {
+    const ctx = {
+      config,
+      fieldPaths,
+      idToPlaceholder: /* @__PURE__ */ new Map(),
+      mapping: {},
+      nextIndex: 0
+    };
+    const encodedInput = deepEncode(input, ctx);
+    onEncode?.({
+      mapping: ctx.mapping,
+      encodedCount: Object.keys(ctx.mapping).length
+    });
+    const generator = fn(encodedInput);
+    let totalDecoded = 0;
+    while (true) {
+      const { value, done } = await generator.next();
+      if (done) {
+        const countRef2 = { count: 0 };
+        const decodedValue2 = deepDecode(value, ctx.mapping, countRef2);
+        totalDecoded += countRef2.count;
+        onDecode?.({ decodedCount: totalDecoded });
+        return decodedValue2;
+      }
+      const countRef = { count: 0 };
+      const decodedValue = deepDecode(value, ctx.mapping, countRef);
+      totalDecoded += countRef.count;
+      yield decodedValue;
+    }
+  };
+}
+function encodeObject(obj, config, encodeFields) {
+  const fieldPaths = encodeFields ? encodeFields.map(parseFieldPath) : null;
+  const ctx = {
+    config,
+    fieldPaths,
+    idToPlaceholder: /* @__PURE__ */ new Map(),
+    mapping: {},
+    nextIndex: 0
+  };
+  const encoded = deepEncode(obj, ctx);
+  return { encoded, mapping: ctx.mapping };
+}
+function decodeObject(obj, mapping) {
+  const countRef = { count: 0 };
+  return deepDecode(obj, mapping, countRef);
+}
+export {
+  decodeObject,
+  encodeObject,
+  wrapBamlFunction,
+  wrapBamlStreamingFunction
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "prompt-identifiers-baml",
+  "version": "0.1.0",
+  "description": "BAML integration for prompt-identifiers. Efficient ID compression for token optimization.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "llm",
+    "ai",
+    "baml",
+    "boundaryml",
+    "tokens",
+    "compression",
+    "prompt",
+    "uuid",
+    "ulid"
+  ],
+  "author": "Leon Wolf <fogxdev@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fogx/prompt-identifiers"
+  },
+  "peerDependencies": {
+    "prompt-identifiers": ">=0.1.0",
+    "@boundaryml/baml": ">=0.70.0"
+  },
+  "peerDependenciesMeta": {
+    "@boundaryml/baml": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.0.0",
+    "prompt-identifiers": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "jest"
+  }
+}