JSDoc (#43)

src/lib/user/index.js

@@ -1,2 +1,7 @@
+/**
+ * User storage module.
+ * @module user
+ */
+
 export * from './user-preferences';
 export * from './user-progress';

src/lib/user/user-preferences.js

@@ -0,0 +1,82 @@
+import clamp from 'just-clamp';
+import { persisted } from 'svelte-local-storage-store';
+
+/**
+ * @typedef {Object} UserPreferences
+ * @property {number} playback_rate - The audio player playback rate (speed)
+ * @property {number} volume - The audio player volume
+ */
+
+/**
+ * The default user preferences
+ * @type {UserPreferences}
+ */
+const DEFAULT_USER_PREFERENCES = { playback_rate: 1, volume: 1 };
+
+/**
+ * The user preferences store
+ * @type {import('svelte/store').Writable<UserPreferences>}
+ */
+const USER_PREFERENCES_STORE = persisted('USER_PREFERENCE', DEFAULT_USER_PREFERENCES);
+
+/**
+ * Sets the playback rate for the user
+ * @param {number} value - The playback rate value
+ * @returns {void}
+ */
+const set_playback_rate = (value) => {
+	const playback_rate = clamp(value, 0.5, 5);
+	return USER_PREFERENCES_STORE.update((prefs) => ({ ...prefs, playback_rate }));
+};
+
+/**
+ * Sets the volume for the user
+ * @param {number} value - The volume value
+ * @returns {void}
+ */
+const set_volume = (value) => {
+	const volume = clamp(value, 0, 1);
+	return USER_PREFERENCES_STORE.update((prefs) => ({ ...prefs, volume }));
+};
+
+/**
+ * Clears user preferences store
+ */
+const clear_store = () => USER_PREFERENCES_STORE.set(DEFAULT_USER_PREFERENCES);
+
+/**
+ * @typedef {Object} UserPreferencesObject
+ * @property {typeof USER_PREFERENCES_STORE.subscribe} subscribe - Subscribes to the user preferences store
+ * @property {typeof set_playback_rate} set_playback_rate - Sets the playback rate for the user
+ * @property {typeof set_volume} set_volume - Sets the volume for the user
+ * @property {typeof clear_store} clear - Clears saved user preferences
+ */
+
+/**
+ * The user preferences object
+ * @type {UserPreferencesObject}
+ */
+export const user_preferences = {
+	/**
+	 * Subscribes to user preferences store
+	 */
+	subscribe: USER_PREFERENCES_STORE.subscribe,
+
+	/**
+	 * Sets the playback rate for the user
+	 * @type {typeof set_playback_rate}
+	 */
+	set_playback_rate,
+
+	/**
+	 * Sets the volume for the user
+	 * @type {typeof set_volume}
+	 */
+	set_volume,
+
+	/**
+	 * Clears user preferences store
+	 * @type {typeof clear_store}
+	 */
+	clear: clear_store,
+};

src/lib/user/user-preferences.ts

@@ -1,49 +0,0 @@
-import clamp from 'just-clamp';
-import { persisted } from 'svelte-local-storage-store';
-
-export interface UserPreferences {
-	playback_rate: number;
-	volume: number;
-}
-
-const default_user_preferences = { playback_rate: 1, volume: 1 };
-const user_preferences_store = persisted<UserPreferences>(
-	'USER_PREFERENCE',
-	default_user_preferences,
-);
-
-/**
- * Sets the playback rate for the user
- * @param value - The playback rate value
- * @returns A Promise that resolves with the updated user preferences
- */
-const set_playback_rate = (value: number) => {
-	const playback_rate = clamp(value, 0.5, 5);
-	return user_preferences_store.update((prefs) => ({ ...prefs, playback_rate }));
-};
-
-/**
- * Sets the volume for the user
- * @param value - The volume value
- * @returns A Promise that resolves with the updated user preferences
- */
-const set_volume = (value: number) => {
-	const volume = clamp(value, 0, 1);
-	return user_preferences_store.update((prefs) => ({ ...prefs, volume }));
-};
-
-/**
- * Clears user preferences store
- */
-const clear_store = () => user_preferences_store.set(default_user_preferences);
-
-export const user_preferences = {
-	/**
-	 * Subscribes to user preferences store
-	 */
-	subscribe: user_preferences_store.subscribe,
-
-	set_playback_rate,
-	set_volume,
-	clear: clear_store,
-};

src/lib/user/user-progress.js

@@ -0,0 +1,77 @@
+import { persisted } from 'svelte-local-storage-store';
+import { get } from 'svelte/store';
+import { episode_audio, episode_progress } from '../audio';
+import { announce, use_url } from '../utility';
+
+/**
+ * User progress object type.
+ * This object acts as a dictionary with string keys and number values.
+ * @typedef {Object.<string, number>} UserProgress
+ */
+
+/**
+ * Default user progress object
+ * @type {UserProgress}
+ */
+const DEFAULT_USER_PROGRESS = {};
+import {} from 'svelte-local-storage-store';
+/**
+ * User progress store
+ * @type {import('svelte/store').Writable<UserProgress>}
+ */
+const USER_PROGRESS_STORE = persisted('USER_PROGRESS', DEFAULT_USER_PROGRESS);
+
+/**
+ * Saves user progress
+ * @function
+ * @returns {void}
+ */
+const save_user_progress = () => {
+	const audio = get(episode_audio);
+	if (!audio?.src) return;
+
+	announce.info('saving progress: ', audio.src);
+
+	const pathname = use_url(audio.src).pathname;
+	const current_time = get(episode_progress).current_time;
+	USER_PROGRESS_STORE.update((prev) => ({ ...prev, [pathname]: current_time }));
+};
+
+/**
+ * Gets user progress for a given audio source
+ * @function
+ * @param {string} src - Audio source
+ * @returns {number|undefined} - User progress for the given audio source, or undefined if not found
+ */
+const get_user_progress = (src) => {
+	const pathname = use_url(src).pathname;
+
+	const store = get(USER_PROGRESS_STORE);
+
+	/**@type {number|undefined} */
+	const value = store[pathname];
+
+	return value;
+};
+
+/**
+ * Clears user progress store
+ * @function
+ * @returns {void}
+ */
+const clear_user_progress = () => USER_PROGRESS_STORE.set(DEFAULT_USER_PROGRESS);
+
+/**
+ * User progress object
+ * @namespace
+ * @property {function} subscribe - Subscribes to user progress store
+ * @property {function} get - Gets user progress for a given audio source
+ * @property {function} clear - Clears user progress store
+ * @property {function} save - Saves user progress
+ */
+export const user_progress = {
+	subscribe: USER_PROGRESS_STORE.subscribe,
+	get: get_user_progress,
+	clear: clear_user_progress,
+	save: save_user_progress,
+};

src/lib/user/user-progress.ts

@@ -1,53 +0,0 @@
-import { persisted } from 'svelte-local-storage-store';
-import { get } from 'svelte/store';
-import { episode_audio, episode_progress } from '../audio';
-import { announce, use_url } from '../utility';
-
-export type UserProgress = {
-	[key: string]: number;
-};
-
-const default_user_progress = {};
-const user_progress_store = persisted<UserProgress>('USER_PROGRESS', default_user_progress);
-
-/**
- * Saves user progress
- */
-const save = () => {
-	const audio = get(episode_audio);
-	if (!audio?.src) return;
-
-	announce.info('saving progress: ', audio.src);
-
-	const pathname = use_url(audio.src).pathname;
-	const current_time = get(episode_progress).current_time;
-	user_progress_store.update((prev) => ({ ...prev, [pathname]: current_time }));
-};
-
-/**
- * Gets user progress for a given audio source
- * @param {string} src - Audio source
- * @returns {number} - User progress for the given audio source
- */
-const get_user_progress = (src: string) => {
-	const pathname = use_url(src).pathname;
-	const store = get(user_progress_store) as UserProgress;
-
-	return store[pathname];
-};
-
-/**
- * Clears user progress store
- */
-const clear_user_progress = () => user_progress_store.set(default_user_progress);
-
-export const user_progress = {
-	/**
-	 * Subscribes to user preferences store
-	 */
-	subscribe: user_progress_store.subscribe,
-
-	get: get_user_progress,
-	clear: clear_user_progress,
-	save,
-};