books/fyo

Fyo

This is the underlying framework that runs Books, at some point it may be removed into a separate repo, but as of now it's in gestation.

The reason for maintaining a framework is to allow for varied backends. Currently Books runs on the electron renderer process and all db stuff happens on the electron main process which has access to nodelibs. As the development of Fyo progresses it will allow for a browser frontend and a node server backend.

This platform variablity will be handled by code in the fyo/demux subdirectory.

Pre Req

Singleton: The Fyo class is used as a singleton throughout Books, this allows for a single source of truth and a common interface to access different modules such as db, doc an auth.

Localization: Since Books' functionality changes depending on region, regional information (countryCode) is required in the initialization process.

Doc: This is fyo's abstraction for an ORM, the associated files are located in model/doc.ts, all classes exported from books/models extend this.

Terminology

• Schema: object that defines shape of the data in the database.
• Model: the controller class that extends the Doc class, or the Doc class itself (if a specific controller doesn't exist).
• doc (not Doc): instance of a Model, i.e. what has the data.

If you are confused, I understand.

Initialization

There are a set of core models which are maintained in the fyo/models subdirectory, from this the SystemSettings field countryCode is used to config regional information.

A few things have to be done on initialization:

1. Connect To DB

If creating a new instance then fyo.db.createNewDatabase or if loading an instance fyo.db.connectToDatabase.

Both of them take countryCode as an argument, fyo.db.createNewDatabase should be passed the countryCode as the schemas are built on the basis of this.

2. Initialize and Register

Done using fyo.initializeAndRegister after a database is connected, this should be passed the models and regional models.

This sets the schemas and associated models on the fyo object along with a few other things.

Sequence

First Load: i.e. registering or creating a new instance.

• Get countryCode from the setup wizard.
• Create a new DB using fyo.db.createNewDatabase with the countryCode.
• Get models and regionalModels using countryCode from models/index.ts/getRegionalModels.
• Call fyo.initializeAndRegister with the all models.

Next Load: i.e. logging in or opening an existing instance.

• Connect to DB using fyo.db.connectToDatabase and get countryCode from the return.
• Get models and regionalModels using countryCode from models/index.ts/getRegionalModels.
• Call fyo.initializeAndRegister with the all models.

Note: since SystemSettings are initialized on fyo.initializeAndRegister db needs to be set first else an error will be thrown

Testing

For testing the fyo class, mocha is used (node side). So for this the demux classes are directly replaced by node side managers such as DatabaseManager.

For this to work the class signatures of the demux class and the manager have to be the same which is maintained by abstract demux classes.

DatabaseManager is used as the DatabaseDemux for testing without API or IPC calls. For AuthDemux the DummyAuthDemux class is used.

Translations

All translations take place during runtime, for translations to work, a LanguageMap (for def check utils/types.ts) has to be set.

This can be done using fyo/utils/translation.ts/setLanguageMapOnTranslationString.

Since translations are runtime, if the code is evaluated before the language map is loaded, translations won't work. To prevent this, don't maintain translation strings globally since this will be evaluated before the map is loaded.

Observers

The doc and db handlers have observers (instances of Observable) as properties, these can be accessed using

• fyo.db.observer
• fyo.doc.observer

The purpose of the observer is to trigger registered callbacks when some doc operation or db operation takes place.

These are schema level observers i.e. they are registered like so: method:schemaName. The callbacks receive args passed to the functions.