xtrace

trace data when composing functions

Usage no npm install needed!

<script type="module">
  import xtrace from 'https://cdn.skypack.dev/xtrace';
</script>

README

xtrace

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

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.