@appstrax/database

This library contains a simple javascript database service, which allows you to easily integrate with your database in your web applications.

Getting Started

Create your Appstrax API here: https://codecapsules.io/.

Installation

npm install @appstrax/database --save

Setup

Initialize the database library:

// import the database library
import { database } from '@appstrax/database';

// initialize the database service
const apiUrl = 'YOUR API URL HERE'; // eg. appstrax-database-api-snidtu.codecapsules.co.za
database.init(apiUrl);

Model

DocumentDto {
  id: string;
  data: any = {};
  createdAt: Date = null;
  updatedAt: Date = null;
}

Fetch from database

import { database } from '@appstrax/database';

try {
  // fetch all records
  let documents = await database.find('collection');

  // fetch all records where name is equal to 'appstrax'
  documents = await database.find('collection', { name: 'appstrax' });

  // documents are a DocumentDto[]
} catch (err) {
  console.log(err);
}

import { database } from '@appstrax/database';

try {
  const document = await database.findById('collection', id);
  // document is a DocumentDto
} catch (err) {
  console.log(err);
}

Write to database

import { database } from '@appstrax/database';

try {
  const document = await database.create('collection', {
    // any custom fields
    field1: 'value 1',
    field2: 'value 2',
    ...
  });

  // document is a DocumentDto
} catch (err) {
  console.log(err);
}

import { database } from '@appstrax/database';

try {
  const document = await database.edit('collection', id, {
    // whole object to be updated
    field1: 'value 1',
    field2: 'value 2',
    ...
  });

  // document is a DocumentDto
} catch (err) {
  console.log(err);
}

Remove from database

import { database } from '@appstrax/database';

try {
  await database.delete('collection', id);
} catch (err) {
  console.log(err);
}

CRUD Service

This is a helper class which wraps the database calls above. Below shows an example of how to use this service.

import { CrudService, Model, Ignore } from '@appstrax/database';

// your model must extend Model
export class User extends Model {
  // all fields must have a default value
  name: string = '';
  surname: string = '';
  email: string = '';
  role: string = 'user';

  // any fields you do now want to save to the database, prefix with @Ignore
  @Ignore age: number = 0;

  getFullName() {
    return this.name + ' ' + this.surname;
  }
}

export class UserService extends CrudService<User> {
  constructor() {
    // 'users' is the collection
    super('users', User);
  }

  // extend the service with any custom functions here
}

to use the service, here are some examples

try {
  const userService = new UserService();
  
  let user = new User();
  user.name = 'Test';
  user.surname = 'User';
  user.email = '[email protected]';


  // create a user
  user = await userService.save(user);
  console.log(JSON.stringify(user));
  /*
    example output
    {
      id: '610a4ff4f2cac700146571b6',
      name: 'Test',
      surname: 'User',
      email: '[email protected]',
      role: 'user',
      age: 0,
      createdAt: '2021-08-23T10:05:02.233Z',
      updatedAt: '2021-08-23T10:05:02.233Z'
    }
  */


  user.name = 'Joe';
  user.surname = 'Soap';
  // update a user
  user = await userService.save(user);
  console.log(JSON.stringify(user));
  /*
    example output
    {
      id: '610a4ff4f2cac700146571b6',
      name: 'Joe',
      surname: 'Soap',
      email: '[email protected]',
      role: 'user',
      age: 0,
      createdAt: '2021-08-23T10:05:02.233Z',
      updatedAt: '2021-08-23T10:06:49.047Z'
    }
  */


  // fetch all users
  const users = await userService.find();
  // the fetched users will be an array of instantiated User objects, this allows:
  console.log(users[0].getFullName());
  /*
    example output
    'Joe Soap'
  */


  // fetch a user by id
  user = await userService.findById(users[0].id);
  // the fetched user will be an instantiated User object


  // remove a user
  await userService.delete(user.id);
} catch(err) {
  // something went wrong
}