384 lines
11 KiB
TypeScript
384 lines
11 KiB
TypeScript
|
/**
|
||
|
|
* Multi-way trees (aka rose trees) and forests, where a forest is
|
||
|
|
*
|
||
|
|
* ```ts
|
||
|
|
* type Forest<A> = Array<Tree<A>>
|
||
|
|
* ```
|
||
|
|
*
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
import { Applicative1 } from './Applicative'
|
||
|
|
import { Apply1 } from './Apply'
|
||
|
|
import { Chain1 } from './Chain'
|
||
|
|
import { Comonad1 } from './Comonad'
|
||
|
|
import { Eq } from './Eq'
|
||
|
|
import { Foldable1 } from './Foldable'
|
||
|
|
import { Functor1 } from './Functor'
|
||
|
|
import { HKT, Kind, Kind2, Kind3, Kind4, URIS, URIS2, URIS3, URIS4 } from './HKT'
|
||
|
|
import { Monad as MonadHKT, Monad1, Monad2, Monad2C, Monad3, Monad3C, Monad4 } from './Monad'
|
||
|
|
import { Monoid } from './Monoid'
|
||
|
|
import { Pointed1 } from './Pointed'
|
||
|
|
import { Predicate } from './Predicate'
|
||
|
|
import { Show } from './Show'
|
||
|
|
import { PipeableTraverse1, Traversable1 } from './Traversable'
|
||
|
|
/**
|
||
|
|
* @category model
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare type Forest<A> = Array<Tree<A>>
|
||
|
|
/**
|
||
|
|
* @category model
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export interface Tree<A> {
|
||
|
|
readonly value: A
|
||
|
|
readonly forest: Forest<A>
|
||
|
|
}
|
||
|
|
/**
|
||
|
|
* @category constructors
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare function make<A>(value: A, forest?: Forest<A>): Tree<A>
|
||
|
|
/**
|
||
|
|
* @category instances
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare function getShow<A>(S: Show<A>): Show<Tree<A>>
|
||
|
|
/**
|
||
|
|
* @category instances
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare function getEq<A>(E: Eq<A>): Eq<Tree<A>>
|
||
|
|
/**
|
||
|
|
* Neat 2-dimensional drawing of a forest
|
||
|
|
*
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare function drawForest(forest: Forest<string>): string
|
||
|
|
/**
|
||
|
|
* Neat 2-dimensional drawing of a tree
|
||
|
|
*
|
||
|
|
* @example
|
||
|
|
* import { make, drawTree } from 'fp-ts/Tree'
|
||
|
|
*
|
||
|
|
* const fa = make('a', [
|
||
|
|
* make('b'),
|
||
|
|
* make('c'),
|
||
|
|
* make('d', [make('e'), make('f')])
|
||
|
|
* ])
|
||
|
|
*
|
||
|
|
* assert.strictEqual(drawTree(fa), `a
|
||
|
|
* ├─ b
|
||
|
|
* ├─ c
|
||
|
|
* └─ d
|
||
|
|
* ├─ e
|
||
|
|
* └─ f`)
|
||
|
|
*
|
||
|
|
*
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare function drawTree(tree: Tree<string>): string
|
||
|
|
/**
|
||
|
|
* Build a (possibly infinite) tree from a seed value in breadth-first order.
|
||
|
|
*
|
||
|
|
* @category constructors
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare function unfoldTree<A, B>(b: B, f: (b: B) => [A, Array<B>]): Tree<A>
|
||
|
|
/**
|
||
|
|
* Build a (possibly infinite) forest from a list of seed values in breadth-first order.
|
||
|
|
*
|
||
|
|
* @category constructors
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare function unfoldForest<A, B>(bs: Array<B>, f: (b: B) => [A, Array<B>]): Forest<A>
|
||
|
|
/**
|
||
|
|
* Monadic tree builder, in depth-first order
|
||
|
|
*
|
||
|
|
* @category constructors
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare function unfoldTreeM<M extends URIS4>(
|
||
|
|
M: Monad4<M>
|
||
|
|
): <S, R, E, A, B>(b: B, f: (b: B) => Kind4<M, S, R, E, [A, Array<B>]>) => Kind4<M, S, R, E, Tree<A>>
|
||
|
|
export declare function unfoldTreeM<M extends URIS3>(
|
||
|
|
M: Monad3<M>
|
||
|
|
): <R, E, A, B>(b: B, f: (b: B) => Kind3<M, R, E, [A, Array<B>]>) => Kind3<M, R, E, Tree<A>>
|
||
|
|
export declare function unfoldTreeM<M extends URIS3, E>(
|
||
|
|
M: Monad3C<M, E>
|
||
|
|
): <R, A, B>(b: B, f: (b: B) => Kind3<M, R, E, [A, Array<B>]>) => Kind3<M, R, E, Tree<A>>
|
||
|
|
export declare function unfoldTreeM<M extends URIS2>(
|
||
|
|
M: Monad2<M>
|
||
|
|
): <E, A, B>(b: B, f: (b: B) => Kind2<M, E, [A, Array<B>]>) => Kind2<M, E, Tree<A>>
|
||
|
|
export declare function unfoldTreeM<M extends URIS2, E>(
|
||
|
|
M: Monad2C<M, E>
|
||
|
|
): <A, B>(b: B, f: (b: B) => Kind2<M, E, [A, Array<B>]>) => Kind2<M, E, Tree<A>>
|
||
|
|
export declare function unfoldTreeM<M extends URIS>(
|
||
|
|
M: Monad1<M>
|
||
|
|
): <A, B>(b: B, f: (b: B) => Kind<M, [A, Array<B>]>) => Kind<M, Tree<A>>
|
||
|
|
export declare function unfoldTreeM<M>(
|
||
|
|
M: MonadHKT<M>
|
||
|
|
): <A, B>(b: B, f: (b: B) => HKT<M, [A, Array<B>]>) => HKT<M, Tree<A>>
|
||
|
|
/**
|
||
|
|
* Monadic forest builder, in depth-first order
|
||
|
|
*
|
||
|
|
* @category constructors
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare function unfoldForestM<M extends URIS4>(
|
||
|
|
M: Monad4<M>
|
||
|
|
): <S, R, E, A, B>(bs: Array<B>, f: (b: B) => Kind4<M, S, R, E, [A, Array<B>]>) => Kind4<M, S, R, E, Forest<A>>
|
||
|
|
export declare function unfoldForestM<M extends URIS3>(
|
||
|
|
M: Monad3<M>
|
||
|
|
): <R, E, A, B>(bs: Array<B>, f: (b: B) => Kind3<M, R, E, [A, Array<B>]>) => Kind3<M, R, E, Forest<A>>
|
||
|
|
export declare function unfoldForestM<M extends URIS3, E>(
|
||
|
|
M: Monad3C<M, E>
|
||
|
|
): <R, A, B>(bs: Array<B>, f: (b: B) => Kind3<M, R, E, [A, Array<B>]>) => Kind3<M, R, E, Forest<A>>
|
||
|
|
export declare function unfoldForestM<M extends URIS2>(
|
||
|
|
M: Monad2<M>
|
||
|
|
): <R, E, B>(bs: Array<B>, f: (b: B) => Kind2<M, R, [E, Array<B>]>) => Kind2<M, R, Forest<E>>
|
||
|
|
export declare function unfoldForestM<M extends URIS2, E>(
|
||
|
|
M: Monad2C<M, E>
|
||
|
|
): <A, B>(bs: Array<B>, f: (b: B) => Kind2<M, E, [A, Array<B>]>) => Kind2<M, E, Forest<A>>
|
||
|
|
export declare function unfoldForestM<M extends URIS>(
|
||
|
|
M: Monad1<M>
|
||
|
|
): <A, B>(bs: Array<B>, f: (b: B) => Kind<M, [A, Array<B>]>) => Kind<M, Forest<A>>
|
||
|
|
export declare function unfoldForestM<M>(
|
||
|
|
M: MonadHKT<M>
|
||
|
|
): <A, B>(bs: Array<B>, f: (b: B) => HKT<M, [A, Array<B>]>) => HKT<M, Forest<A>>
|
||
|
|
/**
|
||
|
|
* Fold a tree into a "summary" value in depth-first order.
|
||
|
|
*
|
||
|
|
* For each node in the tree, apply `f` to the `value` and the result of applying `f` to each `forest`.
|
||
|
|
*
|
||
|
|
* This is also known as the catamorphism on trees.
|
||
|
|
*
|
||
|
|
* @example
|
||
|
|
* import { fold, make } from 'fp-ts/Tree'
|
||
|
|
* import { concatAll } from 'fp-ts/Monoid'
|
||
|
|
* import { MonoidSum } from 'fp-ts/number'
|
||
|
|
*
|
||
|
|
* const t = make(1, [make(2), make(3)])
|
||
|
|
*
|
||
|
|
* const sum = concatAll(MonoidSum)
|
||
|
|
*
|
||
|
|
* // Sum the values in a tree:
|
||
|
|
* assert.deepStrictEqual(fold((a: number, bs: Array<number>) => a + sum(bs))(t), 6)
|
||
|
|
*
|
||
|
|
* // Find the maximum value in the tree:
|
||
|
|
* assert.deepStrictEqual(fold((a: number, bs: Array<number>) => bs.reduce((b, acc) => Math.max(b, acc), a))(t), 3)
|
||
|
|
*
|
||
|
|
* // Count the number of leaves in the tree:
|
||
|
|
* assert.deepStrictEqual(fold((_: number, bs: Array<number>) => (bs.length === 0 ? 1 : sum(bs)))(t), 2)
|
||
|
|
*
|
||
|
|
* @category folding
|
||
|
|
* @since 2.6.0
|
||
|
|
*/
|
||
|
|
export declare function fold<A, B>(f: (a: A, bs: Array<B>) => B): (tree: Tree<A>) => B
|
||
|
|
/**
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare const ap: <A>(fa: Tree<A>) => <B>(fab: Tree<(a: A) => B>) => Tree<B>
|
||
|
|
/**
|
||
|
|
* Composes computations in sequence, using the return value of one computation to determine the next computation.
|
||
|
|
*
|
||
|
|
* @category Monad
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare const chain: <A, B>(f: (a: A) => Tree<B>) => (ma: Tree<A>) => Tree<B>
|
||
|
|
/**
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare const extend: <A, B>(f: (wa: Tree<A>) => B) => (wa: Tree<A>) => Tree<B>
|
||
|
|
/**
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare const duplicate: <A>(wa: Tree<A>) => Tree<Tree<A>>
|
||
|
|
/**
|
||
|
|
* @category sequencing
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare const flatten: <A>(mma: Tree<Tree<A>>) => Tree<A>
|
||
|
|
/**
|
||
|
|
* `map` can be used to turn functions `(a: A) => B` into functions `(fa: F<A>) => F<B>` whose argument and return types
|
||
|
|
* use the type constructor `F` to represent some computational context.
|
||
|
|
*
|
||
|
|
* @category mapping
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare const map: <A, B>(f: (a: A) => B) => (fa: Tree<A>) => Tree<B>
|
||
|
|
/**
|
||
|
|
* @category folding
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare const reduce: <A, B>(b: B, f: (b: B, a: A) => B) => (fa: Tree<A>) => B
|
||
|
|
/**
|
||
|
|
* @category folding
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare const foldMap: <M>(M: Monoid<M>) => <A>(f: (a: A) => M) => (fa: Tree<A>) => M
|
||
|
|
/**
|
||
|
|
* @category folding
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare const reduceRight: <A, B>(b: B, f: (a: A, b: B) => B) => (fa: Tree<A>) => B
|
||
|
|
/**
|
||
|
|
* @category Extract
|
||
|
|
* @since 2.6.2
|
||
|
|
*/
|
||
|
|
export declare const extract: <A>(wa: Tree<A>) => A
|
||
|
|
/**
|
||
|
|
* @category traversing
|
||
|
|
* @since 2.6.3
|
||
|
|
*/
|
||
|
|
export declare const traverse: PipeableTraverse1<URI>
|
||
|
|
/**
|
||
|
|
* @category traversing
|
||
|
|
* @since 2.6.3
|
||
|
|
*/
|
||
|
|
export declare const sequence: Traversable1<URI>['sequence']
|
||
|
|
/**
|
||
|
|
* @category constructors
|
||
|
|
* @since 2.7.0
|
||
|
|
*/
|
||
|
|
export declare const of: <A>(a: A) => Tree<A>
|
||
|
|
/**
|
||
|
|
* @category type lambdas
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare const URI = 'Tree'
|
||
|
|
/**
|
||
|
|
* @category type lambdas
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare type URI = typeof URI
|
||
|
|
declare module './HKT' {
|
||
|
|
interface URItoKind<A> {
|
||
|
|
readonly [URI]: Tree<A>
|
||
|
|
}
|
||
|
|
}
|
||
|
|
/**
|
||
|
|
* @category instances
|
||
|
|
* @since 2.7.0
|
||
|
|
*/
|
||
|
|
export declare const Functor: Functor1<URI>
|
||
|
|
/**
|
||
|
|
* @category mapping
|
||
|
|
* @since 2.10.0
|
||
|
|
*/
|
||
|
|
export declare const flap: <A>(a: A) => <B>(fab: Tree<(a: A) => B>) => Tree<B>
|
||
|
|
/**
|
||
|
|
* @category instances
|
||
|
|
* @since 2.10.0
|
||
|
|
*/
|
||
|
|
export declare const Pointed: Pointed1<URI>
|
||
|
|
/**
|
||
|
|
* @category instances
|
||
|
|
* @since 2.10.0
|
||
|
|
*/
|
||
|
|
export declare const Apply: Apply1<URI>
|
||
|
|
/**
|
||
|
|
* Combine two effectful actions, keeping only the result of the first.
|
||
|
|
*
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare const apFirst: <B>(second: Tree<B>) => <A>(first: Tree<A>) => Tree<A>
|
||
|
|
/**
|
||
|
|
* Combine two effectful actions, keeping only the result of the second.
|
||
|
|
*
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare const apSecond: <B>(second: Tree<B>) => <A>(first: Tree<A>) => Tree<B>
|
||
|
|
/**
|
||
|
|
* @category instances
|
||
|
|
* @since 2.7.0
|
||
|
|
*/
|
||
|
|
export declare const Applicative: Applicative1<URI>
|
||
|
|
/**
|
||
|
|
* @category instances
|
||
|
|
* @since 2.10.0
|
||
|
|
*/
|
||
|
|
export declare const Chain: Chain1<URI>
|
||
|
|
/**
|
||
|
|
* @category instances
|
||
|
|
* @since 2.7.0
|
||
|
|
*/
|
||
|
|
export declare const Monad: Monad1<URI>
|
||
|
|
/**
|
||
|
|
* Composes computations in sequence, using the return value of one computation to determine the next computation and
|
||
|
|
* keeping only the result of the first.
|
||
|
|
*
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare const chainFirst: <A, B>(f: (a: A) => Tree<B>) => (first: Tree<A>) => Tree<A>
|
||
|
|
/**
|
||
|
|
* @category instances
|
||
|
|
* @since 2.7.0
|
||
|
|
*/
|
||
|
|
export declare const Foldable: Foldable1<URI>
|
||
|
|
/**
|
||
|
|
* @category instances
|
||
|
|
* @since 2.7.0
|
||
|
|
*/
|
||
|
|
export declare const Traversable: Traversable1<URI>
|
||
|
|
/**
|
||
|
|
* @category instances
|
||
|
|
* @since 2.7.0
|
||
|
|
*/
|
||
|
|
export declare const Comonad: Comonad1<URI>
|
||
|
|
/**
|
||
|
|
* @category do notation
|
||
|
|
* @since 2.9.0
|
||
|
|
*/
|
||
|
|
export declare const Do: Tree<{}>
|
||
|
|
/**
|
||
|
|
* @category do notation
|
||
|
|
* @since 2.8.0
|
||
|
|
*/
|
||
|
|
export declare const bindTo: <N extends string>(name: N) => <A>(fa: Tree<A>) => Tree<{ readonly [K in N]: A }>
|
||
|
|
declare const let_: <N extends string, A, B>(
|
||
|
|
name: Exclude<N, keyof A>,
|
||
|
|
f: (a: A) => B
|
||
|
|
) => (fa: Tree<A>) => Tree<{ readonly [K in N | keyof A]: K extends keyof A ? A[K] : B }>
|
||
|
|
export {
|
||
|
|
/**
|
||
|
|
* @category do notation
|
||
|
|
* @since 2.13.0
|
||
|
|
*/
|
||
|
|
let_ as let
|
||
|
|
}
|
||
|
|
/**
|
||
|
|
* @category do notation
|
||
|
|
* @since 2.8.0
|
||
|
|
*/
|
||
|
|
export declare const bind: <N extends string, A, B>(
|
||
|
|
name: Exclude<N, keyof A>,
|
||
|
|
f: (a: A) => Tree<B>
|
||
|
|
) => (ma: Tree<A>) => Tree<{ readonly [K in N | keyof A]: K extends keyof A ? A[K] : B }>
|
||
|
|
/**
|
||
|
|
* @category do notation
|
||
|
|
* @since 2.8.0
|
||
|
|
*/
|
||
|
|
export declare const apS: <N extends string, A, B>(
|
||
|
|
name: Exclude<N, keyof A>,
|
||
|
|
fb: Tree<B>
|
||
|
|
) => (fa: Tree<A>) => Tree<{ readonly [K in N | keyof A]: K extends keyof A ? A[K] : B }>
|
||
|
|
/**
|
||
|
|
* @since 2.0.0
|
||
|
|
*/
|
||
|
|
export declare function elem<A>(E: Eq<A>): (a: A, fa: Tree<A>) => boolean
|
||
|
|
/**
|
||
|
|
* @since 2.11.0
|
||
|
|
*/
|
||
|
|
export declare const exists: <A>(predicate: Predicate<A>) => (ma: Tree<A>) => boolean
|
||
|
|
/**
|
||
|
|
* This instance is deprecated, use small, specific instances instead.
|
||
|
|
* For example if a function needs a `Functor` instance, pass `T.Functor` instead of `T.tree`
|
||
|
|
* (where `T` is from `import T from 'fp-ts/Tree'`)
|
||
|
|
*
|
||
|
|
* @category zone of death
|
||
|
|
* @since 2.0.0
|
||
|
|
* @deprecated
|
||
|
|
*/
|
||
|
|
export declare const tree: Monad1<URI> & Foldable1<URI> & Traversable1<URI> & Comonad1<URI>
|