lukaswelinder / immu-level Goto Github PK

The currently used 'bytewise' module is poorly written and throws errors when used in 'strict' mode.

Internal implementation should utilize Immutable.js structures all the way down for performance/memory optimization purposes.

Delete methods shouldn't be much more complicated than using the internal stream method to find all keys/paths contained within target.

Internal methods should be designed in a way to maximize their extensibility; most if not all public API methods will delegate to these in one way or another.

This might take a few refactors to get right, but will be worth the time in the end. One particular consideration needs to be the decision of where (what layer) to do type & error handling. My preference is to do that on the top layer (within the public API methods) for the sake of predictability.

Use doc-blocker commenting style to thoroughly explain how internal (prefixed '__') methods work.

To meet the first milestone, tests will only be written for using immu-level on Node.js with 'tape' as the test suite.

By using LevelUP .batch() method in chained form, we can crank out a bit more performance (reduces memory footprint for large write operations).

Public API methods ._**()should delegate to.**_In() in order to keep code dry. It's likely that some of the methods listed below will not be implemented.

Public API for forEach:

• .forEach([key,] cb)
• .forEachIn(keyPath, cb)
• .forEachRight([key,] cb)
• .forEachRightIn(keyPath, cb)
• .flatForEach([key,] cb)
• .flatForEachIn(keyPath, cb)
• .flatForEachRight([key,] cb)
• .flatForEachRightIn(keyPath, cb)

Public API for map:
All return instance of Immutable.js Map() or OrderedMap()

• .map([key,] cb)
• .mapIn(keyPath, cb)
• .mapRight([key,] cb)
• .mapRightIn(keyPath, cb)
• .flatMap([key,] cb)
• .flatMapIn(keyPath, cb)
• .flatMapRight([key,] cb)
• .flatMapRightIn(keyPath, cb)

Callback arguments (undecided):

• cb(val, key || keyPath, db)
  • for non 'flat' methods, val is instance of Immutable.js Map()

Public API for reduce:
Optional argument curr defaults to Immutable.js Map() - (undecided)

• .reduce([key,] cb[, curr])
• .reduceIn(keyPath, cb[, curr])
• .reduceRight([key,] cb[, curr])
• .reduceRightIn(keyPath, cb[, curr])
• .flatReduce([key,] cb[, curr])
• .flatReduceIn(keyPath, cb[, curr])
• .flatReduceRight([key,] cb[, curr])
• .flatReduceRightIn(keyPath, cb[, curr])

Callback arguments (undecided):

• cb(curr, val, key || keyPath, db)
  • for non 'flat' methods, val is instance of Immutable.js Map()

Reasoning:

While many of these methods exist on Immutable.js structures, they can be more efficiently done using a readStream on the db instance.

Some of these methods, in particular those prefixed with 'flat', will also be used internally for generating batch-updates and/or other iteration methods.

If the value is left behind, it could cause issues when traversing/querying in reverse order (based on the nature of immutable.Map().setIn(keyPath, val) method.

If an object were to be set/constructed within the value keyPath, then a primitive were to be set, the primitive value would overwrite the object that existed there. This would only happen if the primitive were encountered later, thus the reason this would cause problems when traversing k/v pairs in reverse order.

My current thought is to do as follows:

try {
  JSON.stringify(val);
} catch(err) {
  reject(err);
}

However, this doesn't feel like a particularly efficient approach...

It would be great to handle (set and get) circular objects, but I will not be making that a priority at this moment.

Public API:

• .set(key, val)
• .setIn(keyPath, val)
• .get(key)
• .getIn(keyPath)

Private API:

• .__read(opt) - create read stream over contents of opt.root
• '.__write(root, obj)- build LevelDB batch fromobj`

Write out the documentation in a format that will be used to further document functionality.

Also write out a basic TODO with planned features and fixes.