beancount 0.1.0 → 0.2.0

package/README.md

@@ -14,7 +14,7 @@ npm install beancount
 
 - **Full Beancount Support** - All directives supported: transactions, open/close, balance, pad, note, document, price, event, query, custom, commodity, include, option, plugin, pushtag/poptag
 - **Full Transaction Support** - Tags, links, metadata, costs, price annotations, and postings
-- **Type-Safe** - Complete TypeScript types for all entries and components
+- **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
 - **Recursive File Parsing** - Option to automatically follow and merge `include` directives with circular reference protection
@@ -24,7 +24,7 @@ npm install beancount
 ## Quick Start
 
 ```typescript
-import { parse, ParseResult } from 'beancount'
+import { parse } from './main.mjs'
 
 const beancountContent = `
 2024-01-01 open Assets:Checking USD
@@ -36,22 +36,21 @@ const beancountContent = `
 
 const result = parse(beancountContent)
 
-// Access parsed entries
-console.log(result.entries.length) // 2
+// Access parsed directives
+console.log(result.nodes.length) // 5
+console.log(result.nodes)
 
-// Convert back to string
-console.log(result.toString())
+// Edit parsed directives
+result.transactions[0].narration = 'Trip to the supermarket'
+result.transactions[0].postings.forEach((p) => (p.currency = 'EUR'))
 
-// Convert to JSON
-const resultJSON = JSON.stringify(result)
-console.log(resultJSON)
-
-// 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
@@ -68,7 +67,7 @@ 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
 

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) { }

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

@@ -1,28 +1,28 @@
 import { Temporal } from '@js-temporal/polyfill';
-import { EntryType } from '../entryTypeToClass.mjs';
-import { Entry } from './Entry.mjs';
-import type { Transaction } from './entryTypes/Transaction/index.mjs';
-import type { Balance } from './entryTypes/Balance.mjs';
-import type { Close } from './entryTypes/Close.mjs';
-import type { Commodity } from './entryTypes/Commodity.mjs';
-import type { Custom } from './entryTypes/Custom.mjs';
-import type { Document } from './entryTypes/Document.mjs';
-import type { Event } from './entryTypes/Event.mjs';
-import type { Include } from './entryTypes/Include.mjs';
-import type { Note } from './entryTypes/Note.mjs';
-import type { Open } from './entryTypes/Open.mjs';
-import type { Option } from './entryTypes/Option.mjs';
-import type { Pad } from './entryTypes/Pad.mjs';
-import type { Plugin } from './entryTypes/Plugin.mjs';
-import type { Poptag } from './entryTypes/Poptag.mjs';
-import type { Price } from './entryTypes/Price.mjs';
-import type { Pushtag } from './entryTypes/Pushtag.mjs';
-import type { Query } from './entryTypes/Query.mjs';
-import type { Comment } from './entryTypes/Comment.mjs';
-import type { Blankline } from './entryTypes/Blankline.mjs';
+import { NodeType } from '../nodeTypeToClass.mjs';
+import { Node } from './Node.mjs';
+import type { Transaction } from './nodes/Transaction/index.mjs';
+import type { Balance } from './nodes/Balance.mjs';
+import type { Close } from './nodes/Close.mjs';
+import type { Commodity } from './nodes/Commodity.mjs';
+import type { Custom } from './nodes/Custom.mjs';
+import type { Document } from './nodes/Document.mjs';
+import type { Event } from './nodes/Event.mjs';
+import type { Include } from './nodes/Include.mjs';
+import type { Note } from './nodes/Note.mjs';
+import type { Open } from './nodes/Open.mjs';
+import type { Option } from './nodes/Option.mjs';
+import type { Pad } from './nodes/Pad.mjs';
+import type { Plugin } from './nodes/Plugin.mjs';
+import type { Poptag } from './nodes/Poptag.mjs';
+import type { Price } from './nodes/Price.mjs';
+import type { Pushtag } from './nodes/Pushtag.mjs';
+import type { Query } from './nodes/Query.mjs';
+import type { Comment } from './nodes/Comment.mjs';
+import type { Blankline } from './nodes/Blankline.mjs';
 export interface ParseResultObj {
-    entries: {
-        type: EntryType;
+    nodes: {
+        type: NodeType;
     }[];
 }
 /**
@@ -47,115 +47,115 @@ export interface CalculateCurrencyColumnOptions {
     minPadding?: number;
 }
 /**
- * Container class for parsed Beancount entries.
- * Provides methods for converting entries back to string format.
+ * Container class for the result of a parse.
+ * Provides methods for converting node back to string format.
  */
 export declare class ParseResult {
-    entries: Entry[];
+    nodes: Node[];
     /**
      * Creates a new ParseResult instance.
-     * @param entries - Array of parsed Entry objects
+     * @param nodes - Array of parsed nodes
      */
-    constructor(entries: Entry[]);
+    constructor(nodes: Node[]);
     /**
-     * Gets all transaction entries from the parsed entries.
-     * @returns Array of entries that are transactions
+     * Gets all transaction nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to transaction directives
      */
     get transactions(): Transaction[];
     /**
-     * Gets all balance entries from the parsed entries.
-     * @returns Array of entries that are balance directives
+     * Gets all balance nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to balance directives
      */
     get balance(): Balance[];
     /**
-     * Gets all close entries from the parsed entries.
-     * @returns Array of entries that are close directives
+     * Gets all close nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to close directives
      */
     get close(): Close[];
     /**
-     * Gets all commodity entries from the parsed entries.
-     * @returns Array of entries that are commodity directives
+     * Gets all commodity nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to commodity directives
      */
     get commodity(): Commodity[];
     /**
-     * Gets all custom entries from the parsed entries.
-     * @returns Array of entries that are custom directives
+     * Gets all custom nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to custom directives
      */
     get custom(): Custom[];
     /**
-     * Gets all document entries from the parsed entries.
-     * @returns Array of entries that are document directives
+     * Gets all document nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to document directives
      */
     get document(): Document[];
     /**
-     * Gets all event entries from the parsed entries.
-     * @returns Array of entries that are event directives
+     * Gets all event nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to event directives
      */
     get event(): Event[];
     /**
-     * Gets all include entries from the parsed entries.
-     * @returns Array of entries that are include directives
+     * Gets all include nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to include directives
      */
     get include(): Include[];
     /**
-     * Gets all note entries from the parsed entries.
-     * @returns Array of entries that are note directives
+     * Gets all note nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to note directives
      */
     get note(): Note[];
     /**
-     * Gets all open entries from the parsed entries.
-     * @returns Array of entries that are open directives
+     * Gets all open nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to open directives
      */
     get open(): Open[];
     /**
-     * Gets all option entries from the parsed entries.
-     * @returns Array of entries that are option directives
+     * Gets all option nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to option directives
      */
     get option(): Option[];
     /**
-     * Gets all pad entries from the parsed entries.
-     * @returns Array of entries that are pad directives
+     * Gets all pad nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to pad directives
      */
     get pad(): Pad[];
     /**
-     * Gets all plugin entries from the parsed entries.
-     * @returns Array of entries that are plugin directives
+     * Gets all plugin nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to plugin directives
      */
     get plugin(): Plugin[];
     /**
-     * Gets all poptag entries from the parsed entries.
-     * @returns Array of entries that are poptag directives
+     * Gets all poptag nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to poptag directives
      */
     get poptag(): Poptag[];
     /**
-     * Gets all price entries from the parsed entries.
-     * @returns Array of entries that are price directives
+     * Gets all price nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to price directives
      */
     get price(): Price[];
     /**
-     * Gets all pushtag entries from the parsed entries.
-     * @returns Array of entries that are pushtag directives
+     * Gets all pushtag nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to pushtag directives
      */
     get pushtag(): Pushtag[];
     /**
-     * Gets all query entries from the parsed entries.
-     * @returns Array of entries that are query directives
+     * Gets all query nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to query directives
      */
     get query(): Query[];
     /**
-     * Gets all comment entries from the parsed entries.
-     * @returns Array of entries that are comments
+     * Gets all comment nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to a comments
      */
     get comment(): Comment[];
     /**
-     * Gets all blankline entries from the parsed entries.
-     * @returns Array of entries that are blank lines
+     * Gets all blankline nodes from the parsed nodes.
+     * @returns Array of nodes that correspond to a blank line
      */
     get blankline(): Blankline[];
     /**
-     * Gets all unique account names used across all entries.
+     * Gets all unique account names used across all directives.
      * Extracts accounts from transactions (via postings), open, close,
-     * balance, pad, note, and document entries.
+     * balance, pad, note, and document nodes.
      * @returns Set of unique account names
      */
     get accounts(): Set<string>;
@@ -170,14 +170,14 @@ export declare class ParseResult {
      */
     accountsActiveAt(date: Temporal.PlainDate): Set<string>;
     /**
-     * Converts all entries to their string representation.
-     * Each entry is converted using its toString() method and joined with newlines.
+     * Converts all nodes to their string representation.
+     * Each node is converted using its toString() method and joined with newlines.
      * @returns The complete Beancount file content as a string
      */
     toString(): string;
     /**
-     * Converts all entries to a formatted string with aligned columns.
-     * Uses each entry's toFormattedString() method for consistent formatting.
+     * Converts all nodes to a formatted string with aligned columns.
+     * Uses each node's toFormattedString() method for consistent formatting.
      * @param formatOptions - Formatting options
      *
      * @returns The formatted Beancount file content as a string
@@ -194,11 +194,11 @@ export declare class ParseResult {
     static fromJSON(jsonString: string): ParseResult;
     /**
      * Creates a ParseResult instance from a plain JavaScript object.
-     * Deserializes each entry by mapping it to the appropriate Entry class based on its type.
+     * Deserializes each node by mapping it to the appropriate Node class based on its type.
      *
      * @param obj - Plain object representation of a ParseResult
-     * @returns A new ParseResult instance with deserialized entries
-     * @throws {Error} If an entry has an unknown type with no corresponding entry class
+     * @returns A new ParseResult instance with deserialized nodes
+     * @throws {Error} If an node has an unknown type with no corresponding node class
      * @remarks **Warning:** No validation is performed on the input object. We assume the object is valid and well-formed.
      */
     static fromJSONData(obj: ParseResultObj): ParseResult;