Add missing functions to the documentation

[rveciana]

The official docs aren't complete, and it would be a good idea adding the missing parts of the library. I took these notes with all the functions, types and missing parts, along with some comments I found in the code that could help doing this:

Core

Types:

• AddStopArg,
• DefaultedStateObservable,
• EmptyObservableError,
• NoSubscribersError,
• PipeState: see notes below
• StateObservable,
• StatePromise,
• WithDefaultOperator,

Functions:

• liftSuspense: see notes below

• sinkSuspense: see notes below

• SUSPENSE,

• withDefault: see notes below

• bind

• shareLatest

• state

Tsx components:

• RemoveSubscribe
• Subscribe
• useStateObservable

Utils

types:

• MapWithChanges
• KeyChanges

functions:

• combineKeys
• createSignal
• createKeyedSignal
• mergeWithKey
• partitionByKey
• toKeySet
• suspend
• suspended
• switchMapSuspended
• selfDependent
• contextBinder
• createListener: see notes below

Comments I found on CHANGELOG.md

sinkSuspense() is an operator that when it receives a SUSPENSE, it will throw it as an error down the stream, which resets all of the observables down below. It will then hold the subscription to the upstream, waiting for a resubscription to happen immediately. If it doesn't happen, then it will unsubscribe from upstream.

liftSuspense() is an operator that when it receives SUSPENSE as an error, it will immediately resubscribe to its upstream, and emit SUSPENSE as a value.

This allows to avoid dealing with SUSPENSE on the streams that are in-between the one that generates SUSPENSE and the one that needs to receive it.

const account$ = accountSwitch$.pipe(switchMapSuspended((v) => fetchAccount(v)))

  

const posts$ = account$.pipe(

switchMap((v) => (v === SUSPENSE ? of(SUSPENSE) : fetchPosts(v))),

)

  

/// with sinkSuspense

const account$ = accountSwitch$.pipe(

switchMapSuspended((v) => fetchAccount(v)),

sinkSuspense(),

)

  

const posts$ = account$.pipe(switchMap((v) => fetchPosts(v)))

• .pipeState(), withDefault()

StateObservables now have a shorthand method .pipeState(...args) which works as RxJS .pipe(, but it wraps the result into a new state.

const newState$ = state(

parent$.pipe(

map(...)

)

)

  

// Becomes

const newState$ = parent$.pipeState(

map(...)

)

withDefault(value) is an operator that creates a DefaultedStateObservable. It can be used at the end of pipeState to set the default value for that one.

const newState$ = state(

parent$.pipe(

map(...)

),

"defaultVal"

)

  

// Becomes

const newState$ = parent$.pipeState(

map(...),

withDefault("defaultVal")

)

createListener. No docs found except for the code, that is really simple.

/**

• Creates a void signal. It's sugar for splitting the Observer and the Observable of a signal.

• @returns [1, 2]

• 1. The Observable
• 2. The emitter function.

*/

export function createListener(...args: any[]) {

return (createSignal as any)(...args)

}