beancount 0.0.31 → 0.2.0

package/build/src/main.mjs

@@ -3,7 +3,7 @@
  *
  * @remarks
  * The primary function you'll use is {@link parse}, which parses a complete Beancount file
- * and returns a {@link ParseResult} containing all parsed entries.
+ * and returns a {@link ParseResult} containing parsed nodes.
  *
  * @example
  * ```typescript
@@ -17,42 +17,42 @@
  * `
  *
  * const result = parse(beancountContent)
- * console.log(result.entries) // Array of parsed Entry objects
+ * console.log(result.nodes) // Array of parsed Node objects
  * ```
  *
  * @module
  */
 // Primary parsing functionality
-export { parse, parseEntry } from './parse.mjs';
-export { deserializeEntry, deserializeEntryFromString, deserializeEntries, deserializeEntriesFromString, } from './deserialize.mjs';
+export { parse, parseSourceFragment } from './parse.mjs';
+export { deserializeNode, deserializeNodeFromString, deserializeNodes, deserializeNodesFromString, } from './deserialize.mjs';
 export { parseFile, } from './parseFile.mjs';
 // Core classes
 export { ParseResult, } from './classes/ParseResult.mjs';
-export { Entry, assertEntryConstructor } from './classes/Entry.mjs';
-export { DateEntry } from './classes/DateEntry.mjs';
+export { Node, assertNodeConstructor } from './classes/Node.mjs';
+export { DatedNode } from './classes/DatedNode.mjs';
 export { Value } from './classes/Value.mjs';
-// Entry type classes
-export { Balance } from './classes/entryTypes/Balance.mjs';
-export { Blankline } from './classes/entryTypes/Blankline.mjs';
-export { Close } from './classes/entryTypes/Close.mjs';
-export { Comment } from './classes/entryTypes/Comment.mjs';
-export { Commodity } from './classes/entryTypes/Commodity.mjs';
-export { Custom } from './classes/entryTypes/Custom.mjs';
-export { Document } from './classes/entryTypes/Document.mjs';
-export { Event } from './classes/entryTypes/Event.mjs';
-export { Include } from './classes/entryTypes/Include.mjs';
-export { Note } from './classes/entryTypes/Note.mjs';
-export { Open } from './classes/entryTypes/Open.mjs';
-export { Option } from './classes/entryTypes/Option.mjs';
-export { Pad } from './classes/entryTypes/Pad.mjs';
-export { Plugin } from './classes/entryTypes/Plugin.mjs';
-export { Poptag } from './classes/entryTypes/Poptag.mjs';
-export { Price } from './classes/entryTypes/Price.mjs';
-export { Pushtag } from './classes/entryTypes/Pushtag.mjs';
-export { Query } from './classes/entryTypes/Query.mjs';
-export { Transaction, } from './classes/entryTypes/Transaction/index.mjs';
+// Node classes
+export { Balance } from './classes/nodes/Balance.mjs';
+export { Blankline } from './classes/nodes/Blankline.mjs';
+export { Close } from './classes/nodes/Close.mjs';
+export { Comment } from './classes/nodes/Comment.mjs';
+export { Commodity } from './classes/nodes/Commodity.mjs';
+export { Custom } from './classes/nodes/Custom.mjs';
+export { Document } from './classes/nodes/Document.mjs';
+export { Event } from './classes/nodes/Event.mjs';
+export { Include } from './classes/nodes/Include.mjs';
+export { Note } from './classes/nodes/Note.mjs';
+export { Open } from './classes/nodes/Open.mjs';
+export { Option } from './classes/nodes/Option.mjs';
+export { Pad } from './classes/nodes/Pad.mjs';
+export { Plugin } from './classes/nodes/Plugin.mjs';
+export { Poptag } from './classes/nodes/Poptag.mjs';
+export { Price } from './classes/nodes/Price.mjs';
+export { Pushtag } from './classes/nodes/Pushtag.mjs';
+export { Query } from './classes/nodes/Query.mjs';
+export { Transaction, } from './classes/nodes/Transaction/index.mjs';
 // Transaction sub-components
-export { Posting } from './classes/entryTypes/Transaction/Posting.mjs';
-export { Tag } from './classes/entryTypes/Transaction/Tag.mjs';
-export { beancountEntryToClass, entryTypeToClass } from './entryTypeToClass.mjs';
-export { DATED_ENTRY_TYPES, NON_DATED_ENTRY_TYPES } from './entryTypes.mjs';
+export { Posting } from './classes/nodes/Transaction/Posting.mjs';
+export { Tag } from './classes/nodes/Transaction/Tag.mjs';
+export { beancountDirectiveNodeTypeToClass, nodeTypeToClass, } from './nodeTypeToClass.mjs';
+export { DATED_DIRECTIVE_TYPES, NON_DATED_DIRECTIVE_TYPES, } from './directiveTypes.mjs';

package/build/src/nodeTypeToClass.d.mts

@@ -0,0 +1,81 @@
+import { Transaction, Balance, Close, Comment, Commodity, Custom, Document, Event, Include, Note, Open, Option, Pad, Plugin, Poptag, Price, Pushtag, Query, Blankline } from './classes/nodes/index.mjs';
+import type { DATED_DIRECTIVE_TYPES, NON_DATED_DIRECTIVE_TYPES } from './directiveTypes.mjs';
+/**
+ * Union type of all node types that correspond to a Beancount directive that includes a date field.
+ * Derived from {@link DATED_DIRECTIVE_TYPES}.
+ */
+export type DatedDirectiveNodeType = (typeof DATED_DIRECTIVE_TYPES)[number];
+/**
+ * Union type of all node types that correspond to a Beancount directive type that does NOT include
+ * a date field.
+ * Derived from {@link NON_DATED_DIRECTIVE_TYPES}.
+ */
+export type NonDatedDirectiveNodeType = (typeof NON_DATED_DIRECTIVE_TYPES)[number];
+/**
+ * Union type of all node type that corrospond to Beancount directives.
+ * Directive types derived from https://beancount.github.io/docs/beancount_language_syntax.html#directives-1
+ * Node can have additional synthetic types, see {@link SyntheticNodeType}
+ *
+ * Derived from {@link DATED_DIRECTIVE_TYPES} and {@link NON_DATED_DIRECTIVE_TYPES}.
+ */
+export type BeancountDirectiveNodeType = DatedDirectiveNodeType | NonDatedDirectiveNodeType;
+/**
+ * Union type of synthetic node types that are not part of the official Beancount directive syntax.
+ *
+ * These node types are created during parsing to preserve the complete structure of a Beancount file,
+ * enabling lossless round-trip parsing
+ */
+export type SyntheticNodeType = 'comment' | 'blankline';
+/**
+ * Union type of all valid node type names, that being the beancount directive types and the additional
+ * synthetic node types of comment and blankline
+ */
+export type NodeType = BeancountDirectiveNodeType | SyntheticNodeType;
+/**
+ * Mapping of Beancount directive node type names to their corresponding class constructors.
+ * @internal
+ */
+export declare const beancountDirectiveNodeTypeToClass: {
+    transaction: typeof Transaction;
+    balance: typeof Balance;
+    close: typeof Close;
+    commodity: typeof Commodity;
+    custom: typeof Custom;
+    document: typeof Document;
+    event: typeof Event;
+    include: typeof Include;
+    note: typeof Note;
+    open: typeof Open;
+    option: typeof Option;
+    pad: typeof Pad;
+    plugin: typeof Plugin;
+    poptag: typeof Poptag;
+    price: typeof Price;
+    pushtag: typeof Pushtag;
+    query: typeof Query;
+};
+/**
+ * Mapping of all node type names (including synthetic) to their corresponding class constructors.
+ * @internal
+ */
+export declare const nodeTypeToClass: {
+    comment: typeof Comment;
+    blankline: typeof Blankline;
+    transaction: typeof Transaction;
+    balance: typeof Balance;
+    close: typeof Close;
+    commodity: typeof Commodity;
+    custom: typeof Custom;
+    document: typeof Document;
+    event: typeof Event;
+    include: typeof Include;
+    note: typeof Note;
+    open: typeof Open;
+    option: typeof Option;
+    pad: typeof Pad;
+    plugin: typeof Plugin;
+    poptag: typeof Poptag;
+    price: typeof Price;
+    pushtag: typeof Pushtag;
+    query: typeof Query;
+};

package/build/src/nodeTypeToClass.mjs

@@ -0,0 +1,37 @@
+import { Transaction, Balance, Close, Comment, Commodity, Custom, Document, Event, Include, Note, Open, Option, Pad, Plugin, Poptag, Price, Pushtag, Query, Blankline, } from './classes/nodes/index.mjs';
+/**
+ * Mapping of Beancount directive node type names to their corresponding class constructors.
+ * @internal
+ */
+export const beancountDirectiveNodeTypeToClass = {
+    transaction: Transaction,
+    balance: Balance,
+    close: Close,
+    commodity: Commodity,
+    custom: Custom,
+    document: Document,
+    event: Event,
+    include: Include,
+    note: Note,
+    open: Open,
+    option: Option,
+    pad: Pad,
+    plugin: Plugin,
+    poptag: Poptag,
+    price: Price,
+    pushtag: Pushtag,
+    query: Query,
+};
+// Compile-time assertion: beancountDirectiveNodeTypeToClass must have all BeancountDirectiveNodeType keys
+beancountDirectiveNodeTypeToClass;
+/**
+ * Mapping of all node type names (including synthetic) to their corresponding class constructors.
+ * @internal
+ */
+export const nodeTypeToClass = {
+    ...beancountDirectiveNodeTypeToClass,
+    comment: Comment,
+    blankline: Blankline,
+};
+// Compile-time assertion: nodeTypeToClass must have all NodeType keys
+nodeTypeToClass;

package/build/src/parse.d.mts

@@ -1,29 +1,29 @@
 import { ParseResult } from './classes/ParseResult.mjs';
-import { Comment, Blankline } from './classes/entryTypes/index.mjs';
+import { Comment, Blankline } from './classes/nodes/index.mjs';
 /**
- * Parses a single unparsed entry into its corresponding Entry class instance.
+ * Parses a single source fragment into its corresponding Node class instance.
  *
  * This function:
- * - Performs generic parsing to determine entry type
- * - Instantiates the appropriate Entry subclass
+ * - Performs generic parsing to determine node type
+ * - Instantiates the appropriate Node subclass
  * - Handles special cases for comments and blank lines
  *
- * @param unparsedEntry - Array of string tokens representing a single entry
- * @returns An Entry instance
+ * @param sourceFragment - Array of string tokens that should be parsed to a single node
+ * @returns A Node instance
  */
-export declare const parseEntry: (unparsedEntry: string[]) => import("./classes/entryTypes/index.mjs").Transaction | import("./classes/entryTypes/Balance.mjs").Balance | import("./classes/entryTypes/Close.mjs").Close | import("./classes/entryTypes/Commodity.mjs").Commodity | import("./classes/entryTypes/Custom.mjs").Custom | import("./classes/entryTypes/Document.mjs").Document | import("./classes/entryTypes/Event.mjs").Event | import("./classes/entryTypes/Include.mjs").Include | import("./classes/entryTypes/Note.mjs").Note | import("./classes/entryTypes/Open.mjs").Open | import("./classes/entryTypes/Option.mjs").Option | import("./classes/entryTypes/Pad.mjs").Pad | import("./classes/entryTypes/Plugin.mjs").Plugin | import("./classes/entryTypes/Poptag.mjs").Poptag | import("./classes/entryTypes/Price.mjs").Price | import("./classes/entryTypes/Pushtag.mjs").Pushtag | import("./classes/entryTypes/Query.mjs").Query | Comment | Blankline;
+export declare const parseSourceFragment: (sourceFragment: string[]) => import("./classes/nodes/index.mjs").Transaction | import("./classes/nodes/Balance.mjs").Balance | import("./classes/nodes/Close.mjs").Close | import("./classes/nodes/Commodity.mjs").Commodity | import("./classes/nodes/Custom.mjs").Custom | import("./classes/nodes/Document.mjs").Document | import("./classes/nodes/Event.mjs").Event | import("./classes/nodes/Include.mjs").Include | import("./classes/nodes/Note.mjs").Note | import("./classes/nodes/Open.mjs").Open | import("./classes/nodes/Option.mjs").Option | import("./classes/nodes/Pad.mjs").Pad | import("./classes/nodes/Plugin.mjs").Plugin | import("./classes/nodes/Poptag.mjs").Poptag | import("./classes/nodes/Price.mjs").Price | import("./classes/nodes/Pushtag.mjs").Pushtag | import("./classes/nodes/Query.mjs").Query | Comment | Blankline;
 /**
- * Parses a complete Beancount file string into a ParseResult containing Entry objects.
+ * Parses a complete Beancount file string into a ParseResult containing Node objects.
  *
  * This is the main entry point for parsing Beancount files. It handles:
- * - Splitting the input into individual entries
- * - Parsing each entry into its appropriate type
- * - Managing the tag stack for pushtag/poptag directives
+ * - Splitting the source into source fragment
+ * - Parsing each source fragment into its appropriate node
+ * - Managing the tag stack for pushtag/poptag nodes
  * - Applying tags from the stack to transactions
  *
  * @remarks
  * This is the primary function you'll use from this library. It takes a Beancount file
- * as a string and returns a structured ParseResult object containing all parsed entries.
+ * as a string and returns a structured ParseResult object containing the resulting parsed nodes.
  *
  * @example
  * Basic usage:
@@ -38,10 +38,10 @@ export declare const parseEntry: (unparsedEntry: string[]) => import("./classes/
  * `
  *
  * const result = parse(content)
- * // result.entries contains parsed Entry objects
+ * // result.nodes contains parsed Node objects
  * ```
  *
- * @param input - The complete Beancount file content as a string
- * @returns A ParseResult instance containing all parsed entries
+ * @param source - The complete Beancount file content as a string
+ * @returns A ParseResult instance containing all parsed nodes
  */
-export declare const parse: (input: string) => ParseResult;
+export declare const parse: (source: string) => ParseResult;

package/build/src/parse.mjs

@@ -1,23 +1,23 @@
 import { ParseResult } from './classes/ParseResult.mjs';
-import { Comment, Blankline } from './classes/entryTypes/index.mjs';
+import { Comment, Blankline } from './classes/nodes/index.mjs';
 import { genericParse, } from './genericParse.mjs';
-import { beancountEntryToClass, } from './entryTypeToClass.mjs';
-import { splitStringIntoUnparsedEntries } from './utils/splitStringIntoUnparsedEntries.js';
+import { beancountDirectiveNodeTypeToClass, } from './nodeTypeToClass.mjs';
+import { splitStringIntoSourceFragments } from './utils/splitStringIntoSourceFragments.js';
 /**
- * Parses a single unparsed entry into its corresponding Entry class instance.
+ * Parses a single source fragment into its corresponding Node class instance.
  *
  * This function:
- * - Performs generic parsing to determine entry type
- * - Instantiates the appropriate Entry subclass
+ * - Performs generic parsing to determine node type
+ * - Instantiates the appropriate Node subclass
  * - Handles special cases for comments and blank lines
  *
- * @param unparsedEntry - Array of string tokens representing a single entry
- * @returns An Entry instance
+ * @param sourceFragment - Array of string tokens that should be parsed to a single node
+ * @returns A Node instance
  */
-export const parseEntry = (unparsedEntry) => {
-    const genericParseResult = genericParse(unparsedEntry);
+export const parseSourceFragment = (sourceFragment) => {
+    const genericParseResult = genericParse(sourceFragment);
     const { type } = genericParseResult;
-    if (genericParseResult.fake) {
+    if (genericParseResult.synthetic) {
         if (type === 'blankline') {
             return Blankline.fromGenericParseResult(genericParseResult);
         }
@@ -25,26 +25,26 @@ export const parseEntry = (unparsedEntry) => {
             return Comment.fromGenericParseResult(genericParseResult);
         }
     }
-    const EntryClass = beancountEntryToClass[type];
-    if (EntryClass) {
-        return EntryClass.fromGenericParseResult(genericParseResult);
+    const NodeClass = beancountDirectiveNodeTypeToClass[type];
+    if (NodeClass) {
+        return NodeClass.fromGenericParseResult(genericParseResult);
     }
     else {
-        throw Error(`Could not parse ${unparsedEntry.toString()}`);
+        throw Error(`Could not parse ${sourceFragment.toString()}`);
     }
 };
 /**
- * Parses a complete Beancount file string into a ParseResult containing Entry objects.
+ * Parses a complete Beancount file string into a ParseResult containing Node objects.
  *
  * This is the main entry point for parsing Beancount files. It handles:
- * - Splitting the input into individual entries
- * - Parsing each entry into its appropriate type
- * - Managing the tag stack for pushtag/poptag directives
+ * - Splitting the source into source fragment
+ * - Parsing each source fragment into its appropriate node
+ * - Managing the tag stack for pushtag/poptag nodes
  * - Applying tags from the stack to transactions
  *
  * @remarks
  * This is the primary function you'll use from this library. It takes a Beancount file
- * as a string and returns a structured ParseResult object containing all parsed entries.
+ * as a string and returns a structured ParseResult object containing the resulting parsed nodes.
  *
  * @example
  * Basic usage:
@@ -59,25 +59,25 @@ export const parseEntry = (unparsedEntry) => {
  * `
  *
  * const result = parse(content)
- * // result.entries contains parsed Entry objects
+ * // result.nodes contains parsed Node objects
  * ```
  *
- * @param input - The complete Beancount file content as a string
- * @returns A ParseResult instance containing all parsed entries
+ * @param source - The complete Beancount file content as a string
+ * @returns A ParseResult instance containing all parsed nodes
  */
-export const parse = (input) => {
-    const unparsedEntries = splitStringIntoUnparsedEntries(input);
-    const parsedEntries = [];
+export const parse = (source) => {
+    const sourceFragments = splitStringIntoSourceFragments(source);
+    const nodes = [];
     const tagStack = [];
-    for (const unparsedEntry of unparsedEntries) {
-        const parsedEntry = parseEntry(unparsedEntry);
-        if (parsedEntry) {
-            if (parsedEntry.type === 'pushtag') {
-                tagStack.push(parsedEntry.tag);
+    for (const sourceFragment of sourceFragments) {
+        const node = parseSourceFragment(sourceFragment);
+        if (node) {
+            if (node.type === 'pushtag') {
+                tagStack.push(node.tag);
             }
-            else if (parsedEntry.type === 'poptag') {
+            else if (node.type === 'poptag') {
                 // Find and remove the most recent matching tag from the stack
-                const tagToRemove = parsedEntry.tag.content;
+                const tagToRemove = node.tag.content;
                 for (let i = tagStack.length - 1; i >= 0; i--) {
                     if (tagStack[i].content === tagToRemove) {
                         tagStack.splice(i, 1);
@@ -85,11 +85,11 @@ export const parse = (input) => {
                     }
                 }
             }
-            if (parsedEntry.type === 'transaction') {
-                parsedEntry.tags.push(...tagStack);
+            if (node.type === 'transaction') {
+                node.tags.push(...tagStack);
             }
-            parsedEntries.push(parsedEntry);
+            nodes.push(node);
         }
     }
-    return new ParseResult(parsedEntries);
+    return new ParseResult(nodes);
 };

package/build/src/parseFile.d.mts

@@ -18,7 +18,7 @@ export type { FileSystemHelpers };
  *
  * @param filepath - Path to the Beancount file to parse
  * @param options - Parsing options
- * @returns A ParseResult containing all parsed entries
+ * @returns A ParseResult containing all parsed nodes
  *
  * @example
  * Basic usage (Node.js):
@@ -32,7 +32,7 @@ export type { FileSystemHelpers };
  * With recursive parsing of includes (Node.js):
  * ```typescript
  * const result = await parseFile('/path/to/main.beancount', { recurse: true })
- * // All entries from included files are merged into the result
+ * // All nodes from included files are merged into the result
  * ```
  *
  * @example

package/build/src/parseFile.mjs

@@ -6,7 +6,7 @@ import { getDefaultFileSystemHelpers, } from './fileSystemHelpers.mjs';
  *
  * @param filepath - Path to the Beancount file to parse
  * @param options - Parsing options
- * @returns A ParseResult containing all parsed entries
+ * @returns A ParseResult containing all parsed nodes
  *
  * @example
  * Basic usage (Node.js):
@@ -20,7 +20,7 @@ import { getDefaultFileSystemHelpers, } from './fileSystemHelpers.mjs';
  * With recursive parsing of includes (Node.js):
  * ```typescript
  * const result = await parseFile('/path/to/main.beancount', { recurse: true })
- * // All entries from included files are merged into the result
+ * // All nodes from included files are merged into the result
  * ```
  *
  * @example
@@ -86,7 +86,7 @@ export const parseFile = async (filepath, options = {}) => {
  * @param filepath - Path to the Beancount file to parse
  * @param visited - Set of already visited file paths (absolute)
  * @param fsHelpers - File system helpers for reading files and handling paths
- * @returns A ParseResult containing all parsed entries
+ * @returns A ParseResult containing all parsed nodes
  */
 const parseFileRecursive = async (filepath, visited, fsHelpers) => {
     const absolutePath = fsHelpers.resolvePath(filepath);
@@ -97,18 +97,18 @@ const parseFileRecursive = async (filepath, visited, fsHelpers) => {
     visited.add(absolutePath);
     const content = await fsHelpers.readFile(absolutePath);
     const result = parse(content);
-    const allEntries = [];
+    const allNodes = [];
     const baseDir = fsHelpers.dirname(absolutePath);
-    for (const entry of result.entries) {
-        if (entry.type === 'include') {
-            const includeEntry = entry;
-            const includePath = fsHelpers.resolveRelative(baseDir, includeEntry.filename);
+    for (const node of result.nodes) {
+        if (node.type === 'include') {
+            const includeNode = node;
+            const includePath = fsHelpers.resolveRelative(baseDir, includeNode.filename);
             const includeResult = await parseFileRecursive(includePath, visited, fsHelpers);
-            allEntries.push(...includeResult.entries);
+            allNodes.push(...includeResult.nodes);
         }
         else {
-            allEntries.push(entry);
+            allNodes.push(node);
         }
     }
-    return new ParseResult(allEntries);
+    return new ParseResult(allNodes);
 };

package/build/src/utils/splitStringIntoSourceFragments.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Splits a Beancount file string into an array of source fragments.
+ * Each fragment is represented as an array of strings.
+ *
+ * This function handles:
+ * - Splitting on blank lines between fragments
+ * - Detecting new fragments based on indentation
+ * - Preserving multi-line fragments
+ *
+ * @param source - The complete Beancount file content as a string
+ * @returns An array where each element is an array of strings representing one source fragment
+ * @internal
+ */
+export declare const splitStringIntoSourceFragments: (source: string) => string[][];

package/build/src/utils/splitStringIntoSourceFragments.js

@@ -0,0 +1,48 @@
+import { countChar } from './countChar.mjs';
+import { stringAwareSplitLine } from './stringAwareSplitLine.mjs';
+/**
+ * Splits a Beancount file string into an array of source fragments.
+ * Each fragment is represented as an array of strings.
+ *
+ * This function handles:
+ * - Splitting on blank lines between fragments
+ * - Detecting new fragments based on indentation
+ * - Preserving multi-line fragments
+ *
+ * @param source - The complete Beancount file content as a string
+ * @returns An array where each element is an array of strings representing one source fragment
+ * @internal
+ */
+export const splitStringIntoSourceFragments = (source) => {
+    const lines = source.split('\n');
+    // split up the file into source fragments
+    let inFragment = false;
+    let inString = false;
+    const fragments = lines.reduce((acc, line) => {
+        if (!inString) {
+            if (line.trim() === '') {
+                // empty newline, next fragment starts
+                inFragment = false;
+            }
+            if (!line.startsWith(' ') && inFragment) {
+                // no indent, new fragment
+                inFragment = false;
+            }
+            if (!inFragment) {
+                acc.push([]);
+                inFragment = true;
+            }
+        }
+        acc[acc.length - 1].push(line);
+        // After a blank line, ensure next line starts a new fragment
+        if (!inString && line.trim() === '') {
+            inFragment = false;
+        }
+        // odd number of ", we're in an unclosed string
+        if (countChar(line, '"') % 2 === 1) {
+            inString = !inString;
+        }
+        return acc;
+    }, []);
+    return fragments.map((lines) => stringAwareSplitLine(lines.join('\n')));
+};