beancount 0.0.2 → 0.0.4

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

@@ -1,11 +1,21 @@
 import { simpleParseLine } from '../../utils/simpleParseLine.mjs';
 import { assertEntryConstructor, Entry } from '../Entry.mjs';
 import { Tag } from './Transaction/Tag.mjs';
+/**
+ * Represents a Poptag entry that removes a tag from the tag stack.
+ * Transactions after this will no longer inherit the popped tag.
+ */
 export class Poptag extends Entry {
     constructor() {
         super(...arguments);
+        /** @inheritdoc */
         this.type = 'poptag';
     }
+    /**
+     * Creates a Poptag instance from a generic parse result.
+     * @param genericParseResult - The parsed poptag entry data
+     * @returns A new Poptag instance
+     */
     static fromGenericParseResult(genericParseResult) {
         const [tagContent] = simpleParseLine(genericParseResult.header);
         return new Poptag({
@@ -15,6 +25,7 @@ export class Poptag extends Entry {
             }),
         });
     }
+    /** @inheritdoc */
     toString() {
         return `poptag #${this.tag.content}`;
     }

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

@@ -1,11 +1,29 @@
 import type { GenericParseResultWithDate } from '../../genericParse.mjs';
 import { DateEntry } from '../DateEntry.mjs';
+/**
+ * Represents a Price entry that records the price of a commodity.
+ * Price directives establish the exchange rate between a commodity and a currency.
+ */
 export declare class Price extends DateEntry {
+    /** @inheritdoc */
     type: "price";
+    /** The commodity being priced */
     commodity: string;
+    /** The currency the price is expressed in */
     currency: string;
+    /** The price amount */
     amount: string;
+    /**
+     * Gets the formatted price string (amount + currency).
+     * @returns The formatted price string
+     */
     get price(): string | undefined;
+    /**
+     * Creates a Price instance from a generic parse result.
+     * @param genericParseResult - The parsed price entry data
+     * @returns A new Price instance
+     */
     static fromGenericParseResult(genericParseResult: GenericParseResultWithDate): Price;
+    /** @inheritdoc */
     toString(): string;
 }

package/build/src/classes/entryTypes/Price.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 Price entry that records the price of a commodity.
+ * Price directives establish the exchange rate between a commodity and a currency.
+ */
 export class Price extends DateEntry {
     constructor() {
         super(...arguments);
+        /** @inheritdoc */
         this.type = 'price';
     }
+    /**
+     * Gets the formatted price string (amount + currency).
+     * @returns The formatted price string
+     */
     get price() {
         return formatPrice(this.amount, this.currency);
     }
+    /**
+     * Creates a Price instance from a generic parse result.
+     * @param genericParseResult - The parsed price entry data
+     * @returns A new Price instance
+     */
     static fromGenericParseResult(genericParseResult) {
         const [commodity, amount, currency] = simpleParseLine(genericParseResult.header);
         return new Price({
@@ -19,6 +33,7 @@ export class Price extends DateEntry {
             amount,
         });
     }
+    /** @inheritdoc */
     toString() {
         return `${this.getDateTypePrefix()} ${this.commodity} ${this.amount} ${this.currency}${this.getMetaDataString()}`;
     }

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

@@ -1,9 +1,21 @@
 import type { GenericParseResult } from '../../genericParse.mjs';
 import { Entry } from '../Entry.mjs';
 import { Tag } from './Transaction/Tag.mjs';
+/**
+ * Represents a Pushtag entry that pushes a tag onto the tag stack.
+ * Subsequent transactions will automatically inherit this tag until it's popped.
+ */
 export declare class Pushtag extends Entry {
+    /** @inheritdoc */
     type: "pushtag";
+    /** The tag being pushed onto the stack */
     tag: Tag;
+    /**
+     * Creates a Pushtag instance from a generic parse result.
+     * @param genericParseResult - The parsed pushtag entry data
+     * @returns A new Pushtag instance
+     */
     static fromGenericParseResult(genericParseResult: GenericParseResult): Pushtag;
+    /** @inheritdoc */
     toString(): string;
 }

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

@@ -1,11 +1,21 @@
 import { simpleParseLine } from '../../utils/simpleParseLine.mjs';
 import { assertEntryConstructor, Entry } from '../Entry.mjs';
 import { Tag } from './Transaction/Tag.mjs';
+/**
+ * Represents a Pushtag entry that pushes a tag onto the tag stack.
+ * Subsequent transactions will automatically inherit this tag until it's popped.
+ */
 export class Pushtag extends Entry {
     constructor() {
         super(...arguments);
+        /** @inheritdoc */
         this.type = 'pushtag';
     }
+    /**
+     * Creates a Pushtag instance from a generic parse result.
+     * @param genericParseResult - The parsed pushtag entry data
+     * @returns A new Pushtag instance
+     */
     static fromGenericParseResult(genericParseResult) {
         const [tagContent] = simpleParseLine(genericParseResult.header);
         return new Pushtag({
@@ -15,6 +25,7 @@ export class Pushtag extends Entry {
             }),
         });
     }
+    /** @inheritdoc */
     toString() {
         return `${this.type} #${this.tag.content}`;
     }

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

@@ -1,9 +1,22 @@
 import type { GenericParseResultWithDate } from '../../genericParse.mjs';
 import { DateEntry } from '../DateEntry.mjs';
+/**
+ * Represents a Query entry that defines a named SQL query.
+ * Query directives allow defining reusable queries in the Beancount file.
+ */
 export declare class Query extends DateEntry {
+    /** @inheritdoc */
     type: "query";
+    /** The name of the query */
     name: string;
+    /** The SQL query contents */
     sqlContents: string;
+    /**
+     * Creates a Query instance from a generic parse result.
+     * @param genericParseResult - The parsed query entry data
+     * @returns A new Query instance
+     */
     static fromGenericParseResult(genericParseResult: GenericParseResultWithDate): Query;
+    /** @inheritdoc */
     toString(): string;
 }

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

@@ -2,11 +2,21 @@ import { assertEntryConstructor } from '../Entry.mjs';
 import { DateEntry } from '../DateEntry.mjs';
 import { stringAwareParseLine } from '../../utils/stringAwareParseLine.mjs';
 import { parseString } from '../Value.mjs';
+/**
+ * Represents a Query entry that defines a named SQL query.
+ * Query directives allow defining reusable queries in the Beancount file.
+ */
 export class Query extends DateEntry {
     constructor() {
         super(...arguments);
+        /** @inheritdoc */
         this.type = 'query';
     }
+    /**
+     * Creates a Query instance from a generic parse result.
+     * @param genericParseResult - The parsed query entry data
+     * @returns A new Query instance
+     */
     static fromGenericParseResult(genericParseResult) {
         const [name, sqlContents] = stringAwareParseLine(genericParseResult.header);
         return new Query({
@@ -15,6 +25,7 @@ export class Query extends DateEntry {
             sqlContents: parseString(sqlContents).trim(),
         });
     }
+    /** @inheritdoc */
     toString() {
         return `${this.getDateTypePrefix()} "${this.name}" "${this.sqlContents}"${this.getMetaDataString()}`;
     }

package/build/src/classes/entryTypes/Transaction/Posting.d.mts

@@ -1,16 +1,57 @@
 import { FormatOptions } from '../../Entry.mjs';
+/**
+ * Represents a single posting (account movement) within a transaction.
+ * Each posting records an amount moving to/from an account.
+ */
 export declare class Posting {
+    /** Optional posting flag (e.g., '*' for cleared) */
     flag?: string;
+    /** The account name for this posting */
     account: string;
+    /** The amount as a string (may be omitted for auto-calculated postings) */
     amount?: string;
+    /** The currency code for the amount */
     currency?: string;
+    /** Optional cost specification (e.g., for currency conversions) */
     cost?: string;
+    /** Currency for the price annotation */
     priceCurrency?: string;
+    /** Amount for the price annotation */
     priceAmount?: string;
+    /** Optional comment for this posting */
     comment?: string;
+    /**
+     * Creates a new Posting instance.
+     * @param obj - Object containing posting properties
+     */
     constructor(obj: Record<string, unknown>);
+    /**
+     * Parses a posting line string into a Posting instance.
+     * Expected format: [Flag] Account [Amount Currency] [{Cost}] [@ PriceAmount PriceCurrency] [; Comment]
+     *
+     * @param unparsedline - The posting line string to parse
+     * @returns A new Posting instance
+     * @throws {Error} If the posting line cannot be parsed
+     */
     static fromGenericParseResult(unparsedline: string): Posting;
+    /**
+     * Gets the formatted price string combining amount, currency, cost, and price annotation.
+     * @returns The formatted price string, or undefined if no price components exist
+     */
     get price(): string | undefined;
+    /**
+     * Converts this posting to a string representation.
+     * Delegates to toFormattedString with zero currency column alignment.
+     *
+     * @returns The string representation of this posting
+     */
     toString(): string;
+    /**
+     * Converts this posting to a formatted string with aligned currency column.
+     * Adds padding before the price to align at the specified column.
+     *
+     * @param formatOptions - Formatting options including currency column position
+     * @returns The formatted string representation of this posting
+     */
     toFormattedString(formatOptions: FormatOptions): string;
 }

package/build/src/classes/entryTypes/Transaction/Posting.mjs

@@ -1,8 +1,24 @@
 import { formatPrice } from '../../../utils/formatPrice.mjs';
+/**
+ * Represents a single posting (account movement) within a transaction.
+ * Each posting records an amount moving to/from an account.
+ */
 export class Posting {
+    /**
+     * Creates a new Posting instance.
+     * @param obj - Object containing posting properties
+     */
     constructor(obj) {
         Object.assign(this, obj);
     }
+    /**
+     * Parses a posting line string into a Posting instance.
+     * Expected format: [Flag] Account [Amount Currency] [{Cost}] [@ PriceAmount PriceCurrency] [; Comment]
+     *
+     * @param unparsedline - The posting line string to parse
+     * @returns A new Posting instance
+     * @throws {Error} If the posting line cannot be parsed
+     */
     static fromGenericParseResult(unparsedline) {
         // [Flag] Account Amount [{Cost}] [@ Price]
         const matches = /^(?:([^ ]) )?([^ ]*)(?: +([^A-Z]*) +(\w+)(?: +{(.*)})?(?: +@ +(?:(\d+\.?\d*) (\w+)))?)?( *;.*)?$/.exec(unparsedline);
@@ -21,12 +37,29 @@ export class Posting {
             comment: comment?.replace(/^ *;/, '').trim(),
         });
     }
+    /**
+     * Gets the formatted price string combining amount, currency, cost, and price annotation.
+     * @returns The formatted price string, or undefined if no price components exist
+     */
     get price() {
         return formatPrice(this.amount, this.currency, this.cost, this.priceAmount, this.priceCurrency);
     }
+    /**
+     * Converts this posting to a string representation.
+     * Delegates to toFormattedString with zero currency column alignment.
+     *
+     * @returns The string representation of this posting
+     */
     toString() {
         return this.toFormattedString({ currencyColumn: 0 });
     }
+    /**
+     * Converts this posting to a formatted string with aligned currency column.
+     * Adds padding before the price to align at the specified column.
+     *
+     * @param formatOptions - Formatting options including currency column position
+     * @returns The formatted string representation of this posting
+     */
     toFormattedString(formatOptions) {
         const parts = [];
         if (this.flag !== undefined) {

package/build/src/classes/entryTypes/Transaction/Tag.d.mts

@@ -1,9 +1,28 @@
+/**
+ * Represents a tag associated with a transaction.
+ * Tags can be specified inline in the transaction or inherited from a tag stack (pushtag/poptag).
+ */
 export declare class Tag {
+    /** The tag name/content (without the '#' prefix) */
     content: string;
+    /** Whether this tag comes from the tag stack (pushtag) or is inline */
     fromStack: boolean;
+    /**
+     * Creates a new Tag instance.
+     * @param obj - Object containing tag content and source information
+     * @param obj.content - The tag name/content
+     * @param obj.fromStack - Whether this tag is from the tag stack
+     */
     constructor(obj: {
         content: string;
         fromStack: boolean;
     });
+    /**
+     * Converts this tag to its string representation.
+     * Tags from the stack return an empty string (they're implicit),
+     * while inline tags return '#tagname' format.
+     *
+     * @returns The tag string with '#' prefix, or empty string if from stack
+     */
     toString(): string;
 }

package/build/src/classes/entryTypes/Transaction/Tag.mjs

@@ -1,7 +1,24 @@
+/**
+ * Represents a tag associated with a transaction.
+ * Tags can be specified inline in the transaction or inherited from a tag stack (pushtag/poptag).
+ */
 export class Tag {
+    /**
+     * Creates a new Tag instance.
+     * @param obj - Object containing tag content and source information
+     * @param obj.content - The tag name/content
+     * @param obj.fromStack - Whether this tag is from the tag stack
+     */
     constructor(obj) {
         Object.assign(this, obj);
     }
+    /**
+     * Converts this tag to its string representation.
+     * Tags from the stack return an empty string (they're implicit),
+     * while inline tags return '#tagname' format.
+     *
+     * @returns The tag string with '#' prefix, or empty string if from stack
+     */
     toString() {
         if (this.fromStack) {
             return '';

package/build/src/classes/entryTypes/Transaction/index.d.mts

@@ -3,15 +3,56 @@ import { FormatOptions } from '../../Entry.mjs';
 import { DateEntry } from '../../DateEntry.mjs';
 import { Posting } from './Posting.mjs';
 import { Tag } from './Tag.mjs';
+/**
+ * Represents a Beancount transaction entry.
+ * Transactions record financial movements between accounts with postings.
+ */
 export declare class Transaction extends DateEntry {
+    /** @inheritdoc */
     type: "transaction";
+    /** The payee of the transaction */
     payee: string;
+    /** Optional narration/description of the transaction */
     narration?: string;
+    /** Optional transaction flag (e.g., '*' for cleared, '!' for pending) */
     flag?: string;
+    /** Array of postings (account movements) in this transaction */
     postings: Posting[];
-    links: string[];
+    /** Set of link identifiers associated with this transaction */
+    links: Set<string>;
+    /** Array of tags associated with this transaction (from inline tags and tag stack) */
     tags: Tag[];
+    /**
+     * Creates a Transaction instance from a generic parse result.
+     * Parses payee, narration, links, tags, postings, and metadata.
+     *
+     * @param genericParseResult - The parsed transaction data
+     * @returns A new Transaction instance
+     */
     static fromGenericParseResult(genericParseResult: GenericParseResultTransaction): Transaction;
+    /** @inheritdoc */
     toString(): string;
+    /** @inheritdoc */
     toFormattedString(formatOptions: FormatOptions): string;
+    /**
+     * Converts this transaction to a JSON-serializable object.
+     * Ensures the links Set is properly serialized as an array.
+     *
+     * @returns A JSON-serializable representation of this transaction
+     */
+    toJSON(): this & {
+        links: string[];
+    };
+    /**
+     * Transforms JSON data before creating a Transaction instance.
+     * Deserializes transaction-specific properties including postings, tags, links, and metadata.
+     *
+     * @param json - The JSON data to transform
+     * @returns The transformed data with:
+     *   - postings converted to Posting instances
+     *   - tags converted to Tag instances
+     *   - links converted from array to Set<string>
+     *   - metadata values converted to Value instances
+     */
+    protected parseJSONData(json: Record<string, unknown>): Record<string, unknown>;
 }

package/build/src/classes/entryTypes/Transaction/index.mjs

@@ -1,13 +1,25 @@
 import { assertEntryConstructor } from '../../Entry.mjs';
 import { DateEntry } from '../../DateEntry.mjs';
 import { stringAwareParseLine } from '../../../utils/stringAwareParseLine.mjs';
-import { parseString } from '../../Value.mjs';
+import { parseString, Value } from '../../Value.mjs';
 import { parseMetadata } from '../../../utils/parseMetadata.mjs';
 import { Posting } from './Posting.mjs';
 import { Tag } from './Tag.mjs';
+/**
+ * Valid Beancount account type prefixes.
+ * @internal
+ */
 const AccountTypes = ['Assets', 'Liabilities', 'Equity', 'Income', 'Expenses'];
+/**
+ * Parses a string to extract narration/payee, links, and tags.
+ * Links are prefixed with '^' and tags with '#'.
+ *
+ * @param input - The string to parse (may contain narration in quotes, links, and tags)
+ * @returns An object containing extracted links, tags, and the remaining string (narration/payee)
+ * @internal
+ */
 const getStringLinksAndTags = (input) => {
-    let links = [];
+    let links = new Set();
     let tags = [];
     // default if no narration
     let strRemaining = '';
@@ -21,7 +33,7 @@ const getStringLinksAndTags = (input) => {
     }
     const linksMatch = linksAndTags.matchAll(/\^([\w-]*)/g);
     if (linksMatch) {
-        links = linksMatch.map((m) => m[1]).toArray();
+        links = new Set(linksMatch.map((m) => m[1]));
     }
     const tagsMatch = linksAndTags.matchAll(/#([\w-]*)/g);
     if (tagsMatch) {
@@ -31,15 +43,27 @@ const getStringLinksAndTags = (input) => {
     }
     return { links, tags, string: strRemaining };
 };
+/**
+ * Represents a Beancount transaction entry.
+ * Transactions record financial movements between accounts with postings.
+ */
 export class Transaction extends DateEntry {
     constructor() {
         super(...arguments);
+        /** @inheritdoc */
         this.type = 'transaction';
     }
+    /**
+     * Creates a Transaction instance from a generic parse result.
+     * Parses payee, narration, links, tags, postings, and metadata.
+     *
+     * @param genericParseResult - The parsed transaction data
+     * @returns A new Transaction instance
+     */
     static fromGenericParseResult(genericParseResult) {
         // eslint-disable-next-line prefer-const
         let [payee, ...rest] = stringAwareParseLine(genericParseResult.header);
-        let links = [];
+        let links = new Set();
         let tags = [];
         let narration;
         if (rest.length === 0) {
@@ -79,9 +103,11 @@ export class Transaction extends DateEntry {
             tags,
         });
     }
+    /** @inheritdoc */
     toString() {
         return this.toFormattedString({ currencyColumn: 0 });
     }
+    /** @inheritdoc */
     toFormattedString(formatOptions) {
         const firstLine = [
             this.date.toJSON(),
@@ -91,12 +117,50 @@ export class Transaction extends DateEntry {
         if (this.narration !== undefined) {
             firstLine.push(`"${this.narration}"`);
         }
-        firstLine.push(...this.links.map((l) => `^${l}`));
+        firstLine.push(...this.links.values().map((l) => `^${l}`));
         firstLine.push(...this.tags.map((t) => t.toString()));
         const lines = [firstLine.join(' ') + this.getMetaDataString()];
         lines.push(...this.postings.map((p) => `  ${p.toFormattedString(formatOptions)}`));
         return lines.join('\n');
     }
+    /**
+     * Converts this transaction to a JSON-serializable object.
+     * Ensures the links Set is properly serialized as an array.
+     *
+     * @returns A JSON-serializable representation of this transaction
+     */
+    toJSON() {
+        return {
+            ...this,
+            links: Array.from(this.links),
+        };
+    }
+    /**
+     * Transforms JSON data before creating a Transaction instance.
+     * Deserializes transaction-specific properties including postings, tags, links, and metadata.
+     *
+     * @param json - The JSON data to transform
+     * @returns The transformed data with:
+     *   - postings converted to Posting instances
+     *   - tags converted to Tag instances
+     *   - links converted from array to Set<string>
+     *   - metadata values converted to Value instances
+     */
+    parseJSONData(json) {
+        const { postings, tags, links, metadata, ...rest } = json;
+        return {
+            ...rest,
+            postings: postings?.map((p) => new Posting(p)),
+            tags: tags?.map((t) => new Tag(t)),
+            links: links ? new Set(links) : new Set(),
+            metadata: metadata
+                ? Object.fromEntries(Object.entries(metadata).map(([key, val]) => [
+                    key,
+                    new Value(val),
+                ]))
+                : undefined,
+        };
+    }
 }
 // Ensure class conforms to EntryConstructor pattern
 assertEntryConstructor(Transaction);

package/build/src/entryTypeToClass.d.mts

@@ -0,0 +1,59 @@
+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';
+/**
+ * Union type of all valid Beancount entry type names.
+ * EntryTypes derived from https://beancount.github.io/docs/beancount_language_syntax.html#directives-1
+ * Entries can have two additional 'fake' types: 'comment' and 'blankline', see {@link EntryType}
+ */
+export type BeancountEntryType = 'transaction' | 'balance' | 'close' | 'commodity' | 'custom' | 'document' | 'event' | 'include' | 'note' | 'open' | 'option' | 'pad' | 'plugin' | 'poptag' | 'price' | 'pushtag' | 'query';
+/**
+ * Union type of all valid entry type names, including the 'fake' entry types of comment and blankline.
+ */
+export type EntryType = BeancountEntryType | 'comment' | 'blankline';
+/**
+ * Mapping of Beancount entry type names to their corresponding class constructors.
+ * @internal
+ */
+export declare const beancountEntryToClass: {
+    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 entry type names (including 'comment' and 'blankline') to their corresponding class constructors.
+ * @internal
+ */
+export declare const entryTypeToClass: {
+    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/entryTypeToClass.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/entryTypes/index.mjs';
+/**
+ * Mapping of Beancount entry type names to their corresponding class constructors.
+ * @internal
+ */
+export const beancountEntryToClass = {
+    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: beancountEntryToClass must have all BeancountEntryType keys
+beancountEntryToClass;
+/**
+ * Mapping of all entry type names (including 'comment' and 'blankline') to their corresponding class constructors.
+ * @internal
+ */
+export const entryTypeToClass = {
+    ...beancountEntryToClass,
+    comment: Comment,
+    blankline: Blankline,
+};
+// Compile-time assertion: entryTypeToClass must have all EntryType keys
+beancountEntryToClass;