dimond-db 1.0.0

package/src/engine/StorageEngine.js

@@ -0,0 +1,177 @@
+import { join } from 'path';
+import { FileStorage } from '../storage/FileStorage.js';
+import { StorageError } from '../errors/DatabaseError.js';
+
+/**
+ * Storage Engine - Manages collection file operations
+ */
+export class StorageEngine {
+    /**
+     * @param {string} databasePath - Root path for the database
+     */
+    constructor(databasePath) {
+        this.databasePath = databasePath;
+        this.collectionsPath = join(databasePath, 'collections');
+        this.metadataPath = join(databasePath, 'metadata.json');
+    }
+
+    /**
+     * Initializes the database storage structure
+     */
+    async initialize() {
+        await FileStorage.ensureDir(this.databasePath);
+        await FileStorage.ensureDir(this.collectionsPath);
+
+        // Create metadata if it doesn't exist
+        if (!(await FileStorage.exists(this.metadataPath))) {
+            await this.writeMetadata({
+                version: '1.0.0',
+                collections: [],
+                createdAt: new Date().toISOString()
+            });
+        }
+    }
+
+    /**
+     * Gets the file path for a collection
+     * @param {string} collectionName - Name of the collection
+     * @returns {string} Full path to the collection file
+     */
+    getCollectionPath(collectionName) {
+        return join(this.collectionsPath, `${collectionName}.collection`);
+    }
+
+    /**
+     * Checks if a collection exists
+     * @param {string} collectionName - Name of the collection
+     * @returns {Promise<boolean>} True if collection exists
+     */
+    async collectionExists(collectionName) {
+        const collectionPath = this.getCollectionPath(collectionName);
+        return await FileStorage.exists(collectionPath);
+    }
+
+    /**
+     * Reads a collection file
+     * @param {string} collectionName - Name of the collection
+     * @returns {Promise<Array>} Array of documents
+     */
+    async readCollection(collectionName) {
+        const collectionPath = this.getCollectionPath(collectionName);
+
+        if (!(await FileStorage.exists(collectionPath))) {
+            return [];
+        }
+
+        try {
+            return await FileStorage.readJSON(collectionPath);
+        } catch (error) {
+            throw new StorageError(
+                `Failed to read collection "${collectionName}"`,
+                error
+            );
+        }
+    }
+
+    /**
+     * Writes documents to a collection file
+     * @param {string} collectionName - Name of the collection
+     * @param {Array} documents - Array of documents to write
+     */
+    async writeCollection(collectionName, documents) {
+        // Ensure collection exists before writing
+        if (!(await this.collectionExists(collectionName))) {
+            await this.createCollection(collectionName);
+        }
+
+        const collectionPath = this.getCollectionPath(collectionName);
+
+        try {
+            await FileStorage.writeJSON(collectionPath, documents);
+        } catch (error) {
+            throw new StorageError(
+                `Failed to write collection "${collectionName}"`,
+                error
+            );
+        }
+    }
+
+    /**
+     * Creates a new collection
+     * @param {string} collectionName - Name of the collection
+     */
+    async createCollection(collectionName) {
+        const collectionPath = this.getCollectionPath(collectionName);
+
+        // Create empty collection file
+        await FileStorage.writeJSON(collectionPath, []);
+
+        // Update metadata
+        const metadata = await this.readMetadata();
+        if (!metadata.collections.includes(collectionName)) {
+            metadata.collections.push(collectionName);
+            await this.writeMetadata(metadata);
+        }
+    }
+
+    /**
+     * Deletes a collection
+     * @param {string} collectionName - Name of the collection
+     */
+    async deleteCollection(collectionName) {
+        const collectionPath = this.getCollectionPath(collectionName);
+
+        // Delete collection file
+        await FileStorage.deleteFile(collectionPath);
+
+        // Update metadata
+        const metadata = await this.readMetadata();
+        metadata.collections = metadata.collections.filter(
+            name => name !== collectionName
+        );
+        await this.writeMetadata(metadata);
+    }
+
+    /**
+     * Lists all collections
+     * @returns {Promise<Array<string>>} Array of collection names
+     */
+    async listCollections() {
+        const files = await FileStorage.listFiles(this.collectionsPath);
+        return files
+            .filter(file => file.endsWith('.collection'))
+            .map(file => file.replace('.collection', ''));
+    }
+
+    /**
+     * Reads metadata
+     * @returns {Promise<Object>} Metadata object
+     */
+    async readMetadata() {
+        try {
+            return await FileStorage.readJSON(this.metadataPath);
+        } catch (error) {
+            // Return default metadata if file doesn't exist or is corrupted
+            return {
+                version: '1.0.0',
+                collections: [],
+                createdAt: new Date().toISOString()
+            };
+        }
+    }
+
+    /**
+     * Writes metadata
+     * @param {Object} metadata - Metadata object to write
+     */
+    async writeMetadata(metadata) {
+        await FileStorage.writeJSON(this.metadataPath, metadata);
+    }
+
+    /**
+     * Deletes the entire database
+     */
+    async dropDatabase() {
+        await FileStorage.deleteDir(this.databasePath);
+    }
+}

package/src/errors/DatabaseError.js

@@ -0,0 +1,68 @@
+/**
+ * Base class for all LocalDB errors
+ */
+export class DatabaseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+
+/**
+ * Thrown when a collection is not found
+ */
+export class CollectionNotFoundError extends DatabaseError {
+    constructor(collectionName) {
+        super(`Collection "${collectionName}" not found`);
+        this.collectionName = collectionName;
+    }
+}
+
+/**
+ * Thrown when attempting to insert a document with a duplicate _id
+ */
+export class DuplicateKeyError extends DatabaseError {
+    constructor(id) {
+        super(`Duplicate key error: document with _id "${id}" already exists`);
+        this.id = id;
+    }
+}
+
+/**
+ * Thrown when document validation fails
+ */
+export class ValidationError extends DatabaseError {
+    constructor(message) {
+        super(`Validation error: ${message}`);
+    }
+}
+
+/**
+ * Thrown when a query is malformed or invalid
+ */
+export class QueryError extends DatabaseError {
+    constructor(message) {
+        super(`Query error: ${message}`);
+    }
+}
+
+/**
+ * Thrown when storage operations fail
+ */
+export class StorageError extends DatabaseError {
+    constructor(message, cause) {
+        super(`Storage error: ${message}`);
+        this.cause = cause;
+    }
+}
+
+/**
+ * Thrown when database operations fail
+ */
+export class DatabaseOperationError extends DatabaseError {
+    constructor(operation, message) {
+        super(`Database operation "${operation}" failed: ${message}`);
+        this.operation = operation;
+    }
+}

package/src/index.js

@@ -0,0 +1,18 @@
+import { Database } from './database/Database.js';
+
+// Export the main Database class as LocalDB
+export { Database as LocalDB };
+
+// Export error classes for advanced error handling
+export {
+    DatabaseError,
+    CollectionNotFoundError,
+    DuplicateKeyError,
+    ValidationError,
+    QueryError,
+    StorageError,
+    DatabaseOperationError
+} from './errors/DatabaseError.js';
+
+// Default export
+export default Database;

package/src/query/operators.js

@@ -0,0 +1,187 @@
+import { QueryError } from '../errors/DatabaseError.js';
+
+/**
+ * Comparison operators for querying documents
+ */
+
+/**
+ * Equality comparison ($eq)
+ * @param {*} fieldValue - The field value from the document
+ * @param {*} queryValue - The value to compare against
+ * @returns {boolean} True if values are equal
+ */
+export function $eq(fieldValue, queryValue) {
+    return fieldValue === queryValue;
+}
+
+/**
+ * Inequality comparison ($ne)
+ * @param {*} fieldValue - The field value from the document
+ * @param {*} queryValue - The value to compare against
+ * @returns {boolean} True if values are not equal
+ */
+export function $ne(fieldValue, queryValue) {
+    return fieldValue !== queryValue;
+}
+
+/**
+ * Greater than comparison ($gt)
+ * @param {*} fieldValue - The field value from the document
+ * @param {*} queryValue - The value to compare against
+ * @returns {boolean} True if field value is greater than query value
+ */
+export function $gt(fieldValue, queryValue) {
+    return fieldValue > queryValue;
+}
+
+/**
+ * Greater than or equal comparison ($gte)
+ * @param {*} fieldValue - The field value from the document
+ * @param {*} queryValue - The value to compare against
+ * @returns {boolean} True if field value is greater than or equal to query value
+ */
+export function $gte(fieldValue, queryValue) {
+    return fieldValue >= queryValue;
+}
+
+/**
+ * Less than comparison ($lt)
+ * @param {*} fieldValue - The field value from the document
+ * @param {*} queryValue - The value to compare against
+ * @returns {boolean} True if field value is less than query value
+ */
+export function $lt(fieldValue, queryValue) {
+    return fieldValue < queryValue;
+}
+
+/**
+ * Less than or equal comparison ($lte)
+ * @param {*} fieldValue - The field value from the document
+ * @param {*} queryValue - The value to compare against
+ * @returns {boolean} True if field value is less than or equal to query value
+ */
+export function $lte(fieldValue, queryValue) {
+    return fieldValue <= queryValue;
+}
+
+/**
+ * In array comparison ($in)
+ * @param {*} fieldValue - The field value from the document
+ * @param {Array} queryValue - The array of values to check against
+ * @returns {boolean} True if field value is in the array
+ */
+export function $in(fieldValue, queryValue) {
+    if (!Array.isArray(queryValue)) {
+        throw new QueryError('$in operator requires an array');
+    }
+    return queryValue.includes(fieldValue);
+}
+
+/**
+ * Not in array comparison ($nin)
+ * @param {*} fieldValue - The field value from the document
+ * @param {Array} queryValue - The array of values to check against
+ * @returns {boolean} True if field value is not in the array
+ */
+export function $nin(fieldValue, queryValue) {
+    if (!Array.isArray(queryValue)) {
+        throw new QueryError('$nin operator requires an array');
+    }
+    return !queryValue.includes(fieldValue);
+}
+
+/**
+ * Field exists check ($exists)
+ * @param {*} fieldValue - The field value from the document
+ * @param {boolean} queryValue - Whether the field should exist
+ * @returns {boolean} True if existence matches expectation
+ */
+export function $exists(fieldValue, queryValue) {
+    const exists = fieldValue !== undefined;
+    return queryValue ? exists : !exists;
+}
+
+/**
+ * Map of operator names to their functions
+ */
+export const OPERATORS = {
+    $eq,
+    $ne,
+    $gt,
+    $gte,
+    $lt,
+    $lte,
+    $in,
+    $nin,
+    $exists
+};
+
+/**
+ * Checks if a key is a query operator
+ * @param {string} key - The key to check
+ * @returns {boolean} True if the key is an operator
+ */
+export function isOperator(key) {
+    return key.startsWith('$') && key in OPERATORS;
+}
+
+/**
+ * Gets the nested value from an object using dot notation
+ * @param {Object} obj - The object to get the value from
+ * @param {string} path - The dot-notation path (e.g., 'user.address.city')
+ * @returns {*} The value at the path, or undefined if not found
+ */
+export function getNestedValue(obj, path) {
+    const keys = path.split('.');
+    let value = obj;
+
+    for (const key of keys) {
+        if (value === null || value === undefined) {
+            return undefined;
+        }
+        value = value[key];
+    }
+
+    return value;
+}
+
+/**
+ * Sets a nested value in an object using dot notation
+ * @param {Object} obj - The object to set the value in
+ * @param {string} path - The dot-notation path
+ * @param {*} value - The value to set
+ */
+export function setNestedValue(obj, path, value) {
+    const keys = path.split('.');
+    const lastKey = keys.pop();
+
+    let current = obj;
+    for (const key of keys) {
+        if (!(key in current) || typeof current[key] !== 'object') {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+
+    current[lastKey] = value;
+}
+
+/**
+ * Deletes a nested value from an object using dot notation
+ * @param {Object} obj - The object to delete the value from
+ * @param {string} path - The dot-notation path
+ */
+export function deleteNestedValue(obj, path) {
+    const keys = path.split('.');
+    const lastKey = keys.pop();
+
+    let current = obj;
+    for (const key of keys) {
+        if (!(key in current)) {
+            return;
+        }
+        current = current[key];
+    }
+
+    delete current[lastKey];
+}

package/src/storage/FileStorage.js

@@ -0,0 +1,131 @@
+import { promises as fs } from 'fs';
+import { join, dirname } from 'path';
+import { StorageError } from '../errors/DatabaseError.js';
+
+/**
+ * File Storage - Handles all file system operations
+ */
+export class FileStorage {
+    /**
+     * Reads a JSON file and returns parsed content
+     * @param {string} filePath - Path to the file
+     * @returns {Promise<*>} Parsed JSON content
+     */
+    static async readJSON(filePath) {
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            return JSON.parse(content);
+        } catch (error) {
+            if (error.code === 'ENOENT') {
+                throw new StorageError(`File not found: ${filePath}`, error);
+            }
+            if (error instanceof SyntaxError) {
+                throw new StorageError(`Invalid JSON in file: ${filePath}`, error);
+            }
+            throw new StorageError(`Failed to read file: ${filePath}`, error);
+        }
+    }
+
+    /**
+     * Writes data to a JSON file
+     * @param {string} filePath - Path to the file
+     * @param {*} data - Data to write
+     */
+    static async writeJSON(filePath, data) {
+        try {
+            // Ensure parent directory exists
+            const parentDir = dirname(filePath);
+            await this.ensureDir(parentDir);
+
+            const content = JSON.stringify(data, null, 2);
+
+            // Atomic write: write to temp file then rename
+            const tempPath = `${filePath}.tmp`;
+            await fs.writeFile(tempPath, content, 'utf-8');
+            await fs.rename(tempPath, filePath);
+        } catch (error) {
+            throw new StorageError(`Failed to write file: ${filePath}`, error);
+        }
+    }
+
+    /**
+     * Checks if a file exists
+     * @param {string} filePath - Path to check
+     * @returns {Promise<boolean>} True if file exists
+     */
+    static async exists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * Creates a directory and all parent directories if they don't exist
+     * @param {string} dirPath - Directory path to create
+     */
+    static async ensureDir(dirPath) {
+        try {
+            await fs.mkdir(dirPath, { recursive: true });
+        } catch (error) {
+            throw new StorageError(`Failed to create directory: ${dirPath}`, error);
+        }
+    }
+
+    /**
+     * Deletes a file
+     * @param {string} filePath - Path to the file
+     */
+    static async deleteFile(filePath) {
+        try {
+            await fs.unlink(filePath);
+        } catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw new StorageError(`Failed to delete file: ${filePath}`, error);
+            }
+        }
+    }
+
+    /**
+     * Lists all files in a directory
+     * @param {string} dirPath - Directory path
+     * @returns {Promise<string[]>} Array of file names
+     */
+    static async listFiles(dirPath) {
+        try {
+            return await fs.readdir(dirPath);
+        } catch (error) {
+            if (error.code === 'ENOENT') {
+                return [];
+            }
+            throw new StorageError(`Failed to list directory: ${dirPath}`, error);
+        }
+    }
+
+    /**
+     * Deletes a directory and all its contents
+     * @param {string} dirPath - Directory path
+     */
+    static async deleteDir(dirPath) {
+        try {
+            await fs.rm(dirPath, { recursive: true, force: true });
+        } catch (error) {
+            throw new StorageError(`Failed to delete directory: ${dirPath}`, error);
+        }
+    }
+
+    /**
+     * Gets file stats
+     * @param {string} filePath - Path to the file
+     * @returns {Promise<Object>} File stats
+     */
+    static async getStats(filePath) {
+        try {
+            return await fs.stat(filePath);
+        } catch (error) {
+            throw new StorageError(`Failed to get file stats: ${filePath}`, error);
+        }
+    }
+}

package/src/utils/deepClone.js

@@ -0,0 +1,31 @@
+/**
+ * Creates a deep clone of an object
+ * @param {*} obj - The object to clone
+ * @returns {*} A deep clone of the object
+ */
+export function deepClone(obj) {
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+
+    if (obj instanceof Date) {
+        return new Date(obj.getTime());
+    }
+
+    if (obj instanceof RegExp) {
+        return new RegExp(obj.source, obj.flags);
+    }
+
+    if (Array.isArray(obj)) {
+        return obj.map(item => deepClone(item));
+    }
+
+    const cloned = {};
+    for (const key in obj) {
+        if (obj.hasOwnProperty(key)) {
+            cloned[key] = deepClone(obj[key]);
+        }
+    }
+
+    return cloned;
+}

package/src/utils/idGenerator.js

@@ -0,0 +1,35 @@
+import { randomBytes } from 'crypto';
+
+/**
+ * Generates a UUID v4 compliant unique identifier
+ * @returns {string} A UUID string
+ */
+export function generateId() {
+    const bytes = randomBytes(16);
+
+    // Set version (4) and variant bits according to RFC 4122
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // Version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // Variant 10
+
+    const hex = bytes.toString('hex');
+
+    return [
+        hex.substring(0, 8),
+        hex.substring(8, 12),
+        hex.substring(12, 16),
+        hex.substring(16, 20),
+        hex.substring(20, 32)
+    ].join('-');
+}
+
+/**
+ * Validates if a string is a valid UUID format
+ * @param {string} id - The ID to validate
+ * @returns {boolean} True if valid UUID format
+ */
+export function isValidId(id) {
+    if (typeof id !== 'string') return false;
+
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(id);
+}