Update to version 2.2.0

node-mysql-wrapper/node-mysql-wrapper.d.ts

@@ -17,12 +17,69 @@ declare module "node-mysql-wrapper" {
         [index: string]: T;
     }
 
-    class MysqlUtil {
+    class Helper {
+        /** 
+         * Callback like forEach
+         * @name valueCallback
+         * @function
+         * @param {T} the value of the object's key 
+         * @returnTye {U}
+         * @return {U}
+        */
+        
+        /**
+         * Callback like forEach
+         * @name keyCallback
+         * @function
+         * @param {string} the name of the object's key 
+         * @returnTye {U}
+         * @return {U}
+        */
+
         constructor();
+        
+        /**
+         * Create and return a copy of an object.
+         * @param {T} object the object you want to copy.
+         * @returnType {T}
+         * @return {T}
+         */
         static copyObject<T>(object: T): T;
+        
+        /**
+         * Converts any_string to anyString and returns it.
+         * @param {string} columnKey the string you want to convert.
+         * @returnType {string}
+         * @return {string}
+         */
         static toObjectProperty(columnKey: string): string;
+        
+        /**
+         * Converts anyString to any_string and returns it.
+         * @param {string} objectKey the string you want to convert.
+         * @returnType {string}
+         * @return {string}
+         */
         static toRowProperty(objectKey: string): string;
+        
+    
+        
+        /**
+         * Iterate object's keys and return their values to the callback.
+         * @param {Map<T>} map the object.
+         * @param {valueCallback}
+         * @returnType {U}
+         * @return {U}
+         */
         static forEachValue<T, U>(map: Map<T>, callback: (value: T) => U): U;
+
+        /**
+        * Iterate object's keys and return their names to the callback.
+        * @param {Map<T>} map the object.
+        * @param {keyCallback}
+        * @returnType {U}
+        * @return {U}
+        */
         static forEachKey<T, U>(map: Map<T>, callback: (key: string) => U): U;
     }
 
@@ -32,67 +89,364 @@ declare module "node-mysql-wrapper" {
         noDatabaseProperties: string[];
         whereClause: string;
     }
-	
+
     class Criteria implements ICriteria {
+        
+        /**
+         * The raw format of the criteria eg: {yearsOld:22}.
+         */
         rawCriteriaObject: any;
+        
+        /**
+         * Which tables to search after the find method of the proto table finish.
+         */
         tables: string[];
+        
+        /**
+         * The properties of the criteria which don't belong to the database's table.
+         */
         noDatabaseProperties: string[];
+        
+        /**
+         * The converted/exported where clause. 
+         */
         whereClause: string;
+
         constructor(rawCriteriaObject: any, tables: string[], noDatabaseProperties: string[], whereClause: string);
     }
-	
+
     class CriteriaBuilder<T> {
         private _table;
-        constructor(table: MysqlTable<T>);
+        constructor(table: Table<T>);
+        
+        /**
+         * Builds the criteria raw object to Criteria object.
+         * @param {any} rawCriteriaObject the criteria at raw format you pass eg: {yearsOld:18}.
+         * @returnType {Criteria}
+         * @return {Criteria}
+         */
         build(rawCriteriaObject: any): Criteria;
     }
 
+    class SelectQueryRules {
+        orderByClause: string;
+        groupByClause: string;
+        limitClause: string;
 
-    class MysqlConnection extends EventEmitter {
-        connection: Mysql.IConnection;
-        eventTypes: string[];
-        tableNamesToUseOnly: any[];
-        tables: MysqlTable<any>[];
-        constructor(connection: string | Mysql.IConnection);
-        create(connection: string | Mysql.IConnection): void;
-        attach(connection: Mysql.IConnection): void;
-        end(callback?: (error: any) => void): void;
-        destroy(): void;
-        link(readyCallback?: () => void): Promise<void>;
-        useOnly(...tables: any[]): void;
-        fetchDatabaseInfornation(): Promise<void>;
-        escape(val: string): string;
-        notice(tableWhichCalled: string, queryStr: string, parsedResults: any[]): void;
-        watch(tableName: string, evtType: any, callback: (parsedResults: any[]) => void): void;
-        unwatch(tableName: string, evtType: string, callbackToRemove: (parsedResults: any[]) => void): void;
-        query(queryStr: string, callback: (err: Mysql.IError, results: any) => any, queryArguments?: any[]): void;
-        table<T>(tableName: string): MysqlTable<T>;
+
+        static build(): SelectQueryRules;
+        static build(parentRule?: SelectQueryRules): SelectQueryRules;
+
+        orderBy(columnKey: string, descending?: boolean): SelectQueryRules;
+
+        groupBy(columnKey: string): SelectQueryRules;
+
+        limit(limitRowsOrStart: number, limitEnd?: number): SelectQueryRules;
+
+        clearOrderBy(): SelectQueryRules;
+
+        clearGroupBy(): SelectQueryRules;
+
+        clearLimit(): SelectQueryRules;
+
+        clear(): SelectQueryRules;
+
+        from(parentRule: SelectQueryRules): SelectQueryRules;
+
+        toString(): string;
     }
-	
-    class MysqlTable<T> {
+
+    class SelectQuery<T> {
+
+        private _rules: SelectQueryRules;
+        private _table: Table<T>;
+        private _criteriaRawJsObject: any;
+        private _callback: (_results: T[]) => any;
+        private callback: (resolve?: (thenableOrResult?: T | Promise.Thenable<T>) => void, reject?: (error?: any) => void) => void;
+
+        constructor(table: Table<T>, criteriaRawJsObject: any, callback?: (_results: T[]) => any);
+
+        orderBy(columnKey: string, descending?: boolean): SelectQuery<T>;
+
+        groupBy(columnKey: string): SelectQuery<T>;
+
+        limit(limitRowsOrStart: number, limitEnd?: number): SelectQuery<T>;
+
+        /**
+        * Executes the select and returns the Promise.
+        */
+        promise(): Promise<T[]>;
+        
+        /**
+         * Exactly the same thing as promise().
+         * Executes the select and returns the Promise.
+         */
+        execute(): Promise<T[]>;
+
+        then(onFulfill: (value: any[]) => any|Promise.Thenable<any>): Promise<any>;
+        then<U>(onFulfill: (value: T[]) => U|Promise.Thenable<U>, onReject: (error: any) => Promise.Thenable<U>, onProgress?: (note: any) => any): Promise<U>;
+        then<U>(onFulfill: (value: T[]) => U|Promise.Thenable<U>, onReject?: (error: any) => U, onProgress?: (note: any) => any): Promise<U>;
+
+    }
+
+    class Connection extends EventEmitter {
+        
+        /**
+         * The real database connection socket.
+         */
+        connection: Mysql.IConnection;
+        
+        /**
+         * Collection of the supported event types for the tables.
+         */
+        eventTypes: string[];
+        
+        /**
+         * Force to fetch ONLY these Database table names {array of string}.  
+         */
+        tableNamesToUseOnly: any[];
+        
+        /**
+         * All tables {MysqlTable} inside this connection's database.
+         */
+        tables: Table<any>[];
+
+        constructor(connection: string | Mysql.IConnection);
+        
+        /**
+         * Creates the MysqlConnection from the connection url or the real connection object.
+         * @param {string | Mysql.IConnection} connection the connection url or the real connection object.
+         * @returnType {nothing}
+         * @return {nothing}
+         */
+        create(connection: string | Mysql.IConnection): void;
+        
+        /**
+         * Attach a real connection.
+         * @param {Mysql.IConnection} connection the real connection object.
+         * @returnType {nothing}
+         * @return {nothing} 
+         */
+        attach(connection: Mysql.IConnection): void;
+        
+        /**
+         * Close the entire real connection and remove all event's listeners (if exist).
+         * @param {function} callback If error occurs when closing the connection, this callback has the responsibility to catch it.
+         * @returnType {nothing}
+         * @return {nothing} 
+         */
+        end(callback?: (error: any) => void): void;
+        
+        /**
+         * Close the entire real connection and remove all event's listeners (if exist).
+         * the difference from the 'end' is that this method doesn't care about errors so no callback passing here. 
+         */
+        destroy(): void;
+        
+        /**
+         * Link the real connection with this MysqlConnection object.
+         * @param {function} readyCallback when the link operation is done this callback is executed.
+         * @returnType {Promise}
+         * @return {Promise}
+         */
+        link(readyCallback?: () => void): Promise<void>;
+        
+        /**
+         * Force to use/fetch information from only certain of database's tables, otherwise all database's tables information will be fetched.
+         * @param {Array} tables the array of the tables  {string}
+         * @returnType {nothing}
+         * @return {nothing}
+         */
+        useOnly(...tables: any[]): void;
+        
+        /**
+         * This method has the resposibility of fetching the correct tables from the database ( table = columns' names, primary key name).
+         * @returnType {Promise}
+         * @return {Promise}
+         */
+        fetchDatabaseInfornation(): Promise<void>;
+        
+        /**
+         * Escape the query column's value  and return it.
+         * @param {string} val the value which will be escaped. 
+         * @returnType {string}
+         * @return {string}
+         */
+        escape(val: string): string;
+        
+        /**
+         * Call when must notify the Database events, SAVE(INSERT,UPDATE), REMOVE(DELETE).
+         * @param {string} tableWhichCalled the table name which event is coming from.
+         * @param {string} queryStr the full parsed query string which used to determinate the type of event to notify.
+         * @param {any[]} parsedResults the parsed results (results after a method parse/edit/export them as objects), these are passing to the watch listener(s).
+         * @returnType {nothing}
+         * @return {nothing}
+         */
+        notice(tableWhichCalled: string, queryStr: string, parsedResults: any[]): void;
+        
+        /**
+         * Adds an event listener/watcher on a table for a 'database event'.
+         * @param {string} tableName the table name which you want to add the event listener.
+         * @param {string or string[]} evtType the event(s) type you want to watch, one of these(string) or an array of them(string[]): ["INSERT", "UPDATE", "REMOVE", "SAVE"].
+         * @param {function} callback Callback which has one parameter(typeof any[]) which filled by the parsedResults (results after query executed and exports to object(s)). 
+         * @returnType {nothing}
+         * @return {nothing}
+         */
+        watch(tableName: string, evtType: any, callback: (parsedResults: any[]) => void): void;
+        
+        /**
+         * Removes an event listener/watcher from a table for a specific event type.
+         * @param {string} tableName the table name which you want to remove the event listener. 
+         * @param {string} evtType the Event type you want to remove, one of these: "INSERT", "UPDATE", "REMOVE", "SAVE".
+         * @param {function} callbackToRemove the callback that you were used for watch this event type.
+         * @returnType {nothing}
+         * @return {nothing}
+         */
+        unwatch(tableName: string, evtType: string, callbackToRemove: (parsedResults: any[]) => void): void;
+        
+        /**
+         * Executes a database query.
+         * @param {string} queryStr the query text/string to be executed.
+         * @param {function} callback the function will be called and fill the one and only parameter when an errors occurs.
+         * @param {any[]} queryArguments (optional) the query arguments you want to pass into query. ['arg1','arg2']...
+         * @returnType {nothing}
+         * @return {nothing} 
+         */
+        query(queryStr: string, callback: (err: Mysql.IError, results: any) => any, queryArguments?: any[]): void;
+        
+        /**
+         * Returns a MysqlTable object from the database factory. (Note: this method doesn't create anything, just finds and returns the correct table, you don't have to create anything at all. Tables are fetched by the library itself.)
+         * If you are using typescript you can pass a class (generic<T>) in order to use the auto completion assistance on table's results methods(find,findById,findAll,save,remove,safeRemove). 
+         * @param {string} tableName the table name which you want to get, on the form of: 'anyDatabaseTable' OR 'any_database_table' (possible your real table name into your database).
+         * @returnType {MysqlTable}
+         * @return {MysqlTable}
+         */
+        table<T>(tableName: string): Table<T>;
+    }
+
+    class Table<T> {
         private _name;
         private _connection;
         private _columns;
         private _primaryKey;
         private _criteriaBuilder;
-        constructor(tableName: string, connection: MysqlConnection);
+        private _rules;
+        constructor(tableName: string, connection: Connection);
+        
+        /**
+         * An array of all columns' names inside this table.
+         */
         columns: string[];
+        
+        /**
+         * The name of the primary key column which this table is using.
+         */
         primaryKey: string;
-        connection: MysqlConnection;
+        
+        /**
+         * The MysqlConnection object which this MysqlTable belongs. 
+         */
+        connection: Connection;
+        
+        /**
+         * The real database name of the table. Autofilled by library. 
+         */
         name: string;
+        
+        /**
+         * Set of the query rules that will be applied after the 'where clause' on each select query executed by this table. 
+         */
+        rules: SelectQueryRules;
+        
+        /**
+        * Adds or turn on an event listener/watcher on a table for a 'database event'.
+        * @param {string} evtType the event type you want to watch, one of these: ["INSERT", "UPDATE", "REMOVE", "SAVE"].
+        * @param {function} callback Callback which has one parameter(typeof any[]) which filled by the parsedResults (results after query executed and exports to object(s)). 
+        * @returnType {nothing}
+        * @return {nothing}
+        */
         on(evtType: string, callback: (parsedResults: any[]) => void): void;
+            
+        /**
+         * Removes or turn off an event listener/watcher from a table for a specific event type.
+         * @param {string} evtType the Event type you want to remove, one of these: "INSERT", "UPDATE", "REMOVE", "SAVE".
+         * @param {function} callbackToRemove the callback that you were used for watch this event type.
+         * @returnType {nothing}
+         * @return {nothing}
+         */
         off(evtType: string, callbackToRemove: (parsedResults: any[]) => void): void;
+        
+        /**
+         * Use it when you want to check if extended function is exists here.
+         * @param {string} extendedFunctionName the name of the function you want to check.
+         * @returnType {boolean}
+         * @return {boolean}
+         */
         has(extendedFunctionName: string): boolean;
+        
+        /**
+         * Extends this table's capabilities with a function.
+         * @param {string} functionName the function name you want to use, this is used when you want to call this function later.
+         * @param {function} theFunction the function with any optional parameters you want to pass along.
+         * @returnType {nothing}
+         * @return {nothing} 
+         */
         extend(functionName: string, theFunction: (...args: any[]) => any): void;
+        
+        /**
+         * Converts and returns an object from this form: { a_property:'dsda', other_property:something, any_property_name:true } to { aProperty:..., otherProperty...,anyPropertyName...}
+         * @param {any} row the raw row object.
+         * @returnType {any}
+         * @return {any}
+         */
         objectFromRow(row: any): any;
+           
+        /**
+         * Converts and returns an object from this form: { aProperty:'dsda', otherProperty:something, anyPropertyName:true } to { a_property:..., other_property...,any_property_name...}
+         * @param {any} row the raw row object.
+         * @returnType {any}
+         * @return {any}
+         */
         rowFromObject(obj: any): any;
+        
+        /**
+         * Returns and array of [columns[],values[]]
+         * @param {any} jsObject the raw row object.
+         * @returnType {array}
+         * @return {array}
+         */
         getRowAsArray(jsObject: any): Array<any>;
+        
+        /**
+         * Returns the primary key's value from an object.
+         * @param {any} jsObject the object which you want to find and return the value of the primary key.
+         * @returnType {number | string}
+         * @return {number | string}
+         */
         getPrimaryKeyValue(jsObject: any): number | string;
+
         parseQueryResult(result: any, criteria: ICriteria): Promise<any>;
-        find(criteriaRawJsObject: any, callback?: (_results: T[]) => any): Promise<T[]>;
+        
+        /**
+         * 
+         */
+        find(criteriaRawJsObject: any): SelectQuery<T>; // only criteria 
+        find(criteriaRawJsObject: any, callback: ((_results: T[]) => any)): SelectQuery<T>; // criteria and callback
+        find(criteriaRawJsObject: any, callback?: (_results: T[]) => any): SelectQuery<T>;
+
+        findById(id: number|string): Promise<T>; // without callback
         findById(id: number | string, callback?: (result: T) => any): Promise<T>;
-        findAll(callback?: (_results: T[]) => any): Promise<T[]>;
+
+        findAll(): SelectQuery<T>; // without callback
+        findAll(callback?: (_results: T[]) => any): SelectQuery<T>;
+
+        save(criteriaRawJsObject: any): Promise<any>; //without callback
         save(criteriaRawJsObject: any, callback?: (_result: any) => any): Promise<any>;
+
+        safeRemove(id: number | string): Promise<{
+            affectedRows: number;
+            table: string;
+        }>; //withoutcallback
         safeRemove(id: number | string, callback?: (_result: {
             affectedRows: number;
             table: string;
@@ -100,6 +454,11 @@ declare module "node-mysql-wrapper" {
             affectedRows: number;
             table: string;
         }>;
+
+        remove(criteriaRawObject: any): Promise<{
+            affectedRows: number;
+            table: string;
+        }>; // without callback
         remove(criteriaRawJsObject: any, callback?: (_result: {
             affectedRows: number;
             table: string;
@@ -109,23 +468,47 @@ declare module "node-mysql-wrapper" {
         }>;
     }
 
-    class MysqlWrapper {
-        connection: MysqlConnection;
+    class Wrapper {
+        connection: Connection;
         readyListenerCallbacks: Function[];
-        constructor(connection?: MysqlConnection);
+        constructor(connection?: Connection);
         static when(..._promises: Promise<any>[]): Promise<any>;
-        setConnection(connection: MysqlConnection): void;
+        setConnection(connection: Connection): void;
+            
+        /**
+         * Force to use/fetch information from only certain of database's tables, otherwise all database's tables information will be fetched.
+         * @param {Array} tables the array of the tables  {string}
+         * @returnType {nothing}
+         * @return {nothing}
+         */
         useOnly(...useTables: any[]): void;
+
         has(tableName: string, functionName?: string): boolean;
         ready(callback: () => void): void;
-        table<T>(tableName: string): MysqlTable<T>;
+        table<T>(tableName: string): Table<T>;
         noticeReady(): void;
         removeReadyListener(callback: () => void): void;
         query(queryStr: string, callback: (err: Mysql.IError, results: any) => any, queryArguments?: any[]): void;
+        
+        /**
+        * Close the entire real connection and remove all event's listeners (if exist).
+        * the difference from the 'end' is that this method doesn't care about errors so no callback passing here. 
+        */
         destroy(): void;
+        
+        /**
+       * Close the entire real connection and remove all event's listeners (if exist).
+       * @param {function} maybeAcallbackError If error occurs when closing the connection, this callback has the responsibility to catch it.
+       * @returnType {nothing}
+       * @return {nothing} 
+       */
         end(maybeAcallbackError: (err: any) => void): void;
+
+        newTableRules(tableName: string): SelectQueryRules;
+
+        buildRules(): SelectQueryRules;
+        buildRules(parentRules?: SelectQueryRules): SelectQueryRules;
     }
 
-    function wrap(mysqlUrlOrObjectOrMysqlAlreadyConnection: Mysql.IConnection | string, ...useTables: any[]): MysqlWrapper;
-
+    function wrap(mysqlUrlOrObjectOrMysqlAlreadyConnection: Mysql.IConnection | string, ...useTables: any[]): Wrapper;
 }