@saltcorn/data 0.6.1-beta.0 → 0.6.1

package/models/scheduler.js

@@ -1,3 +1,8 @@
+/**
+ * @category saltcorn-data
+ * @module models/scheduler
+ * @subcategory models
+ */
 const Crash = require("./crash");
 const { eachTenant } = require("./tenant");
 const Trigger = require("./trigger");
@@ -6,6 +11,11 @@ const { getState } = require("../db/state");
 const fetch = require("node-fetch");
 const EventLog = require("./eventlog");
 
+/**
+ * @param {Date} date 
+ * @param {number} plusSeconds 
+ * @returns {Promise<void>}
+ */
 const sleepUntil = (date, plusSeconds) => {
   const waitTill = new Date();
   waitTill.setTime(date.getTime() + 1000 * plusSeconds);
@@ -14,6 +24,11 @@ const sleepUntil = (date, plusSeconds) => {
   return new Promise((resolve) => setTimeout(resolve, ms));
 };
 
+/**
+ * @param {string} name 
+ * @param {number} hours 
+ * @returns {Promise<Trigger[]>}
+ */
 const getIntervalTriggersDueNow = async (name, hours) => {
   const state = getState();
   const cfgField = `next_${name.toLowerCase()}_event`;
@@ -51,6 +66,10 @@ const getIntervalTriggersDueNow = async (name, hours) => {
 
 let availabilityPassed = false;
 
+/**
+ * @param {string} port 
+ * @returns {Promise<void>}
+ */
 const checkAvailability = async (port) => {
   try {
     const response = await fetch(`http://127.0.0.1:${port}/auth/login`);
@@ -72,6 +91,15 @@ const checkAvailability = async (port) => {
   }
 };
 
+/**
+ * @param {object} opts
+ * @param {function} [opts.stop_when]
+ * @param {number} [opts.number]
+ * @param {boolean} opts.watchReaper
+ * @param {string} opts.port
+ * @param {boolean} opts.disableScheduler
+ * @returns {Promise<void>}
+ */
 const runScheduler = async ({
   stop_when = () => false,
   tickSeconds = 60 * 5,

package/models/table.js

@@ -1,9 +1,15 @@
 /**
  * Table Database Access Layer
- *
+ * @category saltcorn-data
+ * @module models/table
+ * @subcategory models
  */
 const db = require("../db");
-const { sqlsanitize, mkWhere, mkSelectOptions } = require("../db/internal.js");
+const {
+  sqlsanitize,
+  mkWhere,
+  mkSelectOptions,
+} = require("@saltcorn/db-common/internal.js");
 const Field = require("./field");
 const Trigger = require("./trigger");
 const {
@@ -29,7 +35,7 @@ const {
  * TODO more detailed explanation
  * TODO refactor - move to object util module?
  * @param objs
- * @returns {{}}
+ * @returns {object}
  */
 const transposeObjects = (objs) => {
   const keys = new Set();
@@ -64,7 +70,7 @@ const isDate = function (date) {
 /**
  * Normalise specific error message according db specific
  * @param msg
- * @returns {*}
+ * @returns {string}
  */
 // todo refactor
 const normalise_error_message = (msg) =>
@@ -80,8 +86,13 @@ const normalise_error_message = (msg) =>
 
 /**
  * Table class
+ * @category saltcorn-data
  */
 class Table {
+  /**
+   * Table constructor
+   * @param {object} o
+   */
   constructor(o) {
     this.name = o.name;
     this.id = o.id;
@@ -100,7 +111,7 @@ class Table {
    *
    * Find one Table
    * @param where - where condition
-   * @returns {Promise<*|Table|null>} table or null
+   * @returns {*|Table|null} table or null
    */
   static findOne(where) {
     if (
@@ -131,9 +142,13 @@ class Table {
    * Find Tables
    * @param where - where condition
    * @param selectopts - options
-   * @returns {Promise<*>} table list
+   * @returns {Promise<Table[]>} table list
    */
   static async find(where, selectopts = { orderBy: "name", nocase: true }) {
+    if (selectopts.cached) {
+      const { getState } = require("../db/state");
+      return getState().tables.map((t) => new Table(t));
+    }
     const tbls = await db.select("_sc_tables", where, selectopts);
 
     return tbls.map((t) => new Table(t));
@@ -143,7 +158,7 @@ class Table {
    * Find Tables including external tables
    * @param where0
    * @param selectopts
-   * @returns {Promise<*[]>}
+   * @returns {Promise<object[]>}
    */
   static async find_with_external(
     where0 = {},
@@ -284,7 +299,7 @@ class Table {
 
   /***
    * get Table SQL Name
-   * @returns {string}
+   * @type {string}
    */
   get sql_name() {
     return `${db.getTenantSchemaPrefix()}"${sqlsanitize(this.name)}"`;
@@ -339,7 +354,7 @@ class Table {
    * Get rows from Table in db
    * @param where
    * @param selopts
-   * @returns {Promise<*>}
+   * @returns {Promise<void>}
    */
   async getRows(where = {}, selopts) {
     await this.getFields();
@@ -363,9 +378,8 @@ class Table {
    * Return distinct Values for column in table
    * ????
    * @param fieldnm
-   * @returns {Promise<*>}
+   * @returns {Promise<Object[]>}
    */
-
   async distinctValues(fieldnm) {
     const res = await db.query(
       `select distinct "${db.sqlsanitize(fieldnm)}" from ${this.sql_name}`
@@ -457,7 +471,7 @@ class Table {
 
   /**
    * Get primary key field
-   * @returns {*}
+   * @type {string}
    */
   get pk_name() {
     return this.fields.find((f) => f.primary_key).name;
@@ -503,7 +517,7 @@ class Table {
 
   /**
    * Get Fields list for table
-   * @returns {Promise<*>}
+   * @returns {Promise<Field[]>}
    */
   async getFields() {
     if (!this.fields) {
@@ -903,7 +917,7 @@ class Table {
   /**
    * Get parent relations for table
    * @param allow_double
-   * @returns {Promise<{parent_relations: *[], parent_field_list: *[]}>}
+   * @returns {Promise<{parent_relations: object[], parent_field_list: object[]}>}
    */
   async get_parent_relations(allow_double) {
     const fields = await this.getFields();
@@ -936,7 +950,7 @@ class Table {
 
   /**
    * Get child relations for table
-   * @returns {Promise<{child_relations: *[], child_field_list: *[]}>}
+   * @returns {Promise<{child_relations: object[], child_field_list: object[]}>}
    */
   async get_child_relations() {
     const cfields = await Field.find({ reftable_name: this.name });
@@ -1083,6 +1097,11 @@ class Table {
     )}" a ${joinq} ${where}  ${mkSelectOptions(selectopts)}`;
     return { sql, values };
   }
+
+  /**
+   * @param {object} [opts = {}]
+   * @returns {Promise<object[]>}
+   */
   async getJoinedRows(opts = {}) {
     const fields = await this.getFields();
 

package/models/table_constraints.js

@@ -1,8 +1,21 @@
+/**
+ * TableConstraint Database Access Layer
+ * @category saltcorn-data
+ * @module models/table_constraints
+ * @subcategory models
+ */
 const db = require("../db");
 const { contract, is } = require("contractis");
 const { stringToJSON } = require("../utils");
 
+/**
+ * TableConstraint class
+ * @category saltcorn-data
+ */
 class TableConstraint {
+  /**
+   * @param {object} o 
+   */
   constructor(o) {
     this.table_id = +o.table_id;
     if (o.table) {
@@ -14,22 +27,39 @@ class TableConstraint {
     contract.class(this);
   }
 
+  /**
+   * @type {object}
+   */
   get toJson() {
     return {
       type: this.type,
       configuration: this.configuration,
     };
   }
+
+  /**
+   * @param {*} where 
+   * @param {*} selectopts 
+   * @returns {Promise<TableConstraint[]>}
+   */
   static async find(where, selectopts) {
     const db_flds = await db.select("_sc_table_constraints", where, selectopts);
     return db_flds.map((dbf) => new TableConstraint(dbf));
   }
 
+  /**
+   * @param {*} where 
+   * @returns {Promise<TableConstraint>}
+   */
   static async findOne(where) {
     const p = await db.selectMaybeOne("_sc_table_constraints", where);
     return p ? new TableConstraint(p) : null;
   }
 
+  /**
+   * @param {*} f 
+   * @returns {Promise<TableConstraint>}
+   */
   static async create(f) {
     const con = new TableConstraint(f);
     const { id, ...rest } = con;
@@ -43,6 +73,10 @@ class TableConstraint {
 
     return con;
   }
+
+  /**
+   * @returns {Promise<void>}
+   */
   async delete() {
     await db.deleteWhere("_sc_table_constraints", { id: this.id });
     if (this.type === "Unique" && this.configuration.fields) {
@@ -51,6 +85,12 @@ class TableConstraint {
       await db.drop_unique_constraint(table.name, this.configuration.fields);
     }
   }
+
+  /**
+   * @param {*} table 
+   * @param {*} field 
+   * @returns {Promise<void>}
+   */
   static async delete_field_constraints(table, field) {
     const tblcs = await TableConstraint.find({ table_id: table.id });
     for (const c of tblcs) {
@@ -58,6 +98,10 @@ class TableConstraint {
         await c.delete();
     }
   }
+
+  /**
+   * @type {string[]}
+   */
   static get type_options() {
     return ["Unique"];
   }

package/models/tenant.js

@@ -1,15 +1,20 @@
 /**
  * Tenant Management Data Layer Access
- *
+ * @category saltcorn-data
+ * @module models/tenant
+ * @subcategory models
  */
 const db = require("../db");
 const reset = require("../db/reset_schema");
 const { contract, is } = require("contractis");
-const { sqlsanitize } = require("../db/internal");
+const { sqlsanitize } = require("@saltcorn/db-common/internal");
 const { setConfig } = require("./config");
+const fs = require("fs").promises;
+
 /**
  * List all Tenants
- * @type {*|(function(...[*]=): *)}
+ * @function
+ * @returns {Promise<string[]>}
  */
 const getAllTenants = contract(
   is.fun([], is.promise(is.array(is.str))),
@@ -24,19 +29,27 @@ const getAllTenants = contract(
  * - create db schema
  * - reset db schema (create required )
  * - change current base_url
- * @type {*|(function(...[*]=): *)}
  *
  * Arguments:
  * subdomain - tenant name (subdomain)
  * newurl - base url of tenant
  * email - email of creator
  * description - description of tenant
+ * @function
+ * @param {string} subdomain
+ * @param {string} [newurl]
+ * @param {string} [email]
+ * @param {string} [description]
+ * @returns {Promise<void>}
  */
 const createTenant = contract(
-  is.fun([is.str, is.maybe(is.str), is.maybe(is.str), is.maybe(is.str)], is.promise(is.undefined)),
+  is.fun(
+    [is.str, is.maybe(is.str), is.maybe(is.str), is.maybe(is.str)],
+    is.promise(is.undefined)
+  ),
   // TODO how to set names for arguments
-  async ( subdomain, newurl, email, description) => {
-      // normalize domain name
+  async (subdomain, newurl, email, description) => {
+    // normalize domain name
     const saneDomain = domain_sanitize(subdomain);
 
     // add email
@@ -61,10 +74,31 @@ const createTenant = contract(
     });
   }
 );
+const copy_tenant_template = async ({
+  tenant_template,
+  target,
+  loadAndSaveNewPlugin,
+}) => {
+  const { create_backup, restore } = require("./backup");
+  // TODO use a hygenic name for backup file
+  const backupFile = await db.runWithTenant(tenant_template, create_backup);
+  await db.runWithTenant(target, async () => {
+    await restore(backupFile, loadAndSaveNewPlugin, true);
+
+    await db.updateWhere("_sc_files", { user_id: null }, {});
+    await db.deleteWhere("users", {});
+    await db.reset_sequence("users");
+    //
+  });
+  await fs.unlink(backupFile);
+};
+
 /**
  * Delete Tenant
  * Note! This is deleting all tenant data in database!
- * @type {*|(function(...[*]=): *)}
+ * @function
+ * @param {string} sub
+ * @returns {Promise<void>}
  */
 const deleteTenant = contract(
   is.fun(is.str, is.promise(is.undefined)),
@@ -80,7 +114,9 @@ const deleteTenant = contract(
  * Sanitize Domain (Normalize domain name).
  * - force to lower case
  * - remove . in name
- * @type {*|(function(...[*]=): *)}
+ * @function
+ * @param {string} s
+ * @returns {string}
  */
 const domain_sanitize = contract(is.fun(is.str, is.str), (s) =>
   sqlsanitize(s.replace(".", "").toLowerCase())
@@ -104,4 +140,5 @@ module.exports = {
   domain_sanitize,
   deleteTenant,
   eachTenant,
+  copy_tenant_template,
 };

package/models/trigger.js

@@ -1,6 +1,8 @@
 /**
- *
  * Trigger Data Access Layer
+ * @category saltcorn-data
+ * @module models/trigger
+ * @subcategory models
  */
 
 const db = require("../db");
@@ -10,8 +12,13 @@ const EventLog = require("./eventlog");
 
 /**
  * Trigger class
+ * @category saltcorn-data
  */
 class Trigger {
+  /**
+   * Trigger constructor
+   * @param {object} o 
+   */
   constructor(o) {
     this.name = o.name;
     this.action = o.action;
@@ -36,7 +43,7 @@ class Trigger {
 
   /**
    * Get JSON from Trigger
-   * @returns {{when_trigger, configuration: any, name, description, action}}
+   * @type {{when_trigger, configuration: any, name, description, action}}
    */
   get toJson() {
     let table_name = this.table_name;
@@ -60,7 +67,7 @@ class Trigger {
   /**
    * Find triggers in State cache
    * @param where - condition
-   * @returns {T[]}
+   * @returns {Trigger[]}
    */
   static find(where) {
     const { getState } = require("../db/state");
@@ -71,7 +78,7 @@ class Trigger {
    * Find triggers in DB
    * @param where
    * @param selectopts
-   * @returns {Promise<*>}
+   * @returns {Promise<Trigger[]>}
    */
   static async findDB(where, selectopts) {
     const db_flds = await db.select("_sc_triggers", where, selectopts);
@@ -80,7 +87,7 @@ class Trigger {
 
   /**
    * Find all triggers
-   * @returns {Promise<*>}
+   * @returns {Promise<Trigger[]>}
    */
   static async findAllWithTableName() {
     const schema = db.getTenantSchemaPrefix();
@@ -94,7 +101,7 @@ class Trigger {
   /**
    * Find one trigger in State cache
    * @param where
-   * @returns {T}
+   * @returns {Trigger}
    */
   static findOne(where) {
     const { getState } = require("../db/state");
@@ -142,7 +149,13 @@ class Trigger {
     await require("../db/state").getState().refresh_triggers();
   }
 
-  // Emit an event: run associated triggers
+  /**
+   * Emit an event: run associated triggers
+   * @param {*} eventType 
+   * @param {*} channel 
+   * @param {object} [userPW = {}]
+   * @param {*} payload 
+   */
   static emitEvent(eventType, channel, userPW = {}, payload) {
     setTimeout(async () => {
       const { password, ...user } = userPW || {};
@@ -205,7 +218,7 @@ class Trigger {
   /**
    * Run trigger without row
    * @param runargs
-   * @returns {Promise<*>}
+   * @returns {Promise<boolean>}
    */
   async runWithoutRow(runargs = {}) {
     const { getState } = require("../db/state");
@@ -224,7 +237,7 @@ class Trigger {
    * get triggers
    * @param when_trigger
    * @param table
-   * @returns {Promise<*>}
+   * @returns {Promise<Trigger[]>}
    */
   static async getTableTriggers(when_trigger, table) {
     const { getState } = require("../db/state");
@@ -249,8 +262,8 @@ class Trigger {
   }
 
   /**
-   *  Trigger when options
-   * @returns {string[]}
+   * Trigger when options
+   * @type {string[]}
    */
   static get when_options() {
     const { getState } = require("../db/state");

package/models/user.js

@@ -1,3 +1,8 @@
+/**
+ * @category saltcorn-data
+ * @module models/user
+ * @subcategory models
+ */
 const db = require("../db");
 const bcrypt = require("bcryptjs");
 const { contract, is } = require("contractis");
@@ -5,6 +10,10 @@ const { v4: uuidv4 } = require("uuid");
 const dumbPasswords = require("dumb-passwords");
 const validator = require("email-validator");
 
+/**
+ * @param {object} o 
+ * @returns {*}
+ */
 const safeUserFields = (o) => {
   const {
     email,
@@ -25,8 +34,13 @@ const safeUserFields = (o) => {
 };
 /**
  * User
+ * @category saltcorn-data
  */
 class User {
+  /**
+   * User constructor
+   * @param {object} o 
+   */
   constructor(o) {
     this.email = o.email;
     this.password = o.password;
@@ -59,7 +73,7 @@ class User {
   /**
    * Get bcrypt hash for Password
    * @param pw - password string
-   * @returns {Promise<*>}
+   * @returns {Promise<string>}
    */
   static async hashPassword(pw) {
     return await bcrypt.hash(pw, 10);
@@ -68,7 +82,7 @@ class User {
   /**
    * Check password
    * @param pw - password string
-   * @returns {*}
+   * @returns {boolean}
    */
   checkPassword(pw) {
     return bcrypt.compareSync(pw, this.password);
@@ -92,7 +106,7 @@ class User {
    * Find or Create User
    * @param k
    * @param v
-   * @param uo
+   * @param {object} [uo = {}]
    * @returns {Promise<{session_object: {_attributes: {}}, _attributes: {}}|User|*|boolean|{error: string}|User>}
    */
   static async findOrCreateByAttribute(k, v, uo = {}) {
@@ -149,7 +163,7 @@ class User {
 
   /**
    * Create session object for user
-   * @returns {{role_id: number, language, id, email, tenant: *}}
+   * @type {{role_id: number, language, id, email, tenant: *}}
    */
   get session_object() {
     const so = {
@@ -183,7 +197,7 @@ class User {
    * Find users list
    * @param where - where object
    * @param selectopts - select options
-   * @returns {Promise<*>}
+   * @returns {Promise<User[]>}
    */
   static async find(where, selectopts) {
     const us = await db.select("users", where, selectopts);
@@ -260,7 +274,7 @@ class User {
 
   /**
    * Add new API token to user
-   * @returns {Promise<*|string>}
+   * @returns {Promise<string>}
    */
   async getNewAPIToken() {
     const api_token = uuidv4();
@@ -271,7 +285,7 @@ class User {
 
   /**
    * Remove API token for user
-   * @returns {Promise<null>}
+   * @returns {Promise<string>}
    */
   async removeAPIToken() {
     const api_token = null;
@@ -320,6 +334,9 @@ class User {
     return await u.set_to_verified();
   }
 
+  /**
+   * @returns {Promise<boolean>}
+   */
   async set_to_verified() {
     const upd = { verified_on: new Date() };
     const { getState } = require("../db/state");
@@ -397,7 +414,7 @@ class User {
 
   /**
    * Generate password
-   * @returns {*}
+   * @returns {string}
    */
   static generate_password() {
     const candidate = is.str.generate().split(" ").join("");
@@ -405,6 +422,10 @@ class User {
     if (candidate.length < 10) return User.generate_password();
     else return candidate;
   }
+
+  /**
+   * @returns {Promise<void>}
+   */
   async destroy_sessions() {
     if (!db.isSQLite) {
       const schema = db.getTenantSchema();
@@ -417,6 +438,10 @@ class User {
       );
     }
   }
+
+  /**
+   * @param {object} req 
+   */
   relogin(req) {
     req.login(this.session_object, function (err) {
       if (err) req.flash("danger", err);