beancount 0.0.31 → 0.2.0

package/README.md

@@ -1,5 +1,7 @@
 # beancount
 
+[![CI](https://github.com/Boelensman1/node-beancount/actions/workflows/ci.yml/badge.svg)](https://github.com/Boelensman1/node-beancount/actions/workflows/ci.yml)
+
 A parser and editor for Beancount accounting files with full type safety.
 
 ## Installation
@@ -11,16 +13,18 @@ npm install beancount
 ## Features
 
 - **Full Beancount Support** - All directives supported: transactions, open/close, balance, pad, note, document, price, event, query, custom, commodity, include, option, plugin, pushtag/poptag
-- **Type-Safe** - Complete TypeScript types for all entries and components
-- **Rich Transaction Support** - Tags, links, metadata, costs, price annotations, and postings
+- **Full Transaction Support** - Tags, links, metadata, costs, price annotations, and postings
+- **Type-Safe** - Complete TypeScript types
+- **Platform Agnostic** - Works in Node.js, browsers, Deno, and other JavaScript runtimes
 - **Round-Trip Parsing** - Parse to objects and serialize back to text
-- **Formatted Output** - Column-aligned output with `toFormattedString()` and CLI formatter
+- **Recursive File Parsing** - Option to automatically follow and merge `include` directives with circular reference protection
+- **Formatted Output** - Column-aligned output with `toFormattedString()`
 - **CLI Formatter** - Command-line tool `beancount-format` for formatting files with auto-aligned columns
 
 ## Quick Start
 
 ```typescript
-import { parse, ParseResult } from 'beancount'
+import { parse } from './main.mjs'
 
 const beancountContent = `
 2024-01-01 open Assets:Checking USD
@@ -32,22 +36,21 @@ const beancountContent = `
 
 const result = parse(beancountContent)
 
-// Access parsed entries
-console.log(result.entries.length) // 2
-
-// Convert back to string
-console.log(result.toString())
+// Access parsed directives
+console.log(result.nodes.length) // 5
+console.log(result.nodes)
 
-// Convert to JSON
-const resultJSON = JSON.stringify(result)
-console.log(resultJSON)
+// Edit parsed directives
+result.transactions[0].narration = 'Trip to the supermarket'
+result.transactions[0].postings.forEach((p) => (p.currency = 'EUR'))
 
-// Convert back to parsed entries
-console.log(ParseResult.fromJSON(result))
-
-// Or with formatted output (aligned columns)
-// only partially implemented at this point
+// Output formatted
 console.log(result.toFormattedString())
+/* outputs:
+2024-01-15 * "Grocery Store" "Trip to the supermarket"
+  Assets:Checking                                  -50.00 EUR
+  Expenses:Food                                     50.00 EUR
+*/
 ```
 
 ## Parsing Files
@@ -64,7 +67,37 @@ const result = await parseFile('/path/to/ledger.beancount')
 const result = await parseFile('/path/to/main.beancount', { recurse: true })
 ```
 
-When `recurse: true`, the parser follows all `include` directives and merges the entries from included files into the result. Circular includes are handled gracefully (each file is only parsed once).
+When `recurse: true`, the parser follows all `include` directives and merges the directives from included files into the result. Circular includes are handled gracefully (each file is only parsed once).
+
+## Browser Usage
+
+The library works in browsers and other non-Node.js environments. The core `parse()` function works everywhere. For `parseFile()`, provide custom file system helpers:
+
+```typescript
+import { parseFile, type FileSystemHelpers } from 'beancount'
+
+const browserFS: FileSystemHelpers = {
+  readFile: async (path) => {
+    const response = await fetch(path)
+    return response.text()
+  },
+  resolvePath: (path) => new URL(path, window.location.origin).pathname,
+  resolveRelative: (base, rel) => {
+    const baseDir = base.substring(0, base.lastIndexOf('/') + 1)
+    return new URL(rel, window.location.origin + baseDir).pathname
+  },
+  dirname: (path) => path.substring(0, path.lastIndexOf('/')),
+}
+
+const result = await parseFile('/api/ledger.beancount', {
+  recurse: true,
+  fs: browserFS,
+})
+```
+
+## Documentation
+
+Full API documentation is available at https://Boelensman1.github.io/node-beancount/
 
 ## CLI Usage
 
@@ -102,10 +135,6 @@ beancount-format -w income.beancount expenses.beancount
 beancount-format --currency-column 60 ledger.beancount
 ```
 
-## Documentation
-
-Full API documentation is available at https://Boelensman1.github.io/node-beancount/
-
 ## Contributing
 
 This project uses Make for task orchestration. Common commands:

package/build/src/benchmark.mjs

@@ -25,4 +25,4 @@ console.log(`Average parse time: ${avgDuration.toFixed(3)} ms`);
 console.log(`Min: ${minDuration.toFixed(3)} ms, Max: ${maxDuration.toFixed(3)} ms`);
 console.log(`Average throughput: ${(fileSizeKB / avgDurationSeconds / 1000).toFixed(2)} MB/s`);
 console.log('---');
-console.log(`Parsed ${lastResult.entries.length} items`);
+console.log(`Parsed ${lastResult.nodes.length} items`);

package/build/src/classes/DatedNode.d.mts

@@ -0,0 +1,40 @@
+import { Temporal } from '@js-temporal/polyfill';
+import { Node } from './Node.mjs';
+import { Value } from './Value.mjs';
+import type { DatedDirectiveNodeType } from '../nodeTypeToClass.mjs';
+/**
+ * Abstract base class for all nodes that correspond to dated Beancount directives
+ * like transaction and open.
+ *
+ * Child classes must implement static `fromGenericParseResult` method
+ */
+export declare abstract class DatedNode extends Node {
+    /** The type of this dated node */
+    abstract type: DatedDirectiveNodeType;
+    /** The date of this node as a Temporal.PlainDate object */
+    date: Temporal.PlainDate;
+    /** Optional metadata key-value pairs associated with this node */
+    metadata?: Record<string, Value>;
+    /**
+     * Creates a new DatedNode instance.
+     * @param obj - Object containing node properties
+     * @param obj.date - The date string in YYYY-MM-DD format
+     */
+    constructor(obj: {
+        date: string | Temporal.PlainDate;
+        [key: string]: unknown;
+    });
+    /**
+     * Returns the common prefix for all DatedNode toString methods.
+     * Format: "YYYY-MM-DD <type>"
+     * @returns The formatted date and type prefix string
+     */
+    protected getDateTypePrefix(): string;
+    /**
+     * Converts metadata and comment to a formatted string.
+     * If metadata exists, each key-value pair is formatted on separate indented lines.
+     *
+     * @returns The formatted metadata and comment string, or empty string if neither exists
+     */
+    getMetaDataString(): string;
+}

package/build/src/classes/DatedNode.mjs

@@ -0,0 +1,61 @@
+import { Temporal } from '@js-temporal/polyfill';
+import { Node } from './Node.mjs';
+import { Value } from './Value.mjs';
+/**
+ * Abstract base class for all nodes that correspond to dated Beancount directives
+ * like transaction and open.
+ *
+ * Child classes must implement static `fromGenericParseResult` method
+ */
+export class DatedNode extends Node {
+    /**
+     * Creates a new DatedNode instance.
+     * @param obj - Object containing node properties
+     * @param obj.date - The date string in YYYY-MM-DD format
+     */
+    constructor(obj) {
+        const { date, metadata, ...props } = obj;
+        super(props);
+        if (date) {
+            if (date instanceof Temporal.PlainDate) {
+                this.date = date;
+            }
+            else if (typeof date === 'string') {
+                this.date = Temporal.PlainDate.from(date, { overflow: 'reject' });
+            }
+            else {
+                throw new Error('Could not parse date, should be either string of Temporal.PlainDate');
+            }
+        }
+        if (metadata) {
+            this.metadata = Object.fromEntries(Object.entries(metadata).map(([key, val]) => [
+                key,
+                new Value(val),
+            ]));
+        }
+    }
+    /**
+     * Returns the common prefix for all DatedNode toString methods.
+     * Format: "YYYY-MM-DD <type>"
+     * @returns The formatted date and type prefix string
+     */
+    getDateTypePrefix() {
+        return `${this.date.toJSON()} ${this.type}`;
+    }
+    /**
+     * Converts metadata and comment to a formatted string.
+     * If metadata exists, each key-value pair is formatted on separate indented lines.
+     *
+     * @returns The formatted metadata and comment string, or empty string if neither exists
+     */
+    getMetaDataString() {
+        const comment = this.comment ? ` ; ${this.comment}` : '';
+        if (!this.metadata) {
+            return comment;
+        }
+        return (`${comment}\n` +
+            Object.entries(this.metadata)
+                .map(([key, val]) => `  ${key}: ${val.toString()}`)
+                .join('\n'));
+    }
+}

package/build/src/classes/Node.d.mts

@@ -0,0 +1,92 @@
+import type { BeancountDirectiveNodeType } from '../nodeTypeToClass.mjs';
+import { genericParse } from '../genericParse.mjs';
+import { FormatOptions } from './ParseResult.mjs';
+/**
+ * Type helper for Node class constructors that enforce the static factory methods.
+ * Child classes must implement static fromGenericParseResult and fromObject methods to create instances.
+ * Note: The constructor is protected, so only the static factory methods are part of the public API.
+ */
+export interface NodeConstructor<T extends Node> {
+    /**
+     * Creates an Node instance from a generic parse result.
+     * @param parsedStart - The result from genericParse containing parsed node data
+     * @returns A new instance of the Node subclass
+     */
+    fromGenericParseResult(parsedStart: ReturnType<typeof genericParse>): T;
+}
+/**
+ * Abstract base class for all nodes.
+ *
+ * Child classes must implement static `fromGenericParseResult` method
+ */
+export declare abstract class Node {
+    /** Optional comment text associated with this node */
+    comment?: string;
+    /** Internal metadata key-value pairs associated with this node.
+     * These can be anything, are not used in the output, and are meant to be used
+     * to allow your pipeline to keep track of an internal property */
+    internalMetadata: Record<string, unknown>;
+    /** The type of this node (e.g., 'open', 'close', 'transaction', 'comment', 'blankline') */
+    abstract type: BeancountDirectiveNodeType | 'comment' | 'blankline';
+    /**
+     * Creates a new Node instance.
+     * @param obj - Object containing node properties
+     */
+    constructor(obj: Record<string, unknown>);
+    /**
+     * Creates an Node instance from a Beancount string.
+     * Parses the input string and constructs the appropriate Node subclass.
+     *
+     * @param input - A single unparsed node as a string
+     * @returns A new instance of the Node subclass
+     */
+    static fromString<T extends Node>(this: NodeConstructor<T>, input: string): T;
+    /**
+     * Creates an Node instance from JSON data.
+     * Calls fromJSONData to allow subclasses to transform the data before construction.
+     *
+     * @param jsonString - JSON data representing an node
+     * @returns A new instance of the Node subclass
+     * @remarks **Warning:** No validation is performed on the JSON input. We assume the JSON is valid and well-formed.
+     */
+    static fromJSON<T extends Node>(this: new (obj: any) => T, jsonString: string): T;
+    /**
+     * Creates an Node instance from JSON data.
+     * Calls fromJSONData to allow subclasses to transform the data before construction.
+     *
+     * @param jsonData - object representing an node
+     * @returns A new instance of the Node subclass
+     * @remarks **Warning:** No validation is performed on the input. We assume the input is valid and well-formed.
+     */
+    static fromJSONData<T extends Node>(this: new (obj: any) => T, jsonData: Record<string, unknown>): T;
+    /**
+     * Converts this node to a formatted string with aligned columns.
+     * Default implementation delegates to toString(). Subclasses can override for custom formatting.
+     *
+     * @param _formatOptions - Formatting options (unused in base implementation)
+     * @returns The formatted string representation of this node
+     */
+    toFormattedString(_formatOptions?: FormatOptions): string;
+    /**
+     * Transforms JSON data before creating an Node instance.
+     * Default implementation returns the input unchanged.
+     * Subclasses can override this to handle custom deserialization logic
+     * (e.g., converting nested objects, handling dates, etc.).
+     *
+     * @param json - The JSON data to transform
+     * @returns The transformed data ready for the constructor
+     */
+    protected parseJSONData(json: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Converts an node to a JSON-serializable object.
+     * @returns A JSON-serializable representation of this node
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Type assertion helper to ensure a class conforms to NodeConstructor.
+ * Usage: assertNodeConstructor(MyNodeClass)
+ * @param _ctor - The constructor to validate (unused at runtime)
+ * @internal
+ */
+export declare function assertNodeConstructor<T extends Node>(_ctor: NodeConstructor<T>): void;

package/build/src/classes/Node.mjs

@@ -0,0 +1,107 @@
+import { genericParse } from '../genericParse.mjs';
+import { stringAwareSplitLine } from '../utils/stringAwareSplitLine.mjs';
+import { defaultFormatOptions } from './ParseResult.mjs';
+/**
+ * Abstract base class for all nodes.
+ *
+ * Child classes must implement static `fromGenericParseResult` method
+ */
+export class Node {
+    /**
+     * Creates a new Node instance.
+     * @param obj - Object containing node properties
+     */
+    constructor(obj) {
+        /** Internal metadata key-value pairs associated with this node.
+         * These can be anything, are not used in the output, and are meant to be used
+         * to allow your pipeline to keep track of an internal property */
+        this.internalMetadata = {};
+        Object.assign(this, obj);
+    }
+    /**
+     * Creates an Node instance from a Beancount string.
+     * Parses the input string and constructs the appropriate Node subclass.
+     *
+     * @param input - A single unparsed node as a string
+     * @returns A new instance of the Node subclass
+     */
+    static fromString(input) {
+        const sourceFragment = stringAwareSplitLine(input);
+        const genericParseResult = genericParse(sourceFragment);
+        const result = this.fromGenericParseResult(genericParseResult);
+        if (result.type !== genericParseResult.type) {
+            console.warn('Parse result type is not equal to requested object type, make sure the correct class is initiated');
+        }
+        return result;
+    }
+    /**
+     * Creates an Node instance from JSON data.
+     * Calls fromJSONData to allow subclasses to transform the data before construction.
+     *
+     * @param jsonString - JSON data representing an node
+     * @returns A new instance of the Node subclass
+     * @remarks **Warning:** No validation is performed on the JSON input. We assume the JSON is valid and well-formed.
+     */
+    static fromJSON(jsonString) {
+        const json = JSON.parse(jsonString);
+        // @ts-expect-error Not sure how to type this correctly
+        return this.fromJSONData(json); // eslint-disable-line
+    }
+    /**
+     * Creates an Node instance from JSON data.
+     * Calls fromJSONData to allow subclasses to transform the data before construction.
+     *
+     * @param jsonData - object representing an node
+     * @returns A new instance of the Node subclass
+     * @remarks **Warning:** No validation is performed on the input. We assume the input is valid and well-formed.
+     */
+    static fromJSONData(jsonData) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const instance = new this({});
+        const transformedData = instance.parseJSONData(jsonData);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return new this(transformedData);
+    }
+    /**
+     * Converts this node to a formatted string with aligned columns.
+     * Default implementation delegates to toString(). Subclasses can override for custom formatting.
+     *
+     * @param _formatOptions - Formatting options (unused in base implementation)
+     * @returns The formatted string representation of this node
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    toFormattedString(_formatOptions = defaultFormatOptions) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string
+        return this.toString();
+    }
+    /**
+     * Transforms JSON data before creating an Node instance.
+     * Default implementation returns the input unchanged.
+     * Subclasses can override this to handle custom deserialization logic
+     * (e.g., converting nested objects, handling dates, etc.).
+     *
+     * @param json - The JSON data to transform
+     * @returns The transformed data ready for the constructor
+     */
+    parseJSONData(json) {
+        return json;
+    }
+    /**
+     * Converts an node to a JSON-serializable object.
+     * @returns A JSON-serializable representation of this node
+     */
+    toJSON() {
+        return {
+            ...this,
+        };
+    }
+}
+/**
+ * Type assertion helper to ensure a class conforms to NodeConstructor.
+ * Usage: assertNodeConstructor(MyNodeClass)
+ * @param _ctor - The constructor to validate (unused at runtime)
+ * @internal
+ */
+export function assertNodeConstructor(
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_ctor) { }