nativescript-sqlite-access v1.1.0

NativeScript sqlite access

Just a NativeScript plugin to access and manage data with sqlite on .

Installation

Run the following command from the root of your project:

tns plugin add nativescript-sqlite-access

The command above automatically installs the necessary files, as well as stores nativescript-sqlite-access as a dependency in your project's package.json file.

Usage

You need to import function DbBuilder to create a instance of SqliteAccess class and access to the API of the plugin to manage your app's data.

import { DbBuilder } from 'nativescript-sqlite-access';

export class HomeViewModel {
    private db;
    constructor() {
        super();
        // Creating SqliteAccess class instance
        // Passing the name of the database file
        this.db = DbBuilder("<database_file_name>");
    }
}

The function DbBuilder receive two parameters the database file name and an optional DbCreationOptions object. If you do not pass the last parameter, a default one will be created, but you cannot set the db version.

See the full example below in typescript

import {DbBuilder, IDatabase, DbCreationOptions, ReturnType} from 'nativescript-sqlite-access';

export class HomeViewModel {
    private db: IDatabase;
    constructor() {
        super();
        this.db = DbBuilder("test.db", <DbCreationOptions>{
            version: 1, //Version of the database
            /*All tables needed*/
            createTableScriptsFn: ()=> {
                return ['CREATE TABLE if not exists table_name(_id INTEGER PRIMARY KEY AUTOINCREMENT, column TEXT)'];
            },
            /*Drop tables scripts, needed if your will change the tables structure*/
            dropTableScriptsFn:()=> { 
                return ['DROP TABLE IF EXISTS table_name']
            },
            returnType: ReturnType.AS_OBJECT /*(DEFAULT) | ReturnType.AS_ARRAY*/
        });
    }
}

createTableScriptsFn and dropTableScriptsFn will be executed when database is created or database version is changed to a higher value. Those functions must return an array of string with all the scripts to create or delete the tables used in your app. In case you change a table structure you must change the database version to apply the changes.

DbCreationOptions' properties

API

/**
* Insert a row into table with the values (key = columns and values = columns value)
*
* @param {string} tableName
* @param {{ [key: string]: any; }} values
*
* @returns {number}  id inserted
*/

insert(tableName: string, values: { [key: string]: any }): number;

/**
* Replace a row values in the table with the values (key = columns and values = columns value).
* The table must has a primary column to match with
*
* @param {string} tableName
* @param {{ [key: string]: any; }} values
*
* @returns {number} rows affected
*/
replace(tableName: string, values: { [key: string]: any }): number;

/**
* Update a row values in the table with the values (key = columns and values = columns value) to the matched row.
*
* @param {string} tableName
* @param {{ [key: string]: any; }} values
* @param {string} whereClause
* @param {Array<any>} whereArs
*
* @returns {number} rows affected
*/
update(tableName: string, values: { [key: string]: any }, whereClause: string, whereArs: Array<any>): number;

/**
* Delete rows or a row from the table that matches the condition.
*
* @param {string} tableName
* @param {string} whereClause - optional
* @param {Array<any>} whereArs - optional
*
* @returns {number} rows affected
*/
delete(tableName: string, whereClause?: string, whereArs?: Array<any>): number;

/**
* Query the table data that matches the condition.
* @see ExtendedPromise for more information.
* 
* @param {string} sql SQL Query. `SELECT [COLUMNS,] FROM TABLE WHERE column1=? and column2=?`. WHERE clause can be omitted
* @param {Array<any>} conditionParams - optional if there is not WHERE clause in the sql param
*
* @returns {ExtendedPromise} ExtendedPromise object that returns a Promise<Array<any>>
*/
select(sql: string, conditionParams?: Array<any>): ExtendedPromise;

/**
* Execute a query selector with the params passed in
* @see ExtendedPromise for more information.
* 
* @param {string} tableName
* @param {Array<string>} columns - optional
* @param {string} selection - optional
* @param {Array<string>} selectionArgs - optional
* @param {string} groupBy - optional
* @param {string} orderBy - optional
* @param {string} limit - optional
*
* @returns {ExtendedPromise} ExtendedPromise object that returns a Promise<Array<any>>
*/
query(tableName: string, columns?: Array<string>,
    selection?: string, selectionArgs?: Array<any>,
    groupBy?: string, orderBy?: string, limit?: string): ExtendedPromise;

/**
* Execute a SQL script and do not return anything
* @param {string} sql
*/
execSQL(sql: string): void;

/**
* Open a transaction
*/
beginTransact(): void;

/**
* Commit the transaction
*/
commit(): void;

/**
* Rollback a transaction
*/
rollback(): void;

/**
* Close the database connection
*/
close(): void;

select and query function return a ExtendedPromise in v1.0.8.

/**
 * Let it add preprocessing function to each row matched by SQL query, each function return a Promise object.
 * The map and reduce functions are similar to the functions apply to an Array, 
 * just one preprocessing function is apply to the data per call.
 * The process function is call just if the map or reduce function will not be apply.
 */
class ExtendedPromise {

map(callback): Promise<any>;

reduce(callback, initialValue: any): Promise<any>;

process(): Promise<any>;

}

### Changes

v1.0.8
- Fixes the wrong import file in the index file.
- parameter reduceFn was remove from `select` function.
- `select` and `query` function return a `ExtendedPromise` that let you add a map or reduce function to each matched rows.