doculite

To start using Doculite, instantiate a new Database object. By default, this creates a sqlite.db file in your current working directory.

import { Database } from "doculite";

// Creates sqlite.db file in the cwd
const db = new Database();

Doculite uses a Firestore-like syntax for data management. Collections are automatically created as SQLite tables upon the first document insertion.

To interact with data, you first create a reference to a document using db.collection(name).doc(id). If you do not provide an ID to .doc(), the ID is optional (though the example suggests it may be generated or handled by the library). Documents must be valid JavaScript objects that can be parsed to JSON.

// create ref to the doc. Doc ID optional.
const usersRef = db.collection("users").doc("123");
const refWithoutId = db.collection("users").doc();

// Any valid Javascript object that can be parsed to valid JSON can be inserted as a document.
await usersRef.set({
  username: "John Doe",
  createdAt: "123",
  updatedAt: "123",
});
await refWithoutId.set({ username: "Jane Doe" });

To remove a document from a collection, call the .delete() method on its document reference.

const db = new Database();
const ref = db.collection("users").doc("deletable");

await ref.set({ username: "deletableUsername", updatedAt: 123123 });

await ref.delete();

const doc = await ref.get();
console.log(doc); // prints null

To retrieve the data of a specific document, create a document reference and call the .get() method. This returns the document data or null if it does not exist.

// define ref
const usersRef = db.collection("users").doc("123");
// get
const user = await usersRef.get();
// print
console.log(user); // prints { username: "John Doe" };

You can perform basic queries on a collection using the .where(field, value) method. This returns a query object. Calling .get() on the query object returns an array of documents that match the criteria.

const usersRef = db.collection("users");

await usersRef.doc().set({ username: "Doculite", updatedAt: 234 });

const query = usersRef.where("username", "Doculite");

const docs = await query.get();

const user = docs[0];
console.log(user.username); // prints `Doculite`

Doculite supports real-time listeners on documents. Use the .onSnapshot(callback) method on a document reference. The callback is triggered whenever the document changes.

Calling .onSnapshot() returns an unsubscribe function which, when executed, stops the listener.

// ref to doc
const ref = db.collection("users").doc("123");

// snapshot listener returns unsubscribe function
const unsub = ref.onSnapshot((doc) => {
  console.log("Omg the user doc is updating!", doc?.username);
});

await ref.set({ username: "SHEESH Doe", updatedAt: 2 });
// prints: `Omg the user doc is updating! SHEESH Doe`

// unsub
unsub();

The primary entry point for Doculite is the Database class. It is used to manage database initialization, collection management, document operations (CRUD), and real-time updates. You can import it directly from the root module.

import { Database } from './index';

// Usage involves initializing the Database instance

The Query class allows you to fetch documents from a specific collection where a property matches a given value. You instantiate it by providing the Database instance, the collectionName, the property name to filter by, and the propertyValue to match.

Use the .get() method to perform an asynchronous fetch of the matching documents.

// Assuming 'db' is an initialized Database instance
const query = new Query(db, 'users', 'email', 'user@example.com');
const docs = await query.get();

When using DocumentReference.set(), you can control whether the new data overwrites the existing document or merges with it using the SetOptions object.

• merge: false (default): The document is replaced by the new docData. Any existing fields not present in docData will be lost.
• merge: true: The new docData is shallowly merged into the existing document. Existing fields are preserved unless they are explicitly overwritten by keys in docData.

// Overwrite existing document
await docRef.set({ field: 'value' }, { merge: false });

// Merge new fields into existing document
await docRef.set({ newField: 'newValue' }, { merge: true });

Use the PubSub<E>() function to create a new publish-subscribe instance. The generic type parameter E defines the schema of available events, where each key in E represents an event name and its corresponding value represents the payload type for that event. This ensures type safety when publishing messages or subscribing to specific events.

type Events = {
  warn: { message: string },
  error: { message: string }
}

const pubSub = PubSub<Events>();

// Publishing an event
pubSub.publish('warn', { message: "Something bad happened!" });