📦 GraphDB – An in memory database with sync capabilities

GraphDB is an in memory database with sync capabilities that lets you handle data the way you want with a bare minimum setup.

• Quick start
• Initialization
• API and Types
• Create a collection
• Get a collection
• Populate a collection
• Listen to collection on
• Create a document
• Read a document
• Query documents
• Query documents with complex where clause
• Query documents with additional options
• Update a document
• Remove a document
• Listen to changes
• Syncers

Quick start

yarn add @alexvcasillas/graphdb

npm i -s @alexvcasillas/graphdb

Initialization

import { GraphDB } from '@alexvcasillas/graphdb';

const graphdb = GraphDB();

API and Types

export type GraphDBType = {
  createCollection: <T>(
    collectionId: string,
    syncers?: GraphDocumentSyncers<T>
  ) => void;
  getCollection: <T>(collectionId: string) => Collection<T> | null;
};

export type Where = {
  [property: string]: any;
};

export type QueryOptions = {
  skip?: number;
  limit?: number;
  orderBy?: {
    [key: string]: 'ASC' | 'DESC';
  };
};

export type Collection<T> = {
  read: (documentId: string) => GraphDocument<T>;
  query: (
    where: Where,
    options?: QueryOptions
  ) => GraphDocument<T> | GraphDocument<T>[] | null;
  create: (document: T) => Promise<string>;
  update: (documentId: string, patch: Partial<T>) => Promise<GraphDocument<T>>;
  remove: (documentId: string) => Promise<RemoveOperationFeedback>;
  populate: (population: GraphDocument<T>[]) => void;
  listen: (
    documentId: string,
    listener: ListenerFn<GraphDocument<T>>
  ) => CancelListenerFn;
  on: (
    type: 'create' | 'update' | 'remove' | 'populate',
    listener: ListenerFn<GraphDocument<T>>
  ) => CancelListenerFn;
};

export type GraphDocument<T> = {
  _id: string;
  createdAt: Date;
  updateAt: Date;
} & T;

export type ListenerFn<T> = (document: GraphDocument<T>) => void;
export type ListenerOnFn = () => void;

export type GraphDocumentListener<T> = {
  id: string;
  document: string;
  fn: ListenerFn<GraphDocument<T>>;
};

export type GraphDocumentListenerOn = {
  id: string;
  type: 'create' | 'update' | 'remove' | 'populate';
  fn: ListenerOnFn;
};

export type GraphDocumentListeners<T> = GraphDocumentListener<T>[];
export type GraphDocumentListenersOn = GraphDocumentListenerOn[];

export type CancelListenerFn = () => void;

export type GraphDocumentSyncers<T> = {
  create?: (document: GraphDocument<T>) => Promise<boolean>;
  update?: (document: GraphDocument<T>) => Promise<boolean>;
  remove?: (documentId: string) => Promise<boolean>;
};

export type RemoveOperationFeedback = {
  removedId: string;
  acknowledge: true;
};

Create a collection

interface UserModel {
  name: string;
  lastName: string;
  age: string;
}

graphdb.createCollection<UserModel>('user');

Get a collection

interface UserModel {
  name: string;
  lastName: string;
  age: string;
}

const userCollection = graphdb.getCollection<UserModel>('user');

Populate a collection

interface UserModel {
  name: string;
  lastName: string;
  age: string;
}

const userCollection = graphdb.getCollection<UserModel>('user');

userCollection.populate([
  {
    _id: '1',
    name: 'Alex',
    lastName: 'Casillas',
    age: 29,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '2',
    name: 'Alex',
    lastName: 'Casillas',
    age: 29,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '3',
    name: 'Alex',
    lastName: 'Casillas',
    age: 29,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '4',
    name: 'Alex',
    lastName: 'Casillas',
    age: 29,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '5',
    name: 'Alex',
    lastName: 'Casillas',
    age: 29,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '6',
    name: 'Alex',
    lastName: 'Casillas',
    age: 29,
    createdAt: new Date(),
    updateAt: new Date(),
  },
]);

Listen to collection on

import { GraphDocument } from '@alexvcasillas/graphdb';

interface UserModel {
  name: string;
  lastName: string;
  age: string;
}

const userCollection = graphdb.getCollection<UserModel>('user');

const stopOnCreateListen = userCollection.on('create', function onCreate() {});
const stopOnPopulateListen = userCollection.on(
  'populate',
  function onPopulate() {}
);
const stopOnUpdateListen = userCollection.on('update', function onUpdate() {});
const stopOnRemoveListen = userCollection.on('remove', function onRemove() {});

stopOnCreateListen();
stopOnPopulateListen();
stopOnUpdateListen();
stopOnRemoveListen();

Create a document

interface UserModel {
  name: string;
  lastName: string;
  age: string;
}

const userCollection = graphdb.getCollection<UserModel>('user');

const insertedId = await userCollection.create({
  name: 'Alex',
  lastName: 'Casillas',
  age: 29,
});

Read a document

interface UserModel {
  name: string;
  lastName: string;
  age: string;
}

const userCollection = graphdb.getCollection<UserModel>('user');

const insertedId = await userCollection.create({
  name: 'Alex',
  lastName: 'Casillas',
  age: 29,
});

const userDocument = userCollection.read(insertedId as string);

Query documents

interface UserModel {
  name: string;
  lastName: string;
  age: string;
}

const userCollection = graphdb.getCollection<UserModel>('user');

await userCollection.create({
  name: 'Alex',
  lastName: 'Casillas',
  age: 29,
});

// Empty where clause returns all documents on the collection
userCollection.query({});
userCollection.query({ name: 'Alex', age: 29 });

RegExp can be used as value to check for a matching property without the need of a complex query object.

interface UserModel {
  name: string;
  lastName: string;
  age: string;
  email: string;
}

const userCollection = graphdb.getCollection<UserModel>('user');

userCollection?.populate([
  {
    _id: '1',
    name: 'Alex',
    lastName: 'Casillas',
    email: 'alex@gmail.com',
    age: 29,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '2',
    name: 'Daniel',
    lastName: 'Casillas',
    email: 'dani@hotmail.com',
    age: 22,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '3',
    name: 'Antonio',
    lastName: 'Cobos',
    email: 'antonio@gmail.com',
    age: 35,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '4',
    name: 'John',
    lastName: 'Snow',
    email: 'john@thewall.com'
    age: 19,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '5',
    name: 'John',
    lastName: 'Doe',
    email: 'john@gmail.com',
    age: 40,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '6',
    name: 'Jane',
    lastName: 'Doe',
    email: 'jane@msn.com',
    age: 50,
    createdAt: new Date(),
    updateAt: new Date(),
  },
]);

const queryResult = userCollection?.query({
  'name', new RegExp(/Al{1,1}/ig)
});

// queryResult.length === 1

// queryResult[0]
// { _id: '1', name: 'Alex', lastName: 'Casillas', email: 'alex@gmail.com' }

Query documents with complex where clause

Complex operators for number types include for now:

• gt: greater than
• gte: greater than or equals
• lt: lower than
• lte: lower than or equals

{ age: { gt: 20, lt: 40 } }

interface UserModel {
  name: string;
  lastName: string;
  age: string;
}

const userCollection = graphdb.getCollection<UserModel>('user');

userCollection?.populate([
  {
    _id: '1',
    name: 'Alex',
    lastName: 'Casillas',
    age: 29,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '2',
    name: 'Daniel',
    lastName: 'Casillas',
    age: 22,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '3',
    name: 'Antonio',
    lastName: 'Cobos',
    age: 35,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '4',
    name: 'John',
    lastName: 'Snow',
    age: 19,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '5',
    name: 'John',
    lastName: 'Doe',
    age: 40,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '6',
    name: 'Jane',
    lastName: 'Doe',
    age: 50,
    createdAt: new Date(),
    updateAt: new Date(),
  },
]);

const queryResult = userCollection?.query({
  age: { gt: 30 },
});

// queryResult.length === 3

// queryResult[0]
// { _id: '3', name: 'Antonio', lastName: 'Cobos', age: 35 }

// queryResult[1]
// { _id: '5', name: 'John', lastName: 'Doe', age: 40 }

// queryResult[2]
// { _id: '6', name: 'Jane', lastName: 'Doe', age: 50 }

Complex operators for string types include for now:

• eq: equals
• notEq: not equals
• includes: includes the given substring
• startsWith: starts with the given substring
• endsWith: ends with the given substring

This operators can be used to form complex where clauses like the following:

{ email: { endsWith: '@gmail.com' } }

interface UserModel {
  name: string;
  lastName: string;
  age: string;
  email: string;
}

const userCollection = graphdb.getCollection<UserModel>('user');

userCollection?.populate([
  {
    _id: '1',
    name: 'Alex',
    lastName: 'Casillas',
    email: 'alex@gmail.com',
    age: 29,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '2',
    name: 'Daniel',
    lastName: 'Casillas',
    email: 'dani@hotmail.com',
    age: 22,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '3',
    name: 'Antonio',
    lastName: 'Cobos',
    email: 'antonio@gmail.com',
    age: 35,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '4',
    name: 'John',
    lastName: 'Snow',
    email: 'john@thewall.com'
    age: 19,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '5',
    name: 'John',
    lastName: 'Doe',
    email: 'john@gmail.com',
    age: 40,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '6',
    name: 'Jane',
    lastName: 'Doe',
    email: 'jane@msn.com',
    age: 50,
    createdAt: new Date(),
    updateAt: new Date(),
  },
]);

const queryResult = userCollection?.query({
  email: { endsWith: '@gmail.com' },
});

// queryResult.length === 3

// queryResult[0]
// { _id: '1', name: 'Alex', lastName: 'Casillas', email: 'alex@gmail.com' }

// queryResult[1]
// { _id: '3', name: 'Antonio', lastName: 'Cobos', email: 'antonio@gmail.com' }

// queryResult[2]
// { _id: '5', name: 'John', lastName: 'Doe', email: 'john@gmail.com' }

Complex operators can include a RegExp to match, this will give you a boost of flexibility, the match property in the complex where clause will allow you to perform this operation.

interface UserModel {
  name: string;
  lastName: string;
  age: string;
  email: string;
}

const userCollection = graphdb.getCollection<UserModel>('user');

userCollection?.populate([
  {
    _id: '1',
    name: 'Alex',
    lastName: 'Casillas',
    email: 'alex@gmail.com',
    age: 29,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '2',
    name: 'Daniel',
    lastName: 'Casillas',
    email: 'dani@hotmail.com',
    age: 22,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '3',
    name: 'Antonio',
    lastName: 'Cobos',
    email: 'antonio@gmail.com',
    age: 35,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '4',
    name: 'John',
    lastName: 'Snow',
    email: 'john@thewall.com'
    age: 19,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '5',
    name: 'John',
    lastName: 'Doe',
    email: 'john@gmail.com',
    age: 40,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '6',
    name: 'Jane',
    lastName: 'Doe',
    email: 'jane@msn.com',
    age: 50,
    createdAt: new Date(),
    updateAt: new Date(),
  },
]);

const queryResult = userCollection?.query({
  'name', { match: new RegExp(/Al{1,1}/ig) }
});

// queryResult.length === 1

// queryResult[0]
// { _id: '1', name: 'Alex', lastName: 'Casillas', email: 'alex@gmail.com' }

Query documents with additional options

Additional options for the query are the following:

• skip: skips the given amount of documents from the beginning of the collection
• limit: by the given amount limits the resulted documents from the query
• orderBy: sorts the resulted query documents by the given fields in the given order (ASC or DESC)

This operators can be combined to form complex option clauses like the following:

{
  skip: 2,
  limit: 4,
  orderBy: {
    age: 'DESC',
  },
}

interface UserModel {
  name: string;
  lastName: string;
  age: string;
}

const userCollection = graphdb.getCollection<UserModel>('user');

userCollection?.populate([
  {
    _id: '1',
    name: 'Alex',
    lastName: 'Casillas',
    age: 29,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '2',
    name: 'Daniel',
    lastName: 'Casillas',
    age: 22,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '3',
    name: 'Antonio',
    lastName: 'Cobos',
    age: 35,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '4',
    name: 'John',
    lastName: 'Snow',
    age: 19,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '5',
    name: 'John',
    lastName: 'Doe',
    age: 40,
    createdAt: new Date(),
    updateAt: new Date(),
  },
  {
    _id: '6',
    name: 'Jane',
    lastName: 'Doe',
    age: 50,
    createdAt: new Date(),
    updateAt: new Date(),
  },
]);

const queryResult = userCollection?.query(
  {},
  {
    orderBy: {
      age: 'ASC',
    },
  }
);

// queryResult[0]._id = '4'
// queryResult[1]._id = '2'
// queryResult[2]._id = '1'
// queryResult[3]._id = '3'
// queryResult[4]._id = '5'
// queryResult[5]._id = '6'

Update a document

interface UserModel {
  name: string;
  lastName: string;
  age: string;
}

const userCollection = graphdb.getCollection<UserModel>('user');

const insertedId = await userCollection.create({
  name: 'Alex',
  lastName: 'Casillas',
  age: 29,
});

const updatedDocument = await userCollection.update(insertedId as string, {
  name: 'John',
  lastName: 'Snow',
});

Remove a document

interface UserModel {
  name: string;
  lastName: string;
  age: string;
}

const userCollection = graphdb.getCollection<UserModel>('user');

const insertedId = await userCollection.create({
  name: 'Alex',
  lastName: 'Casillas',
  age: 29,
});

const removeFeedback = await userCollection.remove(insertedId as string);

Listen to changes

import { GraphDocument } from '@alexvcasillas/graphdb';

interface UserModel {
  name: string;
  lastName: string;
  age: string;
}

const userCollection = graphdb.getCollection<UserModel>('user');

const insertedId = await userCollection.create({
  name: 'Alex',
  lastName: 'Casillas',
  age: 29,
});

const stopListen = userCollection.listen(
  insertedId as string,
  (document: GraphDocument<UserModel>) => {
    // Handle document updates here
  }
);

// Call this whenever you want to stop lintening to changes
stopListen();

Syncers

Syncers are a cool feature that will let you sync data to your backend. You can add up to three syncers: to create, to update and to remove.

import { GraphDB } from '@alexvcasillas/graphdb'

const graphdb = GraphDB();

interface UserModel {
  name: string;
  lastName: string;
  age: string;
}

graphdb.createCollection<UserModel>('user', {
  create(document: GraphDocument<T>) {
    return new Promise((resolve, reject) => {
      // Send data to your backend!
      const backendResponse = await backend.create(document);
      // Resolve with true if backend process was ok
      if (backendResponse.status === 200) return resolve(true);
      // Reject with false if backend process was ok
      if (backendResponse.status === 500) return reject(false);
    });
  };
  update(document: GraphDocument<T>) {
    return new Promise((resolve, reject) => {
      // Send data to your backend!
      const backendResponse = await backend.update(document);
      // Resolve with true if backend process was ok
      if (backendResponse.status === 200) return resolve(true);
      // Reject with false if backend process was ok
      if (backendResponse.status === 500) return reject(false);
    });
  };
  remove(documentId: string) {
    return new Promise((resolve, reject) => {
      // Send data to your backend!
      const backendResponse = await backend.remove(document);
      // Resolve with true if backend process was ok
      if (backendResponse.status === 200) return resolve(true);
      // Reject with false if backend process was ok
      if (backendResponse.status === 500) return reject(false);
    });
  };
});

The cool thing about data-syncing is that if the sync promise returns false, it will revert changes locally at the state it was previously, meaning that changes wont be applied localy and you'll always be in-sync with your backend.