velocedb
Version:
High-performance, secure, and robust local database
321 lines (226 loc) • 7.41 kB
Markdown
# 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.
[](https://www.npmjs.com/package/velocedb)
[](https://opensource.org/licenses/MIT)
[](https://github.com/amirfarzamnia/velocedb/issues)
[](https://github.com/amirfarzamnia/velocedb/stargazers)
[](https://github.com/amirfarzamnia/velocedb/forks)
## 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
### Basic CRUD Operations
```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];
```
### Working with Complex Data
```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
### Proxy Mode (Default)
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!";
```
### No Proxy Mode
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
### Hot Reloading
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();
```
### Manual File Operations
```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();
```
### Event Handling
```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>("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](CONTRIBUTING.md) for details.
## License
VeloceDB is licensed under the [MIT License](https://opensource.org/licenses/MIT).
## Support
For support, please:
1. Check the [documentation](https://github.com/amirfarzamnia/velocedb)
2. Search existing issues
3. Create a new issue if needed