@bendyline/squisq-formats 2.0.1 → 2.2.0

package/src/ooxml/namespaces.ts

@@ -1,196 +0,0 @@
-/**
- * OOXML Namespace Constants
- *
- * All Office Open XML namespace URIs used across DOCX, PPTX, and XLSX.
- * Organized by category for easy reference.
- */
-
-// ============================================
-// Package-level namespaces (shared by all formats)
-// ============================================
-
-/** Relationships namespace (used in _rels/*.rels files) */
-export const NS_RELATIONSHIPS = 'http://schemas.openxmlformats.org/package/2006/relationships';
-
-/** Content Types namespace ([Content_Types].xml) */
-export const NS_CONTENT_TYPES = 'http://schemas.openxmlformats.org/package/2006/content-types';
-
-// ============================================
-// Relationship type URIs
-// ============================================
-
-/** Relationship type: Office document (main part) */
-export const REL_OFFICE_DOCUMENT =
-  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument';
-
-/** Relationship type: Core properties */
-export const REL_CORE_PROPERTIES =
-  'http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties';
-
-/** Relationship type: Extended properties (app.xml) */
-export const REL_EXTENDED_PROPERTIES =
-  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties';
-
-/** Relationship type: Styles */
-export const REL_STYLES =
-  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles';
-
-/** Relationship type: Numbering */
-export const REL_NUMBERING =
-  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering';
-
-/** Relationship type: Font table */
-export const REL_FONT_TABLE =
-  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable';
-
-/** Relationship type: Settings */
-export const REL_SETTINGS =
-  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings';
-
-/** Relationship type: Hyperlink */
-export const REL_HYPERLINK =
-  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink';
-
-/** Relationship type: Image */
-export const REL_IMAGE =
-  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/image';
-
-/** Relationship type: Footnotes */
-export const REL_FOOTNOTES =
-  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes';
-
-/** Relationship type: Theme */
-export const REL_THEME =
-  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme';
-
-// ============================================
-// WordprocessingML (DOCX)
-// ============================================
-
-/** WordprocessingML main namespace (w:) */
-export const NS_WML = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
-
-// ============================================
-// PresentationML (PPTX)
-// ============================================
-
-/** PresentationML main namespace (p:) */
-export const NS_PML = 'http://schemas.openxmlformats.org/presentationml/2006/main';
-
-/** PowerPoint 2010 extension namespace (p14:) */
-export const NS_PML_2010 = 'http://schemas.microsoft.com/office/powerpoint/2010/main';
-
-// ============================================
-// SpreadsheetML (XLSX)
-// ============================================
-
-/** SpreadsheetML main namespace */
-export const NS_SML = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main';
-
-// ============================================
-// DrawingML (shared across formats)
-// ============================================
-
-/** DrawingML main namespace (a:) */
-export const NS_DRAWINGML = 'http://schemas.openxmlformats.org/drawingml/2006/main';
-
-/** DrawingML WordprocessingML drawing namespace (wp:) */
-export const NS_WP_DRAWING =
-  'http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing';
-
-/** DrawingML picture namespace (pic:) */
-export const NS_PICTURE = 'http://schemas.openxmlformats.org/drawingml/2006/picture';
-
-// ============================================
-// Dublin Core / Core Properties
-// ============================================
-
-/** Dublin Core elements namespace */
-export const NS_DC = 'http://purl.org/dc/elements/1.1/';
-
-/** Dublin Core terms namespace */
-export const NS_DCTERMS = 'http://purl.org/dc/terms/';
-
-/** Core properties namespace */
-export const NS_CORE_PROPERTIES =
-  'http://schemas.openxmlformats.org/package/2006/metadata/core-properties';
-
-/** XML Schema Instance namespace */
-export const NS_XSI = 'http://www.w3.org/2001/XMLSchema-instance';
-
-// ============================================
-// Markup Compatibility
-// ============================================
-
-/** Markup Compatibility namespace (mc:) */
-export const NS_MC = 'http://schemas.openxmlformats.org/markup-compatibility/2006';
-
-/** Office relationships namespace (r:) */
-export const NS_R = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
-
-// ============================================
-// Content type strings
-// ============================================
-
-export const CONTENT_TYPE_RELATIONSHIPS =
-  'application/vnd.openxmlformats-package.relationships+xml';
-
-export const CONTENT_TYPE_CORE_PROPERTIES =
-  'application/vnd.openxmlformats-package.core-properties+xml';
-
-export const CONTENT_TYPE_DOCX_DOCUMENT =
-  'application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml';
-
-export const CONTENT_TYPE_DOCX_STYLES =
-  'application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml';
-
-export const CONTENT_TYPE_DOCX_NUMBERING =
-  'application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml';
-
-export const CONTENT_TYPE_DOCX_SETTINGS =
-  'application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml';
-
-export const CONTENT_TYPE_DOCX_FONT_TABLE =
-  'application/vnd.openxmlformats-officedocument.wordprocessingml.fontTable+xml';
-
-export const CONTENT_TYPE_DOCX_FOOTNOTES =
-  'application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml';
-
-export const CONTENT_TYPE_PPTX_PRESENTATION =
-  'application/vnd.openxmlformats-officedocument.presentationml.presentation.main+xml';
-
-export const CONTENT_TYPE_PPTX_SLIDE =
-  'application/vnd.openxmlformats-officedocument.presentationml.slide+xml';
-
-export const CONTENT_TYPE_PPTX_SLIDE_LAYOUT =
-  'application/vnd.openxmlformats-officedocument.presentationml.slideLayout+xml';
-
-export const CONTENT_TYPE_PPTX_SLIDE_MASTER =
-  'application/vnd.openxmlformats-officedocument.presentationml.slideMaster+xml';
-
-export const CONTENT_TYPE_PPTX_THEME = 'application/vnd.openxmlformats-officedocument.theme+xml';
-
-/** Relationship type: Slide */
-export const REL_SLIDE =
-  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide';
-
-/** Relationship type: Slide layout */
-export const REL_SLIDE_LAYOUT =
-  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout';
-
-/** Relationship type: Slide master */
-export const REL_SLIDE_MASTER =
-  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideMaster';
-
-export const CONTENT_TYPE_XLSX_WORKBOOK =
-  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml';
-
-export const CONTENT_TYPE_XLSX_WORKSHEET =
-  'application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml';
-
-export const CONTENT_TYPE_XLSX_STYLES =
-  'application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml';
-
-/** Relationship type: Worksheet */
-export const REL_WORKSHEET =
-  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet';

package/src/ooxml/readUtils.ts

@@ -1,44 +0,0 @@
-/**
- * Shared DOM-read helpers for OOXML importers.
- *
- * Every importer walks parts with `getElementsByTagNameNS` and resolves
- * relationship targets relative to the referencing part; these helpers hold
- * the common pieces so new readers (theme, slide layouts) don't re-implement
- * them per format.
- */
-
-import type { Relationship } from './types.js';
-
-/**
- * Read a namespaced attribute with a qualified-name fallback for documents
- * whose producer omitted the namespace declaration (e.g. `r:id`).
- */
-export function attrNS(el: Element, ns: string, local: string, qualified: string): string | null {
-  return el.getAttributeNS(ns, local) ?? el.getAttribute(qualified);
-}
-
-/** Directory portion of a part path, e.g. `ppt/slides/slide1.xml` → `ppt/slides`. */
-export function baseDirOf(path: string): string {
-  const slash = path.lastIndexOf('/');
-  return slash === -1 ? '' : path.slice(0, slash);
-}
-
-/**
- * Resolve a relationship target against the referencing part's directory.
- * Absolute targets (leading `/`) are package-rooted; relative targets may
- * climb with `..` segments (e.g. `../slideLayouts/slideLayout1.xml`).
- */
-export function resolveTarget(baseDir: string, target: string): string {
-  if (target.startsWith('/')) return target.replace(/^\//, '');
-  const stack = baseDir ? baseDir.split('/') : [];
-  for (const seg of target.split('/')) {
-    if (seg === '..') stack.pop();
-    else if (seg !== '.') stack.push(seg);
-  }
-  return stack.join('/');
-}
-
-/** First relationship of the given type, if any. */
-export function findRelByType(rels: Relationship[], type: string): Relationship | undefined {
-  return rels.find((r) => r.type === type);
-}

package/src/ooxml/reader.ts

@@ -1,318 +0,0 @@
-/**
- * OOXML Package Reader
- *
- * Opens OOXML archives (.docx, .pptx, .xlsx) and parses their
- * structural metadata: [Content_Types].xml, relationships, and
- * core properties.
- *
- * 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';
-import type { OoxmlPackage, ContentTypeMap, Relationship, CoreProperties } from './types.js';
-import { NS_RELATIONSHIPS, NS_DC, NS_DCTERMS, NS_CORE_PROPERTIES } from './namespaces.js';
-import {
-  openBoundedZipArchive,
-  type BoundedZipArchive,
-  type ZipSafetyLimits,
-} from '../shared/zipSafety.js';
-
-export type OoxmlOpenOptions = ZipSafetyLimits;
-
-type DomParserLike = new () => {
-  parseFromString(source: string, mimeType: string): unknown;
-};
-
-/** 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 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, 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;
-}
-
-// ============================================
-// Package Opening
-// ============================================
-
-/**
- * Open an OOXML package from raw data.
- *
- * Parses the ZIP archive, [Content_Types].xml, and root relationships.
- *
- * @param data - The raw .docx/.pptx/.xlsx file as ArrayBuffer or Blob
- * @param limits - Optional archive count, size, and compression-ratio limits
- * @returns A parsed OoxmlPackage
- */
-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, 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;
-}
-
-// ============================================
-// Content Types
-// ============================================
-
-/**
- * Parse [Content_Types].xml from the archive.
- */
-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, 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');
-    if (ext && ct) defaults.set(ext, ct);
-  }
-
-  // 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');
-    if (partName && ct) {
-      // Normalize: strip leading slash
-      overrides.set(partName.replace(/^\//, ''), ct);
-    }
-  }
-
-  return { overrides, defaults };
-}
-
-// ============================================
-// Relationships
-// ============================================
-
-/**
- * Parse relationships for a specific part.
- *
- * @param pkg - The OOXML package (or the zip directly)
- * @param partPath - The part path (e.g., "word/document.xml").
- *   Use "" for root-level relationships (_rels/.rels).
- * @returns Array of relationship entries
- */
-export async function getPartRelationships(
-  pkg: OoxmlPackage,
-  partPath: string,
-): Promise<Relationship[]> {
-  return parseRelationships(pkg, partPath, packageSignals.get(pkg));
-}
-
-/**
- * Parse a _rels/*.rels file from the ZIP.
- *
- * For root relationships, relsPath = "_rels/.rels".
- * For part relationships, relsPath = "<dir>/_rels/<filename>.rels".
- */
-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, signal);
-  const result: Relationship[] = [];
-
-  const els = doc.getElementsByTagNameNS(NS_RELATIONSHIPS, 'Relationship');
-  // Fallback in case namespace isn't used (some generators omit it)
-  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');
-    const target = el.getAttribute('Target');
-    if (id && type && target) {
-      const targetMode = el.getAttribute('TargetMode') as 'Internal' | 'External' | null;
-      result.push({
-        id,
-        type,
-        target,
-        ...(targetMode ? { targetMode } : {}),
-      });
-    }
-  }
-
-  return result;
-}
-
-/**
- * Build the _rels path for a given part path.
- *
- * "word/document.xml" → "word/_rels/document.xml.rels"
- * "xl/workbook.xml"   → "xl/_rels/workbook.xml.rels"
- */
-function buildRelsPath(partPath: string): string {
-  const lastSlash = partPath.lastIndexOf('/');
-  if (lastSlash === -1) {
-    return `_rels/${partPath}.rels`;
-  }
-  const dir = partPath.substring(0, lastSlash);
-  const file = partPath.substring(lastSlash + 1);
-  return `${dir}/_rels/${file}.rels`;
-}
-
-// ============================================
-// Part Access
-// ============================================
-
-/**
- * Extract an XML part from the package and parse it as a DOM Document.
- *
- * @param pkg - The OOXML package
- * @param partPath - Path within the archive (e.g., "word/document.xml")
- * @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), signal) : null;
-}
-
-/**
- * Extract a binary part from the package (e.g., an image from word/media/).
- *
- * @param pkg - The OOXML package
- * @param partPath - Path within the archive
- * @returns The binary content, or null if the part doesn't exist
- */
-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;
-}
-
-function readArchivePart(
-  source: OoxmlPackage | BoundedZipArchive,
-  path: string,
-  maxBytes?: number,
-): Promise<Uint8Array | null> {
-  return 'entries' in source
-    ? source.read(path, maxBytes)
-    : readPackagePart(source, path, maxBytes);
-}
-
-async function readPackagePart(
-  pkg: OoxmlPackage,
-  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().');
-  }
-  return archive.read(path, maxBytes);
-}
-
-// ============================================
-// Core Properties
-// ============================================
-
-/**
- * Parse core document properties from docProps/core.xml.
- *
- * @param pkg - The OOXML package
- * @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 {};
-
-  function getText(ns: string, localName: string): string | undefined {
-    const els = doc!.getElementsByTagNameNS(ns, localName);
-    if (els.length > 0 && els[0].textContent) {
-      return els[0].textContent;
-    }
-    return undefined;
-  }
-
-  const properties = {
-    title: getText(NS_DC, 'title'),
-    subject: getText(NS_DC, 'subject'),
-    creator: getText(NS_DC, 'creator'),
-    description: getText(NS_DC, 'description'),
-    keywords: getText(NS_CORE_PROPERTIES, 'keywords'),
-    lastModifiedBy: getText(NS_CORE_PROPERTIES, 'lastModifiedBy'),
-    revision: getText(NS_CORE_PROPERTIES, 'revision'),
-    created: getText(NS_DCTERMS, 'created'),
-    modified: getText(NS_DCTERMS, 'modified'),
-  };
-  throwIfOoxmlAborted(signal);
-  return properties;
-}