Documentation in Portuguese

MycroDB is a JavaScript library designed for managing Document Databases stored in a single JSON file or in memory.

MycroDB is available as an NPM library, and you can find it at https://www.npmjs.com/package/mycro-db.

To showcase how MycroDB works, we've developed a sample project that implements a Command Line Interface (CLI) for task management. For more information about this project, please visit its dedicated repository at Todz.

To integrate MycroDB into your project, you can install it via npm (or other package managers):

npm install mycro-db

To get started, import the 'MycroDatabase' class along with a 'Storage' class, and initialize both objects:

import { JsonStorage, MemoryStorage, MycroDatabase } from 'mycro-db';

// In-memory mode
const inMemoryStorage = new MemoryStorage();
const db = new MycroDatabase(inMemoryStorage);

// JSON file mode
const jsonStorage = new JsonStorage('my_database.json');
const db = new MycroDatabase(jsonStorage);

To maintain organized data, the library employs a collection structure. Utilize collections to logically categorize your data.

To create a collection, you need to provide a name, and optionally, you can include a model (an object with properties and their corresponding data types) to enhance IDE intellisense.

const User = db.collection('users', { name: String(), age: Number() });

To insert a document into a collection, you should supply a plain JavaScript object with values compatible with JSON. You can insert one or more documents in a single operation by passing an array of document objects.

User.insert([
    { name: 'Alice', age: 28 },
    { name: 'Bob', age: 30 }
]);

To update a document, provide an object containing the 'id' key with the document's ID to be updated, and the 'data' key containing an object with 'key: value' pairs to be updated in the document. The update is atomic, meaning that only the values provided in the object will be updated, while other values in the document remain unchanged. You can update one or more documents in a single operation by passing an array of document objects.

User.update([
    { id: 1, data: { age: 45 } }
]);

To retrieve a document from a collection, provide an ID of the document. You can get one or more documents in a single operation by passing an array of IDs.

User.get([
    1, 5
]);

To query documents in a collection, provide a strategy (filter) function. If no filtering function is provided, all documents will be returned. The number of documents returned depends on the 'limit' parameter, and the offset parameter is used for 'pagination'. All parameters are optional. By default, the limit is 25, and the offset is 0.

const strategy = (user) => user.age > 21;
const limit = 10;
const offset = 0;

User.query(strategy, limit, offset);

To remove a document, provide an ID of the document. You can remove one or more documents in a single operation by passing an array of IDs.

User.remove([
    1, 5
]);

The library supports the following storage strategies:

This is the simplest strategy, saving data in memory until the application reloads and all data is erased.

import { MemoryStorage } from 'mycro-db';

const storage = new MemoryStorage();
const db = new MycroDatabase(storage);

This is the most commonly used strategy and is ideal for those requiring flexibility and persistence. You can provide a schema, but it is primarily used as a reference for IDE intellisense.

import { JsonStorage } from 'mycro-db';

const storage = new JsonStorage('my_database.json');
const db = new MycroDatabase(storage);

This strategy offers the same functionality as JSON, but it incorporates a 'Schema' for 'insert' and 'update' functions, ensuring that documents added to the database conform to the expected structure (no extra fields and correct data types). If an extra field or incorrect value is provided, an error is raised.

import { TypedJsonStorage } from 'mycro-db';

const storage = new TypedJsonStorage('my_database.json');
const db = new MycroDatabase(storage);

const user = db.collection('users', { name: String(), age: Number() });
// Here, it is defined that a user has Name and Age fields, respectively a String and a Number.

For a detailed history of changes to this project, please refer to the changes.md file in the root directory.

This project is licensed under the MIT License. See the LICENSE file for details.