beancount 0.0.31 → 0.2.0

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

@@ -0,0 +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/nodes/Transaction/Tag.mjs

@@ -0,0 +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 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 '';
+        }
+        return `#${this.content}`;
+    }
+}

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

@@ -0,0 +1,70 @@
+import { Temporal } from '@js-temporal/polyfill';
+import type { GenericParseResultTransaction } from '../../../genericParse.mjs';
+import { DatedNode } from '../../DatedNode.mjs';
+import { Posting } from './Posting.mjs';
+import { Tag } from './Tag.mjs';
+import { FormatOptions } from '../../ParseResult.mjs';
+export interface PostingComment {
+    order: number;
+    comment: string;
+}
+/**
+ * Represents a Beancount transaction node.
+ * Transactions record financial movements between accounts with postings.
+ */
+export declare class Transaction extends DatedNode {
+    /** @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[];
+    /** Array of comments under this transaction (mixed in with the postings) */
+    postingComments: PostingComment[];
+    /** 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[];
+    /**
+     * @inheritdoc
+     */
+    constructor(obj: {
+        date: string | Temporal.PlainDate;
+        [key: string]: unknown;
+    });
+    /**
+     * 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(): Record<string, unknown>;
+    /**
+     * 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/nodes/Transaction/index.mjs

@@ -0,0 +1,193 @@
+import { assertNodeConstructor } from '../../Node.mjs';
+import { DatedNode } from '../../DatedNode.mjs';
+import { stringAwareParseLine } from '../../../utils/stringAwareParseLine.mjs';
+import { parseString, Value } from '../../Value.mjs';
+import { parseMetadata } from '../../../utils/parseMetadata.mjs';
+import { Posting } from './Posting.mjs';
+import { Tag } from './Tag.mjs';
+import { defaultFormatOptions } from '../../ParseResult.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 = new Set();
+    let tags = [];
+    // default if no narration
+    let strRemaining = '';
+    let linksAndTags = input;
+    // check for narration
+    const match = /^(".*")(.*)/.exec(input);
+    if (match) {
+        // strRemaining = narration
+        strRemaining = match[1];
+        linksAndTags = match[2];
+    }
+    const linksMatch = linksAndTags.matchAll(/\^([\w-_.]*)/g);
+    if (linksMatch) {
+        links = new Set(linksMatch.map((m) => m[1]));
+    }
+    const tagsMatch = linksAndTags.matchAll(/#([\w-_.]*)/g);
+    if (tagsMatch) {
+        tags = tagsMatch
+            .map((m) => new Tag({ content: m[1], fromStack: false }))
+            .toArray();
+    }
+    return { links, tags, string: strRemaining };
+};
+/**
+ * Represents a Beancount transaction node.
+ * Transactions record financial movements between accounts with postings.
+ */
+export class Transaction extends DatedNode {
+    /**
+     * @inheritdoc
+     */
+    constructor(obj) {
+        /*
+         * This constructor exists to provide a default value for some values.
+         * Class field initializers (e.g., `postingComments = []`) run after
+         * `super()` returns, which would overwrite values set by `Object.assign`
+         * in the parent constructor.
+         */
+        super(obj);
+        /** @inheritdoc */
+        this.type = 'transaction';
+        this.postingComments ??= [];
+        this.postings ??= [];
+        this.links ??= new Set();
+        this.tags ??= [];
+    }
+    /**
+     * 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 = new Set();
+        let tags = [];
+        let narration;
+        if (rest.length === 0) {
+            // no narration
+            const payeeParsed = getStringLinksAndTags(payee);
+            payee = payeeParsed.string;
+            links = payeeParsed.links;
+            tags = payeeParsed.tags;
+        }
+        else {
+            const payeeParsed = getStringLinksAndTags(rest.join(' '));
+            narration = payeeParsed.string;
+            links = payeeParsed.links;
+            tags = payeeParsed.tags;
+        }
+        const unparsedPostings = [];
+        const unparsedMetadata = [];
+        const postingComments = [];
+        genericParseResult.body.forEach((line) => {
+            //                           V remove flag,       V get account type
+            const accountType = line.replace(/^[^ ] /, '').split(':')[0];
+            if (AccountTypes.includes(accountType)) {
+                unparsedPostings.push(line);
+            }
+            else if (line.startsWith(';')) {
+                postingComments.push({
+                    comment: line,
+                    order: unparsedPostings.length + postingComments.length,
+                });
+            }
+            else {
+                unparsedMetadata.push(line);
+            }
+        });
+        const postings = unparsedPostings.map((p) => Posting.fromString(p));
+        const metadata = parseMetadata(unparsedMetadata);
+        return new Transaction({
+            ...genericParseResult.props,
+            payee: parseString(payee),
+            narration: narration ? parseString(narration) : undefined,
+            postings,
+            postingComments,
+            metadata,
+            links,
+            tags,
+        });
+    }
+    /** @inheritdoc */
+    toString() {
+        return this.toFormattedString({ currencyColumn: 0 });
+    }
+    /** @inheritdoc */
+    toFormattedString(formatOptions = defaultFormatOptions) {
+        const firstLine = [
+            this.date.toJSON(),
+            this.flag ?? 'txn',
+            `"${this.payee}"`,
+        ];
+        if (this.narration !== undefined) {
+            firstLine.push(`"${this.narration}"`);
+        }
+        firstLine.push(...this.links.values().map((l) => `^${l}`));
+        firstLine.push(...this.tags.map((t) => t.toString()));
+        const lines = [firstLine.join(' ') + this.getMetaDataString()];
+        const postingLines = this.postings.map((p) => `  ${p.toFormattedString(formatOptions)}`);
+        this.postingComments.forEach((comment) => {
+            postingLines.splice(comment.order, 0, `  ${comment.comment}`);
+        });
+        lines.push(...postingLines);
+        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, postingComments, tags, links, metadata, ...rest } = json;
+        return {
+            ...rest,
+            postings: postings?.map((p) => new Posting(p)),
+            postingComments: postingComments ?? [],
+            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 NodeConstructor pattern
+assertNodeConstructor(Transaction);

package/build/src/classes/nodes/index.d.mts

@@ -0,0 +1,19 @@
+export { Transaction } from './Transaction/index.mjs';
+export { Balance } from './Balance.mjs';
+export { Blankline } from './Blankline.mjs';
+export { Close } from './Close.mjs';
+export { Comment } from './Comment.mjs';
+export { Commodity } from './Commodity.mjs';
+export { Custom } from './Custom.mjs';
+export { Document } from './Document.mjs';
+export { Event } from './Event.mjs';
+export { Include } from './Include.mjs';
+export { Note } from './Note.mjs';
+export { Open } from './Open.mjs';
+export { Option } from './Option.mjs';
+export { Pad } from './Pad.mjs';
+export { Plugin } from './Plugin.mjs';
+export { Price } from './Price.mjs';
+export { Poptag } from './Poptag.mjs';
+export { Pushtag } from './Pushtag.mjs';
+export { Query } from './Query.mjs';

package/build/src/classes/nodes/index.mjs

@@ -0,0 +1,19 @@
+export { Transaction } from './Transaction/index.mjs';
+export { Balance } from './Balance.mjs';
+export { Blankline } from './Blankline.mjs';
+export { Close } from './Close.mjs';
+export { Comment } from './Comment.mjs';
+export { Commodity } from './Commodity.mjs';
+export { Custom } from './Custom.mjs';
+export { Document } from './Document.mjs';
+export { Event } from './Event.mjs';
+export { Include } from './Include.mjs';
+export { Note } from './Note.mjs';
+export { Open } from './Open.mjs';
+export { Option } from './Option.mjs';
+export { Pad } from './Pad.mjs';
+export { Plugin } from './Plugin.mjs';
+export { Price } from './Price.mjs';
+export { Poptag } from './Poptag.mjs';
+export { Pushtag } from './Pushtag.mjs';
+export { Query } from './Query.mjs';

package/build/src/cli.mjs

@@ -36,7 +36,7 @@ Examples:
  * @param filePath Path to the file to format
  * @param write Whether to write the formatted content back to the file
  * @param currencyColumn Currency column number, or null to auto-calculate
- * @param force Wether to also format files with 0 entries, defaults to false
+ * @param force Wether to also format files without any Beancount directives, defaults to false
  * @returns Resolves to true if successful, false if an error occurred
  */
 async function formatFile(filePath, write, currencyColumn, force = false) {
@@ -49,11 +49,11 @@ async function formatFile(filePath, write, currencyColumn, force = false) {
         }
         // Read and parse the beancount file
         const parseResult = await parseFile(filePath);
-        // check if we have any non-comment non-blankline entries
+        // check if we have any Beancount directives
         if (!force &&
-            parseResult.entries.length ===
+            parseResult.nodes.length ===
                 parseResult.blankline.length + parseResult.comment.length) {
-            console.error(`Error processing ${filePath}: does not seem to be a beancount file, it has no entries`);
+            console.error(`Error processing ${filePath}: does not seem to be a beancount file, it has no Beancount directives`);
             return false;
         }
         // Determine currency column

package/build/src/deserialize.d.mts

@@ -1,58 +1,58 @@
-import { Entry } from './classes/Entry.mjs';
+import { Node } from './classes/Node.mjs';
 /**
- * Deserializes a single entry from its JSON representation.
+ * Deserializes a single node from its JSON representation.
  *
  * This function takes a plain JavaScript object (typically from JSON.parse)
- * and reconstructs the appropriate Entry subclass instance. It validates
+ * and reconstructs the appropriate Node subclass instance. It validates
  * the input and provides helpful error messages for common issues.
  *
- * @param entryData - Plain object containing entry data with a 'type' field
- * @returns An Entry instance of the appropriate subclass
- * @throws {Error} If the entry data is invalid:
+ * @param nodeData - Plain object containing node data with a 'type' field
+ * @returns An Node instance of the appropriate subclass
+ * @throws {Error} If the node data is invalid:
  *   - Missing or invalid 'type' field
- *   - Unknown entry type
- *   - Invalid entry structure (errors from Entry.fromJSONData)
+ *   - Unknown node type
+ *   - Invalid node structure (errors from Node.fromJSONData)
  *
  * @example
- * Deserializing a simple entry:
+ * Deserializing a simple node:
  * ```typescript
- * const entryData = {
+ * const nodeData = {
  *   type: 'open',
  *   date: '2024-01-01',
  *   account: 'Assets:Checking'
  * }
- * const entry = deserializeEntry(entryData)
- * console.log(entry.type) // 'open'
+ * const node = deserializeNode(nodeData)
+ * console.log(node.type) // 'open'
  * ```
  *
  * @example
  * Deserializing from JSON.parse:
  * ```typescript
  * const json = '{"type":"balance","date":"2024-01-02","account":"Assets:Checking","amount":"100","currency":"USD"}'
- * const entryData = JSON.parse(json)
- * const entry = deserializeEntry(entryData)
+ * const nodeData = JSON.parse(json)
+ * const node = deserializeNode(nodeData)
  * ```
  */
-export declare function deserializeEntry(entryData: Record<string, unknown>): Entry;
+export declare function deserializeNode(nodeData: Record<string, unknown>): Node;
 /**
- * Deserializes a single entry from a JSON string.
+ * Deserializes a single node from a JSON string.
  *
- * This function parses a JSON string containing an entry object
- * and reconstructs the appropriate Entry subclass instance.
+ * This function parses a JSON string containing an node object
+ * and reconstructs the appropriate Node subclass instance.
  *
- * @param jsonString - JSON string containing an entry object
- * @returns An Entry instance of the appropriate subclass
- * @throws {Error} If the JSON is invalid or entry cannot be deserialized:
+ * @param jsonString - JSON string containing an node object
+ * @returns An Node instance of the appropriate subclass
+ * @throws {Error} If the JSON is invalid or node cannot be deserialized:
  *   - Invalid JSON syntax
  *   - JSON does not contain an object
- *   - Entry validation errors (see deserializeEntry)
+ *   - Node validation errors (see deserializeNode)
  *
  * @example
  * Deserializing from a JSON string:
  * ```typescript
  * const json = '{"type":"open","date":"2024-01-01","account":"Assets:Checking"}'
- * const entry = deserializeEntryFromString(json)
- * console.log(entry.type) // 'open'
+ * const node = deserializeNodeFromString(json)
+ * console.log(node.type) // 'open'
  * ```
  *
  * @example
@@ -60,34 +60,34 @@ export declare function deserializeEntry(entryData: Record<string, unknown>): En
  * ```typescript
  * const original = Open.fromString('2024-01-01 open Assets:Checking')
  * const json = JSON.stringify(original.toJSON())
- * const deserialized = deserializeEntryFromString(json)
+ * const deserialized = deserializeNodeFromString(json)
  * // deserialized equals original
  * ```
  */
-export declare function deserializeEntryFromString(jsonString: string): Entry;
+export declare function deserializeNodeFromString(jsonString: string): Node;
 /**
- * Deserializes an array of entries from their JSON representations.
+ * Deserializes an array of nodes from their JSON representations.
  *
  * This function takes an array of plain JavaScript objects (typically from JSON.parse)
- * and reconstructs each as the appropriate Entry subclass instance. It validates
- * the input and provides helpful error messages, including the index of any entry
+ * and reconstructs each as the appropriate Node subclass instance. It validates
+ * the input and provides helpful error messages, including the index of any node
  * that fails to deserialize.
  *
- * @param entriesData - Array of plain objects containing entry data
- * @returns Array of Entry instances
- * @throws {Error} If the input is invalid or entries cannot be deserialized:
+ * @param nodesData - Array of plain objects containing node data
+ * @returns Array of Node instances
+ * @throws {Error} If the input is invalid or nodes cannot be deserialized:
  *   - Input is not an array
- *   - Any entry fails validation (see deserializeEntry)
+ *   - Any node fails validation (see deserializeNode)
  *
  * @example
- * Deserializing an array of entries:
+ * Deserializing an array of nodes:
  * ```typescript
- * const entriesData = [
+ * const nodesData = [
  *   { type: 'open', date: '2024-01-01', account: 'Assets:Checking' },
  *   { type: 'balance', date: '2024-01-02', account: 'Assets:Checking', amount: '100', currency: 'USD' }
  * ]
- * const entries = deserializeEntries(entriesData)
- * console.log(entries.length) // 2
+ * const nodes = deserializeNodes(nodesData)
+ * console.log(nodes.length) // 2
  * ```
  *
  * @example
@@ -96,35 +96,35 @@ export declare function deserializeEntryFromString(jsonString: string): Entry;
  * const original = [Open.fromString('2024-01-01 open Assets:Checking')]
  * const json = JSON.stringify(original.map(e => e.toJSON()))
  * const parsed = JSON.parse(json)
- * const deserialized = deserializeEntries(parsed)
+ * const deserialized = deserializeNodes(parsed)
  * // deserialized equals original
  * ```
  */
-export declare function deserializeEntries(entriesData: Record<string, unknown>[]): Entry[];
+export declare function deserializeNodes(nodesData: Record<string, unknown>[]): Node[];
 /**
- * Deserializes an array of entries from a JSON string.
+ * Deserializes an array of nodes from a JSON string.
  *
- * This function parses a JSON string containing an array of entry objects
- * and reconstructs each entry as the appropriate Entry subclass instance.
+ * This function parses a JSON string containing an array of node objects
+ * and reconstructs each node as the appropriate Node subclass instance.
  * It validates the input and provides helpful error messages, including
- * the index of any entry that fails to deserialize.
+ * the index of any node that fails to deserialize.
  *
- * @param jsonString - JSON string containing an array of entry objects
- * @returns Array of Entry instances
- * @throws {Error} If the JSON is invalid or entries cannot be deserialized:
+ * @param jsonString - JSON string containing an array of node objects
+ * @returns Array of Node instances
+ * @throws {Error} If the JSON is invalid or nodes cannot be deserialized:
  *   - Invalid JSON syntax
  *   - JSON does not contain an array
- *   - Any entry fails validation (see deserializeEntry)
+ *   - Any node fails validation (see deserializeNode)
  *
  * @example
- * Deserializing multiple entries:
+ * Deserializing multiple nodes:
  * ```typescript
  * const json = '[
  *   {"type": "open", "date": "2024-01-01", "account": "Assets:Checking"},
  *   {"type": "balance", "date": "2024-01-02", "account": "Assets:Checking", "amount": "100", "currency": "USD"}
  * ]'
- * const entries = deserializeEntries(json)
- * console.log(entries.length) // 2
+ * const nodes = deserializeNodes(json)
+ * console.log(nodes.length) // 2
  * ```
  *
  * @example
@@ -133,9 +133,9 @@ export declare function deserializeEntries(entriesData: Record<string, unknown>[
  * import { parse } from 'beancount'
  *
  * const original = parse('2024-01-01 open Assets:Checking')
- * const json = JSON.stringify(original.entries.map(e => e.toJSON()))
- * const deserialized = deserializeEntries(json)
- * // deserialized equals original.entries
+ * const json = JSON.stringify(original.nodes.map(e => e.toJSON()))
+ * const deserialized = deserializeNodes(json)
+ * // deserialized equals original.nodes
  * ```
  */
-export declare function deserializeEntriesFromString(jsonString: string): Entry[];
+export declare function deserializeNodesFromString(jsonString: string): Node[];