beancount 0.0.2 → 0.0.3

package/build/src/main.d.mts

@@ -0,0 +1,58 @@
+/**
+ * beancount - A parser and editor for Beancount accounting files with full type safety.
+ *
+ * @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.
+ *
+ * @example
+ * ```typescript
+ * import { parse } from 'beancount'
+ *
+ * const beancountContent = `
+ * 2024-01-01 open Assets:Checking
+ * 2024-01-02 * "Grocery Store" "Weekly shopping"
+ *   Assets:Checking  -50.00 USD
+ *   Expenses:Food     50.00 USD
+ * `
+ *
+ * const result = parse(beancountContent)
+ * console.log(result.entries) // Array of parsed Entry objects
+ * ```
+ *
+ * @module
+ */
+export { parse, parseEntry, splitStringIntoUnparsedEntries } from './parse.mjs';
+export type { ParseOptions } from './parse.mjs';
+export type { GenericParseResult, GenericParseResultWithDate, GenericParseResultTransaction, } from './genericParse.mjs';
+export type { Metadata } from './utils/parseMetadata.mjs';
+export { ParseResult } from './classes/ParseResult.mjs';
+export { Entry, assertEntryConstructor } from './classes/Entry.mjs';
+export type { FormatOptions } from './classes/Entry.mjs';
+export { DateEntry } from './classes/DateEntry.mjs';
+export type { BeancountDateEntryType } from './classes/DateEntry.mjs';
+export { Value } from './classes/Value.mjs';
+export type { ValueType } from './classes/Value.mjs';
+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';
+export { Posting } from './classes/entryTypes/Transaction/Posting.mjs';
+export { Tag } from './classes/entryTypes/Transaction/Tag.mjs';
+export type { BeancountEntryType, EntryType } from './entryTypeToClass.mjs';
+export { beancountEntryToClass, entryTypeToClass } from './entryTypeToClass.mjs';

package/build/src/main.mjs

@@ -0,0 +1,55 @@
+/**
+ * beancount - A parser and editor for Beancount accounting files with full type safety.
+ *
+ * @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.
+ *
+ * @example
+ * ```typescript
+ * import { parse } from 'beancount'
+ *
+ * const beancountContent = `
+ * 2024-01-01 open Assets:Checking
+ * 2024-01-02 * "Grocery Store" "Weekly shopping"
+ *   Assets:Checking  -50.00 USD
+ *   Expenses:Food     50.00 USD
+ * `
+ *
+ * const result = parse(beancountContent)
+ * console.log(result.entries) // Array of parsed Entry objects
+ * ```
+ *
+ * @module
+ */
+// Primary parsing functionality
+export { parse, parseEntry, splitStringIntoUnparsedEntries } from './parse.mjs';
+// Core classes
+export { ParseResult } from './classes/ParseResult.mjs';
+export { Entry, assertEntryConstructor } from './classes/Entry.mjs';
+export { DateEntry } from './classes/DateEntry.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';
+// 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';

package/build/src/parse.d.mts

@@ -1,29 +1,82 @@
 import { ParseResult } from './classes/ParseResult.mjs';
-import { Transaction, Balance, Close, Comment, Commodity, Custom, Document, Event, Include, Note, Open, Option, Pad, Plugin, Poptag, Price, Pushtag, Query, Blankline } from './classes/entryTypes/index.mjs';
-declare const entryTypes: {
-    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;
-};
-export type EntryType = keyof typeof entryTypes;
+import { Comment, Blankline } from './classes/entryTypes/index.mjs';
+/**
+ * Splits a Beancount file string into an array of unparsed entry arrays.
+ * Each entry is represented as an array of strings (tokens).
+ *
+ * This function handles:
+ * - Splitting on blank lines between entries
+ * - Detecting new entries based on indentation
+ * - Preserving multi-line strings that span lines
+ *
+ * @param input - The complete Beancount file content as a string
+ * @returns An array where each element is an array of string tokens representing one entry
+ * @internal
+ */
 export declare const splitStringIntoUnparsedEntries: (input: string) => string[][];
-export declare const parseEntry: (unparsedEntry: string[], skipBlanklines?: boolean) => Open | Transaction | Balance | Close | Commodity | Custom | Document | Event | Include | Note | Option | Pad | Plugin | Poptag | Price | Pushtag | Query | Blankline | Comment | undefined;
+/**
+ * Parses a single unparsed entry into its corresponding Entry class instance.
+ *
+ * This function:
+ * - Performs generic parsing to determine entry type
+ * - Instantiates the appropriate Entry subclass
+ * - Handles special cases for comments and blank lines
+ *
+ * @param unparsedEntry - Array of string tokens representing a single entry
+ * @param skipBlanklines - If true, returns undefined for blank lines; if false, returns Blankline instances
+ * @returns An Entry instance, or undefined if the entry is blank and skipBlanklines is true
+ */
+export declare const parseEntry: (unparsedEntry: string[], skipBlanklines?: boolean) => import("./classes/entryTypes/index.mjs").Transaction | import("./classes/entryTypes/Balance.mjs").Balance | Blankline | import("./classes/entryTypes/Close.mjs").Close | Comment | 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/Price.mjs").Price | import("./classes/entryTypes/Poptag.mjs").Poptag | import("./classes/entryTypes/Pushtag.mjs").Pushtag | import("./classes/entryTypes/Query.mjs").Query | undefined;
+/**
+ * Options for configuring the parse function behavior.
+ */
 export interface ParseOptions {
+    /**
+     * If true, blank lines in the input are skipped and not included in the result.
+     * If false, blank lines are preserved as Blankline entries.
+     * Defaults to true.
+     */
     skipBlanklines?: boolean;
 }
+/**
+ * Parses a complete Beancount file string into a ParseResult containing Entry 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
+ * - 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.
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * import { parse } from 'beancount'
+ *
+ * const content = `
+ * 2024-01-01 open Assets:Checking
+ * 2024-01-02 * "Payee" "Narration"
+ *   Assets:Checking  100.00 USD
+ *   Income:Salary   -100.00 USD
+ * `
+ *
+ * const result = parse(content)
+ * // result.entries contains parsed Entry objects
+ * ```
+ *
+ * @example
+ * With options:
+ * ```typescript
+ * // Preserve blank lines in output
+ * const result = parse(content, { skipBlanklines: false })
+ * ```
+ *
+ * @param input - The complete Beancount file content as a string
+ * @param options - Optional parsing configuration
+ * @param options.skipBlanklines - If true, skips blank lines; defaults to true
+ * @returns A ParseResult instance containing all parsed entries
+ */
 export declare const parse: (input: string, { skipBlanklines }?: ParseOptions) => ParseResult;
-export {};

package/build/src/parse.mjs

@@ -1,29 +1,23 @@
 import assert from 'node:assert';
 import { ParseResult } from './classes/ParseResult.mjs';
-import { Transaction, Balance, Close, Comment, Commodity, Custom, Document, Event, Include, Note, Open, Option, Pad, Plugin, Poptag, Price, Pushtag, Query, Blankline, } from './classes/entryTypes/index.mjs';
+import { Comment, Blankline } from './classes/entryTypes/index.mjs';
 import { countChar } from './utils/countChar.mjs';
 import { stringAwareSplitLine } from './utils/stringAwareSplitLine.mjs';
 import { genericParse, } from './genericParse.mjs';
-// from https://beancount.github.io/docs/beancount_language_syntax.html#directives-1
-const entryTypes = {
-    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,
-};
+import { beancountEntryToClass } from './entryTypeToClass.mjs';
+/**
+ * Splits a Beancount file string into an array of unparsed entry arrays.
+ * Each entry is represented as an array of strings (tokens).
+ *
+ * This function handles:
+ * - Splitting on blank lines between entries
+ * - Detecting new entries based on indentation
+ * - Preserving multi-line strings that span lines
+ *
+ * @param input - The complete Beancount file content as a string
+ * @returns An array where each element is an array of string tokens representing one entry
+ * @internal
+ */
 export const splitStringIntoUnparsedEntries = (input) => {
     const lines = input.split('\n');
     // split up the file into entries
@@ -53,10 +47,22 @@ export const splitStringIntoUnparsedEntries = (input) => {
     }, []);
     return unparsedEntries.map((lines) => stringAwareSplitLine(lines.join('\n')));
 };
+/**
+ * Parses a single unparsed entry into its corresponding Entry class instance.
+ *
+ * This function:
+ * - Performs generic parsing to determine entry type
+ * - Instantiates the appropriate Entry subclass
+ * - Handles special cases for comments and blank lines
+ *
+ * @param unparsedEntry - Array of string tokens representing a single entry
+ * @param skipBlanklines - If true, returns undefined for blank lines; if false, returns Blankline instances
+ * @returns An Entry instance, or undefined if the entry is blank and skipBlanklines is true
+ */
 export const parseEntry = (unparsedEntry, skipBlanklines = true) => {
     const genericParseResult = genericParse(unparsedEntry);
     const { type } = genericParseResult;
-    const EntryClass = entryTypes[type];
+    const EntryClass = beancountEntryToClass[type];
     if (EntryClass) {
         return EntryClass.fromGenericParseResult(genericParseResult);
     }
@@ -75,6 +81,47 @@ export const parseEntry = (unparsedEntry, skipBlanklines = true) => {
         });
     }
 };
+/**
+ * Parses a complete Beancount file string into a ParseResult containing Entry 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
+ * - 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.
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * import { parse } from 'beancount'
+ *
+ * const content = `
+ * 2024-01-01 open Assets:Checking
+ * 2024-01-02 * "Payee" "Narration"
+ *   Assets:Checking  100.00 USD
+ *   Income:Salary   -100.00 USD
+ * `
+ *
+ * const result = parse(content)
+ * // result.entries contains parsed Entry objects
+ * ```
+ *
+ * @example
+ * With options:
+ * ```typescript
+ * // Preserve blank lines in output
+ * const result = parse(content, { skipBlanklines: false })
+ * ```
+ *
+ * @param input - The complete Beancount file content as a string
+ * @param options - Optional parsing configuration
+ * @param options.skipBlanklines - If true, skips blank lines; defaults to true
+ * @returns A ParseResult instance containing all parsed entries
+ */
 export const parse = (input, { skipBlanklines = true } = {}) => {
     const unparsedEntries = splitStringIntoUnparsedEntries(input);
     const parsedEntries = [];

package/build/src/utils/countChar.d.mts

@@ -1 +1,8 @@
+/**
+ * Counts the number of occurrences of a character in a string.
+ *
+ * @param line - The string to search in
+ * @param charToCount - The character to count occurrences of
+ * @returns The number of times the character appears in the string
+ */
 export declare const countChar: (line: string, charToCount: string) => number;

package/build/src/utils/countChar.mjs

@@ -1,3 +1,10 @@
+/**
+ * Counts the number of occurrences of a character in a string.
+ *
+ * @param line - The string to search in
+ * @param charToCount - The character to count occurrences of
+ * @returns The number of times the character appears in the string
+ */
 export const countChar = (line, charToCount) => {
     return line.split(charToCount).length - 1;
 };

package/build/src/utils/formatPrice.d.mts

@@ -1,9 +1,14 @@
 /**
- * Formats a price string from amount and currency components.
+ * Formats a price string from amount, currency, cost, and price annotation components.
  * Returns undefined if either amount or currency is missing.
  *
+ * Format: "amount currency [{cost}] [@ priceAmount priceCurrency]"
+ *
  * @param amount - The amount portion of the price
  * @param currency - The currency portion of the price
- * @returns Formatted price string "amount currency" or undefined
+ * @param cost - Optional cost specification in curly braces
+ * @param priceAmount - Optional price annotation amount
+ * @param priceCurrency - Optional price annotation currency
+ * @returns Formatted price string or undefined if amount/currency are missing
  */
 export declare const formatPrice: (amount: string | undefined, currency: string | undefined, cost?: string, priceAmount?: string, priceCurrency?: string) => string | undefined;

package/build/src/utils/formatPrice.mjs

@@ -1,10 +1,15 @@
 /**
- * Formats a price string from amount and currency components.
+ * Formats a price string from amount, currency, cost, and price annotation components.
  * Returns undefined if either amount or currency is missing.
  *
+ * Format: "amount currency [{cost}] [@ priceAmount priceCurrency]"
+ *
  * @param amount - The amount portion of the price
  * @param currency - The currency portion of the price
- * @returns Formatted price string "amount currency" or undefined
+ * @param cost - Optional cost specification in curly braces
+ * @param priceAmount - Optional price annotation amount
+ * @param priceCurrency - Optional price annotation currency
+ * @returns Formatted price string or undefined if amount/currency are missing
  */
 export const formatPrice = (amount, currency, cost, priceAmount, priceCurrency) => {
     if (!amount || !currency) {

package/build/src/utils/parseMetadata.d.mts

@@ -1,3 +1,15 @@
 import { Value } from '../classes/Value.mjs';
+/**
+ * Type representing metadata as a record of key-value pairs.
+ * Keys are strings, values are Value objects.
+ */
 export type Metadata = Record<string, Value>;
+/**
+ * Parses metadata lines into a Metadata object.
+ * Each line should be in the format "key: value".
+ *
+ * @param rest - Array of metadata line strings to parse
+ * @returns A Metadata object with parsed key-value pairs, or undefined if no lines provided
+ * @throws {Error} If any line cannot be parsed as metadata
+ */
 export declare const parseMetadata: (rest: string[]) => Metadata | undefined;

package/build/src/utils/parseMetadata.mjs

@@ -1,4 +1,12 @@
 import { Value } from '../classes/Value.mjs';
+/**
+ * Parses metadata lines into a Metadata object.
+ * Each line should be in the format "key: value".
+ *
+ * @param rest - Array of metadata line strings to parse
+ * @returns A Metadata object with parsed key-value pairs, or undefined if no lines provided
+ * @throws {Error} If any line cannot be parsed as metadata
+ */
 export const parseMetadata = (rest) => {
     if (rest.length === 0) {
         return undefined;

package/build/src/utils/simpleParseLine.d.mts

@@ -1 +1,8 @@
+/**
+ * Parses a line by splitting on spaces and filtering out empty strings.
+ * Does not handle quoted strings - use stringAwareParseLine for that.
+ *
+ * @param line - The line string to parse
+ * @returns Array of non-empty tokens split by spaces
+ */
 export declare const simpleParseLine: (line: string) => string[];

package/build/src/utils/simpleParseLine.mjs

@@ -1 +1,8 @@
+/**
+ * Parses a line by splitting on spaces and filtering out empty strings.
+ * Does not handle quoted strings - use stringAwareParseLine for that.
+ *
+ * @param line - The line string to parse
+ * @returns Array of non-empty tokens split by spaces
+ */
 export const simpleParseLine = (line) => line.split(' ').filter((e) => e !== '');

package/build/src/utils/stringAwareParseLine.d.mts

@@ -1 +1,8 @@
+/**
+ * Parses a line by splitting on spaces while respecting quoted strings.
+ * Spaces inside quoted strings are preserved as part of the string content.
+ *
+ * @param line - The line string to parse
+ * @returns Array of tokens split by spaces (excluding spaces within quotes)
+ */
 export declare const stringAwareParseLine: (line: string) => string[];

package/build/src/utils/stringAwareParseLine.mjs

@@ -1,3 +1,10 @@
+/**
+ * Parses a line by splitting on spaces while respecting quoted strings.
+ * Spaces inside quoted strings are preserved as part of the string content.
+ *
+ * @param line - The line string to parse
+ * @returns Array of tokens split by spaces (excluding spaces within quotes)
+ */
 export const stringAwareParseLine = (line) => {
     const result = [];
     let current = '';

package/build/src/utils/stringAwareSplitLine.d.mts

@@ -1 +1,10 @@
+/**
+ * Splits a string by newlines while respecting quoted strings.
+ * Newlines inside quoted strings are preserved as part of the string content.
+ * Handles escape sequences within quotes.
+ *
+ * @param input - The input string to split
+ * @returns Array of strings split by newlines (excluding newlines within quotes)
+ * @throws {Error} If there is an unclosed quote in the input
+ */
 export declare const stringAwareSplitLine: (input: string) => string[];

package/build/src/utils/stringAwareSplitLine.mjs

@@ -1,3 +1,12 @@
+/**
+ * Splits a string by newlines while respecting quoted strings.
+ * Newlines inside quoted strings are preserved as part of the string content.
+ * Handles escape sequences within quotes.
+ *
+ * @param input - The input string to split
+ * @returns Array of strings split by newlines (excluding newlines within quotes)
+ * @throws {Error} If there is an unclosed quote in the input
+ */
 export const stringAwareSplitLine = (input) => {
     const result = [];
     let current = '';