@bendyline/squisq-formats 2.0.0 → 2.1.0

package/src/registry/convert.ts

@@ -22,12 +22,22 @@ import type {
   FormatId,
   FormatRegistry,
   NormalizedInput,
+  PreparedConversion,
+  PreparedExportOptions,
 } from './types.js';
 
 function markdownFormatOptions(options: ConvertOptions): BuiltinFormatOptions['md'] {
   return (options.formatOptions?.md ?? {}) as BuiltinFormatOptions['md'];
 }
 
+function throwIfAborted(signal?: AbortSignal): void {
+  if (!signal?.aborted) return;
+  if (signal.reason !== undefined) throw signal.reason;
+  const error = new Error('Document conversion was cancelled.');
+  error.name = 'AbortError';
+  throw error;
+}
+
 // ── Byte sniffing ───────────────────────────────────────────────────
 
 function hasPrefix(bytes: Uint8Array, prefix: number[]): boolean {
@@ -274,39 +284,30 @@ async function applyTransformStyle(
   return [];
 }
 
-// ── convert() ───────────────────────────────────────────────────────
+// ── prepare / convert ───────────────────────────────────────────────
 
-/**
- * Convert a source document to a target format.
- *
- * @param source - A bytes / markdown / doc source.
- * @param to - The target format id (must be registered and support export).
- * @param options - Conversion options (registry, theme, transform, …).
- * @throws {@link ConversionError} on any failure, with a stable `code`.
- */
-export async function convert(
+/** Normalize and transform a source once, then safely export that snapshot many times. */
+export async function prepareConversion(
   source: ConvertSource,
-  to: FormatId,
   options: ConvertOptions = {},
-): Promise<ConversionResult> {
-  const registry = options.registry ?? defaultRegistry();
+): Promise<PreparedConversion> {
+  return prepareConversionInternal(source, options);
+}
 
-  const target: FormatDefinition | undefined = registry.get(to);
-  if (!target) {
-    throw new ConversionError('unknown-format', `Unknown target format "${to}".`, { format: to });
-  }
-  if (!target.exportDoc) {
-    throw new ConversionError(
-      'unsupported-output',
-      `Format "${target.label}" does not support export.`,
-      { format: to, hint: 'This format is import-only.' },
-    );
-  }
+async function prepareConversionInternal(
+  source: ConvertSource,
+  options: ConvertOptions,
+  failureFormat?: FormatId,
+): Promise<PreparedConversion> {
+  throwIfAborted(options.signal);
+  const registry = options.registry ?? defaultRegistry();
 
   let normalized: Normalized;
   try {
     normalized = await normalize(source, options, registry);
+    throwIfAborted(options.signal);
   } catch (err: unknown) {
+    throwIfAborted(options.signal);
     if (err instanceof ConversionError) throw err;
     const message = err instanceof Error ? err.message : String(err);
     throw new ConversionError('invalid-input', message, {
@@ -321,7 +322,6 @@ export async function convert(
     input.doc = { ...input.doc, themeId: options.themeId };
   }
 
-  let result: ConversionResult;
   try {
     if (options.transformStyle) {
       warnings.push(
@@ -332,18 +332,102 @@ export async function convert(
           options.transformRegistry,
         )),
       );
+      throwIfAborted(options.signal);
     }
-    result = await target.exportDoc(input, options);
   } catch (err: unknown) {
+    throwIfAborted(options.signal);
     if (err instanceof ConversionError) throw err;
     const message = err instanceof Error ? err.message : String(err);
-    throw new ConversionError('conversion-failed', message, { format: to, cause: err });
+    throw new ConversionError('conversion-failed', message, {
+      format: failureFormat,
+      cause: err,
+    });
   }
 
-  const ext = target.extensions[0]?.replace(/^\.+/, '') ?? to;
+  const preparedWarnings = Object.freeze([...warnings]);
+  const preparedInput = { ...input };
+  return Object.freeze({
+    async convert(to: FormatId, targetOptions: PreparedExportOptions = {}) {
+      const target = requireExportTarget(registry, to);
+      const exportOptions = mergePreparedExportOptions(options, targetOptions);
+      throwIfAborted(exportOptions.signal);
+      let result: ConversionResult;
+      try {
+        result = await target.exportDoc!({ ...preparedInput }, exportOptions);
+        throwIfAborted(exportOptions.signal);
+      } catch (err: unknown) {
+        throwIfAborted(exportOptions.signal);
+        if (err instanceof ConversionError) throw err;
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ConversionError('conversion-failed', message, { format: to, cause: err });
+      }
+
+      const ext = target.extensions[0]?.replace(/^\.+/, '') ?? to;
+      return {
+        ...result,
+        suggestedFilename: `${preparedInput.baseName}.${ext}`,
+        warnings: [...preparedWarnings, ...result.warnings],
+      };
+    },
+  });
+}
+
+function requireExportTarget(registry: FormatRegistry, to: FormatId): FormatDefinition {
+  const target = registry.get(to);
+  if (!target) {
+    throw new ConversionError('unknown-format', `Unknown target format "${to}".`, { format: to });
+  }
+  if (!target.exportDoc) {
+    throw new ConversionError(
+      'unsupported-output',
+      `Format "${target.label}" does not support export.`,
+      { format: to, hint: 'This format is import-only.' },
+    );
+  }
+  return target;
+}
+
+function mergePreparedExportOptions(
+  prepared: ConvertOptions,
+  target: PreparedExportOptions,
+): ConvertOptions {
   return {
-    ...result,
-    suggestedFilename: `${input.baseName}.${ext}`,
-    warnings: [...warnings, ...result.warnings],
+    ...prepared,
+    signal: mergeAbortSignals(prepared.signal, target.signal),
+    title: target.title ?? prepared.title,
+    resolvePlayerScript: target.resolvePlayerScript ?? prepared.resolvePlayerScript,
+    formatOptions:
+      target.formatOptions === undefined
+        ? prepared.formatOptions
+        : { ...(prepared.formatOptions ?? {}), ...target.formatOptions },
   };
 }
+
+function mergeAbortSignals(
+  preparedSignal?: AbortSignal,
+  targetSignal?: AbortSignal,
+): AbortSignal | undefined {
+  if (!preparedSignal) return targetSignal;
+  if (!targetSignal || preparedSignal === targetSignal) return preparedSignal;
+  return AbortSignal.any([preparedSignal, targetSignal]);
+}
+
+/**
+ * Convert a source document to a target format.
+ *
+ * @param source - A bytes / markdown / doc source.
+ * @param to - The target format id (must be registered and support export).
+ * @param options - Conversion options (registry, theme, transform, …).
+ * @throws {@link ConversionError} on any failure, with a stable `code`.
+ */
+export async function convert(
+  source: ConvertSource,
+  to: FormatId,
+  options: ConvertOptions = {},
+): Promise<ConversionResult> {
+  throwIfAborted(options.signal);
+  const registry = options.registry ?? defaultRegistry();
+  requireExportTarget(registry, to);
+  const prepared = await prepareConversionInternal(source, { ...options, registry }, to);
+  return prepared.convert(to);
+}

package/src/registry/defaultFormats.ts

@@ -399,9 +399,12 @@ export function defaultFormats(): FormatDefinition[] {
       const { zipToContainer } = await import('../container/index.js');
       return zipToContainer(data, optionsFor(options, 'dbk'));
     },
-    async exportDoc(input): Promise<ConversionResult> {
+    async exportDoc(input, options): Promise<ConversionResult> {
       const { containerToZip } = await import('../container/index.js');
-      const blob = await containerToZip(await snapshotContainerWithDocument(input));
+      const blob = await containerToZip(
+        await snapshotContainerWithDocument(input),
+        optionsFor(options, 'dbk'),
+      );
       return ok(await toBytes(blob), MIME.zip);
     },
   };

package/src/registry/index.ts

@@ -30,6 +30,8 @@ export type {
   BuiltinFormatOptions,
   MarkdownFormatOptions,
   DbkFormatOptions,
+  PreparedConversion,
+  PreparedExportOptions,
 } from './types.js';
 export { BUILTIN_FORMAT_IDS } from './types.js';
 
@@ -38,4 +40,4 @@ export type { ConversionErrorCode, ConversionErrorOptions } from './errors.js';
 
 export { createRegistry, defaultRegistry } from './registry.js';
 export { defaultFormats } from './defaultFormats.js';
-export { convert } from './convert.js';
+export { convert, prepareConversion } from './convert.js';

package/src/registry/types.ts

@@ -25,6 +25,7 @@ import type { PdfImportOptions } from '../pdf/import.js';
 import type { HtmlExportOptions } from '../html/htmlTemplate.js';
 import type { HtmlImportOptions } from '../html/import.js';
 import type { EpubExportOptions } from '../epub/export.js';
+import type { ContainerToZipOptions } from '../container/index.js';
 import type { ZipSafetyLimits } from '../shared/zipSafety.js';
 
 /** A format identifier (e.g. `'docx'`). Strings so hosts can register their own. */
@@ -62,7 +63,7 @@ export interface MarkdownFormatOptions {
 }
 
 /** Resource limits applied when importing a DBK/ZIP container. */
-export type DbkFormatOptions = ZipSafetyLimits;
+export type DbkFormatOptions = ZipSafetyLimits & ContainerToZipOptions;
 
 /**
  * Strongly typed option bags for built-in formats. Import and export options
@@ -97,6 +98,8 @@ export interface NormalizedInput {
 
 /** Options threaded through `convert()` and into every format method. */
 export interface ConvertOptions {
+  /** Cancel normalization, transformation, or export at the next bounded work boundary. */
+  signal?: AbortSignal;
   /** Registry to resolve formats against. Defaults to `defaultRegistry()`. */
   registry?: FormatRegistry;
   /** Explicit source format id (skips extension/byte sniffing). */
@@ -119,6 +122,20 @@ export interface ConvertOptions {
   formatOptions?: Partial<BuiltinFormatOptions> & Record<FormatId, unknown>;
 }
 
+/** Target-only options accepted after a source has already been normalized and transformed. */
+export type PreparedExportOptions = Pick<
+  ConvertOptions,
+  'signal' | 'title' | 'resolvePlayerScript' | 'formatOptions'
+>;
+
+/**
+ * An opaque normalized conversion snapshot. The source and transform pipeline
+ * has already completed; each call exports that same snapshot to one target.
+ */
+export interface PreparedConversion {
+  convert(to: FormatId, options?: PreparedExportOptions): Promise<ConversionResult>;
+}
+
 /** Describes how a single format imports to / exports from the squisq model. */
 export interface FormatDefinition {
   id: FormatId;

package/src/shared/boundedZipArchive.ts

@@ -8,6 +8,7 @@ import {
   compressionRatioError,
   entryTooLargeError,
   resolveZipSafetyLimits,
+  throwIfZipAborted,
   validateZipArchive,
   tooManyEntriesError,
   ZipSafetyError,
@@ -19,7 +20,7 @@ import {
 import { declaredZipEntryCount, prepareZipInput, type ZipInput } from './zipEntryCount.js';
 
 interface ActiveZipRead {
-  stop(error: ZipSafetyError): void;
+  stop(error: unknown): void;
 }
 
 interface ZipChunkStream {
@@ -58,15 +59,22 @@ class JsZipBoundedArchive implements BoundedZipArchive {
 
   private readonly limits: ResolvedZipSafetyLimits;
   private readonly entriesByPath: ReadonlyMap<string, ValidatedZipEntry>;
+  private readonly signal?: AbortSignal;
   private readonly reads = new Map<string, Promise<Uint8Array>>();
   private readonly activeReads = new Set<ActiveZipRead>();
   private terminalError?: ZipSafetyError;
   private emittedBytes = 0;
 
-  constructor(zip: JSZip, entries: readonly ValidatedZipEntry[], limits: ResolvedZipSafetyLimits) {
+  constructor(
+    zip: JSZip,
+    entries: readonly ValidatedZipEntry[],
+    limits: ResolvedZipSafetyLimits,
+    signal?: AbortSignal,
+  ) {
     this.zip = zip;
     this.entries = entries;
     this.limits = limits;
+    this.signal = signal;
     this.entriesByPath = new Map(entries.map((entry) => [entry.path, entry]));
   }
 
@@ -77,6 +85,7 @@ class JsZipBoundedArchive implements BoundedZipArchive {
 
   /** Read and cache one member, returning null when it does not exist. */
   async read(path: string, maxBytes?: number): Promise<Uint8Array | null> {
+    throwIfZipAborted(this.signal);
     this.throwIfFailed();
     if (maxBytes !== undefined) assertNonNegativeFinite('member read limit', maxBytes);
     const entry = this.entriesByPath.get(path);
@@ -87,7 +96,16 @@ class JsZipBoundedArchive implements BoundedZipArchive {
       pending = this.streamEntry(entry, maxBytes);
       this.reads.set(path, pending);
     }
-    const bytes = await pending;
+    let bytes: Uint8Array;
+    try {
+      bytes = await pending;
+    } catch (error: unknown) {
+      // Cancellation is scoped to the current operation, not archive
+      // corruption. Do not leave a cancelled read cached for a later caller.
+      if (this.reads.get(path) === pending && !this.terminalError) this.reads.delete(path);
+      throw error;
+    }
+    throwIfZipAborted(this.signal);
     if (maxBytes !== undefined && bytes.byteLength > maxBytes) {
       const error = entryTooLargeError(path, bytes.byteLength, maxBytes);
       this.failArchive(error);
@@ -108,6 +126,7 @@ class JsZipBoundedArchive implements BoundedZipArchive {
   }
 
   private streamEntry(metadata: ValidatedZipEntry, readLimit?: number): Promise<Uint8Array> {
+    throwIfZipAborted(this.signal);
     const { path, entry, declaredSize, crc32: expectedCrc } = metadata;
     const effectiveEntryLimit = Math.min(
       this.limits.maxEntryUncompressedBytes,
@@ -129,12 +148,17 @@ class JsZipBoundedArchive implements BoundedZipArchive {
       let settled = false;
       let written = 0;
       let crc = 0xffffffff;
+      const removeAbortListener = (): void =>
+        this.signal?.removeEventListener('abort', handleAbort);
+      const handleAbort = (): void =>
+        controller.stop(this.signal?.reason ?? new Error('ZIP operation was cancelled'));
 
       const controller: ActiveZipRead = {
         stop: (error) => {
           if (settled) return;
           settled = true;
           this.activeReads.delete(controller);
+          removeAbortListener();
           // Public JSZip cancellation is cooperative. It prevents another
           // compressed-input tick; data already emitted synchronously by the
           // current tick is ignored because `settled` is now true.
@@ -148,19 +172,28 @@ class JsZipBoundedArchive implements BoundedZipArchive {
         },
       };
       this.activeReads.add(controller);
+      if (this.signal) {
+        this.signal.addEventListener('abort', handleAbort, { once: true });
+        if (this.signal.aborted) {
+          handleAbort();
+          return;
+        }
+      }
 
       stream
         .on('data', (chunk: Uint8Array) => {
           if (settled) return;
           const nextWritten = written + chunk.byteLength;
           try {
+            throwIfZipAborted(this.signal);
             this.assertChunkAllowed(metadata, nextWritten, chunk.byteLength, effectiveEntryLimit);
             output = growOutput(output, nextWritten, declaredSize, effectiveEntryLimit);
             output.set(chunk, written);
             written = nextWritten;
             crc = updateCrc32(crc, chunk);
           } catch (error: unknown) {
-            this.failArchive(asZipSafetyError(error, path));
+            if (this.signal?.aborted) controller.stop(error);
+            else this.failArchive(asZipSafetyError(error, path));
           }
         })
         .on('error', (error: unknown) => {
@@ -200,6 +233,7 @@ class JsZipBoundedArchive implements BoundedZipArchive {
 
           settled = true;
           this.activeReads.delete(controller);
+          removeAbortListener();
           resolve(output.byteLength === written ? output : output.slice(0, written));
         })
         .resume();
@@ -260,13 +294,16 @@ export async function openBoundedZipArchive(
   data: ZipInput,
   limits: ZipSafetyLimits = {},
 ): Promise<BoundedZipArchive> {
+  throwIfZipAborted(limits.signal);
   const resolved = resolveZipSafetyLimits(limits);
   let prepared: { input: ZipInput; bytes?: Uint8Array };
   try {
-    prepared = await prepareZipInput(data);
+    prepared = await prepareZipInput(data, limits.signal);
   } catch (error: unknown) {
+    if (limits.signal?.aborted) throw limits.signal.reason ?? error;
     throw invalidArchiveError(error);
   }
+  throwIfZipAborted(limits.signal);
   if (prepared.bytes) {
     const declaredEntries = declaredZipEntryCount(prepared.bytes);
     if (declaredEntries !== undefined && declaredEntries > resolved.maxEntries) {
@@ -277,9 +314,11 @@ export async function openBoundedZipArchive(
   try {
     zip = await JSZip.loadAsync(prepared.input);
   } catch (error: unknown) {
+    if (limits.signal?.aborted) throw limits.signal.reason ?? error;
     throw invalidArchiveError(error);
   }
-  return createBoundedZipArchive(zip, resolved);
+  throwIfZipAborted(limits.signal);
+  return createBoundedZipArchive(zip, limits);
 }
 
 function invalidArchiveError(cause: unknown): ZipSafetyError {
@@ -291,9 +330,11 @@ export function createBoundedZipArchive(
   zip: JSZip,
   limits: ZipSafetyLimits = {},
 ): BoundedZipArchive {
+  throwIfZipAborted(limits.signal);
   const resolved = resolveZipSafetyLimits(limits);
-  const entries = validateZipArchive(zip, resolved);
-  return new JsZipBoundedArchive(zip, entries, resolved);
+  const entries = validateZipArchive(zip, limits);
+  throwIfZipAborted(limits.signal);
+  return new JsZipBoundedArchive(zip, entries, resolved, limits.signal);
 }
 
 function asZipSafetyError(error: unknown, path: string): ZipSafetyError {

package/src/shared/zipEntryCount.ts

@@ -1,5 +1,7 @@
 /** Narrow EOCD preflight for rejecting record-count bombs before JSZip allocation. */
 
+import { throwIfZipAborted } from './zipLimits.js';
+
 const END_OF_CENTRAL_DIRECTORY = 0x06054b50;
 const ZIP64_END_OF_CENTRAL_DIRECTORY = 0x06064b50;
 const ZIP64_END_LOCATOR = 0x07064b50;
@@ -12,7 +14,9 @@ export type ZipInput = ArrayBuffer | Uint8Array | Blob;
 /** Materialize Blob input once when possible so preflight bytes feed JSZip too. */
 export async function prepareZipInput(
   data: ZipInput,
+  signal?: AbortSignal,
 ): Promise<{ input: ZipInput; bytes?: Uint8Array }> {
+  throwIfZipAborted(signal);
   if (ArrayBuffer.isView(data)) {
     const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
     return { input: bytes, bytes };
@@ -22,7 +26,8 @@ export async function prepareZipInput(
     return { input: bytes, bytes };
   }
 
-  const bytes = await readBlobBytes(data);
+  const bytes = await readBlobBytes(data, signal);
+  throwIfZipAborted(signal);
   return bytes ? { input: bytes, bytes } : { input: data };
 }
 
@@ -82,16 +87,65 @@ function isBlobLike(data: ZipInput): data is Blob {
   return typeof candidate.size === 'number' && typeof candidate.slice === 'function';
 }
 
-async function readBlobBytes(blob: Blob): Promise<Uint8Array | undefined> {
+async function readBlobBytes(blob: Blob, signal?: AbortSignal): Promise<Uint8Array | undefined> {
   const arrayBuffer = (blob as Blob & { arrayBuffer?: () => Promise<ArrayBuffer> }).arrayBuffer;
   if (typeof arrayBuffer === 'function') {
-    return new Uint8Array(await arrayBuffer.call(blob));
+    return new Uint8Array(await raceWithAbort(arrayBuffer.call(blob), signal));
   }
   if (typeof FileReader === 'undefined') return undefined;
   return new Promise((resolve, reject) => {
     const reader = new FileReader();
-    reader.onload = () => resolve(new Uint8Array(reader.result as ArrayBuffer));
-    reader.onerror = () => reject(reader.error ?? new Error('Could not read ZIP blob.'));
+    let settled = false;
+    const cleanup = (): void => signal?.removeEventListener('abort', handleAbort);
+    const finish = (work: () => void): void => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      work();
+    };
+    const handleAbort = (): void => {
+      if (settled) return;
+      const reason = signal?.reason ?? new Error('ZIP operation was cancelled');
+      // Mark the promise settled before FileReader.abort(): browsers are
+      // allowed to dispatch `abort` synchronously and re-enter this handler.
+      finish(() => reject(reason));
+      try {
+        reader.abort();
+      } catch {
+        // Preserve the caller's reason if a platform reader is already done.
+      }
+    };
+    reader.onload = () => finish(() => resolve(new Uint8Array(reader.result as ArrayBuffer)));
+    reader.onerror = () =>
+      finish(() => reject(reader.error ?? new Error('Could not read ZIP blob.')));
+    reader.onabort = handleAbort;
+    signal?.addEventListener('abort', handleAbort, { once: true });
+    if (signal?.aborted) {
+      handleAbort();
+      return;
+    }
     reader.readAsArrayBuffer(blob);
   });
 }
+
+function raceWithAbort<T>(work: Promise<T>, signal?: AbortSignal): Promise<T> {
+  throwIfZipAborted(signal);
+  if (!signal) return work;
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const finish = (complete: () => void): void => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener('abort', handleAbort);
+      complete();
+    };
+    const handleAbort = (): void =>
+      finish(() => reject(signal.reason ?? new Error('ZIP operation was cancelled')));
+    signal.addEventListener('abort', handleAbort, { once: true });
+    if (signal.aborted) handleAbort();
+    work.then(
+      (value) => finish(() => resolve(value)),
+      (error: unknown) => finish(() => reject(error)),
+    );
+  });
+}

package/src/shared/zipLimits.ts

@@ -3,6 +3,8 @@
 import type JSZip from 'jszip';
 
 export interface ZipSafetyLimits {
+  /** Cooperatively cancel archive opening, validation, and member traversal. */
+  signal?: AbortSignal;
   /** Maximum number of archive records, including directories. Default: 10,000. */
   maxEntries?: number;
   /** Maximum uncompressed bytes for one member. Defaults to maxUncompressedBytes. */
@@ -77,6 +79,7 @@ export const DEFAULT_MAX_ZIP_COMPRESSION_RATIO = 1_000;
  * JSZip normalizes traversal names, so inspect `unsafeOriginalName` too.
  */
 export function validateZipArchive(zip: JSZip, limits: ZipSafetyLimits = {}): ValidatedZipEntry[] {
+  throwIfZipAborted(limits.signal);
   const resolved = resolveZipSafetyLimits(limits);
   const files: ValidatedZipEntry[] = [];
   let memberCount = 0;
@@ -84,6 +87,7 @@ export function validateZipArchive(zip: JSZip, limits: ZipSafetyLimits = {}): Va
   let oversizedEntry: { path: string; actual: number; limit: number } | undefined;
 
   zip.forEach((relativePath, entry) => {
+    throwIfZipAborted(limits.signal);
     memberCount++;
     if (entry.dir) return;
     const originalPath = originalEntryPath(entry, relativePath);
@@ -140,6 +144,12 @@ export function validateZipArchive(zip: JSZip, limits: ZipSafetyLimits = {}): Va
   return files;
 }
 
+/** Preserve the caller's exact cancellation reason across ZIP/OOXML layers. */
+export function throwIfZipAborted(signal?: AbortSignal): void {
+  if (!signal?.aborted) return;
+  throw signal.reason ?? new Error('ZIP operation was cancelled');
+}
+
 /** Reject a path that could be interpreted outside an archive's logical root. */
 export function assertSafeZipPath(path: string): void {
   if (!isSafeArchivePath(path)) {