@saltcorn/data 0.6.1-beta.0 → 0.6.1

package/base-plugin/viewtemplates/room.js

@@ -1,3 +1,8 @@
+/**
+ * @category saltcorn-data
+ * @module base-plugin/viewtemplates/room
+ * @subcategory base-plugin
+ */
 const Field = require("../../models/field");
 const Table = require("../../models/table");
 const Form = require("../../models/form");
@@ -30,6 +35,11 @@ const { getState } = require("../../db/state");
 const db = require("../../db");
 const { getForm, fill_presets } = require("./viewable_fields");
 
+/**
+ * 
+ * @param {object} req 
+ * @returns {Workflow}
+ */
 const configuration_workflow = (req) =>
   new Workflow({
     steps: [
@@ -160,6 +170,9 @@ const configuration_workflow = (req) =>
     ],
   });
 
+/**
+ * @returns {object[]}
+ */
 const get_state_fields = () => [
   {
     name: "id",
@@ -170,6 +183,23 @@ const get_state_fields = () => [
 ];
 const limit = 10;
 
+/**
+ * @param {string} table_id 
+ * @param {string} viewname 
+ * @param {object} optsOne
+ * @param {string} optsOne.participant_field,
+ * @param {string} optsOne.msg_relation
+ * @param {*} optsOne.msgsender_field
+ * @param {string} optsOne.msgview
+ * @param {string} optsOne.msgform
+ * @param {string} optsOne.participant_maxread_field
+ * @param {object} state 
+ * @param {object} optsTwo
+ * @param {object} optsTwo.req
+ * @param {object} optsTwo.res
+ * @returns {Promise<div>}
+ * @throws {InvalidConfiguration}
+ */
 const run = async (
   table_id,
   viewname,
@@ -274,6 +304,18 @@ const run = async (
   );
 };
 
+/**
+ * @param {*} table_id 
+ * @param {*} viewname 
+ * @param {object} optsOne 
+ * @param {string} optsOne.participant_field
+ * @param {string} optsOne.participant_maxread_field
+ * @param {body} body 
+ * @param {object} optsTwo 
+ * @param {object} optsTwo.req
+ * @param {object} optsTwo.res
+ * @returns {Promise<void>}
+ */
 const ack_read = async (
   table_id,
   viewname,
@@ -321,6 +363,23 @@ const ack_read = async (
     },
   };
 };
+
+/**
+ * @param {*} table_id 
+ * @param {*} viewname 
+ * @param {object} optsOne.
+ * @param {string} optsOne.participant_field
+ * @param {string} optsOne.msg_relation
+ * @param {*} optsOne.msgsender_field
+ * @param {string} optsOne.msgview
+ * @param {*} optsOne.msgform
+ * @param {*} optsOne.participant_maxread_field
+ * @param {object} body 
+ * @param {object} optsTwo 
+ * @param {object} optsTwo.req
+ * @param {object} optsTwo.res 
+ * @returns {Promise<object>}
+ */
 const fetch_older_msg = async (
   table_id,
   viewname,
@@ -384,6 +443,23 @@ const fetch_older_msg = async (
     },
   };
 };
+
+/**
+ * @param {*} table_id 
+ * @param {string} viewname 
+ * @param {object} optsOne
+ * @param {string} optsOne.participant_field
+ * @param {string} optsOne.msg_relation
+ * @param {*} optsOne.msgsender_field
+ * @param {string} optsOne.msgview
+ * @param {string} optsOne.msgform
+ * @param {string} optsOne.participant_maxread_field
+ * @param {*} body 
+ * @param {object} optsTwo
+ * @param {object} optsTwo.req
+ * @param {object} optsTwo.res
+ * @returns {Promise<object>}
+ */
 const submit_msg_ajax = async (
   table_id,
   viewname,
@@ -472,6 +548,18 @@ const submit_msg_ajax = async (
   }
 };
 
+/**
+ * @param {*} table_id 
+ * @param {string} viewname 
+ * @param {object} opts
+ * @param {*} opts.participant_field
+ * @param {string} opts.msg_relation,
+ * @param {string} opts.msgsender_field,
+ * @param {string} opts.msgview,
+ * @param {*} opts.msgform,
+ * @param {*} opts.participant_maxread_field,
+ * @returns {object[]}
+ */
 const virtual_triggers = (
   table_id,
   viewname,
@@ -514,14 +602,25 @@ const virtual_triggers = (
   ];
 };
 module.exports = {
+  /** @type {string} */
   name: "Room",
+  /** @type {string} */
   description: "Real-time space for chat",
   configuration_workflow,
   run,
   get_state_fields,
+  /** @type {boolean} */
   display_state_form: false,
   routes: { submit_msg_ajax, ack_read, fetch_older_msg },
+  /** @type {boolean} */
   noAutoTest: true,
+  /**
+   * @param {object} opts
+   * @param {object} opts.participant_field
+   * @param {string} room_id 
+   * @param {object} user 
+   * @returns {Promise<object>}
+   */
   authorize_join: async ({ participant_field }, room_id, user) => {
     if (!user) return false;
     const [
@@ -539,6 +638,7 @@ module.exports = {
     return !!partRow;
   },
   virtual_triggers,
+  /** @returns {object[]} */
   getStringsForI18n() {
     return [];
   },

package/base-plugin/viewtemplates/show.js

@@ -1,3 +1,8 @@
+/**
+ * @category saltcorn-data
+ * @module base-plugin/viewtemplates/show
+ * @subcategory base-plugin
+ */
 const Form = require("../../models/form");
 const User = require("../../models/user");
 const Field = require("../../models/field");
@@ -49,6 +54,10 @@ const { get_expression_function } = require("../../models/expression");
 const { get_base_url } = require("../../models/config");
 const Library = require("../../models/library");
 
+/**
+ * @param {object} req 
+ * @returns {Workflow}
+ */
 const configuration_workflow = (req) =>
   new Workflow({
     steps: [
@@ -181,6 +190,10 @@ const configuration_workflow = (req) =>
       },
     ],
   });
+
+/**
+ * @returns {object[]}
+ */
 const get_state_fields = () => [
   {
     name: "id",
@@ -190,8 +203,21 @@ const get_state_fields = () => [
   },
 ];
 
+/** @type {function} */
 const initial_config = initial_config_all_fields(false);
 
+/**
+ * @param {string} table_id 
+ * @param {string} viewname 
+ * @param {object} opts
+ * @param {object[]} opts.columns
+ * @param {object} opts.layout
+ * @param {string} [opts.page_title]
+ * @param {boolean} opts.page_title_formula
+ * @param {object} state 
+ * @param {object} extra 
+ * @returns {Promise<string>}
+ */
 const run = async (
   table_id,
   viewname,
@@ -216,6 +242,7 @@ const run = async (
   const { joinFields, aggregations } = picked_fields_to_query(columns, fields);
   readState(state, fields);
   const qstate = await stateFieldsToWhere({ fields, state, approximate: true });
+  if (Object.keys(qstate).length === 0) return extra.req.__("No row selected");
   const rows = await tbl.getJoinedRows({
     where: qstate,
     joinFields,
@@ -268,6 +295,12 @@ const run = async (
   return page_title_preamble + rendered;
 };
 
+/**
+ * @param {object} opts
+ * @param {object} opts.layout
+ * @param {object[]} opts.fields
+ * @returns {Promise<void>}
+ */
 const set_join_fieldviews = async ({ layout, fields }) => {
   await traverse(layout, {
     join_field: async (segment) => {
@@ -298,6 +331,16 @@ const set_join_fieldviews = async ({ layout, fields }) => {
   });
 };
 
+/**
+ * @param {object} table 
+ * @param {string} viewname 
+ * @param {object} opts
+ * @param {object[]} opts.columns
+ * @param {object} opts.layout
+ * @param {object} extra 
+ * @param {object[]} rows 
+ * @returns {Promise<string>}
+ */
 const renderRows = async (
   table,
   viewname,
@@ -387,6 +430,16 @@ const renderRows = async (
   });
 };
 
+/**
+ * @param {number} table_id 
+ * @param {string} viewname 
+ * @param {object} opts
+ * @param {object[]} opts.columns
+ * @param {object} opts.layout
+ * @param {object} state 
+ * @param {object} extra 
+ * @returns {Promise<object[]>}
+ */
 const runMany = async (
   table_id,
   viewname,
@@ -423,6 +476,18 @@ const runMany = async (
   return rendered.map((html, ix) => ({ html, row: rows[ix] }));
 };
 
+/**
+ * @param {object} row 
+ * @param {Field[]} fields 
+ * @param {Layout} layout0 
+ * @param {string} viewname 
+ * @param {Table} table 
+ * @param {Role} role 
+ * @param {object} req 
+ * @param {object} is_owner 
+ * @throws {Error}
+ * @returns {Layout}
+ */
 const render = (row, fields, layout0, viewname, table, role, req, is_owner) => {
   const evalMaybeExpr = (segment, key, fmlkey) => {
     if (segment.isFormula && segment.isFormula[fmlkey || key]) {
@@ -560,6 +625,19 @@ const render = (row, fields, layout0, viewname, table, role, req, is_owner) => {
     is_owner,
   });
 };
+
+/**
+ * @param {number} table_id 
+ * @param {*} viewname 
+ * @param {object} opts
+ * @param {object[]} opts.columns
+ * @param {*} opts.layout
+ * @param {*} body 
+ * @param {object} optsTwo
+ * @param {object} optsTwo.req 
+ * @param {*} optsTwo.res
+ * @returns {Promise<object>}
+ */
 const run_action = async (
   table_id,
   viewname,
@@ -587,7 +665,9 @@ const run_action = async (
 };
 
 module.exports = {
+  /** @type {string} */
   name: "Show",
+  /** @type {string} */
   description: "Show a single row, with flexible layout",
   get_state_fields,
   configuration_workflow,
@@ -595,8 +675,14 @@ module.exports = {
   runMany,
   renderRows,
   initial_config,
+  /** @type {boolean} */
   display_state_form: false,
   routes: { run_action },
+  /**
+   * @param {object} opts
+   * @param {object} opts.layout
+   * @returns {string[]}
+   */
   getStringsForI18n({ layout }) {
     return getStringsForI18n(layout);
   },

package/base-plugin/viewtemplates/viewable_fields.js

@@ -1,3 +1,8 @@
+/**
+ * @category saltcorn-data
+ * @module base-plugin/viewtemplates/viewable_fields
+ * @subcategory base-plugin
+ */
 const { post_btn, link } = require("@saltcorn/markup");
 const { text, a, i } = require("@saltcorn/markup/tags");
 const { getState } = require("../../db/state");
@@ -11,6 +16,16 @@ const { traverseSync } = require("../../models/layout");
 const { structuredClone } = require("../../utils");
 const db = require("../../db");
 
+/** 
+ * @function
+ * @param {string} viewname
+ * @param {Table|object} table
+ * @param {string} action_name
+ * @param {object} r
+ * @param {string} colId missing in contract
+ * @param {colIdNm} colIdNm missing in contract
+ * @returns {any}
+ */
 const action_url = contract(
   is.fun([is.str, is_tablely, is.str, is.obj()], is.any),
   (viewname, table, action_name, r, colId, colIdNm) => {
@@ -26,6 +41,23 @@ const action_url = contract(
   }
 );
 
+/**
+ * @param {string} url 
+ * @param {object} req 
+ * @param {object} opts
+ * @param {string} opts.action_name
+ * @param {string} opts.action_label
+ * @param {*} opts.confirm
+ * @param {*} opts.rndid
+ * @param {string} opts.action_style
+ * @param {number} opts.action_size
+ * @param {*} opts.action_icon
+ * @param {string} opts.action_bgcol
+ * @param {string} opts.action_bordercol
+ * @param {string} opts.action_textcol
+ * @param {*} __ 
+ * @returns {object}
+ */
 const action_link = (
   url,
   req,
@@ -72,6 +104,12 @@ const action_link = (
       btnClass: `${action_style || "btn-primary"} ${action_size || ""}`,
     });
 };
+
+/**
+ * @function
+ * @param {Field[]} fields
+ * @returns {function}
+ */
 const get_view_link_query = contract(
   is.fun(is.array(is.class("Field")), is.fun(is.obj(), is.str)),
   (fields) => {
@@ -91,6 +129,17 @@ const get_view_link_query = contract(
   }
 );
 
+/**
+ * @function
+ * @param {object} opts
+ * @param {string} opts.link_text
+ * @param {boolean} opts.link_text_formula missing in contract
+ * @param {string} [opts.link_url]
+ * @param {boolean} opts.link_url_formula
+ * @param {boolean} opts.link_target_blank
+ * @param {Field[]} fields
+ * @returns {object}
+ */
 const make_link = contract(
   is.fun(
     [is.obj({ link_text: is.str }), is.array(is.class("Field"))],
@@ -123,6 +172,11 @@ const make_link = contract(
     };
   }
 );
+
+/**
+ * @param {string} s 
+ * @returns {object}
+ */
 const parse_view_select = (s) => {
   const colonSplit = s.split(":");
   if (colonSplit.length === 1) return { type: "Own", viewname: s };
@@ -143,6 +197,23 @@ const parse_view_select = (s) => {
 };
 
 //todo: use above to simplify code
+/** 
+ * @function
+ * @param {object} opts
+ * @param {string} opts.view,
+ * @param {object} opts.view_label missing in contract
+ * @param {object} opts.in_modal
+ * @param {object} opts.view_label_formula
+ * @param {string} [opts.link_style = ""]
+ * @param {string} [opts.link_size = ""]
+ * @param {string} [opts.link_icon = ""]
+ * @param {string} [opts.textStyle = ""]
+ * @param {string} [opts.link_bgcol]
+ * @param {string} [opts.link_bordercol]
+ * @param {string} [opts.link_textcol]
+ * @param {Field[]} fields
+ * @returns {object}
+ */
 const view_linker = contract(
   is.fun(
     [is.obj({ view: is.str }), is.array(is.class("Field"))],
@@ -266,12 +337,27 @@ const view_linker = contract(
   }
 );
 
+/**
+ * @param {string} nm 
+ * @returns {boolean}
+ */
 const action_requires_write = (nm) => {
   if (!nm) return false;
   if (nm === "Delete") return true;
   if (nm.startsWith("Toggle")) return true;
 };
 
+/** 
+ * @function
+ * @param {string} viewname
+ * @param {Table|object} table
+ * @param {Fields[]} fields
+ * @param {object[]} columns
+ * @param {boolean} isShow
+ * @param {object} req
+ * @param {*} __
+ * @returns {object[]}
+ */
 const get_viewable_fields = contract(
   is.fun(
     [
@@ -439,6 +525,12 @@ const get_viewable_fields = contract(
       })
       .filter((v) => !!v)
 );
+
+/**
+ * @param {string} fname 
+ * @param {object} req 
+ * @returns {string}
+ */
 const sortlinkForName = (fname, req) => {
   const { _sortby, _sortdesc } = req.query || {};
   const desc =
@@ -449,6 +541,14 @@ const sortlinkForName = (fname, req) => {
       : "true";
   return `javascript:sortby('${text(fname)}', ${desc})`;
 };
+
+/**
+ * @param {object} column 
+ * @param {object} f 
+ * @param {object} req 
+ * @param {*} __ 
+ * @returns {string}
+ */
 const headerLabelForName = (column, f, req, __) => {
   const label = column.header_label
     ? text(__(column.header_label))
@@ -462,6 +562,14 @@ const headerLabelForName = (column, f, req, __) => {
       : i({ class: "fas fa-caret-up" });
   return label + arrow;
 };
+
+/** 
+ * @function
+ * @param {Field[]} fields
+ * @param {object} state
+ * @param {boolean} [fuzzyStrings]
+ * @returns {object}
+ */
 const splitUniques = contract(
   is.fun(
     [is.array(is.class("Field")), is.obj(), is.maybe(is.bool)],
@@ -487,6 +595,16 @@ const splitUniques = contract(
     return { uniques, nonUniques };
   }
 );
+
+/**
+ * @param {object} table 
+ * @param {string} viewname 
+ * @param {object[]} [columns] 
+ * @param {object} layout0 
+ * @param {boolean} id 
+ * @param {object} req 
+ * @returns {Promise<Form>}
+ */
 const getForm = async (table, viewname, columns, layout0, id, req) => {
   const fields = await table.getFields();
 
@@ -556,6 +674,12 @@ const getForm = async (table, viewname, columns, layout0, id, req) => {
   return form;
 };
 
+/**
+ * @param {object} table 
+ * @param {object} req 
+ * @param {object} fixed 
+ * @returns {Promise<object>}
+ */
 const fill_presets = async (table, req, fixed) => {
   const fields = await table.getFields();
   Object.keys(fixed || {}).forEach((k) => {

package/contracts.js

@@ -1,5 +1,12 @@
+/**
+ * @category saltcorn-data
+ * @module contract
+ */
 const { contract, is } = require("contractis");
 
+/**
+ * @type {function}
+ */
 const fieldlike = is.obj(
   {
     name: is.str,
@@ -9,8 +16,14 @@ const fieldlike = is.obj(
   (o) => o.type || o.input_type
 );
 
+/**
+ * @type {function}
+ */
 const is_header = is.obj({ script: is.maybe(is.str) });
 
+/**
+ * @type {function}
+ */
 const is_menu_item = is.obj({
   label: is.str,
   link: is.maybe(is.str),
@@ -24,6 +37,9 @@ const is_menu_item = is.obj({
   ),
 });
 
+/**
+ * @type {function}
+ */
 const is_layout_container = is.or(
   is.eq(null),
   is.obj({
@@ -34,6 +50,9 @@ const is_layout_container = is.or(
   is.obj({})
 );
 
+/**
+ * @type {function}
+ */
 const is_layout = is.or(
   is.obj(
     {
@@ -61,6 +80,9 @@ const is_layout = is.or(
   is.and(is_layout_container, is.obj({}))
 );
 
+/**
+ * @type {function}
+ */
 const is_plugin_wrap_arg = is.obj({
   title: is.str,
   body: is.or(is.str, is_layout),
@@ -81,6 +103,9 @@ const is_plugin_wrap_arg = is.obj({
   headers: is.array(is_header),
 });
 
+/**
+ * @type {function}
+ */
 const is_plugin_authwrap_arg = is.obj({
   title: is.str,
   form: is.class("Form"),
@@ -106,8 +131,14 @@ const is_plugin_authwrap_arg = is.obj({
   }),
 });
 
+/**
+ * @type {function}
+ */
 const is_plugin_wrap = is.fun(is_plugin_wrap_arg, is.str);
 
+/**
+ * @type {function}
+ */
 const is_plugin_layout = is.obj({
   wrap: is_plugin_wrap,
   authWrap: is.maybe(is.fun(is_plugin_authwrap_arg, is.str)),
@@ -115,6 +146,9 @@ const is_plugin_layout = is.obj({
 
 const is_attribute = is.obj({ name: is.str, type: is.str, required: is.bool });
 
+/**
+ * @type {function}
+ */
 const is_plugin_type = is.obj({
   name: is.str,
   sql_name: is.str,
@@ -138,6 +172,9 @@ const is_plugin_type = is.obj({
   presets: is.maybe(is.objVals(is.fun([], is.any))),
 });
 
+/**
+ * @type {function}
+ */
 const is_table_query = is.obj({
   joinFields: is.maybe(is.objVals(is.obj({ ref: is.str, target: is.str }))),
   aggregations: is.maybe(
@@ -157,6 +194,9 @@ const is_table_query = is.obj({
   orderDesc: is.maybe(is.bool),
 });
 
+/**
+ * @type {function}
+ */
 const is_viewtemplate = is.obj({
   name: is.str,
   get_state_fields: is.maybe(
@@ -183,8 +223,16 @@ const is_plugin_function = is.obj({
   isAsync: is.maybe(is.bool),
 });
 
+/**
+ * 
+ * @param {*} a 
+ * @returns {function}
+ */
 const is_maybe_cfg_fun = (a) => is.or(is.fun(is.obj, a), a, is.undefined);
 
+/**
+ * @type {function}
+ */
 const is_plugin = is.obj({
   sc_plugin_api_version: is.posint,
   headers: is_maybe_cfg_fun(is.array(is_header)),
@@ -217,6 +265,9 @@ const is_plugin = is.obj({
   dependencies: is.maybe(is.array(is.str)),
 });
 
+/**
+ * @type {function}
+ */
 const is_pack = is.obj({
   tables: is.array(is.obj({ name: is.str, fields: is.array(fieldlike) })),
   views: is.array(
@@ -224,6 +275,10 @@ const is_pack = is.obj({
   ),
   plugins: is.array(is.obj({ name: is.str, source: is.str, location: is.str })),
 });
+
+/**
+ * @type {function}
+ */
 const is_column = is.obj({
   type: is.one_of([
     "Action",
@@ -235,6 +290,9 @@ const is_column = is.obj({
   ]),
 });
 
+/**
+ * @type {function}
+ */
 const is_tablely = is.or(is.class("Table"), is.obj({ external: is.eq(true) }));
 
 module.exports = {