react-use-level

A react provider and associated hooks for mutating and live querying into a leveldb. The example todo app shows all of the features. Use the various query types (key, keys, range) to pull data out of the local storage leveldb, and use the mutations (put, patch, del) to make changes to the data. Any change that has a query listening within its key range will re-fetch its data. This means your state is always up to date and reflecting the values of the local storage leveldb.

install

npm install react-use-level. This should be imported into a context where react already exists, as it is a peer-dependency.

api

LevelProvider, a react provider which should be the parent of any component that is looking to use the provided hooks.

useLevelKeyQuery, a react hook that is convinience around useLevelQuery(createKeyQuery(key, opts)). key is where the value is found, opts has the shape { map? : async (value, db) }.

useLevelKeysQuery, a react hook that is convinience around useLevelQuery(createKeysQuery(keys, opts)). keys is an array of where the values are found, opts has the shape { map : async (values, db)? }.

useLevelRangeQuery, a react hook that is convinience around useLevelQuery(createRangeQuery(opts)). opts has the shape { gt : key?, gte : key?, lt : key?, lte : key?, filter: async (value, values, db)?, map : async (value, values, db)?, limit: integer? }.

In the case where the query options accept both filter & map functions, filter runs before the map. The db passed into the map and filter function has the shape db : { get : async (key) => value, getMany : async (keys) => values, values : (rangeOpts) => iterator => yield value, keys : (rangeOpts) => iterator => yield key, iterator : (rangeOpts) => iterator => yield [key, value] }.

useLevelQuery, a react hook whose retun value is live state on a query into the level instance. Use createKeyQuery or createRangeQuery as the arguments to this hook.

createKeyQuery, a convinience function around creating a key query. Use its return value as the argument into useLevelQuery to have live state on that particular key.

createKeysQuery, a convinience function around creating a getMany keys query. Use its return value as the argument into useLevelQuery to have live state on that particular key.

createRangeQuery, a convinience function around creating a range query. Use its return value as the argument into useLevelQuery to have live state on a key range.

useLevelMutate, a react hook whose return value is two memoized functions, { put, patch, del }. put takes two arguments, (key, value), which are used to set a value in the underlying leveldb at defined key. patch also takes (key, value) but it will retrieve and merge the old value with the value being passed in. This is useful for partial updates to your values. del takes a single argument, (key), which is used to delete a value in the underlying levedb. All mutations will check for live queries in the range, and will re-run those queries if necessary. Since both of these functions are memoized and given access to the LevelContext values, be sure to list them as dependencies in any effect or callback that they are used within. This is shown in the example todo app with the const del = useCallback block.

LevelContext, a react context that provides direct access to all of the underlying state, and level instance. queries is a react state array that keeps track of all of the live queries in order to rerun them if a mutation occurs over its key range. dirtyQueries is a react state object whose keys are query.id and values are booleans denoting if the current query.id has had a mutation in its range and needs to be re-run. queryParams is a react state object whose keys are query.id and values are a stringified version of the query argument passed into the useLevelQuery hook. This is used to manage the query object within the queries array, ensuring the latest version of its props are being used for cache invalidations. This is more for internal use, but exposed in case you want to build on this layer of abstraction.