bkper-js 2.27.0 → 2.29.0

package/CHANGELOG.md

@@ -4,7 +4,30 @@ See what's new and what has changed in bkper-js
 
 ## 2026
 
+**February 2026**
+
+- Added `User.getGivenName`
+- Added `BooksDataTableBuilder`
+- Added `AccountsDataTableBuilder`
+- Added `GroupsDataTableBuilder`
+- Added `TransactionsDataTableBuilder`
+- Added `Book.createAccountsDataTable`
+- Added `Book.createGroupsDataTable`
+- Added `Book.createTransactionsDataTable`
+- Added `TransactionsDataTableBuilder.ids`
+- Added `TransactionsDataTableBuilder.properties`
+- Added `TransactionsDataTableBuilder.urls`
+- Added `TransactionsDataTableBuilder.recordedAt`
+- Added `AccountsDataTableBuilder.hiddenProperties`
+- Added `BooksDataTableBuilder.hiddenProperties`
+- Added `GroupsDataTableBuilder.hiddenProperties`
+- Added `GroupsDataTableBuilder.tree`
+- Added `TransactionsDataTableBuilder.hiddenProperties`
+- Added `BalancesDataTableBuilder.hiddenProperties`
+
+
 **January 2026**
+
 - Added `App.setUsers`
 - Added `App.getUsers`
 - Added `App.setDevelopers`
@@ -38,16 +61,18 @@ See what's new and what has changed in bkper-js
 ## 2025
 
 **December 2025**
+
 - Added `File.update`
 - Added `EventType.FILE_UPDATED`
 
 **November 2025**
+
 - **v2.15.2 - INTERNAL REFACTOR:**
-  - Introduced `ResourceProperty` abstract class for model entities that support custom properties
-  - Moved shared property methods to ResourceProperty
-  - Refactor 7 model classes to extend ResourceProperty instead of Resource
-  - Eliminate ~350 lines of duplicated property management code
-  - Maintained full backward compatibility - no breaking changes to existing APIs
+    - Introduced `ResourceProperty` abstract class for model entities that support custom properties
+    - Moved shared property methods to ResourceProperty
+    - Refactor 7 model classes to extend ResourceProperty instead of Resource
+    - Eliminate ~350 lines of duplicated property management code
+    - Maintained full backward compatibility - no breaking changes to existing APIs
 - Added `ResourceProperty.setVisibleProperty`
 - Added `ResourceProperty.setVisibleProperties`
 - Added `ResourceProperty.getVisibleProperties`
@@ -63,11 +88,11 @@ See what's new and what has changed in bkper-js
 **September 2025**
 
 - **v2.8.0 - INTERNAL REFACTOR:**
-  - Introduced abstract `Resource` class for all model entities
-  - Improved config management with `getConfig()` pattern for config resolution
-  - Enhanced type safety with explicit Config type usage throughout
-  - Standardized `json()` method across resources for consistent JSON serialization
-  - Maintained full backward compatibility - no breaking changes to existing APIs
+    - Introduced abstract `Resource` class for all model entities
+    - Improved config management with `getConfig()` pattern for config resolution
+    - Enhanced type safety with explicit Config type usage throughout
+    - Standardized `json()` method across resources for consistent JSON serialization
+    - Maintained full backward compatibility - no breaking changes to existing APIs
 - Added `Account.isBalanceVerified`
 - Added `App.getOwnerWebsiteUrl`
 - Added `App.getReadme`

package/lib/builders/AccountsDataTableBuilder.js

@@ -0,0 +1,247 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { AccountType } from '../model/Enums.js';
+import { convertInMatrix } from '../utils.js';
+/**
+ * A AccountsDataTableBuilder is used to setup and build two-dimensional arrays containing accounts.
+ *
+ * @public
+ */
+export class AccountsDataTableBuilder {
+    constructor(accounts) {
+        this.accounts = accounts;
+        this.shouldIncludeArchived = false;
+        this.shouldAddGroups = false;
+        this.shouldAddProperties = false;
+        this.shouldAddIds = false;
+        this.shouldAddHiddenProperties = false;
+        this.propertyKeys = [];
+    }
+    /**
+     * Defines whether the archived accounts should be included.
+     *
+     * @param include - Whether to include archived accounts
+     *
+     * @returns This builder with respective include archived option, for chaining.
+     */
+    archived(include) {
+        this.shouldIncludeArchived = include;
+        return this;
+    }
+    /**
+     * Defines whether include account groups.
+     *
+     * @param include - Whether to include groups
+     *
+     * @returns This builder with respective include groups option, for chaining.
+     */
+    groups(include) {
+        this.shouldAddGroups = include;
+        return this;
+    }
+    /**
+     * Defines whether include custom account properties.
+     *
+     * @param include - Whether to include properties
+     *
+     * @returns This builder with respective include properties option, for chaining.
+     */
+    properties(include) {
+        this.shouldAddProperties = include;
+        return this;
+    }
+    /**
+     * Defines whether include account ids.
+     *
+     * @param include - Whether to include ids
+     *
+     * @returns This builder with respective include ids option, for chaining.
+     */
+    ids(include) {
+        this.shouldAddIds = include;
+        return this;
+    }
+    /**
+     * Defines whether to include hidden properties (keys ending with underscore "_").
+     * Only relevant when {@link properties} is enabled.
+     * Default is false — hidden properties are excluded.
+     *
+     * @param include - Whether to include hidden properties
+     *
+     * @returns This builder with respective option, for chaining.
+     */
+    hiddenProperties(include) {
+        this.shouldAddHiddenProperties = include;
+        return this;
+    }
+    getPropertyKeys() {
+        if (this.propertyKeys.length === 0) {
+            for (const account of this.accounts) {
+                for (const key of account.getPropertyKeys()) {
+                    if (!this.shouldAddHiddenProperties && key.endsWith('_')) {
+                        continue;
+                    }
+                    if (this.propertyKeys.indexOf(key) <= -1) {
+                        this.propertyKeys.push(key);
+                    }
+                }
+            }
+            this.propertyKeys = this.propertyKeys.sort();
+        }
+        return this.propertyKeys;
+    }
+    getTypeIndex(type) {
+        if (type === AccountType.ASSET) {
+            return 0;
+        }
+        if (type === AccountType.LIABILITY) {
+            return 1;
+        }
+        if (type === AccountType.INCOMING) {
+            return 2;
+        }
+        return 3;
+    }
+    getMaxNumberOfGroups() {
+        return __awaiter(this, void 0, void 0, function* () {
+            let maxNumberOfGroups = 0;
+            for (const account of this.accounts) {
+                const groups = yield account.getGroups();
+                if (groups.length > maxNumberOfGroups) {
+                    maxNumberOfGroups = groups.length;
+                }
+            }
+            return maxNumberOfGroups;
+        });
+    }
+    /**
+     * Sorts groups for an account in hierarchy-path order:
+     * 1. Hierarchical groups (those with parent or children) come first, ordered by:
+     *    - Root group name (alphabetically)
+     *    - Depth within the hierarchy (parent before child)
+     * 2. Free groups (no parent and no children) come last, sorted alphabetically
+     */
+    sortGroupsHierarchyPath_(groups) {
+        // Partition into hierarchical vs free groups
+        const hierarchicalGroups = [];
+        const freeGroups = [];
+        for (const group of groups) {
+            if (group.getParent() != null || group.hasChildren()) {
+                hierarchicalGroups.push(group);
+            }
+            else {
+                freeGroups.push(group);
+            }
+        }
+        // Group hierarchical groups by their root
+        const byRoot = new Map();
+        for (const group of hierarchicalGroups) {
+            const root = group.getRoot();
+            const rootId = root.getId() || '';
+            if (!byRoot.has(rootId)) {
+                byRoot.set(rootId, []);
+            }
+            byRoot.get(rootId).push(group);
+        }
+        // Sort chains: first by root name alphabetically, then by depth within each chain
+        const sortedChains = Array.from(byRoot.entries())
+            .sort((a, b) => {
+            const rootA = a[1][0].getRoot();
+            const rootB = b[1][0].getRoot();
+            return rootA.getNormalizedName().localeCompare(rootB.getNormalizedName());
+        })
+            .map(([_, chainGroups]) => chainGroups.sort((a, b) => a.getDepth() - b.getDepth()));
+        // Sort free groups alphabetically
+        freeGroups.sort((a, b) => a.getNormalizedName().localeCompare(b.getNormalizedName()));
+        // Combine: hierarchical chains first, then free groups
+        const result = [];
+        for (const chain of sortedChains) {
+            result.push(...chain);
+        }
+        result.push(...freeGroups);
+        return result;
+    }
+    /**
+     * Builds a two-dimensional array containing all accounts.
+     *
+     * @returns A promise resolving to a two-dimensional array containing all accounts
+     */
+    build() {
+        return __awaiter(this, void 0, void 0, function* () {
+            let table = new Array();
+            let accounts = this.accounts;
+            if (!this.shouldIncludeArchived) {
+                accounts = this.accounts.filter(a => !a.isArchived());
+            }
+            let headers = [];
+            if (this.shouldAddIds) {
+                headers.push('Account Id');
+            }
+            headers.push('Name');
+            headers.push('Type');
+            if (this.shouldAddGroups) {
+                const maxGroups = yield this.getMaxNumberOfGroups();
+                for (let i = 0; i < maxGroups; i++) {
+                    headers.push('Group');
+                }
+            }
+            accounts.sort((a1, a2) => {
+                let ret = this.getTypeIndex(a1.getType()) - this.getTypeIndex(a2.getType());
+                if (ret === 0) {
+                    ret = a1.getNormalizedName().localeCompare(a2.getNormalizedName());
+                }
+                return ret;
+            });
+            let propertyKeys = [];
+            if (this.shouldAddProperties) {
+                propertyKeys = this.getPropertyKeys();
+            }
+            for (const account of accounts) {
+                const line = [];
+                if (this.shouldAddIds) {
+                    line.push(account.getId());
+                }
+                line.push(account.getName());
+                line.push(account.getType());
+                if (this.shouldAddGroups) {
+                    const groups = this.sortGroupsHierarchyPath_(yield account.getGroups());
+                    for (const group of groups) {
+                        line.push(group.getName());
+                    }
+                }
+                if (this.shouldAddGroups && this.shouldAddProperties) {
+                    const numOfBlankCells = headers.length - line.length;
+                    for (let i = 0; i < numOfBlankCells; i++) {
+                        line.push('');
+                    }
+                }
+                if (this.shouldAddProperties) {
+                    const properties = account.getProperties();
+                    for (const key of propertyKeys) {
+                        const propertyValue = properties[key];
+                        if (propertyValue) {
+                            line.push(propertyValue);
+                            continue;
+                        }
+                        line.push('');
+                    }
+                }
+                table.push(line);
+            }
+            if (this.shouldAddProperties) {
+                headers = headers.concat(propertyKeys);
+            }
+            table.unshift(headers);
+            convertInMatrix(table);
+            return table;
+        });
+    }
+}
+//# sourceMappingURL=AccountsDataTableBuilder.js.map

package/lib/{model → builders}/BalancesDataTableBuilder.js

@@ -1,5 +1,5 @@
-import { Amount } from "./Amount.js";
-import { BalanceType } from "./Enums.js";
+import { Amount } from '../model/Amount.js';
+import { BalanceType } from '../model/Enums.js';
 import * as Utils from '../utils.js';
 /**
  * A BalancesDataTableBuilder is used to setup and build two-dimensional arrays containing balance information.
@@ -25,6 +25,7 @@ export class BalancesDataTableBuilder {
         this.shouldPeriod = false;
         this.shouldRaw = false;
         this.shouldAddProperties = false;
+        this.shouldAddHiddenProperties = false;
     }
     getBalance(balance, permanent) {
         return this.getRepresentativeBalance(balance, permanent).toNumber();
@@ -73,7 +74,7 @@ export class BalancesDataTableBuilder {
      * @returns This builder with respective expanded option, for chaining.
      */
     expanded(expanded) {
-        if (typeof expanded == "boolean" && expanded == true) {
+        if (typeof expanded == 'boolean' && expanded == true) {
             this.maxDepth = 1;
             this.skipRoot = true;
         }
@@ -83,7 +84,7 @@ export class BalancesDataTableBuilder {
         else if (expanded == -2) {
             this.expandAllAccounts = true;
         }
-        else if (typeof expanded == "number" && expanded > 0) {
+        else if (typeof expanded == 'number' && expanded > 0) {
             this.maxDepth = expanded;
         }
         return this;
@@ -188,6 +189,19 @@ export class BalancesDataTableBuilder {
         this.shouldAddProperties = include;
         return this;
     }
+    /**
+     * Defines whether to include hidden properties (keys ending with underscore "_").
+     * Only relevant when {@link properties} is enabled.
+     * Default is false — hidden properties are excluded.
+     *
+     * @param include - Whether to include hidden properties
+     *
+     * @returns This builder with respective option, for chaining.
+     */
+    hiddenProperties(include) {
+        this.shouldAddHiddenProperties = include;
+        return this;
+    }
     /**
      * Defines whether should split **TOTAL** [[BalanceType]] into debit and credit.
      *
@@ -231,6 +245,9 @@ export class BalancesDataTableBuilder {
     ////////////////////////
     addPropertyKeys(propertyKeys, container) {
         for (const key of container.getPropertyKeys()) {
+            if (!this.shouldAddHiddenProperties && key.endsWith('_')) {
+                continue;
+            }
             if (propertyKeys.indexOf(key) <= -1) {
                 propertyKeys.push(key);
             }
@@ -309,7 +326,8 @@ export class BalancesDataTableBuilder {
         let depth = container.getDepth();
         if (depth <= this.maxDepth) {
             if (!this.skipRoot && !this.shouldTranspose) {
-                container.payload.name = Utils.repeatString(" ", depth * 4) + container.payload.name;
+                container.payload.name =
+                    Utils.repeatString(' ', depth * 4) + container.payload.name;
             }
             if (!this.skipRoot || depth != 0) {
                 containersFlat.push(container);
@@ -330,7 +348,8 @@ export class BalancesDataTableBuilder {
         if (container.isFromGroup()) {
             if (!this.shouldTranspose) {
                 let depth = container.getDepth();
-                container.payload.name = Utils.repeatString(" ", depth * 4) + container.payload.name;
+                container.payload.name =
+                    Utils.repeatString(' ', depth * 4) + container.payload.name;
             }
             containersFlat.push(container);
             if (this.shouldAddProperties) {
@@ -460,7 +479,7 @@ export class BalancesDataTableBuilder {
         var dataIndexMap = new Object();
         var cumulativeBalance = this.balanceType == BalanceType.CUMULATIVE;
         var header = new Array();
-        header.push("");
+        header.push('');
         if (this.balancesContainers == null) {
             return table;
         }
@@ -486,7 +505,9 @@ export class BalancesDataTableBuilder {
                     else {
                         amount = balance.getPeriodBalanceRaw();
                     }
-                    indexEntry[container.getName()] = this.shouldRaw ? amount : this.getRepresentativeBalance(amount, container.isPermanent());
+                    indexEntry[container.getName()] = this.shouldRaw
+                        ? amount
+                        : this.getRepresentativeBalance(amount, container.isPermanent());
                 }
             }
         }
@@ -499,7 +520,7 @@ export class BalancesDataTableBuilder {
             for (const container of containers) {
                 var amount = rowObject[container.getName()];
                 if (amount == null) {
-                    amount = "null_amount";
+                    amount = 'null_amount';
                 }
                 else {
                     amount = new Amount(amount);
@@ -514,7 +535,9 @@ export class BalancesDataTableBuilder {
             }
             rows.push(row);
         }
-        rows.sort(function (a, b) { return a[0].getTime() - b[0].getTime(); });
+        rows.sort(function (a, b) {
+            return a[0].getTime() - b[0].getTime();
+        });
         var lastRow = null;
         for (var i = 0; i < rows.length; i++) {
             var row = rows[i];
@@ -522,7 +545,7 @@ export class BalancesDataTableBuilder {
                 //first row, all null values will be 0
                 for (var j = 1; j < row.length; j++) {
                     var cell = row[j];
-                    if (cell == "null_amount") {
+                    if (cell == 'null_amount') {
                         var amount = new Amount(0);
                         if (this.shouldFormatValue) {
                             amount = Utils.formatValue(amount, this.book.getDecimalSeparator(), this.book.getFractionDigits());
@@ -537,12 +560,12 @@ export class BalancesDataTableBuilder {
             else {
                 for (var j = 1; j < row.length; j++) {
                     var cell = row[j];
-                    if (cell == "null_amount" && cumulativeBalance) {
+                    if (cell == 'null_amount' && cumulativeBalance) {
                         if (lastRow) {
                             row[j] = lastRow[j];
                         }
                     }
-                    else if (cell == "null_amount") {
+                    else if (cell == 'null_amount') {
                         var amount = new Amount(0);
                         if (this.shouldFormatValue) {
                             amount = Utils.formatValue(amount, this.book.getDecimalSeparator(), this.book.getFractionDigits());

package/lib/builders/BooksDataTableBuilder.js

@@ -0,0 +1,127 @@
+import { convertInMatrix } from '../utils.js';
+/**
+ * A BooksDataTableBuilder is used to setup and build two-dimensional arrays containing books.
+ *
+ * @public
+ */
+export class BooksDataTableBuilder {
+    constructor(books) {
+        this.shouldAddProperties = false;
+        this.shouldAddIds = false;
+        this.shouldAddHiddenProperties = false;
+        this.propertyKeys = [];
+        this.books = books;
+    }
+    /**
+     * Defines whether to include custom book properties.
+     *
+     * @param include - Whether to include properties
+     *
+     * @returns This builder with respective include properties option, for chaining.
+     */
+    properties(include) {
+        this.shouldAddProperties = include;
+        return this;
+    }
+    /**
+     * Defines whether to include book ids.
+     *
+     * @param include - Whether to include ids
+     *
+     * @returns This builder with respective include ids option, for chaining.
+     */
+    ids(include) {
+        this.shouldAddIds = include;
+        return this;
+    }
+    /**
+     * Defines whether to include hidden properties (keys ending with underscore "_").
+     * Only relevant when {@link properties} is enabled.
+     * Default is false — hidden properties are excluded.
+     *
+     * @param include - Whether to include hidden properties
+     *
+     * @returns This builder with respective option, for chaining.
+     */
+    hiddenProperties(include) {
+        this.shouldAddHiddenProperties = include;
+        return this;
+    }
+    mapPropertyKeys() {
+        this.propertyKeys = [];
+        for (const book of this.books) {
+            for (const key of book.getPropertyKeys()) {
+                if (!this.shouldAddHiddenProperties && key.endsWith('_')) {
+                    continue;
+                }
+                if (this.propertyKeys.indexOf(key) <= -1) {
+                    this.propertyKeys.push(key);
+                }
+            }
+        }
+        this.propertyKeys = this.propertyKeys.sort();
+    }
+    /**
+     * Builds a two-dimensional array containing all Books.
+     *
+     * @returns A two-dimensional array containing all Books
+     */
+    build() {
+        var _a, _b;
+        const table = new Array();
+        this.books.sort((a, b) => {
+            var _a, _b;
+            const collA = (_a = a.getCollection()) === null || _a === void 0 ? void 0 : _a.getName();
+            const collB = (_b = b.getCollection()) === null || _b === void 0 ? void 0 : _b.getName();
+            // Books with collection before books without
+            if (collA && !collB)
+                return -1;
+            if (!collA && collB)
+                return 1;
+            let ret = (collA || '').localeCompare(collB || '');
+            if (ret === 0) {
+                ret = (a.getName() || '').localeCompare(b.getName() || '');
+            }
+            return ret;
+        });
+        let headers = [];
+        if (this.shouldAddIds) {
+            headers.push('Book Id');
+        }
+        headers.push('Name');
+        headers.push('Collection');
+        headers.push('Date Pattern');
+        headers.push('Decimal Separator');
+        headers.push('Fraction Digits');
+        headers.push('Period');
+        headers.push('Owner');
+        if (this.shouldAddProperties) {
+            this.mapPropertyKeys();
+            headers = headers.concat(this.propertyKeys);
+        }
+        for (const book of this.books) {
+            const line = [];
+            if (this.shouldAddIds) {
+                line.push(book.getId());
+            }
+            line.push(book.getName() || '');
+            line.push(((_a = book.getCollection()) === null || _a === void 0 ? void 0 : _a.getName()) || '');
+            line.push(book.getDatePattern() || '');
+            line.push(book.getDecimalSeparator() || '');
+            line.push((_b = book.getFractionDigits()) !== null && _b !== void 0 ? _b : '');
+            line.push(book.getPeriod() || '');
+            line.push(book.getOwnerName() || '');
+            if (this.shouldAddProperties) {
+                const properties = book.getProperties();
+                for (const key of this.propertyKeys) {
+                    line.push(properties[key] || '');
+                }
+            }
+            table.push(line);
+        }
+        table.unshift(headers);
+        convertInMatrix(table);
+        return table;
+    }
+}
+//# sourceMappingURL=BooksDataTableBuilder.js.map