Oktane
Current status: 🚧 In alpha stage so expect breaking changes. Check out the roadmap for more info.
A light-weight and customizable library for data fetching in React.
Features
- 📦 Minimal footprint (< 3kb gzipped)
- 🌐 Backend agnostic
- 🧹 Automatic Garbage collection
- 🔫 Request cancellation
- ⏫ Parallel / Dependent Queries
- 🔃 Subscriptions / Lazy queries
- 🔌 Plugins support
- 💙 TypeScript ready
- and more ...
Installation
Requires React v16.8.6 or higher
npm add oktane
Basic usage
Creating the client
; const client = ; const App = <ClientProvider value=client> <Todos /> </ClientProvider>;
Fetching data
; const Todos = { const data status = ; if status === 'pending' return <p>loading ...</p>; return <> <h2>Todo list</h2> <ul> data </ul> </> ;};
How it works
Many data fetching libraries provide multiple React hooks to support use cases e.g. useSubscription
, useInfiniteQuery
..etc. To minimize the API surface Oktane takes a different approach.
Here how someone would make a request using the useQuery hook provided by Oktane:
const data error hasMore fetchMore ...rest = ;
Note: useManualQuery hook works the same way as
useQuery
except it doesn't fetch the request automatically on mount/updates but rather exposes a helper to manually fetch when needed.
When resolving a request, Oktane checks the value returned by clientOptions.fetch(request, ctx)
call and does one of the following based to the type:
- Promise: (demo )
- Waits for the Promise to resolve and then set
data
to the result. - In the case of error, Oktane will catch the error and expose it as
error
. - Calling
hasMore
will always return false. - Use case: API Calls, loading data from LocalStorage ...etc.
- Waits for the Promise to resolve and then set
- Iterable / Async Iterable: (demo )
- Calls
iterator.next()
once and setsdata
to the result. - Next values can be emitted by calling
fetchMore
. - Calling
hasMore
will return true as long as the iterator doesn't complete. - In the case of error, Oktane will catch the error and expose it as
error
. - Use case: Infinite scroll.
- Calls
- Callback function: (demo )
- Assumes a function that accepts a subscriber and optionally returns a function to close subscription (i.e. unsubscribe).
- Any value passed to
subscriber.next()
will be available asdata
. - Calling
subscriber.error()
will set the value toerror
and close the subscription. - Calling
subscriber.complete()
will mark the request as completed and close the subscription. - Calling
hasMore
will always return false. - Use case: Anything you would use an Observable for e.g. Web Socket.
- Anything else: wraps it in
Promise.resolve
and applies the Promise rule above.
It's worth mentioning that custom plugins may alter the behavior described above. For example, a plugin may decide not to report errors back to the React hook and instead retry the request every time it fails.
API
createClient
: Client
Arguments
- options (object)
- fetch (function): The function that resolves all requests. Required.
- plugins (array): An array of custom plugins.
- cache (object)
- disposeTime (number): A timeout for unused requests. Default is 30 seconds.
useQuery
: { void; void; boolean; void;}
useManualQuery
: { void; void; void; boolean; void;}
Examples
Check out the examples folder.
Credits
Inspired by the following great libraries:
- Redux: Predictable state container for JavaScript apps.
- SWR: React Hooks library for remote data fetching.
- React Query: Hooks for fetching, caching, and updating asynchronous data in React.
License
MIT © Ahmed T. Ali