https://github.com/rodrigoslayertech/dataruni
Dataruni is a lightweight, unified database system designed for React applications.
https://github.com/rodrigoslayertech/dataruni
Last synced: 3 months ago
JSON representation
Dataruni is a lightweight, unified database system designed for React applications.
- Host: GitHub
- URL: https://github.com/rodrigoslayertech/dataruni
- Owner: rodrigoslayertech
- Created: 2025-11-25T14:43:25.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-01-21T03:48:04.000Z (5 months ago)
- Last Synced: 2026-03-07T22:39:05.308Z (4 months ago)
- Language: TypeScript
- Homepage:
- Size: 16.6 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# Dataruni
**Dataruni** is a lightweight, unified database system designed for React applications. It bridges the gap between persistent local storage (IndexedDB) and React state, providing a seamless "sync-to-state" experience for offline-first applications.
Built originally for the Codecious ecosystem, Dataruni abstracts away the complexity of IndexedDB, offering a simple hook-based API that feels just like `useState`, but with the power of a robust database backing it up.
## Features
- 🚀 **React-First API**: Use `useDataruniValue` just like `useState`.
- 💾 **IndexedDB Powered**: Handles large datasets asynchronously without blocking the UI.
- 🔄 **State Synchronization**: Automatically loads data on mount and persists updates in the background.
- 📦 **Zero-Config**: Works out of the box with sensible defaults, but fully configurable.
- 🔒 **Type-Safe**: Built with TypeScript for full type inference.
- 📱 **Offline Ready**: Perfect for PWAs and mobile-first web apps.
## Installation
```bash
npm install @codecious/dataruni
# or
pnpm add @codecious/dataruni
# or
yarn add @codecious/dataruni
```
## Usage
### Basic Usage
The core of Dataruni is the `useDataruniValue` hook. It binds a database key to a React state variable.
```tsx
import { useDataruniValue } from '@codecious/dataruni';
// Define your configuration once
const dbConfig = {
dbName: 'MyAppDB',
dbVersion: 1,
storeName: 'my-store' // Optional, defaults to 'dataruni-store'
};
function AppSettings() {
// usage is identical to useState, but with a key and config
const [theme, setTheme, isLoading] = useDataruniValue(
'app-theme', // Key in the database
'light', // Default value
dbConfig // Database configuration
);
if (isLoading) {
return
Loading preferences...;
}
return (
setTheme(theme === 'light' ? 'dark' : 'light')}>
Current theme: {theme}
);
}
```
### Advanced Configuration
You can manage complex objects and arrays easily. Dataruni handles the serialization and storage for you.
```tsx
interface UserProfile {
id: string;
name: string;
preferences: {
notifications: boolean;
};
}
const [user, setUser] = useDataruniValue(
'user-profile',
null,
dbConfig
);
// Updates are persisted automatically
const updateName = (newName: string) => {
setUser(prev => prev ? { ...prev, name: newName } : null);
};
```
## API Reference
### `useDataruniValue(key, defaultValue, config)`
The main hook for data persistence.
- **Parameters**:
- `key` (string): The unique identifier for the data in the store.
- `defaultValue` (T): The value to use if no data is found in the DB or while loading.
- `config` (DataruniConfig): Configuration object for the database connection.
- **Returns**: `[value, setValue, isLoading]`
- `value` (T): The current state.
- `setValue` (function): Function to update state and persist to DB. Accepts a value or a callback `(prev) => newValue`.
- `isLoading` (boolean): True while the initial value is being fetched from IndexedDB.
### `initDB(config)`
Initializes the IndexedDB connection. Useful for pre-loading or side-effects outside of React components.
- **Parameters**:
- `config` (DataruniConfig): `{ dbName: string, dbVersion?: number, storeName?: string }`
- **Returns**: `Promise`
## License
MIT © [Codecious](https://github.com/rodrigoslayertech)