Unified DB Layer

A cross-platform unified database layer that automatically detects your runtime environment and uses the appropriate storage backend with a familiar Prisma-like API.

✨ Features

• 🌍 Cross-platform: Works seamlessly in Browser, Node.js, Electron, and React Native
• 🔍 Auto-detection: Automatically selects the best storage backend for your environment
• 📊 Prisma-like API: Familiar and intuitive database operations with method chaining
• 📴 Offline-first: No network dependencies, works entirely offline
• ⚡ Zero-config: Works out of the box with sensible defaults
• 🎯 TypeScript: Full type support included
• 🔒 Data validation: Built-in validation with custom rules
• 🪝 Hooks system: Extensible middleware for custom logic
• 📦 Lightweight: Minimal bundle size with tree-shaking support
• 🔄 Import/Export: Easy data backup and migration

🚀 Quick Start

Installation

npm install universal-db-layer

For React Native projects, also install:

npm install @react-native-async-storage/async-storage

Basic Usage

import { UnifiedDB } from "universal-db-layer";

// Define your data models
const db = new UnifiedDB({
  models: {
    User: {
      fields: {
        id: { type: "string", primaryKey: true },
        name: { type: "string", required: true },
        email: { type: "string", required: true },
        age: { type: "number", default: 0 },
        createdAt: { type: "date", default: "now" },
      },
    },
    Post: {
      fields: {
        id: { type: "string", primaryKey: true },
        title: { type: "string", required: true },
        content: { type: "string", required: true },
        authorId: { type: "string", required: true },
        published: { type: "boolean", default: false },
      },
    },
  },
});

// Initialize the database
await db.init();

// Use the Prisma-like API
const user = await db.user.create({
  name: "John Doe",
  email: "[email protected]",
  age: 30,
});

const users = await db.user.findMany({
  where: { age: { gte: 18 } },
  orderBy: { name: "asc" },
  take: 10,
});

const post = await db.post.create({
  title: "Hello World",
  content: "This is my first post!",
  authorId: user.id,
  published: true,
});

🌐 Platform Support

| Platform | Storage Backend | Capacity | Persistence | | ---------------- | ----------------------- | ------------------ | ----------------- | | Browser | IndexedDB (preferred) | ~50MB+ | Until cleared | | Browser | localStorage (fallback) | ~5-10MB | Until cleared | | Node.js | File System | Disk space | Permanent | | Electron | File System | Disk space | Permanent | | React Native | AsyncStorage | Platform dependent | Until uninstalled |

The library automatically detects your environment and chooses the best available storage backend.

📚 Documentation

• API Reference - Complete API documentation
• Examples - Platform-specific examples and use cases
• Migration Guide - Upgrading between versions

🎯 Use Cases

• Offline-first applications - Work without internet connectivity
• Cross-platform development - Same API across web, mobile, and desktop
• Rapid prototyping - Quick setup without external database dependencies
• Local data caching - Store API responses and user preferences
• Development and testing - Mock databases for testing environments

🔧 Advanced Features

Query Builder

// Complex queries with method chaining
const results = await db.user
  .where("age", ">", 18)
  .where("email", "contains", "@company.com")
  .orderBy("createdAt", "desc")
  .limit(50)
  .findMany();

Hooks and Middleware

// Add custom logic to database operations
db.addHook("beforeCreate", (modelName, data) => {
  data.createdBy = getCurrentUserId();
  return data;
});

db.addHook("afterUpdate", (modelName, data) => {
  console.log(`Updated ${modelName}:`, data.id);
});

Data Import/Export

// Backup your data
const backup = await db.export();

// Restore from backup
await db.import(backup, { clearFirst: true });

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/yourusername/universal-db-layer.git
cd universal-db-layer

# Install dependencies
npm install

# Run tests
npm test

# Build the package
npm run build

# Run linting
npm run lint

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

📋 Requirements

• Node.js: >= 14.0.0
• Browsers: Modern browsers with ES2018+ support
• React Native: >= 0.60.0 (with AsyncStorage)

🐛 Issues and Support

• Bug Reports: GitHub Issues
• Feature Requests: GitHub Discussions
• Questions: Stack Overflow

📈 Roadmap

• [ ] Relationships: Support for model relationships and joins
• [ ] Migrations: Automatic schema migrations
• [ ] Encryption: Built-in data encryption support
• [ ] Sync: Cloud synchronization capabilities
• [ ] Plugins: Plugin system for custom storage backends
• [ ] Performance: Query optimization and indexing

🏆 Acknowledgments

• Inspired by Prisma for the API design
• Built with Rollup for optimal bundling
• Tested with Jest for reliability

📄 License

MIT © Your Name