entidb library

EntiDB - A robust, embedded document database for Dart

EntiDB provides a feature-rich document database with support for:

Entity Storage: Generic, type-safe storage for any Entity
Collections: Type-safe collections with indexing and queries
Transactions: ACID-compliant transactions with isolation levels
Indexing: BTree and Hash indexes for fast queries
Encryption: Optional AES-GCM encryption at rest
Migrations: Bidirectional schema migrations with rollback support
Backup: Point-in-time snapshots with integrity verification
Logging: Structured logging with configurable levels

Quick Start

import 'package:entidb/entidb.dart';

// Define your entity
class Product implements Entity {
  @override
  final String? id;
  final String name;
  final double price;

  Product({this.id, required this.name, required this.price});

  @override
  Map<String, dynamic> toMap() => {'name': name, 'price': price};

  static Product fromMap(String id, Map<String, dynamic> map) =>
    Product(id: id, name: map['name'], price: map['price']);
}

// Open database
final db = await EntiDB.open(
  path: './myapp_data',
  config: EntiDBConfig.production(),
);

// Get a collection
final products = await db.collection<Product>(
  'products',
  fromMap: Product.fromMap,
);

// Insert and query
await products.insert(Product(name: 'Widget', price: 29.99));
final results = await products.find(
  QueryBuilder().whereGreaterThan('price', 20.0).build(),
);

// Close when done
await db.close();

See individual module documentation for detailed usage.

Classes

AesGcmEncryptionService: AES-GCM encryption service implementation.
AllQuery: A query that matches all entities.
AndQuery: Query to combine multiple queries with a logical AND.
AuthenticationConfig: Configuration for the authentication service.
AuthenticationService: Comprehensive authentication service for EntiDB.
BackupConfig: Configuration options for the backup service.
BackupManager<D extends Entity, U extends Entity>: Manages backup and restore operations for data and user storage.
BackupMetadata: Represents metadata for a backup file.
BackupResult: Represents the result of a backup or restore operation.
BackupService<T extends Entity>: A robust backup service for entity storage.
BetweenQuery: Query to check if a field's value falls within a range.
BTreeIndex: B-tree index implementation using a self-balancing tree structure.
CacheStatistics: Statistics about cache performance.
Collection<T extends Entity>: A type-safe collection of entities with indexing and query support.
CollectionConfig: Configuration for collection behavior.
CollectionStats: Statistics for a single collection.
CombinedBackupResult: Result of a combined backup/restore operation.
CombinedMemoryBackup: Combined in-memory backups for both storages.
ContainsQuery: Query to check if a string or list field contains a value.
DerivedKey: Result of a key derivation operation.
DifferentialSnapshot: A differential backup snapshot containing changes since a base backup.
EncryptionResult: Result of an encryption operation.
EncryptionService: Abstract interface for encryption services.
EndsWithQuery: Query to check if a string field ends with a suffix.
EntiDB: The main EntiDB database class.
EntiDBConfig: Configuration for EntiDB database instance.
EntiDBLogger: A thread-safe logging utility for EntiDB with module-specific contexts.
EntiDBStats: Database statistics.
Entity: Base interface for all storable entities in EntiDB.
EqualsQuery: Query to check if a field equals a specific value.
ExistsQuery: Query to check if a field exists in the data map.
FullTextConfig: Configuration options for full-text indexing.
FullTextIndex: Full-text search index using an inverted index structure.
GreaterThanOrEqualsQuery: Query to check if a field's value is greater than or equal to a specified value.
GreaterThanQuery: Query to check if a field's value is greater than a specified value.
HashIndex: Hash-based index implementation for O(1) exact-match lookups.
IIndex: Abstract interface for index implementations.
IncrementalSnapshot: An incremental backup snapshot containing changes since the previous backup.
IndexManager: Manages multiple indexes for a collection.
IndexMetadata: Metadata about a persisted index.
IndexPersistence: Manages persistent storage of indexes to disk.
IndexStatistics: Statistics about an index for query optimization.
InQuery: Query to check if a field's value exists within a list of values.
IQuery: Abstract interface for all query types.
IsNotNullQuery: Query to check if a field's value is not null.
IsNullQuery: Query to check if a field's value is null.
KeyDerivationConfig: Configuration for PBKDF2 key derivation.
KeyDerivationService: Password-based key derivation service.
LessThanOrEqualsQuery: Query to check if a field's value is less than or equal to a specified value.
LessThanQuery: Query to check if a field's value is less than a specified value.
LoggerConfig: Configuration options for EntiDBLogger.
LoginResult: Result of a successful login.
MemoryStorage<T extends Entity>: In-memory storage implementation for testing and development.
MigrationConfig: Configuration for the migration system.
MigrationLog: A record of a single migration execution.
MigrationManager<D extends Entity, U extends Entity>: Manages migrations for both data and user storage.
MigrationResult: Result of a migration operation.
MigrationRunner<T extends Entity>: Executes migrations for an entity storage.
MigrationStatus: Status of migrations for both data and user storage.
MigrationStep: Represents a single migration step in a migration path.
MigrationStrategy: Abstract interface for migration strategies.
MultiPermissionCheckResult: Result of checking multiple permissions.
NoEncryptionService: A pass-through encryption service that performs no encryption.
NoOpMigrationStrategy: A no-op migration strategy that passes data through unchanged.
NotEqualsQuery: Query to check if a field does not equal a specific value.
NotInQuery: Query to check if a field's value does not exist within a list of values.
NotQuery: Query to negate another query.
OrQuery: Query to combine multiple queries with a logical OR.
PagedStorage<T extends Entity>: High-performance page-based storage implementation.
PagedStorageConfig: Configuration for PagedStorage.
PasswordValidationResult: Result of a password validation check.
Permission: Represents a permission in the system.
PermissionCheckResult: Result of a permission check.
Permissions: A set of common/built-in permissions.
PermissionSet: A collection of permissions that can be checked together.
QueryBuilder: A builder class for constructing complex queries using a fluent interface.
QueryCache<T extends Entity>: A cache for query results with TTL and LRU eviction.
QueryCacheConfig: Configuration for query cache behavior.
QueryOptimizer: Query optimizer that generates execution plans for queries.
QueryPlan: A query execution plan generated by the optimizer.
QueryPlanCache: Cache for query execution plans.
RangeBounds: Range bounds for range queries.
RefreshResult: Result of a token refresh operation.
RegexQuery: Query to match a field's string value against a regular expression.
Role: Represents a role in the authorization system.
RoleManager: Manages roles and permissions for the authorization system.
RoleManagerConfig: Configuration for the RoleManager.
SchemaVersion: Represents schema version metadata stored in the database.
ScoredResult: A search result with relevance score.
SecurityConfig: Configuration for security-related operations.
SecurityService: Service for security operations including password hashing and JWT management.
SerializedFullTextIndex: Serializable full-text index data structure.
SerializedIndex: Serializable index data structure.
SingleEntityMigrationStrategy: A migration strategy that transforms entities individually.
Snapshot: Represents a point-in-time snapshot of storage data.
StartsWithQuery: Query to check if a string field starts with a prefix.
Storage<T extends Entity>: Abstract interface for entity storage backends.
StorageRecord: A record from storage containing entity ID and data.
StorageStatistics: Represents comprehensive storage statistics.
SystemRoles: Predefined system roles.
TermPosting: Represents a term posting with position information.
TokenClaims: Represents the claims extracted from a JWT token.
Transaction<T extends Entity>: A transaction for atomic entity operations.
TransactionManager<T extends Entity>: Manages the lifecycle of transactions for a specific entity type.
TransactionOperation: An individual operation within a transaction.
TypeRegistry: Central registry for type serializers used during entity serialization.
User: Represents a user in the EntiDB authentication system.
UserSession: Represents an active user session.
VersionedData: Represents versioned entity data with metadata for migration tracking.

Enums

Action: Standard actions that can be performed on resources.
AesKeySize: Supported key sizes for AES encryption.
BackupOperation: Types of backup operations.
BackupType: Types of backup operations.
ExecutionStrategy: The execution strategy for a query.
IndexType: The type of index to create.
IsolationLevel: The isolation level for a transaction.
LogLevel: Log level for filtering log output.
MigrationOutcome: The outcome of a migration step.
OperationType: The type of operation to perform on an entity.
PermissionScope: Scope modifiers for permissions.
Resource: Standard resources in the system.
StorageBackend: Storage backend types for EntiDB.
TransactionStatus: The current status of a transaction.
UserStatus: Represents the status of a user account.

Mixins

TransactionalStorage<T extends Entity>: Mixin for storage backends that support transactions.

Extensions

ActionExtension on Action: Extension methods for Action.
PermissionScopeExtension on PermissionScope: Extension methods for PermissionScope.
QueryCachingExtension on IQuery: Extension to provide query caching capabilities to queries.
ResourceExtension on Resource: Extension methods for Resource.
TransactionExtension on Storage<T>: Extension for creating transactions from storage.
UserStatusExtension on UserStatus: Extension methods for UserStatus serialization.

Functions

createDataMigration<T extends Entity>({required Storage<T> storage, required MigrationConfig config}) → DataMigration<T>: Creates a data migration runner with the given storage and configuration.
createUserMigration<T extends Entity>({required Storage<T> storage, required MigrationConfig config}) → UserMigration<T>: Creates a user migration runner with the given storage and configuration.
transactionScope<T extends Entity, R>(Storage<T> storage, FutureOr<R> action(Transaction<T> txn), {IsolationLevel isolationLevel = IsolationLevel.readCommitted}) → Future<R>: A simple transaction scope for automatic commit/rollback.

Typedefs

DataMigration<T extends Entity> = MigrationRunner<T>: Migration runner specialized for application data entities.
EntityFromMap<T extends Entity> = T Function(String id, Map<String, dynamic> data): Factory function type for deserializing entities from stored data.
StorageStats = StorageStatistics: Legacy alias for backward compatibility.
UserMigration<T extends Entity> = MigrationRunner<T>: Migration runner specialized for user/authentication entities.

Exceptions / Errors

AuthenticationException: Base exception for authentication-related errors.
AuthenticationFailedException: Thrown when authentication verification fails during decryption.
AuthorizationException: Base exception for authorization-related errors.
BackupCompressionException: Thrown when backup compression fails.
BackupDecompressionException: Thrown when backup decompression fails.
BackupException: Base exception for backup and restore operations.
BackupIntegrityException: Thrown when backup integrity verification fails.
BackupNotSupportedException: Thrown when a backup operation is not supported.
BackupQuotaExceededException: Thrown when a backup quota or limit is exceeded.
BackupTimeoutException: Thrown when a backup operation times out.
BackupVersionException: Thrown when a backup file has an incompatible version.
CircularInheritanceException: Thrown when circular inheritance is detected in role hierarchy.
CollectionException: Base exception for collection-related errors.
CollectionOperationException: Thrown when a collection operation fails.
CollectionTypeMismatchException: Thrown when a collection type mismatch occurs.
ConcurrencyException: Thrown when concurrent modifications conflict.
DataBackupCreationException: Thrown when data backup creation fails.
DataBackupFileNotFoundException: Thrown when a data backup file cannot be found.
DataBackupRestorationException: Thrown when data backup restoration fails.
DatabaseDisposedException: Thrown when the database has been disposed but is still accessed.
DatabaseException: General database exception for top-level EntiDB operations.
DatabaseNotOpenException: Thrown when the database is not open but an operation requires it.
DatabaseOpenException: Thrown when the database cannot be opened.
DecryptionException: Thrown when data decryption fails.
DocumentAlreadyExistsException: Thrown when attempting to insert a document with an existing ID.
DocumentException: Base exception for document-related errors.
DocumentNotFoundException: Thrown when a document cannot be found by its ID.
EmptyBackupException: Thrown when a backup file is empty or has no entities.
EncryptionException: Base exception for encryption-related errors.
EncryptionFailedException: Thrown when data encryption fails.
EncryptionNotInitializedException: Thrown when the encryption service is not properly initialized.
EntiDBException: Base exception class for all EntiDB exceptions.
EntityAlreadyExistsException: Thrown when attempting to insert an entity with an existing ID.
EntityNotFoundException: Thrown when an entity is not found in storage.
IndexAlreadyExistsException: Thrown when attempting to create an index that already exists.
IndexException: Base exception for index-related errors.
IndexNotFoundException: Thrown when an index is not found on a specified field.
InheritanceDepthExceededException: Thrown when role inheritance depth exceeds the configured limit.
InvalidIvException: Thrown when an invalid IV (Initialization Vector) is provided.
InvalidKeyException: Thrown when an invalid encryption key is provided.
InvalidOrExpiredTokenException: Thrown when a JWT token is invalid or has expired.
InvalidUserOrPasswordException: Thrown when login fails due to invalid credentials.
JWTTokenException: Thrown when JWT token operations fail.
KeyDerivationException: Thrown when key derivation from a password fails.
MigrationException: Base exception for migration-related errors.
NoActiveTransactionException: Thrown when attempting to commit or rollback without an active transaction.
PermissionDeniedException: Thrown when a user lacks the required permission for an operation.
QueryException: Base exception for query-related errors.
RoleAlreadyDefinedException: Thrown when attempting to define a role that already exists.
SchemaValidationException: Thrown when document validation against a schema fails.
ServerException: Base exception for server-related errors.
StorageAlreadyExistsException: Thrown when a storage location already exists.
StorageCorruptedException: Thrown when storage data is corrupted.
StorageException: Base exception for storage-related errors.
StorageInitializationException: Thrown when storage initialization fails.
StorageNotFoundException: Thrown when a storage location (file or directory) is not found.
StorageNotOpenException: Thrown when attempting to access a storage that is not open.
StorageOperationException: Thrown when a storage operation fails.
StorageOutOfSpaceException: Thrown when there is insufficient disk space for a storage operation.
StoragePermissionException: Thrown when there is a permission error accessing storage.
StorageReadException: Thrown when a storage read operation fails.
StorageReadOnlyException: Thrown when attempting to write to a read-only storage.
StorageVersionMismatchException: Thrown when there is a version mismatch in the storage format.
StorageWriteException: Thrown when a storage write operation fails.
SystemRoleProtectionException: Thrown when attempting to modify a protected system role.
TransactionAlreadyActiveException: Thrown when a transaction is already active.
TransactionConflictException: Thrown when a serializable transaction detects a conflict on commit.
TransactionException: Base exception for transaction-related errors.
TypeAlreadyRegisteredException: Exception thrown when attempting to register a type that is already registered.
TypeDeserializationException: Exception thrown when type deserialization fails.
TypeNameConflictException: Exception thrown when a type name conflicts with an existing registration.
TypeNotRegisteredException: Exception thrown when attempting to deserialize an unregistered type.
TypeRegistryException: Base exception for type registry errors.
TypeSerializationException: Exception thrown when type serialization fails.
UndefinedRoleException: Thrown when an operation references an undefined role.
UnsupportedIndexTypeException: Thrown when an unsupported index type is requested.
UserAlreadyExistsException: Thrown when attempting to register a user with an existing username.
UserBackupCreationException: Thrown when user backup creation fails.
UserBackupFileNotFoundException: Thrown when a user backup file cannot be found.
UserBackupRestorationException: Thrown when user backup restoration fails.
UserNotFoundException: Thrown when a user cannot be found by username or ID.

entidb library

Quick Start

Classes

Enums

Mixins

Extensions

Functions

Typedefs

Exceptions / Errors

entidb package

entidb library