@bendyline/squisq-formats 2.0.0 → 2.0.1

package/src/__tests__/ooxmlCancellation.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest';
+import { inferThemeFromFile } from '../infer/index';
+import { getPartXml, openPackage } from '../ooxml/reader';
+import { inspectPptxLayouts } from '../pptx/layouts';
+import { prepareZipInput } from '../shared/zipEntryCount';
+import { buildThemedPptx } from './pptxInferFixtures';
+
+function blockingBlob(onRead: () => void): Blob {
+  const blob = {
+    size: 128,
+    slice: () => blob,
+    arrayBuffer: () => {
+      onRead();
+      return new Promise<ArrayBuffer>(() => undefined);
+    },
+  };
+  return blob as unknown as Blob;
+}
+
+describe('OOXML cancellation', () => {
+  it('preserves the exact reason while theme inference reads Blob input', async () => {
+    let markStarted: (() => void) | undefined;
+    const started = new Promise<void>((resolve) => {
+      markStarted = resolve;
+    });
+    const controller = new AbortController();
+    const reason = new Error('stop inference');
+    const pending = inferThemeFromFile(
+      blockingBlob(() => markStarted?.()),
+      {
+        signal: controller.signal,
+      },
+    );
+
+    await started;
+    controller.abort(reason);
+
+    await expect(pending).rejects.toBe(reason);
+  });
+
+  it('preserves the exact reason while layout inspection opens Blob input', async () => {
+    let markStarted: (() => void) | undefined;
+    const started = new Promise<void>((resolve) => {
+      markStarted = resolve;
+    });
+    const controller = new AbortController();
+    const reason = new Error('stop layout inspection');
+    const pending = inspectPptxLayouts(
+      blockingBlob(() => markStarted?.()),
+      {
+        signal: controller.signal,
+      },
+    );
+
+    await started;
+    controller.abort(reason);
+
+    await expect(pending).rejects.toBe(reason);
+  });
+
+  it('propagates package cancellation through later OOXML part traversal', async () => {
+    const controller = new AbortController();
+    const pkg = await openPackage(await buildThemedPptx(), { signal: controller.signal });
+    const reason = new Error('stop OOXML traversal');
+    controller.abort(reason);
+
+    await expect(getPartXml(pkg, 'ppt/presentation.xml')).rejects.toBe(reason);
+  });
+
+  it('handles a synchronously re-entrant FileReader abort exactly once', async () => {
+    const previous = globalThis.FileReader;
+    let abortCalls = 0;
+    class ReentrantFileReader {
+      result: ArrayBuffer | null = null;
+      error: DOMException | null = null;
+      onload: ((event: ProgressEvent<FileReader>) => void) | null = null;
+      onerror: ((event: ProgressEvent<FileReader>) => void) | null = null;
+      onabort: ((event: ProgressEvent<FileReader>) => void) | null = null;
+      readAsArrayBuffer(): void {
+        // Remain pending until the caller aborts.
+      }
+
+      abort(): void {
+        abortCalls += 1;
+        this.onabort?.({} as ProgressEvent<FileReader>);
+      }
+    }
+    Object.defineProperty(globalThis, 'FileReader', {
+      configurable: true,
+      writable: true,
+      value: ReentrantFileReader,
+    });
+
+    const blobLike = { size: 1, slice: () => blobLike } as unknown as Blob;
+    const controller = new AbortController();
+    const reason = new Error('stop FileReader');
+    try {
+      const pending = prepareZipInput(blobLike, controller.signal);
+      controller.abort(reason);
+      await expect(pending).rejects.toBe(reason);
+      expect(abortCalls).toBe(1);
+    } finally {
+      if (previous === undefined) Reflect.deleteProperty(globalThis, 'FileReader');
+      else {
+        Object.defineProperty(globalThis, 'FileReader', {
+          configurable: true,
+          writable: true,
+          value: previous,
+        });
+      }
+    }
+  });
+});

package/src/container/index.ts

@@ -24,6 +24,12 @@ import {
 } from '../shared/zipSafety.js';
 
 export type ZipToContainerOptions = ZipSafetyLimits;
+export interface ContainerToZipOptions {
+  /** STORE avoids producing archives that violate strict import compression-ratio policies. */
+  compression?: 'STORE' | 'DEFLATE';
+  /** JSZip DEFLATE level; ignored for STORE. */
+  compressionLevel?: number;
+}
 export { ZipSafetyError };
 export type { ZipSafetyLimits, ZipSafetyErrorCode, ZipSafetyErrorOptions };
 
@@ -36,7 +42,10 @@ export type { ZipSafetyLimits, ZipSafetyErrorCode, ZipSafetyErrorOptions };
  * @param container — The container to serialize
  * @returns A Blob containing the ZIP archive
  */
-export async function containerToZip(container: ContentContainer): Promise<Blob> {
+export async function containerToZip(
+  container: ContentContainer,
+  options: ContainerToZipOptions = {},
+): Promise<Blob> {
   const zip = new JSZip();
   const entries = await container.listFiles();
 
@@ -48,10 +57,15 @@ export async function containerToZip(container: ContentContainer): Promise<Blob>
     }
   }
 
+  const compression = options.compression ?? 'DEFLATE';
+  const compressionLevel = options.compressionLevel ?? 6;
+  if (!Number.isSafeInteger(compressionLevel) || compressionLevel < 1 || compressionLevel > 9) {
+    throw new Error('ZIP compression level must be an integer between 1 and 9');
+  }
   return zip.generateAsync({
     type: 'blob',
-    compression: 'DEFLATE',
-    compressionOptions: { level: 6 },
+    compression,
+    ...(compression === 'DEFLATE' ? { compressionOptions: { level: compressionLevel } } : {}),
   });
 }
 

package/src/index.ts

@@ -76,6 +76,7 @@ export type {
 // Format registry + programmatic convert()
 export {
   convert,
+  prepareConversion,
   createRegistry,
   defaultRegistry,
   defaultFormats,
@@ -103,4 +104,6 @@ export type {
   BuiltinFormatOptions,
   MarkdownFormatOptions,
   DbkFormatOptions,
+  PreparedConversion,
+  PreparedExportOptions,
 } from './registry/index.js';

package/src/infer/index.ts

@@ -16,7 +16,7 @@
  */
 
 import type { CustomTemplateDefinition, Theme } from '@bendyline/squisq/schemas';
-import { openPackage } from '../ooxml/reader.js';
+import { openPackage, throwIfOoxmlAborted } from '../ooxml/reader.js';
 import type { OoxmlOpenOptions } from '../ooxml/reader.js';
 import type { OoxmlPackage } from '../ooxml/types.js';
 import { ConversionError } from '../registry/errors.js';
@@ -53,7 +53,8 @@ export interface InferredFileTheme {
   warnings: string[];
 }
 
-async function looksLikePdf(data: ArrayBuffer | Blob): Promise<boolean> {
+async function looksLikePdf(data: ArrayBuffer | Blob, signal?: AbortSignal): Promise<boolean> {
+  throwIfOoxmlAborted(signal);
   // Duck-typed (not instanceof): buffers routinely cross realms in test
   // environments and web workers. Blobs carry `size`; ArrayBuffers carry
   // `byteLength`.
@@ -64,16 +65,39 @@ async function looksLikePdf(data: ArrayBuffer | Blob): Promise<boolean> {
     typeof blob.slice === 'function' &&
     typeof blob.arrayBuffer === 'function'
   ) {
-    head = new Uint8Array(await blob.slice(0, 5).arrayBuffer());
+    head = new Uint8Array(await waitForAbortable(blob.slice(0, 5).arrayBuffer(), signal));
   } else if (typeof (data as ArrayBuffer).byteLength === 'number') {
     const buf = data as ArrayBuffer;
     head = new Uint8Array(buf, 0, Math.min(5, buf.byteLength));
   }
+  throwIfOoxmlAborted(signal);
   if (!head || head.length < 4) return false;
   // '%PDF'
   return head[0] === 0x25 && head[1] === 0x50 && head[2] === 0x44 && head[3] === 0x46;
 }
 
+function waitForAbortable<T>(work: Promise<T>, signal?: AbortSignal): Promise<T> {
+  throwIfOoxmlAborted(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('OOXML operation was cancelled')));
+    signal.addEventListener('abort', handleAbort, { once: true });
+    if (signal.aborted) handleAbort();
+    work.then(
+      (value) => finish(() => resolve(value)),
+      (error: unknown) => finish(() => reject(error)),
+    );
+  });
+}
+
 /**
  * Classify an opened package from its already-parsed content types.
  * (Deliberately not the registry's byte sniffer — that re-parses the zip
@@ -110,7 +134,8 @@ export async function inferThemeFromFile(
   data: ArrayBuffer | Blob,
   options: InferThemeOptions = {},
 ): Promise<InferredFileTheme> {
-  if (await looksLikePdf(data)) {
+  throwIfOoxmlAborted(options.signal);
+  if (await looksLikePdf(data, options.signal)) {
     throw new ConversionError(
       'unsupported-input',
       'PDF theme inference is not supported — PDF files carry no theme color/font tables.',
@@ -122,6 +147,7 @@ export async function inferThemeFromFile(
   try {
     pkg = await openPackage(data, options);
   } catch (err: unknown) {
+    if (options.signal?.aborted) throw options.signal.reason ?? err;
     throw new ConversionError(
       'invalid-input',
       'Could not read this file as a Word, PowerPoint, or Excel document.',
@@ -130,6 +156,7 @@ export async function inferThemeFromFile(
   }
 
   const format = options.format ?? sniffOoxmlFormat(pkg);
+  throwIfOoxmlAborted(options.signal);
   if (!format) {
     throw new ConversionError(
       'invalid-input',
@@ -138,6 +165,7 @@ export async function inferThemeFromFile(
   }
 
   const extraction = await EXTRACTORS[format](pkg);
+  throwIfOoxmlAborted(options.signal);
   if (!extraction) {
     throw new ConversionError('invalid-input', 'No theme part found in this file.', { format });
   }
@@ -145,6 +173,7 @@ export async function inferThemeFromFile(
   const { theme, warnings: mapWarnings } = compileExtractedTheme(extraction, {
     nameHint: options.nameHint,
   });
+  throwIfOoxmlAborted(options.signal);
   const warnings = [...extraction.warnings, ...mapWarnings];
 
   let layouts: CustomTemplateDefinition[] | undefined;
@@ -155,6 +184,7 @@ export async function inferThemeFromFile(
       const { analyzePptxLayouts } = await import('../pptx/layouts.js');
       const analysis = await analyzePptxLayouts(pkg, {
         colors: colorHintsFromExtraction(extraction),
+        signal: options.signal,
       });
       warnings.push(...analysis.warnings);
       const defs = analysis.layouts
@@ -164,5 +194,6 @@ export async function inferThemeFromFile(
     }
   }
 
+  throwIfOoxmlAborted(options.signal);
   return { theme, extraction, ...(layouts ? { layouts } : {}), warnings };
 }

package/src/ooxml/reader.ts

@@ -5,8 +5,8 @@
  * structural metadata: [Content_Types].xml, relationships, and
  * core properties.
  *
- * Uses bounded JSZip member streams and a platform DOMParser (with an xmldom
- * fallback in bare Node/SSR) to parse XML.
+ * Uses bounded JSZip member streams and a platform DOMParser (with the
+ * package-owned xmldom parser in Node/SSR) to parse XML.
  */
 
 import { DOMParser as XmldomDOMParser } from '@xmldom/xmldom';
@@ -26,21 +26,44 @@ type DomParserLike = new () => {
 
 /** Safe read sessions for opaque packages opened by this module. */
 const packageArchives = new WeakMap<OoxmlPackage, BoundedZipArchive>();
+const packageSignals = new WeakMap<OoxmlPackage, AbortSignal>();
 const MAX_CONTENT_TYPES_BYTES = 1024 * 1024;
 const MAX_RELATIONSHIPS_BYTES = 4 * 1024 * 1024;
+const CANCELLATION_CHECKPOINT_INTERVAL = 256;
+
+/** Preserve the caller's exact cancellation reason across OOXML traversal. */
+export function throwIfOoxmlAborted(signal?: AbortSignal): void {
+  if (!signal?.aborted) return;
+  throw signal.reason ?? new Error('OOXML operation was cancelled');
+}
+
+async function cancellationCheckpoint(index: number, signal?: AbortSignal): Promise<void> {
+  throwIfOoxmlAborted(signal);
+  if (index > 0 && index % CANCELLATION_CHECKPOINT_INTERVAL === 0) {
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    throwIfOoxmlAborted(signal);
+  }
+}
 
 /**
- * Parse XML in browsers and bare Node. Browser DOMParser is preferred; the
- * pure-JS xmldom implementation is the package-owned fallback for Node/SSR.
+ * Parse XML in browsers and Node. Test runners and SSR hosts can install a
+ * partial browser DOMParser whose namespace behavior differs from browsers,
+ * so Node always uses the package-owned, namespace-aware xmldom parser.
  */
-function parseXml(source: string): Document {
-  const nativeParser = (globalThis as { DOMParser?: DomParserLike }).DOMParser;
+function parseXml(source: string, signal?: AbortSignal): Document {
+  throwIfOoxmlAborted(signal);
+  const runtime = globalThis as {
+    DOMParser?: DomParserLike;
+    process?: { versions?: { node?: string } };
+  };
+  const nativeParser = runtime.process?.versions?.node ? undefined : runtime.DOMParser;
   const Parser = nativeParser ?? (XmldomDOMParser as unknown as DomParserLike);
   const doc = new Parser().parseFromString(source, 'application/xml') as Document;
   const parserErrors = doc.getElementsByTagName('parsererror');
   if (parserErrors.length > 0) {
     throw new Error(`Invalid OOXML XML part: ${parserErrors[0]?.textContent ?? 'parse error'}`);
   }
+  throwIfOoxmlAborted(signal);
   return doc;
 }
 
@@ -61,15 +84,18 @@ export async function openPackage(
   data: ArrayBuffer | Blob,
   limits: OoxmlOpenOptions = {},
 ): Promise<OoxmlPackage> {
+  throwIfOoxmlAborted(limits.signal);
   const archive = await openBoundedZipArchive(data, limits);
-  const contentTypes = await parseContentTypes(archive);
-  const rootRelationships = await parseRelationships(archive, '');
+  const contentTypes = await parseContentTypes(archive, limits.signal);
+  const rootRelationships = await parseRelationships(archive, '', limits.signal);
+  throwIfOoxmlAborted(limits.signal);
 
   const pkg = {
     contentTypes,
     rootRelationships,
   } as unknown as OoxmlPackage;
   packageArchives.set(pkg, archive);
+  if (limits.signal) packageSignals.set(pkg, limits.signal);
   return pkg;
 }
 
@@ -80,17 +106,21 @@ export async function openPackage(
 /**
  * Parse [Content_Types].xml from the archive.
  */
-async function parseContentTypes(archive: BoundedZipArchive): Promise<ContentTypeMap> {
+async function parseContentTypes(
+  archive: BoundedZipArchive,
+  signal?: AbortSignal,
+): Promise<ContentTypeMap> {
   const overrides = new Map<string, string>();
   const defaults = new Map<string, string>();
 
   const text = await archive.readText('[Content_Types].xml', MAX_CONTENT_TYPES_BYTES);
   if (text === null) return { overrides, defaults };
-  const doc = parseXml(text);
+  const doc = parseXml(text, signal);
 
   // Parse <Default Extension="rels" ContentType="..." />
   const defaultEls = doc.getElementsByTagName('Default');
   for (let i = 0; i < defaultEls.length; i++) {
+    await cancellationCheckpoint(i, signal);
     const el = defaultEls[i];
     const ext = el.getAttribute('Extension');
     const ct = el.getAttribute('ContentType');
@@ -100,6 +130,7 @@ async function parseContentTypes(archive: BoundedZipArchive): Promise<ContentTyp
   // Parse <Override PartName="/word/document.xml" ContentType="..." />
   const overrideEls = doc.getElementsByTagName('Override');
   for (let i = 0; i < overrideEls.length; i++) {
+    await cancellationCheckpoint(i, signal);
     const el = overrideEls[i];
     const partName = el.getAttribute('PartName');
     const ct = el.getAttribute('ContentType');
@@ -128,7 +159,7 @@ export async function getPartRelationships(
   pkg: OoxmlPackage,
   partPath: string,
 ): Promise<Relationship[]> {
-  return parseRelationships(pkg, partPath);
+  return parseRelationships(pkg, partPath, packageSignals.get(pkg));
 }
 
 /**
@@ -140,13 +171,14 @@ export async function getPartRelationships(
 async function parseRelationships(
   source: OoxmlPackage | BoundedZipArchive,
   partPath: string,
+  signal?: AbortSignal,
 ): Promise<Relationship[]> {
   const relsPath = partPath === '' ? '_rels/.rels' : buildRelsPath(partPath);
 
   const bytes = await readArchivePart(source, relsPath, MAX_RELATIONSHIPS_BYTES);
   if (!bytes) return [];
   const text = new TextDecoder().decode(bytes);
-  const doc = parseXml(text);
+  const doc = parseXml(text, signal);
   const result: Relationship[] = [];
 
   const els = doc.getElementsByTagNameNS(NS_RELATIONSHIPS, 'Relationship');
@@ -154,6 +186,7 @@ async function parseRelationships(
   const fallbackEls = els.length > 0 ? els : doc.getElementsByTagName('Relationship');
 
   for (let i = 0; i < fallbackEls.length; i++) {
+    await cancellationCheckpoint(i, signal);
     const el = fallbackEls[i];
     const id = el.getAttribute('Id');
     const type = el.getAttribute('Type');
@@ -200,8 +233,10 @@ function buildRelsPath(partPath: string): string {
  * @returns Parsed XML Document, or null if the part doesn't exist
  */
 export async function getPartXml(pkg: OoxmlPackage, partPath: string): Promise<Document | null> {
+  const signal = packageSignals.get(pkg);
+  throwIfOoxmlAborted(signal);
   const bytes = await readPackagePart(pkg, partPath);
-  return bytes ? parseXml(new TextDecoder().decode(bytes)) : null;
+  return bytes ? parseXml(new TextDecoder().decode(bytes), signal) : null;
 }
 
 /**
@@ -215,6 +250,7 @@ export async function getPartBinary(
   pkg: OoxmlPackage,
   partPath: string,
 ): Promise<ArrayBuffer | null> {
+  throwIfOoxmlAborted(packageSignals.get(pkg));
   const bytes = await readPackagePart(pkg, partPath);
   return bytes ? bytes.slice().buffer : null;
 }
@@ -234,6 +270,7 @@ async function readPackagePart(
   path: string,
   maxBytes?: number,
 ): Promise<Uint8Array | null> {
+  throwIfOoxmlAborted(packageSignals.get(pkg));
   const archive = packageArchives.get(pkg);
   if (!archive) {
     throw new TypeError('Invalid OoxmlPackage: create packages with openPackage().');
@@ -252,6 +289,8 @@ async function readPackagePart(
  * @returns Parsed core properties (all fields optional)
  */
 export async function getCoreProperties(pkg: OoxmlPackage): Promise<CoreProperties> {
+  const signal = packageSignals.get(pkg);
+  throwIfOoxmlAborted(signal);
   const doc = await getPartXml(pkg, 'docProps/core.xml');
   if (!doc) return {};
 
@@ -263,7 +302,7 @@ export async function getCoreProperties(pkg: OoxmlPackage): Promise<CoreProperti
     return undefined;
   }
 
-  return {
+  const properties = {
     title: getText(NS_DC, 'title'),
     subject: getText(NS_DC, 'subject'),
     creator: getText(NS_DC, 'creator'),
@@ -274,4 +313,6 @@ export async function getCoreProperties(pkg: OoxmlPackage): Promise<CoreProperti
     created: getText(NS_DCTERMS, 'created'),
     modified: getText(NS_DCTERMS, 'modified'),
   };
+  throwIfOoxmlAborted(signal);
+  return properties;
 }