diff --git a/docs/api/core/bind.md b/docs/api/core/bind.md index 4c1cc3c..83b9191 100644 --- a/docs/api/core/bind.md +++ b/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( getObservable: (...args: A) => Observable, - defaultValue?: T, + defaultValue?: (...args: A) => T | T, ): [(...args: A) => Exclude, (...args: A) => Observable] ``` diff --git a/docs/api/core/subscribe.md b/docs/api/core/subscribe.md index a5f865a..1be9157 100644 --- a/docs/api/core/subscribe.md +++ b/docs/api/core/subscribe.md @@ -3,29 +3,32 @@ id: subscribe title: --- -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 + source$?: Observable 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. +::: diff --git a/docs/api/core/useSubscribe.md b/docs/api/core/useSubscribe.md deleted file mode 100644 index c215c70..0000000 --- a/docs/api/core/useSubscribe.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: useSubscribe(source) -sidebar_label: useSubcribe() ---- - -A React hook that creates a subscription to the provided Observable once the -component mounts and it unsubscribes when the component unmounts. - -```ts -function useSubscribe(source$: Observable): void; -``` - -#### Arguments - -- `source$`: Source Observable that the hook will subscribe to. - -:::note Important -This hook doesn't trigger any updates. -::: - -## See also - -* [``](subscribe) diff --git a/docs/api/utils/collect.md b/docs/api/utils/collect.md index def5dac..417c184 100644 --- a/docs/api/utils/collect.md +++ b/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. diff --git a/docs/api/utils/collectValues.md b/docs/api/utils/collectValues.md index fec9415..2e303c3 100644 --- a/docs/api/utils/collectValues.md +++ b/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. diff --git a/docs/api/utils/combineKeys.md b/docs/api/utils/combineKeys.md new file mode 100644 index 0000000..dc6b853 --- /dev/null +++ b/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 = ( + keys$: Observable | Set>, + getInner$: (key: K) => Observable, +): Observable> +``` + +#### 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) diff --git a/docs/api/utils/contextBinder.md b/docs/api/utils/contextBinder.md new file mode 100644 index 0000000..ba51924 --- /dev/null +++ b/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( + ...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(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
{contextDisplay}
+} +``` diff --git a/docs/api/utils/createKeyedSignal.md b/docs/api/utils/createKeyedSignal.md new file mode 100644 index 0000000..1d587c5 --- /dev/null +++ b/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
( + keySelector?: (signal: T) => K, + mapper?: (...args: A) => T, +): [(key: K) => GroupedObservable, (...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) diff --git a/docs/api/utils/createSignal.md b/docs/api/utils/createSignal.md new file mode 100644 index 0000000..d958acf --- /dev/null +++ b/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( + mapper?: (...args: A) => T, +): [Observable, (...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) diff --git a/docs/api/utils/partitionByKey.md b/docs/api/utils/partitionByKey.md new file mode 100644 index 0000000..650eaac --- /dev/null +++ b/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( + stream: Observable, + keySelector: (value: T) => K, + streamSelector: (grouped: Observable, key: K) => Observable, +): [(key: K) => GroupedObservable, Observable] +``` + +#### 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) diff --git a/docs/api/utils/split.md b/docs/api/utils/split.md index 95c9fa7..af3b328 100644 --- a/docs/api/utils/split.md +++ b/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. diff --git a/sidebars.js b/sidebars.js index a44e1aa..1c2bbd6 100644 --- a/sidebars.js +++ b/sidebars.js @@ -10,7 +10,6 @@ module.exports = { "api/core/bind", "api/core/shareLatest", "api/core/suspense", - "api/core/useSubscribe", "api/core/subscribe", ], }, @@ -18,14 +17,25 @@ module.exports = { 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", + ] + } ], }, ],