[docs]: TS-Doc comments added (#1087)

* docs: Added tsdoc comments

* lint fixes

Author: overthemike

src/react.ts

@@ -15,6 +15,16 @@ import {
 import { snapshot, subscribe } from './vanilla.ts'
 import type { Snapshot } from './vanilla.ts'
 
+/**
+ * React hook to display affected paths in React DevTools for debugging
+ *
+ * This internal hook collects the paths that were accessed during render
+ * and displays them in React DevTools to help with debugging render optimizations.
+ *
+ * @param {object} state - The state object being tracked
+ * @param {WeakMap<object, unknown>} affected - WeakMap of accessed properties
+ * @private
+ */
 const useAffectedDebugValue = (
   state: object,
   affected: WeakMap<object, unknown>,
@@ -87,8 +97,9 @@ type Options = {
  * > console.log(state)
  * { profile: { name: "new name" } }
  *
- * `useSnapshot()` depends on the original reference of the child proxy so if you replace it with a new one, the component
- * that is subscribed to the old proxy won't receive new updates because it is still subscribed to the old one.
+ * `useSnapshot()` depends on the original reference of the child proxy so if you replace it with a new one, the
+ * component that is subscribed to the old proxy won't receive new updates because it is still subscribed to
+ * the old one.
  *
  * In this case we recommend the example C or D. On both examples you don't need to worry with re-render,
  * because it is render-optimized.

src/vanilla.ts

@@ -3,20 +3,33 @@ import { getUntracked, markToTrack } from 'proxy-compare'
 const isObject = (x: unknown): x is object =>
   typeof x === 'object' && x !== null
 
+/** Function type for any kind of function */
 type AnyFunction = (...args: any[]) => any
 
+/** Object that can be proxied */
 type ProxyObject = object
 
+/** Property access path as an array of property names/symbols */
 type Path = (string | symbol)[]
+
+/**
+ * Operation performed on a proxy object
+ * - 'set': A property was set to a new value
+ * - 'delete': A property was deleted
+ */
 type Op =
   | [op: 'set', path: Path, value: unknown, prevValue: unknown]
   | [op: 'delete', path: Path, prevValue: unknown]
+
+/** Function called when a proxy object changes */
 type Listener = (op: Op, nextVersion: number) => void
 
 export type INTERNAL_Op = Op
 
+/** JavaScript primitive types */
 type Primitive = string | number | boolean | null | undefined | symbol | bigint
 
+/** Types that should not be proxied in snapshots */
 type SnapshotIgnore =
   | Date
   | Map<any, any>
@@ -28,6 +41,11 @@ type SnapshotIgnore =
   | AnyFunction
   | Primitive
 
+/**
+ * Snapshot type that converts objects to readonly versions recursively
+ *
+ * @template T - Type to convert to a snapshot
+ */
 export type Snapshot<T> = T extends { $$valtioSnapshot: infer S }
   ? S
   : T extends SnapshotIgnore
@@ -156,6 +174,14 @@ let canProxy: typeof canProxyDefault = canProxyDefault
 let createSnapshot: typeof createSnapshotDefault = createSnapshotDefault
 let createHandler: typeof createHandlerDefault = createHandlerDefault
 
+/**
+ * Creates a reactive proxy object that can be tracked for changes
+ *
+ * @template T - Type of the object to be proxied
+ * @param {T} baseObject - The object to create a proxy for
+ * @returns {T} A proxied version of the input object
+ * @throws {Error} If the input is not an object
+ */
 export function proxy<T extends object>(baseObject: T = {} as T): T {
   if (!isObject(baseObject)) {
     throw new Error('object required')
@@ -266,11 +292,26 @@ export function proxy<T extends object>(baseObject: T = {} as T): T {
   return proxyObject
 }
 
+/**
+ * Gets the current version number of a proxy object
+ *
+ * @param {unknown} proxyObject - The proxy object to get the version of
+ * @returns {number | undefined} The current version number, or undefined if not a proxy
+ */
 export function getVersion(proxyObject: unknown): number | undefined {
   const proxyState = proxyStateMap.get(proxyObject as object)
   return proxyState?.[1]()
 }
 
+/**
+ * Subscribes to changes in a proxy object
+ *
+ * @template T - Type of the proxy object
+ * @param {T} proxyObject - The proxy object to subscribe to
+ * @param {Function} callback - Function called when the proxy object changes
+ * @param {boolean} [notifyInSync] - If true, notifications happen synchronously
+ * @returns {Function} Unsubscribe function to stop listening for changes
+ */
 export function subscribe<T extends object>(
   proxyObject: T,
   callback: (unstable_ops: Op[]) => void,
@@ -307,6 +348,13 @@ export function subscribe<T extends object>(
   }
 }
 
+/**
+ * Creates an immutable snapshot of the current state of a proxy object
+ *
+ * @template T - Type of the proxy object
+ * @param {T} proxyObject - The proxy object to create a snapshot from
+ * @returns {Snapshot<T>} An immutable snapshot of the current state
+ */
 export function snapshot<T extends object>(proxyObject: T): Snapshot<T> {
   const proxyState = proxyStateMap.get(proxyObject as object)
   if (import.meta.env?.MODE !== 'production' && !proxyState) {
@@ -316,6 +364,16 @@ export function snapshot<T extends object>(proxyObject: T): Snapshot<T> {
   return createSnapshot(target, ensureVersion()) as Snapshot<T>
 }
 
+/**
+ * Marks an object to be excluded from proxying
+ *
+ * Objects marked with ref will be kept as references in snapshots
+ * instead of being deeply copied.
+ *
+ * @template T - Type of the object to mark as a reference
+ * @param {T} obj - The object to mark as a reference
+ * @returns {T & { $$valtioSnapshot: T }} The same object with a type marker
+ */
 export function ref<T extends object>(obj: T) {
   refSet.add(obj)
   return obj as T & { $$valtioSnapshot: T }

src/vanilla/utils/deepClone.ts

@@ -13,6 +13,14 @@ const getDefaultRefSet = (): WeakSet<object> => {
   return defaultRefSet
 }
 
+/**
+ * Creates a deep clone of an object, maintaining proxy behavior for Maps and Sets
+ *
+ * @template T - Type of the object to clone
+ * @param {T} obj - The object to clone
+ * @param {Function} [getRefSet=getDefaultRefSet] - Function to get the set of reference objects
+ * @returns {T} A deep clone of the input object
+ */
 export function deepClone<T>(
   obj: T,
   getRefSet: () => WeakSet<object> = getDefaultRefSet,

src/vanilla/utils/devtools.ts

@@ -22,11 +22,20 @@ type Options = {
 } & Config
 
 /**
- * devtools
+ * Connects a proxy object to Redux DevTools Extension for state debugging
+ *
+ * This allows real-time monitoring and time-travel debugging of state changes
+ * using the Redux DevTools browser extension.
  *
- * This is to connect with [Redux DevTools Extension](https://github.com/reduxjs/redux-devtools).
  * Limitation: Only plain objects/values are supported.
  *
+ * @template T - Type of the proxy object
+ * @param {T} proxyObject - The proxy object to connect to DevTools
+ * @param {Options} [options] - Configuration options for the DevTools connection
+ * @param {boolean} [options.enabled] - Explicitly enable or disable the connection
+ * @param {string} [options.name=''] - Name to display in DevTools
+ * @returns {Function|undefined} Unsubscribe function to disconnect from DevTools, or undefined if connection failed
+ *
  * @example
  * import { devtools } from 'valtio/utils'
  * const state = proxy({ count: 0, text: 'hello' })

src/vanilla/utils/proxyMap.ts

@@ -10,6 +10,12 @@ type InternalProxyObject<K, V> = Map<K, V> & {
   toJSON: () => Map<K, V>
 }
 
+/**
+ * Determines if an object is a proxy Map created with proxyMap
+ *
+ * @param {object} obj - The object to check
+ * @returns {boolean} True if the object is a proxy Map, false otherwise
+ */
 export const isProxyMap = (obj: object): boolean => {
   return (
     Symbol.toStringTag in obj &&
@@ -19,10 +25,17 @@ export const isProxyMap = (obj: object): boolean => {
 }
 
 /**
- * proxyMap
+ * Creates a reactive Map that integrates with Valtio's proxy system
+ *
+ * This utility creates a Map-like object that works with Valtio's reactivity system,
+ * allowing you to track changes to the Map in the same way as regular proxy objects.
+ * The API is the same as the standard JavaScript Map.
  *
- * This is to create a proxy which mimic the native Map behavior.
- * The API is the same as Map API
+ * @template K - Type of the Map keys
+ * @template V - Type of the Map values
+ * @param {Iterable<[K, V]>} [entries] - Initial key-value pairs to populate the Map
+ * @returns {Map<K, V>} A proxy Map object that tracks changes
+ * @throws {TypeError} If entries is not iterable
  *
  * @example
  * import { proxyMap } from 'valtio/utils'

src/vanilla/utils/proxySet.ts

@@ -18,6 +18,12 @@ type InternalProxySet<T> = Set<T> & {
   isDisjointFrom: (other: Set<T>) => boolean
 }
 
+/**
+ * Determines if an object is a proxy Set created with proxySet
+ *
+ * @param {object} obj - The object to check
+ * @returns {boolean} True if the object is a proxy Set, false otherwise
+ */
 export const isProxySet = (obj: object): boolean => {
   return (
     Symbol.toStringTag in obj &&
@@ -27,14 +33,22 @@ export const isProxySet = (obj: object): boolean => {
 }
 
 /**
- * proxySet
+ * Creates a reactive Set that integrates with Valtio's proxy system
  *
- * This is to create a proxy which mimic the native Set behavior.
- * The API is the same as Set API
+ * This utility creates a Set-like object that works with Valtio's reactivity system,
+ * allowing you to track changes to the Set in the same way as regular proxy objects.
+ * The API extends the standard JavaScript Set with additional set operations like
+ * union, intersection, difference, etc.
+ *
+ * @template T - Type of the Set elements
+ * @param {Iterable<T>} [initialValues] - Initial values to populate the Set
+ * @returns {Set<T>} A reactive proxy Set with extended methods
+ * @throws {TypeError} If initialValues is not iterable
  *
  * @example
  * import { proxySet } from 'valtio/utils'
  * const state = proxySet([1,2,3])
+ *
  * // can be used inside a proxy as well
  * const state = proxy({
  *   count: 1,