@origints/mammoth 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,171 @@
+# @origints/mammoth
+
+> DOCX to HTML/text conversion for Origins using mammoth.js.
+
+---
+
+## Why
+
+Word documents are everywhere in enterprise workflows, but extracting their content programmatically is challenging. You need to convert them to a usable format while preserving semantic structure.
+
+This package wraps mammoth.js and exposes it as Origins transforms. Convert DOCX files to clean HTML or plain text, with full control over style mapping and conversion options.
+
+---
+
+## Features
+
+- Convert DOCX to semantic HTML
+- Convert DOCX to plain text
+- Custom style mapping for headings, lists, and more
+- Configurable image handling
+- Conversion warnings and messages
+- Integrates with Origins transform registry
+
+---
+
+## Quick Start
+
+```bash
+npm install @origints/mammoth @origints/core
+```
+
+```ts
+import { Planner, loadFile, run, globalRegistry } from "@origints/core";
+import { docxToHtml, registerMammothTransforms } from "@origints/mammoth";
+
+registerMammothTransforms(globalRegistry);
+
+const plan = Planner.in(loadFile("document.docx"))
+  .mapIn(docxToHtml())
+  .emit((out, $) => out.add("html", $.get("html").asString()))
+  .compile();
+
+const result = await run(plan, {}, globalRegistry);
+
+if (result.ok) {
+  console.log(result.value.html);
+}
+```
+
+Expected output:
+
+```
+<h1>Document Title</h1><p>Content here...</p>
+```
+
+---
+
+## Installation
+
+- Supported platforms:
+  - macOS / Linux / Windows
+- Runtime requirements:
+  - Node.js >= 18
+- Package managers:
+  - npm, pnpm, yarn
+- Peer dependencies:
+  - @origints/core ^0.1.0
+
+```bash
+npm install @origints/mammoth @origints/core
+# or
+pnpm add @origints/mammoth @origints/core
+```
+
+---
+
+## Usage
+
+### Basic HTML conversion
+
+```ts
+import { Planner, loadFile, globalRegistry } from "@origints/core";
+import { docxToHtml, registerMammothTransforms } from "@origints/mammoth";
+
+registerMammothTransforms(globalRegistry);
+
+const plan = Planner.in(loadFile("report.docx"))
+  .mapIn(docxToHtml())
+  .emit((out, $) => {
+    out.add("html", $.get("html").asString());
+    out.add("messages", $.get("messages").asArray());
+  })
+  .compile();
+```
+
+### Custom style mapping
+
+```ts
+const plan = Planner.in(loadFile("document.docx"))
+  .mapIn(
+    docxToHtml({
+      styleMap: [
+        "p[style-name='Title'] => h1.document-title",
+        "p[style-name='Heading 1'] => h1",
+        "p[style-name='Heading 2'] => h2",
+        "p[style-name='Quote'] => blockquote",
+      ],
+    })
+  )
+  .emit((out, $) => out.add("html", $.get("html").asString()))
+  .compile();
+```
+
+### Convert to plain text
+
+```ts
+import { docxToText } from "@origints/mammoth";
+
+const plan = Planner.in(loadFile("document.docx"))
+  .mapIn(docxToText())
+  .emit((out, $) => out.add("text", $.get("text").asString()))
+  .compile();
+```
+
+### Image handling options
+
+```ts
+const plan = Planner.in(loadFile("document.docx"))
+  .mapIn(
+    docxToHtml({
+      imageHandling: "omit", // or 'base64'
+    })
+  )
+  .emit((out, $) => out.add("html", $.get("html").asString()))
+  .compile();
+```
+
+---
+
+## Project Status
+
+- **Experimental** - APIs may change
+
+---
+
+## Non-Goals
+
+- Not a DOCX writer/generator
+- Not a full Word document parser (no styles, comments, etc.)
+- Not a PDF converter
+
+---
+
+## Documentation
+
+- See `@origints/core` for Origins concepts
+- See [mammoth.js](https://www.npmjs.com/package/mammoth) for conversion details
+
+---
+
+## Contributing
+
+- Open an issue before large changes
+- Keep PRs focused
+- Tests required for new features
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@origints/mammoth",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "DOCX to HTML conversion for Origins using mammoth.js",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,13 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint \"{src,tests}/**/*.{ts,tsx}\" --max-warnings 0",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
   "dependencies": {
     "mammoth": "^1.11.0"
   },
@@ -27,6 +34,7 @@
     "@origints/core": "^0.1.0"
   },
   "devDependencies": {
+    "@origints/core": "workspace:*",
     "@types/node": "25.0.6",
     "@vitest/coverage-v8": "^4.0.16",
     "eslint": "9.39.2",
@@ -34,14 +42,6 @@
     "typescript": "5.9.3",
     "vite": "7.3.1",
     "vite-plugin-dts": "4.5.4",
-    "vitest": "4.0.16",
-    "@origints/core": "0.1.0"
-  },
-  "scripts": {
-    "build": "vite build",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "lint": "eslint \"{src,tests}/**/*.{ts,tsx}\" --max-warnings 0",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "vitest": "4.0.16"
   }
-}
+}