From e63e4ae9fce94e8671b2739b281527cead30c223 Mon Sep 17 00:00:00 2001
From: Andrey Petrov <ndt.080@yandex.by>
Date: Wed, 21 Aug 2024 21:31:00 +0300
Subject: [PATCH] feat: update tsdoc comments and file with tests

---
 index.d.ts         | 54 ++++++++++++++++++++++++++++++++++++++++++++++
 test/index.test.ts | 16 +++++++-------
 2 files changed, 62 insertions(+), 8 deletions(-)

diff --git a/index.d.ts b/index.d.ts
index 46c3c20..8a07ec9 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -8,10 +8,40 @@ export type StoreKeys<T> = T extends {
   : never
 
 export interface UseStoreOptions<SomeStore, Value> {
+  /**
+   * Will re-render components only on specific key changes.
+   */
   keys?: StoreKeys<SomeStore>[]
+  /**
+   * Allows you to extract value from complex/deep objects
+   */
   selector?: (state: StoreValue<SomeStore>) => Value
 }
 
+/**
+ * Subscribe to store changes and get store’s value.
+ *
+ * Can be user with store builder too.
+ *
+ * ```js
+ * import { useStore } from 'nanostores/preact'
+ *
+ * import { router } from '../store/router'
+ *
+ * export const Layout = () => {
+ *   let page = useStore(router)
+ *   if (page.value.router === 'home') {
+ *     return <HomePage />
+ *   } else {
+ *     return <Error404 />
+ *   }
+ * }
+ * ```
+ *
+ * @param store Store instance.
+ * @param options
+ * @returns Store value.
+ */
 export function useStore<
   SomeStore extends Store,
   Value = StoreValue<SomeStore>
@@ -20,6 +50,30 @@ export function useStore<
   options: UseStoreOptions<SomeStore, Value> = {}
 ): ReadonlySignal<Value>
 
+/**
+ * Subscribe to store changes and get store’s value.
+ *
+ * Can be user with store builder too.
+ *
+ * ```js
+ * import { useLegacyStore } from 'nanostores/preact'
+ *
+ * import { router } from '../store/router'
+ *
+ * export const Layout = () => {
+ *   let page = useLegacyStore(router)
+ *   if (page.router === 'home') {
+ *     return <HomePage />
+ *   } else {
+ *     return <Error404 />
+ *   }
+ * }
+ * ```
+ *
+ * @param store Store instance.
+ * @param options
+ * @returns Store value.
+ */
 export function useLegacyStore<
   SomeStore extends Store,
   Value = StoreValue<SomeStore>
diff --git a/test/index.test.ts b/test/index.test.ts
index 17a9a0d..42693dd 100644
--- a/test/index.test.ts
+++ b/test/index.test.ts
@@ -9,7 +9,7 @@ import type { FunctionalComponent as FC } from 'preact'
 import { h } from 'preact'
 import { useState } from 'preact/hooks'
 
-import { useStore } from '../index.js'
+import { useLegacyStore } from '../index.js'
 
 afterEach(() => {
   window.document.head.innerHTML = ''
@@ -32,13 +32,13 @@ test('renders simple store', async () => {
 
   let Test1: FC = () => {
     renders += 1
-    let value = useStore(letter)
+    let value = useLegacyStore(letter)
     // @ts-expect-error: Preact type issue with data-*
     return h('div', { 'data-testid': 'test1' }, value)
   }
 
   let Test2: FC = () => {
-    let value = useStore(letter)
+    let value = useLegacyStore(letter)
     // @ts-expect-error: Preact type issue with data-*
     return h('div', { 'data-testid': 'test2' }, value)
   }
@@ -96,13 +96,13 @@ test('does not reload store on component changes', async () => {
   })
 
   let TestA: FC = () => {
-    let simpleValue = useStore(simple)
+    let simpleValue = useLegacyStore(simple)
     // @ts-expect-error: Preact type issue with data-*
     return h('div', { 'data-testid': 'test' }, `1 ${simpleValue}`)
   }
 
   let TestB: FC = () => {
-    let simpleValue = useStore(simple)
+    let simpleValue = useLegacyStore(simple)
     // @ts-expect-error: Preact type issue with data-*
     return h('div', { 'data-testid': 'test' }, `2 ${simpleValue}`)
   }
@@ -166,7 +166,7 @@ test('has keys option', async () => {
   let MapTest: FC = () => {
     renderCount++
     let [keys, setKeys] = useState<(keyof MapStore)[]>(['a'])
-    let { a, b } = useStore(mapSore, { keys })
+    let { a, b } = useLegacyStore(mapSore, { keys })
     return h(
       // @ts-expect-error: Preact type issue with data-*
       'div',
@@ -231,7 +231,7 @@ test('return correct value for Atom, if store was changed between rendering and
   }
 
   let Wrapper: FC = () => {
-    let value = useStore(store)
+    let value = useLegacyStore(store)
     return h('p', {}, renderWithMutate(value))
   }
 
@@ -250,7 +250,7 @@ test('return correct value for MapStore, if store was changed between rendering
   }
 
   let Wrapper: FC = () => {
-    let value = useStore(store).value
+    let value = useLegacyStore(store).value
     return h('p', {}, renderWithMutate(value))
   }