Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update reference docs to match 0.8.0 #38

Merged
merged 3 commits into from
May 2, 2021
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/api/core/bind.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>]
```

Expand Down
25 changes: 14 additions & 11 deletions docs/api/core/subscribe.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
josepot marked this conversation as resolved.
Show resolved Hide resolved
- `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.
:::
23 changes: 0 additions & 23 deletions docs/api/core/useSubscribe.md

This file was deleted.

4 changes: 4 additions & 0 deletions docs/api/utils/collect.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
5 changes: 5 additions & 0 deletions docs/api/utils/collectValues.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
27 changes: 27 additions & 0 deletions docs/api/utils/combineKeys.md
Original file line number Diff line number Diff line change
@@ -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)
44 changes: 44 additions & 0 deletions docs/api/utils/contextBinder.md
Original file line number Diff line number Diff line change
@@ -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>
}
```
36 changes: 36 additions & 0 deletions docs/api/utils/createKeyedSignal.md
Original file line number Diff line number Diff line change
@@ -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)
31 changes: 31 additions & 0 deletions docs/api/utils/createSignal.md
Original file line number Diff line number Diff line change
@@ -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)
33 changes: 33 additions & 0 deletions docs/api/utils/partitionByKey.md
Original file line number Diff line number Diff line change
@@ -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)
4 changes: 4 additions & 0 deletions docs/api/utils/split.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
18 changes: 14 additions & 4 deletions sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -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",
]
}
],
},
],
Expand Down