@kortyx/hooks 0.12.1 → 0.14.0

package/dist/index.js

@@ -298,7 +298,8 @@ var emitStructuredData = (args) => {
     data: validated
   });
 };
-var shouldEmitStructured = (cfg) => Boolean(cfg) && (cfg?.stream ?? true);
+var shouldEmitStructured = (cfg) => Boolean(cfg);
+var shouldStreamStructured = (cfg) => Boolean(cfg) && (cfg?.stream ?? true);
 
 // src/reason/checkpoint.ts
 var resolveReasonCheckpointKey = (args) => typeof args.id === "string" && args.id.length > 0 ? `__useReason:${args.id}` : `__useReason:auto:${args.autoIndex}`;
@@ -861,12 +862,12 @@ var withStructuredStreamHints = (input, args) => {
   const rules = [];
   for (const path of args.setFieldPaths ?? []) {
     rules.push(
-      `- For the top-level field \`${path}\`, write one stable final value and do not rewrite it after it is complete.`
+      `- For the field path pattern \`${path}\`, write one stable final value and do not rewrite it after it is complete.`
     );
   }
   for (const path of args.appendFieldPaths ?? []) {
     rules.push(
-      `- For the top-level array field \`${path}\`, write items in final order and finish each item before starting the next.`
+      `- For the array field path pattern \`${path}\`, write items in final order and finish each item before starting the next.`
     );
     rules.push(
       `- Once an item in \`${path}\` is complete, do not rewrite or reorder earlier items.`
@@ -874,7 +875,7 @@ var withStructuredStreamHints = (input, args) => {
   }
   for (const path of args.textDeltaFieldPaths ?? []) {
     rules.push(
-      `- For the top-level string field \`${path}\`, write the value progressively by appending text to the end.`
+      `- For the string field path pattern \`${path}\`, write the value progressively by appending text to the end.`
     );
     rules.push(
       `- Do not rewrite or replace the earlier prefix of \`${path}\` once emitted.`
@@ -890,22 +891,12 @@ var withStructuredStreamHints = (input, args) => {
 };
 
 // src/reason/structured-stream.ts
-var escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-var findTopLevelArrayStart = (text, path) => {
-  const match = new RegExp(`"${escapeRegex(path)}"\\s*:\\s*\\[`).exec(text);
-  return match ? match.index + match[0].length : -1;
-};
 var resolveAppendFieldPaths = (cfg) => {
   const fields = cfg?.fields;
   if (!fields) return [];
   const appendPaths = Object.entries(fields).filter(([, mode]) => mode === "append").map(([path]) => path);
   for (const path of appendPaths) {
     assertStructuredPath(path, "useReason structured append");
-    if (path.includes(".")) {
-      throw new Error(
-        "useReason structured append streaming requires non-empty top-level array field keys."
-      );
-    }
   }
   return appendPaths;
 };
@@ -915,11 +906,6 @@ var resolveSetFieldPaths = (cfg) => {
   const setPaths = Object.entries(fields).filter(([, mode]) => mode === "set").map(([path]) => path);
   for (const path of setPaths) {
     assertStructuredPath(path, "useReason structured set");
-    if (path.includes(".")) {
-      throw new Error(
-        "useReason structured set streaming requires non-empty top-level field keys."
-      );
-    }
   }
   return setPaths;
 };
@@ -929,22 +915,9 @@ var resolveTextDeltaFieldPaths = (cfg) => {
   const textPaths = Object.entries(fields).filter(([, mode]) => mode === "text-delta").map(([path]) => path);
   for (const path of textPaths) {
     assertStructuredPath(path, "useReason structured text-delta");
-    if (path.includes(".")) {
-      throw new Error(
-        "useReason structured text-delta streaming requires non-empty top-level string field keys."
-      );
-    }
   }
   return textPaths;
 };
-var findTopLevelFieldValueStart = (text, path) => {
-  const match = new RegExp(`"${escapeRegex(path)}"\\s*:\\s*`).exec(text);
-  return match ? match.index + match[0].length : -1;
-};
-var findTopLevelStringStart = (text, path) => {
-  const match = new RegExp(`"${escapeRegex(path)}"\\s*:\\s*"`).exec(text);
-  return match ? match.index + match[0].length : -1;
-};
 var extractCompletedStringValueAt = (args) => {
   let value = "";
   for (let i = args.start; i < args.text.length; i += 1) {
@@ -990,12 +963,52 @@ var extractCompletedStringValueAt = (args) => {
     complete: false
   };
 };
-var extractCompletedNestedValueAt = (args) => {
+var skipWhitespace = (text, start) => {
+  let i = start;
+  while (i < text.length && /\s/.test(text[i] ?? "")) i += 1;
+  return i;
+};
+var pathSegmentMatches = (patternPart, actualPart) => patternPart === "*" || patternPart === actualPart;
+var pathMatchesPattern = (actualParts, patternParts) => actualParts.length === patternParts.length && actualParts.every(
+  (part, index) => pathSegmentMatches(patternParts[index] ?? "", part)
+);
+var isPathPrefix = (prefix, full) => prefix.length <= full.length && prefix.every((part, index) => pathSegmentMatches(full[index] ?? "", part));
+var parseStringToken = (text, start) => {
+  if (text[start] !== '"') return { complete: false };
+  const parsed = extractCompletedStringValueAt({ text, start: start + 1 });
+  if (!parsed.complete || parsed.value === void 0)
+    return { complete: false };
+  let inEscape = false;
+  for (let i = start + 1; i < text.length; i += 1) {
+    const ch = text[i];
+    if (ch === void 0) break;
+    if (inEscape) {
+      inEscape = false;
+      if (ch === "u") i += 4;
+      continue;
+    }
+    if (ch === "\\") {
+      inEscape = true;
+      continue;
+    }
+    if (ch === '"') {
+      return {
+        complete: true,
+        end: i + 1,
+        value: parsed.value
+      };
+    }
+  }
+  return { complete: false };
+};
+var skipNestedValue = (text, start) => {
+  const opener = text[start];
+  const closer = opener === "{" ? "}" : "]";
   let inString = false;
   let isEscaped = false;
   let nesting = 0;
-  for (let i = args.start; i < args.text.length; i += 1) {
-    const ch = args.text[i];
+  for (let i = start; i < text.length; i += 1) {
+    const ch = text[i];
     if (ch === void 0) break;
     if (inString) {
       if (isEscaped) {
@@ -1015,124 +1028,266 @@ var extractCompletedNestedValueAt = (args) => {
       inString = true;
       continue;
     }
-    if (ch === args.opener) {
+    if (ch === opener) {
       nesting += 1;
       continue;
     }
-    if (ch === args.closer) {
+    if (ch === closer) {
       nesting -= 1;
       if (nesting === 0) {
-        const raw = args.text.slice(args.start, i + 1);
-        try {
-          return {
-            complete: true,
-            value: JSON.parse(raw)
-          };
-        } catch {
-          return {
-            complete: false
-          };
-        }
+        return { complete: true, end: i + 1 };
       }
     }
   }
-  return {
-    complete: false
-  };
+  return { complete: false };
 };
-var extractCompletedFieldValue = (args) => {
-  const start = findTopLevelFieldValueStart(args.text, args.path);
-  if (start < 0) {
-    return {
-      found: false,
-      complete: false
-    };
+var skipCompleteValue = (text, start) => {
+  const i = skipWhitespace(text, start);
+  const first = text[i];
+  if (!first) return { complete: false };
+  if (first === '"') {
+    const parsed = parseStringToken(text, i);
+    return parsed.complete && parsed.end !== void 0 ? { complete: true, end: parsed.end } : { complete: false };
   }
-  const first = args.text[start];
-  if (!first) {
-    return {
-      found: true,
-      complete: false
-    };
+  if (first === "{" || first === "[") {
+    return skipNestedValue(text, i);
   }
+  for (let j = i; j < text.length; j += 1) {
+    const ch = text[j];
+    if (ch !== "," && ch !== "}" && ch !== "]") continue;
+    const raw = text.slice(i, j).trim();
+    if (!raw) return { complete: false };
+    try {
+      JSON.parse(raw);
+      return { complete: true, end: j };
+    } catch {
+      return { complete: false };
+    }
+  }
+  return { complete: false };
+};
+var locateValueStart = (args) => {
+  const [first] = locateValueStarts(args);
+  return first ? {
+    found: true,
+    start: first.start
+  } : {
+    found: false
+  };
+};
+var locateValueStarts = (args) => {
+  const targetParts = parseStructuredPath(
+    args.path,
+    "useReason structured field"
+  );
+  const matches = [];
+  const visitValue = (start, currentParts) => {
+    const valueStart = skipWhitespace(args.text, start);
+    if (pathMatchesPattern(currentParts, targetParts)) {
+      matches.push({
+        path: currentParts.join("."),
+        start: valueStart
+      });
+      return;
+    }
+    if (!isPathPrefix(currentParts, targetParts)) {
+      return;
+    }
+    const first = args.text[valueStart];
+    if (first === "{") visitObject(valueStart + 1, currentParts);
+    if (first === "[") visitArray(valueStart + 1, currentParts);
+  };
+  const visitObject = (start, currentParts) => {
+    let i = skipWhitespace(args.text, start);
+    while (i < args.text.length) {
+      const ch = args.text[i];
+      if (ch === "}") return;
+      if (ch === ",") {
+        i = skipWhitespace(args.text, i + 1);
+        continue;
+      }
+      if (ch !== '"') return;
+      const key = parseStringToken(args.text, i);
+      if (!key.complete || key.end === void 0 || key.value === void 0) {
+        return;
+      }
+      i = skipWhitespace(args.text, key.end);
+      if (args.text[i] !== ":") return;
+      const valueStart = skipWhitespace(args.text, i + 1);
+      const childParts = [...currentParts, key.value];
+      if (pathMatchesPattern(childParts, targetParts)) {
+        matches.push({
+          path: childParts.join("."),
+          start: valueStart
+        });
+      } else if (isPathPrefix(childParts, targetParts)) {
+        visitValue(valueStart, childParts);
+      }
+      const skipped = skipCompleteValue(args.text, valueStart);
+      if (!skipped.complete || skipped.end === void 0) {
+        return;
+      }
+      i = skipWhitespace(args.text, skipped.end);
+      if (args.text[i] === ",") {
+        i = skipWhitespace(args.text, i + 1);
+        continue;
+      }
+      if (args.text[i] === "}") return;
+      return;
+    }
+  };
+  const visitArray = (start, currentParts) => {
+    let i = skipWhitespace(args.text, start);
+    let index = 0;
+    while (i < args.text.length) {
+      if (args.text[i] === "]") return;
+      const childParts = [...currentParts, String(index)];
+      if (pathMatchesPattern(childParts, targetParts)) {
+        matches.push({
+          path: childParts.join("."),
+          start: i
+        });
+      } else if (isPathPrefix(childParts, targetParts)) {
+        visitValue(i, childParts);
+      }
+      const skipped = skipCompleteValue(args.text, i);
+      if (!skipped.complete || skipped.end === void 0) {
+        return;
+      }
+      i = skipWhitespace(args.text, skipped.end);
+      if (args.text[i] === ",") {
+        index += 1;
+        i = skipWhitespace(args.text, i + 1);
+        continue;
+      }
+      if (args.text[i] === "]") return;
+      return;
+    }
+  };
+  visitValue(0, []);
+  return matches;
+};
+var extractCompletedValueAt = (args) => {
+  const start = skipWhitespace(args.text, args.start);
+  const first = args.text[start];
+  if (!first) return { complete: false };
   if (first === '"') {
     const parsed = extractCompletedStringValueAt({
       text: args.text,
       start: start + 1
     });
     return parsed.complete ? {
-      found: true,
       complete: true,
       value: parsed.value
     } : {
-      found: true,
       complete: false
     };
   }
   if (first === "{") {
-    const parsed = extractCompletedNestedValueAt({
+    return extractCompletedNestedValueAt({
       text: args.text,
       start,
       opener: "{",
       closer: "}"
     });
-    return parsed.complete ? {
-      found: true,
-      complete: true,
-      value: parsed.value
-    } : {
-      found: true,
-      complete: false
-    };
   }
   if (first === "[") {
-    const parsed = extractCompletedNestedValueAt({
+    return extractCompletedNestedValueAt({
       text: args.text,
       start,
       opener: "[",
       closer: "]"
     });
-    return parsed.complete ? {
-      found: true,
-      complete: true,
-      value: parsed.value
-    } : {
-      found: true,
-      complete: false
-    };
   }
   for (let i = start; i < args.text.length; i += 1) {
     const ch = args.text[i];
     if (ch === void 0) break;
-    if (ch !== "," && ch !== "}") continue;
+    if (ch !== "," && ch !== "}" && ch !== "]") continue;
     const raw = args.text.slice(start, i).trim();
-    if (!raw) {
-      return {
-        found: true,
-        complete: false
-      };
-    }
+    if (!raw) return { complete: false };
     try {
       return {
-        found: true,
         complete: true,
         value: JSON.parse(raw)
       };
     } catch {
-      return {
-        found: true,
-        complete: false
-      };
+      return { complete: false };
+    }
+  }
+  return { complete: false };
+};
+var extractCompletedNestedValueAt = (args) => {
+  let inString = false;
+  let isEscaped = false;
+  let nesting = 0;
+  for (let i = args.start; i < args.text.length; i += 1) {
+    const ch = args.text[i];
+    if (ch === void 0) break;
+    if (inString) {
+      if (isEscaped) {
+        isEscaped = false;
+        continue;
+      }
+      if (ch === "\\") {
+        isEscaped = true;
+        continue;
+      }
+      if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+    if (ch === args.opener) {
+      nesting += 1;
+      continue;
+    }
+    if (ch === args.closer) {
+      nesting -= 1;
+      if (nesting === 0) {
+        const raw = args.text.slice(args.start, i + 1);
+        try {
+          return {
+            complete: true,
+            value: JSON.parse(raw)
+          };
+        } catch {
+          return {
+            complete: false
+          };
+        }
+      }
     }
   }
   return {
-    found: true,
     complete: false
   };
 };
+var extractCompletedFieldValues = (args) => {
+  const located = locateValueStarts(args);
+  const values = [];
+  for (const match of located) {
+    const parsed = extractCompletedValueAt({
+      text: args.text,
+      start: match.start
+    });
+    if (!parsed.complete) continue;
+    values.push({
+      path: match.path,
+      value: parsed.value
+    });
+  }
+  return values;
+};
 var extractCompletedArrayItems = (args) => {
-  const start = findTopLevelArrayStart(args.text, args.path);
-  if (start < 0) return [];
+  const located = locateValueStart(args);
+  if (!located.found || located.start === void 0) return [];
+  const arrayStart = skipWhitespace(args.text, located.start);
+  if (args.text[arrayStart] !== "[") return [];
+  const start = arrayStart + 1;
   const items = [];
   let inString = false;
   let isEscaped = false;
@@ -1195,17 +1350,39 @@ var extractCompletedArrayItems = (args) => {
   }
   return items;
 };
+var extractCompletedArrayItemGroups = (args) => {
+  return locateValueStarts(args).flatMap((match) => {
+    const items = extractCompletedArrayItems({
+      text: args.text,
+      path: match.path
+    });
+    return items.length > 0 ? [
+      {
+        path: match.path,
+        items
+      }
+    ] : [];
+  });
+};
 var extractStreamingStringValue = (args) => {
-  const start = findTopLevelStringStart(args.text, args.path);
-  if (start < 0) {
+  const located = locateValueStart(args);
+  if (!located.found || located.start === void 0) {
     return {
-      found: false,
+      found: located.found,
+      complete: false,
+      value: ""
+    };
+  }
+  const stringStart = skipWhitespace(args.text, located.start);
+  if (args.text[stringStart] !== '"') {
+    return {
+      found: true,
       complete: false,
       value: ""
     };
   }
   let value = "";
-  for (let i = start; i < args.text.length; i += 1) {
+  for (let i = stringStart + 1; i < args.text.length; i += 1) {
     const ch = args.text[i];
     if (ch === void 0) break;
     if (ch === '"') {
@@ -1257,6 +1434,21 @@ var extractStreamingStringValue = (args) => {
     value
   };
 };
+var extractStreamingStringValues = (args) => {
+  return locateValueStarts(args).flatMap((match) => {
+    const current = extractStreamingStringValue({
+      text: args.text,
+      path: match.path
+    });
+    return current.found ? [
+      {
+        path: match.path,
+        complete: current.complete,
+        value: current.value
+      }
+    ] : [];
+  });
+};
 
 // src/reason/use-reason.ts
 var mergeUsage = (left, right) => {
@@ -1316,7 +1508,7 @@ var emitReasonStructuredOutput = (args) => {
     streamId: args.opId
   });
 };
-var shouldEmitReasonStructured = (args) => (args.emit ?? true) && shouldEmitStructured(args.structured);
+var shouldStreamReasonStructured = (args) => (args.emit ?? true) && shouldStreamStructured(args.structured);
 var resolveEffectiveReasoningIncludeThoughts = (args) => args.reasoning?.includeThoughts ?? args.model.options?.reasoning?.includeThoughts ?? false;
 var resolveEffectiveResponseFormatType = (args) => args.responseFormat?.type ?? args.model.options?.responseFormat?.type;
 var assertReasoningThoughtsCompatibility = (args) => {
@@ -1366,7 +1558,7 @@ async function useReason(args) {
   const appendFieldPaths = resolveAppendFieldPaths(args.structured);
   const textDeltaFieldPaths = resolveTextDeltaFieldPaths(args.structured);
   const useStructuredIncrementalStreaming = Boolean(
-    args.outputSchema && !args.interrupt && (setFieldPaths.length > 0 || appendFieldPaths.length > 0 || textDeltaFieldPaths.length > 0) && args.stream !== false && shouldEmitReasonStructured(args)
+    args.outputSchema && !args.interrupt && (setFieldPaths.length > 0 || appendFieldPaths.length > 0 || textDeltaFieldPaths.length > 0) && args.stream !== false && shouldStreamReasonStructured(args)
   );
   let firstText = "";
   let firstRaw;
@@ -1407,70 +1599,73 @@ async function useReason(args) {
           onTextChunk: (delta) => {
             firstText += delta;
             finalText = firstText;
-            for (const path of setFieldPaths) {
-              const current = extractCompletedFieldValue({
+            for (const fieldPath of setFieldPaths) {
+              const values = extractCompletedFieldValues({
                 text: firstText,
-                path
-              });
-              if (!current.found || !current.complete) continue;
-              const nextSerialized = JSON.stringify(current.value);
-              if (emittedSetValues.get(path) === nextSerialized) continue;
-              emittedSetValues.set(path, nextSerialized);
-              emitStructuredData({
-                kind: "set",
-                path,
-                value: current.value,
-                dataType: args.structured?.dataType ?? "reason-output",
-                ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
-                ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
-                ...id ? { id } : {},
-                streamId: opId
+                path: fieldPath
               });
+              for (const { path, value } of values) {
+                const nextSerialized = JSON.stringify(value);
+                if (emittedSetValues.get(path) === nextSerialized) continue;
+                emittedSetValues.set(path, nextSerialized);
+                emitStructuredData({
+                  kind: "set",
+                  path,
+                  value,
+                  dataType: args.structured?.dataType ?? "reason-output",
+                  ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+                  ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+                  ...id ? { id } : {},
+                  streamId: opId
+                });
+              }
             }
-            for (const path of appendFieldPaths) {
-              const items = extractCompletedArrayItems({
+            for (const fieldPath of appendFieldPaths) {
+              const groups = extractCompletedArrayItemGroups({
                 text: firstText,
-                path
-              });
-              const emittedAppendCount = emittedAppendCounts.get(path) ?? 0;
-              if (items.length <= emittedAppendCount) continue;
-              const nextItems = items.slice(emittedAppendCount);
-              emittedAppendCounts.set(path, items.length);
-              emitStructuredData({
-                kind: "append",
-                path,
-                items: nextItems,
-                dataType: args.structured?.dataType ?? "reason-output",
-                ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
-                ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
-                ...id ? { id } : {},
-                streamId: opId
+                path: fieldPath
               });
+              for (const { path, items } of groups) {
+                const emittedAppendCount = emittedAppendCounts.get(path) ?? 0;
+                if (items.length <= emittedAppendCount) continue;
+                const nextItems = items.slice(emittedAppendCount);
+                emittedAppendCounts.set(path, items.length);
+                emitStructuredData({
+                  kind: "append",
+                  path,
+                  items: nextItems,
+                  dataType: args.structured?.dataType ?? "reason-output",
+                  ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+                  ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+                  ...id ? { id } : {},
+                  streamId: opId
+                });
+              }
             }
-            for (const path of textDeltaFieldPaths) {
-              const current = extractStreamingStringValue({
+            for (const fieldPath of textDeltaFieldPaths) {
+              const values = extractStreamingStringValues({
                 text: firstText,
-                path
+                path: fieldPath
               });
-              const emittedTextValue = emittedTextValues.get(path) ?? "";
-              if (!current.found || current.value.length <= emittedTextValue.length || !current.value.startsWith(emittedTextValue)) {
-                continue;
+              for (const { path, value } of values) {
+                const emittedTextValue = emittedTextValues.get(path) ?? "";
+                if (value.length <= emittedTextValue.length || !value.startsWith(emittedTextValue)) {
+                  continue;
+                }
+                const nextDelta = value.slice(emittedTextValue.length);
+                emittedTextValues.set(path, value);
+                if (nextDelta.length === 0) continue;
+                emitStructuredData({
+                  kind: "text-delta",
+                  path,
+                  delta: nextDelta,
+                  dataType: args.structured?.dataType ?? "reason-output",
+                  ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+                  ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+                  ...id ? { id } : {},
+                  streamId: opId
+                });
               }
-              const nextDelta = current.value.slice(
-                emittedTextValue.length
-              );
-              emittedTextValues.set(path, current.value);
-              if (nextDelta.length === 0) continue;
-              emitStructuredData({
-                kind: "text-delta",
-                path,
-                delta: nextDelta,
-                dataType: args.structured?.dataType ?? "reason-output",
-                ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
-                ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
-                ...id ? { id } : {},
-                streamId: opId
-              });
             }
           }
         } : {}