hertzg / node-xhb

(somewhat) Sane library to parse and serialize HomeBank XHB files (databases).

XHB file read/write for NodeJS

This package provides ability to read and modify xhb files created by HomeBank in somewhat sane manner.

HomeBank is a personal finance and money management software application built and maintained by Maxime Doyen.

Command Line Usage

This package also includes a tiny cli utility xhb to convert between .xhb and .json formats

# Convert XHB to JSON
$ npx xhb parse < database.xhb > database.json

# Modify the database with common tools, just keep structure the same
$ mv database.json database-modified.json

# Convert JSON back to XHB
$ npx xhb serialize < database-modified.json > database-modified.xhb

Programmatic Usage

$ npm install xhb --save

import FS from 'fs'
import { parse, serialize } from 'xhb'

const contents = FS.readFileSync('./homebank.xhb', { encoding: 'utf8' })
const xhb = parse(contents)

// modify / copy / clone the xhb object, whatever you need to do with it.

const modified = serialize(xhb)
FS.writeFileSync('./homebank-modified.xhb', modified, { encoding: 'utf8' })

API overview

As the original code is using GLib types, following aliases are used to map to javascript types

export type gShort = number
export type gUShort = number
export type gInt = number
export type gUInt32 = number
export type gCharP = string
export type gDouble = string // For airthmetic operations, consider using decimal.js
export type gBoolean = number // https://developer.gnome.org/glib/stable/glib-Basic-Types.html#gboolean

XHB File structure

export interface XHB {
  versions: Versions
  properties?: Properties
  accounts: Account[]
  archives: Archive[]
  assigns: Assign[]
  categories: Category[]
  currencies: Currency[]
  operations: Operation[]
  payees: Payee[]
  tags: Tag[]
}

For more information, please see type definitions for respective entities from source code.

FAQ

Here are some questions that come up or most likely will come up.

Dates are in weird format, how do I convert them to js Dates?

The dates are in GLib specific julian day format (which is not "real" julian day count). Consider using package gdate-julian package.

---

All the amounts are parsed as strings not numbers. Why?

All amounts in HomBank are handled as gdoubles in C, here are a few reasons why I went with strings in javascript:

• There is no double type in javascript
• It's out of the scope of this project
• Using floats (number) would not be able to fit all values
• The values in XML are strings so you can parse them as you see fit.

Recommendation: Consider using decimal.js package to work with gdoubles It will save you quite a lot of headache.

---

Tags is always empty, even thou I've added tags to operations. Whats up with that?

HomeBank does not create them separately in XML. This package reads and write the XHB file as it is.

---

The XML produced is not "correct" xml and why do you use sprintf to create xml tags? That's stupid!

This is the way HomeBank deals with XML files. Don't believe me? Check the source code on launchpad. The goal of this project is to be able to read and write files acceptable by that application so I mimic the way it deals with the file format.

See: https://bazaar.launchpad.net/~mdoyen/homebank/5.2.x/view/head:/src/hb-xml.c#L1214

---

node-xhb's Issues

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update all dependencies (@types/node, actions/setup-node, actions/stale, actions/upload-artifact, semantic-release, yarn)

Detected dependencies

github-actions

.github/workflows/_test-matrix.yml

• actions/checkout v4
• actions/setup-node v3

.github/workflows/pr.yml

• actions/checkout v4
• actions/setup-node v3
• actions/upload-artifact v3

.github/workflows/release.yml

• actions/checkout v4
• actions/setup-node v3

.github/workflows/stale.yml

• actions/stale v8

npm

package.json

• printj ^1.2.2
• xml-parser ^1.2.1
• yargs ^17.2.1
• @semantic-release/changelog ^6.0.0
• @semantic-release/commit-analyzer ^11.0.0
• @semantic-release/exec ^6.0.0
• @semantic-release/git ^10.0.0
• @semantic-release/github ^9.0.0
• @semantic-release/npm ^11.0.0
• @semantic-release/release-notes-generator ^12.0.0
• @tsconfig/node16 ^16.0.0
• @types/jest ^29.0.0
• @types/node ^18.0.0
• @types/xml-parser ^1.2.29
• @types/yargs ^17
• conventional-changelog-conventionalcommits ^7.0.0
• jest ^29.0.0
• prettier ^3.0.0
• rimraf ^5.0.0
• semantic-release ^22.0.0
• ts-jest ^29.0.0
• ts-node ^10.4.0
• typescript ^5.0.0
• node >=16
• yarn 3.6.4

---

• Check this box to trigger a request for Renovate to run again on this repository

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Location: renovate.json
Error type: Invalid JSON (parsing failed)
Message: Syntax error: expecting String near false, }