Velocedb

⚠️ Development & Testing Only ⚠️

VeloceDB is a high-performance, secure, and robust local database designed specifically for development and testing environments. It is not recommended for production use, especially in mid-to-large scale applications, as it prioritizes development convenience over production-grade performance and scalability.

Features

• Development-Focused: Optimized for rapid development and testing workflows
• High Performance: Fast data access and modifications
• Security: Built with robust security measures
• Flexibility: Supports all data types and complex data structures
• Ease of Use: Simple API, no need for complex functions to interact with data
• Debugging: Advanced debugging features for better data management
• Hot Reloading: Automatic file watching and data reloading
• Dual Mode: Choose between Proxy and No-Proxy modes for different use cases

Installation

# Using npm
npm install velocedb

# Using yarn
yarn add velocedb

# Using pnpm
pnpm add velocedb

Quick Start

import { Veloce } from "velocedb";

// Initialize database with base data
const db = new Veloce("database.json", {
  users: [],
  settings: {},
});

// Basic operations
db.data.users = [
  { id: 1, name: "John" },
  { id: 2, name: "Jane" },
];

// Data is automatically saved
console.log(db.data.users[0].name); // "John"

Usage Examples

Basic CRUD Operations

import { Veloce } from "velocedb";

// Initialize with base data structure
const db = new Veloce("database.json", {
  users: [],
  settings: {},
});

// Create
db.data.users = [{ id: 1, name: "John" }];

// Read
const user = db.data.users[0];

// Update
db.data.users[0].name = "Johnny";

// Delete
delete db.data.users[0];

Working with Complex Data

import { Veloce } from "velocedb";

// Initialize with base data structure
const db = new Veloce("database.json", {
  config: {},
  tasks: [],
  mixed: {},
});

// Nested objects
db.data.config = {
  settings: {
    theme: "dark",
    notifications: true,
  },
};

// Arrays
db.data.tasks = [
  { id: 1, title: "Task 1", completed: false },
  { id: 2, title: "Task 2", completed: true },
];

// Mixed data types
db.data.mixed = {
  string: "text",
  number: 42,
  boolean: true,
  array: [1, 2, 3],
  object: { key: "value" },
};

Modes of Operation

Proxy Mode (Default)

Proxy Mode provides advanced features like auto-save and update tracking. It's ideal for development and testing.

import { Veloce } from "velocedb";

const db = new Veloce("database.json", { value: "" });

// Auto-save enabled by default
db.data.value = "Hello World!";

No Proxy Mode

No Proxy Mode is optimized for performance and direct data manipulation. It requires manual saving.

import { Veloce } from "velocedb";

const db = new Veloce("database.json", { value: "" }, { noProxy: true });

db.data = { value: "Hello World!" };
db.save(); // Manual save required

Configuration Options

interface VeloceConfig {
  // File indentation (default: 2)
  indentation?: number;

  // Auto-save enabled (default: true)
  autoSave?: boolean;

  // No-proxy mode (default: false)
  noProxy?: boolean;

  // Auto-save delay in milliseconds (default: 750)
  autoSaveDelayMs?: number;

  // Save retry timeout in milliseconds (default: 100)
  saveRetryTimeoutMs?: number;

  // Update callback function
  onUpdate?: (method: string, result: unknown) => void;

  // Maximum auto-save timeouts (default: 10)
  maxAutoSaveTimeouts?: number;

  // File system options (default: { encoding: "utf-8" })
  fileOptions?: fs.WriteFileOptions;

  // Use synchronous operations (default: false)
  useSync?: boolean;
}

Advanced Usage

Hot Reloading

You canmplement functionalities like reload on file change::

import { Veloce } from "velocedb";

const db = new Veloce("database.json", {});

// Manual reload
db.reload();

// Async reload
await db.reloadAsync();

Manual File Operations

import { Veloce } from "velocedb";

const db = new Veloce("database.json", {});

// Save manually
db.save();

// Async save
await db.saveAsync();

// Delete database file
db.delete();

// Async delete
await db.deleteAsync();

Event Handling

import { Veloce } from "velocedb";

const db = new Veloce(
  "database.json",
  {},
  {
    onUpdate: (method, result) => {
      console.log(`Operation: ${method}`);
      console.log(`Result: ${result}`);
    },
  }
);

Best Practices

1. Development Only: Use VeloceDB exclusively for development and testing environments.

2. Data Structure Planning:

   // Define clear data structures
   interface User {
     id: number;
     name: string;
     email: string;
   }
   
   interface Database {
     users: User[];
     settings: {
       theme: string;
       notifications: boolean;
     };
   }
   
   const db = new Veloce<Database>("database.json");

3. Performance Optimization:

   • Use No-Proxy mode for large datasets
   • Increase autoSaveDelayMs for frequent updates
   • Batch updates when possible

4. Error Handling:

   try {
     db.data.value = "test";
   } catch (error) {
     console.error("Database operation failed:", error);
   }

Common Pitfalls

1. Production Use: Avoid using VeloceDB in production environments.

2. Large Datasets: Performance may degrade with very large datasets.

3. Concurrent Access: Not designed for concurrent access from multiple processes.

4. Memory Usage: Keep an eye on memory usage with large datasets.

Troubleshooting

1. Data Not Saving:

   • Check file permissions
   • Verify autoSave is enabled
   • Ensure proper error handling

2. Performance Issues:

   • Switch to No-Proxy mode
   • Increase autoSaveDelayMs
   • Reduce data complexity

3. File Corruption:

   • Regular backups
   • Use reload() to refresh data
   • Check file integrity

Contributing

Contributions are welcome! Please read our Contributing Guidelines for details.

License

VeloceDB is licensed under the MIT License.

Support

For support, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue if needed