style: require jsdoc comments

maxnowack · Jan 9, 2025 · 39b1d74 · 39b1d74
1 parent a2d2228
commit 39b1d74
Show file tree

Hide file tree

Showing 21 changed files with 131 additions and 0 deletions.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -6,6 +6,11 @@ import { withMermaid } from 'vitepress-plugin-mermaid'
 const require = createRequire(import.meta.url)
 const package_ = require('../../packages/base/core/package.json')
 
+/**
+ * Builds an HTML string for redirecting to a specified URL.
+ * @param to - The URL to redirect to.
+ * @returns The HTML string for the redirect.
+ */
 function buildRedirectHtml(to: string) {
   return `<!DOCTYPE html><html><title>Redirecting...</title><meta http-equiv="refresh" content="0; url=${to}"><link rel="canonical" href="${to}"><body><a href="${to}">Redirecting...</a></body></html>`
 }

diff --git a/eslint.config.mjs b/eslint.config.mjs
@@ -59,6 +59,7 @@ export default tseslint.config(
       'import/extensions': ['.js', '.cjs', '.mjs', '.ts', '.mts', '.tsx'],
     },
     rules: {
+      'jsdoc/require-jsdoc': 'error',
       'unicorn/consistent-function-scoping': ['error', { checkArrowFunctions: false }],
       'unicorn/no-useless-undefined': ['error', {
         checkArguments: false,

diff --git a/examples/replication-http/src/system/syncManager.ts b/examples/replication-http/src/system/syncManager.ts
@@ -1,6 +1,12 @@
 import { SyncManager } from '@signaldb/sync'
 import createIndexedDBAdapter from '@signaldb/indexeddb'
 
+/**
+ * Fetches data from the authenticated API.
+ * @param path - The API endpoint path.
+ * @param [options] - Optional fetch options.
+ * @returns The fetch response.
+ */
 function authenticatedFetch(path: string, options?: RequestInit) {
   const databaseId = '65676881edfe6a3e7e2c'
   const projectId = '6567685ea287ba49be81'

diff --git a/packages/base/core/__tests__/reactivity.spec.ts b/packages/base/core/__tests__/reactivity.spec.ts
@@ -22,6 +22,12 @@ const primitiveReactivity = (() => {
   let currentComputation: Computation | null = null
   let lastComputation: Computation | null = null
 
+  /**
+   * Creates a reactive signal with an initial value.
+   * @template T
+   * @param initialValue - The initial value of the signal.
+   * @returns The reactive signal.
+   */
   function signal<T>(initialValue: T) {
     let value = initialValue
     const computationDeps = new Set<Computation>()
@@ -45,6 +51,11 @@ const primitiveReactivity = (() => {
     }
     effectCallback()
   }
+  /**
+   * Temporarily suspends reactivity tracking for the duration of the callback.
+   * @param callback - The callback function to execute without reactivity tracking.
+   * @returns The result of the callback function.
+   */
   function peek<T>(callback: () => T) {
     const previousComputation = currentComputation
     currentComputation = null

diff --git a/packages/base/core/src/Collection/Cursor.ts b/packages/base/core/src/Collection/Cursor.ts
@@ -114,6 +114,12 @@ export default class Cursor<T extends BaseItem, U = T> {
     signal.depend()
     const notify = () => signal.notify()
 
+    /**
+     * Builds a notifier function for the specified event.
+     * @template Event - The type of the event.
+     * @param event - The event for which to build the notifier.
+     * @returns A function that handles the event and triggers the appropriate notifications.
+     */
     function buildNotifier<Event extends keyof ObserveCallbacks<T>>(
       event: Event,
     ) {

diff --git a/packages/base/core/src/utils/compact.ts b/packages/base/core/src/utils/compact.ts
@@ -1,5 +1,11 @@
 type Truthy<T> = T extends false | '' | 0 | null | undefined ? never : T // from lodash
 
+/**
+ * Checks if a value is truthy.
+ * @template T - The type of the value.
+ * @param value - The value to check.
+ * @returns A boolean indicating if the value is truthy.
+ */
 function truthy<T>(value: T): value is Truthy<T> {
   return !!value
 }

diff --git a/packages/base/sync/__tests__/SyncManager.spec.ts b/packages/base/sync/__tests__/SyncManager.spec.ts
@@ -4,6 +4,13 @@ import { Collection, createPersistenceAdapter } from '@signaldb/core'
 import type { BaseItem, LoadResponse, PersistenceAdapter } from '@signaldb/core'
 import { SyncManager } from '../src'
 
+/**
+ * Creates a memory persistence adapter for testing purposes.
+ * @param initialData - Initial data to populate the adapter.
+ * @param transmitChanges - Whether to transmit changes.
+ * @param [delay] - Optional delay for simulating async operations.
+ * @returns The memory persistence adapter.
+ */
 function memoryPersistenceAdapter<
   T extends { id: I } & Record<string, any>,
   I = any,

diff --git a/packages/base/sync/__tests__/applyChanges.spec.ts b/packages/base/sync/__tests__/applyChanges.spec.ts
@@ -9,6 +9,11 @@ interface TestItem extends BaseItem<number> {
   name: string,
 }
 
+/**
+ * Returns a default change item with the given id.
+ * @param id - The id of the change item.
+ * @returns The default change item.
+ */
 function getDefaultChangeItem(id = '1') {
   return { id, time: Date.now(), collectionName: 'test' }
 }

diff --git a/packages/base/sync/src/sync.ts b/packages/base/sync/src/sync.ts
@@ -4,13 +4,24 @@ import type { Change } from './types'
 import getSnapshot from './getSnapshot'
 import applyChanges from './applyChanges'
 
+/**
+ * Checks if there are any changes in the given changeset.
+ * @param changes The changeset to check.
+ * @returns True if there are changes, false otherwise.
+ */
 function hasChanges<T>(
   changes: Changeset<T>,
 ) {
   return changes.added.length > 0
     || changes.modified.length > 0
     || changes.removed.length > 0
 }
+/**
+ * Checks if there is a difference between the old items and the new items.
+ * @param oldItems The old items.
+ * @param newItems The new items.
+ * @returns True if there is a difference, false otherwise.
+ */
 function hasDifference<ItemType extends BaseItem<IdType>, IdType>(
   oldItems: ItemType[],
   newItems: ItemType[],

diff --git a/packages/base/sync/src/utils/debounce.ts b/packages/base/sync/src/utils/debounce.ts
@@ -22,6 +22,12 @@ export default function debounce<Arguments extends any[], T, ThisType>(
 
   const { leading = false, trailing = true } = options
 
+  /**
+   * The debounced function that will be returned.
+   * @param this The context to bind the function to.
+   * @param args The arguments to pass to the function.
+   * @returns The result of the debounced function.
+   */
   function debounced(this: ThisType, ...args: Arguments) {
     const shouldCallImmediately = leading && !timeout
     const shouldCallTrailing = trailing && !timeout

diff --git a/packages/integrations/react/__tests__/useReactivity.spec.ts b/packages/integrations/react/__tests__/useReactivity.spec.ts
@@ -5,6 +5,11 @@ import { signal, onDispose, effect } from '@maverick-js/signals'
 import { StrictMode } from 'react'
 import { createUseReactivityHook } from '../src'
 
+/**
+ * Helper function to create a reactive signal.
+ * @param initialValue - The initial value of the signal.
+ * @returns An object with get and set methods to interact with the signal.
+ */
 function reactiveHelper<T>(initialValue: T) {
   const dep = signal(initialValue)
   return {

diff --git a/packages/integrations/react/src/index.ts b/packages/integrations/react/src/index.ts
@@ -41,6 +41,12 @@ interface ReactiveEffect {
  * }
  */
 export function createUseReactivityHook(effect: ReactiveEffect) {
+  /**
+   * Custom hook for managing reactive computations.
+   * @param reactiveFunction - A function that returns the reactive data.
+   * @param deps - Dependency list for the effect.
+   * @returns The reactive data.
+   */
   function useReactivity<T>(
     reactiveFunction: () => T,
     deps?: DependencyList,

diff --git a/packages/persistence-adapters/fs/__tests__/adapter.spec.ts b/packages/persistence-adapters/fs/__tests__/adapter.spec.ts
@@ -4,6 +4,14 @@ import { it, expect } from 'vitest'
 import { Collection } from '@signaldb/core'
 import createFilesystemAdapter from '../src'
 
+/**
+ * Waits for a specific event to be emitted.
+ * @template T
+ * @param emitter - The event emitter instance.
+ * @param event - The name of the event to wait for.
+ * @param [timeout] - Optional timeout in milliseconds.
+ * @returns A promise that resolves with the event value.
+ */
 async function waitForEvent<T>(
   emitter: EventEmitter<any>,
   event: string,

diff --git a/packages/persistence-adapters/fs/src/index.ts b/packages/persistence-adapters/fs/src/index.ts
@@ -38,6 +38,10 @@ export default function createFilesystemAdapter<
 
   let savePromise: Promise<void> | null = null
 
+  /**
+   * Retrieves the items from the file.
+   * @returns A promise that resolves to an array of items.
+   */
   async function getItems(): Promise<T[]> {
     const fs = await import('fs')
     const exists = await fs.promises.access(filename).then(() => true).catch(() => false)

diff --git a/packages/persistence-adapters/indexeddb/__tests__/adapter.spec.ts b/packages/persistence-adapters/indexeddb/__tests__/adapter.spec.ts
@@ -5,6 +5,13 @@ import { Collection } from '@signaldb/core'
 import 'fake-indexeddb/auto'
 import createIndexedDBAdapter from '../src'
 
+/**
+ * Waits for a specific event to be emitted.
+ * @param emitter - The event emitter.
+ * @param event - The event to wait for.
+ * @param [timeout] - Optional timeout in milliseconds.
+ * @returns A promise that resolves with the event value.
+ */
 async function waitForEvent<T>(
   emitter: EventEmitter,
   event: string,

diff --git a/packages/persistence-adapters/indexeddb/src/index.ts b/packages/persistence-adapters/indexeddb/src/index.ts
@@ -15,6 +15,10 @@ export default function createIndexedDBAdapter<
   const databaseName = `signaldb-${name}`
   const storeName = 'items'
 
+  /**
+   * Opens the IndexedDB database and creates the object store if it doesn't exist.
+   * @returns A promise that resolves with the opened database.
+   */
   function openDatabase(): Promise<IDBDatabase> {
     return new Promise((resolve, reject) => {
       const request = indexedDB.open(databaseName, 1)
@@ -29,6 +33,10 @@ export default function createIndexedDBAdapter<
     })
   }
 
+  /**
+   * Retrieves all items from the IndexedDB object store.
+   * @returns A promise that resolves with an array of items.
+   */
   async function getAllItems(): Promise<T[]> {
     const database = await openDatabase()
     return new Promise((resolve, reject) => {

diff --git a/packages/persistence-adapters/localstorage/__tests__/adapter.spec.ts b/packages/persistence-adapters/localstorage/__tests__/adapter.spec.ts
@@ -4,6 +4,13 @@ import { describe, it, expect } from 'vitest'
 import { Collection } from '@signaldb/core'
 import createLocalStorageAdapter from '../src'
 
+/**
+ * Waits for a specific event to be emitted.
+ * @param emitter - The event emitter instance.
+ * @param event - The event name to wait for.
+ * @param [timeout] - Optional timeout in milliseconds.
+ * @returns A promise that resolves with the event value.
+ */
 async function waitForEvent<T>(
   emitter: EventEmitter,
   event: string,

diff --git a/packages/persistence-adapters/localstorage/src/index.ts b/packages/persistence-adapters/localstorage/src/index.ts
@@ -37,6 +37,10 @@ export default function createLocalStorageAdapter<
   const { serialize = JSON.stringify, deserialize = JSON.parse } = options || {}
 
   const collectionId = `signaldb-collection-${name}`
+  /**
+   * Retrieves items from localStorage and deserializes them.
+   * @returns The deserialized items from localStorage.
+   */
   function getItems(): T[] {
     return deserialize(localStorage.getItem(collectionId) || '[]')
   }

diff --git a/packages/persistence-adapters/opfs/__tests__/adapter.spec.ts b/packages/persistence-adapters/opfs/__tests__/adapter.spec.ts
@@ -4,6 +4,13 @@ import { describe, it, expect } from 'vitest'
 import { Collection } from '@signaldb/core'
 import createOPFSAdapter from '../src'
 
+/**
+ * Waits for a specific event to be emitted.
+ * @param emitter - The event emitter.
+ * @param event - The event to wait for.
+ * @param [timeout] - Optional timeout in milliseconds.
+ * @returns A promise that resolves with the event value.
+ */
 async function waitForEvent<T>(
   emitter: EventEmitter,
   event: string,

diff --git a/packages/persistence-adapters/opfs/src/index.ts b/packages/persistence-adapters/opfs/src/index.ts
@@ -41,6 +41,10 @@ export default function createOPFSAdapter<
 
   let savePromise: Promise<void> | null = null
 
+  /**
+   * Retrieves the items from the OPFS file.
+   * @returns A promise that resolves to an array of items.
+   */
   async function getItems(): Promise<T[]> {
     const opfsRoot = await navigator.storage.getDirectory()
     const existingFileHandle = await opfsRoot.getFileHandle(filename, { create: true })

diff --git a/packages/reactivity-adapters/angular/__tests__/reactivity.spec.ts b/packages/reactivity-adapters/angular/__tests__/reactivity.spec.ts
@@ -6,6 +6,10 @@ import angularReactivityAdapter from '../src'
 
 // borrowed from https://github.com/angular/angular/blob/80f472f9f4c09af33f41f7e8dd656eff0b74d03f/packages/core/test/signals/effect_util.ts
 const queue = new Set<Watch>()
+/**
+ * Creates and runs a watch effect.
+ * @param effectFunction - The effect function to run.
+ */
 function testingEffect(
   effectFunction: (onCleanup: (cleanupFunction: WatchCleanupFn) => void) => void,
 ): void {
@@ -14,6 +18,9 @@ function testingEffect(
   // Effects start dirty.
   w.notify()
 }
+/**
+ * Flushes and runs all queued effects.
+ */
 function flushEffects(): void {
   for (const watch of queue) {
     queue.delete(watch)