Jsonjsdb

A comprehensive client-side relational database solution for static Single Page Applications (SPA). Jsonjsdb enables offline data storage and querying capabilities when running applications locally (file://) or over HTTP/HTTPS (localhost or production servers).

Table of Contents

• 🚀 Quick Start
• 📦 Packages
  • jsonjsdb - Core Library
  • jsonjsdb-builder - Build Tool
• 🎯 Use Cases & Limitations
  • ✅ Perfect for
  • ⚠️ Limitations
• 🤝 Contributing
• 📄 License

🚀 Quick Start

npm install jsonjsdb

import Jsonjsdb from 'jsonjsdb'

const db = new Jsonjsdb()
await db.init()
const users = db.getAll('user')

📦 Packages

This monorepo contains two complementary packages:

jsonjsdb - Core Library

The main client-side database library for frontend applications.

• ✅ Client-side relational database
• ✅ File system (file://) and HTTP/HTTPS support
• ✅ Runs locally or on web servers
• ✅ Memory-based fast queries
• ✅ Supports 100-200MB databases

📖 View Documentation

jsonjsdb-builder - Build Tool

Development tooling to convert Excel files to jsonjs database format.

• ✅ Excel to .json and .json.js conversion
• ✅ Vite integration
• ✅ Watch mode for development
• ✅ Automatic database updates

📖 View Documentation

🎯 Use Cases & Limitations

✅ Perfect for:

Offline Applications

• Applications that need to function without network connectivity
• Local-first applications with occasional sync capabilities
• Embedded applications in restricted environments

Corporate Deployments

• Enterprise environments with strict security policies
• Applications deployed on shared drives or local networks
• Solutions requiring minimal IT infrastructure approval

Portable Solutions

• Cross-platform compatibility (server, desktop, shared storage)
• Simple drag-and-drop deployment without installation
• Applications that need to run from USB drives or isolated systems

Static Sites with Data

• Documentation sites with searchable content
• Catalogs and directories with filtering capabilities
• Educational resources with interactive data exploration

⚠️ Limitations

Data Interactivity

• Not designed for real-time collaborative features
• Users cannot interact with each other through the database
• Similar limitations to static website architectures

Update Strategy

• Optimized for batch data updates rather than real-time modifications
• Database updates require regenerating the entire dataset
• Best suited for periodically updated, relatively stable data

Memory Constraints

• Entire database loads into memory during initialization
• Performance testing shows optimal range: 100-200MB on modern systems
• Larger datasets may cause performance degradation or memory issues

Browser Compatibility

• Requires modern browser support for local file system access
• Some features may be limited in older browser versions

🤝 Contributing

Contributions are welcome! Whether it's bug reports, new features, or improvements, your input is appreciated.

📄 License

MIT License - see LICENSE for details.