Postconditions: what we check

• convertToHtml · file-read-error

  error
  WhenFile path does not exist, cannot be read, or input options are invalid
  ThrowsError (ENOENT, EACCES, or 'Could not find file in options')
  Required handlingCaller MUST wrap convertToHtml() in try-catch to handle file-not-found and permission errors.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• convertToHtml · corrupt-docx-error

  error
  WhenBuffer contains invalid or corrupt docx/zip data
  ThrowsError (zip parsing error)
  Required handlingCaller MUST wrap convertToHtml() in try-catch to handle corrupt or invalid docx files.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• extractRawText · file-read-error

  error
  WhenFile path does not exist, cannot be read, or input options are invalid
  ThrowsError (ENOENT, EACCES, or 'Could not find file in options')
  Required handlingCaller MUST wrap extractRawText() in try-catch to handle file-not-found and permission errors.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• extractRawText · corrupt-docx-error

  error
  WhenBuffer contains invalid or corrupt docx/zip data
  ThrowsError (zip parsing error)
  Required handlingCaller MUST wrap extractRawText() in try-catch to handle corrupt or invalid docx files.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• convertToMarkdown · converttomarkdown-file-read-error

  error
  WhenFile path does not exist, cannot be read, or input options are missing
  ThrowsError (ENOENT, EACCES, or 'Could not find file in options')
  Required handlingCaller MUST wrap convertToMarkdown() in try-catch. Error propagates from unzip.js when the file path does not exist (ENOENT), cannot be accessed (EACCES), or when no valid input type is provided. Without handling, a missing upload causes an unhandled promise rejection that crashes the processing pipeline.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• convertToMarkdown · converttomarkdown-corrupt-docx-error

  error
  WhenBuffer contains invalid or corrupt docx/zip data
  ThrowsError (zip parsing error from JSZip.loadAsync)
  Required handlingCaller MUST wrap convertToMarkdown() in try-catch. Corrupt .docx files are common when processing user-uploaded documents. JSZip.loadAsync() rejects when the input is not a valid ZIP file (all .docx are ZIP archives). The error propagates up through unzip.openZip() without transformation.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][3]
• convertToMarkdown · converttomarkdown-deprecated-use

  warning
  WhenconvertToMarkdown is called in new code (not legacy maintenance) instead of converting to HTML first and using a dedicated HTML-to-Markdown library
  ReturnsMarkdown output in result.value, but the implementation is not maintained. The official recommendation is to call convertToHtml() and pipe through a dedicated library (e.g. turndown) for better results.
  Required handlingSHOULD migrate to convertToHtml() + turndown pattern. The Mammoth maintainer has explicitly deprecated this function. New code should not use it. Existing callers should migrate to avoid quality regressions as the Markdown support is no longer improved.
  costlowin proddegraded serviceusers seedegraded performancevisibilitysilent
  Sources[1]
• embedStyleMap · embedstylemap-file-read-error

  error
  WhenInput file path does not exist, is unreadable, or input options are missing
  ThrowsError (ENOENT, EACCES, or 'Could not find file in options')
  Required handlingCaller MUST wrap embedStyleMap() in try-catch. The function opens the .docx via unzip.openZip(), which throws when the file path is missing or the buffer is invalid. Document transformation pipelines that pre-process uploaded .docx files for style consistency must handle missing-file scenarios.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• embedStyleMap · embedstylemap-corrupt-docx-error

  error
  WhenInput buffer contains invalid or corrupt docx/zip data
  ThrowsError (zip parsing error from JSZip.loadAsync)
  Required handlingCaller MUST wrap embedStyleMap() in try-catch. The function reads the .docx ZIP structure to inject the style map. A corrupt archive causes JSZip to reject. This is critical in document pre-processing pipelines that modify uploaded docs before storage — corrupted inputs must be caught and rejected early.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][3]
• embedStyleMap · embedstylemap-result-not-saved

  warning
  WhenembedStyleMap() resolves successfully but the caller does not call toBuffer() or toArrayBuffer() to persist the modified document, OR does not write the returned buffer to storage (file system or object store)
  ReturnsPromise resolves to {toArrayBuffer(), toBuffer()} — if the result is not written to storage, the embedded style map is silently lost. The original file is NOT modified in place — a new document must be explicitly saved.
  Required handlingCaller MUST call docx.toBuffer() or docx.toArrayBuffer() on the resolved value AND write it to persistent storage. The function does not overwrite the original file. If the result is not persisted, the style map embedding is silently lost and future conversions will use the original document without the embedded map.
  costlowin prodsilent failureusers seelost datavisibilitysilent
  Sources[1][4]
• readAsArrayBuffer · readasarraybuffer-image-missing-from-zip

  error
  WhenThe embedded image referenced in the .docx relationships is missing from the underlying zip archive (corrupt or hand-edited .docx where the image part was deleted but the relationship/reference remained), OR the relationship resolves to an invalid zip path. JSZip's zipFile.file(name) returns null and the subsequent .async("uint8array") access throws TypeError.
  ThrowsTypeError (Cannot read properties of null (reading 'async')) from JSZip
  Required handlingCaller MUST wrap image.readAsArrayBuffer() in try-catch inside the imageConverter callback (or attach .catch() to the returned Promise). Without handling, the rejected Promise propagates up through the imgElement wrapper and surfaces as a conversion-level rejection that crashes the entire convertToHtml/convertToMarkdown call — one missing image breaks the whole document conversion.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][3][5]
• readAsBase64String · readasbase64string-image-missing-from-zip

  error
  WhenThe embedded image referenced in the .docx relationships is missing from the underlying zip archive, OR the relationship resolves to an invalid zip path. JSZip's zipFile.file(name) returns null and the subsequent .async() access throws. This is the common failure mode for hand-edited or partially-corrupted .docx files and propagates through the default dataUri converter.
  ThrowsTypeError (Cannot read properties of null (reading 'async')) from JSZip
  Required handlingCaller MUST wrap image.readAsBase64String() in try-catch inside the imageConverter callback, or attach .catch() to the returned Promise. Custom imgElement callbacks that use readAsBase64String to build data-URI src attributes must handle the rejection — without handling, one corrupt image embed crashes the entire convertToHtml/convertToMarkdown pipeline and the user sees a 500/unhandled rejection instead of a partial document with a warning.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][3][5][6]
• readAsBuffer · readasbuffer-image-missing-from-zip

  error
  WhenThe embedded image referenced in the .docx relationships is missing from the underlying zip archive, OR the relationship path is invalid. JSZip's zipFile.file(name) returns null and the .async() access throws TypeError before Buffer.from is reached.
  ThrowsTypeError (Cannot read properties of null (reading 'async')) from JSZip
  Required handlingCaller MUST wrap image.readAsBuffer() in try-catch inside the imageConverter callback, or attach .catch() to the returned Promise. An uncaught rejection propagates through the imgElement wrapper and crashes the whole document conversion.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][3][5]
• readAsBuffer · readasbuffer-browser-no-buffer-polyfill

  warning
  Whenimage.readAsBuffer() is called from browser code without a Buffer polyfill (e.g. mammoth bundled into a frontend app without webpack/vite Buffer shim). The underlying options.readImage() resolves an ArrayBuffer, then Buffer.from throws ReferenceError because Buffer is not a global in browsers.
  ThrowsReferenceError (Buffer is not defined) — browsers without polyfill
  Required handlingCaller MUST either (a) avoid readAsBuffer() in browser code and use readAsArrayBuffer() or readAsBase64String() instead, OR (b) wrap the call in try-catch and supply a polyfilled fallback. The mammoth README explicitly warns "This is not supported in browsers unless a Buffer polyfill has been used." Custom imageConverters shipped in isomorphic libraries must guard this method or ship a polyfill.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][5]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.