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.

Example of a script

This example script doesn't do anything interesting, but illustrates the ideas in this doc.

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.

Still to be worked out

1. How do we indicate from a script that todaysRiver is dirty and must be written?

2. What about callbacks that are running when the day rolls over? We must protect against this, because todaysRiver is changed by day rollover.

3. How often to save localStorage? I have it done in the everyMinute script. In nodeRunner it's in everySecond. I'm not sure about the tradeoffs.

4. How to test? I want to release this to Andrew for testing asap, but don't want to release it to all River4 users until it's had somewhat of a burn-in.