beancount 0.0.1 → 0.0.3

package/README.md

@@ -19,7 +19,7 @@ npm install beancount
 ## Quick Start
 
 ```typescript
-import { parse } from 'beancount'
+import { parse, ParseResult } from 'beancount'
 
 const beancountContent = `
 2024-01-01 open Assets:Checking USD
@@ -37,6 +37,13 @@ console.log(result.entries.length) // 2
 // Convert back to string
 console.log(result.toString())
 
+// 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
 console.log(result.toFormattedString())
@@ -46,12 +53,6 @@ console.log(result.toFormattedString())
 
 Full API documentation is available at https://Boelensman1.github.io/node-beancount/
 
-You can also generate documentation locally with:
-
-```bash
-command make docs
-```
-
 ## Contributing
 
 This project uses Make for task orchestration. Common commands:

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

@@ -1,17 +1,29 @@
 import { Temporal } from '@js-temporal/polyfill';
 import { Entry } from './Entry.mjs';
 import { Value } from './Value.mjs';
-import type { EntryType } from '../parse.mjs';
-export type DateEntryType = Exclude<EntryType, 'include' | 'option' | 'plugin'>;
+import type { BeancountEntryType } from '../entryTypeToClass.mjs';
+/**
+ * Union type of all Beancount entry types that include a date field.
+ * Excludes non-dated directives 'include', 'option', and 'plugin'.
+ */
+export type BeancountDateEntryType = Exclude<BeancountEntryType, 'include' | 'option' | 'plugin'>;
 /**
  * Abstract base class for all Beancount entry types that have a date.
  *
  * Child classes must implement static `fromGenericParseResult` method
  */
 export declare abstract class DateEntry extends Entry {
-    abstract type: DateEntryType;
+    /** The type of this dated entry */
+    abstract type: BeancountDateEntryType;
+    /** The date of this entry as a Temporal.PlainDate object */
     date: Temporal.PlainDate;
+    /** Optional metadata key-value pairs associated with this entry */
     metadata?: Record<string, Value>;
+    /**
+     * Creates a new DateEntry instance.
+     * @param obj - Object containing entry properties
+     * @param obj.date - The date string in YYYY-MM-DD format
+     */
     constructor(obj: {
         date: string;
         [key: string]: unknown;
@@ -19,7 +31,14 @@ export declare abstract class DateEntry extends Entry {
     /**
      * Returns the common prefix for all DateEntry 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/DateEntry.mjs

@@ -1,25 +1,44 @@
 import { Temporal } from '@js-temporal/polyfill';
 import { Entry } from './Entry.mjs';
+import { Value } from './Value.mjs';
 /**
  * Abstract base class for all Beancount entry types that have a date.
  *
  * Child classes must implement static `fromGenericParseResult` method
  */
 export class DateEntry extends Entry {
+    /**
+     * Creates a new DateEntry instance.
+     * @param obj - Object containing entry properties
+     * @param obj.date - The date string in YYYY-MM-DD format
+     */
     constructor(obj) {
-        const { date, ...props } = obj;
+        const { date, metadata, ...props } = obj;
         super(props);
         if (date) {
             this.date = Temporal.PlainDate.from(date, { overflow: 'reject' });
         }
+        if (metadata) {
+            this.metadata = Object.fromEntries(Object.entries(metadata).map(([key, val]) => [
+                key,
+                new Value(val),
+            ]));
+        }
     }
     /**
      * Returns the common prefix for all DateEntry 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) {

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

@@ -1,14 +1,23 @@
+import type { BeancountEntryType } from '../entryTypeToClass.mjs';
 import { genericParse } from '../../src/genericParse.mjs';
-import type { EntryType } from '../parse.mjs';
 /**
  * Type helper for Entry 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 EntryConstructor<T extends Entry> {
+    /**
+     * Creates an Entry instance from a generic parse result.
+     * @param parsedStart - The result from genericParse containing parsed entry data
+     * @returns A new instance of the Entry subclass
+     */
     fromGenericParseResult(parsedStart: ReturnType<typeof genericParse>): T;
 }
+/**
+ * Options for formatting Entry output.
+ */
 export interface FormatOptions {
+    /** The column position where currency symbols should be aligned */
     currencyColumn: number;
 }
 /**
@@ -17,14 +26,55 @@ export interface FormatOptions {
  * Child classes must implement static `fromGenericParseResult` method
  */
 export declare abstract class Entry {
+    /** Optional comment text associated with this entry */
     comment?: string;
-    abstract type: EntryType | 'comment' | 'blankline';
+    /** The type of this entry (e.g., 'open', 'close', 'transaction', 'comment', 'blankline') */
+    abstract type: BeancountEntryType | 'comment' | 'blankline';
+    /**
+     * Creates a new Entry instance.
+     * @param obj - Object containing entry properties
+     */
     constructor(obj: Record<string, unknown>);
+    /**
+     * Creates an Entry instance from a Beancount string.
+     * Parses the input string and constructs the appropriate Entry subclass.
+     *
+     * @param input - A single Beancount entry as a string
+     * @returns A new instance of the Entry subclass
+     */
     static fromString<T extends Entry>(this: EntryConstructor<T>, input: string): T;
+    /**
+     * Creates an Entry instance from JSON data.
+     * Calls parseJSON to allow subclasses to transform the data before construction.
+     *
+     * @param jsonString - JSON data representing an entry
+     * @returns A new instance of the Entry subclass
+     * @remarks **Warning:** No validation is performed on the JSON input. We assume the JSON is valid and well-formed.
+     */
+    static fromJSON<T extends Entry>(this: new (obj: any) => T, jsonString: string): T;
+    /**
+     * Converts this entry 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 entry
+     */
     toFormattedString(_formatOptions: FormatOptions): string;
+    /**
+     * Transforms JSON data before creating an Entry 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 parseJSON(json: Record<string, unknown>): Record<string, unknown>;
 }
 /**
  * Type assertion helper to ensure a class conforms to EntryConstructor.
  * Usage: assertEntryConstructor(MyEntryClass)
+ * @param _ctor - The constructor to validate (unused at runtime)
+ * @internal
  */
 export declare function assertEntryConstructor<T extends Entry>(_ctor: EntryConstructor<T>): void;

package/build/src/classes/Entry.mjs

@@ -6,9 +6,20 @@ import { stringAwareSplitLine } from '../utils/stringAwareSplitLine.mjs';
  * Child classes must implement static `fromGenericParseResult` method
  */
 export class Entry {
+    /**
+     * Creates a new Entry instance.
+     * @param obj - Object containing entry properties
+     */
     constructor(obj) {
         Object.assign(this, obj);
     }
+    /**
+     * Creates an Entry instance from a Beancount string.
+     * Parses the input string and constructs the appropriate Entry subclass.
+     *
+     * @param input - A single Beancount entry as a string
+     * @returns A new instance of the Entry subclass
+     */
     static fromString(input) {
         const unparsedEntry = stringAwareSplitLine(input);
         const genericParseResult = genericParse(unparsedEntry);
@@ -18,15 +29,52 @@ export class Entry {
         }
         return result;
     }
+    /**
+     * Creates an Entry instance from JSON data.
+     * Calls parseJSON to allow subclasses to transform the data before construction.
+     *
+     * @param jsonString - JSON data representing an entry
+     * @returns A new instance of the Entry 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);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const instance = new this({});
+        const transformedData = instance.parseJSON(json);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return new this(transformedData);
+    }
+    /**
+     * Converts this entry 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 entry
+     */
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     toFormattedString(_formatOptions) {
         // eslint-disable-next-line @typescript-eslint/no-base-to-string
         return this.toString();
     }
+    /**
+     * Transforms JSON data before creating an Entry 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
+     */
+    parseJSON(json) {
+        return json;
+    }
 }
 /**
  * Type assertion helper to ensure a class conforms to EntryConstructor.
  * Usage: assertEntryConstructor(MyEntryClass)
+ * @param _ctor - The constructor to validate (unused at runtime)
+ * @internal
  */
 export function assertEntryConstructor(
 // eslint-disable-next-line @typescript-eslint/no-unused-vars

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

@@ -1,9 +1,35 @@
 import { Entry } from './Entry.mjs';
+/**
+ * Container class for parsed Beancount entries.
+ * Provides methods for converting entries back to string format.
+ */
 export declare class ParseResult {
     entries: Entry[];
+    /**
+     * Creates a new ParseResult instance.
+     * @param entries - Array of parsed Entry objects
+     */
     constructor(entries: Entry[]);
+    /**
+     * Converts all entries to their string representation.
+     * Each entry is converted using its toString() method and joined with newlines.
+     * @returns The complete Beancount file content as a string
+     */
     toString(): string;
-    toFormattedString(options?: {
-        width: number;
-    }): string;
+    /**
+     * Converts all entries to a formatted string with aligned columns.
+     * Uses each entry's toFormattedString() method for consistent formatting.
+     *
+     * @returns The formatted Beancount file content as a string
+     */
+    toFormattedString(): string;
+    /**
+     * Creates an ParseResult instance from JSON data.
+     * Calls parseJSON to allow subclasses to transform the data before construction.
+     *
+     * @param jsonString - JSON data representing an ParseResult
+     * @remarks **Warning:** No validation is performed on the JSON input. We assume the JSON is valid and well-formed.
+     * @returns A new instance of ParseResult loaded with the data in the JSON
+     */
+    static fromJSON(jsonString: string): ParseResult;
 }

package/build/src/classes/ParseResult.mjs

@@ -1,19 +1,60 @@
-const defaultFormattingOptions = {
-    width: 100,
-};
+import { entryTypeToClass } from '../entryTypeToClass.mjs';
+/**
+ * Container class for parsed Beancount entries.
+ * Provides methods for converting entries back to string format.
+ */
 export class ParseResult {
+    /**
+     * Creates a new ParseResult instance.
+     * @param entries - Array of parsed Entry objects
+     */
     constructor(entries) {
         this.entries = entries;
     }
+    /**
+     * Converts all entries to their string representation.
+     * Each entry is converted using its toString() method and joined with newlines.
+     * @returns The complete Beancount file content as a string
+     */
     toString() {
         // eslint-disable-next-line @typescript-eslint/no-base-to-string
         return this.entries.map((e) => e.toString()).join('\n');
     }
-    toFormattedString(options = defaultFormattingOptions) {
+    /**
+     * Converts all entries to a formatted string with aligned columns.
+     * Uses each entry's toFormattedString() method for consistent formatting.
+     *
+     * @returns The formatted Beancount file content as a string
+     */
+    toFormattedString() {
         // TODO: calculate currencyColumn
         const currencyColumn = 59;
         return this.entries
             .map((e) => e.toFormattedString({ currencyColumn }))
             .join('\n');
     }
+    /**
+     * Creates an ParseResult instance from JSON data.
+     * Calls parseJSON to allow subclasses to transform the data before construction.
+     *
+     * @param jsonString - JSON data representing an ParseResult
+     * @remarks **Warning:** No validation is performed on the JSON input. We assume the JSON is valid and well-formed.
+     * @returns A new instance of ParseResult loaded with the data in the JSON
+     */
+    static fromJSON(jsonString) {
+        const json = JSON.parse(jsonString);
+        const jsonEntries = json.entries;
+        const entries = jsonEntries.map((jsonEntry) => {
+            const { type } = jsonEntry;
+            const EntryClass = entryTypeToClass[type];
+            if (!EntryClass) {
+                throw new Error(`No entryclass found for type ${type}`);
+            }
+            // Type assertion needed because TypeScript can't verify that all entry classes
+            // in the union type have compatible constructor signatures
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+            return EntryClass.fromJSON(JSON.stringify(jsonEntry));
+        });
+        return new ParseResult(entries);
+    }
 }

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

@@ -1,12 +1,51 @@
+/**
+ * Union type of all possible value types in Beancount metadata and expressions.
+ */
 export type ValueType = 'string' | 'date' | 'boolean' | 'amount' | 'numbers';
+/**
+ * Removes surrounding double quotes from a string value.
+ * @param val - The string to parse (potentially with quotes)
+ * @returns The string without leading or trailing quotes
+ */
 export declare const parseString: (val: string) => string;
+/**
+ * Represents a typed value in Beancount (used in metadata, expressions, etc.).
+ * Handles string, boolean, date, amount, and number values.
+ */
 export declare class Value {
+    /** The type of this value */
     type: ValueType;
+    /** The actual value data */
     value: unknown;
+    /**
+     * Creates a new Value instance.
+     * @param obj - Object containing type and value properties
+     * @param obj.type - The value type
+     * @param obj.value - The value data
+     */
     constructor(obj: {
         type: ValueType;
         value: unknown;
     });
+    /**
+     * Parses a string into a Value object with appropriate type detection.
+     * Detects and handles:
+     * - Quoted strings
+     * - Boolean values (TRUE/FALSE, case-insensitive)
+     * - Amounts (fallback for other values)
+     *
+     * @param input - The string to parse
+     * @returns A new Value instance with detected type
+     */
     static fromString(input: string): Value;
+    /**
+     * Converts this value to its string representation.
+     * Formats based on type:
+     * - Booleans as TRUE/FALSE
+     * - Strings with surrounding quotes
+     * - Other types as their string representation
+     *
+     * @returns The formatted string representation
+     */
     toString(): string;
 }

package/build/src/classes/Value.mjs

@@ -1,10 +1,35 @@
+/**
+ * Removes surrounding double quotes from a string value.
+ * @param val - The string to parse (potentially with quotes)
+ * @returns The string without leading or trailing quotes
+ */
 export const parseString = (val) => {
     return val.replace(/^"|"$/g, '');
 };
+/**
+ * Represents a typed value in Beancount (used in metadata, expressions, etc.).
+ * Handles string, boolean, date, amount, and number values.
+ */
 export class Value {
+    /**
+     * Creates a new Value instance.
+     * @param obj - Object containing type and value properties
+     * @param obj.type - The value type
+     * @param obj.value - The value data
+     */
     constructor(obj) {
         Object.assign(this, obj);
     }
+    /**
+     * Parses a string into a Value object with appropriate type detection.
+     * Detects and handles:
+     * - Quoted strings
+     * - Boolean values (TRUE/FALSE, case-insensitive)
+     * - Amounts (fallback for other values)
+     *
+     * @param input - The string to parse
+     * @returns A new Value instance with detected type
+     */
     static fromString(input) {
         if (input.startsWith('"') && input.endsWith('"')) {
             // string!
@@ -19,6 +44,15 @@ export class Value {
         // TODO: more parsing
         return new Value({ type: 'amount', value: input });
     }
+    /**
+     * Converts this value to its string representation.
+     * Formats based on type:
+     * - Booleans as TRUE/FALSE
+     * - Strings with surrounding quotes
+     * - Other types as their string representation
+     *
+     * @returns The formatted string representation
+     */
     toString() {
         switch (this.type) {
             case 'boolean':

package/build/src/classes/entryTypes/Balance.d.mts

@@ -1,13 +1,32 @@
 import type { GenericParseResultWithDate } from '../../genericParse.mjs';
 import { FormatOptions } from '../Entry.mjs';
 import { DateEntry } from '../DateEntry.mjs';
+/**
+ * Represents a Balance assertion entry.
+ * Balance directives assert that an account has a specific balance at a given date.
+ */
 export declare class Balance extends DateEntry {
+    /** @inheritdoc */
     type: "balance";
+    /** The account name for the balance assertion */
     account: string;
+    /** The expected amount */
     amount: string;
+    /** The currency of the amount */
     currency: string;
+    /**
+     * Gets the formatted price string (amount + currency).
+     * @returns The formatted price string
+     */
     get price(): string | undefined;
+    /**
+     * Creates a Balance instance from a generic parse result.
+     * @param genericParseResult - The parsed balance entry data
+     * @returns A new Balance instance
+     */
     static fromGenericParseResult(genericParseResult: GenericParseResultWithDate): Balance;
+    /** @inheritdoc */
     toString(): string;
+    /** @inheritdoc */
     toFormattedString(formatOptions: FormatOptions): string;
 }

package/build/src/classes/entryTypes/Balance.mjs

@@ -2,14 +2,28 @@ import { assertEntryConstructor } from '../Entry.mjs';
 import { DateEntry } from '../DateEntry.mjs';
 import { simpleParseLine } from '../../utils/simpleParseLine.mjs';
 import { formatPrice } from '../../utils/formatPrice.mjs';
+/**
+ * Represents a Balance assertion entry.
+ * Balance directives assert that an account has a specific balance at a given date.
+ */
 export class Balance extends DateEntry {
     constructor() {
         super(...arguments);
+        /** @inheritdoc */
         this.type = 'balance';
     }
+    /**
+     * Gets the formatted price string (amount + currency).
+     * @returns The formatted price string
+     */
     get price() {
         return formatPrice(this.amount, this.currency);
     }
+    /**
+     * Creates a Balance instance from a generic parse result.
+     * @param genericParseResult - The parsed balance entry data
+     * @returns A new Balance instance
+     */
     static fromGenericParseResult(genericParseResult) {
         const [account, amount, currency] = simpleParseLine(genericParseResult.header);
         return new Balance({
@@ -19,9 +33,11 @@ export class Balance extends DateEntry {
             currency,
         });
     }
+    /** @inheritdoc */
     toString() {
         return this.toFormattedString({ currencyColumn: 0 });
     }
+    /** @inheritdoc */
     toFormattedString(formatOptions) {
         const firstPart = `${this.getDateTypePrefix()} ${this.account}`;
         const paddingLength = formatOptions.currencyColumn - firstPart.length - this.amount.length - 2; // not sure what this is for

package/build/src/classes/entryTypes/Blankline.d.mts

@@ -1,8 +1,24 @@
 import type { GenericParseResult } from '../../genericParse.mjs';
 import { Entry, EntryConstructor } from '../Entry.mjs';
+/**
+ * Represents a blank line in a Beancount file.
+ * Blank lines are used to separate entries for readability.
+ */
 export declare class Blankline extends Entry {
+    /** @inheritdoc */
     type: "blankline";
+    /**
+     * Creates a Blankline instance from a generic parse result.
+     * @param _genericParseResult - Unused, blank lines have no content
+     * @returns A new Blankline instance
+     */
     static fromGenericParseResult(_genericParseResult: GenericParseResult): Blankline;
+    /** @inheritdoc */
     toString(): string;
+    /**
+     * Creates a Blankline instance from a string.
+     * @param _input - Unused, blank lines have no content
+     * @returns A new Blankline instance
+     */
     static fromString<T extends Entry>(this: EntryConstructor<T>, _input: string): T;
 }

package/build/src/classes/entryTypes/Blankline.mjs

@@ -1,17 +1,33 @@
 import { assertEntryConstructor, Entry } from '../Entry.mjs';
+/**
+ * Represents a blank line in a Beancount file.
+ * Blank lines are used to separate entries for readability.
+ */
 export class Blankline extends Entry {
     constructor() {
         super(...arguments);
+        /** @inheritdoc */
         this.type = 'blankline';
     }
+    /**
+     * Creates a Blankline instance from a generic parse result.
+     * @param _genericParseResult - Unused, blank lines have no content
+     * @returns A new Blankline instance
+     */
     static fromGenericParseResult(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     _genericParseResult) {
         return new Blankline({});
     }
+    /** @inheritdoc */
     toString() {
         return '';
     }
+    /**
+     * Creates a Blankline instance from a string.
+     * @param _input - Unused, blank lines have no content
+     * @returns A new Blankline instance
+     */
     static fromString(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     _input) {

package/build/src/classes/entryTypes/Close.d.mts

@@ -1,8 +1,20 @@
 import type { GenericParseResultWithDate } from '../../genericParse.mjs';
 import { DateEntry } from '../DateEntry.mjs';
+/**
+ * Represents a Close entry that closes an account.
+ * Close directives mark the end of an account's lifespan.
+ */
 export declare class Close extends DateEntry {
+    /** @inheritdoc */
     type: "close";
+    /** The account name being closed */
     account: string;
+    /**
+     * Creates a Close instance from a generic parse result.
+     * @param genericParseResult - The parsed close entry data
+     * @returns A new Close instance
+     */
     static fromGenericParseResult(genericParseResult: GenericParseResultWithDate): Close;
+    /** @inheritdoc */
     toString(): string;
 }

package/build/src/classes/entryTypes/Close.mjs

@@ -1,10 +1,20 @@
 import { assertEntryConstructor } from '../Entry.mjs';
 import { DateEntry } from '../DateEntry.mjs';
+/**
+ * Represents a Close entry that closes an account.
+ * Close directives mark the end of an account's lifespan.
+ */
 export class Close extends DateEntry {
     constructor() {
         super(...arguments);
+        /** @inheritdoc */
         this.type = 'close';
     }
+    /**
+     * Creates a Close instance from a generic parse result.
+     * @param genericParseResult - The parsed close entry data
+     * @returns A new Close instance
+     */
     static fromGenericParseResult(genericParseResult) {
         const account = genericParseResult.header.trim();
         return new Close({
@@ -12,6 +22,7 @@ export class Close extends DateEntry {
             account,
         });
     }
+    /** @inheritdoc */
     toString() {
         return `${this.getDateTypePrefix()} ${this.account}${this.getMetaDataString()}`;
     }