mammoth

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]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]raw.githubusercontent.com/mwilliamson/mammoth.jshttps://raw.githubusercontent.com/mwilliamson/mammoth.js/master/README.md
2. [2]github.com/mwilliamson/mammoth.jshttps://github.com/mwilliamson/mammoth.js/blob/master/lib/unzip.js
3. [3]github.com/mwilliamson/mammoth.jshttps://github.com/mwilliamson/mammoth.js/blob/master/lib/zipfile.js
4. [4]github.com/mwilliamson/mammoth.jshttps://github.com/mwilliamson/mammoth.js/blob/master/lib/index.js