@saltcorn/data 0.6.1-beta.0 → 0.6.1

package/models/email.js

@@ -1,3 +1,8 @@
+/**
+ * @category saltcorn-data
+ * @module models/email
+ * @subcategory models
+ */
 const nodemailer = require("nodemailer");
 const { getState } = require("../db/state");
 const BootstrapEmail = require("bootstrap-email");
@@ -9,6 +14,9 @@ const { v4: uuidv4 } = require("uuid");
 const db = require("../db");
 const { mockReqRes } = require("../tests/mocks");
 
+/**
+ * @returns {Transporter}
+ */
 const getMailTransport = () => {
   const port = getState().getConfig("smtp_port");
   const secure = getState().getConfig("smtp_secure", port === 465);
@@ -23,6 +31,10 @@ const getMailTransport = () => {
   });
 };
 
+/**
+ * @param {object} bsHtml 
+ * @returns {object}
+ */
 const transformBootstrapEmail = async (bsHtml) => {
   const filename = await tmp.tmpName();
   await fs.writeFile(filename, div({ class: "container" }, bsHtml));
@@ -33,6 +45,11 @@ const transformBootstrapEmail = async (bsHtml) => {
   return email;
 };
 
+/**
+ * @param {object} user 
+ * @param {object} [req]
+ * @returns {Promise<object>}
+ */
 const send_verification_email = async (user, req) => {
   const verification_view_name = getState().getConfig("verification_view");
   if (verification_view_name) {

package/models/eventlog.js

@@ -1,9 +1,23 @@
+/**
+ * EventLog Database Access Layer
+ * @category saltcorn-data
+ * @module models/eventlog
+ * @subcategory models
+ */
 const db = require("../db");
 const moment = require("moment");
 
 const { contract, is } = require("contractis");
 
+/**
+ * EventLog Class
+ * @category saltcorn-data
+ */
 class EventLog {
+  /**
+   * EventLog constructor
+   * @param {object} o 
+   */
   constructor(o) {
     this.id = o.id;
     this.event_type = o.event_type;
@@ -16,14 +30,30 @@ class EventLog {
       typeof o.payload === "string" ? JSON.parse(o.payload) : o.payload;
     contract.class(this);
   }
+
+  /**
+   * @param {object} where 
+   * @param {object} selopts 
+   * @returns {Promise<EventLog[]>}
+   */
   static async find(where, selopts) {
     const us = await db.select("_sc_event_log", where, selopts);
     return us.map((u) => new EventLog(u));
   }
+
+  /**
+   * @param {object} where 
+   * @returns {Promise<EventLog>}
+   */
   static async findOne(where) {
     const u = await db.selectOne("_sc_event_log", where);
     return new EventLog(u);
   }
+
+  /**
+   * @param {string} id 
+   * @returns {Promise<EventLog>}
+   */
   static async findOneWithUser(id) {
     const {
       rows,
@@ -37,12 +67,25 @@ class EventLog {
     return el;
   }
 
+  /**
+   * @param {object} where 
+   * @returns {Promise<number>}
+   */
   static async count(where) {
     return await db.count("_sc_event_log", where || {});
   }
+
+  /**
+    * @type {string}
+    */
   get reltime() {
     return moment(this.occur_at).fromNow();
   }
+
+  /**
+   * @param {object} o 
+   * @returns {Promise<EventLog>}
+   */
   static async create(o) {
     const { getState } = require("../db/state");
 
@@ -64,10 +107,18 @@ class EventLog {
     return ev;
   }
 
+  /**
+   * @param {string} evType 
+   * @returns {boolean}
+   */
   static hasTable(evType) {
     return ["Insert", "Update", "Delete"].includes(evType);
   }
 
+  /**
+   * @param {string} evType 
+   * @returns {boolean}
+   */
   static hasChannel(evType) {
     const { getState } = require("../db/state");
     const t = getState().eventTypes[evType];

package/models/expression.js

@@ -1,7 +1,17 @@
+/**
+ * @category saltcorn-data
+ * @module models/expression
+ * @subcategory models
+ */
 const vm = require("vm");
 let acorn = require("acorn");
 const estraverse = require("estraverse");
 const astring = require("astring");
+
+/**
+ * @param {string} s 
+ * @returns {boolean|void}
+ */
 function expressionValidator(s) {
   if (!s || s.length == 0) return "Missing formula";
   try {
@@ -11,11 +21,21 @@ function expressionValidator(s) {
     return e.message;
   }
 }
+
+/**
+ * @param {string} expression 
+ * @returns {string}
+ */
 function jsexprToSQL(expression) {
   if (!expression) return expression;
   return expression.replace(/===/g, "=").replace(/==/g, "=").replace(/"/g, "'");
 }
 
+/**
+ * @param {string} expression 
+ * @throws {Error}
+ * @returns {object}
+ */
 function jsexprToWhere(expression) {
   if (!expression) return {};
   try {
@@ -77,6 +97,11 @@ function jsexprToWhere(expression) {
   }
 }
 
+/**
+ * @param {string} expression 
+ * @param {object[]} statefuns 
+ * @returns {object}
+ */
 function transform_for_async(expression, statefuns) {
   var isAsync = false;
   const ast = acorn.parseExpressionAt(expression, 0, {
@@ -99,6 +124,11 @@ function transform_for_async(expression, statefuns) {
   return { isAsync, expr_string: astring.generate(ast) };
 }
 
+/**
+ * @param {string} expression 
+ * @param {object[]} fields 
+ * @returns {any}
+ */
 function get_expression_function(expression, fields) {
   const field_names = fields.map((f) => f.name);
   const args = field_names.includes("user")
@@ -110,6 +140,13 @@ function get_expression_function(expression, fields) {
     getState().function_context
   );
 }
+
+/**
+ * @param {string} expression 
+ * @param {object[]} fields 
+ * @param {object} [extraContext = {}]
+ * @returns {any}
+ */
 function get_async_expression_function(expression, fields, extraContext = {}) {
   const field_names = fields.map((f) => f.name);
   const args = field_names.includes("user")
@@ -124,6 +161,11 @@ function get_async_expression_function(expression, fields, extraContext = {}) {
   });
 }
 
+/**
+ * @param {object[]} rows 
+ * @param {object[]} fields 
+ * @returns {object[]} 
+ */
 function apply_calculated_fields(rows, fields) {
   let hasExprs = false;
   let transform = (x) => x;
@@ -152,6 +194,12 @@ function apply_calculated_fields(rows, fields) {
     return rows.map(transform);
   } else return rows;
 }
+
+/**
+ * @param {*} row 
+ * @param {*} fields 
+ * @returns {Promise<any>}
+ */
 const apply_calculated_fields_stored = async (row, fields) => {
   let hasExprs = false;
   let transform = (x) => x;
@@ -182,7 +230,7 @@ const apply_calculated_fields_stored = async (row, fields) => {
 };
 /**
  * Recalculate calculated columns that are stored in db
- * @param table - table object
+ * @param {object} table - table object
  * @returns {Promise<void>}
  */
 const recalculate_for_stored = async (table) => {

package/models/field.js

@@ -1,12 +1,14 @@
 /**
- *
  * Field Data Access Layer
+ * @category saltcorn-data
+ * @module models/field
+ * @subcategory models
  */
 
 const db = require("../db");
 const { contract, is } = require("contractis");
 const { recalculate_for_stored } = require("./expression");
-const { sqlsanitize } = require("../db/internal.js");
+const { sqlsanitize } = require("@saltcorn/db-common/internal.js");
 const { InvalidAdminAction } = require("../utils");
 const { mkWhere } = require("../db");
 
@@ -22,6 +24,7 @@ const readKey = (v, field) => {
 
 /**
  * Field Class
+ * @category saltcorn-data
  */
 class Field {
   /**
@@ -99,7 +102,7 @@ class Field {
 
   /**
    * To Json
-   * @returns {{expression, fieldview, is_unique: (boolean), label: *, table_id: *, type: (string|*), primary_key: (*|boolean), sublabel, required: (boolean), refname: (string|*), reftable_name: (string|*|Table), stored: (*|boolean), name: (*), attributes: any, id, calculated: (*|boolean), reftype: (string|*)}}
+   * @type {object}
    */
   get toJson() {
     return {
@@ -126,8 +129,8 @@ class Field {
 
   /**
    * Label 2 Name
-   * @param label
-   * @returns {*}
+   * @param {string} label
+   * @returns {string}
    */
   // todo from internalization point of view better to separate label, name. sqlname
   // because label can contain characters that cannot be used in PG for sql names
@@ -137,7 +140,7 @@ class Field {
 
   /**
    * ???
-   * @returns {string|*}
+   * @returns {string}
    */
   get form_name() {
     if (this.parent_field) return `${this.parent_field}_${this.name}`;
@@ -146,7 +149,8 @@ class Field {
 
   /**
    * Fill fkey options???
-   * @param force_allow_none
+   * @param {boolean} [force_allow_none = false]
+   * @param {object} where
    * @returns {Promise<void>}
    */
   async fill_fkey_options(force_allow_none = false, where) {
@@ -177,8 +181,8 @@ class Field {
 
   /**
    * Distinct Values
-   * @param req
-   * @returns {Promise<[{label: string, value: string}, {jsvalue: boolean, label, value: string}, {jsvalue: boolean, label, value: string}]|[{label: string, value: string}, ...*]|*[]>}
+   * @param {object} [req]
+   * @returns {Promise<void>}
    */
   async distinct_values(req, where) {
     const __ = req && req.__ ? req.__ : (s) => s;
@@ -226,6 +230,9 @@ class Field {
     return [{ label: "", value: "" }, ...dbOpts];
   }
 
+  /**
+   * @type {string}
+   */
   get sql_type() {
     if (this.is_fkey) {
       const schema = db.getTenantSchemaPrefix();
@@ -241,12 +248,18 @@ class Field {
     }
   }
 
+  /**
+   * @type {string}
+   */
   get pretty_type() {
     if (this.reftable_name === "_sc_files") return "File";
     if (this.is_fkey) return `Key to ${this.reftable_name}`;
     else return this.type ? this.type.name : "?";
   }
 
+  /**
+   * @type {string}
+   */
   get sql_bare_type() {
     if (this.is_fkey) {
       const { getState } = require("../db/state");
@@ -257,6 +270,9 @@ class Field {
     }
   }
 
+  /**
+   * @returns {Promise<any>}
+   */
   async generate() {
     if (this.is_fkey) {
       const rows = await db.select(
@@ -271,6 +287,10 @@ class Field {
     }
   }
 
+  /**
+   * @param {object} whole_rec 
+   * @returns {object}
+   */
   validate(whole_rec) {
     const type = this.is_fkey ? { name: "Key" } : this.type;
     const readval = this.is_fkey
@@ -295,26 +315,47 @@ class Field {
     else return { error: "Not accepted" };
   }
 
+  /**
+   * 
+   * @param {object} where 
+   * @param {object} [selectopts]
+   * @returns {Field[]}
+   */
   static async find(where, selectopts = { orderBy: "name", nocase: true }) {
     const db_flds = await db.select("_sc_fields", where, selectopts);
     return db_flds.map((dbf) => new Field(dbf));
   }
 
+  /**
+   * @param {object} where 
+   * @returns {Promise<Field>}
+   */
   static async findOne(where) {
     const db_fld = await db.selectOne("_sc_fields", where);
     return new Field(db_fld);
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async add_unique_constraint() {
     await this.fill_table();
     await db.add_unique_constraint(this.table.name, [this.name]);
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async remove_unique_constraint() {
     await this.fill_table();
     await db.drop_unique_constraint(this.table.name, [this.name]);
   }
 
+  /**
+   * 
+   * @param {boolean} not_null 
+   * @returns {Promise<void>}
+   */
   async toggle_not_null(not_null) {
     const schema = db.getTenantSchemaPrefix();
     await this.fill_table();
@@ -328,6 +369,10 @@ class Field {
     await require("../db/state").getState().refresh_tables();
   }
 
+  /**
+   * @param {object} new_field 
+   * @returns {Promise<void>}
+   */
   async alter_sql_type(new_field) {
     let new_sql_type = new_field.sql_type;
     let def = "";
@@ -365,6 +410,9 @@ class Field {
     await require("../db/state").getState().refresh_tables();
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async fill_table() {
     if (!this.table) {
       const Table = require("./table");
@@ -372,6 +420,10 @@ class Field {
     }
   }
 
+  /**
+   * @param {object} v 
+   * @returns {Promise<void>}
+   */
   async update(v) {
     if (
       typeof v.is_unique !== "undefined" &&
@@ -405,6 +457,10 @@ class Field {
     });
     await require("../db/state").getState().refresh_tables();
   }
+
+  /**
+   * @type {string}
+   */
   get listKey() {
     return this.type.listAs
       ? (r) => this.type.listAs(r[this.name])
@@ -412,6 +468,10 @@ class Field {
       ? (r) => this.type.showAs(r[this.name])
       : this.name;
   }
+
+  /**
+   * @type {object}
+   */
   get presets() {
     if (this.type && this.type.presets) return this.type.presets;
 
@@ -420,6 +480,11 @@ class Field {
 
     return null;
   }
+
+  /**
+   * @throws {InvalidAdminAction}
+   * @returns {Promise<void>}
+   */
   async delete() {
     const Table = require("./table");
     const table = await Table.findOne({ id: this.table_id });
@@ -457,6 +522,10 @@ class Field {
     await require("../db/state").getState().refresh_tables();
   }
 
+  /**
+   * @param {object} table 
+   * @returns {Promise<void>}
+   */
   async enable_fkey_constraint(table) {
     if (this.is_fkey && !db.isSQLite) {
       const schema = db.getTenantSchemaPrefix();
@@ -472,6 +541,11 @@ class Field {
     }
   }
 
+  /**
+   * @param {object} fld 
+   * @param {boolean} [bare = false]
+   * @returns {Promise<Field>}
+   */
   static async create(fld, bare = false) {
     const f = new Field(fld);
     const schema = db.getTenantSchemaPrefix();
@@ -568,6 +642,11 @@ class Field {
     return f;
   }
 
+  /**
+   * @param {function|object[]} [typeattribs]
+   * @param {number} [table_id]
+   * @returns {*}
+   */
   static getTypeAttributes(typeattribs, table_id) {
     const Table = require("./table");
 

package/models/fieldrepeat.js

@@ -1,7 +1,21 @@
+/**
+ * FieldRepeat Database Access Layer
+ * @category saltcorn-data
+ * @module models/fieldrepeat
+ * @subcategory models
+ */
 const { contract, is } = require("contractis");
 const Field = require("./field");
 
+/**
+ * FieldRepeat Class
+ * @category saltcorn-data
+ */
 class FieldRepeat {
+  /**
+   * FieldRepeat constructor
+   * @param {object} o 
+   */
   constructor(o) {
     this.label = o.label || o.name;
     this.name = o.name;
@@ -11,6 +25,10 @@ class FieldRepeat {
     this.isRepeat = true;
     contract.class(this);
   }
+
+  /**
+   * @returns {Promise<void>}
+   */
   async generate() {
     const nrepeats = Math.round(Math.random() * 5);
     var r = {};
@@ -22,9 +40,20 @@ class FieldRepeat {
       }
     }
   }
+
+  /**
+   * @param {*} whole_rec 
+   * @returns {object}
+   */
   validate(whole_rec) {
     return this.validate_from_ix(whole_rec, 0);
   }
+
+  /**
+   * @param {*} whole_rec 
+   * @param {*} ix 
+   * @returns {object}
+   */
   validate_from_ix(whole_rec, ix) {
     var has_any = false;
     var res = {};
@@ -41,6 +70,10 @@ class FieldRepeat {
       return { success: [res, ...rest.success] };
     } else return { success: [] };
   }
+
+  /**
+   * @type {string}
+   */
   get form_name() {
     return this.name;
   }

package/models/file.js

@@ -1,6 +1,8 @@
 /**
- *
- * @type {{changeConnection?: ((function(*): Promise<void>)|(function(*=): Promise<void>)), select?: ((function(*=, *=, *=): Promise<*>)|(function(*=, *=, *=): Promise<*>)), runWithTenant: ((function(*=, *=): (*))|(function(*, *): *)), set_sql_logging?: (function(*=): void), insert?: ((function(*=, *=, *=): Promise<undefined|*>)|(function(*=, *=, *=): Promise<*>)), update?: ((function(*=, *=, *=): Promise<void>)|(function(*=, *=, *, *=): Promise<void>)), sql_log?: (function(*=, *=): void), deleteWhere?: ((function(*=, *=): Promise<void>)|(function(*=, *=): Promise<*>)), isSQLite: boolean, selectMaybeOne?: ((function(*=, *=): Promise<null|*>)|(function(*=, *=): Promise<null|*>)), close?: ((function(): Promise<void>)|(function(): Promise<void>)), drop_unique_constraint?: ((function(*=, *): Promise<void>)|(function(*=, *): Promise<void>)), enable_multi_tenant: (function()), getVersion?: ((function(): Promise<*>)|(function(*=): Promise<*>)), add_unique_constraint?: ((function(*=, *): Promise<void>)|(function(*=, *): Promise<void>)), getTenantSchema: ((function(): *)|(function(): *)), is_it_multi_tenant: ((function(): boolean)|(function(): boolean)), sqliteDatabase?: *, drop_reset_schema?: ((function(): Promise<void>)|(function(*): Promise<void>)), query?: ((function(*=, *=): Promise<unknown>)|(function(*=, *=): *)), count?: ((function(*=, *=): Promise<number>)|(function(*=, *=): Promise<number>)), pool?: *, connectObj: {sc_version: string, connectionString: *, git_commit: *, version_tag: (*|string)}|{sqlite_path}|boolean, sqlsanitize: *|(function(...[*]=): *), getClient?: (function(): Promise<*>), reset_sequence?: (function(*=): Promise<void>), copyFrom?: (function(*=, *=, *, *): Promise<void>), mkWhere: function(*=): {values: *, where: string|string}, selectOne?: ((function(*=, *=): Promise<*|undefined>)|(function(*=, *=): Promise<*>)), getTenantSchemaPrefix: function(): string|string}|{sqlsanitize?: *|(function(...[*]=): *), connectObj?: {sc_version: string, connectionString: *, git_commit: *, version_tag: (*|string)}|{sqlite_path}|boolean, isSQLite?: boolean, mkWhere?: function(*=): {values: *, where: string|string}, getTenantSchemaPrefix?: function(): string|string}}
+ * File Database Access Layer
+ * @category saltcorn-data
+ * @module models/file
+ * @subcategory models
  */
 
 const db = require("../db");
@@ -19,8 +21,13 @@ const fs = require("fs").promises;
  * 3. List of files stored in _sc_files table in Saltcorn database.
  * 4. Each tenant has own file list and file storage.
  * 5. This class provides file descriptor and basic functions to manipulate with files.
+ * @category saltcorn-data
  */
 class File {
+  /**
+   * Constructor
+   * @param o {object}
+   */
   constructor(o) {
     this.filename = o.filename;
     this.location = o.location;
@@ -43,7 +50,14 @@ class File {
    * @param selectopts
    * @returns {Promise<*>}
    */
-  static async find(where, selectopts) {
+  static async find(where, selectopts = {}) {
+    if (selectopts.cached) {
+      const { getState } = require("../db/state");
+      const files = Object.values(getState().files).sort((a, b) =>
+        a.filename > b.filename ? 1 : -1
+      );
+      return files.map((t) => new File(t));
+    }
     const db_flds = await db.select("_sc_files", where, selectopts);
     return db_flds.map((dbf) => new File(dbf));
   }
@@ -106,7 +120,7 @@ class File {
    * @param file
    * @param user_id
    * @param min_role_read
-   * @returns {Promise<File|[]>}
+   * @returns {Promise<File>}
    */
   static async from_req_files(file, user_id, min_role_read = 1) {
     if (Array.isArray(file)) {
@@ -150,6 +164,11 @@ class File {
       return { error: e.message };
     }
   }
+
+  /**
+   * MIME type of the file
+   * @type {string}
+   */
   get mimetype() {
     return `${this.mime_super}/${this.mime_sub}`;
   }