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

``bash

Using npm

npm install velocedb

Using yarn

yarn add velocedb

Using pnpm

pnpm add velocedb
`

Quick Start

`typescript
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

$3

`typescript
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];
`

$3

`typescript
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

$3

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

`typescript
import { Veloce } from "velocedb";

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

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

$3

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

`typescript
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

`typescript
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

$3

You canmplement functionalities like reload on file change::

`typescript
import { Veloce } from "velocedb";

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

// Manual reload
db.reload();

// Async reload
await db.reloadAsync();
`

$3

`typescript
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();
`

$3

`typescript
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:

`typescript
// 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.json");
`

3. Performance Optimization:

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

4. Error Handling:

`typescript
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