Database Abstraction

defuss-db abstracts interactions with databases, allowing you to focus on your application logic without worrying about the underlying database implementation, schema, or queries. It provides a consistent API for various databases, making it easier to switch between them or use multiple databases in a single application.

Supported Databases

• Dexie: A wrapper for IndexedDB that provides a simple and powerful API for working with client-side databases in web applications. It is designed to be easy to use and provides a consistent API across different browsers.

• MongoDB: A NoSQL database that uses a flexible, JSON-like format for data storage. It is designed for scalability and performance, making it a popular choice for modern web applications.

• LibSQL: A SQL database that is designed to be lightweight and easy to use. It is built on top of SQLite and provides a simple API for interacting with SQL databases.

Providing an isomorphic API for all three databases, defuss-db allows you to use the same codebase for both client-side and server-side database interactions. This means you can write your database queries once and use them in both environments without worrying about compatibility issues.

Integrating defuss-db in an existing defuss project

🚀 Looking for a template to start from? examples/notebooks is an Astro project pre-configured to work with defuss-db out-of-the-box.

2. Integrate defuss-db:

Just import Table from defuss-db and use it in your project:

import { Table } from 'defuss-db';

A table needs a database storage provider:

In-browser (client-side/frontend) use-case:

import { DexieProvider } from "defuss-db";

Using the database is as easy as wiring them up:

// define a model
interface User {
  name: string;
  age: number;
  email: string;
}

const dexieProvider = new DexieProvider(TEST_DB_NAME);
await dexieProvider.connect(); // connects to the database

const myTable = new DefussTable<User>(provider, "my-table");
await myTable.init(); // runs a schema update

3. Use the API of defuss-db:

To interact with the table, create, read, update, and delete records:

const user: User = {
  name: "Alice",
  age: 30,
  email: "[email protected]",
};

// in defuss-db, indices are added explicitly, this allows for indices to diverge from the underlying from the data stored. This separation solves a common issue with performance in speed and size dimensions.
const indexData = { email: user.email }; // data to find the user by later-on

// returns the primary key of the inserted user
const pk = await table.insert(/* data */ user, /* indices */ indexData);

// find a specific user
const user = await table.findOne(/* indices */ { email: "[email protected]" });

// find many users of a specific TLD
const users = await table.find(/* indices */ { email: "*@example.com" });

// updates the user
await table.update(/* update indices */ { email: user.email }, /* paertial data */ { age: 29 });

// deletes the user
await table.delete(/* indices */ { email: user.email });

Due to the nature of defuss-db, bridging the gap beween different database architectures and even between frontend and backend, the API cannot feature all the specific functionality of each underlaying provider. It is designed to simply provide the intersection feature-set. There are no foreign keys, no transactions, no joins, and no complex queries. You are supposed to design your data model in a semi-normalized way and use smart indices and data access patterns to get the most out of this.

🚀 How does defuss-db work?

Inside this package, you'll find the following relevant folders and files:

/
├── provider/dexie.ts
├── provider/libsql.ts
├── provider/mongodb.ts
├── src/index.ts
├── src/types.ts
├── src/env.ts
├── src/table.ts
├── src/client.ts
├── src/server.ts
├── tsconfig.json
├── LICENSE
├── package.json

The src/index.ts file is the "entry point" for general and type imports, while server.ts and client.ts are the respective imports to use whenever a specific runtime environment implement is desired to be used. The defuss-db/client and defuss-db/server imports will resolve to these files automatically.

You'll find each specific provider implementation in the provider folder.

🧞 Commands

All commands are run from the root of the project, from a terminal:

| Command | Action | | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | npm build | Build a new version of the integration. | | npm mongodb:start | Start the MongoDB server (requires Docker). | | npm mongodb:stop | Stop the MongoDB server (requires Docker). | | npm test:integration | Run the integration tests for the defuss-db package. |