feat: allow passing in memory buffers

README.md

@@ -2,7 +2,9 @@
 
 [![CI](https://github.com/dead8309/markitdown-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/dead8309/markitdown/actions/workflows/ci.yml)
 
-`markitdown-ts` is a TypeScript library designed for converting various file formats to Markdown. This makes it suitable for indexing, text analysis, and other applications that benefit from structured text. It is a TypeScript implementation of the original `markitdown` [Python library.](https://github.com/microsoft/markitdown)
+`markitdown-ts` is a TypeScript library designed for converting various file formats to Markdown. It can process fiiles from local paths, URLs, or directly from in-memory buffers, making it ideal for serverless and edge environments like Supabase Functions or Cloudflare Workers.
+
+It is a TypeScript implementation of the original `markitdown` [Python library.](https://github.com/microsoft/markitdown) and is suitable for indexing, text analysis, and other applications that benefit from structured text.
 
 It supports:
 
@@ -32,12 +34,21 @@ pnpm add markitdown-ts
 
 ## Usage
 
+### Basic Usage (from a File Path)
+
+The simplest way to use the library is by providing a local file path or a URL.
+
 ```typescript
 import { MarkItDown } from "markitdown-ts";
 
 const markitdown = new MarkItDown();
 try {
+  // Convert a local file
   const result = await markitdown.convert("path/to/your/file.pdf");
+
+  // Or convert from a URL
+  const result = await markitdown.convert("https://arxiv.org/pdf/2308.08155v2.pdf");
+
   if (result) {
     console.log(result.text_content);
   }
@@ -46,7 +57,57 @@ try {
 }
 ```
 
-Pass additional options as needed for specific functionality.
+### Advanced Usage (from Buffers, Blobs, or Responses)
+
+For use in serverless environments where you can't rely on a persistent filesystem, you can convert data directly from memory.
+
+> [!IMPORTANT]
+>
+> This is the recommended approach for environments like **Supabase Edge Functions**, **Cloudflare Workers**, or **AWS Lambda**.
+
+#### From a Buffer
+
+If you have your file content in a `Buffer`, use the `convertBuffer` method. You **must** provide the `file_extension` in the options so the library knows which converter to use.
+
+```typescript
+import { MarkItDown } from "markitdown-ts";
+import * as fs from "fs";
+
+const markitdown = new MarkItDown();
+try {
+  const buffer = fs.readFileSync("path/to/your/file.docx");
+  const result = await markitdown.convertBuffer(buffer, {
+    file_extension: ".docx"
+  });
+  console.log(result?.text_content);
+} catch (error) {
+  console.error("Conversion failed:", error);
+}
+```
+
+#### From a Response or Blob
+
+You can pass a standard `Response` object directly to the `convert` method. This is perfect for handling file uploads from a request body.
+
+```typescript
+import { MarkItDown } from "markitdown-ts";
+
+const markitdown = new MarkItDown();
+
+// Example: Simulating a file upload by creating a Blob and a Response
+const buffer = fs.readFileSync("path/to/archive.zip");
+const blob = new Blob([buffer]);
+const response = new Response(blob, {
+  headers: { "Content-Type": "application/zip" }
+});
+
+try {
+  const result = await markitdown.convert(response);
+  console.log(result?.text_content);
+} catch (error) {
+  console.error("Conversion failed:", error);
+}
+```
 
 ## YouTube Transcript Support
 
@@ -76,11 +137,22 @@ const result = await markitdown.convert("test.jpg", {
 
 ## API
 
-The library uses a single function `convert` for all conversions, with the options and the response type defined as such:
+The library exposes a `MarkItDown` class with two primary conversion methods.
 
 ```typescript
-export interface DocumentConverter {
-  convert(local_path: string, options: ConverterOptions): Promise<ConverterResult>;
+class MarkItDown {
+  /**
+   * Converts a source from a file path, URL, or Response object.
+   */
+  async convert(source: string | Response, options?: ConverterOptions): Promise<ConverterResult>;
+
+  /**
+   * Converts a source from an in-memory Buffer.
+   */
+  async convertBuffer(
+    source: Buffer,
+    options: ConverterOptions & { file_extension: string }
+  ): Promise<ConverterResult>;
 }
 
 export type ConverterResult =
@@ -92,16 +164,28 @@ export type ConverterResult =
   | undefined;
 
 export type ConverterOption = {
+  // Required when using convertBuffer
   file_extension?: string;
+
+  // For URL-based converters (e.g., Wikipedia, Bing SERP)
   url?: string;
+
+  // Provide a custom fetch implementation
   fetch?: typeof fetch;
-  enableYoutubeTranscript?: boolean; // false by default
-  youtubeTranscriptLanguage?: string; // "en" by default
-  llmModel: string;
+
+  // YouTube-specific options
+  enableYoutubeTranscript?: boolean; // Default: false
+  youtubeTranscriptLanguage?: string; // Default: "en"
+
+  // Image-specific LLM options
+  llmModel?: LanguageModel;
   llmPrompt?: string;
+
+  // Options for .docx conversion (passed to mammoth.js)
   styleMap?: string | Array<string>;
-  _parent_converters?: DocumentConverter[];
-  cleanup_extracted?: boolean;
+
+  // Options for .zip conversion
+  cleanupExtracted?: boolean; // Default: true
 };
 ```
 

src/converters/bingserp.ts

@@ -6,7 +6,7 @@ import { CustomTurnDown } from "../custom-turndown";
 
 export class BingSerpConverter implements DocumentConverter {
   async convert(
-    localPath: string,
+    source: string | Buffer,
     options: ConverterOptions = {}
   ): Promise<ConverterResult | null> {
     const fileExtension = options.file_extension || "";
@@ -19,7 +19,10 @@ export class BingSerpConverter implements DocumentConverter {
     }
 
     try {
-      const htmlContent = fs.readFileSync(localPath, { encoding: "utf-8" });
+      const htmlContent =
+        typeof source === "string"
+          ? fs.readFileSync(source, { encoding: "utf-8" })
+          : Buffer.from(source).toString("utf-8");
       return this._convert(htmlContent, url);
     } catch (error) {
       console.error("Bing SERP Parsing Error:", error);

src/converters/docx.ts

@@ -4,25 +4,26 @@ import { HtmlConverter } from "./html";
 import Mammoth from "mammoth";
 
 export class DocxConverter extends HtmlConverter {
-  async convert(local_path: string, options: ConverterOptions): Promise<ConverterResult> {
+  async convert(source: string | Buffer, options: ConverterOptions): Promise<ConverterResult> {
     const fileExtension = options.file_extension || "";
     if (![".docx"].includes(fileExtension.toLowerCase())) {
       return null;
     }
 
     try {
-      let exists = fs.existsSync(local_path);
-      if (!exists) {
-        throw new Error("File does'nt exists");
-      }
-      let htmlContent = await Mammoth.convertToHtml(
-        {
-          path: local_path
-        },
-        {
-          ...options
+      let mammothInput: { path: string } | { buffer: Buffer };
+      if (typeof source === "string") {
+        if (!fs.existsSync(source)) {
+          throw new Error("File does'nt exists");
         }
-      );
+        mammothInput = { path: source };
+      } else {
+        mammothInput = { buffer: Buffer.from(source) };
+      }
+
+      let htmlContent = await Mammoth.convertToHtml(mammothInput, {
+        ...options
+      });
 
       return await this._convert(htmlContent.value);
     } catch (e) {

src/converters/html.ts

@@ -4,18 +4,24 @@ import { CustomTurnDown } from "../custom-turndown";
 import { ConverterOptions, ConverterResult, DocumentConverter } from "../types";
 
 export class HtmlConverter implements DocumentConverter {
-  async convert(local_path: string, options: ConverterOptions): Promise<ConverterResult> {
+  async convert(source: string | Buffer, options: ConverterOptions): Promise<ConverterResult> {
     const extension = options.file_extension || "";
     if (![".html", ".htm"].includes(extension.toLowerCase())) {
       return null;
     }
 
     try {
-      let exists = fs.existsSync(local_path);
-      if (!exists) {
-        throw new Error("File does'nt exists");
+      let content;
+      if (typeof source === "string") {
+        let exists = fs.existsSync(source);
+        if (!exists) {
+          throw new Error("File does'nt exists");
+        }
+        content = fs.readFileSync(source, { encoding: "utf-8" });
+      } else {
+        content = source.toString("utf-8");
       }
-      let content = fs.readFileSync(local_path, { encoding: "utf-8" });
+
       return await this._convert(content);
     } catch (e) {
       console.error(e);

src/converters/image.ts

@@ -5,7 +5,7 @@ import { generateText } from "ai";
 
 export class ImageConverter extends MediaConverter {
   async convert(
-    localPath: string,
+    source: string | Buffer,
     options: ConverterOptions = {}
   ): Promise<ConverterResult | null> {
     const fileExtension = options.file_extension || "";
@@ -14,49 +14,62 @@ export class ImageConverter extends MediaConverter {
     }
 
     try {
-      return this._convert(localPath, options);
+      return this._convert(source, options);
     } catch (error) {
       console.error("Image Conversion Error:", error);
       return null;
     }
   }
-  private async _convert(localPath: string, options: ConverterOptions): Promise<ConverterResult> {
+  private async _convert(
+    source: string | Buffer,
+    options: ConverterOptions
+  ): Promise<ConverterResult> {
     let mdContent = "";
 
-    const metadata = await this._getMetadata(localPath);
-    if (metadata) {
-      for (const f of [
-        "ImageSize",
-        "Title",
-        "Caption",
-        "Description",
-        "Keywords",
-        "Artist",
-        "Author",
-        "DateTimeOriginal",
-        "CreateDate",
-        "GPSPosition"
-      ]) {
-        if (metadata[f]) {
-          mdContent += `${f}: ${metadata[f]}\n`;
+    if (typeof source === "string") {
+      const metadata = await this._getMetadata(source);
+      if (metadata) {
+        for (const f of [
+          "ImageSize",
+          "Title",
+          "Caption",
+          "Description",
+          "Keywords",
+          "Artist",
+          "Author",
+          "DateTimeOriginal",
+          "CreateDate",
+          "GPSPosition"
+        ]) {
+          if (metadata[f]) {
+            mdContent += `${f}: ${metadata[f]}\n`;
+          }
         }
       }
+    } else {
+      console.warn(
+        "Metadata extraction is skipped for Buffer inputs as it requires a file path for exiftool."
+      );
     }
+
     if (options.llmModel) {
-      mdContent += `\n# Description:\n${(
-        await this._getLLMDescription(localPath, options)
-      ).trim()}\n`;
+      const imageBuffer =
+        typeof source === "string" ? fs.readFileSync(source) : Buffer.from(source);
+      mdContent += `\n# Description:\n${(await this._getLLMDescription(imageBuffer, options)).trim()}\n`;
     }
     return {
       title: null,
       text_content: mdContent.trim()
     };
   }
-  private async _getLLMDescription(localPath: string, options: ConverterOptions): Promise<string> {
+  private async _getLLMDescription(
+    imageBuffer: Buffer,
+    options: ConverterOptions
+  ): Promise<string> {
     if (!options.llmPrompt || options.llmPrompt.trim() === "") {
       options.llmPrompt = "Write a detailed caption for this image.";
     }
-    const imageFile = fs.readFileSync(localPath).toString("base64");
+    const imageFileAsBase64 = imageBuffer.toString("base64");
 
     const result = await generateText({
       model: options.llmModel!,
@@ -67,7 +80,7 @@ export class ImageConverter extends MediaConverter {
             { type: "text", text: options.llmPrompt },
             {
               type: "image",
-              image: imageFile
+              image: imageFileAsBase64
             }
           ]
         }

src/converters/ipynb.ts

@@ -3,15 +3,19 @@ import * as fs from "fs";
 
 export class IpynbConverter implements DocumentConverter {
   async convert(
-    localPath: string,
+    source: string | Buffer,
     options: ConverterOptions = {}
   ): Promise<ConverterResult | null> {
     const fileExtension = options.file_extension || "";
     if (fileExtension.toLowerCase() !== ".ipynb") {
       return null;
     }
     try {
-      const notebookContent = JSON.parse(fs.readFileSync(localPath, { encoding: "utf-8" }));
+      const contentStirng =
+        typeof source === "string"
+          ? fs.readFileSync(source, { encoding: "utf-8" })
+          : source.toString("utf-8");
+      const notebookContent = JSON.parse(contentStirng);
       return this._convert(notebookContent);
     } catch (error) {
       console.error("Error converting .ipynb file:", error);

src/converters/media.ts

@@ -5,16 +5,19 @@ import * as util from "util";
 const exec = util.promisify(childProcess.exec);
 
 export abstract class MediaConverter implements DocumentConverter {
-  abstract convert(localPath: string, options: ConverterOptions): Promise<ConverterResult | null>;
+  abstract convert(
+    source: string | Buffer,
+    options: ConverterOptions
+  ): Promise<ConverterResult | null>;
 
-  async _getMetadata(localPath: string): Promise<{ [key: string]: string } | null> {
+  async _getMetadata(local_path: string): Promise<{ [key: string]: string } | null> {
     const exiftool = await this._which("exiftool");
     if (!exiftool) {
       console.error("exiftool is not found on this system so metadata cannot be extracted");
       return null;
     }
     try {
-      const result = await exec(`"${exiftool}" -json "${localPath}"`);
+      const result = await exec(`"${exiftool}" -json "${local_path}"`);
       return JSON.parse(result.stdout)[0];
     } catch (error) {
       console.error("Exiftool error:", error);