readme and comments

Author: ppaska

README.md

@@ -1,14 +1,135 @@
 # sql-data-api-client-js
 SQL Data Api client for Javascript
 
-### Usage
+## Install
 
 > npm install sql-data-api
 
+## Set base URL
+
+```js
+import { setBaseUrl } from 'sql-data-api';
+
+// ...
+
+setBaseUrl('https://api.worksheet.systems');
+
+```
+
+## Authentication
+
+There are two types of authentication.
+
+1. you can set user name and password (use your Worksheet Systems account)
+
 ```js
+import { authenticate } from 'sql-data-api';
+
+await authenticate("testUser", "1111111")
+
+```
+
+2. Use `Api Access Token` generated https://app.worksheet.systems/account/settings/info
+
+```js
+import { setUserAccessToken } from 'sql-data-api';
+
+setUserAccessToken('$ACCESS_TOKEN')
+```
+
+## Query Data
+
+```js
+
+// returns table as array of items
+query(tableOrViewName: string, fieldsOrQuery?: string | SqlReadQueryInfo, queryInfoSettings?: SqlReadQueryInfo): Promise<ScalarObject[]>;
+
+// Query specification
+export interface SqlReadQueryInfo {
+    fields?: string;
+    filter?: string;
+    filterParams?: Record<string, ScalarType>;
+    skip?: number;
+    top?: number;
+    orderBy?: string;
+    mainTableAlias?: string;
+    joins?: [JoinType, string, string][];
+}
+
+```
+### Query Usage
+
+#### A simple queries
+
+```js
+import { sqlDataApi } from 'sql-data-api';
+
+// returns all rows from the table
+const allRows = await sqlDataApi('connectionName')
+    .query('someTableOrViewName');
+
+// returns two fields for all rows
+const allRowsAndJustTwoFieds = await sqlDataApi('connectionName')
+    .query('someTableOrViewName', 'Field1, Field2');
+
+// returns two fields for UK
+const allRowsAndJustTwoFieds = await sqlDataApi('connectionName')
+    .query('someTableOrViewName', {
+        fields: "F1, f2", 
+        filter: "Country = @country",
+        filterParams: {country: 'UK'},
+        top: 1000,
+        orderBy: "F2 DESC",
+    });
+
+```
+
+#### SQL Functions
+
+SQL Functions can be used in `fields` and `filter` properties
+
+```js
+
+const itwms = await sqlDataApi('connectionName')
+    .query('someTableOrViewName', {
+        fields: 'cast(DateTimeField as Date) SomeDate, concat(FirstName, '-', LastName") FullName',
+        filter: "concat(FirstName, '-', LastName) = @fullName",
+        filterParams: {fullName: 'Adam Smith'}
+    });
+
+```
+#### Aggregated query
+
+Add `groupBy|` prefix to the field and use aggregation functions e.g: sum, avg, count ...
+
+```js
+
+const aggData = await sqlDataApi('connectionName')
+    .query('someTableOrViewName', {
+        fields: 'groupBy|country, sum(revenue) revenue'
+    });
+
+```
+
+
+## Save a array of items 
+
+```js
+save(tableName: string, items: ScalarObject[], itemsToDeleteOrSaveOptions?: Record<string, unknown>[] | SqlSaveOptions, saveOptions?: SqlSaveOptions): Promise<SqlSaveStatus>;
+
+export interface SqlSaveOptions {
+    method: "Merge" | "Append" | "BulkInsert";
+    batchSize?: number;
+    primaryKeys?: string[];
+    batchProgressFunc?: (processedCount: number, status: SqlSaveStatus) => void;
+}
+
+saveWithAutoId(tableName: string, item: ScalarObject): Promise<number>;
+
+sqlExecute(sql: string, params?: ScalarObject): Promise<ScalarObject[] | unknown>;
 
 ```
 
-### License
+## License
 
 A permissive MIT License (c) FalconSoft Ltd.

src/sql-data.api.ts

@@ -16,27 +16,105 @@ const appHttpHeaders = {
   "Content-Type": "application/json",
 };
 
+/**
+ * Interface that represents a SQL save result
+ */
 export interface SqlSaveStatus {
+  /**
+   * Number of inserted row
+   */
   inserted: number;
+
+  /**
+   * Number of updated row
+   */
   updated: number;
+
+  /**
+   * Number of deleted row
+   */
   deleted: number;
 }
 
+/**
+ * Sql Query configuration
+ */
 export interface SqlReadQueryInfo {
+  /**
+   * A list of comma separated fields to select.
+   * Examples:
+   *  - 'Field1, Field2'
+   *  - 't.Field1, t.Field2' - where t is an alias
+   *  - 'concat(FirstName, ' ', LastName) FullName, AnotherField' - you can use SQL functions
+   *  - 'groupBy|Country, sum(profit) Profit' - aggregated query.
+   */
   fields?: string;
+
+  /**
+   * A filter expression. Where you can use SQL functions, aliases and parameters
+   * Examples:
+   *  - "Country = 'UK'"
+   *  - "Country = @country AND City = @city"
+   *  - "concat(t.FirstName, ' ', t.LastName) = @fullName"
+   */
   filter?: string;
+
+  /**
+   * A filter parameters used in an expresiion
+   * e.g: {country: 'UK', fullName: 'Adam Smith'}
+   */
   filterParams?: Record<string, ScalarType>;
+
+  /**
+   * Number of rows to skip
+   */
   skip?: number;
+
+  /**
+   * top rows to take
+   */
   top?: number;
+
+  /**
+   * Define a sortings fields
+   */
   orderBy?: string;
+
+  /**
+   * Alias for main table. But default it is undefined
+   */
   mainTableAlias?: string;
+
+  /**
+   * joins tables together
+   * Examples:
+   *  - ['InnerJoin', 'Customers c', 't.CustomerId = c.CustomerID'] - inner joins mainTable to Cutomers table
+   */
   joins?: [JoinType, string, string][];
 }
 
+/**
+ * Sql Save operation config
+ */
 export interface SqlSaveOptions {
+  /**
+   * save types
+   */
   method: "Merge" | "Append" | "BulkInsert";
+
+  /**
+   * a batch size for optimization point
+   */
   batchSize?: number;
+  /**
+   * Define a primary key that should be used. Normally primary keys are taken from the table,
+   * Use this property only if you want to upsert (merge) data on some other fields 
+   */
   primaryKeys?: string[];
+
+  /**
+   * Report progress on batch saving
+   */
   batchProgressFunc?: (processedCount: number, status: SqlSaveStatus) => void;
 }