harndb

Description:

harndb

HarnDB #
HarnDB es una base de datos de documentos orientada a objetos escrita en Dart. Permite almacenar datos y proporciona una API para realizar operaciones de lectura y escritura en la base de datos.
HarnDB utiliza archivos de disco para almacenar los datos y se ejecuta completamente en la memoria de la aplicación, lo que lo hace adecuado para aplicaciones que requieren un almacenamiento rápido y eficiente. También admite la indexación de campos para acelerar las consultas y proporciona una interfaz para realizar operaciones de agregación en los datos.
En resumen, HarnDB es una base de datos simple, rápida y fácil de usar que es especialmente adecuada para aplicaciones que manejan datos en formato JSON y necesitan un almacenamiento rápido y eficiente.

Comenzar a usar HarnDB #
Para comenzar a utilizar HarnDB, primero debes importar el paquete harndb en tu proyecto y crear una instancia de la clase Harn.
import 'package:harndb/harndb.dart';

void main() async {
final harn = Harn();
}
copied to clipboard
Una vez creada la instancia de Harn, debes llamar al método initialize() para cargar los datos iniciales en la memoria. Este método buscará en el sistema de archivos los archivos que representan las colecciones guardadas y los cargará en memoria.
import 'package:harndb/harndb.dart';

void main() async {
final harn = Harn();
await harn.initialize();
}
copied to clipboard
Después de inicializar Harn, puedes crear una colección y comenzar a agregar documentos a ella.
import 'package:harndb/harndb.dart';

void main() async {
final harn = Harn();
await harn.initialize();

final myCollection = harn.collection('myCollection');

final myDocument = {'name': 'John Doe', 'age': 30};

await myCollection.insert(myDocument);
}
copied to clipboard

Colecciones #
En HarnDB, una colección es similar a una tabla en una base de datos relacional o a una colección en una base de datos NoSQL. Es un contenedor de documentos JSON que están relacionados de alguna manera.
Cada colección en HarnDB tiene un nombre único y contiene documentos JSON que pueden ser insertados, actualizados, eliminados y consultados mediante el uso de la API de HarnDB. Además, una colección en HarnDB puede tener uno o varios índices que permiten una consulta más eficiente de los documentos.
Harn db = Harn();
final myFirstCollection = db.collection("myFirstCollection");
copied to clipboard
Para crear una colección en HarnDB, primero necesitas instanciar un objeto Harn y luego llamar al método collection pasándole como parámetro el nombre de la colección que deseas crear.

Método Insert() #
El método insert permite agregar un nuevo documento a la colección representada por la instancia actual de HarnCollection. El documento a insertar debe ser pasado como un mapa de cadenas de texto como llave y valores dinámicos, donde la llave _id no debe estar presente, ya que se generará automáticamente por el método.
Future<void> insert(Map<String, dynamic> document) async
copied to clipboard
Parámetros #



Parámetro
Descripción




document
Un mapa que contiene los campos del nuevo documento.



Retorna #



Tipo
Descripción




Future
Una promesa que se resuelve una vez que se completa la inserción del documento.



El método devuelve una promesa que se resuelve cuando el documento ha sido insertado en la colección y ha sido almacenado en el sistema de archivos.
Ejemplo de uso #
Harn db = Harn();
final myCollection = db.collection('users');
await collection.insert({
'name': 'John Doe',
'age': 30,
'email': '[email protected]',
});
copied to clipboard
En el ejemplo anterior, se crea una instancia de HarnCollection para representar una colección de usuarios, y se inserta un nuevo documento con los campos name, age, y email. El método insert se encarga de generar un nuevo identificador único para el documento y establecer las marcas de tiempo createdAt y updatedAt.

Método insertMany() #
Este método permite insertar varios documentos a la vez en la colección.
insertMany(List<Map<String, dynamic>> documents) => Future<void>
copied to clipboard
Parámetros #



Parámetro
Descripción




documents
Una lista de mapas que representan los documentos a insertar en la colección.



Retorna #



Tipo
Descripción




Future
Una promesa que se resolverá cuando los documentos hayan sido insertados en la colección.



Ejemplo de uso #
Harn db = Harn();
final collection = db.collection('users');

// Define una lista de documentos a insertar en la colección
final documents = [
{
'firstName': 'John',
'lastName': 'Doe',
'email': '[email protected]',
},
{
'firstName': 'Jane',
'lastName': 'Doe',
'email': '[email protected]',
},
{
'firstName': 'Bob',
'lastName': 'Smith',
'email': '[email protected]',
},
];

// Inserta los documentos en la colección
await collection.insertMany(documents);
copied to clipboard
En este ejemplo, se crea una coleccion con el nombre 'users'. A continuación, se define una lista de documentos que se insertarán en la colección y se llama al método insertMany para insertar los documentos en la colección. Cada documento se agrega a la colección con un nuevo ID generado automáticamente y se establecen las fechas de creación y actualización. El método devuelve una promesa que se resuelve cuando los documentos han sido insertados en la colección.

Método find() #
El método find de la clase HarnCollection se utiliza para buscar documentos en una colección según un criterio de consulta específico.
List<Map<String, dynamic>> find(Map<String, dynamic> query)
copied to clipboard
Parámetros #



Parámetro
Descripción




query
Un mapa de clave-valor que representa la consulta de búsqueda.



Retorna #



Tipo
Descripción




List<Map<String, dynamic>>
Una lista de mapas que representan los documentos de la colección que coinciden con la consulta de búsqueda.



Ejemplo de uso: #
Harn db = Harn();
final collection = db.collection('users');
// Insertar algunos documentos
await collection.insert({'name': 'Alice', 'age': 25});
await collection.insert({'name': 'Bob', 'age': 30});
await collection.insert({'name': 'Charlie', 'age': 35});

// Buscar documentos que coincidan con la consulta
final results1 = collection.find({'name': 'Bob'}); // [{"_id": "...", "name": "Bob", "age": 35}]
final results2 = collection.find({'age': {'\$gt': 30}}); // [{"_id": "...", "name": "Bob", "age": 35}, {"_id": "...", "name": "Charlie", "age": 42}]
copied to clipboard

Método findOne() #
El método findOne se encarga de buscar y devolver un documento de una colección que cumpla con una condición determinada.
Map<String, dynamic>? findOne(bool Function(dynamic) predicate)
copied to clipboard
Parámetros #



Parámetro
Descripción




predicate
Una función de predicado que toma un documento y devuelve un valor booleano que indica si el documento cumple con la condición de búsqueda.



Retorna #



Tipo
Descripción




Map<String, dynamic> or null
Un mapa que representa el primer documento de la colección que cumple con la condición de búsqueda, o null si no se encuentra ningún documento.



Ejemplo de uso #
Harn db = Harn();
// Crear una nueva colección
final collection = db.collection('users');

// Insertar algunos documentos
await collection.insert({'name': 'Alice', 'age': 28});
await collection.insert({'name': 'Bob', 'age': 35});
await collection.insert({'name': 'Charlie', 'age': 42});

// Buscar el primer documento que cumpla con la condición de búsqueda
final result1 = collection.findOne((document) => document['name'] == 'Bob'); // {"_id": "...", "name": "Bob", "age": 35}
final result2 = collection.findOne((document) => document['age'] > 30); // {"_id": "...", "name": "Bob", "age": 35}
copied to clipboard

Método findById() #
El método findById se utiliza para buscar un documento en la colección por su identificador único _id. Este método toma como argumento el valor del _id del documento a buscar y devuelve un mapa que representa el documento. Si el documento no existe en la colección, se devuelve null.
Map<String, dynamic> findById(String id)
copied to clipboard
Parámetros #



Parámetro
Descripción




id (tipo String)
El ID del documento que se desea buscar.



Retorna #



Tipo
Descripción




Map<String, dynamic>
El documento con el ID especificado, si existe en la colección. Si no existe, devuelve null.



Ejemplo de uso #
Harn db = Harn();
final collection = db.collection('users');
await collection.insert({
'name': 'John',
'age': 35,
});
final document = collection.findById('dnb3j77xus776sgb4j37s');
print(document); // { '_id': 'dnb3j77xus776sgb4j37s', 'name': 'John', 'age': 35, 'createdAt': 1649207692814, 'updatedAt': 1649207692814 }

copied to clipboard
En el ejemplo anterior, se crea una nueva instancia de HarnCollection con el nombre 'users' y una colección vacía. Luego, se inserta un nuevo documento en la colección con un _id generado automáticamente. Finalmente, se busca el documento recién insertado por su _id y se imprime en la consola.

Método Count() #
El método count() de la clase HarnCollection devuelve el número total de documentos almacenados en la colección.
int count({Map<String, dynamic>? query})
copied to clipboard
Parámetros #



Parámetro
Descripción




query (opcional)
un Map<String, dynamic> que contiene los campos y valores que se deben buscar en los documentos de la colección. Si no se proporciona un query, se contarán todos los documentos en la colección.



Retorna #



Tipo
Descripción




int
el número de documentos en la colección que coinciden con el query, o el número total de documentos en la colección si no se proporciona un query.



Ejemplo de uso: #
Harn db = Harn();
final users = db.collection('users');
users.insert({"name": "John", "age": 30});
users.insert({"name": "Jane", "age": 25});
users.insert({"name": "Bob", "age": 40});

// Contar el número de documentos en la colección
int documentCount = collection.count();
print(documentCount); // 3

// Contar el número de documentos en la colección que cumplen con un query
int matchingDocumentCount = collection.count(query: {"age": 30});
print(matchingDocumentCount); // 1
copied to clipboard
Este ejemplo muestra cómo se puede utilizar el método count con y sin un query opcional. El primer llamado al método count cuenta todos los documentos en la colección (lo que dará como resultado 3), mientras que el segundo llamado cuenta los documentos que tienen un campo "age" igual a 30 (que será 1).

Método where() #
El método where en la clase HarnCollection devuelve una lista de los documentos en la colección que cumplen con una condición dada. La condición se especifica mediante una función bool Function(dynamic) que toma un documento como entrada y devuelve un valor booleano.
List<Map<String, dynamic>> where(bool Function(dynamic) predicate)
copied to clipboard
Parámetros #



Parámetro
Descripción




predicate
Una función que toma un valor dinámico y devuelve un valor booleano. Esta función se usará para filtrar los documentos en la colección.



Retorna #



Tipo
Descripción




List<Map<String, dynamic>>
Lista de documentos que cumplen la condición dada por la función predicate.



Ejemplo de uso #
Harn db = Harn();
final users = db.collection('users');
// Agregamos algunos usuarios a la colección.
await users.insert({'name': 'Alice', 'age': 30, 'city': 'New York'});
await users.insert({'name': 'Bob', 'age': 25, 'city': 'San Francisco'});
await users.insert({'name': 'Charlie', 'age': 35, 'city': 'Los Angeles'});

// Obtenemos los usuarios que tienen una edad mayor a 25.
final result = users.where((doc) => doc['age'] > 25);

print(result);
// Output: [{'name': 'Alice', 'age': 30, 'city': 'New York'}, {'name': 'Charlie', 'age': 35, 'city': 'Los Angeles'}]
copied to clipboard
En este ejemplo, creamos una colección users y agregamos algunos usuarios a ella. Luego usamos el método where para obtener los usuarios que tienen una edad mayor a 25. La función que se pasa al método where toma un documento como entrada y devuelve true si la edad del usuario es mayor a 25. La lista resultante contiene los objetos de los usuarios que cumplen con esta condición.

Método update() #
El método update de la clase HarnCollection se encarga de actualizar un documento existente en la colección, recibiendo como parámetros el id del documento y un mapa con los campos a actualizar.
Future<void> update(String id, Map<String, dynamic> updates) async
copied to clipboard
Parámetros #



Parámetro
Descripción




id (String)
El identificador único del documento a actualizar.


updates
(Map<String, dynamic>): Un mapa que contiene los campos y valores a actualizar en el documento.



Retorna #



Tipo
Descripción




Future
Una promesa que se resuelve una vez que se ha completado la actualización.



Ejemplo de uso #
Supongamos que tenemos una colección de productos y deseamos actualizar el precio de un producto en particular. Podemos hacerlo de la siguiente manera:
Harn db = Harn();
final collection = db.collection('users');
await collection.insert({
'name': 'John Doe',
'age': 30,
});

// Actualizar el documento con el ID 'jh4y67s62hh26s6534u47s6s'
await collection.update('jh4y67s62hh26s6534u47s6s', {
'name': 'Jane Doe',
'age': 35,
});
copied to clipboard

Método remove() #
El método remove de la clase HarnCollection se encarga de eliminar un documento de la colección a partir de su ID. Este método recibe como parámetro el ID del documento que se desea eliminar y retorna una Future
Future<void> remove(String id) async
copied to clipboard
Parámetros #



Parámetro
Descripción




id
Un valor de tipo String que representa el identificador único del documento a eliminar.



Retorna #



Tipo
Descripción




Future
Una promesa que se resuelve cuando se completa la eliminación del documento.



Ejemplo de uso #
Harn db = Harn();
final collection = db.collection('my_collection');
await collection.insert({'name': 'John', 'age': 30});
await collection.remove('jh4y67s62hh26s6534u47s6s');
copied to clipboard
Este ejemplo la coleccion con el nombre 'myCollection', inserta un documento con el nombre 'John Doe' y la edad '30', y luego elimina el documento con el identificador 'jh4y67s62hh26s6534u47s6s' de la colección.

Método deleteMany() #
El método deleteMany permite eliminar múltiples documentos de la colección en base a una consulta.
Future<void> deleteMany(Map<String, dynamic> query) async
copied to clipboard
Parámetros #



Parámetro
Descripción




query
Un mapa que representa la consulta para filtrar los documentos a eliminar. Los documentos que coincidan con esta consulta se eliminarán de la colección.



Retorna #



Tipo
Descripción




Future
Un futuro que se completa cuando se han eliminado los documentos de la colección.



Ejemplo de uso: #
Harn db = Harn();
final usersCollection = db.collection('users');
// Eliminar todos los documentos que tengan el campo "age" con valor 30
await usersCollection.deleteMany({'age': 30});

copied to clipboard
Este ejemplo eliminará todos los documentos de la colección que tengan el campo "age" con valor 30.

Método updateMany() #
El método updateMany actualiza varios documentos que cumplan con una determinada condición. Este método toma dos argumentos: query, que es un mapa que define la condición que deben cumplir los documentos que se actualizarán, y updates, que es un mapa que contiene los campos que se actualizarán y sus nuevos valores.
Future<void> updateMany(Map<String, dynamic> query, Map<String, dynamic> updates) async
copied to clipboard
Parámetros #



Parámetro
Descripción




query
un Map<String, dynamic> que contiene los campos y valores a buscar en los documentos de la colección que se deben actualizar.


updates
un Map<String, dynamic> que contiene los campos y valores que se deben actualizar en los documentos que cumplan con el query.



Retorna #



Tipo
Descripción




Future
Un futuro que se completa cuando se han actualizado los documentos de la colección.



Ejemplo de uso: #
Harn db = Harn();
final users = db.collection('users');
// Supongamos que tenemos una colección de usuarios con los campos "name", "age" y "city"
// Actualizar la edad de todos los usuarios que viven en "Barcelona" a 30 años
await users.updateMany({'city': 'Barcelona'}, {'age': 30});
copied to clipboard
En este ejemplo, la condición especificada en query es {'age': {'$gte': 18}}, que significa que queremos actualizar todos los documentos donde el campo age sea mayor o igual a 18. En updates, especificamos que queremos actualizar el campo age a 30 para todos los documentos que cumplen con la condición.

Método distinct() #
El método distinct de la clase HarnCollection es utilizado para obtener los valores únicos de un campo específico en los documentos de la colección.
List<dynamic> distinct(String fieldName)
copied to clipboard
Parámetros #



Parámetro
Descripción




fieldName
String - Nombre del campo cuyos valores únicos se deben extraer.



Retorna #



Tipo
Descripción




List
Una lista de valores únicos del campo especificado. Los valores se devuelven en el orden en que se encontraron en la colección.



Ejemplo de uso #
Supongamos que tenemos una colección de libros y cada libro tiene un campo autor. Queremos obtener todos los autores únicos en la colección. Podríamos usar el método distinct de la siguiente manera:
Harn db = Harn();
final collection = db.collection('users');
collection.insert({'title': 'El Aleph', 'author': 'Jorge Luis Borges'});
collection.insert({'title': 'Cien años de soledad', 'author': 'Gabriel García Márquez'});
collection.insert({'title': 'La tregua', 'author': 'Mario Benedetti'});
collection.insert({'title': 'Ficciones', 'author': 'Jorge Luis Borges'});

final uniqueAuthors = collection.distinct('author');
print(uniqueAuthors); // ['Jorge Luis Borges', 'Gabriel García Márquez', 'Mario Benedetti']
copied to clipboard
En este ejemplo, creamos una colección de libros y luego usamos el método distinct para obtener los autores únicos en la colección. La salida será una lista de los autores únicos: ['Jorge Luis Borges', 'Gabriel García Márquez', 'Mario Benedetti'].

método groupBy() #
El método groupBy permite agrupar los documentos de una colección de acuerdo a un campo específico. Este método devuelve un mapa donde las claves son los valores únicos encontrados en el campo seleccionado y los valores son una lista de los documentos que contienen ese valor.
Map<dynamic, List<Map<String, dynamic>>> groupBy(String fieldName)
copied to clipboard
Parámetros #



Parámetro
Descripción




fieldName
String que representa el nombre del campo utilizado para agrupar los documentos.



Retorna #



Tipo
Descripción




Map
El método devuelve un Map que asocia valores únicos del campo fieldName con una lista de documentos que tienen ese valor en el campo.



Ejemplo de uso #
Supongamos que tenemos una colección de usuarios donde cada documento tiene los siguientes campos:
Harn db = Harn();
final users = db.collection('users');
users.insert({'name': 'John', 'age': 25, 'gender': 'Male'});
users.insert({'name': 'Jane', 'age': 30, 'gender': 'Female'});
users.insert({'name': 'Bob', 'age': 35, 'gender': 'Male'});
users.insert({'name': 'Alice', 'age': 40, 'gender': 'Female'});
users.insert({'name': 'David', 'age': 45, 'gender': 'Male'});
copied to clipboard
Podemos usar el método groupBy para agrupar los documentos por género de la siguiente manera:
final groups = users.groupBy('gender');
copied to clipboard
El resultado será un mapa con dos claves ('Male' y 'Female') y los valores serán listas con los documentos correspondientes a cada género:
{
'Male': [
{'name': 'John', 'age': 25, 'gender': 'Male'},
{'name': 'Bob', 'age': 35, 'gender': 'Male'},
{'name': 'David', 'age': 45, 'gender': 'Male'},
],
'Female': [
{'name': 'Jane', 'age': 30, 'gender': 'Female'},
{'name': 'Alice', 'age': 40, 'gender': 'Female'},
],
}

copied to clipboard

Método aggregateCount() #
El método aggregateCount(fieldName) de la clase HarnCollection devuelve un Map<dynamic, int> donde cada clave representa un valor único en el campo especificado por el parámetro fieldName, y su valor representa el número de documentos en la colección que contienen ese valor.
Map<dynamic, int> aggregateCount(String fieldName)
copied to clipboard
Parámetros #



Parámetro
Descripción




fieldName
Cadena que indica el nombre del campo sobre el que se va a realizar la agregación.



Retorna #



Tipo
Descripción




Map<dynamic, int>
Mapa donde las claves son los valores del campo fieldName en la colección y los valores son las veces que aparece cada uno de ellos en la colección.



Ejemplo de uso #
Supongamos que tenemos una colección de documentos que representan personas con información como su nombre, edad, género, etc. Podemos contar cuántas personas hay de cada género en la colección utilizando el método aggregateCount de la siguiente manera:
Harn db = Harn();
final collection = db.collection('people');
await collection.insert({'name': 'Alice', 'age': 25, 'gender': 'female'});
await collection.insert({'name': 'Bob', 'age': 30, 'gender': 'male'});
await collection.insert({'name': 'Charlie', 'age': 20, 'gender': 'male'});
await collection.insert({'name': 'Diana', 'age': 28, 'gender': 'female'});
await collection.insert({'name': 'Eve', 'age': 35, 'gender': 'female'});

final genderCounts = collection.aggregateCount('gender');
print(genderCounts); // {female: 3, male: 2}
copied to clipboard
En este ejemplo, primero creamos una colección vacía llamada 'people' utilizando HarnCollection('people', {}). Luego, insertamos algunos documentos en la colección utilizando el método insert. Después, llamamos al método aggregateCount en la colección para obtener un recuento de género. Finalmente, imprimimos el resultado del recuento de género en la consola, que debería ser un mapa con la cuenta de cada género en la colección.

Método index() #
El método index de la clase HarnCollection crea un índice para un campo específico dentro de la colección. El índice es un mapa que asocia valores únicos del campo con una lista de identificadores de documentos que tienen ese valor.
void index(String fieldName)
copied to clipboard
Parámetros #



Parámetro
Descripción




fieldName
String que indica el nombre del campo por el cual se va a indexar la colección.



Ejemplo de uso: #
Supongamos que tenemos una colección de usuarios y queremos buscar rápidamente los usuarios con un determinado correo electrónico. Podemos crear un índice para el campo "email" de la siguiente manera:
Harn db = Harn();
final users = db.collection('users');

// Insert some documents...

users.index('email');

copied to clipboard
Una vez creado el índice, podemos buscar los documentos que tienen un valor específico en el campo "email" de la siguiente manera:
final List<String> userIds = users.collection['email-index']['[email protected]'];
final List<Map<String, dynamic>> usersWithEmail = List<Map<String, dynamic>>.from(userIds.map((id) => users.findById(id)));

copied to clipboard
En este ejemplo, la variable userIds contiene una lista de identificadores de documentos que tienen el valor "[email protected]" en el campo "email". Luego, creamos una lista de documentos a partir de estos identificadores usando el método findById.
Es importante tener en cuenta que la creación de un índice puede llevar algún tiempo, especialmente si la colección es grande. Por lo tanto, debe utilizarse con cuidado y solo para campos que se buscan con frecuencia.

método orderBy() #
El método orderBy se utiliza para ordenar los documentos de una colección según un campo específico.
List<Map<String, dynamic>> orderBy(String field, {bool descending = false})
copied to clipboard
Parámetros #



Parámetro
Descripción




field
String que especifica el nombre del campo por el cual se ordenarán los documentos de la colección


descending
bool opcional que indica si los documentos deben ordenarse en orden descendente. El valor predeterminado es false, lo que significa que los documentos se ordenarán en orden ascendente.



Retorna #



Tipo
Descripción




List<Map<String, dynamic>>
Lista de documentos ordenados de la colección según el campo especificado. Si se especifica el argumento descending como true, los documentos se ordenarán en orden descendente.



A continuación se muestra un ejemplo de cómo usar el método orderBy:
Harn db = Harn();
final collection = db.collection('users');
collection.insert({'name': 'Alice', 'age': 25});
collection.insert({'name': 'Bob', 'age': 35});
collection.insert({'name': 'Charlie', 'age': 30});

// Ordenar los documentos por edad de forma ascendente
final documentsAsc = collection.orderBy('age');
print(documentsAsc);
// Resultado: [{'name': 'Alice', 'age': 25}, {'name': 'Charlie', 'age': 30}, {'name': 'Bob', 'age': 35}]

// Ordenar los documentos por edad de forma descendente
final documentsDesc = collection.orderBy('age', descending: true);
print(documentsDesc);
// Resultado: [{'name': 'Bob', 'age': 35}, {'name': 'Charlie', 'age': 30}, {'name': 'Alice', 'age': 25}]

copied to clipboard
En este ejemplo, creamos una colección llamada users con tres documentos que representan usuarios con nombre y edad. Luego, utilizamos el método orderBy para ordenar los documentos de la colección según el campo age. En el primer caso, ordenamos los documentos de forma ascendente y en el segundo caso, de forma descendente. El método orderBy devuelve una lista de los documentos ordenados según el campo especificado.

método whereBetween() #
El método whereBetween se encuentra dentro de la clase HarnCollection y es utilizado para filtrar una lista de documentos en base a un rango de valores de un campo específico.
List<Map<String, dynamic>> whereBetween(String field, dynamic start, dynamic end)
copied to clipboard
Parámetros #



Parámetro
Descripción




field
String que representa el nombre del campo en el que se desea buscar valores entre un rango.


start
dynamic que representa el límite inferior del rango de búsqueda.


end
dynamic que representa el límite superior del rango de búsqueda.



Retorna #



Tipo
Descripción




Map<String, dynamic>
documentos de la colección donde el valor del campo especificado en el parámetro field se encuentra dentro del rango especificado por start y end. Si no se encuentran documentos que coincidan con el rango especificado, se devuelve una lista vacía.



El método retorna una lista de documentos que cumplan con la condición de que el valor del campo field esté entre start y end.
Ejemplo de uso #
Harn db = Harn();
final harnCollection = db.collection('users');

await harnCollection.insert({
'name': 'John Doe',
'age': 35,
});

await harnCollection.insert({
'name': 'Jane Smith',
'age': 25,
});

await harnCollection.insert({
'name': 'Bob Johnson',
'age': 45,
});

final List<Map<String, dynamic>> result =
harnCollection.whereBetween('age', 30, 40);

print(result);

// Salida esperada:
// [
// {'name': 'John Doe', 'age': 35, '_id': '0', 'createdAt': 1649243610000, 'updatedAt': 1649243610000},
// ]

copied to clipboard
En el ejemplo anterior, se creó una instancia de la clase HarnCollection y se insertaron tres documentos en ella. Luego, se llamó al método whereBetween para filtrar los documentos que tengan una edad entre 30 y 40 años, lo que resulta en un solo documento que cumple con la condición especificada. Finalmente, se imprimió el resultado en la consola.

Método calculate() #
El método calculate de la clase HarnCollection es utilizado para realizar operaciones aritméticas simples en los valores de un campo específico en los documentos de una colección.
List<Map<String, dynamic>> calculate(String field, num value,{String operator = '+'})
copied to clipboard
Parámetros #



Parámetro
Descripción




field
String que representa el nombre del campo que se va a calcular.


value
num que representa el valor que se va a utilizar en el cálculo.


operator
es un parámetro opcional que es un String que indica el operador que se va a utilizar en el cálculo. Puede ser + o - y su valor por defecto es +.



Retorna #



Tipo
Descripción




List<Map<String, dynamic>>
Lista de documentos, donde cada documento es un Map<String, dynamic> que representa un registro de la colección.



El método devuelve una lista de documentos modificados con los valores de campo actualizados.
Ejemplo de uso #
Supongamos que tenemos una colección llamada ventas que contiene documentos con información sobre las ventas de una tienda. Cada documento tiene un campo monto que indica el monto de la venta. Queremos actualizar el valor del campo monto en cada documento, agregándole una cantidad adicional.
Harn db = Harn();
final ventasCollection = db.collection('ventas');
await ventasCollection.insert({'monto': 100});
await ventasCollection.insert({'monto': 200});
await ventasCollection.insert({'monto': 300});

final nuevosMontos = ventasCollection.calculate('monto', 50, operator: '+');
copied to clipboard
En este ejemplo, se crea una nueva instancia de la colección ventas y se insertan tres documentos con montos de venta de 100, 200 y 300. Luego, se llama al método calculate con los parámetros field como 'monto', value como 50 y operator como +.
El método calculate actualizará el valor del campo monto en cada documento de la colección, sumando 50 al valor actual. Los nuevos valores de campo se almacenarán en una lista llamada nuevosMontos.
En este caso, nuevosMontos será una lista de tres documentos, cada uno con el campo monto actualizado:
[
{'_id': '001', 'monto': 150, 'createdAt': 123456789, 'updatedAt': 123456789},
{'_id': '002', 'monto': 250, 'createdAt': 123456789, 'updatedAt': 123456789},
{'_id': '003', 'monto': 350, 'createdAt': 123456789, 'updatedAt': 123456789},
]
copied to clipboard

método findExtremes #
El método findExtremes de la clase HarnCollection es un método que permite encontrar los valores máximos y mínimos de un campo numérico dentro de los documentos de una colección.
Map<String, num> findExtremes(String field)
copied to clipboard
Parámetros #



Parámetro
Descripción




field
String que representa el nombre del campo que se va a calcular.



Retorna #



Tipo
Descripción




Map
Map con resultados de min y max



El método devuelve un Map que contiene dos pares clave-valor: {"min": num?, "max": num?}. Si no se encuentra ningún documento con un campo numérico con el nombre especificado, se devuelve null.
Ejemplo de uso #
Harn db = Harn();
final collection = db.collection('myCollection');
collection.insert({'name': 'Alice', 'age': 35});
collection.insert({'name': 'Bob', 'age': 30});
collection.insert({'name': 'Charlie', 'age': 40});

final extremes = collection.findExtremes('age');

if (extremes != null) {
print('Mínimo: ${extremes["min"]}');
print('Máximo: ${extremes["max"]}');
} else {
print('No se encontraron documentos con el campo especificado.');
}

copied to clipboard
En este ejemplo, se crea una instancia de la clase HarnCollection y se agregan tres documentos con campos name y age. Luego, se llama al método findExtremes con el parámetro 'age' para encontrar los valores máximos y mínimos del campo age en los documentos de la colección. Si se encuentra algún documento con el campo age, se imprimen los valores máximos y mínimos correspondientes. En caso contrario, se imprime un mensaje de que no se encontraron documentos con el campo especificado.

Método sumField() #
Método sumField de la clase HarnCollection
El método sumField de la clase HarnCollection recorre todos los documentos de la colección y calcula la suma de un campo numérico específico.
num sumField(String field)
copied to clipboard
Parámetros #



Parámetro
Descripción




field
String que representa el nombre del campo que se va a calcular.



Retorna #



Tipo
Descripción




num
Suma de un campo numérico específico.



Ejemplo de uso #
Harn db = Harn();
final harnCollection = db.collection('users');
await harnCollection.insert({'name': 'Alice', 'age': 25});
await harnCollection.insert({'name': 'Bob', 'age': 30});
await harnCollection.insert({'name': 'Charlie', 'age': 35});

final sumOfAges = harnCollection.sumField('age');
print(sumOfAges); // Salida: 90
copied to clipboard
En este ejemplo, se crea una instancia de la clase HarnCollection y se insertan tres documentos con los campos 'name' y 'age'. Luego, se llama al método sumField para obtener la suma de los valores de edad de todos los documentos. La salida del programa es 90, que es la suma de 25, 30 y 35.

metodo averageField() #
El método averageField se utiliza para calcular el promedio de un campo numérico en los documentos de una colección.
El método devuelve un valor double que representa el promedio de los valores del campo numérico en todos los documentos de la colección. Si la colección está vacía o si ningún documento tiene el campo especificado, el método devuelve 0.
num averageField(String field)
copied to clipboard
Parámetros #



Parámetro
Descripción




field
String que representa el nombre del campo que se va a calcular.



Retorna #



Tipo
Descripción




num
Promedio de un campo numérico específico.



Ejemplo de uso #
Supongamos que tenemos una colección de estudiantes, y cada documento tiene un campo nota que representa la nota del estudiante en un examen. Queremos calcular el promedio de las notas de todos los estudiantes. Podemos hacer lo siguiente:
Harn db = Harn();
final harn = db.collection('estudiantes');
await harn.insert({'nombre': 'Juan', 'nota': 8});
await harn.insert({'nombre': 'Ana', 'nota': 9});
await harn.insert({'nombre': 'Pedro', 'nota': 7});

final promedioNotas = harn.averageField('nota');
print('El promedio de las notas es $promedioNotas');
copied to clipboard
Este código imprimirá El promedio de las notas es 8.0 en la consola.

Método findByDate() #
El método findByDate busca documentos dentro de una colección de documentos que tienen una fecha de creación o actualización que coincide con una fecha dada.
List<Map<String, dynamic>> findByDate(
DateTime date, {
bool includeCreatedAt = true,
bool includeUpdatedAt = false,
DateSearchType searchType = DateSearchType.exact
})
copied to clipboard
Parámetros #



Parámetro
Descripción




date (obligatorio)
Objeto DateTime que representa la fecha a buscar.


includeCreatedAt
(opcional): Booleano que indica si se deben buscar documentos según su fecha de creación (valor predeterminado: true).


includeUpdatedAt
(opcional): Booleano que indica si se deben buscar documentos según su fecha de actualización (valor predeterminado: false).


searchType
(opcional): Enumeración que define el tipo de búsqueda que se realizará (exact, after o before). Si se elige exact se buscarán documentos que coincidan exactamente con la fecha dada. Si se elige after se buscarán documentos cuya fecha sea posterior o igual a la fecha dada. Si se elige before se buscarán documentos cuya fecha sea anterior o igual a la fecha dada (valor predeterminado: DateSearchType.exact).



Retorna #



Tipo
Descripción




List<Map<String, dynamic>>
Lista de mapas que representan los documentos que coinciden con la búsqueda.



Ejemplo de uso #
Harn db = Harn();
final collection = db.collection('my_collection');

// Agrega algunos documentos con fechas de creación y actualización
final now = DateTime.now();
final yesterday = now.subtract(Duration(days: 1));
final tomorrow = now.add(Duration(days: 1));
collection.insert({'createdAt': now, 'updatedAt': now, 'name': 'Document 1'});
collection.insert({'createdAt': yesterday, 'updatedAt': yesterday, 'name': 'Document 2'});
collection.insert({'createdAt': tomorrow, 'updatedAt': tomorrow, 'name': 'Document 3'});

// Busca documentos creados exactamente hoy
final todayDocuments = collection.findByDate(now);
print(todayDocuments); // [{createdAt: 2023-04-07 11:26:48.201202, updatedAt: 2023-04-07 11:26:48.201202, name: Document 1}]

// Busca documentos creados o actualizados después de ayer
final afterYesterdayDocuments = collection.findByDate(yesterday, searchType: DateSearchType.after);
print(afterYesterdayDocuments); // [{createdAt: 2023-04-07 11:26:48.201202, updatedAt: 2023-04-07 11:26:48.201202, name: Document 1}, {createdAt: 2023-04-08 11:26:48.201202, updatedAt: 2023-04-08 11:26:48.201202, name: Document 3}]

// Busca documentos creados o actualizados antes de mañana
final beforeTomorrowDocuments = collection.findByDate(tomorrow, includeUpdatedAt: true, searchType: DateSearchType.before);
print(beforeTomorrowDocuments); // [{createdAt: 2023-04-07 11:26:48.201202, updatedAt: 2023-04-07 11:26:48.201202, name: Document 1}, {createdAt: 2023-04-06 11:26:48.201202, updatedAt: 2023-04
copied to clipboard
En este ejemplo, se crean tres documentos en la colección. El tercer documento tiene una propiedad createdAt que se establece en 1648584062000, que tiene el tiempo especificado por findByCreatedAt. El método devuelve este documento como resultado de la búsqueda.

Método orderByDate #
Este método devuelve una lista de documentos de la colección ordenados por fecha. El campo de fecha utilizado para el ordenamiento se puede especificar mediante el parámetro fieldName. Por defecto, se ordena por el campo 'createdAt'.
List<Map<String, dynamic>> orderByDate({String fieldName = 'createdAt', bool descending = false})
copied to clipboard
Parámetros #



Parámetro
Descripción




fieldName
(opcional): un String que especifica el nombre del campo de fecha por el que se desea ordenar. Por defecto es 'createdAt'.


descending
(opcional): un bool que especifica si el ordenamiento debe ser descendente o no. Por defecto es false (orden ascendente).



Retorna #



Tipo
Descripción




List<Map<String, dynamic>>
Una lista de documentos de la colección ordenados por fecha.







Ejemplo de uso #
Harn db = Harn();
final collection = db.collection('my_collection');

collection.insert({
'title': 'Document 1',
'body': 'This is the first document',
'createdAt': DateTime(2022, 1, 1),
'updatedAt': DateTime(2022, 1, 1),
});

collection.insert({
'title': 'Document 2',
'body': 'This is the second document',
'createdAt': DateTime(2022, 1, 3),
'updatedAt': DateTime(2022, 1, 3),
});

collection.insert({
'title': 'Document 3',
'body': 'This is the third document',
'createdAt': DateTime(2022, 1, 2),
'updatedAt': DateTime(2022, 1, 2),
});

// Ordenar los documentos por fecha de creación
final sortedDocuments = collection.orderByDate(fieldName: 'createdAt', descending: true);

// Imprimir los documentos ordenados
sortedDocuments.forEach((document) {
print(document);
});
copied to clipboard
Este ejemplo ordena los documentos de la colección por fecha de creación de forma descendente y luego los imprime en la consola.

Método geoSearch() #
El método geoSearch se puede utilizar para buscar documentos en una colección por su ubicación geográfica. Esta búsqueda se realiza comparando las coordenadas de cada documento con las coordenadas proporcionadas por el usuario y determinando si el documento está dentro de un área específica.
geoSearch(field: String, lat: double, lng: double, radius: double) -> List<Map<String,dynamic>>
copied to clipboard
Parámetros #



Parámetro
Descripción




field
String - El nombre del campo geográfico en los documentos que se utilizará para la búsqueda. Este campo debe contener un objeto con las propiedades lat y lng que representan la latitud y longitud de la ubicación geográfica del documento.


lat
double - La latitud de la ubicación geográfica de referencia a partir de la cual se buscarán los documentos.


lng
double - La longitud de la ubicación geográfica de referencia a partir de la cual se buscarán los documentos.


radius
double - El radio en kilómetros alrededor de la ubicación geográfica de referencia en el cual se buscarán los documentos.



Retorna #



Tipo
Descripción




List<Map<String, dynamic>>
Una lista de los documentos que se encuentran dentro del radio especificado alrededor de la ubicación geográfica de referencia.



Ejemplo de uso #
Harn db = Harn();
final users = db.collection('users');

users.insert({
'name': 'John Doe',
'location': {'lat': 51.5074, 'lng': -0.1278}
});
users.insert({
'name': 'Jane Doe',
'location': {'lat': 40.7128, 'lng': -74.0060}
});

// Buscar documentos dentro de un radio de 1000 km de una ubicación geográfica específica.
final List<Map<String, dynamic>> result = users.geoSearch('location', 37.7749, -122.4194, 1000);
copied to clipboard

método randomDocument() #
El método randomDocument se utiliza para obtener un documento aleatorio de la colección.
Map<String, dynamic>? randomDocument(Map<String, dynamic> query)
copied to clipboard
Parámetros #



Parámetro
Descripción




query
Un Map que representa la consulta de búsqueda.



Retorna #



Tipo
Descripción




Map<String, dynamic>
que representa un documento aleatorio que cumple con la consulta proporcionada. Si no se encontraron documentos que cumplan con la consulta, se devuelve null.



Ejemplo de uso #
Harn db = Harn();
final collection = db.collection('my_collection');

// Insertar algunos documentos en la colección
await collection.insert({'name': 'John', 'age': 30});
await collection.insert({'name': 'Alice', 'age': 25});
await collection.insert({'name': 'Bob', 'age': 35});

// Obtener un documento aleatorio de la colección que cumple con la consulta
final query = {'age': {'\$gt': 18}};
final randomDoc = collection.randomDocument(query);
if (randomDoc != null) {
print('Documento aleatorio seleccionado: $randomDoc');
} else {
print('No se encontraron documentos que cumplan con la consulta.');
}
copied to clipboard
El método randomDocument no recibe ningún argumento y devuelve un mapa con el documento seleccionado aleatoriamente de la colección. El mapa tiene la estructura de los documentos de la colección, que incluye los campos _id, createdAt y updatedAt.

método countWhere() #
El método countWhere devuelve la cantidad de documentos dentro de la colección que cumplen con la función predicate. La función predicate recibe como parámetro cada uno de los documentos de la colección y debe devolver un valor booleano indicando si el documento cumple o no con una determinada condición.
int countWhere(bool Function(dynamic) predicate)
copied to clipboard
Parámetros #



Parámetro
Descripción




predicate
Una función que toma un parámetro y devuelve un valor booleano. Se aplicará a cada documento de la colección y se contará aquellos para los que devuelve true.



Retorna #



Tipo
Descripción




int
El número de documentos que cumplen con la condición especificada por la función predicate.



Ejemplo de uso #
Harn db = Harn();
final users = db.collection('users');
users.insert({'name': 'John Doe', 'age': 25, 'gender': 'male'});
users.insert({'name': 'Jane Doe', 'age': 30, 'gender': 'female'});
users.insert({'name': 'Bob Smith', 'age': 20, 'gender': 'male'});
users.insert({'name': 'Alice Johnson', 'age': 35, 'gender': 'female'});

// Contar el número de usuarios masculinos
final count = users.countWhere((document) => document['gender'] == 'male');
print(count); // Salida: 2
copied to clipboard

Método subscribe() #
El método subscribe de la clase HarnCollection se utiliza para agregar observadores a una instancia de HarnCollection. Los observadores deben ser instancias de la clase HarnObserverCollection y serán notificados cada vez que se cree, actualice o elimine un documento en la colección.
void subscribe(HarnObserverCollection observer)
copied to clipboard
Parámetros #



Parámetro
Descripción




observer
un objeto de tipo HarnObserverCollection, que implementa la interfaz HarnObserverCollection



El método subscribe toma como argumento una instancia de HarnObserverCollection y lo agrega a la lista de observadores de la instancia actual de HarnCollection.
Ejemplo de uso: #
Harn db = Harn();
final collection = db.collection('users');
final observer = MyObserver(); // Clase que implementa la interfaz HarnObserverCollection
collection.subscribe(observer);
copied to clipboard

Método unsubscribe() #
El método unsubscribe permite eliminar un objeto HarnObserverCollection de la lista de observadores asociados a una colección.
void unsubscribe(HarnObserverCollection observer)
copied to clipboard
Parámetros #



Parámetro
Descripción




observer
HarnObserverCollection - el objeto observador que se desea eliminar de la lista de observadores.



Ejemplo de uso #
Harn db = Harn();

// Crear un objeto de colección
final collection = db.collection('employees');

// Crear un objeto observador
final observer = MyObserver();

// Suscribir el observador a la colección
collection.subscribe(observer);

// ...

// Eliminar el observador de la colección
collection.unsubscribe(observer);

copied to clipboard
En el ejemplo anterior, se crea una instancia de HarnCollection llamada collection y una instancia de HarnObserverCollection llamada observer. Se suscribe el objeto observer a la colección mediante el método subscribe y se realiza algún cambio en la colección. Luego, se elimina el objeto observer de la lista de observadores mediante el método unsubscribe. A partir de este momento, el objeto observer no recibirá notificaciones sobre los cambios realizados en la colección.

Método fullTextSearch() #
El método fullTextSearch de la clase HarnCollection se utiliza para realizar una búsqueda de texto completo en todos los documentos de la colección. El método devuelve una lista de documentos que contienen la cadena de texto especificada.
List<Map<String, dynamic>> fullTextSearch(String query)
copied to clipboard
Parámetros #



Parámetro
Descripción




query
String que representa la consulta de búsqueda a realizar.



Retorna #



Tipo
Descripción




List<Map<String, dynamic>>
Lista de documentos que contienen el texto buscado en al menos uno de sus campos.



El método devuelve una lista de documentos que contienen la cadena de texto especificada.
Ejemplo de uso #
Harn db = Harn();
final myCollection = db.collection('my_collection');

await myCollection.insert({
'title': 'The quick brown fox',
'body': 'Jumped over the lazy dog'
});

await myCollection.insert({
'title': 'The lazy dog',
'body': 'Just laid there'
});

final searchResults = myCollection.fullTextSearch('lazy dog');

// La variable searchResults contendrá una lista con los siguientes elementos:
// [
// {
// '_id': '1',
// 'title': 'The quick brown fox',
// 'body': 'Jumped over the lazy dog',
// 'createdAt': 1649257268503,
// 'updatedAt': 1649257268503
// },
// {
// '_id': '2',
// 'title': 'The lazy dog',
// 'body': 'Just laid there',
// 'createdAt': 1649257287319,
// 'updatedAt': 1649257287319
// }
// ]
copied to clipboard

Método join() #
El método join se utiliza para unir los documentos de dos colecciones diferentes en función de un campo común. La función toma dos argumentos obligatorios: el nombre de la colección que se va a unir y el nombre del campo que se utilizará para unir los documentos.
List<Map<String, dynamic>> join(
HarnCollection collectionB,
String joinField, {
List<String> propertiesA = const [],
List<String> propertiesB = const []
})
copied to clipboard
Parámetros #



Parámetro
Descripción




collectionB
una instancia de la clase HarnCollection que representa la colección con la que se quiere hacer el join.


joinField
un String que representa el campo por el que se quiere hacer el join.


propertiesA
una lista opcional de String que representa las propiedades de los documentos de la colección actual que se quieren incluir en el resultado del join. Por defecto es una lista vacía, lo que significa que se incluirán todas las propiedades de los documentos de la colección actual.


propertiesB
una lista opcional de String que representa las propiedades de los documentos de la colección collectionB que se quieren incluir en el resultado del join. Por defecto es una lista vacía, lo que significa que se incluirán todas las propiedades de los documentos de la colección collectionB.



Retorna #



Tipo
Descripción




List<Map<String, dynamic>>
Lista de mapas que representa el resultado del join. Cada elemento de la lista es un documento que contiene las propiedades especificadas en propertiesA y propertiesB.



Ejemplo de uso #
Harn db = Harn();
final ordersCollection = db.collection('orders');
final customersCollection = db.collection('customers');

final Map<String, dynamic> order1 = {
'id': 1,
'customerId': 1,
'total': 100
};
final Map<String, dynamic> order2 = {
'id': 2,
'customerId': 2,
'total': 200
};
ordersCollection.insert(order1);
ordersCollection.insert(order2);

final Map<String, dynamic> customer1 = {
'id': 1,
'name': 'John Doe'
};
final Map<String, dynamic> customer2 = {
'id': 2,
'name': 'Jane Smith'
};
customersCollection.insert(customer1);
customersCollection.insert(customer2);

final List<Map<String, dynamic>> joinedResult = ordersCollection.join(
customersCollection,
'customerId',
propertiesA: ['id', 'total'],
propertiesB: ['name']
);

print(joinedResult);
// Output:
// [
// {'id': 1, 'total': 100, 'name': 'John Doe'},
// {'id': 2, 'total': 200, 'name': 'Jane Smith'}
// ]
copied to clipboard
En este ejemplo, el método join se utiliza para obtener una lista de órdenes junto con el nombre del cliente al que pertenecen. La colección ordersCollection tiene dos documentos, cada uno con un campo customerId que indica el cliente al que pertenece la orden. La colección customersCollection tiene dos documentos, cada uno con un campo id que indica el identificador del cliente y un campo name que indica el nombre del cliente. Al llamar al método join en ordersCollection y pasar customersCollection como argumento, el método realiza un join por el campo customerId y devuelve una lista de documentos que contienen las propiedades id y total de los documentos de `orders

método aggregate() #
Este método permite aplicar una serie de etapas (stages) a una colección de objetos y retornar el resultado de la transformación.
Future<dynamic> aggregate(List<Function(List<Map<String, dynamic>>)> stages) async
copied to clipboard
Parámetros #



Parámetro
Descripción




stages
una lista de funciones que reciben como parámetro una lista de Map<String, dynamic> y que retornan void.



Retorna #



Tipo
Descripción




Future
El método retorna un objeto Future



modo de uso #
Harn db = Harn();
final collection = db.collection('users');
collection.insert({"name": "John", "age": 35});
collection.insert({"name": "Mary", "age": 42});
collection.insert({"name": "Bob", "age": 27});

// Definir una lista de etapas para aplicar a la colección
List<Function(List<Map<String, dynamic>>)> stages = [
(List<Map<String, dynamic>> list) {
// Filtrar la colección para encontrar los objetos con edad mayor a 30
list.retainWhere((obj) => obj["age"] > 30);
}
];

// Aplicar las etapas a la colección y obtener el resultado
List<Map<String, dynamic>> result = await collection.aggregate(stages);
print(result); // [{"name": "John", "age": 30}, {"name": "Bob", "age": 40}]
}
copied to clipboard
En este ejemplo, se define una única etapa que filtra la colección para encontrar solo los objetos con edad mayor a 30. El resultado final es una lista de objetos que cumplen con esta condición.

Operadores de consulta #



Operador
Descripción




$and
Se utiliza para realizar una operación lógica AND en una lista de consultas. Se espera que el valor del operador sea una lista de mapas, donde cada mapa es una consulta que se ejecutará en orden. Si todas las consultas de la lista devuelven true, entonces la consulta completa también devuelve true.


$or
Se utiliza para realizar una operación lógica OR en una lista de consultas. Se espera que el valor del operador sea una lista de mapas, donde cada mapa es una consulta que se ejecutará en orden. Si al menos una de las consultas de la lista devuelve true, entonces la consulta completa también devuelve true.


$nor
Se utiliza para realizar una operación lógica NOR en una lista de consultas. Se espera que el valor del operador sea una lista de mapas, donde cada mapa es una consulta que se ejecutará en orden. Si ninguna de las consultas de la lista devuelve true, entonces la consulta completa también devuelve true.


$eq
Se utiliza para comparar si el valor de un campo es igual al valor proporcionado. Si no son iguales, la consulta devuelve false.


$ne
Se utiliza para comparar si el valor de un campo es diferente al valor proporcionado. Si son iguales, la consulta devuelve false.


$gt
Se utiliza para comparar si el valor de un campo es mayor que el valor proporcionado. Si es menor o igual, la consulta devuelve false.


$gte
Se utiliza para comparar si el valor de un campo es mayor o igual que el valor proporcionado. Si es menor, la consulta devuelve false.


$lt
Se utiliza para comparar si el valor de un campo es menor que el valor proporcionado. Si es mayor o igual, la consulta devuelve false.


$lte
Se utiliza para comparar si el valor de un campo es menor o igual que el valor proporcionado. Si es mayor, la consulta devuelve false.



*pd: Si se proporciona un operador desconocido o inválido en la consulta, se lanzará una excepción de argumento.

Otros métodos de HarnDB
Método collectionStats #
El método collectionStats permite obtener estadísticas sobre una colección de documentos almacenados en el sistema de almacenamiento de datos Harn.
La firma del método es la siguiente:
Future<Map<String, dynamic>> collectionStats(String collectionName) async
copied to clipboard
Parámetros #



Parametro
Descripción




collectionName
El nombre de la colección sobre la que se desea obtener estadísticas. Debe ser una cadena de caracteres.



Valor de retorno #
El método retorna una instancia de Future que resuelve en un Map<String, dynamic> con dos claves:



Parametro
Descripción




documentCount
La cantidad de documentos almacenados en la colección.


fileSize
El tamaño en bytes del archivo que almacena la colección en disco.



Si la colección no existe, se retorna un Map<String, dynamic> con documentCount y fileSize iguales a cero.
Ejemplo de uso #
final db = Harn();
final collection = db.collection('myCollection');

// Insertar documentos en la colección
await collection.insert({'name': 'John Doe', 'age': 30});
await collection.insert({'name': 'Jane Smith', 'age': 25});
await collection.insert({'name': 'Bob Johnson', 'age': 45});

// Obtener estadísticas de la colección
final stats = await sb.collectionStats('myCollection');
print(stats);
// Output: {documentCount: 3, fileSize: 2048}
copied to clipboard
En este ejemplo se crea una nueva instancia de Harn y se obtiene una referencia a una colección llamada myCollection. Se insertan tres documentos en la colección y se agrega un índice para el campo name. Luego se obtienen las estadísticas de la colección usando el método collectionStats y se imprime el resultado en consola.

Método listCollectionNames() #
El método listCollectionNames devuelve una lista de nombres de las colecciones en la instancia de Harn.
List<String> listCollectionNames();
copied to clipboard
Ejemplo de uso #
final db = Harn();

await db.collection("users").insert({"name": "John", "age": 35});
await db.collection("products").insert({"name": "book", "price": 15});

final collectionNames = db.listCollectionNames();
print(collectionNames); // ["users", "products"]
copied to clipboard
En este ejemplo, se crea una instancia de Harn y se insertan documentos en las colecciones "users" y "products". Luego, se llama al método listCollectionNames para obtener una lista de los nombres de las colecciones. Finalmente, se imprime la lista en la consola.

Método deleteCollection #
El método deleteCollection de la clase Harn se encarga de eliminar una colección del objeto Harn y de eliminar el archivo correspondiente al almacenamiento de la colección en disco. El método toma como parámetro el nombre de la colección a eliminar.
void deleteCollection(String collectionName) async
copied to clipboard
El método primero elimina la colección del objeto _collections de Harn, utilizando el método remove, que toma como parámetro el nombre de la colección a eliminar. Luego, utiliza el objeto _harnFile, que es una instancia de la clase HarnFile, para eliminar el archivo correspondiente a la colección en disco, utilizando el método delete, que también toma como parámetro el nombre de la colección a eliminar. La eliminación del archivo en disco se realiza de forma asíncrona utilizando await.
Aquí hay un ejemplo de cómo se puede utilizar el método deleteCollection para eliminar una colección llamada "users":
final db = Harn();
await db.initialize();

// Eliminar la colección "users"
await db.deleteCollection("users");

// Verificar que la colección fue eliminada
final collectionNames = db.listCollectionNames();
print(collectionNames); // ["posts", "comments"]
copied to clipboard
En este ejemplo, primero se inicializa Harn y se espera a que todas las colecciones sean cargadas utilizando el método initialize. Luego, se llama al método deleteCollection para eliminar la colección "users". Finalmente, se verifica que la colección fue eliminada imprimiendo la lista de nombres de las colecciones restantes en el objeto Harn utilizando el método listCollectionNames. En este caso, la lista resultante sería ["posts", "comments"], ya que "users" fue eliminada.

Método copyCollection #
El método copyCollection permite copiar una colección de una base de datos Harn a otra con un nombre diferente. Toma como entrada el nombre de la colección fuente y el nombre de la colección de destino. Devuelve una instancia de HarnCollection que representa la colección de destino.
Future<HarnCollection> copyCollection(String sourceCollectionName, String targetCollectionName) async
copied to clipboard
Parámetros #



Parametro
Descripción




sourceCollectionName
El nombre de la colección fuente que se copiará.


targetCollectionName
El nombre de la colección de destino donde se copiará la colección fuente.



Ejemplo de uso #
final db = Harn();
final sourceCollection = db.collection("source_collection");
await sourceCollection.insert({"name": "John Doe", "age": 30});

final targetCollection = await db.copyCollection("source_collection", "target_collection");
final documents = targetCollection.find({});
print(documents); // prints: [{"name": "John Doe", "age": 30}]
copied to clipboard

clase HarnModel #
Es una clase abstracta que define el comportamiento de un modelo de datos en HarnDB. Un modelo de datos es una clase que representa una entidad de la aplicación (por ejemplo, un usuario, un producto, una tarea, etc.) y que se utiliza para almacenar y recuperar datos de HarnDB.
Propiedades #



Parámetro
Descripción




metadata
Objeto de tipo Metadata que contiene información adicional sobre el modelo, como el id, createdAt y updatedAt.



Métodos #



Método
Descripción




toMap()
debe ser implementado por las subclases para convertir la instancia de un modelo a un mapa de datos.


static fromMap(Map<String, dynamic> map)
método estático que debe ser implementado por las subclases para crear una instancia de un modelo a partir de un mapa de datos.



Ejemplo de uso #
class User extends HarnModel {
String name;
int age;

User({required this.name, required this.age, Metadata? metadata})
: super(metadata: metadata);

@override
Map<String, dynamic> toMap() {
var map = super.toMap();
map['name'] = name;
map['age'] = age;
return map;
}

static User fromMap(Map<String, dynamic> map) {
return User(
name: map['name'], age: map['age'], metadata: Metadata.fromMap(map));
}
}

var user = User(name: 'John', age: 25);
print(user.metadata.id); // Imprime un nuevo id único generado por generateId()
print(user.metadata.createdAt); // Imprime un objeto DateTime actualizado generado por generateTimeStamp()
print(user.metadata.updatedAt); // Imprime un objeto DateTime actualizado generado por generateTimeStamp()

var userMap = user.toMap(); // Convierte el objeto User en un mapa de cadena y dinámico
var userFromMap = User.fromMap(userMap); // Convierte el mapa de cadena y dinámico en un objeto User
copied to clipboard

HarnModelCollection #
Es una clase abstracta que define el comportamiento de una colección de modelos de datos en HarnDB. Una colección es una agrupación de instancias de un modelo de datos. Esta clase utiliza la clase HarnCollection de HarnDB para realizar las operaciones de inserción, actualización, eliminación y consulta.
Propiedades #



Método
Descripción




_harnCollection
objeto HarnCollection utilizado para realizar las operaciones en la base de datos.



Métodos #



Método
Descripción




fromMap(Map<String, dynamic> map)
debe ser implementado por las subclases para convertir un mapa de datos a una instancia de un modelo de datos.


insert(T dataModel)
inserta un modelo de datos en la colección.


findById(String id)
busca y devuelve un modelo de datos por su ID.


count({Map<String, dynamic>? query})
cuenta el número de documentos en la colección que cumplen con una consulta opcional.


where(bool Function(dynamic) predicate)
devuelve una lista de modelos de datos que cumplen con un predicado.


find(Map<String, dynamic> query)
devuelve una lista de modelos de datos que cumplen con una consulta.


findOne(bool Function(dynamic) predicate)
devuelve el primer modelo de datos que cumple con un predicado.


update(String id, T updates)
actualiza un modelo de datos por su ID.


remove(String id)
elimina un modelo de datos por su ID.


insertMany(List
inserta varios modelos de datos en la colección.


deleteMany(Map<String, dynamic> query)
elimina varios modelos de datos que cumplen con una consulta.


updateMany(Map<String, dynamic> query, T updates)
actualiza varios modelos de datos que cumplen con una consulta.


distinct(String fieldName)
devuelve una lista de valores únicos de un campo de la colección.


deleteAll()
elimina todos los documentos de la colección.


groupBy(String fieldName)
agrupa los documentos de la colección por un campo y devuelve un mapa de valores únicos a una lista de modelos de datos que comparten el mismo valor para ese campo.


aggregateCount(String fieldName)
devuelve un mapa de valores únicos a la cantidad de documentos que tienen ese valor para un campo.


index(String fieldName)
crea un índice en un campo para mejorar el rendimiento de las consultas.


orderBy(String field, {bool descending = false})
devuelve una lista de modelos de datos ordenados por un campo.


whereBetween(String field, dynamic start, dynamic end)
devuelve una lista de modelos de datos que tienen un valor en un campo entre dos valores dados.


calculate(String field, num value, {String operator = '+'})
Este método recibe un campo field, un valor value y un operador operator (por defecto es +). Realiza una operación aritmética (+, -, * o /) entre el valor de field y value, dependiendo del operador indicado. Devuelve una lista de documentos de tipo T que cumplen con la operación realizada.


findByDate(DateTime date, {bool includeCreatedAt = true, bool includeUpdatedAt = false, DateSearchType searchType = DateSearchType.exact})
Este método recibe una fecha date, un booleano includeCreatedAt (por defecto es true), un booleano includeUpdatedAt (por defecto es false) y un DateSearchType searchType (por defecto es DateSearchType.exact). Devuelve una lista de documentos de tipo T que coinciden con la fecha indicada en el campo createdAt o updatedAt, dependiendo de los parámetros indicados.


orderByDate({String field = 'createdAt', bool descending = false})
Este método recibe un campo field (por defecto es createdAt) y un booleano descending (por defecto es false). Ordena los documentos de tipo T según la fecha indicada en el campo field en orden ascendente o descendente, dependiendo del valor del booleano descending.


geoSearch(String field, double lat, double lng, double radius)
Este método recibe un campo field, una latitud lat, una longitud lng y un radio radius. Devuelve una lista de documentos de tipo T que se encuentran dentro del radio especificado alrededor de las coordenadas indicadas.


randomDocument(Map<String, dynamic> query)
Este método recibe una consulta query en forma de mapa. Devuelve un documento aleatorio de tipo T que cumpla con los criterios de la consulta.


countWhere(bool Function(dynamic) predicate)
Este método recibe una función predicate que toma un valor dinámico como parámetro y devuelve un booleano. Cuenta el número de documentos de tipo T que cumplen con la función predicate.


subscribe(HarnObserverCollection observer)
Este método recibe un observador observer de tipo HarnObserverCollection. Suscribe al observador para que reciba notificaciones de cambios en la colección.


unsubscribe(HarnObserverCollection observer)
Este método recibe un observador observer de tipo HarnObserverCollection. Cancela la suscripción del observador para que deje de recibir notificaciones de cambios en la colección.


fullTextSearch(String query)
Este método recibe una consulta query en forma de texto. Devuelve una lista de documentos de tipo T que coinciden con la consulta.


join(HarnCollection collectionB, String joinField, {List
Este método se utiliza para unir dos colecciones de HarnCollection. Toma como argumento una instancia de la colección HarnCollection (collectionB) y el nombre del campo que se utilizará para unir las dos colecciones (joinField). También se puede especificar una lista de propiedades (propertiesA y propertiesB) que se deben incluir en el resultado final de la unión.


Future
Este método se utiliza para realizar una serie de operaciones en los documentos de la colección. Toma como argumento una lista de funciones (stages) que representan cada una de las operaciones que se deben realizar en los documentos de la colección.


Map<String, num> findExtremes(String field)
Este método se utiliza para encontrar los valores máximos y mínimos de un campo en los documentos de la colección. Toma como argumento el nombre del campo (field) para el que se desean encontrar los valores extremos.


num sumField(String field)
Este método se utiliza para sumar los valores de un campo en los documentos de la colección. Toma como argumento el nombre del campo (field) para el que se desean sumar los valores.


num averageField(String field)
Este método se utiliza para calcular el promedio de los valores de un campo en los documentos de la colección. Toma como argumento el nombre del campo (field) para el que se desea calcular el promedio.



Mode de uso #
A continuación, se muestra un ejemplo de uso de la clase HarnModel y la clase HarnModelCollection:
class Person extends HarnModel {
final String name;
final int age;

Person(this.name, this.age);

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

static Person fromMap(Map<String, dynamic> map) {
return Person(map['name'], map['age']);
}
}

class PersonCollection extends HarnModelCollection<Person> {
PersonCollection(HarnCollection harnCollection) : super(harnCollection);

@override
Person fromMap(Map<String, dynamic> map) {
return Person.fromMap(map);
}
}

void main() async {
final db = Harn();
final personCollection = PersonCollection(db.collection('people'));

final alice = Person('Alice', 30);
await personCollection.insert(alice);

final bob = Person('Bob', 25);
await personCollection.insert(bob);

final people = personCollection.find({});
for (final person in people) {
print(person.name);
}

final aliceFromDB = personCollection.findById(alice.id);
print(aliceFromDB.name);
}
copied to clipboard
En este ejemplo, se crea una clase Person que extiende de HarnModel. La clase PersonCollection extiende de HarnModelCollection y especifica el tipo Person.
En la función main, se crea una instancia de PersonCollection y se insertan dos objetos Person en la base de datos. Luego, se recuperan todos los documentos de la colección y se imprime el nombre de cada persona. Finalmente, se recupera el documento de la persona "Alice" por su ID y se imprime su nombre.
Este es solo un ejemplo básico de cómo se pueden utilizar las clases HarnModel y HarnModelCollection. Con estas clases, se pueden realizar operaciones más avanzadas en la base de datos, como filtrar documentos y actualizarlos.

Clase HarnObserverCollection #
Esta es una clase abstracta que define tres métodos que serán implementados por las clases que la hereden. Estos métodos son llamados cuando ocurren cambios en una colección de documentos.
Métodos #



Método
Descripción




onDocumentCreated(String collectionName, String documentId)
Este método es llamado cuando se crea un nuevo documento en la colección collectionName con el identificador documentId.


onDocumentUpdated(String collectionName, String documentId)
Este método es llamado cuando se actualiza un documento existente en la colección collectionName con el identificador documentId.


onDocumentDeleted(String collectionName, String documentId)
Este método es llamado cuando se elimina un documento de la colección collectionName con el identificador documentId.



Estos métodos deben ser implementados por las clases que hereden de HarnObserverCollection. Cada método debe realizar la acción específica que corresponda a su nombre, como actualizar una interfaz de usuario, registrar una actividad en un archivo de registro, o cualquier otra acción necesaria en respuesta a los cambios en la colección de documentos.
Cabe destacar que HarnObserverCollection es una clase abstracta, lo que significa que no se pueden crear instancias de esta clase directamente. En su lugar, se deben crear subclases que implementen los métodos abstractos.
Ejemplo de uso #
class MyObserver implements HarnObserverCollection {
@override
void onDocumentCreated(String collectionName, String documentId) {
print('New document created in collection $collectionName with ID $documentId');
}

@override
void onDocumentUpdated(String collectionName, String documentId) {
print('Document with ID $documentId updated in collection $collectionName');
}

@override
void onDocumentDeleted(String collectionName, String documentId) {
print('Document with ID $documentId deleted from collection $collectionName');
}
}

void main() {
final db = Harn();
final myCollection = db.collection("myCollection");
var observer = MyObserver();
myCollection.suscribe(observer);
}
copied to clipboard
En este ejemplo, se crea una clase MyObserver que implementa la interfaz HarnObserverCollection. Luego se instancia un objeto de esta clase y se utilizan los métodos de la interfaz para simular eventos de documentos que ocurren en una colección.
Al ejecutar este código, se imprimirán mensajes que indican cuándo se ha creado, actualizado o eliminado un documento de la colección. Por supuesto, en una aplicación real, en lugar de imprimir mensajes, podrías realizar otras acciones relevantes en función de los eventos que se produzcan.

Método importCollection #
El método importCollection se utiliza para importar una colección de documentos desde un archivo en el sistema de archivos a una instancia de Harn.
Parámetros #



Parámetro
Descripción




filePath
(requerido) La ruta del archivo que contiene los datos de la colección JSON que se importará.



Ejemplo de uso #
final db = Harn();
await db.importCollection('/path/to/my/collection.harnCollection');
copied to clipboard

Método exportCollection #
El método exportCollection se utiliza para exportar una colección de documentos JSON de una instancia de Harn a un archivo en el sistema de archivos.
Parámetros #



Parámetro
Descripción




collectionName
(requerido) El nombre de la colección que se exportará.


filePath
(requerido) La ruta del archivo de salida donde se escribirá la colección JSON exportada.



Ejemplo de uso #
final db = Harn();
await db.exportCollection('myCollection', '/path/to/my/exported/collection.harnCollection');
copied to clipboard

Exportacion e inmpotarcion de datos Harn #
Harn proporciona métodos para importar y exportar colecciones y bases de datos, lo que permite a los desarrolladores guardar y restaurar datos en diferentes momentos o en diferentes aplicaciones. Estos métodos son importantes para la portabilidad y la migración de datos, y en este caso, Harn proporciona una manera fácil y eficiente de realizar estas operaciones.
Para que la exportación e importación de datos en una aplicación Harn funcione en Android, se deben solicitar los permisos de almacenamiento externo. Esto se puede lograr agregando la siguiente línea al archivo AndroidManifest.xml de la aplicación:
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
copied to clipboard
En iOS, los permisos para acceder al sistema de archivos son manejados por el sistema operativo y se solicitan automáticamente cuando la aplicación intenta acceder a ellos. Sin embargo, es importante asegurarse de que el Info.plist de la aplicación tenga la siguiente entrada:
<key>NSFileProviderDomainUsageDescription</key>
<string>Describe por qué tu aplicación necesita acceso de lectura/escritura al almacenamiento del usuario.</string>
copied to clipboard

Método importDatabase #
El método importDatabase se utiliza para importar una base de datos completa, incluidas todas sus colecciones y documentos, desde un archivo en el sistema de archivos a una instancia de Harn.
Parámetros #



Parámetro
Descripción




filePath
(requerido) La ruta del archivo que contiene los datos de la base de datos JSON que se importará.



Ejemplo de uso #
final db = Harn();
await db.importDatabase('/path/to/my/database.harndb');
copied to clipboard

Método exportDatabase #
El método exportDatabase se utiliza para exportar una base de datos completa, incluidas todas sus colecciones y documentos, desde una instancia de Harn a un archivo en el sistema de archivos.
Parámetros #



Parámetro
Descripción




namedb
(requerido) El nombre que se le dará al archivo de salida. Si se omite este parámetro, se utilizará el nombre predeterminado "export".


filePath
(requerido) La ruta del archivo de salida donde se escribirá la base de datos JSON exportada.



Ejemplo de uso #
final db = Harn();
await db.exportDatabase('/path/to/my/exported/database.harndb');
copied to clipboard