@ssml-builder-js/azure-tts-client 2.14.0 → 2.15.0

package/src/safe.ts

@@ -1,17 +1,30 @@
 import { validateAzureSsml, type AzureValidationOptions, type SsmlDiagnostic } from "@ssml-builder-js/ssml-core";
-import { AzureTtsError, createSpeechSdkError } from "./errors.ts";
+import {
+  type AzureTtsError,
+  type AzureTtsSynthesisError,
+  type SynthesisErrorKind,
+  toSynthesisError,
+} from "./errors.ts";
 import type { AzureTtsClient } from "./client.ts";
 import { mergeSynthesisResults } from "./synthesis.ts";
-import type { SsmlSynthesisChunk, SsmlSynthesisResult, SynthesisProgressEvent } from "./types.ts";
+import type {
+  SsmlSynthesisChunk,
+  SsmlSynthesisResult,
+  SynthesisProgressEvent,
+  SynthesizeChunksOptions,
+} from "./types.ts";
+import type { AzureTtsOutputFormat } from "./outputFormats.ts";
 
 export interface SsmlValidationError {
-  readonly kind: "validation";
+  readonly kind: "validation-error";
   readonly message: string;
   readonly diagnostics: readonly SsmlDiagnostic[];
 }
 
+export type SsmlSynthesisError = SsmlValidationError | AzureTtsSynthesisError;
+
 export class ChunkValidationError extends Error {
-  readonly kind = "chunk-validation" as const;
+  readonly kind = "validation-error" as const;
   readonly chunkIndex: number;
   readonly diagnostics: readonly SsmlDiagnostic[];
 
@@ -25,15 +38,26 @@ export class ChunkValidationError extends Error {
 
 export type Result<T, E> =
   | { readonly ok: true; readonly success: true; readonly status: "success"; readonly value: T }
-  | {
-      readonly ok: false;
-      readonly success: false;
-      readonly status: "validation-error" | "azure-api-error";
-      readonly error: E;
-    };
+  | (E extends { readonly kind: infer Kind extends SynthesisErrorKind }
+      ? {
+          readonly ok: false;
+          readonly success: false;
+          readonly status: Kind;
+          readonly error: E;
+        }
+      : {
+          readonly ok: false;
+          readonly success: false;
+          readonly status: SynthesisErrorKind;
+          readonly error: E;
+        });
 
 export type SynthesisResult<T, E> = Result<T, E>;
 
+function failure<E extends { readonly kind: SynthesisErrorKind }>(error: E): Result<never, E> {
+  return { ok: false, success: false, status: error.kind, error } as Result<never, E>;
+}
+
 export type Success<T> = Extract<Result<T, never>, { readonly ok: true }>;
 export type ValidationErrorResult = Extract<
   Result<never, SsmlValidationError>,
@@ -44,29 +68,33 @@ export type AzureApiErrorResult = Extract<Result<never, AzureTtsError>, { readon
 export type SsmlSynthesisSafeResult =
   | Result<SsmlSynthesisResult, never>
   | Result<never, SsmlValidationError>
-  | Result<never, AzureTtsError>;
+  | Result<never, SsmlSynthesisError>;
 
 export interface SynthesizeSsmlSafeOptions extends AzureValidationOptions {
   /** Optional nested form for callers that want to keep validation settings grouped. */
   validation?: AzureValidationOptions;
+  signal?: AbortSignal;
 }
 
 export interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
   validation?: AzureValidationOptions;
   outputFormat?: string;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  sourceNodePath?: string[];
   onProgress?: (event: SynthesisProgressEvent) => void;
 }
 
 export type SsmlSynthesisChunksSafeResult =
   | Result<SsmlSynthesisResult, never>
   | Result<never, ChunkValidationError>
-  | Result<never, AzureTtsError>;
+  | Result<never, SsmlSynthesisError | ChunkValidationError>;
 
 interface SynthesisClient {
-  synthesizeSsml(ssml: string): Promise<SsmlSynthesisResult>;
+  synthesizeSsml(ssml: string, options?: Partial<SynthesizeChunksOptions>): Promise<SsmlSynthesisResult>;
   synthesizeChunks?(
     chunks: readonly (SsmlSynthesisChunk | string)[],
-    options?: { onProgress?: (event: SynthesisProgressEvent) => void },
+    options?: SynthesizeChunksOptions,
   ): Promise<SsmlSynthesisResult>;
 }
 
@@ -76,27 +104,31 @@ export async function synthesizeSsmlSafe(
   ssml: string,
   options: SynthesizeSsmlSafeOptions = {},
 ): Promise<SsmlSynthesisSafeResult> {
-  const validationOptions = options.validation ?? options;
+  const validationOptions = withValidationSignal(options.validation ?? options, options.signal);
   const diagnostics = await Promise.resolve(validateAzureSsml(ssml, validationOptions));
+  if (options.signal?.aborted) {
+    const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+    return failure(error);
+  }
   const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
   if (errors.length > 0) {
-    return {
-      ok: false,
-      success: false,
-      status: "validation-error",
-      error: {
-        kind: "validation",
-        message: "SSML validation failed; the Azure Speech API was not called.",
-        diagnostics: errors,
-      },
-    };
+    return failure({
+      kind: "validation-error",
+      message: "SSML validation failed; the Azure Speech API was not called.",
+      diagnostics: errors,
+    });
   }
 
   try {
-    return { ok: true, success: true, status: "success", value: await client.synthesizeSsml(ssml) };
+    return {
+      ok: true,
+      success: true,
+      status: "success",
+      value: await client.synthesizeSsml(ssml, { signal: options.signal }),
+    };
   } catch (error) {
-    const azureError = error instanceof AzureTtsError ? error : createSpeechSdkError(error);
-    return { ok: false, success: false, status: "azure-api-error", error: azureError };
+    const synthesisError = toSynthesisError(error);
+    return failure(synthesisError);
   }
 }
 
@@ -106,7 +138,11 @@ export async function synthesizeSsmlChunksSafe(
   chunks: readonly (SsmlSynthesisChunk | string)[],
   options: SynthesizeSsmlChunksSafeOptions = {},
 ): Promise<SsmlSynthesisChunksSafeResult> {
-  const validationOptions = options.validation ?? options;
+  const validationOptions = withValidationSignal(options.validation ?? options, options.signal);
+  if (options.signal?.aborted) {
+    const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+    return failure(error);
+  }
   const pending = (index: number, status: SynthesisProgressEvent["status"], error?: unknown): void => {
     options.onProgress?.({
       currentChunk: status === "success" ? index + 1 : index,
@@ -126,7 +162,11 @@ export async function synthesizeSsmlChunksSafe(
   const validations = await Promise.all(
     chunks.map(async (chunk) => {
       const ssml = typeof chunk === "string" ? chunk : chunk.ssml;
-      const diagnostics = await Promise.resolve(validateAzureSsml(ssml, validationOptions));
+      const sourceNodePath =
+        typeof chunk === "string" ? options.sourceNodePath : (chunk.sourceNodePath ?? options.sourceNodePath);
+      const diagnostics = await Promise.resolve(
+        validateAzureSsml(ssml, { ...validationOptions, ...(sourceNodePath ? { sourceNodePath } : {}) }),
+      );
       return diagnostics.filter((diagnostic) => diagnostic.severity === "error");
     }),
   );
@@ -134,22 +174,38 @@ export async function synthesizeSsmlChunksSafe(
   if (firstInvalidIndex >= 0) {
     const error = new ChunkValidationError(firstInvalidIndex, validations[firstInvalidIndex] ?? []);
     pending(firstInvalidIndex, "failed", error);
-    return { ok: false, success: false, status: "validation-error", error };
+    return failure(error);
   }
 
   try {
     if (client.synthesizeChunks) {
-      const value = await client.synthesizeChunks(chunks, { onProgress: options.onProgress });
+      const normalizedChunks = chunks.map((chunk) => {
+        if (typeof chunk === "string" || chunk.sourceNodePath || !options.sourceNodePath) return chunk;
+        return { ...chunk, sourceNodePath: [...options.sourceNodePath] };
+      });
+      const value = await client.synthesizeChunks(normalizedChunks, {
+        onProgress: options.onProgress,
+        outputFormat: options.outputFormat,
+        signal: options.signal,
+        timeoutMs: options.timeoutMs,
+        sourceNodePath: options.sourceNodePath,
+      });
       return { ok: true, success: true, status: "success", value };
     }
     const results: SsmlSynthesisResult[] = [];
     for (const [index, chunk] of chunks.entries()) {
       const input = typeof chunk === "string" ? { ssml: chunk } : chunk;
       const sourceNodePath = input.sourceNodePath;
+      const originalTextRange = input.originalTextRange;
       pending(index, "synthesizing");
       const startedAt = Date.now();
       try {
-        const result = await client.synthesizeSsml(input.ssml);
+        const result = await client.synthesizeSsml(input.ssml, {
+          outputFormat: options.outputFormat,
+          signal: options.signal,
+          timeoutMs: options.timeoutMs,
+          sourceNodePath: input.sourceNodePath ?? options.sourceNodePath,
+        });
         results.push({
           ...result,
           ...(input.originalTextRange ? { textRange: { ...input.originalTextRange } } : {}),
@@ -158,9 +214,64 @@ export async function synthesizeSsmlChunksSafe(
                 boundaries: result.boundaries?.map((event) => ({
                   ...event,
                   sourceNodePath: [...sourceNodePath],
+                  ...(event.originalTextRange
+                    ? { originalTextRange: { ...event.originalTextRange } }
+                    : input.originalTextRange
+                      ? { originalTextRange: { ...input.originalTextRange } }
+                      : {}),
+                })),
+                visemes: result.visemes?.map((event) => ({
+                  ...event,
+                  sourceNodePath: [...sourceNodePath],
+                  ...(event.originalTextRange
+                    ? { originalTextRange: { ...event.originalTextRange } }
+                    : input.originalTextRange
+                      ? { originalTextRange: { ...input.originalTextRange } }
+                      : {}),
+                })),
+                bookmarks: result.bookmarks?.map((event) => ({
+                  ...event,
+                  sourceNodePath: [...sourceNodePath],
+                  ...(event.originalTextRange
+                    ? { originalTextRange: { ...event.originalTextRange } }
+                    : input.originalTextRange
+                      ? { originalTextRange: { ...input.originalTextRange } }
+                      : {}),
+                })),
+              }
+            : {}),
+          ...(originalTextRange
+            ? {
+                boundaries: result.boundaries?.map((event) => ({
+                  ...event,
+                  originalTextRange: event.originalTextRange
+                    ? { ...event.originalTextRange }
+                    : { ...originalTextRange },
+                })),
+                wordBoundary: result.wordBoundary?.map((event) => ({
+                  ...event,
+                  originalTextRange: event.originalTextRange
+                    ? { ...event.originalTextRange }
+                    : { ...originalTextRange },
+                })),
+                wordBoundaries: result.wordBoundaries?.map((event) => ({
+                  ...event,
+                  originalTextRange: event.originalTextRange
+                    ? { ...event.originalTextRange }
+                    : { ...originalTextRange },
+                })),
+                visemes: result.visemes?.map((event) => ({
+                  ...event,
+                  originalTextRange: event.originalTextRange
+                    ? { ...event.originalTextRange }
+                    : { ...originalTextRange },
+                })),
+                bookmarks: result.bookmarks?.map((event) => ({
+                  ...event,
+                  originalTextRange: event.originalTextRange
+                    ? { ...event.originalTextRange }
+                    : { ...originalTextRange },
                 })),
-                visemes: result.visemes?.map((event) => ({ ...event, sourceNodePath: [...sourceNodePath] })),
-                bookmarks: result.bookmarks?.map((event) => ({ ...event, sourceNodePath: [...sourceNodePath] })),
               }
             : {}),
         });
@@ -191,10 +302,21 @@ export async function synthesizeSsmlChunksSafe(
       ok: true,
       success: true,
       status: "success",
-      value: mergeSynthesisResults(results, options.outputFormat),
+      value: mergeSynthesisResults(results, {
+        format: (options.outputFormat ?? "audio-16khz-128kbitrate-mono-mp3") as AzureTtsOutputFormat,
+      }),
     };
   } catch (error) {
-    const azureError = error instanceof AzureTtsError ? error : createSpeechSdkError(error);
-    return { ok: false, success: false, status: "azure-api-error", error: azureError };
+    const synthesisError = toSynthesisError(error);
+    return failure(synthesisError);
   }
 }
+
+function withValidationSignal(options: AzureValidationOptions, signal?: AbortSignal): AzureValidationOptions {
+  if (!signal) return options;
+  return {
+    ...options,
+    urlValidatorSignal: signal,
+    urlValidation: { ...(options.urlValidation ?? {}), signal },
+  };
+}