Logo 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();
}

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();
}

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);
}

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");

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

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': 'johndoe@example.com',
  });

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>

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': 'john.doe@example.com',
  },
  {
    'firstName': 'Jane',
    'lastName': 'Doe',
    'email': 'jane.doe@example.com',
  },
  {
    'firstName': 'Bob',
    'lastName': 'Smith',
    'email': 'bob.smith@example.com',
  },
];

// Inserta los documentos en la colección
await collection.insertMany(documents);

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)

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}]

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)

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}

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)

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 }

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})

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

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)

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'}]

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

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,
});

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

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');

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

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});

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

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});

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)

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']

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)

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'});

Podemos usar el método groupBy para agrupar los documentos por género de la siguiente manera:

final groups = users.groupBy('gender');

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'},
  ],
}

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)

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}

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)

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');

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']['example@example.com'];
final List<Map<String, dynamic>> usersWithEmail = List<Map<String, dynamic>>.from(userIds.map((id) => users.findById(id)));

En este ejemplo, la variable userIds contiene una lista de identificadores de documentos que tienen el valor "example@example.com" 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})

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}]

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)

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},
// ]

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 = '+'})

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: '+');

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},
]

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)

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.');
}

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)

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

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)

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');

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
  })

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

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})

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);
});

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

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);

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)

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.');
}

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)

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

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)

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);

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)

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);

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)

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
//   }
// ]

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 []
})

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'}
// ]

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

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}]
}

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

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}

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

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"]

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

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"]

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

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}]

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

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);
}

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);
}

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');

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');

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" />

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>

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');

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');

Libraries

harncollection
harncore
harndb
harndb_method_channel
harndb_platform_interface
harnfile
harnlog
harnmetadata
harnmodel
harnobserver
harnpermission
harnqueue
harnutils