@saltcorn/data 0.8.9 → 0.9.0-beta.1

package/dist/models/table.d.ts

@@ -7,24 +7,114 @@ import type TableConstraint from "./table_constraints";
 import type { AbstractTag } from "@saltcorn/types/model-abstracts/abstract_tag";
 import type { JoinFieldOption, RelationOption } from "@saltcorn/types/base_types";
 /**
- * Table class
+ * A class representing database tables and their properties.
+ *
+ * Use this to create or delete tables and their properties, or to query
+ * or change table rows.
+ *
+ * To query, update, insert or delete rows in an existing table, first you
+ * should find the table object with {@link Table.findOne}.
+ *
+ * @example
+ * ```
+ * Table.findOne({name: "Customers"}) // find the table with name "Customers"
+ * Table.findOne("Customers") // find the table with name "Customers" (shortcut)
+ * Table.findOne({ id: 5 }) // find the table with id=5
+ * Table.findOne(5) // find the table with id=5 (shortcut)
+ * ```
+ *
+ * Table.findOne is synchronous (no need to await), But the functions that
+ * query and manipulate (such as {@link Table.insertRow}, {@link Table.getRows},
+ * {@link Table.updateRow}, {@link Table.deleteRows}) rows are mostly asyncronous,
+ * so you can put the await in front of the
+ * whole expression
+ *
+ * @example
+ * To count the number of rows in the customer table
+ * ```
+ * const nrows = await Table.findOne("Customers").countRows()
+ * ```
+ *
+ * For further examples, see the [Table test suite](https://github.com/saltcorn/saltcorn/blob/master/packages/saltcorn-data/tests/table.test.ts)
+ *
+ * ## Querying table rows
+ *
+ * There are several methods you can use to retrieve rows in the database:
+ *
+ * * {@link Table.countRows} To count the number of rows, optionally matching a criterion
+ * * {@link Table.getRows} To retrieve multiple rows matching a criterion
+ * * {@link Table.getRow} To retrieve a single row matching a criterion
+ * * {@link Table.getJoinedRows} To retrieve rows together with joinfields and aggregations
+ *
+ * These functions all take `Where` expressions which are JavaScript objects describing
+ * the criterion to match to. Some examples:
+ *
+ * * `{ name: "Jim" }`: Match all rows with name="Jim"
+ * * `{ name: { ilike: "im"} }`: Match all rows where name contains "im" (case insensitive)
+ * * `{ age: { lt: 18 } }`: Match all rows with age<18
+ * * `{ age: { lt: 18, equal: true } }`: Match all rows with age<=18
+ * * `{ age: { gt: 18, lt: 65} }`: Match all rows with 18<age<65
+ * * `{ name: { or: ["Harry", "Sally"] } }`: Match all rows with name="Harry" or "Sally"
+ * * `{ or: [{ name: "Joe"}, { age: 37 }] }`: Match all rows with name="Joe" or age=37
+ * * `{ not: { id: 5 } }`: All rows except id=5
+ *
+ * For further examples, see the [mkWhere test suite](https://github.com/saltcorn/saltcorn/blob/master/packages/db-common/internal.test.js)
+ *
+ * ## Updating a Row
+ *
+ * There are two nearly identical functions for updating rows depending on how you want
+ * failures treated
+ *
+ * * {@link Table.updateRow} Update a row, throws an exception if update is invalid
+ * * {@link Table.tryUpdateRow} Update a row, return an error message if update is invalid
+ *
+ * ## Inserting a new Row
+ *
+ * There are two nearly identical functions for inserting a new row depending on how you want
+ * failures treated
+ *
+ * * {@link Table.insertRow} insert a row, throws an exception if it is invalid
+ * * {@link Table.tryInsertRow} insert a row, return an error message if it is invalid
+ *
+ * ## Deleting rows
+ *
+ * Use {@link Table.deleteRows} to delete any number (zero, one or many) of rows matching a criterion. It uses
+ * the same `where` expression as the functions for querying rows
+ *
+ *
  * @category saltcorn-data
  */
 declare class Table implements AbstractTable {
+    /** The table name */
     name: string;
+    /** The table ID */
     id?: number;
+    /** Minimum role to read */
     min_role_read: number;
+    /** Minimum role to write */
     min_role_write: number;
+    /** The ID of the ownership field*/
     ownership_field_id?: string;
+    /** A formula to denote ownership. This is a JavaScript expression which
+     * must evaluate to true if the user is the owner*/
     ownership_formula?: string;
+    /** Version history enabled for this table */
     versioned: boolean;
+    /** Whether sync info for mobile apps is enabled for this table */
     has_sync_info: boolean;
+    /** If true this is an external table (not a database table) */
     external: boolean;
+    /** A description of the purpose of the table */
     description?: string;
+    /** An array of {@link Field}s in this table */
     fields: Field[];
+    /** An array of {@link TableConstraint}s for this table */
     constraints: TableConstraint[];
+    /** Is this a user group? If yes it will appear as options in the ownership dropdown */
     is_user_group: boolean;
+    /** Name of the table provider for this table (not a database table) */
     provider_name?: string;
+    /** Configuration for the table provider for this table */
     provider_cfg?: any;
     /**
      * Table constructor
@@ -121,10 +211,8 @@ declare class Table implements AbstractTable {
      * @param user
      * @param forRead
      */
-    updateWhereWithOwnership(where: Where, fields: Field[], user?: Row, forRead?: boolean): {
-        notAuthorized?: boolean;
-    } | undefined;
-    addDeleteSyncInfo(ids: Row[], timestamp: Date): Promise<void>;
+    private updateWhereWithOwnership;
+    private addDeleteSyncInfo;
     /**
      * Delete rows from table
      * @param where - condition
@@ -137,7 +225,7 @@ declare class Table implements AbstractTable {
      * @param row
      * @returns {*}
      */
-    readFromDB(row: Row): any;
+    private readFromDB;
     /**
      * Get one row from table in db
      * @param where
@@ -168,7 +256,7 @@ declare class Table implements AbstractTable {
     /**
      *
      */
-    storedExpressionJoinFields(): {};
+    private storedExpressionJoinFields;
     /**
      * Update row
      * @param v_in - columns with values to update
@@ -181,8 +269,8 @@ declare class Table implements AbstractTable {
     updateRow(v_in: any, id: number, user?: Row, noTrigger?: boolean, resultCollector?: object, restore_of_version?: any, syncTimestamp?: Date): Promise<string | void>;
     latestSyncInfo(id: number): Promise<any>;
     latestSyncInfos(ids: number[]): Promise<any>;
-    insertSyncInfo(id: number, syncTimestamp?: Date): Promise<void>;
-    updateSyncInfo(id: number, oldLastModified: Date, syncTimestamp?: Date): Promise<void>;
+    private insertSyncInfo;
+    private updateSyncInfo;
     /**
      * Try to Update row
      * @param v
@@ -200,12 +288,14 @@ declare class Table implements AbstractTable {
      */
     toggleBool(id: any, field_name: string, user?: Row): Promise<void>;
     /**
-     * Get primary key field
+     * Get primary key field name
      * @type {string}
      */
     get pk_name(): string;
     /**
-     * Check table constraints
+     * Check table constraints against a row object. Will return a string With an error message if the
+     * table constraints are violated, `undefined` if the row does not violate any constraints
+     *
      * @param row
      */
     check_table_constraints(row0: Row): string | undefined;
@@ -214,11 +304,25 @@ declare class Table implements AbstractTable {
      * @param row
      * @param user
      */
-    check_field_write_role(row: Row, user: Row): string | undefined;
+    private check_field_write_role;
     /**
-     * Insert row
+     * Insert row into the table. By passing in the user as
+     * the second argument, tt will check write rights. If a user object is not
+     * supplied, the insert goes ahead without checking write permissions.
+     *
+     * Returns the primary key value of the inserted row.
+     *
+     * This will throw an exception if the row
+     * does not conform to the table constraints. If you would like to insert a row
+     * with a function that can return an error message, use {@link Table.tryInsertRow} instead.
+     *
+     * @example
+     * ```
+     * await Table.findOne("People").insertRow({ name: "Jim", age: 35 })
+     * ```
+     *
      * @param v_in
-     * @param _userid
+     * @param user
      * @param resultCollector
      * @returns {Promise<*>}
      */
@@ -239,7 +343,7 @@ declare class Table implements AbstractTable {
      *
      * @param msg
      */
-    normalise_error_message(msg: string): string;
+    private normalise_error_message;
     /**
      * Get Fields list for table
      * @returns {Promise<Field[]>}
@@ -259,9 +363,9 @@ declare class Table implements AbstractTable {
      * Create history table
      * @returns {Promise<void>}
      */
-    create_history_table(): Promise<void>;
-    create_sync_info_table(): Promise<void>;
-    drop_sync_table(): Promise<void>;
+    private create_history_table;
+    private create_sync_info_table;
+    private drop_sync_table;
     /**
      * Restore Row Version
      * @param id
@@ -285,7 +389,7 @@ declare class Table implements AbstractTable {
      * Drop history table
      * @returns {Promise<void>}
      */
-    drop_history_table(): Promise<void>;
+    private drop_history_table;
     /**
      * Rename table
      * @param new_name
@@ -383,6 +487,38 @@ declare class Table implements AbstractTable {
      */
     getJoinedRow(opts?: (JoinOptions & ForUserRequest) | any): Promise<Row | null>;
     /**
+     * Get rows along with joined and aggregated fields. The argument to `getJoinedRows` is an object
+     * with several different possible fields, all of which are optional
+     *
+     * * `where`: A Where expression indicating the criterion to match
+     * * `joinFields`: An object with the joinfields to retrieve
+     * * `aggregations`: An object with the aggregations to retrieve
+     * * `orderBy`: A string with the name of the field to order by
+     * * `orderDesc`: If true, descending order
+     * * `limit`: A number with the maximum number of rows to retrieve
+     * * `offset`: The number of rows to skip in the result before returning rows
+     *
+     * @example
+     * ```
+     * const patients = Table.findOne({ name: "patients" });
+     * const patients_rows = await patients.getJoinedRows({
+     *      where: { age: { gt: 65 } },
+     *      orderBy: "id",
+     *      aggregations: {
+     *        avg_temp: {
+     *          table: "readings",
+     *          ref: "patient_id",
+     *          field: "temperature",
+     *          aggregate: "avg",
+     *       },
+     *      },
+     *      joinFields: {
+     *        pages: { ref: "favbook", target: "pages" },
+     *        author: { ref: "favbook", target: "author" },
+     *      },
+     * });
+     * ```
+     *
      * @param {object} [opts = {}]
      * @returns {Promise<object[]>}
      */
@@ -411,6 +547,7 @@ declare class Table implements AbstractTable {
      *
      */
     getForeignTables(): Promise<Array<AbstractTable>>;
+    getFormulaExamples(typename: string): string[];
 }
 declare namespace Table {
     type ParentRelations = {

package/dist/models/table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../models/table.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../models/table.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,KAAK,EACL,aAAa,EACb,GAAG,EAEH,WAAW,EAEZ,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,MAAM,SAAS,CAAC;AAC5B,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EACR,SAAS,EACV,MAAM,gDAAgD,CAAC;AAExD,OAAO,KAAK,EACV,cAAc,EAEf,MAAM,+CAA+C,CAAC;AAEvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAmBlE,OAAO,KAAK,eAAe,MAAM,qBAAqB,CAAC;AA0BvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8CAA8C,CAAC;AAChF,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACf,MAAM,4BAA4B,CAAC;AAwCpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,cAAM,KAAM,YAAW,aAAa;IAClC,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IAEb,mBAAmB;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,2BAA2B;IAC3B,aAAa,EAAE,MAAM,CAAC;IAEtB,4BAA4B;IAC5B,cAAc,EAAE,MAAM,CAAC;IAEvB,mCAAmC;IACnC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;uDACmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IAEnB,kEAAkE;IAClE,aAAa,EAAE,OAAO,CAAC;IAEvB,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;IAElB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,+CAA+C;IAC/C,MAAM,EAAE,KAAK,EAAE,CAAC;IAEhB,0DAA0D;IAC1D,WAAW,EAAE,eAAe,EAAE,CAAC;IAE/B,uFAAuF;IACvF,aAAa,EAAE,OAAO,CAAC;IAEvB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,GAAG,CAAC;IACnB;;;OAGG;gBACS,CAAC,EAAE,QAAQ;IAmBvB,iBAAiB;IAyBjB;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,IAAI;IA+BlD;;;;;OAKG;WACU,IAAI,CACf,KAAK,CAAC,EAAE,KAAK,EACb,UAAU,GAAE,aAAiD,GAC5D,OAAO,CAAC,KAAK,EAAE,CAAC;IA6CnB;;;;;OAKG;WACU,kBAAkB,CAC7B,MAAM,GAAE,KAAU,EAClB,UAAU,GAAE,aAAiD,GAC5D,OAAO,CAAC,KAAK,EAAE,CAAC;IA8BnB;;;;OAIG;IACG,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG;IAO3B;;;;OAIG;IACH,2BAA2B,CACzB,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,IAAI,GACtB,MAAM,GAAG,IAAI,GAAG,SAAS;IAM5B;;;OAGG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI,GAAG,SAAS;IAM5C;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO;IAgBtC;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IA4HtE;;OAEG;IACH,IAAI,aAAa,WAEhB;IACD;;;;;;OAMG;WACU,MAAM,CACjB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,aAAa,GAAG,SAAc,EAAE,wBAAwB;IACjE,EAAE,CAAC,EAAE,MAAM,GACV,OAAO,CAAC,KAAK,CAAC;IAkEjB;;;;OAIG;IAEG,MAAM,CAAC,WAAW,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCzD;;;OAGG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;OAEG;IACG,aAAa;IAenB;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;YAwBlB,iBAAiB;IAiC/B;;;;;OAKG;IACG,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,OAAO;IAwE9D;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAUlB;;;;;OAKG;IACG,MAAM,CACV,KAAK,GAAE,KAAU,EACjB,OAAO,GAAE,aAAa,GAAG,cAAmB,GAC3C,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAuBtB;;;;;OAKG;IACG,OAAO,CACX,KAAK,GAAE,KAAU,EACjB,OAAO,GAAE,aAAa,GAAG,cAAmB,GAC3C,OAAO,CAAC,GAAG,EAAE,CAAC;IAmCjB;;;;OAIG;IACG,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/C;;;;;OAKG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAkBxE;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAWlC;;;;;;;;OAQG;IACG,SAAS,CACb,IAAI,EAAE,GAAG,EACT,EAAE,EAAE,MAAM,EACV,IAAI,CAAC,EAAE,GAAG,EACV,SAAS,CAAC,EAAE,OAAO,EACnB,eAAe,CAAC,EAAE,MAAM,EACxB,kBAAkB,CAAC,EAAE,GAAG,EACxB,aAAa,CAAC,EAAE,IAAI,GACnB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA8KnB,cAAc,CAAC,EAAE,EAAE,MAAM;IAKzB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE;YAUrB,cAAc;YAkBd,cAAc;IA0B5B;;;;;;;OAOG;IACG,YAAY,CAChB,CAAC,EAAE,GAAG,EACN,EAAE,EAAE,GAAG,EACP,IAAI,CAAC,EAAE,GAAG,EACV,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,aAAa,CAAC;IAgBzB;;;;;OAKG;IACG,UAAU,CAAC,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxE;;;OAGG;IACH,IAAI,OAAO,IAAI,MAAM,CAMpB;IAED;;;;;OAKG;IAEH,uBAAuB,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS;IAetD;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAY9B;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,SAAS,CACb,IAAI,EAAE,GAAG,EACT,IAAI,CAAC,EAAE,GAAG,EACV,eAAe,CAAC,EAAE,MAAM,EACxB,SAAS,CAAC,EAAE,OAAO,EACnB,aAAa,CAAC,EAAE,IAAI,GACnB,OAAO,CAAC,GAAG,CAAC;IAgIf;;;;;;OAMG;IACG,YAAY,CAChB,CAAC,EAAE,GAAG,EACN,IAAI,CAAC,EAAE,GAAG,EACV,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,GAAG,CAAA;KAAE,CAAC;IAWhD;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IA4C/B;;;OAGG;IACH,SAAS,IAAI,KAAK,EAAE;IAIpB;;;OAGG;IACH,cAAc,IAAI,KAAK,EAAE;IAIzB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IA2BzC;;;OAGG;YAEW,oBAAoB;YAyBpB,sBAAsB;YAmCtB,eAAe;IAM7B;;;;;OAKG;IACG,mBAAmB,CACvB,EAAE,EAAE,GAAG,EACP,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,GAAG,GACT,OAAO,CAAC,IAAI,CAAC;IAchB;;;;OAIG;IACG,gBAAgB,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB1D;;;;OAIG;IACG,gBAAgB,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB1D;;;OAGG;YACW,kBAAkB;IAOhC;;;;OAIG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuC7C;;;;;OAKG;IACG,MAAM,CAAC,aAAa,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA6B/C;;;;OAIG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAQ7C;;;OAGG;IACG,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9C;;;;;OAKG;WACU,eAAe,CAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC;IAsFzB;;;OAGG;IACH,iBAAiB,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,GAAG,MAAM;IAmC3C;;;;;;OAMG;IACG,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QACR,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B,GACA,OAAO,CAAC,aAAa,CAAC;IA0RzB;;;;;OAKG;IACG,gBAAgB,CACpB,QAAQ,EAAE,MAAM,EAChB,mBAAmB,CAAC,EAAE,OAAO,GAC5B,OAAO,CAAC,GAAG,CAAC;IA0Cf;;;;;OAKG;IACG,sBAAsB,CAC1B,YAAY,CAAC,EAAE,OAAO,EACtB,YAAY,CAAC,EAAE,OAAO,GACrB,OAAO,CAAC,eAAe,EAAE,CAAC;IAqE7B;;;OAGG;IACG,oBAAoB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAevD;;;OAGG;IACG,iBAAiB,CAAC,MAAM,UAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAgB/D;;;;;OAKG;IACG,oBAAoB,CACxB,YAAY,CAAC,EAAE,OAAO,EACtB,YAAY,CAAC,EAAE,OAAO,GACrB,OAAO,CAAC,eAAe,CAAC;IA6ErB,aAAa,CACjB,QAAQ,GAAE,MAAU,EACpB,UAAU,GAAE,CAAC,CAAC,EAAE,KAAK,KAAK,OAAoB,EAC9C,MAAM,GAAE,MAAW,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC;IAsBpB;;;OAGG;IACG,mBAAmB,CACvB,uBAAuB,CAAC,EAAE,OAAO,GAChC,OAAO,CAAC,cAAc,CAAC;IAqC1B;;;;OAIG;IACG,cAAc,CAClB,IAAI,GAAE,CAAC,WAAW,GAAG,cAAc,CAAC,GAAG,GAAQ,GAC9C,OAAO,CAAC,GAAG,CAAC;IA0Nf;;;OAGG;IACG,YAAY,CAChB,IAAI,GAAE,CAAC,WAAW,GAAG,cAAc,CAAC,GAAG,GAAQ,GAC9C,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAKtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,aAAa,CACjB,IAAI,GAAE,CAAC,WAAW,GAAG,cAAc,CAAC,GAAG,GAAQ,GAC9C,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAuFtB;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IA2BnE;;OAEG;WACU,cAAc,IAAI,OAAO,CAAC;QACrC,CAAC,EAAE,EAAE,MAAM,GAAG,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,GAAG,CAAA;SAAE,CAAC,CAAC;KACpD,CAAC;IAWF;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAK5C;;OAEG;IACG,gBAAgB,IAAI,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAavD,kBAAkB,CAAC,QAAQ,EAAE,MAAM;CAMpC;AAGD,kBAAU,KAAK,CAAC;IACd,KAAY,eAAe,GAAG;QAC5B,gBAAgB,EAAE;YAChB,SAAS,EAAE,KAAK,CAAC;YACjB,KAAK,CAAC,EAAE,KAAK,CAAC;YACd,OAAO,CAAC,EAAE,KAAK,CAAC;SACjB,EAAE,CAAC;QACJ,iBAAiB,EAAE,MAAM,EAAE,CAAC;KAC7B,CAAC;IAEF,KAAY,cAAc,GAAG;QAC3B,eAAe,EAAE;YACf,SAAS,EAAE,KAAK,CAAC;YACjB,KAAK,EAAE,KAAK,CAAC;SACd,EAAE,CAAC;QACJ,gBAAgB,EAAE,MAAM,EAAE,CAAC;KAC5B,CAAC;IAEF,KAAY,YAAY,GAAG;QACzB,aAAa,EAAE,KAAK,CAAC;QACrB,aAAa,EAAE,KAAK,CAAC;KACtB,CAAC;CACH;AAED,aAAK,eAAe,GAAG,KAAK,CAAC,eAAe,CAAC;AAC7C,aAAK,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;AAC3C,aAAK,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;AAEvC,SAAS,KAAK,CAAC"}

package/dist/models/table.js

@@ -48,6 +48,7 @@ const utils_1 = __importDefault(require("../utils"));
 const { prefixFieldsInWhere, InvalidConfiguration, InvalidAdminAction, satisfies, structuredClone, getLines, mergeIntoWhere, stringToJSON, isNode, apply, applyAsync, asyncMap, } = utils_1.default;
 const tags_1 = __importDefault(require("@saltcorn/markup/tags"));
 const { text } = tags_1.default;
+const table_helper_1 = require("./internal/table_helper");
 /**
  * Transponce Objects
  * TODO more detailed explanation
@@ -84,18 +85,82 @@ const dateFormats = [moment_1.default.ISO_8601];
 const isDate = function (date) {
     return (0, moment_1.default)(date, dateFormats, true).isValid();
 };
-// todo resolve database specific
 /**
- * Normalise specific error message according db specific
- * @param msg
- * @returns {string}
- */
-// todo refactor
-const normalise_error_message = (msg) => db_1.default.isSQLite
-    ? msg.replace(/SQLITE_CONSTRAINT: UNIQUE constraint failed: (.*?)\.(.*?)/, "Duplicate value for unique field: $2")
-    : msg.replace(/duplicate key value violates unique constraint "(.*?)_(.*?)_unique"/, "Duplicate value for unique field: $2");
-/**
- * Table class
+ * A class representing database tables and their properties.
+ *
+ * Use this to create or delete tables and their properties, or to query
+ * or change table rows.
+ *
+ * To query, update, insert or delete rows in an existing table, first you
+ * should find the table object with {@link Table.findOne}.
+ *
+ * @example
+ * ```
+ * Table.findOne({name: "Customers"}) // find the table with name "Customers"
+ * Table.findOne("Customers") // find the table with name "Customers" (shortcut)
+ * Table.findOne({ id: 5 }) // find the table with id=5
+ * Table.findOne(5) // find the table with id=5 (shortcut)
+ * ```
+ *
+ * Table.findOne is synchronous (no need to await), But the functions that
+ * query and manipulate (such as {@link Table.insertRow}, {@link Table.getRows},
+ * {@link Table.updateRow}, {@link Table.deleteRows}) rows are mostly asyncronous,
+ * so you can put the await in front of the
+ * whole expression
+ *
+ * @example
+ * To count the number of rows in the customer table
+ * ```
+ * const nrows = await Table.findOne("Customers").countRows()
+ * ```
+ *
+ * For further examples, see the [Table test suite](https://github.com/saltcorn/saltcorn/blob/master/packages/saltcorn-data/tests/table.test.ts)
+ *
+ * ## Querying table rows
+ *
+ * There are several methods you can use to retrieve rows in the database:
+ *
+ * * {@link Table.countRows} To count the number of rows, optionally matching a criterion
+ * * {@link Table.getRows} To retrieve multiple rows matching a criterion
+ * * {@link Table.getRow} To retrieve a single row matching a criterion
+ * * {@link Table.getJoinedRows} To retrieve rows together with joinfields and aggregations
+ *
+ * These functions all take `Where` expressions which are JavaScript objects describing
+ * the criterion to match to. Some examples:
+ *
+ * * `{ name: "Jim" }`: Match all rows with name="Jim"
+ * * `{ name: { ilike: "im"} }`: Match all rows where name contains "im" (case insensitive)
+ * * `{ age: { lt: 18 } }`: Match all rows with age<18
+ * * `{ age: { lt: 18, equal: true } }`: Match all rows with age<=18
+ * * `{ age: { gt: 18, lt: 65} }`: Match all rows with 18<age<65
+ * * `{ name: { or: ["Harry", "Sally"] } }`: Match all rows with name="Harry" or "Sally"
+ * * `{ or: [{ name: "Joe"}, { age: 37 }] }`: Match all rows with name="Joe" or age=37
+ * * `{ not: { id: 5 } }`: All rows except id=5
+ *
+ * For further examples, see the [mkWhere test suite](https://github.com/saltcorn/saltcorn/blob/master/packages/db-common/internal.test.js)
+ *
+ * ## Updating a Row
+ *
+ * There are two nearly identical functions for updating rows depending on how you want
+ * failures treated
+ *
+ * * {@link Table.updateRow} Update a row, throws an exception if update is invalid
+ * * {@link Table.tryUpdateRow} Update a row, return an error message if update is invalid
+ *
+ * ## Inserting a new Row
+ *
+ * There are two nearly identical functions for inserting a new row depending on how you want
+ * failures treated
+ *
+ * * {@link Table.insertRow} insert a row, throws an exception if it is invalid
+ * * {@link Table.tryInsertRow} insert a row, return an error message if it is invalid
+ *
+ * ## Deleting rows
+ *
+ * Use {@link Table.deleteRows} to delete any number (zero, one or many) of rows matching a criterion. It uses
+ * the same `where` expression as the functions for querying rows
+ *
+ *
  * @category saltcorn-data
  */
 class Table {
@@ -984,7 +1049,7 @@ class Table {
             await this.updateRow({ [field_name]: !row[field_name] }, id, user);
     }
     /**
-     * Get primary key field
+     * Get primary key field name
      * @type {string}
      */
     get pk_name() {
@@ -995,7 +1060,9 @@ class Table {
         return pkField;
     }
     /**
-     * Check table constraints
+     * Check table constraints against a row object. Will return a string With an error message if the
+     * table constraints are violated, `undefined` if the row does not violate any constraints
+     *
      * @param row
      */
     check_table_constraints(row0) {
@@ -1028,9 +1095,23 @@ class Table {
         return undefined;
     }
     /**
-     * Insert row
+     * Insert row into the table. By passing in the user as
+     * the second argument, tt will check write rights. If a user object is not
+     * supplied, the insert goes ahead without checking write permissions.
+     *
+     * Returns the primary key value of the inserted row.
+     *
+     * This will throw an exception if the row
+     * does not conform to the table constraints. If you would like to insert a row
+     * with a function that can return an error message, use {@link Table.tryInsertRow} instead.
+     *
+     * @example
+     * ```
+     * await Table.findOne("People").insertRow({ name: "Jim", age: 35 })
+     * ```
+     *
      * @param v_in
-     * @param _userid
+     * @param user
      * @param resultCollector
      * @returns {Promise<*>}
      */
@@ -2237,6 +2318,38 @@ class Table {
         return rows.length > 0 ? rows[0] : null;
     }
     /**
+     * Get rows along with joined and aggregated fields. The argument to `getJoinedRows` is an object
+     * with several different possible fields, all of which are optional
+     *
+     * * `where`: A Where expression indicating the criterion to match
+     * * `joinFields`: An object with the joinfields to retrieve
+     * * `aggregations`: An object with the aggregations to retrieve
+     * * `orderBy`: A string with the name of the field to order by
+     * * `orderDesc`: If true, descending order
+     * * `limit`: A number with the maximum number of rows to retrieve
+     * * `offset`: The number of rows to skip in the result before returning rows
+     *
+     * @example
+     * ```
+     * const patients = Table.findOne({ name: "patients" });
+     * const patients_rows = await patients.getJoinedRows({
+     *      where: { age: { gt: 65 } },
+     *      orderBy: "id",
+     *      aggregations: {
+     *        avg_temp: {
+     *          table: "readings",
+     *          ref: "patient_id",
+     *          field: "temperature",
+     *          aggregate: "avg",
+     *       },
+     *      },
+     *      joinFields: {
+     *        pages: { ref: "favbook", target: "pages" },
+     *        author: { ref: "favbook", target: "author" },
+     *      },
+     * });
+     * ```
+     *
      * @param {object} [opts = {}]
      * @returns {Promise<object[]>}
      */
@@ -2381,6 +2494,9 @@ class Table {
         }
         return result;
     }
+    getFormulaExamples(typename) {
+        return (0, table_helper_1.get_formula_examples)(typename, this.fields.filter((f) => !f.calculated));
+    }
 }
 module.exports = Table;
 //# sourceMappingURL=table.js.map