How callbacks work in River4

I'm working on callbacks in River4. This page describes how it works, while I'm doing the work. Ultimately there will be a page on the blog about this feature.

The callbacks folder

1. There's a new sub-folder in the River4 folder, the same folder as the river4.js app: callbacks. Each sub-folder of callbacks stores scripts that are called on a specific event. Only files with the extension .js are run.

2. The addToRiver sub-folder of callbacks contains scripts that are called when a new item has been added to the river.

3. Each script in the addToRiver sub-folder is called once for each new object. There's no guarantee of the order in which they run. However I'm pretty sure they can't run concurrently (please check this when I release the code).

4. The scripts have three pseudo-globals they can use and/or modify: urlfeed, itemFromParser and itemFromRiver. urlfeed is the HTTP address of the feed, its identifier. itemFromParser is an object containing all the data we received from FeedParser. itemFromRiver is the actual object in the river for today. You can add data or modify data in this record, and it will be saved to the river. The items you add can be accessed in other callbacks.

Your first callback

Here's the script I wrote to test the addToRiver callbacks. You should be able to run it on your River4 installation.

To do so, launch River4. It should create a callbacks folder and an addToRiver sub-folder when the first new item comes in.

2. Save a copy of this script in the addToRiver sub-folder.

3. Wait until some new items come in.

4. Look in data/localstorage.json. You should see some data. Here's an example from my server after I ran it for a while.

The data sub-folder

1. There's a new sub-folder of the River4 folder called data. It will hold data files created and managed by the application.

2. For now the only file stored in this folder is localStorage.json.

3. The localStorage object, stored in localStorage.json, works as it does in nodeRunner. It's a place you can store persistent data that will be around when River4 runs. Unlike browser-based localStorage, you can store any type of data, not just strings.

Notes

1. If you modified itemFromRiver in the addToRiver callback, call todaysRiverChanged (), which tells River4 to save the structure at the top of the minute.

2. We don't roll over the day until there's been 60 seconds with no new items added to the river. We assume all the addToRiver callbacks will complete in less than a minute.

3. We save localStorage once a minute, if there were changes.