universal-db-layer

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 unified-db-layer

For React Native projects, also install:

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

Basic Usage

import { UnifiedDB } from "unified-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: "[e-mail]",
  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/unified-db-layer.git
cd unified-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

Made with ❤️ for the JavaScript community