Update reference docs to match 0.8.0

docs/api/core/bind.md

@@ -61,7 +61,7 @@ Binds an Observable factory function to React, and returns a hook and shared str
 ```ts
 function bind<A extends unknown[], O>(
   getObservable: (...args: A) => Observable<O>,
-  defaultValue?: T,
+  defaultValue?: (...args: A) => T | T,
 ): [(...args: A) => Exclude<O, typeof SUSPENSE>, (...args: A) => Observable<O>]
 ```
 

docs/api/core/subscribe.md

@@ -3,29 +3,32 @@ id: subscribe
 title: <Subscribe />
 ---
 
-A React Component that creates a subscription to the provided Observable once
-the component mounts, and unsubscribes when the component unmounts.
+A React Component that manages the subscription of its children's Observables.
 
-It also acts as a Suspense boundary, rendering a fallback element until the
-suspended element resolves.
+It will subscribe to all the observables used by its children before they get 
+mounted, and will unsubscribe from all of them once it unmounts.
+
+If given a fallback, it also acts as a Suspense boundary, rendering the fallback
+element until the suspended element resolves.
 
 ```tsx
 const Subscribe: React.FC<{
-  source$: Observable<any>
+  source$?: Observable<any>
   fallback?: JSX.Element
 }>
 ```
 
 #### Properties
 
-- `source$`: Source Observable that the Component will subscribe to.
+- `source$`: (Optional) Source Observable that the Component should subscribe to, before its children renders.
 - `fallback`: (Optional) The JSX Element to be rendered before the
   subscription is created. Default: `null`.
 
-:::note Important
-This Component doesn't trigger any updates.
+:::note
+This Component doesn't trigger any updates if any of its subscription emits.
 :::
 
-## See also
-
-- [`useSubscribe()`](useSubscribe)
+:::note Important
+This Component first mounts itself rendering `null`, subscribes to `source$` and
+then it renders its children.
+:::

docs/api/utils/collect.md

@@ -3,6 +3,10 @@ title: collect(filter)
 sidebar_label: collect()
 ---
 
+:::caution
+This function is deprecated. [`partitionByKey`](partitionByKey) covers its intended use case.
+:::
+
 A [pipeable operator] that collects all the [`GroupedObservable`]s emitted by
 the source and emits a `Map` with the active inner observables.
 

docs/api/utils/collectValues.md

@@ -2,6 +2,11 @@
 title: collectValues()
 ---
 
+:::caution
+This function is deprecated. [`partitionByKey`](partitionByKey) with
+[`combineKeys`](combineKeys) covers its intended use case.
+:::
+
 A [pipeable operator] that collects all the [`GroupedObservable`]s emitted by
 the source and emits a `Map` with the latest values of the inner Observables.
 

docs/api/utils/combineKeys.md

@@ -0,0 +1,27 @@
+---
+title: combineKeys()
+sidebar_label: combineKeys()
+---
+
+Creates a stream that constructs a Map with the latest value of the inner stream
+of each key.
+
+```ts
+export const combineKeys = <K, T>(
+  keys$: Observable<Array<K> | Set<K>>,
+  getInner$: (key: K) => Observable<T>,
+): Observable<Map<K, T>>
+```
+
+#### Arguments
+
+- `keys$`: Stream of the list of keys to subscribe to.
+- `getInner$`: Function that returns the stream for each key.
+
+#### Returns
+
+A stream with a map containing the latest value from the stream of each key.
+
+## See also
+
+- [`partitionByKey()`](partitionByKey)

docs/api/utils/contextBinder.md

@@ -0,0 +1,44 @@
+---
+title: contextBinder()
+sidebar_label: contextBinder()
+---
+
+Returns a version of bind where its hook will have the first parameters bound
+the results of the provided function (which can use hooks)
+
+```ts
+export function contextBinder<A extends unknown[], T>(
+  ...args: Array<() => any>
+): typeof bind
+```
+
+#### Arguments
+
+- `...args`: A list of functions that its result will be bound to the first arguments
+within `getObservable` of the `bind` function enhanced by this function.
+
+#### Returns
+
+An enhanced `bind` function where it will have its first arguments bound to the
+return values of the input functions
+
+### Example
+
+```tsx
+const MyContext = React.createContext<number>(0);
+
+const myContextBind = contextBinder(
+  () => useContext(MyContext)
+);
+
+const [useValue, value$] = myContextBind(
+  (myContextValue, prefix: string) =>
+    of(prefix + ' ' + myContextValue)
+)
+
+const Component = () => {
+  const contextDisplay = useValue('Current context value:'))
+
+  return <div>{contextDisplay}</div>
+}
+```

docs/api/utils/createKeyedSignal.md

@@ -0,0 +1,36 @@
+---
+title: createKeyedSignal()
+sidebar_label: createKeyedSignal()
+---
+
+Creates a Signal grouped by a key. Essentially splits the producer and consumer
+of a Subject for each key.
+
+```ts
+export function createKeyedSignal<A extends unknown[], T>(
+  keySelector?: (signal: T) => K,
+  mapper?: (...args: A) => T,
+): [(key: K) => GroupedObservable<K, T>, (...args: A) => void]
+```
+
+#### Arguments
+
+- `keySelector?`: (Optional) A function that extracts the key from the emitted value.
+  If omitted, it will use the first argument as the key.
+
+- `mapper?`: (Optional) A function for mapping the arguments of the emitter function into
+the value of the Observable.
+
+  Defaults to `(v: Payload) => v`
+
+#### Returns
+
+`[1, 2]`:
+
+1. A function that returns the observable for a given key
+
+2. The emitter function
+
+## See also
+
+- [`createSignal()`](createSignal)

docs/api/utils/createSignal.md

@@ -0,0 +1,31 @@
+---
+title: createSignal()
+sidebar_label: createSignal()
+---
+
+Creates a Signal: it's like a subject, but with the consumer and the producer split.
+
+```ts
+export function createSignal<A extends unknown[], T>(
+  mapper?: (...args: A) => T,
+): [Observable<T>, (...args: A) => void]
+```
+
+#### Arguments
+
+- `mapper?`: (Optional) A function for mapping the arguments of the emitter function into
+the value of the Observable.
+
+  Defaults to `(v: Payload) => v`
+
+#### Returns
+
+`[1, 2]`:
+
+1. The observable for the signal
+
+2. The emitter function
+
+## See also
+
+- [`createKeyedSignal()`](createKeyedSignal)

docs/api/utils/partitionByKey.md

@@ -0,0 +1,33 @@
+---
+title: partitionByKey()
+sidebar_label: partitionByKey()
+---
+
+Groups the elements from the source stream by using a key selector, and maps
+each of these groups by using a map function.
+
+```ts
+export function partitionByKey<T, K, R>(
+  stream: Observable<T>,
+  keySelector: (value: T) => K,
+  streamSelector: (grouped: Observable<T>, key: K) => Observable<R>,
+): [(key: K) => GroupedObservable<K, R>, Observable<K[]>]
+```
+
+#### Arguments
+
+- `stream`: Input stream
+- `keySelector`: Function that specifies the key for each element in `stream`
+- `streamSelector`: Function to apply to each resulting group
+
+#### Returns
+
+`[1, 2]`:
+
+1. A function that accepts a key and returns a stream for the group of that key.
+
+2. A stream with the list of active keys
+
+## See also
+
+- [`combineKeys()`](combineKeys)

docs/api/utils/split.md

@@ -3,6 +3,10 @@ title: split(keySelector)
 sidebar_label: split()
 ---
 
+:::caution
+This function is deprecated. [`partitionByKey`](partitionByKey) covers its intended use case.
+:::
+
 A [pipeable operator] that groups the items emitted by the source based on the
 `keySelector` function, emitting one Observable for each group.
 

sidebars.js

@@ -10,22 +10,32 @@ module.exports = {
           "api/core/bind",
           "api/core/shareLatest",
           "api/core/suspense",
-          "api/core/useSubscribe",
           "api/core/subscribe",
         ],
       },
       {
         type: "category",
         label: "Utils",
         items: [
-          "api/utils/collect",
-          "api/utils/collectValues",
+          "api/utils/combineKeys",
+          "api/utils/contextBinder",
+          "api/utils/createSignal",
+          "api/utils/createKeyedSignal",
           "api/utils/mergeWithKey",
+          "api/utils/partitionByKey",
           "api/utils/selfDependant",
-          "api/utils/split",
           "api/utils/suspend",
           "api/utils/suspended",
           "api/utils/switchMapSuspended",
+          {
+            type: "category",
+            label: "Deprecated",
+            items: [
+              "api/utils/split",
+              "api/utils/collect",
+              "api/utils/collectValues",
+            ]
+          }
         ],
       },
     ],