@bendyline/squisq-formats 2.1.0 → 2.2.0

package/src/registry/types.ts

@@ -1,170 +0,0 @@
-/**
- * Format registry — shared types.
- *
- * The registry is the programmatic heart of `convert()`: it maps a small set of
- * format ids (`md`, `docx`, `pdf`, …) to `FormatDefinition`s, each of which
- * knows how to import to / export from squisq's markdown + Doc model. Every
- * converter module is loaded lazily via `import()` inside the definition
- * methods, so pulling in the registry never eagerly bundles heavy converters.
- */
-
-import type { Doc, ThemeRegistry } from '@bendyline/squisq/schemas';
-import type { TransformStyleInput, TransformStyleRegistry } from '@bendyline/squisq/transform';
-import type { MarkdownDocument } from '@bendyline/squisq/markdown';
-import type { ContentContainer } from '@bendyline/squisq/storage';
-import type { ParseOptions, StringifyOptions } from '@bendyline/squisq/markdown';
-import type { DocxExportOptions } from '../docx/export.js';
-import type { DocxImportOptions } from '../docx/import.js';
-import type { PptxExportOptions } from '../pptx/export.js';
-import type { PptxImportOptions } from '../pptx/import.js';
-import type { XlsxExportOptions } from '../xlsx/export.js';
-import type { XlsxImportOptions } from '../xlsx/import.js';
-import type { CsvExportOptions, CsvImportOptions } from '../csv/index.js';
-import type { PdfExportOptions } from '../pdf/export.js';
-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. */
-export type FormatId = string;
-
-/** The built-in formats the default registry ships with. */
-export const BUILTIN_FORMAT_IDS = [
-  'md',
-  'docx',
-  'pdf',
-  'pptx',
-  'xlsx',
-  'csv',
-  'html',
-  'htmlzip',
-  'epub',
-  'dbk',
-] as const;
-
-/** The bytes + metadata produced by a successful export. */
-export interface ConversionResult {
-  /** Encoded output bytes. */
-  bytes: Uint8Array;
-  /** MIME type of the output. */
-  mimeType: string;
-  /** A sensible download filename (`<baseName>.<ext>`). */
-  suggestedFilename: string;
-  /** Non-fatal notes accumulated during conversion (may be empty). */
-  warnings: string[];
-}
-
-export interface MarkdownFormatOptions {
-  parse?: ParseOptions;
-  stringify?: StringifyOptions;
-}
-
-/** Resource limits applied when importing a DBK/ZIP container. */
-export type DbkFormatOptions = ZipSafetyLimits & ContainerToZipOptions;
-
-/**
- * Strongly typed option bags for built-in formats. Import and export options
- * share a bag because a single conversion may use the format on either side.
- * Custom registries may add arbitrary keys through the intersection used by
- * {@link ConvertOptions.formatOptions}.
- */
-export interface BuiltinFormatOptions {
-  md: MarkdownFormatOptions;
-  docx: DocxImportOptions & DocxExportOptions;
-  pptx: PptxImportOptions & PptxExportOptions;
-  xlsx: XlsxImportOptions & XlsxExportOptions;
-  csv: CsvImportOptions & CsvExportOptions;
-  pdf: PdfImportOptions & PdfExportOptions;
-  html: HtmlImportOptions & Partial<Omit<HtmlExportOptions, 'playerScript'>>;
-  htmlzip: Partial<Omit<HtmlExportOptions, 'playerScript'>>;
-  epub: EpubExportOptions;
-  dbk: DbkFormatOptions;
-}
-
-/**
- * A source normalized into every shape an exporter might need. `doc` is always
- * present; `markdownDoc` is present when the source was markdown-shaped (an
- * exporter that wants markdown but finds none derives it from `doc`).
- */
-export interface NormalizedInput {
-  doc: Doc;
-  markdownDoc?: MarkdownDocument;
-  container: ContentContainer;
-  baseName: string;
-}
-
-/** 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). */
-  from?: FormatId;
-  /** Theme id to apply to the exported document. */
-  themeId?: string;
-  /** Explicit caller-owned registry for non-document custom themes. */
-  themeRegistry?: ThemeRegistry;
-  /** Built-in/registry id or call-scoped style to apply before export. */
-  transformStyle?: TransformStyleInput;
-  /** Explicit caller-owned registry used to resolve transform style ids. */
-  transformRegistry?: TransformStyleRegistry;
-  /** Content-aware auto-templating when deriving a Doc from markdown. */
-  autoTemplates?: boolean;
-  /** Title hint for exporters that expose document metadata. */
-  title?: string;
-  /** Lazily resolve the standalone player IIFE bundle (required for HTML export). */
-  resolvePlayerScript?: () => Promise<string>;
-  /** Typed per-format options for built-ins; custom format ids remain extensible. */
-  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;
-  label: string;
-  mimeType: string;
-  extensions: readonly string[];
-  /** Import raw bytes to a MarkdownDocument. */
-  importDoc?(data: ArrayBuffer, options: ConvertOptions): Promise<MarkdownDocument>;
-  /** Import raw bytes to a ContentContainer (markdown + extracted media). */
-  importContainer?(data: ArrayBuffer, options: ConvertOptions): Promise<ContentContainer>;
-  /** Export a normalized input to bytes. */
-  exportDoc?(input: NormalizedInput, options: ConvertOptions): Promise<ConversionResult>;
-}
-
-/** A mutable collection of format definitions keyed by id. */
-export interface FormatRegistry {
-  register(def: FormatDefinition): void;
-  get(id: FormatId): FormatDefinition | undefined;
-  byExtension(ext: string): FormatDefinition | undefined;
-  list(): FormatDefinition[];
-}
-
-/** The three shapes `convert()` accepts as a source. */
-export type ConvertSource =
-  | { kind: 'bytes'; data: ArrayBuffer | Uint8Array; filename?: string }
-  | {
-      kind: 'markdown';
-      markdown: string | MarkdownDocument;
-      container?: ContentContainer;
-      baseName?: string;
-    }
-  | { kind: 'doc'; doc: Doc; container?: ContentContainer; baseName?: string };

package/src/shared/boundedZipArchive.ts

@@ -1,383 +0,0 @@
-/** Incremental JSZip member reads governed by one shared archive budget. */
-
-import JSZip from 'jszip';
-import {
-  archiveTooLargeError,
-  assertNonNegativeFinite,
-  compressionRatio,
-  compressionRatioError,
-  entryTooLargeError,
-  resolveZipSafetyLimits,
-  throwIfZipAborted,
-  validateZipArchive,
-  tooManyEntriesError,
-  ZipSafetyError,
-  type ResolvedZipSafetyLimits,
-  type ValidatedZipEntry,
-  type ZipSafetyErrorCode,
-  type ZipSafetyLimits,
-} from './zipLimits.js';
-import { declaredZipEntryCount, prepareZipInput, type ZipInput } from './zipEntryCount.js';
-
-interface ActiveZipRead {
-  stop(error: unknown): void;
-}
-
-interface ZipChunkStream {
-  on(event: 'data', callback: (chunk: Uint8Array) => void): ZipChunkStream;
-  on(event: 'error', callback: (error: unknown) => void): ZipChunkStream;
-  on(event: 'end', callback: () => void): ZipChunkStream;
-  pause(): ZipChunkStream;
-  resume(): ZipChunkStream;
-}
-
-interface StreamableZipObject {
-  internalStream(type: 'uint8array'): ZipChunkStream;
-}
-
-/**
- * A JSZip archive whose member reads share one actual-byte budget.
- *
- * JSZip's promise API accumulates a complete inflated member before returning.
- * This wrapper instead consumes `internalStream('uint8array')`, checks every
- * emitted chunk, and pauses every active stream as soon as any limit fails.
- * Completed reads are cached so repeated OOXML part access is neither inflated
- * nor charged twice.
- */
-export interface BoundedZipArchive {
-  readonly zip: JSZip;
-  readonly entries: readonly ValidatedZipEntry[];
-  readonly emittedUncompressedBytes: number;
-  read(path: string, maxBytes?: number): Promise<Uint8Array | null>;
-  readText(path: string, maxBytes?: number): Promise<string | null>;
-  release(path: string): void;
-}
-
-class JsZipBoundedArchive implements BoundedZipArchive {
-  readonly zip: JSZip;
-  readonly entries: readonly ValidatedZipEntry[];
-
-  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,
-    signal?: AbortSignal,
-  ) {
-    this.zip = zip;
-    this.entries = entries;
-    this.limits = limits;
-    this.signal = signal;
-    this.entriesByPath = new Map(entries.map((entry) => [entry.path, entry]));
-  }
-
-  /** Actual uncompressed bytes accepted from JSZip streams so far. */
-  get emittedUncompressedBytes(): number {
-    return this.emittedBytes;
-  }
-
-  /** 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);
-    if (!entry) return null;
-
-    let pending = this.reads.get(path);
-    if (!pending) {
-      pending = this.streamEntry(entry, maxBytes);
-      this.reads.set(path, 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);
-      throw error;
-    }
-    return bytes;
-  }
-
-  /** Read one UTF-8 text member, returning null when it does not exist. */
-  async readText(path: string, maxBytes?: number): Promise<string | null> {
-    const bytes = await this.read(path, maxBytes);
-    return bytes ? new TextDecoder().decode(bytes) : null;
-  }
-
-  /** Release a cached member when a sequential consumer has taken ownership. */
-  release(path: string): void {
-    this.reads.delete(path);
-  }
-
-  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,
-      readLimit ?? Number.POSITIVE_INFINITY,
-    );
-    // Never trust a declaration enough to allocate it up front. A forged
-    // 511 MiB size must not force 511 MiB of memory for a tiny member.
-    let output: Uint8Array = new Uint8Array(0);
-    let stream: ZipChunkStream;
-    try {
-      stream = (entry as unknown as StreamableZipObject).internalStream('uint8array');
-    } catch (error: unknown) {
-      const safeError = asZipSafetyError(error, path);
-      this.failArchive(safeError);
-      return Promise.reject(safeError);
-    }
-
-    return new Promise<Uint8Array>((resolve, reject) => {
-      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.
-          try {
-            stream.pause();
-          } catch {
-            // Reject with the original safety failure even if a malformed
-            // third-party stream cannot be paused cleanly.
-          }
-          reject(error);
-        },
-      };
-      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) {
-            if (this.signal?.aborted) controller.stop(error);
-            else this.failArchive(asZipSafetyError(error, path));
-          }
-        })
-        .on('error', (error: unknown) => {
-          if (settled) return;
-          const message = error instanceof Error ? error.message : String(error);
-          const code: ZipSafetyErrorCode = message.includes('uncompressed data size mismatch')
-            ? 'size-mismatch'
-            : 'decompression-failed';
-          this.failArchive(
-            new ZipSafetyError(code, `ZIP import: could not decompress ${path}: ${message}`, {
-              path,
-              cause: error,
-            }),
-          );
-        })
-        .on('end', () => {
-          if (settled) return;
-          if (declaredSize !== undefined && written !== declaredSize) {
-            this.failArchive(
-              new ZipSafetyError(
-                'size-mismatch',
-                `ZIP import: archive member size does not match its metadata: ${path}.`,
-                { path, actual: written },
-              ),
-            );
-            return;
-          }
-          const actualCrc = (crc ^ 0xffffffff) >>> 0;
-          if (expectedCrc !== undefined && actualCrc !== expectedCrc >>> 0) {
-            this.failArchive(
-              new ZipSafetyError('crc-mismatch', `ZIP import: CRC32 mismatch for ${path}.`, {
-                path,
-              }),
-            );
-            return;
-          }
-
-          settled = true;
-          this.activeReads.delete(controller);
-          removeAbortListener();
-          resolve(output.byteLength === written ? output : output.slice(0, written));
-        })
-        .resume();
-    });
-  }
-
-  private assertChunkAllowed(
-    entry: ValidatedZipEntry,
-    nextEntryBytes: number,
-    chunkBytes: number,
-    effectiveEntryLimit: number,
-  ): void {
-    if (entry.declaredSize !== undefined && nextEntryBytes > entry.declaredSize) {
-      throw new ZipSafetyError(
-        'size-mismatch',
-        `ZIP import: archive member size does not match its metadata: ${entry.path}.`,
-        { path: entry.path, actual: nextEntryBytes },
-      );
-    }
-    if (
-      effectiveEntryLimit < this.limits.maxUncompressedBytes &&
-      nextEntryBytes > effectiveEntryLimit
-    ) {
-      throw entryTooLargeError(entry.path, nextEntryBytes, effectiveEntryLimit);
-    }
-
-    const nextTotal = this.emittedBytes + chunkBytes;
-    if (nextTotal > this.limits.maxUncompressedBytes) {
-      throw archiveTooLargeError(nextTotal, this.limits.maxUncompressedBytes);
-    }
-    if (nextEntryBytes > effectiveEntryLimit) {
-      throw entryTooLargeError(entry.path, nextEntryBytes, effectiveEntryLimit);
-    }
-
-    const ratio =
-      entry.compressedSize === undefined
-        ? undefined
-        : compressionRatio(nextEntryBytes, entry.compressedSize);
-    if (ratio !== undefined && ratio > this.limits.maxCompressionRatio) {
-      throw compressionRatioError(entry.path, ratio, this.limits.maxCompressionRatio);
-    }
-    this.emittedBytes = nextTotal;
-  }
-
-  private failArchive(error: ZipSafetyError): void {
-    if (this.terminalError) return;
-    this.terminalError = error;
-    for (const active of [...this.activeReads]) active.stop(error);
-  }
-
-  private throwIfFailed(): void {
-    if (this.terminalError) throw this.terminalError;
-  }
-}
-
-/** Load with JSZip, validate metadata, and create a shared bounded read session. */
-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, 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) {
-      throw tooManyEntriesError(declaredEntries, resolved.maxEntries);
-    }
-  }
-  let zip: JSZip;
-  try {
-    zip = await JSZip.loadAsync(prepared.input);
-  } catch (error: unknown) {
-    if (limits.signal?.aborted) throw limits.signal.reason ?? error;
-    throw invalidArchiveError(error);
-  }
-  throwIfZipAborted(limits.signal);
-  return createBoundedZipArchive(zip, limits);
-}
-
-function invalidArchiveError(cause: unknown): ZipSafetyError {
-  return new ZipSafetyError('invalid-archive', 'ZIP import: archive is not readable.', { cause });
-}
-
-/** Wrap an existing JSZip instance in the same validation and shared budget. */
-export function createBoundedZipArchive(
-  zip: JSZip,
-  limits: ZipSafetyLimits = {},
-): BoundedZipArchive {
-  throwIfZipAborted(limits.signal);
-  const resolved = resolveZipSafetyLimits(limits);
-  const entries = validateZipArchive(zip, limits);
-  throwIfZipAborted(limits.signal);
-  return new JsZipBoundedArchive(zip, entries, resolved, limits.signal);
-}
-
-function asZipSafetyError(error: unknown, path: string): ZipSafetyError {
-  if (error instanceof ZipSafetyError) return error;
-  return new ZipSafetyError(
-    'decompression-failed',
-    `ZIP import: could not decompress ${path}: ${error instanceof Error ? error.message : String(error)}`,
-    { path, cause: error },
-  );
-}
-
-function growOutput(
-  current: Uint8Array,
-  required: number,
-  declaredSize: number | undefined,
-  limit: number,
-): Uint8Array {
-  if (required <= current.byteLength) return current;
-  const maximum = Math.min(declaredSize ?? limit, limit);
-  const grownSize = current.byteLength === 0 ? required : current.byteLength * 2;
-  const nextSize = Math.min(maximum, Math.max(required, grownSize));
-  const next = new Uint8Array(nextSize);
-  next.set(current);
-  return next;
-}
-
-let crcTable: Uint32Array | undefined;
-
-function updateCrc32(crc: number, bytes: Uint8Array): number {
-  const table = crcTable ?? (crcTable = makeCrcTable());
-  let next = crc >>> 0;
-  for (const byte of bytes) next = table[(next ^ byte) & 0xff]! ^ (next >>> 8);
-  return next >>> 0;
-}
-
-function makeCrcTable(): Uint32Array {
-  const table = new Uint32Array(256);
-  for (let n = 0; n < table.length; n++) {
-    let value = n;
-    for (let bit = 0; bit < 8; bit++) {
-      value = (value & 1) !== 0 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
-    }
-    table[n] = value >>> 0;
-  }
-  return table;
-}

package/src/shared/container.ts

@@ -1,28 +0,0 @@
-/**
- * Shared tail for the container-producing importers.
- *
- * `docxToContainer`, `pptxToContainer`, and `pdfToContainer` all end the same
- * way: create a `MemoryContentContainer`, write the primary markdown document,
- * then write each extracted image under its path with its MIME type. This
- * factors that identical epilogue into one place.
- */
-
-import { MemoryContentContainer } from '@bendyline/squisq/storage';
-import type { ContentContainer } from '@bendyline/squisq/storage';
-
-/**
- * Assemble a {@link ContentContainer} from a markdown document plus a set of
- * media files. `images` is any iterable of `[path, { data, mimeType }]` pairs
- * (a `Map` from the importers' extraction context satisfies this directly).
- */
-export async function buildContainer(
-  markdown: string,
-  images: Iterable<readonly [string, { data: ArrayBuffer; mimeType: string }]>,
-): Promise<ContentContainer> {
-  const container = new MemoryContentContainer();
-  await container.writeDocument(markdown);
-  for (const [path, { data, mimeType }] of images) {
-    await container.writeFile(path, new Uint8Array(data), mimeType);
-  }
-  return container;
-}