effect-libreoffice 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Install LibreOffice
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends libreoffice-writer
+
+      - name: Lint
+        run: pnpm biome ci .
+
+      - name: Type check
+        run: pnpm type-check
+
+      - name: Test
+        run: pnpm test

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "typescript.tsdk": "node_modules/typescript/lib"
+}

package/Dockerfile

@@ -0,0 +1,12 @@
+FROM alpine:latest
+
+# install fonts https://wiki.alpinelinux.org/wiki/Fonts
+RUN apk add --no-cache font-terminus font-inconsolata font-dejavu font-noto font-noto-cjk font-awesome font-noto-extra
+
+# install libreoffice + dependencies
+RUN apk add --no-cache libreoffice-writer python3 py3-pip openjdk11-jre-headless
+
+# install unoserver via pip
+RUN pip install unoserver --break-system-packages
+
+CMD ["unoserver", "--interface", "0.0.0.0"]

package/README.md

@@ -0,0 +1,82 @@
+# effect-libreoffice
+
+A Effect-based wrapper for LibreOffice, providing multiple strategies for document conversion.
+
+## Implementations
+
+This library offers two distinct implementations for interacting with LibreOffice:
+
+1.  **LibreOfficeCmd (Default)**: Uses the `soffice` command-line tool directly.
+2.  **UnoClient (Uno)**: Connects to a running `unoserver` instance.
+
+### Comparison
+
+| Feature         | LibreOfficeCmd (Default)                 | UnoClient (Uno)                            |
+| :-------------- | :--------------------------------------- | :----------------------------------------- |
+| **Method**      | Spawns a new process for each conversion | Connects to a long-running server          |
+| **Performance** | Slower (~440ms/file)                     | Fast (~60ms/file)                          |
+| **Setup**       | Requires LibreOffice installed locally   | Requires `unoserver`                       |
+| **Best For**    | CLI tools, low volume, simple setup      | Servers, high volume, performance critical |
+
+## Usage
+
+### Default Implementation (CLI)
+
+Best for quick scripts or when you don't want to manage a separate server.
+
+```typescript
+import { LibreOffice } from "effect-libreoffice";
+import { NodeContext } from "@effect/platform-node";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const libre = yield* LibreOffice;
+  yield* libre.convertLocalFile("input.docx", "output.pdf");
+});
+
+// Provide the Default layer (which uses LibreOfficeCmd) and NodeContext
+program.pipe(
+  Effect.provide(LibreOffice.Default),
+  Effect.provide(NodeContext.layer),
+  Effect.runPromise
+);
+```
+
+### Uno Implementation (Remote)
+
+Best for server environments. You need a running `unoserver`.
+
+```yaml
+# compose.yml
+services:
+  unoserver:
+    image: libreofficedocker/libreoffice-unoserver:3.22
+    ports:
+      - "2003:2003"
+    volumes:
+      - /tmp:/tmp # some shared directory where files can be written and read
+```
+
+```typescript
+import { LibreOffice, UnoClient, UnoServer } from "effect-libreoffice";
+import { NodeContext, NodeHttpClient } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+
+const program = Effect.gen(function* () {
+  const libre = yield* LibreOffice;
+  yield* libre.convertLocalFile("input.docx", "output.pdf");
+});
+
+const UnoLayer = LibreOffice.Uno.pipe(
+  Layer.provide(UnoClient.Default),
+  Layer.provide(UnoServer.Remote) // Defaults to localhost:2003
+  // Layer.provide(UnoServer.remoteWithURL("http://unoserver:2003/RPC2"))
+);
+
+program.pipe(
+  Effect.provide(UnoLayer),
+  Effect.provide(NodeHttpClient.layer),
+  Effect.provide(NodeContext.layer),
+  Effect.runPromise
+);
+```

package/biome.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.3.10/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": true
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space"
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": {
+        "noShadowRestrictedNames": "off"
+      },
+      "correctness": {
+        "noUnusedVariables": {
+          "level": "warn",
+          "fix": "none"
+        }
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

package/compose.yml

@@ -0,0 +1,19 @@
+services:
+  # unoserver:
+  #   image: libreofficedocker/libreoffice-unoserver:3.22
+  #   ports:
+  #     - "2004:2004" # uno rest api
+  #     - "2003:2003" # uno api
+  unoserver:
+    build: .
+    ports:
+      - "2003:2003" # uno api
+    volumes:
+      - /tmp/test-convert:/tmp/test-convert
+    user: "1000:1000"
+    environment:
+      - HOME=/tmp
+    develop:
+      watch:
+        - action: rebuild
+          path: ./Dockerfile

package/docker/ubuntu.Dockerfile

@@ -0,0 +1,3 @@
+FROM ubuntu:24.04
+
+RUN apt-get update && apt-get install -y libreoffice-writer --no-install-recommends

package/examples/cloud-run/compose.yml

@@ -0,0 +1,5 @@
+services:
+  unoserver:
+    build: ./uno.Dockerfile
+  api: 
+    build: ./api.Dockerfile

package/examples/cloud-run/uno.Dockerfile

@@ -0,0 +1,9 @@
+FROM alpine:latest
+
+# install libreoffice + dependencies
+RUN apk add --no-cache libreoffice-writer python3 py3-pip openjdk11-jre-headless
+
+# install unoserver via pip
+RUN pip install unoserver --break-system-packages
+
+CMD ["unoserver"]

package/fixtures/test.txt

@@ -0,0 +1,7 @@
+Hi there
+
+This is a test file.
+
+This should be converted to PDF.
+
+Have fun!

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "effect-libreoffice",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "A effect based LibreOffice converter library",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "author": "Filip Weiss <me@fiws.net>",
+  "license": "ISC",
+  "homepage": "https://github.com/fiws/effect-libreoffice",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fiws/effect-libreoffice.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fiws/effect-libreoffice/issues"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "keywords": [],
+  "dependencies": {
+    "fast-xml-parser": "^5.3.3"
+  },
+  "peerDependencies": {
+    "@effect/platform": "^0.93.3",
+    "effect": "^3.19.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.10",
+    "@effect/language-service": "^0.62.4",
+    "@effect/platform": "^0.94.0",
+    "@effect/platform-node": "^0.104.0",
+    "@effect/vitest": "^0.27.0",
+    "effect": "^3.19.13",
+    "testcontainers": "^11.10.0",
+    "tinybench": "^6.0.0",
+    "tsdown": "^0.18.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "types": "./dist/index.d.mts",
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,126 @@
+import { FileSystem, Path } from "@effect/platform";
+import { NodeContext } from "@effect/platform-node";
+import { assert, expect, it } from "@effect/vitest";
+import { Effect, Layer, Predicate } from "effect";
+import { LibreOffice } from "./index";
+
+const TestLive = Layer.provideMerge(LibreOffice.Default, NodeContext.layer);
+
+it.layer(TestLive)("Libreoffice (Default)", (it) => {
+  it.scoped(
+    "should convert a file",
+    Effect.fn(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const libre = yield* LibreOffice;
+
+      const tempDir = yield* fs.makeTempDirectory();
+      const sourceFile = path.join(tempDir, "test.txt");
+      const targetFile = path.join(tempDir, "test.out.pdf");
+
+      yield* fs.writeFileString(sourceFile, "Hello PDF");
+      yield* libre.convertLocalFile(sourceFile, targetFile);
+
+      const targetContent = yield* fs.readFile(targetFile);
+
+      const header = new TextDecoder().decode(targetContent.slice(0, 4));
+      expect(header).toBe("%PDF");
+    }),
+  );
+
+  it.effect(
+    "should fails with source file not found",
+    Effect.fn(function* () {
+      const libre = yield* LibreOffice;
+      const result = yield* libre
+        .convertLocalFile("./fixtures/test-not-found.txt", "test.out.pdf")
+        .pipe(Effect.flip);
+
+      expect(result._tag).toBe("LibreOfficeError");
+
+      // assertion for type narrowing
+      assert(
+        Predicate.isTagged(result, "LibreOfficeError"),
+        "result is not LibreOfficeError",
+      );
+      expect(result.reason).toBe("InputFileNotFound");
+    }),
+  );
+
+  it.effect(
+    "Should work with 2 conversions in parallel",
+    Effect.fn(function* () {
+      const libre = yield* LibreOffice;
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+
+      const tempDir = yield* fs.makeTempDirectory();
+      const sourceFile = path.join(tempDir, "test.txt");
+      const targetFile = path.join(tempDir, "test.out.pdf");
+
+      yield* fs.writeFileString(sourceFile, "Hello PDF");
+
+      // will internaly use a semaphore to limit parallel conversions to 1
+      yield* Effect.all(
+        [
+          libre.convertLocalFile(sourceFile, targetFile),
+          libre.convertLocalFile(sourceFile, targetFile),
+        ],
+        { concurrency: "unbounded" },
+      );
+
+      const targetContent = yield* fs.readFile(targetFile);
+
+      const header = new TextDecoder().decode(targetContent.slice(0, 4));
+      expect(header).toBe("%PDF");
+    }),
+  );
+
+  it.effect(
+    "should fail with invalid output extension",
+    Effect.fn(function* () {
+      const libre = yield* LibreOffice;
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const tempDir = yield* fs.makeTempDirectory();
+      const sourceFile = path.join(tempDir, "test.txt");
+      const targetFile = path.join(tempDir, "test.invalidext");
+
+      yield* fs.writeFileString(sourceFile, "Hello PDF");
+
+      const result = yield* libre
+        .convertLocalFile(sourceFile, targetFile)
+        .pipe(Effect.flip);
+
+      assert(
+        Predicate.isTagged(result, "LibreOfficeError"),
+        "result is not LibreOfficeError",
+      );
+      expect(result.reason).toBe("BadOutputExtension");
+    }),
+  );
+
+  it.effect(
+    "should fail with output as directory",
+    Effect.fn(function* () {
+      const libre = yield* LibreOffice;
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const tempDir = yield* fs.makeTempDirectory();
+      const sourceFile = path.join(tempDir, "test.txt");
+      const targetFile = tempDir;
+
+      yield* fs.writeFileString(sourceFile, "Hello PDF");
+
+      const result = yield* libre
+        .convertLocalFile(sourceFile, targetFile)
+        .pipe(Effect.flip);
+
+      assert(
+        Predicate.isTagged(result, "LibreOfficeError"),
+        "result is not LibreOfficeError",
+      );
+      expect(result.reason).toBe("BadOutputExtension");
+    }),
+  );
+});

package/src/index.ts

@@ -0,0 +1,180 @@
+import { Command, FileSystem, Path } from "@effect/platform";
+import { Context, Effect, flow, Layer, Match, Stream, String } from "effect";
+import { LibreOfficeError, type OutputPath } from "./shared";
+import { UnoClient, UnoError } from "./uno/uno";
+
+const runString = <E, R>(
+  stream: Stream.Stream<Uint8Array, E, R>,
+): Effect.Effect<string, E, R> =>
+  stream.pipe(Stream.decodeText(), Stream.runFold(String.empty, String.concat));
+
+export class LibreOfficeCmd extends Context.Reference<LibreOfficeCmd>()(
+  "libre-convert-effect/index/LibreOfficeCmd",
+  { defaultValue: () => ["soffice", "--headless"] },
+) {}
+
+export class LibreOffice extends Effect.Service<LibreOffice>()(
+  "libre-convert-effect/index/LibreOffice",
+  {
+    // #region Default
+    scoped: Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const sem = yield* Effect.makeSemaphore(1);
+
+      return {
+        /**
+         * Converts a file to a different format.
+         *
+         * ### Example
+         *
+         * ```ts
+         * const program = Effect.gen(function* () {
+         *   const libre = yield* LibreOffice;
+         *   yield* libre.convertLocalFile("/path/to/input.docx", "/path/to/output.pdf");
+         * });
+         * ```
+         */
+        convertLocalFile: Effect.fn(function* (
+          input: string,
+          output: OutputPath,
+        ) {
+          const [cmd, ...args] = yield* LibreOfficeCmd;
+
+          const parsedInput = path.parse(input);
+          const parsedOutput = path.parse(output);
+
+          // to preserve compatiblity with unoserver we have to check if the output is a directory
+          if (
+            yield* fs.stat(output).pipe(
+              Effect.map((stat) => stat.type === "Directory"),
+              Effect.catchAll(() => Effect.succeed(false)),
+            )
+          ) {
+            return yield* Effect.fail(
+              new LibreOfficeError({
+                reason: "BadOutputExtension",
+                message: "Output path is a directory",
+              }),
+            );
+          }
+
+          // we need a temporary directory to ensure conversions do not conflict
+          const tempDir = yield* fs.makeTempDirectoryScoped({
+            prefix: "effect-libreoffice-",
+          });
+
+          // libreoffice does not do well with parallel conversions. It works if we provide
+          // a new "UserInstallation" for each conversion but this slows down execution by about 8x
+          // so we use a semaphore to limit parallel conversions to 1
+          yield* sem.withPermits(1)(
+            Effect.gen(function* () {
+              const process = yield* Command.make(
+                cmd,
+                ...args,
+                "--convert-to",
+                parsedOutput.ext.slice(1),
+                "--outdir",
+                tempDir,
+                input,
+              ).pipe(Command.start);
+              // We need to wait for the process to exit to get the exit code
+              // and capture stderr in parallel to avoid missing output
+              const [exitCode, result] = yield* Effect.all(
+                [process.exitCode, runString(process.stderr)],
+                { concurrency: "unbounded" },
+              );
+
+              // Check for specific errors in stderr first, regardless of exit code
+              yield* Match.value(String.trim(result)).pipe(
+                Match.when(
+                  String.includes("Error: source file could not be loaded"),
+                  () =>
+                    new LibreOfficeError({
+                      reason: "InputFileNotFound",
+                      message: result,
+                    }),
+                ),
+                Match.when(
+                  String.includes("Error: no export filter"),
+                  () =>
+                    new LibreOfficeError({
+                      reason: "BadOutputExtension",
+                      message: result,
+                    }),
+                ),
+                Match.when(
+                  String.includes("Permission denied"),
+                  () =>
+                    new LibreOfficeError({
+                      reason: "PermissionDenied",
+                      message: result,
+                    }),
+                ),
+                Match.when(
+                  String.includes("Error: "),
+                  () =>
+                    new LibreOfficeError({
+                      reason: "Unknown",
+                      message: result,
+                    }),
+                ),
+                Match.orElse(() => Effect.void),
+              );
+
+              if (exitCode !== 0) {
+                return yield* new LibreOfficeError({
+                  reason: "Unknown",
+                  message:
+                    result || `Process failed with exit code ${exitCode}`,
+                });
+              }
+
+              // using the libreoffice cli we can not specify the output file name
+              // it will be the input file name with the extension changed to the output format
+              const libreOutputPath = path.join(
+                tempDir,
+                String.concat(parsedInput.name, parsedOutput.ext),
+              );
+
+              // so we rename the file to the expected output path
+              yield* fs.copyFile(libreOutputPath, output);
+
+              // (temp directory is cleaned up by finalizer from makeTempDirectoryScoped)
+            }),
+          );
+        }, Effect.scoped),
+      };
+    }),
+    // #endregion
+  },
+) {
+  // #region Uno
+  /**
+   * The Uno layer uses a unoserver to convert files. It is much more
+   * performant than the cli but requires a unoserver to be running.
+   */
+  static Uno = Layer.scoped(
+    LibreOffice,
+    Effect.gen(function* () {
+      const client = yield* UnoClient;
+
+      return LibreOffice.make({
+        convertLocalFile: flow(
+          client.convert,
+          Effect.as(undefined),
+          Effect.mapError((err) =>
+            err instanceof UnoError
+              ? new LibreOfficeError(err)
+              : new LibreOfficeError({
+                  reason: "Unknown",
+                  message: `Failed to convert file: ${err}`,
+                  cause: err,
+                }),
+          ),
+        ),
+      });
+    }),
+  );
+  // #endregion
+}