@f-o-t/ofx 1.2.1 → 2.0.0

package/README.md

@@ -123,6 +123,112 @@ console.log({
 });
 ```
 
+### Generation Functions
+
+#### `generateBankStatement(options: GenerateBankStatementOptions): string`
+
+Generates a complete OFX bank statement file.
+
+```typescript
+import { generateBankStatement } from "@fot/ofx";
+
+const statement = generateBankStatement({
+  bankId: "123456",
+  accountId: "987654321",
+  accountType: "CHECKING",
+  currency: "USD",
+  startDate: new Date("2025-01-01"),
+  endDate: new Date("2025-01-31"),
+  transactions: [
+    {
+      type: "CREDIT",
+      datePosted: new Date(),
+      amount: 1000,
+      fitId: "1",
+      name: "Deposit",
+    },
+  ],
+});
+
+console.log(statement);
+```
+
+#### `generateCreditCardStatement(options: GenerateCreditCardStatementOptions): string`
+
+Generates a complete OFX credit card statement file.
+
+```typescript
+import { generateCreditCardStatement } from "@fot/ofx";
+
+const statement = generateCreditCardStatement({
+  accountId: "123456789",
+  currency: "USD",
+  startDate: new Date("2025-01-01"),
+  endDate: new Date("2025-01-31"),
+  transactions: [
+    {
+      type: "DEBIT",
+      datePosted: new Date(),
+      amount: -75.5,
+      fitId: "2",
+      name: "Purchase at a store",
+    },
+  ],
+});
+
+console.log(statement);
+```
+
+### Streaming Functions
+
+For processing large OFX files with low memory footprint.
+
+#### `parseStream(input): AsyncGenerator<StreamEvent>`
+
+Parses an OFX file as a stream, yielding events as they are parsed.
+
+```typescript
+import { parseStream } from "@fot/ofx";
+
+// From a ReadableStream (e.g., fetch response)
+const response = await fetch("https://example.com/statement.ofx");
+for await (const event of parseStream(response.body)) {
+  switch (event.type) {
+    case "header":
+      console.log("OFX Version:", event.data.VERSION);
+      break;
+    case "account":
+      console.log("Account:", event.data.ACCTID);
+      break;
+    case "transaction":
+      console.log("Transaction:", event.data.NAME, event.data.TRNAMT);
+      break;
+    case "balance":
+      console.log("Ledger Balance:", event.data.ledger?.BALAMT);
+      break;
+    case "complete":
+      console.log("Total transactions:", event.transactionCount);
+      break;
+  }
+}
+```
+
+#### `parseStreamToArray(input): Promise<StreamResult>`
+
+Collects all stream events into arrays for easier processing.
+
+```typescript
+import { parseStreamToArray } from "@fot/ofx";
+
+const response = await fetch("https://example.com/statement.ofx");
+const result = await parseStreamToArray(response.body);
+
+console.log("Header:", result.header);
+console.log("Transactions:", result.transactions.length);
+console.log("Accounts:", result.accounts);
+console.log("Balances:", result.balances);
+```
+
 ## Types
 
 ### OFXTransaction
@@ -227,6 +333,17 @@ interface BalanceInfo {
 }
 ```
 
+### StreamEvent
+
+```typescript
+type StreamEvent =
+  | { type: "header"; data: OFXHeader }
+  | { type: "transaction"; data: OFXTransaction }
+  | { type: "account"; data: OFXBankAccount | OFXCreditCardAccount }
+  | { type: "balance"; data: { ledger?: OFXBalance; available?: OFXBalance } }
+  | { type: "complete"; transactionCount: number };
+```
+
 ## Schemas
 
 All Zod schemas are exported for custom validation:
@@ -264,13 +381,17 @@ Tested on realistic business statement sizes:
 
 | Transactions | File Size | Parse Time |
 | ------------ | --------- | ---------- |
-| ~10,000      | 2.5 MB    | ~800ms     |
-| ~25,000      | 5.4 MB    | ~1.3s      |
-| ~50,000      | 10.4 MB   | ~4.3s      |
-| ~100,000     | 20.5 MB   | ~27s       |
+| ~5,000       | 1.2 MB    | ~37ms      |
+| ~10,000      | 2.5 MB    | ~108ms     |
+| ~25,000      | 5.4 MB    | ~230ms     |
+| ~50,000      | 10.4 MB   | ~450ms     |
 
 Extraction operations (`getTransactions`, `getBalance`, etc.) are sub-millisecond even on large datasets.
 
+### Streaming Performance
+
+The streaming API achieves ~55,000-66,000 transactions/sec throughput with minimal memory overhead, making it ideal for processing very large files or network streams.
+
 ## License
 
 MIT