readpst 0.1.0 → 0.2.1

package/README.md

@@ -9,9 +9,10 @@ The `readpst` binary must be on your `PATH`:
 ```sh
 brew install libpst      # macOS
 apt install pst-utils    # Debian/Ubuntu
-apk add libpst           # Alpine
 ```
 
+Alpine has no libpst package; build it from [source](https://www.five-ten-sg.com/libpst/) with `libgsf-dev` installed and `CFLAGS="-std=gnu17"` (GCC 15 rejects its pre-C23 declarations).
+
 ```sh
 npm install readpst
 ```
@@ -25,17 +26,35 @@ const files = await extract("mailbox.pst", { outDir: "out" });
 // ["/abs/out/Inbox/1.eml", "/abs/out/Sent Items/1.eml", ...]
 ```
 
-`outDir` mirrors the PST's folder tree, with one RFC 822 `.eml` per message and attachments kept inline as MIME parts. Text is written as UTF-8.
+### Without managing files
+
+`read` extracts into a temp dir, yields each item and removes the dir when the loop ends (also on `break` or a thrown error):
+
+```js
+import { read } from "readpst";
+
+for await (const item of read("mailbox.pst")) {
+  item.path;             // "Inbox/1.eml"
+  await item.buffer();   // Buffer
+  item.stream();         // fs.ReadStream, e.g. to upload to S3
+}
+```
+
+Consume each item's buffer or stream before moving to the next one; the files are gone once the loop finishes.
+
+### Writing to a directory
+
+`extract` writes to a directory you own and returns the file paths. `outDir` mirrors the PST's folder tree, with one RFC 822 `.eml` per message and attachments kept inline as MIME parts. Text is written as UTF-8.
 
 ### Options
 
 | Option        | Default       | Description                                                       |
 | ------------- | ------------- | ----------------------------------------------------------------- |
-| `outDir`      | (required)    | Output directory, created if missing                              |
+| `outDir`      | (required)    | `extract` only: output directory, created if missing              |
 | `types`       | `["email"]`   | Any of `"email"`, `"appointment"`, `"journal"`, `"contact"`       |
 | `readpstPath` | `"readpst"`   | Path to the binary                                                |
 
-`readpst` needs a seekable file on local disk, so download a remote PST to a temp file first. Cleaning up `outDir` is up to you.
+`readpst` needs a seekable file on local disk, so download a remote PST to a temp file first. With `extract`, cleaning up `outDir` is up to you.
 
 ## License
 

package/index.d.ts

@@ -11,3 +11,16 @@ export interface ExtractOptions {
 
 /** Converts a .pst/.ost into one .eml per item and resolves to the absolute paths of the written files. */
 export function extract(pstPath: string, options: ExtractOptions): Promise<string[]>;
+
+export interface PstItem {
+  /** Path relative to the PST root, e.g. "Inbox/1.eml". */
+  path: string;
+  buffer(): Promise<Buffer>;
+  stream(): import("node:fs").ReadStream;
+}
+
+/**
+ * Extracts into a temp dir and yields each item; the dir is removed when the loop ends, breaks or throws.
+ * Read an item's buffer or stream before moving to the next one.
+ */
+export function read(pstPath: string, options?: Omit<ExtractOptions, "outDir">): AsyncGenerator<PstItem, void, undefined>;

package/index.js

@@ -1,6 +1,8 @@
 import { execFile } from "node:child_process";
-import { mkdir, readdir } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { createReadStream } from "node:fs";
+import { mkdir, mkdtemp, readFile, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
 import { promisify } from "node:util";
 
 const run = promisify(execFile);
@@ -21,7 +23,7 @@ export async function extract(pstPath, { outDir, types = ["email"], readpstPath
   } catch (error) {
     if (error.code === "ENOENT") {
       throw new Error(
-        `"${readpstPath}" not found. Install libpst: brew install libpst, apt install pst-utils or apk add libpst`
+        `"${readpstPath}" not found. Install libpst: brew install libpst or apt install pst-utils`
       );
     }
     throw new Error(`readpst failed: ${(error.stderr || error.stdout)?.trim() || error.message}`, { cause: error });
@@ -30,3 +32,14 @@ export async function extract(pstPath, { outDir, types = ["email"], readpstPath
   const entries = await readdir(dir, { recursive: true, withFileTypes: true });
   return entries.filter((entry) => entry.isFile()).map((entry) => join(entry.parentPath, entry.name));
 }
+
+export async function* read(pstPath, options = {}) {
+  const dir = await mkdtemp(join(tmpdir(), "readpst-"));
+  try {
+    for (const file of await extract(pstPath, { ...options, outDir: dir })) {
+      yield { path: relative(dir, file), buffer: () => readFile(file), stream: () => createReadStream(file) };
+    }
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "readpst",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Convert Outlook .pst files to .eml files with libpst's readpst",
   "keywords": ["pst", "ost", "outlook", "eml", "email", "readpst", "libpst"],
   "author": "Philip van Burleigh",