Neoclassical Philosophic Musings

    xtrace

    0.3.0 • Public • Published

    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.

    Install

    npm i xtrace

    DownloadsWeekly Downloads

    264

    Version

    0.3.0

    License

    MIT

    Unpacked Size

    44.1 kB

    Total Files

    16

    Last publish

    Collaborators

    • brekk