Package data store

Packages may need to store data that is relevant to the entire website, not only a single app instance. Think of the website’s language or brand colors. You typically do not want to configure it 100s of times but only once. That’s where the package data store comes into play.

Where

/sys/packages/PACKAGE_NAME -> for a package installed here, /sys/packageData/PACKAGE_NAME -> the package data store is here.

Schema

/sys/packageData/PACKAGE_NAME -> mounts a simple volume via volume link, called the package data volume of the package. This is to give it a dedicated file node ID space.

The package data volume’s root file has a file type pointing at the last file in /sys/packages/PACKAGE_NAME/sys/package/packageData/.

/sys/packageData/PACKAGE_NAME/local -> you can only write custom package data within the subtree of a file named local. The rest is reserved.

Initializing

Withing the package, create an app at {PKG}/sys/package/packageData/v1 (you can use any file name, not only v1).

Set it’s file type to app-1 to define it to be an app.

Create a file named .InitPackageData in it, with any engine of your choice, for example sjs-4. Within that file, the variable f will point to the package data file of the package: /sys/packageData/PACKAGE_NAME. It’s up to you to set up the subtree of this file. You may create the local file if you need to store custom data in it, but it’s also okay to not create any files. Often, you will only create packageData apps to migrate website data across updates.

Note that the package data volume will be automatically created before executing the .InitPackageData method, and its file type will also be set to the package data app.

Updating the package data store (migration)

The big idea is that as your package evolves, you will be appending new package data apps and .Update scripts to update each version to the next one.

It’s important that you always add the new package data app TO THE END of {PKG}/sys/package/packageData/*. The latest version must always be the last file in that list.

Also, as your package may be installed at any time, the current version (the last one) must also contain an up-to-date .InitPackageData file.

See the .Update method docs for more details.