@saltcorn/data 0.6.1-beta.0 → 0.6.1

package/db/connect.js

@@ -1,7 +1,10 @@
 /**
  * Controls Saltcorn configuration
- * @type {path.PlatformPath | path}
+ * @category saltcorn-data
+ * @module db/connect
+ * @subcategory db
  */
+
 const path = require("path");
 const fs = require("fs");
 const envPaths = require("env-paths");
@@ -13,13 +16,18 @@ const pathsWithApp = envPaths("saltcorn", { suffix: "" });
  * @type {string}
  */
 const defaultDataPath = pathsWithApp.data;
+
+/**
+ * @param {string|object} x 
+ * @returns {object}
+ */
 const stringToJSON = (x) => (typeof x === "string" ? JSON.parse(x) : x);
 /**
  * Get Git revision of Saltcorn source.
  * Required to work:
  *  - Git client installed,
  *  - Local git with repo Saltcorn sources.
- * @returns {null} - Return current Git commit
+ * @returns {string} - Return current Git commit
  */
 const getGitRevision = () => {
   let revision = null;
@@ -41,8 +49,8 @@ const getGitRevision = () => {
  * - File store path
  * - Saltcorn confuration inheritance and fixed configuration
  * For all parameters and priority see the code of function.
- * @param connSpec
- * @returns {{sc_version: string, connectionString: *, git_commit: *, version_tag: (*|string)}|{sqlite_path}|boolean}
+ * @param {object} [connSpec = {}]
+ * @returns {object|boolean}
  */
 const getConnectObject = (connSpec = {}) => {
   const git_commit = getGitRevision();
@@ -123,7 +131,7 @@ const getConfigFile = () => {
 };
 /**
  * Check that Saltcorn configured to use SQLite as database
- * @param connObj - connectin object
+ * @param {object} connObj - connectin object
  * @returns {boolean} - Returns true if Saltcorn configured to use SQLite as database
  */
 const is_sqlite = (connObj) => {

package/db/db.test.js

@@ -1,162 +1,8 @@
-const { sqlsanitize, mkWhere, sqlsanitizeAllowDots } = require("./internal");
 const db = require("./index.js");
 const Table = require("../models/table");
 
 afterAll(db.close);
 
-describe("sqlsanitize", () => {
-  it("should not alter valid name", () => {
-    expect(sqlsanitize("ffoo_oo")).toBe("ffoo_oo");
-  });
-  it("should remove spaces", () => {
-    expect(sqlsanitize(" ")).toBe("");
-  });
-  it("should remove chars from invalid name", () => {
-    expect(sqlsanitize("ffoo--oo--uu")).toBe("ffoooouu");
-  });
-  it("should not allow dots", () => {
-    expect(sqlsanitize("ffoo.oo")).toBe("ffoooo");
-  });
-  it("should allow dots when specified", () => {
-    expect(sqlsanitizeAllowDots("ffoo.oo")).toBe("ffoo.oo");
-  });
-  it("should allow quotes when dots specified", () => {
-    expect(sqlsanitizeAllowDots('ffoo."oo"')).toBe('ffoo."oo"');
-  });
-  it("should allow numbers", () => {
-    expect(sqlsanitize("ff1oo_oo")).toBe("ff1oo_oo");
-  });
-  it("should not allow numbers in initial position", () => {
-    expect(sqlsanitize("1ffoo_o1o")).toBe("_1ffoo_o1o");
-  });
-});
-
-describe("mkWhere", () => {
-  it("should empty on no arg", () => {
-    expect(mkWhere()).toStrictEqual({ values: [], where: "" });
-  });
-  it("should empty on null obj arg", () => {
-    expect(mkWhere({})).toStrictEqual({ values: [], where: "" });
-  });
-  it("should query json", () => {
-    expect(mkWhere({ foo: { json: ["bar", 5] } })).toStrictEqual({
-      values: [5],
-      where: `where "foo"->>'bar'=$1`,
-    });
-  });
-
-  it("should set id", () => {
-    expect(mkWhere({ id: 5 })).toStrictEqual({
-      values: [5],
-      where: 'where "id"=$1',
-    });
-    expect(mkWhere({ id: 5, hello: "world" })).toStrictEqual({
-      values: [5, "world"],
-      where: 'where "id"=$1 and "hello"=$2',
-    });
-  });
-  it("should query null", () => {
-    expect(mkWhere({ id: null })).toStrictEqual({
-      values: [],
-      where: 'where "id" is null',
-    });
-    expect(mkWhere({ id: null, foo: 1 })).toStrictEqual({
-      values: [1],
-      where: 'where "id" is null and "foo"=$1',
-    });
-    expect(mkWhere({ foo: 1, id: null })).toStrictEqual({
-      values: [1],
-      where: 'where "foo"=$1 and "id" is null',
-    });
-  });
-  it("should query lt/gt", () => {
-    expect(mkWhere({ id: { lt: 5 } })).toStrictEqual({
-      values: [5],
-      where: 'where "id"<$1',
-    });
-    expect(mkWhere({ id: { gt: 8 } })).toStrictEqual({
-      values: [8],
-      where: 'where "id">$1',
-    });
-    expect(mkWhere({ id: { lt: 5, equal: true } })).toStrictEqual({
-      values: [5],
-      where: 'where "id"<=$1',
-    });
-    expect(mkWhere({ id: { gt: 8, equal: true } })).toStrictEqual({
-      values: [8],
-      where: 'where "id">=$1',
-    });
-    expect(mkWhere({ id: [{ gt: 0 }, { lt: 10 }] })).toStrictEqual({
-      values: [0, 10],
-      where: 'where "id">$1 and "id"<$2',
-    });
-    expect(mkWhere({ id: { or: [{ gt: 10 }, { lt: 5 }] } })).toStrictEqual({
-      values: [10, 5],
-      where: 'where ("id">$1 or "id"<$2)',
-    });
-  });
-  it("should query subselect", () => {
-    expect(
-      mkWhere({
-        id: [{ inSelect: { table: "foo", field: "bar", where: { baz: 7 } } }],
-      })
-    ).toStrictEqual({
-      values: [7],
-      where: 'where "id" in (select bar from foo where "baz"=$1)',
-    });
-    expect(
-      mkWhere({
-        age: 45,
-        id: [{ inSelect: { table: "foo", field: "bar", where: { baz: 7 } } }],
-        name: "Alice",
-      })
-    ).toStrictEqual({
-      values: [45, 7, "Alice"],
-      where: `where "age"=$1 and "id" in (select bar from foo where "baz"=$2) and "name"=$3`,
-    });
-  });
-  it("should query or", () => {
-    expect(mkWhere({ or: [{ id: 5 }, { x: 7 }] })).toStrictEqual({
-      values: [5, 7],
-      where: 'where ("id"=$1 or "x"=$2)',
-    });
-    expect(mkWhere({ or: [{ id: 5 }, { x: { gt: 7 } }] })).toStrictEqual({
-      values: [5, 7],
-      where: 'where ("id"=$1 or "x">$2)',
-    });
-    expect(mkWhere({ or: [{ id: 5 }, { x: 7, y: 8 }] })).toStrictEqual({
-      values: [5, 7, 8],
-      where: 'where ("id"=$1 or "x"=$2 and "y"=$3)',
-    });
-    expect(mkWhere({ not: { id: 5 } })).toStrictEqual({
-      values: [5],
-      where: 'where not ("id"=$1)',
-    });
-    expect(mkWhere({ not: { id: 5, y: 1 } })).toStrictEqual({
-      values: [5, 1],
-      where: 'where not ("id"=$1 and "y"=$2)',
-    });
-    expect(mkWhere({ not: { y: { in: [1, 2, 3] } } })).toStrictEqual({
-      values: [[1, 2, 3]],
-      where: 'where not ("y" = ANY ($1))',
-    });
-    expect(mkWhere({ y: { in: [1, 2, 3] } })).toStrictEqual({
-      values: [[1, 2, 3]],
-      where: 'where "y" = ANY ($1)',
-    });
-    /*
-    TODO
-    expect(mkWhere([{ id: 5 }, { x: 7 }])).toStrictEqual({
-      values: [5, 7],
-      where: 'where "id"=$1 and "x"=$2',
-    });
-    expect(mkWhere([{ or: [{ id: 5 }, { x: 7 }] }, { z: 9 }])).toStrictEqual({
-      values: [5, 7, 9],
-      where: 'where ("id"=$1 or "x"=$2) and "z"=$3',
-    });*/
-  });
-});
-
 describe("where", () => {
   it("should support in", async () => {
     await Table.create("myothertable");

package/db/fixtures.js

@@ -1,3 +1,9 @@
+/**
+ * init fixtures
+ * @category saltcorn-data
+ * @module db/fixtures
+ * @subcategory db
+ */
 const db = require(".");
 const { getState } = require("./state");
 const Table = require("../models/table");
@@ -8,7 +14,13 @@ const User = require("../models/user");
 const Page = require("../models/page");
 const fs = require("fs").promises;
 
-module.exports = async () => {
+module.exports = 
+/**
+ * @function
+ * @name "module.exports function"
+ * @returns {Promise<void>}
+ */
+async () => {
   getState().registerPlugin("base", require("../base-plugin"));
   const table = await Table.create("books", {
     min_role_read: 10,

package/db/index.js

@@ -1,21 +1,60 @@
+/**
+ * init fixtures
+ * @category saltcorn-data
+ * @module db/index
+ * @subcategory db
+ */
+
+/**
+ * All files in the db module.
+ * @namespace db_overview
+ * @property {module:db/connect} connect
+ * @property {module:db/fixtures} fixtures
+ * @property {module:db/reset_schema} reset_schema
+ * @property {module:db/state} state
+ * @property {module:db/connect} connect
+ * 
+ * @category saltcorn-data
+ * @subcategory db 
+ */
 const { getConnectObject, is_sqlite } = require("./connect");
-const { sqlsanitize, mkWhere } = require("./internal");
+const { sqlsanitize, mkWhere } = require("@saltcorn/db-common/internal");
 var connectObj = getConnectObject();
 
-const dbmodule = is_sqlite(connectObj) ? require("./sqlite") : require("./pg");
+/** @type {db/sqlite|db/pg|null} */
+let dbmodule = null;
+try {
+  dbmodule = is_sqlite(connectObj) ? 
+    require("@saltcorn/sqlite/sqlite")(getConnectObject) :
+    require("@saltcorn/postgres/postgres")(getConnectObject);
+} catch(e) {
+  console.log("No database package found.")
+  throw e;
+}
 
-const tenant = require("./tenants");
+/** @type {db/tenant} */
+const tenant = require("@saltcorn/db-common/tenants")(getConnectObject());
 
+/** @type {boolean} */
 const isSQLite = is_sqlite(connectObj);
 
+/** 
+ * @returns {string} 
+ */
 const getTenantSchemaPrefix = () =>
   isSQLite ? "" : `"${tenant.getTenantSchema()}".`;
+
 module.exports = {
   ...tenant,
   sqlsanitize,
   connectObj,
   isSQLite,
   ...dbmodule,
+  /**
+   * @param {object} q 
+   * @returns {function}
+   */
   mkWhere: (q) => mkWhere(q, isSQLite),
   getTenantSchemaPrefix,
 };
+

package/db/reset_schema.js

@@ -1,4 +1,15 @@
+/**
+ * @category saltcorn-data
+ * @module db/reset_schema
+ * @subcategory db
+ */
+
 //https://stackoverflow.com/a/21247009
+/**
+ * @param {boolean} dontDrop 
+ * @param {string} schema0 
+ * @returns {Promise<void>}
+ */
 const reset = async (dontDrop = false, schema0) => {
   const db = require(".");
   const { migrate } = require("../migrate");

package/db/state.js

@@ -1,8 +1,10 @@
 /**
  * State of Saltcorn
  * Keeps cache for main objects
+ * @category saltcorn-data
+ * @module db/state
+ * @subcategory db
  */
-
 const { contract, is } = require("contractis");
 const {
   is_plugin_wrap,
@@ -19,7 +21,11 @@ const { migrate } = require("../migrate");
 const File = require("../models/file");
 const Trigger = require("../models/trigger");
 const View = require("../models/view");
-const { getAllTenants, createTenant } = require("../models/tenant");
+const {
+  getAllTenants,
+  createTenant,
+  copy_tenant_template,
+} = require("../models/tenant");
 const {
   getAllConfigOrDefaults,
   setConfig,
@@ -32,14 +38,23 @@ const { I18n } = require("i18n");
 const path = require("path");
 const fs = require("fs");
 
+/**
+ * @param {object} v
+ * @returns {void}
+ */
 const process_send = (v) => {
   if (process.send) process.send(v);
 };
 
 /**
- * State class
+ * State Class
+ * @category saltcorn-data
  */
 class State {
+  /**
+   * State constructor
+   * @param {string} tenant description
+   */
   constructor(tenant) {
     this.tenant = tenant;
     this.views = [];
@@ -78,8 +93,8 @@ class State {
   /**
    * Get Layout by user
    * Based on role of user
-   * @param user
-   * @returns {unknown}
+   * @param {object} user
+   * @returns {object}
    */
   getLayout(user) {
     const role_id = user ? +user.role_id : 10;
@@ -94,6 +109,7 @@ class State {
 
   /**
    * Refresh State cache for all Saltcorn main objects
+   * @param {boolean} noSignal
    * @returns {Promise<void>}
    */
   async refresh(noSignal) {
@@ -104,8 +120,10 @@ class State {
     await this.refresh_pages(noSignal);
     await this.refresh_config(noSignal);
   }
+
   /**
    * Refresh config
+   * @param {boolean} noSignal
    * @returns {Promise<void>}
    */
   async refresh_config(noSignal) {
@@ -117,6 +135,10 @@ class State {
     if (!noSignal)
       process_send({ refresh: "config", tenant: db.getTenantSchema() });
   }
+
+  /**
+   * @returns {Promise<void>}
+   */
   async refresh_i18n() {
     const localeDir = path.join(__dirname, "..", "app-locales", this.tenant);
     try {
@@ -144,6 +166,7 @@ class State {
 
   /**
    * Refresh views
+   * @param {boolean} noSignal
    * @returns {Promise<void>}
    */
   async refresh_views(noSignal) {
@@ -166,6 +189,7 @@ class State {
 
   /**
    * Refresh triggers
+   * @param {boolean} noSignal
    * @returns {Promise<void>}
    */
   async refresh_triggers(noSignal) {
@@ -176,6 +200,7 @@ class State {
 
   /**
    * Refresh pages
+   * @param {boolean} noSignal
    * @returns {Promise<void>}
    */
   async refresh_pages(noSignal) {
@@ -187,6 +212,7 @@ class State {
 
   /**
    * Refresh files
+   * @param {boolean} noSignal
    * @returns {Promise<void>}
    */
   // todo what will be if there are a lot of files? Yes, there are cache only ids of files.
@@ -202,6 +228,7 @@ class State {
 
   /**
    * Refresh tables & fields
+   * @param {boolean} noSignal
    * @returns {Promise<void>}
    */
   async refresh_tables(noSignal) {
@@ -244,9 +271,9 @@ class State {
 
   /**
    * Get config parameter by key
-   * @param key - key of config paramter
-   * @param def - default value
-   * @returns {*}
+   * @param {string} key - key of config paramter
+   * @param {string} [def] - default value
+   * @returns {string}
    */
   getConfig(key, def) {
     const fixed = db.connectObj.fixed_configuration[key];
@@ -264,9 +291,9 @@ class State {
 
   /**
    * Get copy of config parameter
-   * @param key - key of parameter
-   * @param def - default value
-   * @returns {any}
+   * @param {sring} key - key of parameter
+   * @param {string} [def] - default value
+   * @returns {string}
    */
   getConfigCopy(key, def) {
     return structuredClone(this.getConfig(key, def));
@@ -275,8 +302,8 @@ class State {
   /**
    *
    * Set value of config parameter
-   * @param key - key of parameter
-   * @param value - value of parameter
+   * @param {string} key - key of parameter
+   * @param {string} value - value of parameter
    * @returns {Promise<void>}
    */
   async setConfig(key, value) {
@@ -294,7 +321,7 @@ class State {
 
   /**
    * Delete config parameter by key
-   * @param key - key of parameter
+   * @param {string} key - key of parameter
    * @returns {Promise<void>}
    */
   async deleteConfig(...keys) {
@@ -306,11 +333,13 @@ class State {
   }
 
   /**
-   * Registre plugin
-   * @param name
-   * @param plugin
-   * @param cfg
-   * @param location
+   * Register plugin
+   * @param {string} name
+   * @param {object} plugin
+   * @param {*} cfg
+   * @param {*} location
+   * @param {string} modname
+   * @returns {void}
    */
   registerPlugin(name, plugin, cfg, location, modname) {
     this.plugins[name] = plugin;
@@ -381,7 +410,7 @@ class State {
 
   /**
    * Get type names
-   * @returns {string[]}
+   * @type {string[]}
    */
   get type_names() {
     return Object.keys(this.types);
@@ -389,7 +418,7 @@ class State {
 
   /**
    * Add type
-   * @param t
+   * @param {object} t
    */
   addType(t) {
     this.types[t.name] = {
@@ -403,7 +432,8 @@ class State {
 
   /**
    * Remove plugin
-   * @param name
+   * @param {string} name
+   * @param {boolean} noSignal
    * @returns {Promise<void>}
    */
   async remove_plugin(name, noSignal) {
@@ -415,6 +445,7 @@ class State {
 
   /**
    * Reload plugins
+   * @param {boolean} noSignal
    * @returns {Promise<void>}
    */
   async refresh_plugins(noSignal) {
@@ -441,6 +472,9 @@ class State {
       process_send({ refresh: "plugins", tenant: db.getTenantSchema() });
   }
 
+  /**
+   * @returns {string[]}
+   */
   getStringsForI18n() {
     const strings = [];
     this.views.forEach((v) => strings.push(...v.getStringsForI18n()));
@@ -452,10 +486,18 @@ class State {
     );
   }
 
+  /**
+   *
+   * @param {function} f
+   */
   setRoomEmitter(f) {
     this.roomEmitter = f;
   }
 
+  /**
+   *
+   * @param {*} args
+   */
   emitRoom(...args) {
     if (this.roomEmitter) this.roomEmitter(...args);
   }
@@ -483,6 +525,11 @@ State.contract = {
 const singleton = new State("public");
 
 // return current State object
+
+/**
+ * @function
+ * @returns {State}
+ */
 const getState = contract(
   is.fun([], is.or(is.class("State"), is.eq(undefined))),
   () => {
@@ -497,14 +544,17 @@ const getState = contract(
 var tenants = { public: singleton };
 // list of tenants with other domains
 const otherdomaintenants = {};
+
 /**
  * Get other domain tenant
- * @param hostname
+ * @param {string} hostname
+ * @returns {object}
  */
 const get_other_domain_tenant = (hostname) => otherdomaintenants[hostname];
 /**
  * Get tenant
- * @param ten
+ * @param {string} ten
+ * @returns {object}
  */
 const getTenant = (ten) => {
   //console.log({ ten, tenants });
@@ -512,8 +562,8 @@ const getTenant = (ten) => {
 };
 /**
  * Remove protocol (http:// or https://) from domain url
- * @param url
- * @returns {*}
+ * @param {string} url
+ * @returns {string}
  */
 const get_domain = (url) => {
   const noproto = url.replace("https://", "").replace("http://", "");
@@ -522,8 +572,8 @@ const get_domain = (url) => {
 /**
  * Set tenant base url???
  * From my point of view it just add tenant to list of otherdomaintenant
- * @param tenant_subdomain
- * @param value - new
+ * @param {object} tenant_subdomain
+ * @param {string} [value] - new
  */
 const set_tenant_base_url = (tenant_subdomain, value) => {
   const root_domain = get_domain(singleton.configs.base_url.value);
@@ -535,8 +585,8 @@ const set_tenant_base_url = (tenant_subdomain, value) => {
 };
 /**
  * Switch to multi_tenant
- * @param plugin_loader
- * @param disableMigrate - if true then dont migrate db
+ * @param {object} plugin_loader
+ * @param {boolean} disableMigrate - if true then dont migrate db
  * @returns {Promise<void>}
  */
 const init_multi_tenant = async (plugin_loader, disableMigrate) => {
@@ -558,20 +608,39 @@ const init_multi_tenant = async (plugin_loader, disableMigrate) => {
 };
 /**
  * Create tenant
- * @param t
- * @param plugin_loader
- * @param newurl
+ * @param {string} t
+ * @param {object} plugin_loader
+ * @param {string} newurl
+ * @param {boolean} noSignalOrDB
  * @returns {Promise<void>}
  */
-const create_tenant = async (t, plugin_loader, newurl, noSignalOrDB) => {
+const create_tenant = async (
+  t,
+  plugin_loader,
+  newurl,
+  noSignalOrDB,
+  loadAndSaveNewPlugin
+) => {
   if (!noSignalOrDB) await createTenant(t, newurl);
   tenants[t] = new State(t);
   await db.runWithTenant(t, plugin_loader);
-  if (!noSignalOrDB) process_send({ createTenant: t });
+  if (!noSignalOrDB) {
+    const tenant_template = singleton.getConfig("tenant_template");
+    if (tenant_template) {
+      //create backup
+      await copy_tenant_template({
+        tenant_template,
+        target: t,
+        state: tenants[t],
+        loadAndSaveNewPlugin,
+      });
+    }
+    process_send({ createTenant: t });
+  }
 };
 /**
  * Restart tenant
- * @param plugin_loader
+ * @param {object} plugin_loader
  * @returns {Promise<void>}
  */
 const restart_tenant = async (plugin_loader) => {

package/index.js

@@ -1 +1,14 @@
+/**
+ * @category saltcorn-data
+ * @module saltcorn-data/index
+ */
+
+/**
+ * All modules in the saltcorn-data package.
+ * @namespace saltcorn-data_overview
+ * @property {module:models/index~models_overview} models
+ * @property {module:db/index~db_overview} db
+ * @property {module:base-plugin/index~base-plugin_overview} base-plugin
+ * @category saltcorn-data
+ */
 module.exports = {};