/** * `KV` is an abstraction for managing state-based applications using [Env](./Env.ts.md). It exposes an extensible * get/set/delete API for managing keys to values. Every `KV` is connected to an `Env` that will * provide the default value lazily when first asked for or after being deleted previously. * * The provided implementation will also send events containing all of the creations/updates/deletes * occurring in real-time. * @since 0.11.0 */ import * as B from 'fp-ts/boolean' import { Eq, EqStrict } from 'fp-ts/Eq' import { pipe } from 'fp-ts/function' import * as RM from 'fp-ts/ReadonlyMap' import { not } from 'fp-ts/Refinement' import { fst, snd } from 'fp-ts/Tuple2' import * as A from './Adapter' import * as D from './Disposable' import * as E from './Env' import * as EE from './EnvEither' import { alwaysEqualsEq, deepEqualsEq } from './Eq' import * as O from './Option' import * as RS from './ReaderStream' import * as R from './Resume' /** * @since 0.11.0 * @category Model */ export interface KV extends Eq { readonly key: K readonly initial: E.Env } /** * @since 0.11.0 * @category Model */ export interface Of extends KV {} /** * @since 0.11.0 * @category Type-level */ export type KeyOf = [A] extends [KV] ? R : never /** * @since 0.11.0 * @category Type-level */ export type EnvOf = [A] extends [KV] ? R : never /** * @since 0.11.0 * @category Type-level */ export type ValueOf = [A] extends [KV] ? R : never /** * @since 0.11.0 * @category Options */ export type Options = { readonly key?: K } & Partial> /** * Note that by default an incrementing index is utilized to generate a key if one is not * provided. In other words, by default, this is not referentially transparent for * your own convenience * * @since 0.11.0 * @category Constructor */ export function make( initial: E.Env, options: Options = {}, ): KV { const { equals = deepEqualsEq.equals, key = Symbol() as unknown as K } = options return { key, initial, equals, } } /** * @since 0.11.0 * @category Combinator */ export const get = (kv: KV) => E.asksE((e: Get) => e.getKV(kv)) /** * @since 0.12.0 * @category Environment */ export interface Get { readonly getKV: (kv: KV) => E.Env } /** * @since 0.11.0 * @category Combinator */ export const has = (kv: KV) => E.asksE((e: Has) => e.hasKV(kv)) /** * @since 0.12.0 * @category Environment */ export interface Has { readonly hasKV: (kv: KV) => E.Of } /** * @since 0.11.0 * @category Combinator */ export const set = (kv: KV) => (value: A) => E.asksE((e: Set) => e.setKV(kv, value)) /** * @since 0.12.0 * @category Environment */ export interface Set { readonly setKV: (kv: KV, value: A) => E.Env } /** * @since 0.11.0 * @category Combinator */ export const update = (kv: KV) => (f: (value: A) => E.Env) => pipe(kv, get, E.chainW(f), E.chainW(set(kv))) /** * @since 0.11.0 * @category Combinator */ export const remove = (kv: KV) => E.asksE((e: Remove) => e.removeKV(kv)) /** * @since 0.12.0 * @category Environment */ export interface Remove { readonly removeKV: (kv: KV) => E.Env> } /** * @since 0.12.0 * @category Environment */ export interface Events { readonly kvEvents: Adapter } /** * @since 0.12.0 * @category Combinator */ export const getAdapter = E.asks((e: Events) => e.kvEvents) /** * @since 0.11.0 * @category Combinator */ export const getSendEvent = pipe(getAdapter, E.map(fst)) /** * @since 0.11.0 * @category Combinator */ export const sendEvent = (event: Event) => pipe(getSendEvent, E.apW(E.of(event))) /** * @since 0.12.0 * @category Combinator */ export const getKVEvents: RS.ReaderStream> = (e: Events) => snd(e.kvEvents) /** * @since 0.11.0 * @category Combinator */ export const listenTo = (kv: KV): RS.ReaderStream> => pipe( getKVEvents, RS.filter((x) => x.key === kv.key), ) /** * @since 0.11.0 * @category Combinator */ export const listenToValues = ( kv: KV, ): RS.ReaderStream> => pipe( kv, listenTo, RS.map((e) => (isRemoved(e) ? O.none : O.some(e.value))), RS.startWith(O.none), ) /** * @since 0.12.0 * @category Environment */ export interface ParentEnv { readonly parentKVEnv: O.Option } /** * @since 0.11.0 * @category Combinator */ export const getParentEnv = E.asks((e: ParentEnv) => e.parentKVEnv) /** * Traverse up the tree of KVEnv and parent KVEnv to find the closest KVEnv that * has reference for a given KV. This is useful for providing a React-like Context * API atop of KV. * @since 0.11.0 * @category Combinator */ export const findKVProvider = (ref: KV): E.Env => { const check = pipe( E.Do, E.bindW('hasRef', () => has(ref)), E.bindW('env', () => getEnv), ) return pipe( check, E.chainW( E.chainRec(({ hasRef, env }: E.ValueOf) => { if (hasRef || O.isNone(env.parentKVEnv)) { return pipe(env, EE.of) } return pipe(check, E.useSome(env.parentKVEnv.value), EE.fromEnvL) }), ), ) } /** * @since 0.11.0 * @category Combinator */ export const withProvider = (kv: KV) => (env: E.Env) => pipe( kv, findKVProvider, E.chainW((refs) => pipe(env, E.useSome(refs))), ) /** * @since 0.11.0 * @category Combinator */ export const withProviderStream = (kv: KV) => (rs: RS.ReaderStream) => pipe( kv, findKVProvider, RS.fromEnv, RS.switchMapW((refs) => pipe(rs, RS.useSome(refs))), ) /** * @since 0.12.0 * @category Environment */ export interface Env extends Get, Has, Set, Remove, Events, ParentEnv {} /** * @since 0.12.0 * @category Combinator */ export const getEnv = E.asks( ({ getKV, hasKV, setKV, removeKV, kvEvents, parentKVEnv }: Env): Env => ({ getKV, hasKV, setKV, removeKV, kvEvents, parentKVEnv, }), ) /** * @since 0.11.0 * @category Model */ export type Adapter = A.Adapter> /** * @since 0.12.0 * @category Model */ export type Event = Created | Updated | Removed /** * @since 0.12.0 * @category Model */ export interface Created { readonly _tag: 'Created' readonly key: K readonly value: A readonly fromAncestor: boolean } /** * @since 0.11.0 * @category Refinement */ export const isCreated = (event: Event): event is Created => event._tag === 'Created' /** * @since 0.12.0 * @category Model */ export interface Updated { readonly _tag: 'Updated' readonly key: K readonly previousValue: A readonly value: A readonly fromAncestor: boolean } /** * @since 0.11.0 * @category Refinement */ export const isUpdated = (event: Event): event is Updated => event._tag === 'Updated' /** * @since 0.12.0 * @category Model */ export interface Removed { readonly _tag: 'Removed' readonly key: K readonly fromAncestor: boolean } /** * @since 0.11.0 * @category Refinement */ export const isRemoved = (event: Event): event is Removed => event._tag === 'Removed' /** * @since 0.12.0 * @category Deconstructor */ export const matchW = ( onCreated: (value: A, key: K) => B, onUpdated: (previousValue: A, value: A, key: K) => C, onDeleted: (key: K) => D, ) => (event: Event): B | C | D => { if (event._tag === 'Updated') { return onUpdated(event.previousValue, event.value, event.key) } if (event._tag === 'Created') { return onCreated(event.value, event.key) } return onDeleted(event.key) } /** * @since 0.12.0 * @category Deconstructor */ export const match: ( onCreated: (value: A, key: K) => B, onUpdated: (previousValue: A, value: A, key: K) => B, onDeleted: (key: K) => B, ) => (event: Event) => B = matchW /** * @since 0.12.0 * @category Environment Constructor */ export function env(options: EnvOptions = {}): Env { const { initial = [], kvEvents = A.create() } = options const references = new Map(initial) const sendEvent = createSendEvent(references, kvEvents) return { ...makeGetKV(references, sendEvent), ...makeHasKV(references), ...makeSetKV(references, sendEvent), ...makeDeleteKV(references, sendEvent), parentKVEnv: O.fromNullable(options.parentEnv), kvEvents: [sendEvent, kvEvents[1]], } } /** * @since 0.11.0 * @category Options */ export type EnvOptions = { readonly initial?: Iterable readonly kvEvents?: Adapter readonly parentEnv?: Env } function createSendEvent(references: Map, [push]: Adapter) { return (event: Event) => pipe( event.fromAncestor, B.matchW( // Only update our local references when event.fromAncestor is false // as this indicates the event originates from within our current environment. () => { if (event._tag === 'Created' || event._tag === 'Updated') { references.set(event.key, event.value) } else { references.delete(event.key) } push(event) }, // When event.fromAncestor is true, the event originated from another environment. // We only replicate the event such that a descendant KVEnv can be re-sampled when it subscribes to // a Ref from an Ancestor's environment. () => push(event), ), ) } function makeGetKV(references: Map, sendEvent: (event: Event) => void): Get { return { getKV(kv) { if (references.has(kv.key)) { return E.of(references.get(kv.key)!) } return pipe( kv.initial, E.chainFirstIOK( (value) => () => sendEvent({ _tag: 'Created', key: kv.key, value, fromAncestor: false }), ), ) }, } } function makeHasKV(references: Map): Has { return { hasKV(kv) { return E.fromIO(() => references.has(kv.key)) }, } } function makeSetKV(references: Map, sendEvent: (event: Event) => void): Set { const { getKV } = makeGetKV(references, sendEvent) return { setKV(kv, value) { return pipe( kv, getKV, E.map((previousValue) => [previousValue, !pipe(value, kv.equals(previousValue))] as const), E.chainFirstIOK( ([previousValue, changed]) => () => // Only send event when things changed changed && sendEvent({ _tag: 'Updated', key: kv.key, previousValue, value, fromAncestor: false, }), ), E.map(([previousValue, changed]) => (changed ? value : previousValue)), ) }, } } function makeDeleteKV( references: Map, sendEvent: (event: Event) => void, ): Remove { return { removeKV(kv) { return pipe( E.fromIO(() => (references.has(kv.key) ? O.some(references.get(kv.key)) : O.none)), E.chainFirstIOK( () => () => sendEvent({ _tag: 'Removed', key: kv.key, fromAncestor: false }), ), ) }, } } /** * Sample an Env with the latest references when updates have occured. * @since 0.11.0 * @category Combinator */ export const sample = (env: E.Env): RS.ReaderStream => pipe( getKVEvents, RS.filter(not(isCreated)), RS.startWith(null), RS.exhaustMapLatestEnv(() => env), ) /** * A shared KV for keeping track of a context's disposable resources. * @since 0.11.0 * @category KV */ export const Disposable = make(E.fromIO(D.settable), { ...EqStrict, key: Symbol.for('@typed/fp/KV.Disposable'), }) /** * @since 0.11.0 * @category Use */ export const useKeyedEnvs = (Eq: Eq) => { const refs = make( E.fromIO(() => new Map()), alwaysEqualsEq, ) const lookup = RM.lookup(Eq) const getOrCreate = (key: A, value: E.Env) => pipe( refs, get, E.chainW((m) => pipe( m, lookup(key), O.matchW( () => pipe( value, E.tap((x: Env) => m.set(key, x)), ), E.of, ), ), ), ) const dispose = pipe( Disposable, get, E.tap((d) => d.dispose()), E.chainFirstW(() => remove(Disposable)), ) return pipe( E.Do, E.apSW('parentEnv', getEnv), E.bindW('createRefs', ({ parentEnv }) => E.of((key: A) => { const r = env({ parentEnv }) return pipe( refs, get, E.map((m) => m.set(key, r)), E.constant(r), E.useSome(parentEnv), ) }), ), E.bindW('findRefs', ({ createRefs, parentEnv }) => E.of((key: A) => pipe(getOrCreate(key, createRefs(key)), E.useSome(parentEnv))), ), E.bindW('deleteRefs', ({ parentEnv }) => E.of( (key: A): D.Disposable => ({ dispose: () => pipe( parentEnv, get(refs), R.map((refs) => refs.get(key)), R.chainFirst(() => pipe( refs, get, E.tap((m) => m.delete(key)), )(parentEnv), ), R.chain((refs) => (refs ? dispose(refs) : R.of(null))), R.exec, ), }), ), ), E.map(({ findRefs, deleteRefs }) => ({ findRefs, deleteRefs } as const)), ) }