<p align="center"> <img src="https://github.com/appy-one/acebase/blob/806bc6e78920c1d735ae96fc8eb818f338ceb00a/logo.png?raw=true" alt="AceBase realtime database"> </p>

AceBase realtime database

A fast, low memory, transactional, index & query enabled NoSQL database engine and server for node.js and browser with realtime data change notifications. Supports storing of JSON objects, arrays, numbers, strings, booleans, dates, bigints and binary (ArrayBuffer) data.

Inspired by (and largely compatible with) the Firebase realtime database, with additional functionality and less data sharding/duplication. Capable of storing up to 2^48 (281 trillion) object nodes in a binary database file that can theoretically grow to a max filesize of 8 petabytes.

AceBase is easy to set up and runs anywhere: in the cloud, NAS, local server, your PC/Mac, Raspberry Pi, the browser, wherever you want.

🔥 Check out the new live data proxy feature that allows your app to use and update live database values using in-memory objects and no additional db coding!

Table of contents

• Getting started
  • Prerequisites
  • Installing
  • Example usage
  • Creating a database
• Loading and storing data
  • Loading data
  • Storing data
  • Updating data
  • Transactional updating
  • Removing data
  • Generating unique keys
  • Using arrays
  • Counting children
  • Limit nested data loading
  • Iterating (streaming) children
  • Asserting data types in TypeScript
• Realtime monitoring
  • Monitoring realtime data changes
  • Using variables and wildcards in subscription paths
  • Notify only events
  • Wait for events to activate
  • Get triggering context of events
  • Change tracking using "mutated" and "mutations" events
  • Observe realtime value changes
  • Realtime synchronization with a live data proxy
  • Using proxy methods in Typescript
• Queries
  • Querying data
  • Limiting query result data
  • Removing data with a query
  • Counting query results
  • Checking query result existence
  • Streaming query results
  • Realtime queries
• Indexes
  • Indexing data
  • Indexing scattered data with wildcards
  • Include additional data in indexes
  • Other indexing options
  • Special indexes
  • Array indexes
  • Fulltext indexes
  • Geo indexes
• Schemas (NEW v1.3.0)
  • Validating data with schemas
  • Adding schemas to enforce data rules
  • Schema Examples
• Class mappings (ORM)
  • Mapping data to custom classes
• Data storage options
  • AceBase data storage engine
  • Using SQLite or MSSQL storage
  • AceBase in the browser
  • Using CustomStorage
• Reflect API
  • Introduction
  • Get information about a node
  • Get children of a node
• Importing and Exporting data
  • Export API usage
  • Import API usage
• Transaction Logging
  • Info
• Multi-process support
  • Info
• CommonJS and ESM packages
• Upgrade notices
• Known issues
• Authors
• Contributing
• Sponsoring

Getting Started

AceBase is split up into multiple packages:

• acebase: local AceBase database engine (github, npm)
• acebase-server: AceBase server endpoint to enable remote connections. Includes built-in user authentication and authorization, supports using external OAuth providers such as Facebook and Google (github, npm).
• acebase-client: client to connect to an external AceBase server (github, npm)
• acebase-core: shared functionality, dependency of above packages (github, npm)

AceBase uses semver versioning to prevent breaking changes to impact older code. Please report any errors / unexpected behaviour you encounter by creating an issue on Github.

Prerequisites

AceBase is designed to run in a Node.js environment, as it (by default) requires the 'fs' filesystem to store its data and indexes. However, since v0.9.0 it is now also possible to use AceBase databases in the browser! To run AceBase in the browser, simply include 1 script file and you're good to go! See AceBase in the browser for more info and code samples!

Installing

All AceBase repositories are available through npm. You only have to install one of them, depending on your needs:

Create a local database

If you want to use a local AceBase database in your project, install the acebase package.

npm install acebase

Then, create (open) your database:

const { AceBase } = require('acebase');
const db = new AceBase('my_db'); // nodejs
// OR: const db = AceBase.WithIndexedDB('my_db'); // browser
db.ready(() => {
    // Do stuff
});

Try AceBase in your browser

If you want to try out AceBase running in Node.js, simply open it in RunKit and follow along with the examples. If you want to try out the browser version of AceBase, open google.com in a new tab (GitHub doesn't allow cross-site scripts to be loaded) and run the code snippet below to use it in your browser console immediately.

To try AceBase in RunKit:

const { AceBase } = require('acebase');
const db = new AceBase('mydb');

await db.ref('test').set({ text: 'This is my first AceBase test in RunKit' });

const snap = await db.ref('test/text').get();
console.log(`value of "test/text": ` + snap.val());

To try AceBase in the browser console:

await fetch('https://cdn.jsdelivr.net/npm/acebase@latest/dist/browser.min.js')
    .then(response => response.text())
    .then(text => eval(text));
if (!AceBase) { throw 'AceBase not loaded!'; }

var db = AceBase.WithIndexedDB('mydb');
await db.ref('test').set({ text: 'This is my first AceBase test in the browser' });

const snap = await db.ref('test/text').get();
console.log(`value of "test/text": ` + snap.val());

Setup a database server

If you want to setup an AceBase server, install acebase-server.

npm install acebase-server

Then, start your server (server.js):

const { AceBaseServer } = require('acebase-server');
const server = new AceBaseServer('my_server_db', { /* server config */ });
server.ready(() => {
    // Server running
});

Connect to a remote database

If you want to connect to a remote (or local) AceBase server, install acebase-client.

npm install acebase-client

Then, connect to your AceBase server:

const { AceBaseClient } = require('acebase-client');
const db = new AceBaseClient({ /* connection config */ });
db.ready(() => {
    // Connected!
});

Example usage

The API is similar to that of the Firebase realtime database, with additions.

Creating a database

Creating a new database is as simple as opening it. If the database file doesn't exists, it will be created automatically.

const { AceBase } = require('acebase');
const options = { logLevel: 'log', storage: { path: '.' } }; // optional settings
const db = new AceBase('mydb', options);  // Creates or opens a database with name "mydb"

db.ready(() => {
    // database is ready to use!
})

NOTE: The logLevel option specifies how much info should be written to the console logs. Possible values are: 'verbose', 'log' (default), 'warn' and 'error' (only errors are logged)

Loading data

Run .get on a reference to get the currently stored value. This is short for the Firebase syntax of .once("value").

const snapshot = await db.ref('game/config').get();
if (snapshot.exists()) {
    config = snapshot.val();
}
else {
    config = defaultGameConfig; // use defaults
}

Note: When loading data, the currently stored value will be wrapped and returned in a DataSnapshot object. Use snapshot.exists() to determine if the node exists, snapshot.val() to