a tool for adding clarity to your compositional-pipelines or just invoking side-effects in a clean way

Originally inspired by this book, this is a more fully-fledged solution for adding simple side-effects to a given operation.

API

Table of Contents

• Core Functions
  • callWithScopeWhen
    • Parameters
    • Examples
  • callBinaryWithScopeWhen
    • Parameters
    • Examples
  • segment
    • Parameters
    • Examples
• Derived Functions
  • callWithScope
    • Parameters
    • Examples
  • callWhen
    • Parameters
    • Examples
  • call
    • Parameters
    • Examples
  • callBinaryWithScope
    • Parameters
    • Examples
  • callBinaryWhen
    • Parameters
    • Examples
  • callBinary
    • Parameters
    • Examples
• Logging Functions
  • traceWithScopeWhen
    • Parameters
    • Examples
  • inspect
    • Parameters
    • Examples
  • trace
    • Parameters
    • Examples
  • traceSegment
    • Parameters
    • Examples
• Legacy Functions
  • sideEffect
    • Parameters
    • Examples
  • taggedSideEffect
    • Parameters
    • Examples
  • scopedSideEffect
    • Parameters
    • Examples
  • scopedTrace
    • Parameters
    • Examples

Core Functions

These three functions describe all the functionality this library has to offer.

callWithScopeWhen

call a side-effect function conditionally with a specific context, always return last param

Parameters

• effect function a function to call as a side-effect
• when function unary predicate
• what function a lens, e.g. x => x.id
• value any a value

Examples

import { callWithScopeWhen } from "xtrace"
import { prop } from "ramda"
const logWhen = callWithScopeWhen(console.log)
const getId = prop('id')
const idAbove = above => id => id > above
// ... log as you calculate
pipe(
  logWhen(idAbove(300), getId, 'above three hundred'),
  calculate
)

Returns any value

callBinaryWithScopeWhen

call a binary side-effect function, conditionally, with a specific scope, always return the last param

Parameters

• effect function a function to call as a side-effect
• when function a binary predicate
• what function a lens, e.g. x => x.value
• tag any anything
• value any anything

Examples

import { callBinaryWithScopeWhen } from "xtrace"
import { prop } from "ramda"
const logWithScopeWhen = callBinaryWithScopeWhen(console.log)
// ... log as you calculate
pipe(
  logWithScopeWhen(
    id => id === 200,
    prop('id'),
    'the 200 id item'
  ),
  calculate
)

Returns any value

segment

callBinaryWithScopeWhen but with a curried object style interface. See also callBinaryWithScopeWhen.

Parameters

• config object configuration object
  • config.what function optional lens function, e.g. x => x.y
  • config.when function optional binary predicate
  • config.call function side-effect function
  • config.tag any anything
  • config.value any anything

Examples

import {segment} from "xtrace"
import {prop} from "ramda"
// ... log the item whose id is 300 before calculating
pipe(
  value => segment({
    when: id => id === 300,
    what: prop('id'),
    call: console.log,
    tag: 'the 300 item',
    value
  })
  reduce(calculate, {})
)

Returns any config.value

Derived Functions

These are syntactic sugar to make calling the core functions easier.

callWithScope

call a side-effect function with a specific context, always return last param

Parameters

• effect function a function to call as a side-effect
• what function a lens, e.g. x => x.id
• value any a value

Examples

import { callWithScope } from "xtrace"
import { prop } from "ramda"
const logWithScope = callWithScope(console.log)
const getId = prop('id')
// ... log as you calculate
pipe(
  logWithScope( getId, 'the id')
  calculate,
  logWithScope( x => x.value, 'the value')
)

Returns any value

callWhen

call a side-effect function conditionally, always return last param

Parameters

• effect function a function to call as a side-effect
• when function unary predicate
• value any a value

Examples

import { callWhen } from "xtrace"
import { prop } from "ramda"
const logWhen = callWhen(console.log)
const idAbove = above => (_, {id}) => id > above
// ... log as you calculate
pipe(
  logWhen(idAbove(300), 'above three hundred'),
  calculate
)

Returns any value

call

call a side-effect function, always return last param

Parameters

• effect function a function to call as a side-effect
• when function binary predicate
• value any a value

Examples

import { call } from "xtrace"
import { prop } from "ramda"
const log = call(console.log)
// ... log as you calculate
pipe(
  log('data'),
  calculate
)

Returns any value

callBinaryWithScope

call a binary side-effect function, with a specific scope, always return the last param

Parameters

• effect function a function to call as a side-effect
• what function a lens, e.g. x => x.value
• tag any anything
• value any anything

Examples

import { callBinaryWithScope } from "xtrace"
import { prop } from "ramda"
const logWithScope = callBinaryWithScope(console.log)
// ... log as you calculate
pipe(
  logWithScope(prop('id'), 'the id'),
  calculate
)

Returns any value

callBinaryWhen

call a binary side-effect function, conditionally, always return the last param

Parameters

• effect function a function to call as a side-effect
• what function a lens, e.g. x => x.value
• tag any anything
• value any anything

Examples

import { callBinaryWhen } from "xtrace"
const logWhen = callBinaryWhen(console.log)
// ... log as you calculate
pipe(
  logWhen(({id}) => id === 200, 'the 200 id item'),
  calculate
)

Returns any value

callBinary

call a binary side-effect function, always return the last param

Parameters

• effect function a function to call as a side-effect
• tag any anything
• value any anything

Examples

import { callBinary } from "xtrace"
const log = callBinary(console.log)
// ... log as you calculate
pipe(
  log('data'),
  calculate
)

Returns any value

Logging Functions

These are further syntactic sugar for usage with console.log

traceWithScopeWhen

call console.log, conditionally, with a specific scope, always return the last param

Parameters

• when function a binary predicate
• what function a lens, e.g. x => x.value
• tag any anything
• value any anything

Examples

import { traceWithScopeWhen } from "xtrace"
import { prop } from "ramda"
// ... log as you calculate
pipe(
  traceWithScopeWhen(
    id => id === 200,
    prop('id'),
    'the 200 id item'
  ),
  calculate
)

Returns any value

inspect

call console.log, with a specific scope, always return the last param

Parameters

• what function a lens, e.g. x => x.value
• tag any anything
• value any anything

Examples

import { inspect } from "xtrace"
import { prop } from "ramda"
// ... log as you calculate
pipe(
  inspect(
    prop('id'),
    'the 200 id item'
  ),
  calculate
)

Returns any value

trace

call console.log, always return the last param

Parameters

• tag any anything
• value any anything

Examples

import { trace } from "xtrace"
import { prop } from "ramda"
// ... log as you calculate
pipe(
  trace('data'),
  calculate
)

Returns any value

traceSegment

traceWithScopeWhen but with a curried object style interface. See also traceWithScopeWhen.

Parameters

• config object configuration object
  • config.what function lens function, e.g. x => x.y
  • config.when function binary predicate
  • config.tag any anything
  • config.value any anything

Examples

import {segment} from "xtrace"
import {prop} from "ramda"
// ... log the item whose id is 300 before calculating
pipe(
  value => traceSegment({
    when: id => id === 300,
    what: prop('id'),
    tag: 'the 300 item',
    value
  })
  reduce(calculate, {})
)

Returns any config.value

Legacy Functions

These are function aliases for backwards-compatibility

sideEffect

Now deprecated. See call instead.

Parameters

• effect function a function to call as a side-effect
• when function binary predicate
• value any a value

Examples

import { call as sideEffect } from "xtrace"
import { prop } from "ramda"
const log = sideEffect(console.log)
// ... log as you calculate
pipe(
  log,
  calculate
)

Returns any value

Meta

• deprecated: This is deprecated.

taggedSideEffect

Now deprecated. See callBinary instead.

Parameters

• effect function a function to call as a side-effect
• tag any anything
• value any anything

Examples

import { callBinary as taggedSideEffect } from "xtrace"
const log = taggedSideEffect(console.log)
// ... log as you calculate
pipe(
  log('data'),
  calculate
)

Returns any value

Meta

• deprecated: This is deprecated.

scopedSideEffect

Now deprecated. See callBinaryWithScope instead.

Parameters

• effect function a function to call as a side-effect
• what function a lens, e.g. x => x.value
• tag any anything
• value any anything

Examples

import { callBinaryWithScope as scopedSideEffect } from "xtrace"
import { prop } from "ramda"
const logWithScope = scopedSideEffect(console.log)
// ... log as you calculate
pipe(
  logWithScope(prop('id'), 'the id'),
  calculate
)

Returns any value

Meta

• deprecated: This is deprecated.

scopedTrace

Now deprecated. See traceWithScope | inspect instead.

Parameters

• what function a lens, e.g. x => x.value
• tag any anything
• value any anything

Examples

import { inspect } from "xtrace"
import { prop } from "ramda"
// ... log as you calculate
pipe(
  inspect(
    prop('id'),
    'the 200 id item'
  ),
  calculate
)

Returns any value

Meta

• deprecated: This is deprecated.