hawiah

v1.1.1

Published

2 months ago

One API. Multiple Databases. Zero Complexity. Schema-less database abstraction with smart relationships and DataLoader optimization. Works with Node.js, Bun, and Deno.

Downloads

Modular database abstraction with virtual relationships. Support for 7 drivers, 50+ methods, and DataLoader batching. One API to rule them all.

✨ Features

Universal API - Same code works with any database
Multiple Drivers - JSON, YAML, SQLite, MongoDB, Firebase, PostgreSQL, MySQL
Runtime Agnostic - Works with Node.js, Bun, and Deno
Virtual Relationships - Define relations between any collections, even across different databases!
Hybrid Schema - Blends SQL tables with NoSQL flexibility (Real columns + JSON)
DataLoader Optimization - Automatic query batching and caching eliminates N+1 problems
Extensible - Create custom drivers for any data source
Schema-less / Schema-full - You choose: Strict validation or total freedom
TypeScript Ready - Full type definitions included

📦 Installation

# Core package (required)
npm install hawiah
# or
bun add hawiah
# or
deno install npm:hawiah

# Choose one or more drivers
npm install @hawiah/local      # JSON & YAML
npm install @hawiah/sqlite     # SQLite
npm install @hawiah/mongo      # MongoDB
npm install @hawiah/firebase   # Firebase Firestore
npm install @hawiah/postgres   # PostgreSQL
npm install @hawiah/mysql      # MySQL

Works with:

✅ Node.js
✅ Bun
✅ Deno

🚀 Quick Start

import { Hawiah } from 'hawiah';
import { MongoDriver } from '@hawiah/mongo';

const db = new Hawiah({
  driver: new MongoDriver({
    uri: 'mongodb://localhost:27017',
    databaseName: 'myapp',
    collectionName: 'users'
  })
});

await db.connect();
await db.insert({ id: 1, name: 'John', age: 25 });
const users = await db.get({});
await db.disconnect();

Switch to SQLite or Firebase? Just change the driver. Your code stays the same.

🧬 The Hybrid Schema System

Hawiah v1.1 introduces a game-changing Hybrid Schema capabilities.

Virtual vs. Real Schemas

How Hawiah handles your schema depends on the driver:

Schema Definition

import { Schema, DataTypes } from '@hawiah/core';

const userSchema = new Schema({
  // Basic Types
  username: { type: DataTypes.STRING, required: true },
  age:      { type: DataTypes.INTEGER, min: 18 },
  
  // Advanced Types
  email:    { type: DataTypes.EMAIL, unique: true },
  tags:     { type: DataTypes.ARRAY },
  
  // Default Values
  isActive: { type: DataTypes.BOOLEAN, default: true },
  created:  { type: DataTypes.DATE, default: () => new Date() }
});

🔗 Virtual Relationships - The Game Changer

Define relationships between collections without foreign keys or schema changes. Works across different databases!

import { Hawiah } from 'hawiah';
import { MongoDriver } from '@hawiah/mongo';
import { SQLiteDriver } from '@hawiah/sqlite';

// Users in MongoDB
const users = new Hawiah({
  driver: new MongoDriver({
    uri: 'mongodb://localhost:27017',
    databaseName: 'myapp',
    collectionName: 'users'
  })
});

// Posts in SQLite
const posts = new Hawiah({
  driver: new SQLiteDriver('./blog.db', 'posts')
});

// Define virtual relationship - MongoDB ↔ SQLite!
users.relation('posts', posts, '_id', 'userId', 'many');
posts.relation('author', users, 'userId', '_id', 'one');

await users.connect();
await posts.connect();

// Query with relationships - automatically optimized!
const usersWithPosts = await users.getWith({}, 'posts');
// Each user includes their posts from SQLite - no N+1 queries!

const postsWithAuthors = await posts.getWith({}, 'author');
// Each post includes author from MongoDB - fully batched!

Why Virtual Relationships are Powerful:

✨ Cross-Database Relations - Connect MongoDB users with SQLite posts, or any combination
⚡ Zero N+1 Problems - DataLoader automatically batches and caches all queries
🚀 No Schema Changes - No foreign keys, no migrations, just pure flexibility
🎯 Type-Safe - Full TypeScript support with proper typing
🔄 Nested Relations - Load relations of relations infinitely
💪 Production Ready - Battle-tested optimization used by GraphQL servers worldwide

🗄️ Available Drivers

| Driver | Package | Use Case | |--------|---------|----------| | JSON | @hawiah/local | Development, Testing | | YAML | @hawiah/local | Configuration | | SQLite | @hawiah/sqlite | Desktop/Mobile Apps | | MongoDB | @hawiah/mongo | Web/Cloud Apps | | Firebase | @hawiah/firebase | Real-time Apps | | PostgreSQL | @hawiah/postgres | Enterprise Apps | | MySQL | @hawiah/mysql | Web Apps | | Custom | - | Any Data Source |

📚 API Overview

Basic Operations: insert, insertMany, get, getOne, getById, update, updateById, remove, removeById, clear

Virtual Relationships:

relation(name, targetCollection, localKey, foreignKey, type) - Define virtual relation
getWith(query, relations) - Load data with relations (auto-optimized with DataLoader)

Advanced: sort, paginate, select, count, sum, group, unique

Arrays: push, pull, shift, unshift, pop

Fields: increment, decrement, unset, rename

📖 Documentation

For detailed documentation, driver examples, relationships guide, and custom driver tutorials:

📚 Full Documentation

🔗 Links

📦 GitHub Repositories

Core & Documentation

hawiah - Main package and unified API
hawiah-core - Core abstractions and base classes
hawiah-docs - Full documentation and guides

Database Drivers

hawiah-local - JSON & YAML driver
hawiah-sqlite - SQLite driver
hawiah-mysql - MySQL driver
hawiah-postgres - PostgreSQL driver
hawiah-firebase - Firebase Firestore driver
hawiah-mongo - MongoDB driver