@saltcorn/data 0.6.1-beta.0 → 0.6.1

package/models/form.js

@@ -1,8 +1,22 @@
+/**
+ * Role Database Access Layer
+ * @category saltcorn-data
+ * @module models/form
+ * @subcategory models
+ */
 const { contract, is } = require("contractis");
 const db = require("../db");
 const Field = require("./field");
 
+/**
+ * Form Class
+ * @category saltcorn-data
+ */
 class Form {
+  /**
+    * Constructor
+    * @param o
+    */
   constructor(o) {
     this.fields = o.fields.map((f) =>
       f.constructor.name === Object.name ? new Field(f) : f
@@ -32,6 +46,10 @@ class Form {
     if (o.validate) this.validate(o.validate);
     contract.class(this);
   }
+
+  /**
+   * @param {object} ks 
+   */
   hidden(...ks) {
     ks.forEach((k) => {
       !this.fields.map((f) => f.name).includes(k) &&
@@ -43,12 +61,19 @@ class Form {
         );
     });
   }
+
+  /**
+   * @param {boolean} [force_allow_none = false]
+   */
   async fill_fkey_options(force_allow_none = false) {
     for (const f of this.fields) {
       await f.fill_fkey_options(force_allow_none);
     }
   }
 
+  /**
+   * @returns {Promise<object>}
+   */
   async generate() {
     var r = {};
 
@@ -60,6 +85,10 @@ class Form {
     }
     return r;
   }
+
+  /**
+   * @type {string}
+   */
   get errorSummary() {
     let strs = [];
     Object.entries(this.errors).forEach(([k, v]) => {
@@ -67,6 +96,11 @@ class Form {
     });
     return strs.join("; ");
   }
+
+  /**
+   * @param {*} v 
+   * @returns {object}
+   */
   validate(v) {
     this.hasErrors = false;
     this.errors = {};

package/models/index.js

@@ -0,0 +1,42 @@
+// for the jsdoc documentation
+/**
+ * @category saltcorn-data
+ * @subcategory models
+ * @module models/index
+ */
+
+/**
+ * All files in the models module.
+ * @namespace models_overview
+ * @property {module:models/backup} backup
+ * @property {module:models/config} config
+ * @property {module:models/crash} crash
+ * @property {module:models/discovery} discovery
+ * @property {module:models/email} email
+ * @property {module:models/eventlog} eventlog
+ * @property {module:models/expression} expression
+ * @property {module:models/field} field
+ * @property {module:models/fieldrepeat} fieldrepeat
+ * @property {module:models/file} file
+ * @property {module:models/form} form
+ * @property {module:models/layout} layout
+ * @property {module:models/library} library
+ * @property {module:models/pack} pack
+ * @property {module:models/page} page
+ * @property {module:models/plugin} plugin
+ * @property {module:models/random} random
+ * @property {module:models/role} role
+ * @property {module:models/scheduler} scheduler
+ * @property {module:models/table_constraints} table_constraints
+ * @property {module:models/table} table
+ * @property {module:models/tenant} tenant
+ * @property {module:models/trigger} trigger
+ * @property {module:models/user} user
+ * @property {module:models/view} view
+ * @property {module:models/workflow} workflow
+ * 
+ * 
+ * @category saltcorn-data
+ * @subcategory models 
+ */
+

package/models/layout.js

@@ -1,5 +1,15 @@
+/**
+ * @category saltcorn-data
+ * @module models/layout
+ * @subcategory models
+ */
 const { getState } = require("../db/state");
 
+/**
+ * @param {object} layout 
+ * @param {object[]} visitors 
+ * @returns {void}
+ */
 const traverseSync = (layout, visitors) => {
   const go = (segment) => {
     if (!segment) return;
@@ -26,6 +36,11 @@ const traverseSync = (layout, visitors) => {
   go(layout);
 };
 
+/**
+ * @param {object} layout 
+ * @param {object[]} visitors 
+ * @returns {Promise<void>}
+ */
 const traverse = async (layout, visitors) => {
   const go = async (segment) => {
     if (!segment) return;
@@ -53,8 +68,17 @@ const traverse = async (layout, visitors) => {
   await go(layout);
 };
 
+/**
+ * @param {object} layout 
+ * @param {*} f 
+ * @returns {void}
+ */
 const eachView = (layout, f) => traverse(layout, { view: f });
 
+/**
+ * @param {object} layout 
+ * @returns {Promise<object[]>}
+ */
 const getViews = async (layout) => {
   const views = [];
   await eachView(layout, (segment) => {
@@ -62,6 +86,11 @@ const getViews = async (layout) => {
   });
   return views;
 };
+
+/**
+ * @param {object} layout 
+ * @returns {string[]}
+ */
 const getStringsForI18n = (layout) => {
   const strings = [];
   traverseSync(layout, {
@@ -82,6 +111,10 @@ const getStringsForI18n = (layout) => {
   return strings;
 };
 
+/**
+ * @param {object} layout 
+ * @param {object} locale 
+ */
 const translateLayout = (layout, locale) => {
   const appState = getState()
   const __ = (s) => appState.i18n.__({ phrase: s, locale }) || s;

package/models/library.js

@@ -1,8 +1,22 @@
+/**
+ * Library Database Access Layer
+ * @category saltcorn-data
+ * @module models/library
+ * @subcategory models
+ */
 const db = require("../db");
 const { contract, is } = require("contractis");
 const { traverseSync } = require("./layout");
 
+/**
+ * Library Class
+ * @category saltcorn-data
+ */
 class Library {
+  /**
+   * Library constructor
+   * @param {object} o 
+   */
   constructor(o) {
     this.id = o.id;
     this.name = o.name;
@@ -10,6 +24,10 @@ class Library {
     this.layout =
       typeof o.layout === "string" ? JSON.parse(o.layout) : o.layout;
   }
+
+  /**
+   * @param {object} lib_in 
+   */
   static async create(lib_in) {
     const lib = new Library(lib_in);
     await db.insert("_sc_library", {
@@ -18,19 +36,38 @@ class Library {
       layout: lib.layout,
     });
   }
+
+  /**
+   * @type {...*}
+   */
   get toJson() {
     const { id, ...rest } = this;
     return rest;
   }
+
+  /**
+   * @param {*} where 
+   * @param {*} selectopts 
+   * @returns {Library[]}
+   */
   static async find(where, selectopts) {
     const us = await db.select("_sc_library", where, selectopts);
     return us.map((u) => new Library(u));
   }
+
+  /**
+   * @param {*} where 
+   * @returns {Library}
+   */
   static async findOne(where) {
     const u = await db.selectMaybeOne("_sc_library", where);
     return u ? new Library(u) : u;
   }
 
+  /**
+   * @param {*} what 
+   * @returns {object}
+   */
   suitableFor(what) {
     let notPage, notShow, notEdit, notFilter;
     if (!this.layout) return false;
@@ -78,11 +115,18 @@ class Library {
     }[what];
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async delete() {
     const schema = db.getTenantSchemaPrefix();
     await db.query(`delete FROM ${schema}_sc_library WHERE id = $1`, [this.id]);
   }
 
+  /**
+   * @param {*} row
+   * @returns {Promise<void>}
+   */
   async update(row) {
     await db.update("_sc_library", row, this.id);
   }

package/models/pack.js

@@ -1,3 +1,8 @@
+/**
+ * @category saltcorn-data
+ * @module models/pack
+ * @subcategory models
+ */
 const Table = require("./table");
 const db = require("../db");
 const View = require("./view");
@@ -16,6 +21,11 @@ const Library = require("./library");
 
 const pack_fun = is.fun(is.str, is.promise(is.obj()));
 
+/**
+ * @function
+ * @param {string} name
+ * @returns {Promise<object>}
+ */
 const table_pack = contract(pack_fun, async (name) => {
   const table = await Table.findOne({ name });
   const fields = await table.getFields();
@@ -40,6 +50,11 @@ const table_pack = contract(pack_fun, async (name) => {
   };
 });
 
+/**
+ * @function
+ * @param {string} name
+ * @returns {Promise<object>}
+ */
 const view_pack = contract(pack_fun, async (name) => {
   const view = await View.findOne({ name });
   const table = await Table.findOne({ id: view.table_id });
@@ -55,6 +70,11 @@ const view_pack = contract(pack_fun, async (name) => {
   };
 });
 
+/**
+ * @function
+ * @param {string} name
+ * @returns {Promise<object>}
+ */
 const plugin_pack = contract(pack_fun, async (name) => {
   const Plugin = require("./plugin");
   const plugin = await Plugin.findOne({ name });
@@ -67,6 +87,12 @@ const plugin_pack = contract(pack_fun, async (name) => {
     deploy_private_key: plugin.deploy_private_key,
   };
 });
+
+/**
+ * @function
+ * @param {string} name
+ * @returns {Promise<object>}
+ */
 const page_pack = contract(pack_fun, async (name) => {
   const page = await Page.findOne({ name });
   const root_page_for_roles = await page.is_root_page_for_roles();
@@ -81,17 +107,41 @@ const page_pack = contract(pack_fun, async (name) => {
     root_page_for_roles,
   };
 });
+
+/**
+ * @function
+ * @param {string} name
+ * @returns {Promise<object>}
+ */
 const library_pack = contract(pack_fun, async (name) => {
   const lib = await Library.findOne({ name });
   return lib.toJson;
 });
+
+/**
+ * @function
+ * @param {string} name
+ * @returns {Promise<object>}
+ */
 const trigger_pack = contract(pack_fun, async (name) => {
   const trig = await Trigger.findOne({ name });
   return trig.toJson;
 });
+
+/**
+ * @function
+ * @param {string} role
+ * @returns {Promise<object>}
+ */
 const role_pack = contract(pack_fun, async (role) => {
   return await Role.findOne({ role });
 });
+
+/**
+ * @function
+ * @param {string} pack
+ * @returns {Promise<boolean|object>}
+ */
 const can_install_pack = contract(
   is.fun(
     is_pack,
@@ -147,6 +197,12 @@ const can_install_pack = contract(
   }
 );
 
+/**
+ * @function
+ * @param {string} pack
+ * @param {string} name
+ * @returns {Promise<void>}
+ */
 const uninstall_pack = contract(
   is.fun([is_pack, is.str], is.promise(is.undefined)),
   async (pack, name) => {
@@ -188,6 +244,11 @@ const uninstall_pack = contract(
   }
 );
 
+/**
+ * @function
+ * @param {object} item
+ * @returns {Promise<void>}
+ */
 const add_to_menu = contract(
   is.fun(
     is.obj({ label: is.str, type: is.one_of(["View", "Page"]) }),
@@ -200,6 +261,14 @@ const add_to_menu = contract(
   }
 );
 
+/**
+ * @function
+ * @param {string} pack
+ * @param {string} [name]
+ * @param {function} loadAndSaveNewPlugin
+ * @param {boolean} [bare_tables = false]
+ * @returns {Promise<void>}
+ */
 const install_pack = contract(
   is.fun(
     [is_pack, is.maybe(is.str), is.fun(is_plugin, is.undefined)],
@@ -305,6 +374,12 @@ const install_pack = contract(
   }
 );
 
+/**
+ * @function
+ * @param {Date} date
+ * @param {string} [hours = 24]
+ * @returns {boolean}
+ */
 const is_stale = contract(
   is.fun([is.or(is.class("Date"), is.str), is.maybe(is.posint)], is.bool),
   (date, hours = 24) => {
@@ -314,6 +389,10 @@ const is_stale = contract(
   }
 );
 
+/**
+ * @function
+ * @returns {object[]}
+ */
 const fetch_available_packs = contract(
   is.fun([], is.promise(is.array(is.obj({ name: is.str })))),
   async () => {
@@ -332,6 +411,10 @@ const fetch_available_packs = contract(
   }
 );
 
+/**
+ * @function
+ * @returns {Promise<object[]>}
+ */
 const fetch_available_packs_from_store = contract(
   is.fun([], is.promise(is.array(is.obj({ name: is.str })))),
   async () => {
@@ -345,6 +428,11 @@ const fetch_available_packs_from_store = contract(
   }
 );
 
+/**
+ * @function
+ * @param {string} name
+ * @returns {Promise<object|null>}
+ */ 
 const fetch_pack_by_name = contract(
   is.fun(
     is.str,

package/models/page.js

@@ -1,7 +1,9 @@
 /**
- * Page Data Access Layer
+ * Page Database Access Layer
+ * @category saltcorn-data
+ * @module models/page
+ * @subcategory models
  */
-
 const db = require("../db");
 const { contract, is } = require("contractis");
 const View = require("./view");
@@ -26,8 +28,12 @@ const {
 
 /**
  * Page Class
+ * @category saltcorn-data
  */
 class Page {
+  /**
+   * @param {object} o
+   */
   constructor(o) {
     this.name = o.name;
     this.title = o.title;
@@ -50,6 +56,10 @@ class Page {
    * @returns {Promise<*>}
    */
   static async find(where, selectopts = { orderBy: "name", nocase: true }) {
+    if (selectopts.cached) {
+      const { getState } = require("../db/state");
+      return getState().pages.map((t) => new Page(t));
+    }
     const db_flds = await db.select("_sc_pages", where, selectopts);
     return db_flds.map((dbf) => new Page(dbf));
   }
@@ -136,7 +146,7 @@ class Page {
 
   /**
    * get menu label for page
-   * @returns {*|undefined}
+   * @type {string|undefined}
    */
   get menu_label() {
     const { getState } = require("../db/state");

package/models/plugin.js

@@ -1,3 +1,9 @@
+/**
+ * Plugin Database Access Layer
+ * @category saltcorn-data
+ * @module models/plugin
+ * @subcategory models
+ */
 const db = require("../db");
 const { contract, is } = require("contractis");
 const View = require("./view");
@@ -7,11 +13,12 @@ const { stringToJSON } = require("../utils");
 
 /**
  * Plugin Class
+ * @category saltcorn-data
  */
 class Plugin {
   /**
    * Plugin constructor
-   * @param o
+   * @param {object} o
    */
   constructor(o) {
     this.id = o.id ? +o.id : o.id;
@@ -99,7 +106,7 @@ class Plugin {
 
   /**
    * List of views relay on this plugin
-   * @returns {Promise<*[]|*>}
+   * @returns {Promise<View[]>}
    */
   async dependant_views() {
     const views = await View.find({});

package/models/random.js

@@ -1,3 +1,9 @@
+/**
+ * View Database Access Layer
+ * @category saltcorn-data
+ * @module models/random
+ * @subcategory models
+ */
 const View = require("./view");
 const Field = require("./field");
 const Table = require("./table");
@@ -7,6 +13,10 @@ const { initial_config_all_fields } = require("../plugin-helper");
 const { contract, is } = require("contractis");
 const db = require("../db");
 
+/**
+ * @param {object} [opts = {}]
+ * @returns {Promise<Table>}
+ */
 const random_table = async (opts = {}) => {
   const name = is
     .and(
@@ -41,6 +51,10 @@ const random_table = async (opts = {}) => {
   return table;
 };
 
+/**
+ * @param {Table} table 
+ * @returns {Promise<*>}
+ */
 const fill_table_row = async (table) => {
   const fields = await table.getFields();
   const row = {};
@@ -51,6 +65,13 @@ const fill_table_row = async (table) => {
   //console.log(fields, row);
   await table.tryInsertRow(row);
 };
+
+/**
+ * @param {string} type 
+ * @param {string[]} existing_fields 
+ * @throws {Error} 
+ * @returns {string}
+ */
 const random_expression = (type, existing_fields) => {
   const numField = existing_fields.find((f) =>
     ["Integer", "Float"].includes(f.type)
@@ -69,6 +90,12 @@ const random_expression = (type, existing_fields) => {
       throw new Error("random_expression: unknown type " + type);
   }
 };
+
+/**
+ * @param {string[]} existing_field_names 
+ * @param {Table} table 
+ * @returns {Promise<Field>}
+ */
 const random_field = async (existing_field_names, table) => {
   const tables = await Table.find({});
   const tables_with_data = [];
@@ -144,6 +171,11 @@ const random_field = async (existing_field_names, table) => {
   return f;
 };
 
+/**
+ * @param {Table} table 
+ * @param {string} viewtemplate 
+ * @returns {Promise<View>}
+ */
 const initial_view = async (table, viewtemplate) => {
   const configuration = await initial_config_all_fields(
     viewtemplate === "Edit"
@@ -160,6 +192,10 @@ const initial_view = async (table, viewtemplate) => {
   return view;
 };
 
+/**
+ * @param {Table} table 
+ * @returns {Promise<object[]>}
+ */
 const all_views = async (table) => {
   const list = await initial_view(table, "List");
   const edit = await initial_view(table, "Edit");

package/models/role.js

@@ -1,11 +1,30 @@
+/**
+ * Role Database Access Layer
+ * @category saltcorn-data
+ * @module models/role
+ * @subcategory models
+ */
 const db = require("../db");
 const { contract, is } = require("contractis");
+/**
+ * Role class
+ * @category saltcorn-data
+ */
 class Role {
+  /**
+   * Role constructor
+   * @param {object} o 
+   */
   constructor(o) {
     this.id = o.id;
     this.role = o.role;
     contract.class(this);
   }
+
+  /**
+   * @param {*} uo 
+   * @returns {Role}
+   */
   static async create(uo) {
     const u = new Role(uo);
 
@@ -18,20 +37,37 @@ class Role {
     return u;
   }
 
+  /**
+   * @param {*} where 
+   * @param {*} selectopts 
+   * @returns {Promise<Role[]>}
+   */
   static async find(where, selectopts) {
     const us = await db.select("_sc_roles", where, selectopts);
     return us.map((u) => new Role(u));
   }
+
+  /**
+   * @param {*} where 
+   * @returns {Promise<Role>}
+   */
   static async findOne(where) {
     const u = await db.selectMaybeOne("_sc_roles", where);
     return u ? new Role(u) : u;
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async delete() {
     const schema = db.getTenantSchemaPrefix();
     await db.query(`delete FROM ${schema}_sc_roles WHERE id = $1`, [this.id]);
   }
 
+  /**
+   * @param {*} row 
+   * @returns {Promise<void>}
+   */
   async update(row) {
     await db.update("_sc_roles", row, this.id);
   }