AppClient is a platform library developed and provided by Appery.io that acts as middleware between the mobile app and Appery.io backend services (API Express and Appery.io Database).
Appery.io backend services can be used directly, so using AppClient in a mobile app is quite optional.

Consider using AppClient with backend services (API Express and Appery.io Database) - it can be very useful while working with apps using a lot of backend services.

AppClient also comes into play when the app requires some advanced features, like, for example, offline mode support and data synchronization, caching, user autologin.

AppClient provides all these and many other useful features out of the box.

Initialization

By default $a.aex helper is not available in the project. To enable this helper you need to provide 2 files:

• Settings file AppClientSettings
• External TS lib AppClientMetadata

AppClientSettings

This is a common Settings file (Create New -> Service -> Settings (REST settings)). Available settings are:

AppClientMetadata

This is a common TypeScript file (Create New -> TypeScript -> Type: External lib).

Example

Here is example for appery.io DB settings

const apiHost = "https://api.appery.io";

const AppClientMetadata = {
    "isSecurity": true,
    "securityOptionsEnabled": true,

    "api": {
        "security": {
          // use custom backend script for login
            "login": {
                "method": "POST",
              // script id is set in Settings -> loginScriptId
                "url": `${apiHost}/rest/1/code/{Settings.loginScriptId}/exec`
            },
          // "loginUserByToken"
          // "login"
          // "logout"
          // "signup"
          // "updateUser"
          // "removeUser"
          // "getCurrentUser"
          // "sessionTokenParamName":"Authorization",
          // "authenticationSchemeName": "Bearer"
          // "apiKeyParamName"
        }
    },

    "models": [
        {
            "modelName": "files",
            "modelType": "BACKEND",
            "modelSyncType": "ONE_WAY",
            "schema": {
                "type": "object",
                "properties": {
                    "_id": {
                        "type": [
                            "string"
                        ]
                    }
                },
                "required": []
            },
            "idAttribute": "_id",
            // "deletedAttribute": "deleted",
            // "modifiedAtAttribute": "_updatedAt",
            "mergeAttributes": ["content"],
            "api": {
                "create": {
                    "url": `${apiHost}/rest/1/db/files`
                },
                "get": {
                    "url": `${apiHost}/rest/1/db/files/json/{_id}?full_object=true`
                },
                "delete": {
                    "url": `${apiHost}/rest/1/db/files/{_id}`
                },
                "find": {
                    "url": `${apiHost}/rest/1/db/files`
                },
              // "update" - not used for files but could be set for other models
            }
        }
    ]
};
export {
    AppClientMetadata
};

Helper properties and methods

state

state: string;

Current AppClient state. Could be one of: initial, offline, online, not_synced, synchronizing, sync_failed

Example

console.log(this.$a.aex.state);

getState

getState(): Promise<{state: string}>

Get current AppClient state.

Returns

Promise with current AppClient state. For example: {state: "offline"}

Example

let state = await this.$a.aex.getState();

getInstance

getInstance(): Promise

Get full mssdk AppClient instance.

Returns

Promise with mssdk AppClient instance.

Example

let mssdk = await this.$a.aex.getInstance();

get

get(entity: string, id, options ? ): Promise

Get item from entity by id.

Parameters

• entity - name of the collection or model;
• id - item id;
• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error;
  • cached - get from cache (if true) or make a request to the server (if false). If not specified then try to get data from cache and if nothing was found then make a request to the server.

Returns

Promise with received object

Example

let item = await this.$a.aex.get("tasks", "52c6bfa7e4b03c65ed01f039");

query

query(entity: string, params?: {where?: any; sortBy?: string; limit?: number;}, options?): Promise<any[]>

Query entity.

Parameters

• entity - name of the collection or model;
• params - query params object. Seee details. Available params are:
  • where - (optional). object;
  • sortBy - (optional). string;
  • limit - (optional). number;
• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error;
  • cached - get from cache (if true) or make a request to the server (if false). If not specified then try to get data from cache and if nothing was found then make a request to the server.

Returns

Promise with array of received objects

Example

let items = await this.$a.aex.query("tasks", {where: {"status": "done"}});

queryOne

queryOne(entity: string, params?: {where?: any; sortBy?: string;}, options?): Promise

Query entity.

Parameters

• entity - name of the collection or model;
• params - query params object. Seee details. Available params are:
  • where - (optional). object;
  • sortBy - (optional). string;
• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error;
  • cached - get from cache (if true) or make a request to the server (if false). If not specified then try to get data from cache and if nothing was found then make a request to the server.

Returns

Promise with received object

Example

let items = await this.$a.aex.queryOne("tasks", {where: {"status": "done"}});

count

count(entity: string, params?: {where?: any}, options ? ): Promise<{count: number}>

Query entity and return count of found objects.

Parameters

• entity - name of the collection or model;
• params - query params object. Seee details. Available params are:
  • where - (optional). object;
• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error;
  • cached - get from cache (if true) or make a request to the server (if false). If not specified then try to get data from cache and if nothing was found then make a request to the server.

Returns

Promise with count of found objects. For example: {count: 5}

Example

let count = await this.$a.aex.count("tasks", {where: {"status": "done"}});

save

save(entity: string, obj, options?): Promise

Create or update item. If obj has _id parameter then item will be updated. Otherwise new item will be created.

Parameters

• entity - name of the collection or model;
• obj - item to be saved;
• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with full data of created/saved object. undefined in case of error.

Example

let newItem = {name: "Buy milk", description: "Buy one bottle", status: "new"};
let item = await this.$a.aex.save("tasks", newItem);

delete

delete(entity: string, item, options?): Promise

Delete item.

Parameters

• entity - name of the collection or model;
• item - item to be deleted (actually only _id property in the item object is needed) or item's _id;
• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with { "status": "success"} or undefined in case of error.

Example

let res = await this.$a.aex.delete("tasks", "65a676d33c62ea0123456789");

clear

clear(entity: string, options?): Promise

Clear cache for the specified entity.

Parameters

• entity - name of the collection or model;
• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with { "status": "success"} or undefined in case of error.

Example

let res = await this.$a.aex.clear("tasks");

fetch

fetch(entity: string, options?): Promise

Fetch the entity to cache.

Parameters

• entity - name of the collection or model;
• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with { "status": "success"} or undefined in case of error.

Example

let res = await this.$a.aex.fetch("tasks");

lastSyncDate

lastSyncDate(entity: string, options?): Promise

Returns the last synchronization date for the specified entity.

Parameters

• entity - name of the collection or model;
• options - (optional). Available options are:
  • showError - (optional) show toast with error if error occurs (default is true);
  • message - (optional) message to be shown after success service execution;
  • errorMessage - (optional) message to be shown after error in service execution;
  • throwError - (optional) throw error if service execution ends with error.

Returns

Promise with last synchronization date or undefined in case of error.

Example

let lastSyncDate = await this.$a.aex.lastSyncDate("tasks");

load

load(entity: string, options): Promise

Load the specified items into the entity cache.

Parameters

• entity - name of the collection or model;
• options - Available options are:
  • data - array of item to load;
  • loadingStart - (optional) show loading on service execution start (default is false);
  • loadingEnd - (optional) hide loading on service execution end (default is false);
  • loading - (optional) boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - (optional) show toast with error if error occurs (default is true);
  • message - (optional) message to be shown after success service execution;
  • errorMessage - (optional) message to be shown after error in service execution;
  • throwError - (optional) throw error if service execution ends with error.

Returns

Promise with { "status": "success"} or undefined in case of error.

Example

let res = await this.$a.aex.load("tasks", {data: [
  {
    _id: "64268e560f0d3143a9a0f0c7",
    name: "Buy milk",
    _updatedAt: "2024-12-01T07:47:49.663Z"
  }
]});

fetchMulty

fetchMulty(entities: string[], options?): Promise

Fetch multiple entities to cache.

Parameters

• entities - array of names of collections or models;
• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with { "status": "success"} or undefined in case of error.

Example

let res = await this.$a.aex.fetchMulty(["tasks", "dreams"]);

isLoggedIn

isLoggedIn(): Promise

Check if user is logged in.

Returns

Promise with true if user is logged in otherwise returns false.

Example

let loggedIn = await this.$a.aex.isLoggedIn();

login

login(payload: {username: string, password: string} , options?): Promise

Login with provided credentials.

Parameters

• payload - user's credentials:
  • username - login;
  • password - password;
• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with user's data (_id, sessionToken). If login succeed then sessionToken will be automatically set to AppClient and credentials will be saved to storage for autoLogin.

Example

await this.$a.aex.login(
   {
     username: "Joe",
     password: "123"
   }
);

loginAnonymously

loginAnonymously(options?): Promise

Create temporary user and login with this user's credentials.

Login with provided credentials.

Parameters

• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with user's data (_id, sessionToken). If login succeed then sessionToken will be automatically set to AppClient and credentials will be saved to storage for autoLogin.

Example

await this.$a.aex.loginAnonymously();

logout

logout(options?): Promise

Logout user.

Parameters

• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with {status: 'success'}

Example

await this.$a.aex.logout();

userCreate

userCreate(data: {username: string, password: string}, options?): Promise

Update current user's data.

Parameters

• userData - object with user's data (username and password) to be created.

• options - (optional). Available options are:

  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with user's data (_id, sessionToken, username).

Example

await this.$a.aex.userCreate({  
  username: "[email protected]",
  password: "12345"
});

userGetData

userGetData(options?): Promise

Get current user's data.

Parameters

• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with the user's data (_id, username).

Example

let userData = await this.$a.aex.userGetData();

userUpdate

userUpdate(data: {username: string, password: string}, options?): Promise

Update current user's data.

Parameters

• userData - object with user's data (username and password) to be updated.
• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with the full user's data.

Example

await this.$a.aex.userUpdate({  
  username: "[email protected]",
  password: "12345"
});

userRemove

userRemove(options?): Promise

Remove current user.

Parameters

• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with {status: 'success'}

Example

await this.$a.aex.userRemove();

getSessionToken

getSessionToken(): Promise<string|undefined>

Get current Session Token.

Returns

Promise with current Session Token or undefined if Session Token was not set.

Example

let token = await this.$a.aex.getSessionToken();

setSessionToken

setSessionToken(data: {token: string}, options?): void

Set session token. If you login with login or userCreate then session token will be set automatically and there is no need to set session token with this method.

Example

await this.$a.aex.setSessionToken({token:"86a3f366-ec22-4006-9571-05b49965aef2"});

clearUserData

clearUserData(options?): Promise

Clear all deferred actions and cache.

Parameters

• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise.

Example

await this.$a.aex.clearUserData();

addListener

addListener(event: string, listener: Function): Promise

Add listener for the specified AppClient event.

Parameters

• event - name of the event. Available events are: statechange, init, auth.success, auth.failed, auth.logout
• listener - function to be invoked when specified event fires

Returns

Promise with undefined

Example

const func = (newState) => console.log(newState);
await this.$a.aex.addListener("statechange", func);

removeListener

removeListener(event: string, listener: Function): Promise

Remove listener for the specified AppClient event.

Parameters

• event - name of the event. Available events are: statechange, init, auth.success, auth.failed, auth.logout
• listener - function

Returns

Promise with undefined

Example

const func = (newState) => console.log(newState);
await this.$a.aex.addListener("statechange", func);
.........................
await this.$a.aex.removeListener("statechange", func);

goOnline

goOnline(options?): Promise

Set current state to online after goOffline.

Parameters

• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise.

Example

await this.$a.aex.goOnline();

goOffline

goOnline(options?): Promise

Emulate offline state.

Parameters

• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise.

Example

await this.$a.aex.goOffline();

retrySync

retrySync(options?): Promise<{status: string}>

Retry synchronization. Call it before getConflict to get full data from server (see httpErrorResponse property).

Parameters

• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with {status: 'failed'} or {status: 'success'}.

Example

await this.$a.aex.retrySync();

getConflict

getConflict(options?): Promise

Get next conflict.

Parameters

• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with object.

{
	status: "success"|undefined, // if "success" then no conflict was found
  content: {
  	data: {....}, // new data (after editing)
    revertedData: {....} // data before editing
  },
  httpErrorResponse: {
  	httpStatus: number,
    modifiedEntityNode: {....}, // current item data from server
    response: {....}, // server response
    responseHeaders: {....},// server response headers
    statusText: string
  },
  modelName: string, // Name of the current model
  operation: string // Current operation ("UPDATE", "CREATE", etc.)
}

Example

let conflict = await this.$a.aex.getConflict();

resolveConflict

resolveConflict(data?: {action?: string, data?: any}, options?): Promise

Get next conflict.

Parameters

• data - (optional):
  • action - string. One of "UPDATE", "UNDO", "DELETE"
  • data - new data (in case of UPDATE action). In case of UPDATE action set _updatedAt property of the new data to the current value from server (conflict.httpErrorResponse.modifiedEntityNode._updatedAt)
• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Returns

Promise with {status: 'failed'} or {status: 'success'}.

Example

await this.$a.aex.retrySync();
let conflict = await this.$a.aex.getConflict();
let newData = conflict.content.data;
newData._updatedAt = conflict.httpErrorResponse?.modifiedEntityNode?._updatedAt;
await this.$a.aex.resolveConflict({action: "UPDATE", data: newData}, {loading: true});

resetFailedSync

resetFailedSync(options?): Promise

Reset all deferred actions.

Parameters

• options - (optional). Available options are:
  • loadingStart - show loading on service execution start (default is false);
  • loadingEnd - hide loading on service execution end (default is false);
  • loading - boolean. Shortening for (loadingStart = true and loadingEnd = true);
  • showError - show toast with error if error occurs (default is true);
  • message - message to be shown after success service execution;
  • errorMessage - message to be shown after error in service execution;
  • throwError - throw error if service execution ends with error.

Example

await this.$a.aex.resetFailedSync()