From eae5a9db0ad99591fcbe559bf6fc571902b6cdeb Mon Sep 17 00:00:00 2001 From: Manvel Saroyan Date: Tue, 26 Dec 2023 19:45:46 +0400 Subject: [PATCH] No issue - added JSDoc types to DB methods (#121) --- src/js/db/customActions.js | 26 ++++++++++ src/js/db/prefs.js | 24 ++++++++++ src/js/db/projects.js | 98 ++++++++++++++++++++++++++++++++++++++ src/js/db/tab.js | 7 +++ 4 files changed, 155 insertions(+) diff --git a/src/js/db/customActions.js b/src/js/db/customActions.js index c628543..8ad675a 100644 --- a/src/js/db/customActions.js +++ b/src/js/db/customActions.js @@ -17,19 +17,45 @@ * . */ +/** + * @typedef {Object} CustomActionInfo + * @property {string} description - Custom action description. + */ + +/** + * Custom and predefined actions: + * - Used by [Functions datagrid](https://chrome-automation.com/functions-grid). + * - Editable in [Functions tab](https://chrome-automation.com/functions-management). + * + * @typedef {Object} CustomAction + * @property {Action} data - Action. + * @property {CustomActionInfo} info - More information. + * @property {string} text - Name. + */ + const name = "customActions"; +/** + * Loads CustomActions from storage. + * @returns {Promise} + */ async function load() { const result = await browser.storage.local.get(name); return result[name]; } +/** + * @param {CustomAction[]} items + */ function saveState(items) { const result = {}; result[name] = items; return browser.storage.local.set(result); } +/** + * @type {CustomAction[]} + */ const predefined = [ { data: { diff --git a/src/js/db/prefs.js b/src/js/db/prefs.js index d43fd3e..87e44b9 100644 --- a/src/js/db/prefs.js +++ b/src/js/db/prefs.js @@ -17,8 +17,17 @@ * . */ +/** + * @typedef {Object} Prefs + * @property {boolean} hidePowerfulActionWarning - Hide tooltip for powerful actions. + */ + const name = "prefs"; +/** + * Initialize preferences. + * @returns {Promise} + */ async function init() { let prefs = await load(); @@ -32,17 +41,32 @@ async function init() } } +/** + * Loads preferences from storage. + * @returns {Promise} + */ async function load() { const result = await browser.storage.local.get(name); return result[name]; } +/** + * Get preference. + * @param {keyof Prefs} pref + * @returns {Promise} + */ async function get(pref) { const prefs = await load(); return (prefs && prefs[pref]) ? prefs[pref] : false; } +/** + * Set preference. + * @param {keyof Prefs} pref + * @param {Prefs[pref]} value + * @returns + */ async function set(pref, value) { const prefs = await load(); diff --git a/src/js/db/projects.js b/src/js/db/projects.js index 6103891..4737385 100644 --- a/src/js/db/projects.js +++ b/src/js/db/projects.js @@ -17,13 +17,72 @@ * . */ +// Keep types in [sync with Wiki](https://github.com/browser-automation/cba/wiki/Storage-%7C-projects). + +/** + * @typedef {( + * |"Inject" + * |"inject-cs" + * |"bg-inject" + * |"bg-function" + * |"change" + * |"check" + * |"click" + * |"click-update" + * |"update" + * |"timer" + * |"redirect" + * |"copy-html" + * |"copy" + * |"pause" + * )} ActionType + */ + +/** + * Injectable actions as seen in [Actions table](https://chrome-automation.com/actions-grid). + * Learn more about [Various actions](https://chrome-automation.com/actions). + * @typedef {Object} Action + * @property {string} id - Unique Identifier. + * @property {ActionType} type - One of [injectable action types](https://chrome-automation.com/actions). + * @property {string[]} inputs - action's arguments/inputs: + * 1. Query, code, timer wait time or redirection link. + * 2. New input value. + */ + +/** + * Projects containing actions. + * @typedef {Object} Project + * @property {Action[]} actions - Injectable actions. + * @property {string} id - Unique Identifier. + * @property {string} text - Name of the project. + * @property {"project"} type - Project item indication. + */ + +/** + * [Groups, containing project](https://chrome-automation.com/project) which + * contain [actions](https://chrome-automation.com/actions-grid). + * @typedef {Object} Group + * @property {boolean} expanded - expands/collapse group. + * @property {string} id - Unique Identifier. + * @property {Project[]} subItems - Sub projects. + * @property {string} text - Name of the group. + * @property {"group"} type - Group item indication. + */ + const name = "projects"; +/** + * Loads project Groups from storage. + * @returns {Promise} + */ async function load() { const result = await browser.storage.local.get(name); return result[name]; } +/** + * @param {Group[]} items + */ function saveState(items) { const result = {}; result[name] = items.map(removeEditable); @@ -38,6 +97,12 @@ function removeEditable(item) { return item; } +/** + * Add action to subItem and save to storage. + * @param {Group["id"]} groupId + * @param {Project["id"]} subItemId + * @param {Action} action + */ async function addAction(groupId, subItemId, action) { const groups = await load(); const [group] = groups.filter(({id}) => id === groupId); @@ -53,6 +118,12 @@ async function addAction(groupId, subItemId, action) { return saveState(groups); } +/** + * Import project into a Group with group name. + * @param {Group["subItems"]} subItems + * @param {Group["text"]} groupText + * @returns + */ async function importProjects(subItems, groupText) { const groups = await load(name); @@ -88,6 +159,12 @@ async function importProjects(subItems, groupText) return saveState(groups); } +/** + * Create an empty group object. + * @param {Group["text"]} groupText + * @param {Group["id"]} groupId + * @returns {Group} + */ function createGroupObj(groupText, groupId) { return { id: groupId, @@ -98,11 +175,25 @@ function createGroupObj(groupText, groupId) { } } +/** + * Check if project with specific name exists in Projects. + * + * @param {Project[]} items + * @param {string} value + * @returns + */ function hasTextWithValue(items, value) { return items.filter(({text}) => text === value).length > 0; } +/** + * Get unique text for a new project. + * + * @param {Project[]} items + * @param {string} prefix + * @returns + */ function getNextText(items, prefix) { if (!items || !items.length) return null; @@ -113,6 +204,13 @@ function getNextText(items, prefix) { return `${prefix}${num}`; } +/** + * Check if id exists in the groups. + * + * @param {Group[]} groups + * @param {string} currentId + * @returns + */ function hasId(groups, currentId) { for (const {id, subItems} of groups) diff --git a/src/js/db/tab.js b/src/js/db/tab.js index b4473db..f85329c 100644 --- a/src/js/db/tab.js +++ b/src/js/db/tab.js @@ -19,11 +19,18 @@ const dbName = "tab"; +/** + * Load tab id from storage. + * @returns {Promise} - Tab id. + */ async function load() { const {tab} = await browser.storage.local.get(dbName); return tab; } +/** + * @param {string} id - Tab id. + */ function saveState(id) { const tab = id; return browser.storage.local.set({tab});