From a01cd5213393d491676b972f98c1c40430c7205f Mon Sep 17 00:00:00 2001 From: Tanmay Dineshkumar Shah Date: Tue, 5 Dec 2023 10:40:14 +0530 Subject: [PATCH] chore: add jsdoc comments on util functions --- lib/components/option/Option.svelte | 4 ++++ lib/utils/browser/constructShortcutRules.ts | 6 +++++- lib/utils/browser/getBrowserName.ts | 8 ++++++++ lib/utils/browser/getDeclarativeNetRequestRules.ts | 4 ++++ lib/utils/browser/getFaviconURL.ts | 9 +++++++-- lib/utils/browser/getTabUrl.ts | 8 ++++++++ lib/utils/browser/storageUtils.ts | 5 +++++ lib/utils/browser/tabOperations.ts | 10 ++++++++++ lib/utils/browser/updateDeclarativeNetRequestRules.ts | 6 ++++++ lib/utils/constructShortcutsFromCSVData.ts | 4 ++-- lib/utils/copyToClipboard.ts | 5 +++++ lib/utils/isNotNull.ts | 5 +++++ lib/utils/setShortcutsToStorage.ts | 5 +++++ pnpm-lock.yaml | 11 +++++++++++ tsconfig.json | 4 ++-- 15 files changed, 87 insertions(+), 7 deletions(-) diff --git a/lib/components/option/Option.svelte b/lib/components/option/Option.svelte index 11e1ba6..2ea1900 100644 --- a/lib/components/option/Option.svelte +++ b/lib/components/option/Option.svelte @@ -57,6 +57,10 @@ // reset search query every-time shortcut list changes $: resetSearchQuery($shortcuts) + /** + * loads the shortcuts into the store from storage + * @returns {Promise} + */ async function loadShortcuts() { await shortcuts.init() } diff --git a/lib/utils/browser/constructShortcutRules.ts b/lib/utils/browser/constructShortcutRules.ts index 728e0ba..67333e8 100644 --- a/lib/utils/browser/constructShortcutRules.ts +++ b/lib/utils/browser/constructShortcutRules.ts @@ -1,7 +1,11 @@ -import { FIREFOX, SAFARI } from "~lib/constants/browserNames" import type { Shortcut } from "~lib/types" import { isNonChromiumBrowser } from "./getBrowserName" +/** + * construct the declarative net request rules for given shortcuts array + * @param {Shortcut[]} shortcuts shortcuts array + * @returns {browser.declarativeNetRequest.Rule[] | chrome.declarativeNetRequest.Rule[]} array of shortcut rules + */ export function constructShortcutRules(shortcuts: Shortcut[]) { if (isNonChromiumBrowser()) { return shortcuts.map((shortcut, index) => { diff --git a/lib/utils/browser/getBrowserName.ts b/lib/utils/browser/getBrowserName.ts index 52f9f80..d900e19 100644 --- a/lib/utils/browser/getBrowserName.ts +++ b/lib/utils/browser/getBrowserName.ts @@ -1,9 +1,17 @@ import { FIREFOX, SAFARI } from "~lib/constants/browserNames"; +/** + * gives the browser name + * @returns {string} browser name as per plasmo env + */ export function getBrowserName() { return process.env.PLASMO_BROWSER } +/** + * checks if the browser is a non chromium based one or not + * @returns {boolean} true if if not based on chromium. else false + */ export function isNonChromiumBrowser() { // For now, only safari and firefox are considered in non chromium browsers // More can be added in future if required diff --git a/lib/utils/browser/getDeclarativeNetRequestRules.ts b/lib/utils/browser/getDeclarativeNetRequestRules.ts index 2ef1b46..49008e9 100644 --- a/lib/utils/browser/getDeclarativeNetRequestRules.ts +++ b/lib/utils/browser/getDeclarativeNetRequestRules.ts @@ -1,5 +1,9 @@ import { isNonChromiumBrowser } from "./getBrowserName"; +/** + * gives the saved declarative net request rules in browser + * @returns {browser.declarativeNetRequest.Rule[] | chrome.declarativeNetRequest.Rule[]} declarative net request rules array + */ export async function getDeclarativeNetRequestRules() { const browserName = process.env.PLASMO_BROWSER if (isNonChromiumBrowser()) { diff --git a/lib/utils/browser/getFaviconURL.ts b/lib/utils/browser/getFaviconURL.ts index 5feb676..7c5f4e3 100644 --- a/lib/utils/browser/getFaviconURL.ts +++ b/lib/utils/browser/getFaviconURL.ts @@ -1,6 +1,11 @@ import { isNonChromiumBrowser } from "./getBrowserName" -export function getFaviconURL(u: string) { +/** + * gives the saved favicon url in browser of a given website + * @param {string} url the shortlink's url + * @returns {browser.declarativeNetRequest.Rule[] | chrome.declarativeNetRequest.Rule[]} declarative net request rules array + */ +export function getFaviconURL(shortcutURL: string) { let url: URL | null = null if (isNonChromiumBrowser()) { // NOTE: This is a fallback icon. Firefox does not support accessing cached favicon @@ -11,7 +16,7 @@ export function getFaviconURL(u: string) { } if (url) { - url.searchParams.set("pageUrl", u) + url.searchParams.set("pageUrl", shortcutURL) url.searchParams.set("size", "32") return url.toString() } diff --git a/lib/utils/browser/getTabUrl.ts b/lib/utils/browser/getTabUrl.ts index 2043fc0..cd51f81 100644 --- a/lib/utils/browser/getTabUrl.ts +++ b/lib/utils/browser/getTabUrl.ts @@ -1,9 +1,17 @@ import { isNonChromiumBrowser } from "./getBrowserName" +/** + * gives the active/current tab url + * @returns {Promise} url string of the active/current tab + */ export async function getActiveTabURL() { return await getTabURL() } +/** + * utility function to get current tab url using browser APIs + * @returns {Promise} url string of the active/current tab + */ function getTabURL() { return new Promise((resolve) => { try { diff --git a/lib/utils/browser/storageUtils.ts b/lib/utils/browser/storageUtils.ts index b24d14a..2fae9a9 100644 --- a/lib/utils/browser/storageUtils.ts +++ b/lib/utils/browser/storageUtils.ts @@ -1,6 +1,11 @@ import { Storage } from "@plasmohq/storage"; import type { Shortcut } from "~lib/types"; +/** + * gives the browser local storage data for a given key + * @param {string} key key for the stored data + * @returns {Promise} stored data with given type + */ export async function getDataFromStorage(key) { const storage = new Storage({ area: "local" diff --git a/lib/utils/browser/tabOperations.ts b/lib/utils/browser/tabOperations.ts index 5439651..7c623c8 100644 --- a/lib/utils/browser/tabOperations.ts +++ b/lib/utils/browser/tabOperations.ts @@ -1,5 +1,10 @@ import { isNonChromiumBrowser } from "./getBrowserName" +/** + * opens new tab + * @param {chrome.tabs.CreateProperties | browser.tabs._CreateCreateProperties} props properties for creating new tab + * @returns {void} + */ export function openNewTab(props: chrome.tabs.CreateProperties | browser.tabs._CreateCreateProperties) { if (isNonChromiumBrowser()) { browser.tabs.create(props) @@ -9,6 +14,11 @@ export function openNewTab(props: chrome.tabs.CreateProperties | browser.tabs._C } } +/** + * updates the current tab + * @param {chrome.tabs.UpdateProperties | browser.tabs._UpdateUpdateProperties} props properties for updating the tab + * @returns {void} + */ export function updateTab(props: chrome.tabs.UpdateProperties | browser.tabs._UpdateUpdateProperties) { if (isNonChromiumBrowser()) { browser.tabs.update(props) diff --git a/lib/utils/browser/updateDeclarativeNetRequestRules.ts b/lib/utils/browser/updateDeclarativeNetRequestRules.ts index a968399..34dd035 100644 --- a/lib/utils/browser/updateDeclarativeNetRequestRules.ts +++ b/lib/utils/browser/updateDeclarativeNetRequestRules.ts @@ -1,5 +1,11 @@ import { isNonChromiumBrowser } from "./getBrowserName"; +/** + * updates the declarative net request rules of the browser + * @param { browser.declarativeNetRequest.Rule[] | chrome.declarativeNetRequest.Rule[]} addRules rules that need to be added + * @param {number[]} removeRuleIds IDs of rules that need to be removed + * @returns {void} + */ export async function updateDeclarativeNetRequestRules( addRules: browser.declarativeNetRequest.Rule[] | chrome.declarativeNetRequest.Rule[], diff --git a/lib/utils/constructShortcutsFromCSVData.ts b/lib/utils/constructShortcutsFromCSVData.ts index 45229b9..e478dcd 100644 --- a/lib/utils/constructShortcutsFromCSVData.ts +++ b/lib/utils/constructShortcutsFromCSVData.ts @@ -35,8 +35,8 @@ export async function constructShortcutsFromCSVData(csvData: string[][], savedSh const shortcut: Shortcut = { shortlink: shortcutRow[0], url: shortcutRow[1], - createdAt: new Date(), - updatedAt: new Date(), + createdAt: new Date().toISOString(), + updatedAt: new Date().toISOString(), }; return shortcut; } diff --git a/lib/utils/copyToClipboard.ts b/lib/utils/copyToClipboard.ts index 229fc7a..e79d8e2 100644 --- a/lib/utils/copyToClipboard.ts +++ b/lib/utils/copyToClipboard.ts @@ -1,3 +1,8 @@ +/** + * copies the given text to clipboard + * @param {string} text text to be copied + * @returns {void} + */ export function copyToClipboard(text: string): void { if (navigator.clipboard && navigator.clipboard.writeText) { navigator.clipboard diff --git a/lib/utils/isNotNull.ts b/lib/utils/isNotNull.ts index 60bc291..c475097 100644 --- a/lib/utils/isNotNull.ts +++ b/lib/utils/isNotNull.ts @@ -1,3 +1,8 @@ +/** + * checks if value is null or not + * @param {T | null} value value to be checked + * @returns {boolean} true if value is not null. else false + */ export function isNotNull(value: T | null): value is T { return value !== null; } \ No newline at end of file diff --git a/lib/utils/setShortcutsToStorage.ts b/lib/utils/setShortcutsToStorage.ts index d45e5f9..74a7bde 100644 --- a/lib/utils/setShortcutsToStorage.ts +++ b/lib/utils/setShortcutsToStorage.ts @@ -2,6 +2,11 @@ import type { Shortcut } from "~lib/types" import { setDataToStorage } from "./browser/storageUtils" import { SHORTCUTS_STORAGE_KEY } from "~lib/constants/keys" +/** + * set/store given shortcuts to storage + * @param {Shortcut[]} shortcuts shortcuts to be stored + * @returns {Promise} + */ export async function setShortcutsToStorage(shortcuts: Shortcut[]) { await setDataToStorage(SHORTCUTS_STORAGE_KEY, shortcuts) } \ No newline at end of file diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 5cddaa9..6528577 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1,5 +1,9 @@ lockfileVersion: '6.0' +settings: + autoInstallPeers: true + excludeLinksFromLockfile: false + dependencies: '@plasmohq/storage': specifier: ^1.9.0 @@ -3537,6 +3541,7 @@ packages: /debug@3.2.7: resolution: {integrity: sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ==} + requiresBuild: true peerDependencies: supports-color: '*' peerDependenciesMeta: @@ -4310,6 +4315,7 @@ packages: /iconv-lite@0.6.3: resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==} engines: {node: '>=0.10.0'} + requiresBuild: true dependencies: safer-buffer: 2.1.2 dev: false @@ -5110,6 +5116,7 @@ packages: /ms@2.1.3: resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==} + requiresBuild: true dev: false optional: true @@ -5226,6 +5233,7 @@ packages: /node-gyp-build-optional-packages@5.0.7: resolution: {integrity: sha512-YlCCc6Wffkx0kHkmam79GKvDQ6x+QZkMjFGrIMxgFNILFvGSbCp2fCBC55pGTT9gVaz8Na5CLmxt/urtzRv36w==} hasBin: true + requiresBuild: true dev: false optional: true @@ -5609,6 +5617,7 @@ packages: /pify@4.0.1: resolution: {integrity: sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g==} engines: {node: '>=6'} + requiresBuild: true dev: false optional: true @@ -5858,6 +5867,7 @@ packages: /prr@1.0.1: resolution: {integrity: sha512-yPw4Sng1gWghHQWj0B3ZggWUm4qVbPwPFcRG8KyxiU7J2OHFSoEHKS+EZ3fv5l1t9CyCiop6l/ZYeWbrgoQejw==} + requiresBuild: true dev: false optional: true @@ -6117,6 +6127,7 @@ packages: /sax@1.3.0: resolution: {integrity: sha512-0s+oAmw9zLl1V1cS9BtZN7JAd0cW5e0QH4W3LWEK6a4LaLEA2OTpGYWDY+6XasBLtz6wkm3u1xRw95mRuJ59WA==} + requiresBuild: true dev: false optional: true diff --git a/tsconfig.json b/tsconfig.json index 17f3e9f..932fd75 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -6,7 +6,7 @@ "include": [ ".plasmo/index.d.ts", "./**/*.ts", - "./**/*.svelte" + "./**/*.svelte", ], "compilerOptions": { "paths": { @@ -15,6 +15,6 @@ ] }, "baseUrl": ".", - "types": ["svelte", "chrome", "firefox-webext-browser"] + "types": ["svelte", "chrome", "firefox-webext-browser", "node"] } }