@hawiah/core 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 HAWIAH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# @hawiah/core [![NPM version](https://img.shields.io/npm/v/@hawiah/core.svg?style=flat-square&color=informational)](https://npmjs.com/package/@hawiah/core)
+
+Core package for Hawiah - Schema-less database abstraction layer with multiple driver support, relationships, and DataLoader batching.
+
+> **Note:** This is the core package. For the main package, install `hawiah` instead.
+
+## Installation
+
+```bash
+# Install core package only
+npm install @hawiah/core
+
+# Or install the main package
+npm install hawiah
+```
+
+## Features
+
+- 🚀 Lightweight and fast
+- 🔌 Multiple database driver support
+- 🔗 Built-in relationships with DataLoader batching
+- 📦 Schema-less design
+- 🎯 Simple and intuitive API
+- 🔄 Automatic N+1 query optimization
+- 💾 Memory driver included
+
+## Quick Start
+
+```typescript
+import { Hawiah, MemoryDriver } from '@hawiah/core';
+const db = new Hawiah({ driver: new MemoryDriver() });
+```
+
+## API Methods
+
+### Basic Operations
+- `insert(data)` - Insert a record
+- `insertMany(dataArray)` - Insert multiple records
+- `get(query, limit?)` - Get records matching query
+- `getOne(query)` - Get single record
+- `getAll()` - Get all records
+- `update(query, data)` - Update records
+- `remove(query)` - Remove records
+- `clear()` - Clear all records
+
+### Query Operations
+- `getById(id)` - Get record by ID
+- `getBy(field, value)` - Get records by field value
+- `has(query)` - Check if records exist
+- `count(query)` - Count matching records
+- `sort(query, field, direction)` - Sort results
+- `select(query, fields)` - Select specific fields
+- `paginate(query, page, pageSize)` - Paginate results
+
+### Array Operations
+- `push(query, field, value)` - Add to array
+- `pull(query, field, value)` - Remove from array
+- `shift(query, field)` - Remove first element
+- `unshift(query, field, value)` - Add to beginning
+- `pop(query, field)` - Remove last element
+
+### Numeric Operations
+- `increment(query, field, amount)` - Increment field
+- `decrement(query, field, amount)` - Decrement field
+- `sum(field, query)` - Sum field values
+
+### Relationships
+
+```typescript
+// Define relationships
+const users = new Hawiah({ driver: new MemoryDriver() });
+const posts = new Hawiah({ driver: new MemoryDriver() });
+
+users.relation('posts', posts, '_id', 'userId', 'many');
+posts.relation('author', users, 'userId', '_id', 'one');
+
+// Query with relationships
+const usersWithPosts = await users.getWith({}, 'posts');
+```
+
+## Custom Drivers
+
+Implement the `IDriver` interface to create custom drivers:
+
+```typescript
+import { IDriver, Query, Data } from '@hawiah/core';
+
+class MyDriver implements IDriver {
+  async connect(): Promise<void> { /* ... */ }
+  async disconnect(): Promise<void> { /* ... */ }
+  async get(query: Query): Promise<Data[]> { /* ... */ }
+  async getOne(query: Query): Promise<Data | null> { /* ... */ }
+  async set(data: Data): Promise<Data> { /* ... */ }
+  async update(query: Query, data: Data): Promise<number> { /* ... */ }
+  async delete(query: Query): Promise<number> { /* ... */ }
+  async exists(query: Query): Promise<boolean> { /* ... */ }
+  async count(query: Query): Promise<number> { /* ... */ }
+}
+```
+
+## License
+MIT

package/dist/Hawiah.d.ts

@@ -0,0 +1,348 @@
+import { IDriver, Query, Data } from './interfaces/IDriver';
+/**
+ * Hawiah: A lightweight, schema-less database abstraction layer.
+ * Designed to be friendly and easy to use.
+ */
+export declare class Hawiah {
+    private driver;
+    private isConnected;
+    private relations;
+    private loaders;
+    /**
+     * Creates a new Hawiah instance.
+     * @param options - Configuration options
+     * @param options.driver - The database driver to use
+     */
+    constructor(options: {
+        driver: IDriver;
+    });
+    /**
+     * Connects to the database.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the database.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Adds a new record to the database.
+     * @param data - The data to add
+     * @returns The added record
+     */
+    insert(data: Data): Promise<Data>;
+    /**
+     * Inserts multiple records into the database.
+     * @param dataArray - Array of data to insert
+     * @returns Array of inserted records
+     */
+    insertMany(dataArray: Data[]): Promise<Data[]>;
+    /**
+     * Gets records matching the query.
+     * @param query - The filter condition (default: all)
+     * @param limit - Optional maximum number of records to return
+     * @returns Array of matching records
+     */
+    get(query?: Query, limit?: number): Promise<Data[]>;
+    /**
+     * Gets a single record matching the query.
+     * @param query - The filter condition
+     * @returns The first matching record or null
+     */
+    getOne(query: Query): Promise<Data | null>;
+    /**
+     * Gets all records in the database.
+     * @returns Array of all records
+     */
+    getAll(): Promise<Data[]>;
+    /**
+     * Gets records matching any of the provided queries.
+     * @param queries - Array of filter conditions
+     * @returns Combined array of matching records
+     */
+    getMany(queries: Query[]): Promise<Data[]>;
+    /**
+     * Updates records matching the query.
+     * @param query - The filter condition
+     * @param data - The data to update
+     * @returns Number of updated records
+     */
+    update(query: Query, data: Data): Promise<number>;
+    /**
+     * Updates a single record matching the query.
+     * @param query - The filter condition
+     * @param data - The data to update
+     * @returns True if a record was updated
+     */
+    updateOne(query: Query, data: Data): Promise<boolean>;
+    /**
+     * Saves a record (adds if new, updates if exists).
+     * @param query - The filter condition to check existence
+     * @param data - The data to add or update
+     * @returns The saved record
+     */
+    save(query: Query, data: Data): Promise<Data>;
+    /**
+     * Removes records matching the query.
+     * @param query - The filter condition
+     * @returns Number of removed records
+     */
+    remove(query: Query): Promise<number>;
+    /**
+     * Removes a single record matching the query.
+     * @param query - The filter condition
+     * @returns True if a record was removed
+     */
+    removeOne(query: Query): Promise<boolean>;
+    /**
+     * Clears all records from the database.
+     * @returns Number of removed records
+     */
+    clear(): Promise<number>;
+    /**
+     * Checks if records exist matching the query.
+     * @param query - The filter condition
+     * @returns True if exists
+     */
+    has(query: Query): Promise<boolean>;
+    /**
+     * Counts records matching the query.
+     * @param query - The filter condition
+     * @returns Count of records
+     */
+    count(query?: Query): Promise<number>;
+    /**
+     * Counts records where a field matches a value.
+     * @param field - The field name
+     * @param value - The value to match
+     * @returns Count of records
+     */
+    countBy(field: string, value: any): Promise<number>;
+    /**
+     * Gets a record by its ID.
+     * @param id - The record ID to search for
+     * @returns The matching record or null if not found
+     */
+    getById(id: number | string): Promise<Data | null>;
+    /**
+     * Updates a record by its ID.
+     * @param id - The record ID to update
+     * @param data - The data to update
+     * @returns True if the record was updated
+     */
+    updateById(id: number | string, data: Data): Promise<boolean>;
+    /**
+     * Removes a record by its ID.
+     * @param id - The record ID to remove
+     * @returns True if the record was removed
+     */
+    removeById(id: number | string): Promise<boolean>;
+    /**
+     * Checks if a record exists by its ID.
+     * @param id - The record ID to check
+     * @returns True if the record exists
+     */
+    hasId(id: number | string): Promise<boolean>;
+    /**
+     * Gets records where a field matches a value.
+     * @param field - The field name to match
+     * @param value - The value to match
+     * @returns Array of matching records
+     */
+    getBy(field: string, value: any): Promise<Data[]>;
+    /**
+     * Checks if a record exists where a field matches a value.
+     * @param field - The field name to check
+     * @param value - The value to match
+     * @returns True if a matching record exists
+     */
+    hasBy(field: string, value: any): Promise<boolean>;
+    /**
+     * Sorts the results based on a field.
+     * @param query - The filter condition
+     * @param field - The field to sort by
+     * @param direction - 'asc' or 'desc'
+     * @returns Sorted array of records
+     */
+    sort(query: Query, field: string, direction?: 'asc' | 'desc'): Promise<Data[]>;
+    /**
+     * Selects specific fields from the results.
+     * @param query - The filter condition
+     * @param fields - Array of field names to select
+     * @returns Array of records with only selected fields
+     */
+    select(query: Query, fields: string[]): Promise<Data[]>;
+    /**
+     * Retrieves unique values for a specific field.
+     * @param field - The field to get unique values for
+     * @param query - Optional filter condition
+     * @returns Array of unique values
+     */
+    unique(field: string, query?: Query): Promise<any[]>;
+    /**
+     * Groups records by a specific field.
+     * @param field - The field to group by
+     * @param query - Optional filter condition
+     * @returns Object where keys are group values and values are arrays of records
+     */
+    group(field: string, query?: Query): Promise<{
+        [key: string]: Data[];
+    }>;
+    /**
+     * Paginates results.
+     * @param query - The filter condition
+     * @param page - Page number (1-based)
+     * @param pageSize - Records per page
+     * @returns Pagination result object
+     */
+    paginate(query: Query, page?: number, pageSize?: number): Promise<{
+        data: Data[];
+        page: number;
+        pageSize: number;
+        total: number;
+        totalPages: number;
+    }>;
+    /**
+     * Calculates the sum of a numeric field.
+     * @param field - The field to sum
+     * @param query - Optional filter condition
+     * @returns The sum of all values in the field
+     */
+    sum(field: string, query?: Query): Promise<number>;
+    /**
+     * Increments a numeric field by a specified amount.
+     * @param query - The filter condition to find the record
+     * @param field - The field to increment
+     * @param amount - The amount to increment by (default: 1)
+     * @returns The new value after incrementing
+     * @throws Error if record is not found
+     */
+    increment(query: Query, field: string, amount?: number): Promise<number>;
+    /**
+     * Decrements a numeric field by a specified amount.
+     * @param query - The filter condition to find the record
+     * @param field - The field to decrement
+     * @param amount - The amount to decrement by (default: 1)
+     * @returns The new value after decrementing
+     * @throws Error if record is not found
+     */
+    decrement(query: Query, field: string, amount?: number): Promise<number>;
+    /**
+     * Pushes a value to the end of an array field.
+     * @param query - The filter condition to find records
+     * @param field - The array field to push to
+     * @param value - The value to push
+     * @returns Number of records updated
+     */
+    push(query: Query, field: string, value: any): Promise<number>;
+    /**
+     * Removes all occurrences of a value from an array field.
+     * @param query - The filter condition to find records
+     * @param field - The array field to pull from
+     * @param value - The value to remove
+     * @returns Number of records updated
+     */
+    pull(query: Query, field: string, value: any): Promise<number>;
+    /**
+     * Removes the first element from an array field.
+     * @param query - The filter condition to find records
+     * @param field - The array field to shift
+     * @returns Number of records updated
+     */
+    shift(query: Query, field: string): Promise<number>;
+    /**
+     * Adds a value to the beginning of an array field.
+     * @param query - The filter condition to find records
+     * @param field - The array field to unshift to
+     * @param value - The value to add
+     * @returns Number of records updated
+     */
+    unshift(query: Query, field: string, value: any): Promise<number>;
+    /**
+     * Removes the last element from an array field.
+     * @param query - The filter condition to find records
+     * @param field - The array field to pop from
+     * @returns Number of records updated
+     */
+    pop(query: Query, field: string): Promise<number>;
+    /**
+     * Removes a field from matching records.
+     * @param query - The filter condition to find records
+     * @param field - The field name to remove
+     * @returns Number of records updated
+     */
+    unset(query: Query, field: string): Promise<number>;
+    /**
+     * Renames a field in matching records.
+     * @param query - The filter condition to find records
+     * @param oldField - The current field name
+     * @param newField - The new field name
+     * @returns Number of records updated
+     */
+    rename(query: Query, oldField: string, newField: string): Promise<number>;
+    /**
+     * Gets the first record in the database.
+     * @returns The first record or null if empty
+     */
+    first(): Promise<Data | null>;
+    /**
+     * Gets the last record in the database.
+     * @returns The last record or null if empty
+     */
+    last(): Promise<Data | null>;
+    /**
+     * Checks if the database is empty.
+     * @returns True if no records exist
+     */
+    isEmpty(): Promise<boolean>;
+    /**
+     * Gets random records from the database.
+     * @param sampleSize - Number of random records to return (default: 1)
+     * @returns Array of random records
+     */
+    random(sampleSize?: number): Promise<Data[]>;
+    /**
+     * Ensures the database is connected before executing operations.
+     * @throws Error if database is not connected
+     * @private
+     */
+    private ensureConnected;
+    /**
+     * Gets the underlying database driver.
+     * @returns The database driver instance
+     */
+    getDriver(): IDriver;
+    /**
+     * Checks if the database connection is active.
+     * @returns True if connected
+     */
+    isActive(): boolean;
+    /**
+     * Define a relationship with another Hawiah instance
+     * @param name - Relationship name
+     * @param target - Target Hawiah instance
+     * @param localKey - Local field name
+     * @param foreignKey - Foreign field name
+     * @param type - Relationship type ('one' or 'many')
+     */
+    relation(name: string, target: Hawiah, localKey: string, foreignKey: string, type?: 'one' | 'many'): this;
+    /**
+     * Get records with populated relationships
+     * @param query - Query filter
+     * @param relations - Relationship names to populate
+     */
+    getWith(query?: Query, ...relations: string[]): Promise<Data[]>;
+    /**
+     * Get one record with populated relationships
+     * @param query - Query filter
+     * @param relations - Relationship names to populate
+     */
+    getOneWith(query: Query, ...relations: string[]): Promise<Data | null>;
+    /**
+     * Load a relationship for records using DataLoader batching
+     */
+    private loadRelation;
+    /**
+     * Clear relationship cache
+     */
+    clearCache(): void;
+}