beancount 0.0.1

package/README.md

@@ -0,0 +1,82 @@
+# beancount
+
+A parser and editor for Beancount accounting files with full type safety.
+
+## Installation
+
+```bash
+npm install beancount
+```
+
+## Features
+
+- **Full Beancount Support** - All directives supported: transactions, open/close, balance, pad, note, document, price, event, query, custom, commodity, include, option, plugin, pushtag/poptag
+- **Type-Safe** - Complete TypeScript types for all entries and components
+- **Rich Transaction Support** - Tags, links, metadata, costs, price annotations, and postings
+- **Round-Trip Parsing** - Parse to objects and serialize back to text
+- **Formatted Output** - Column-aligned output with `toFormattedString()` (WIP)
+
+## Quick Start
+
+```typescript
+import { parse } from 'beancount'
+
+const beancountContent = `
+2024-01-01 open Assets:Checking USD
+
+2024-01-15 * "Grocery Store" "Weekly shopping"
+  Assets:Checking   -50.00 USD
+  Expenses:Food      50.00 USD
+`
+
+const result = parse(beancountContent)
+
+// Access parsed entries
+console.log(result.entries.length) // 2
+
+// Convert back to string
+console.log(result.toString())
+
+// Or with formatted output (aligned columns)
+// only partially implemented at this point
+console.log(result.toFormattedString())
+```
+
+## Documentation
+
+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:
+
+```bash
+# Install dependencies
+make install
+
+# Build the project
+make build
+
+# Run tests
+make test
+
+# Run linting (prettier, tsc, eslint, typedoc)
+make lint
+
+# Generate documentation
+make docs
+```
+
+## Requirements
+
+- Node.js >= 22
+
+## License
+
+ISC

package/build/src/benchmark.d.mts

@@ -0,0 +1 @@
+export {};

package/build/src/benchmark.mjs

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import { parse } from './parse.mjs';
+const file = './test/example-full.beancount';
+const fileBuffer = fs.readFileSync(file);
+const fileText = fileBuffer.toString();
+const fileSizeKB = fileBuffer.length / 1024;
+console.log(`File size: ${fileSizeKB.toFixed(2)} KB`);
+console.log(`String length: ${fileText.length} characters`);
+console.log('---');
+const iterations = 10;
+const durations = [];
+let lastResult = parse(fileText);
+console.log(`Running ${iterations} iterations...`);
+for (let i = 0; i < iterations; i++) {
+    const startTime = performance.now();
+    lastResult = parse(fileText);
+    const endTime = performance.now();
+    durations.push(endTime - startTime);
+}
+const avgDuration = durations.reduce((a, b) => a + b, 0) / iterations;
+const avgDurationSeconds = avgDuration / 1000;
+const minDuration = Math.min(...durations);
+const maxDuration = Math.max(...durations);
+console.log(`Average parse time: ${avgDuration.toFixed(3)} ms`);
+console.log(`Min: ${minDuration.toFixed(3)} ms, Max: ${maxDuration.toFixed(3)} ms`);
+console.log(`Average throughput: ${(fileSizeKB / avgDurationSeconds / 1000).toFixed(2)} MB/s`);
+console.log('---');
+console.log(`Parsed ${lastResult.entries.length} items`);

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

@@ -0,0 +1,4 @@
+import { Entry } from './Entry.mjs';
+export declare class Booking extends Entry {
+    type: "booking";
+}

package/build/src/classes/Booking.mjs

@@ -0,0 +1,7 @@
+import { Entry } from './Entry.mjs';
+export class Booking extends Entry {
+    constructor() {
+        super(...arguments);
+        this.type = 'booking';
+    }
+}

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

@@ -0,0 +1,25 @@
+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'>;
+/**
+ * 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;
+    date: Temporal.PlainDate;
+    metadata?: Record<string, Value>;
+    constructor(obj: {
+        date: string;
+        [key: string]: unknown;
+    });
+    /**
+     * Returns the common prefix for all DateEntry toString methods.
+     * Format: "YYYY-MM-DD <type>"
+     */
+    protected getDateTypePrefix(): string;
+    getMetaDataString(): string;
+}

package/build/src/classes/DateEntry.mjs

@@ -0,0 +1,33 @@
+import { Temporal } from '@js-temporal/polyfill';
+import { Entry } from './Entry.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 {
+    constructor(obj) {
+        const { date, ...props } = obj;
+        super(props);
+        if (date) {
+            this.date = Temporal.PlainDate.from(date, { overflow: 'reject' });
+        }
+    }
+    /**
+     * Returns the common prefix for all DateEntry toString methods.
+     * Format: "YYYY-MM-DD <type>"
+     */
+    getDateTypePrefix() {
+        return `${this.date.toJSON()} ${this.type}`;
+    }
+    getMetaDataString() {
+        const comment = this.comment ? ` ; ${this.comment}` : '';
+        if (!this.metadata) {
+            return comment;
+        }
+        return (`${comment}\n` +
+            Object.entries(this.metadata)
+                .map(([key, val]) => `  ${key}: ${val.toString()}`)
+                .join('\n'));
+    }
+}

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

@@ -0,0 +1,30 @@
+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> {
+    fromGenericParseResult(parsedStart: ReturnType<typeof genericParse>): T;
+}
+export interface FormatOptions {
+    currencyColumn: number;
+}
+/**
+ * Abstract base class for all Beancount entry types.
+ *
+ * Child classes must implement static `fromGenericParseResult` method
+ */
+export declare abstract class Entry {
+    comment?: string;
+    abstract type: EntryType | 'comment' | 'blankline';
+    constructor(obj: Record<string, unknown>);
+    static fromString<T extends Entry>(this: EntryConstructor<T>, input: string): T;
+    toFormattedString(_formatOptions: FormatOptions): string;
+}
+/**
+ * Type assertion helper to ensure a class conforms to EntryConstructor.
+ * Usage: assertEntryConstructor(MyEntryClass)
+ */
+export declare function assertEntryConstructor<T extends Entry>(_ctor: EntryConstructor<T>): void;

package/build/src/classes/Entry.mjs

@@ -0,0 +1,33 @@
+import { genericParse } from '../../src/genericParse.mjs';
+import { stringAwareSplitLine } from '../utils/stringAwareSplitLine.mjs';
+/**
+ * Abstract base class for all Beancount entry types.
+ *
+ * Child classes must implement static `fromGenericParseResult` method
+ */
+export class Entry {
+    constructor(obj) {
+        Object.assign(this, obj);
+    }
+    static fromString(input) {
+        const unparsedEntry = stringAwareSplitLine(input);
+        const genericParseResult = genericParse(unparsedEntry);
+        const result = this.fromGenericParseResult(genericParseResult);
+        if (result.type !== genericParseResult.type) {
+            console.warn('Parse result type is not equal to requested object type, make sure the correct class is initiated');
+        }
+        return result;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    toFormattedString(_formatOptions) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string
+        return this.toString();
+    }
+}
+/**
+ * Type assertion helper to ensure a class conforms to EntryConstructor.
+ * Usage: assertEntryConstructor(MyEntryClass)
+ */
+export function assertEntryConstructor(
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_ctor) { }

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

@@ -0,0 +1,9 @@
+import { Entry } from './Entry.mjs';
+export declare class ParseResult {
+    entries: Entry[];
+    constructor(entries: Entry[]);
+    toString(): string;
+    toFormattedString(options?: {
+        width: number;
+    }): string;
+}

package/build/src/classes/ParseResult.mjs

@@ -0,0 +1,19 @@
+const defaultFormattingOptions = {
+    width: 100,
+};
+export class ParseResult {
+    constructor(entries) {
+        this.entries = entries;
+    }
+    toString() {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string
+        return this.entries.map((e) => e.toString()).join('\n');
+    }
+    toFormattedString(options = defaultFormattingOptions) {
+        // TODO: calculate currencyColumn
+        const currencyColumn = 59;
+        return this.entries
+            .map((e) => e.toFormattedString({ currencyColumn }))
+            .join('\n');
+    }
+}

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

@@ -0,0 +1,11 @@
+export declare class Posting {
+    flag?: string;
+    account: string;
+    amount?: string;
+    currency?: string;
+    comment?: string;
+    constructor(obj: Record<string, unknown>);
+    static fromGenericParseResult(unparsedline: string): Posting;
+    get price(): string | undefined;
+    toString(): string;
+}

package/build/src/classes/Posting.mjs

@@ -0,0 +1,37 @@
+import { formatPrice } from '../utils/formatPrice.mjs';
+export class Posting {
+    constructor(obj) {
+        Object.assign(this, obj);
+    }
+    static fromGenericParseResult(unparsedline) {
+        // [Flag] Account Amount [{Cost}] [@ Price]
+        const matches = /^(?:([^ ]) )?([^ ]*)(?: +([^A-Z]*) +(\w+)(?: +{.*})?(?: +@ +(\d+\.?\d* (\w+)))?)?( *;.*)?$/.exec(unparsedline);
+        if (!matches) {
+            throw new Error('Could not parse posting');
+        }
+        const [, flag, account, amount, currency, cost, postingPrice, comment] = matches;
+        return new Posting({
+            flag: flag,
+            account: account?.trim(),
+            amount: amount?.trim(),
+            currency: currency?.trim(),
+            cost: cost?.trim(),
+            postingPrice: postingPrice?.trim(),
+            comment: comment?.replace(/^ *;/, '').trim(),
+        });
+    }
+    get price() {
+        return formatPrice(this.amount, this.currency);
+    }
+    toString() {
+        const parts = [];
+        if (this.flag !== undefined) {
+            parts.push(this.flag);
+        }
+        parts.push(this.account);
+        if (this.price !== undefined) {
+            parts.push(this.price);
+        }
+        return parts.join(' ');
+    }
+}

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

@@ -0,0 +1,4 @@
+import { Entry } from './Entry.mjs';
+export declare class Transaction extends Entry {
+    type: "transaction";
+}

package/build/src/classes/Transaction.mjs

@@ -0,0 +1,7 @@
+import { Entry } from './Entry.mjs';
+export class Transaction extends Entry {
+    constructor() {
+        super(...arguments);
+        this.type = 'transaction';
+    }
+}

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

@@ -0,0 +1,12 @@
+export type ValueType = 'string' | 'date' | 'boolean' | 'amount' | 'numbers';
+export declare const parseString: (val: string) => string;
+export declare class Value {
+    type: ValueType;
+    value: unknown;
+    constructor(obj: {
+        type: ValueType;
+        value: unknown;
+    });
+    static fromString(input: string): Value;
+    toString(): string;
+}

package/build/src/classes/Value.mjs

@@ -0,0 +1,32 @@
+export const parseString = (val) => {
+    return val.replace(/^"|"$/g, '');
+};
+export class Value {
+    constructor(obj) {
+        Object.assign(this, obj);
+    }
+    static fromString(input) {
+        if (input.startsWith('"') && input.endsWith('"')) {
+            // string!
+            return new Value({ type: 'string', value: parseString(input) });
+        }
+        if (input.toUpperCase() === 'TRUE') {
+            return new Value({ type: 'boolean', value: true });
+        }
+        if (input.toUpperCase() === 'FALSE') {
+            return new Value({ type: 'boolean', value: false });
+        }
+        // TODO: more parsing
+        return new Value({ type: 'amount', value: input });
+    }
+    toString() {
+        switch (this.type) {
+            case 'boolean':
+                return this.value ? 'TRUE' : 'FALSE';
+            case 'string':
+                return `"${this.value}"`;
+            default:
+                return String(this.value);
+        }
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { GenericParseResultWithDate } from '../../genericParse.mjs';
+import { FormatOptions } from '../Entry.mjs';
+import { DateEntry } from '../DateEntry.mjs';
+export declare class Balance extends DateEntry {
+    type: "balance";
+    account: string;
+    amount: string;
+    currency: string;
+    get price(): string | undefined;
+    static fromGenericParseResult(genericParseResult: GenericParseResultWithDate): Balance;
+    toString(): string;
+    toFormattedString(formatOptions: FormatOptions): string;
+}

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

@@ -0,0 +1,33 @@
+import { assertEntryConstructor } from '../Entry.mjs';
+import { DateEntry } from '../DateEntry.mjs';
+import { simpleParseLine } from '../../utils/simpleParseLine.mjs';
+import { formatPrice } from '../../utils/formatPrice.mjs';
+export class Balance extends DateEntry {
+    constructor() {
+        super(...arguments);
+        this.type = 'balance';
+    }
+    get price() {
+        return formatPrice(this.amount, this.currency);
+    }
+    static fromGenericParseResult(genericParseResult) {
+        const [account, amount, currency] = simpleParseLine(genericParseResult.header);
+        return new Balance({
+            ...genericParseResult.props,
+            account,
+            amount,
+            currency,
+        });
+    }
+    toString() {
+        return this.toFormattedString({ currencyColumn: 0 });
+    }
+    toFormattedString(formatOptions) {
+        const firstPart = `${this.getDateTypePrefix()} ${this.account}`;
+        const paddingLength = formatOptions.currencyColumn - firstPart.length - this.amount.length - 2; // not sure what this is for
+        const padding = ' '.repeat(Math.max(1, paddingLength));
+        return [firstPart, padding, this.price, this.getMetaDataString()].join('');
+    }
+}
+// Ensure class conforms to EntryConstructor pattern
+assertEntryConstructor(Balance);

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

@@ -0,0 +1,8 @@
+import type { GenericParseResult } from '../../genericParse.mjs';
+import { Entry, EntryConstructor } from '../Entry.mjs';
+export declare class Blankline extends Entry {
+    type: "blankline";
+    static fromGenericParseResult(_genericParseResult: GenericParseResult): Blankline;
+    toString(): string;
+    static fromString<T extends Entry>(this: EntryConstructor<T>, _input: string): T;
+}

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

@@ -0,0 +1,22 @@
+import { assertEntryConstructor, Entry } from '../Entry.mjs';
+export class Blankline extends Entry {
+    constructor() {
+        super(...arguments);
+        this.type = 'blankline';
+    }
+    static fromGenericParseResult(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _genericParseResult) {
+        return new Blankline({});
+    }
+    toString() {
+        return '';
+    }
+    static fromString(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _input) {
+        return this.fromGenericParseResult({});
+    }
+}
+// Ensure class conforms to EntryConstructor pattern
+assertEntryConstructor(Blankline);

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

@@ -0,0 +1,8 @@
+import type { GenericParseResultWithDate } from '../../genericParse.mjs';
+import { DateEntry } from '../DateEntry.mjs';
+export declare class Close extends DateEntry {
+    type: "close";
+    account: string;
+    static fromGenericParseResult(genericParseResult: GenericParseResultWithDate): Close;
+    toString(): string;
+}

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

@@ -0,0 +1,20 @@
+import { assertEntryConstructor } from '../Entry.mjs';
+import { DateEntry } from '../DateEntry.mjs';
+export class Close extends DateEntry {
+    constructor() {
+        super(...arguments);
+        this.type = 'close';
+    }
+    static fromGenericParseResult(genericParseResult) {
+        const account = genericParseResult.header.trim();
+        return new Close({
+            ...genericParseResult.props,
+            account,
+        });
+    }
+    toString() {
+        return `${this.getDateTypePrefix()} ${this.account}${this.getMetaDataString()}`;
+    }
+}
+// Ensure class conforms to EntryConstructor pattern
+assertEntryConstructor(Close);

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

@@ -0,0 +1,8 @@
+import type { GenericParseResult } from '../../genericParse.mjs';
+import { Entry, EntryConstructor } from '../Entry.mjs';
+export declare class Comment extends Entry {
+    type: "comment";
+    static fromGenericParseResult(genericParseResult: GenericParseResult): Comment;
+    toString(): string | undefined;
+    static fromString<T extends Entry>(this: EntryConstructor<T>, input: string): T;
+}

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

@@ -0,0 +1,22 @@
+import { assertEntryConstructor, Entry } from '../Entry.mjs';
+export class Comment extends Entry {
+    constructor() {
+        super(...arguments);
+        this.type = 'comment';
+    }
+    static fromGenericParseResult(genericParseResult) {
+        return new Comment({
+            comment: genericParseResult.props.comment,
+        });
+    }
+    toString() {
+        return this.comment;
+    }
+    static fromString(input) {
+        return this.fromGenericParseResult({
+            props: { comment: input },
+        });
+    }
+}
+// Ensure class conforms to EntryConstructor pattern
+assertEntryConstructor(Comment);

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

@@ -0,0 +1,8 @@
+import type { GenericParseResultWithDate } from '../../genericParse.mjs';
+import { DateEntry } from '../DateEntry.mjs';
+export declare class Commodity extends DateEntry {
+    type: "commodity";
+    currency: string;
+    static fromGenericParseResult(genericParseResult: GenericParseResultWithDate): Commodity;
+    toString(): string;
+}

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

@@ -0,0 +1,20 @@
+import { assertEntryConstructor } from '../Entry.mjs';
+import { DateEntry } from '../DateEntry.mjs';
+export class Commodity extends DateEntry {
+    constructor() {
+        super(...arguments);
+        this.type = 'commodity';
+    }
+    static fromGenericParseResult(genericParseResult) {
+        const currency = genericParseResult.header.trim();
+        return new Commodity({
+            ...genericParseResult.props,
+            currency,
+        });
+    }
+    toString() {
+        return `${this.getDateTypePrefix()} ${this.currency}${this.getMetaDataString()}`;
+    }
+}
+// Ensure class conforms to EntryConstructor pattern
+assertEntryConstructor(Commodity);

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

@@ -0,0 +1,10 @@
+import type { GenericParseResultWithDate } from '../../genericParse.mjs';
+import { DateEntry } from '../DateEntry.mjs';
+import { Value } from '../Value.mjs';
+export declare class Custom extends DateEntry {
+    type: "custom";
+    customType: Value;
+    values?: Value[];
+    static fromGenericParseResult(genericParseResult: GenericParseResultWithDate): Custom;
+    toString(): string;
+}

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

@@ -0,0 +1,27 @@
+import { assertEntryConstructor } from '../Entry.mjs';
+import { DateEntry } from '../DateEntry.mjs';
+import { simpleParseLine } from '../../utils/simpleParseLine.mjs';
+import { Value } from '../Value.mjs';
+export class Custom extends DateEntry {
+    constructor() {
+        super(...arguments);
+        this.type = 'custom';
+    }
+    static fromGenericParseResult(genericParseResult) {
+        const [customType, ...others] = simpleParseLine(genericParseResult.header);
+        return new Custom({
+            ...genericParseResult.props,
+            customType: Value.fromString(customType),
+            values: others.length > 0 ? others.map((o) => Value.fromString(o)) : undefined,
+        });
+    }
+    toString() {
+        const parts = [`${this.getDateTypePrefix()} ${this.customType.toString()}`];
+        if (this.values !== undefined) {
+            parts.push(...this.values.map((v) => v.toString()));
+        }
+        return parts.join(' ') + this.getMetaDataString();
+    }
+}
+// Ensure class conforms to EntryConstructor pattern
+assertEntryConstructor(Custom);

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

@@ -0,0 +1,9 @@
+import type { GenericParseResultWithDate } from '../../genericParse.mjs';
+import { DateEntry } from '../DateEntry.mjs';
+export declare class Document extends DateEntry {
+    type: "document";
+    account: string;
+    pathToDocument: string;
+    static fromGenericParseResult(genericParseResult: GenericParseResultWithDate): Document;
+    toString(): string;
+}

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

@@ -0,0 +1,23 @@
+import { assertEntryConstructor } from '../Entry.mjs';
+import { DateEntry } from '../DateEntry.mjs';
+import { parseString } from '../Value.mjs';
+import { simpleParseLine } from '../../utils/simpleParseLine.mjs';
+export class Document extends DateEntry {
+    constructor() {
+        super(...arguments);
+        this.type = 'document';
+    }
+    static fromGenericParseResult(genericParseResult) {
+        const [account, pathToDocument] = simpleParseLine(genericParseResult.header);
+        return new Document({
+            ...genericParseResult.props,
+            account,
+            pathToDocument: parseString(pathToDocument),
+        });
+    }
+    toString() {
+        return `${this.getDateTypePrefix()} ${this.account} "${this.pathToDocument}"${this.getMetaDataString()}`;
+    }
+}
+// Ensure class conforms to EntryConstructor pattern
+assertEntryConstructor(Document);

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

@@ -0,0 +1,10 @@
+import type { GenericParseResultWithDate } from '../../genericParse.mjs';
+import { DateEntry } from '../DateEntry.mjs';
+import { Value } from '../Value.mjs';
+export declare class Event extends DateEntry {
+    type: "event";
+    name: string;
+    value: Value;
+    static fromGenericParseResult(genericParseResult: GenericParseResultWithDate): Event;
+    toString(): string;
+}