SQLite Docstore

A lightweight, MongoDB-like JSON document storage system powered by SQLite, designed for developers who need efficient document-based storage without the overhead of a dedicated NoSQL database like MongoDB. This library combines the simplicity of SQLite with robust JSON querying capabilities to provide a modern, performant, and flexible document store solution.

Features

• Document Storage: Store and retrieve JSON documents in collections (SQLite tables).
• Rich Query Capabilities: Support for equality checks, $in, $regex, and logical operators.
• MongoDB-Like API: Familiar CRUD functions – insertOne, find, updateOne, and more!
• Advanced Queries: Count, distinct values, and $match/$group aggregations for advanced use cases.
• In-Memory and File-Based DBs: Choice between ephemeral or persistent SQLite databases.
• Lightweight: Leverages the SQLite engine; no separate server or complex setup needed.
• Extensible: Access raw SQLite functions for full flexibility.

---

Why Choose SQLite Docstore?

Sometimes, running a full-fledged MongoDB server is unnecessary, especially for smaller projects, edge deployments, or environments constrained by resources. SQLite Docstore gives you the simplicity of SQLite while letting you work with JSON documents in a MongoDB-like way.

With SQLite Docstore, you:

• Can get started right away without provisioning any external services.
• Have access to persistent, robust, and performant data storage through SQLite.
• Can take advantage of SQLite's native JSON functions to query and manipulate records.

---

Installation

To install via npm:

npm install sqlite-docstore

To install via yarn:

yarn add sqlite-docstore

The library requires Node.js v22 or higher.

---

Getting Started

Here's a quick example to help you get started:

import { sqliteDocstore } from "sqlite-docstore";

const db = sqliteDocstore.init(); // In-memory DB
const collectionName = "users";

// Create a collection
db.createCollection(collectionName);

// Insert a document
const result = db.insertOne(collectionName, { name: "Alice", age: 30 });
console.log("Inserted Document ID:", result.insertedId);

// Query documents
const users = db.find(collectionName, { name: "Alice" });
console.log("Found Users:", users);

// Count documents in a collection
const count = db.countDocuments(collectionName);
console.log("Total Users:", count);

// Drop the collection
db.dropCollection(collectionName);

---

Core API

Initialization

sqliteDocstore.init(fileName?: string | null): SqliteDocstoreFunctions

• fileName: Path to the SQLite file for persistent data. When null, creates an in-memory database (all data is lost when the process exits).

Returns: An object containing MongoDB-like methods to interact with your database.

---

CRUD Operations

createCollection(collectionName: string)

Creates a new collection. Each collection corresponds to an SQLite table.

insertOne(collectionName: string, document: object)

Inserts a single document into a specified collection.

Returns:

{ acknowledged: boolean, insertedId: string }

---

insertMany(collectionName: string, documents: object[])

Inserts multiple documents in a single transaction.

Returns:

{ acknowledged: boolean, insertedCount: number }

---

find(collectionName: string, query?: object)

Finds all documents matching a query. If no query is provided, all documents are returned.

Example:

db.find("users", { name: "Alice" });

---

findOne(collectionName: string, query?: object)

Finds the first document matching a query.

---

findById(collectionName: string, id: string)

Finds a document by its unique _id.

---

updateOne(collectionName: string, query: object, update: {$set: object})

Updates a single document that matches the query using the $set operator.

Returns:

{ acknowledged: boolean, modifiedCount: number }

---

deleteOne(collectionName: string, query: object)

Deletes the first document that matches the query.

Returns:

{ acknowledged: boolean, deletedCount: number }

---

countDocuments(collectionName: string, query?: object)

Counts the number of documents matching a query. Counts all documents if no query is provided.

---

Advanced Operations

findWithIn(collectionName: string, query: object)

Finds documents that match an $in condition.

Example:

db.findWithIn("users", { name: { $in: ["Alice", "Bob"] } });

---

findWithRegex(collectionName: string, query: object)

Finds documents that match a $regex condition.

Example:

db.findWithRegex("users", { name: { $regex: "^A" } });

---

aggregate(collectionName: string, pipeline: object[])

Performs advanced queries using a combination of $match (filtering) and $group (aggregation).

Example:

const pipeline = [
  { $match: { age: { $gt: 25 } } },
  {
    $group: {
      _id: "country",
      totalAge: { $sum: "age" },
      count: { $count: 1 },
    },
  },
];

const results = db.aggregate("users", pipeline);

---

distinct(collectionName: string, field: string)

Returns all distinct values for a specific field.

Example:

db.distinct("users", "age");

---

renameCollection(oldName: string, newName: string)

Renames an existing collection.

---

dropCollection(collectionName: string)

Drops (deletes) a collection and all associated documents.

---

Running Tests

The library uses Mocha for testing. To run the tests:

npm test

To run tests in watch mode as you edit the code:

npm run test-watch

---

Contributing

Contributions, issues, and feature requests are welcome! Please check the issues page before opening new requests.

If you'd like to contribute:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature-name).
3. Commit your changes (git commit -m 'Add feature').
4. Push to your fork (git push origin feature-name).
5. Open a Pull Request.

---

License

This project is licensed under the MIT License.

---

Author

Developed and maintained by jmcudd. Feel free to reach out for support or collaboration!

GitHub: @jmcudd
X: @jmcudd

---

Links

• NPM: sqlite-docstore
• Repository: GitHub Repo
• Issues: Report Issues