gardens

Using gardens makes it easier to handle your log output and debugging code by giving you the ability to break your output into named scopes, handle errors in a unified way, and use the same library for it all regardless of what your deployment target is. It supports scope nesting, custom colors and styles, time stamps, high resolution timing, HTML output, and many other fun things!

A garden can be used interchangeably with console, and works basically anywhere that JavaScript can run. If you want to add support for an environment that I don't know about feel free to open an issue!

Edge	Firefox	Chrome	Safari	Opera	Electron

• Node.js
• Deno
• React Native

Installation

yarn add gardens

You should use Yarn and pnp.

Usage

• Site
• Documentation

Depending on where you're using Gardens, you might need to do any of the following...

// CommonJS (Node.js, Electron)
const gardens = require( 'gardens' );

// CommonJS (React Native)
const gardens = require( 'gardens/native' );

// Bundled ES6 (Browsers, Rollup, Webpack, Parcel, etc.)
import gardens from 'gardens';

// ES6 (Deno)
import gardens from 'https://deno.land/x/gardens/mod.ts';

<!-- <script> (Browsers) -->
<script type="application/javascript" src="https://unpkg.com/gardens@^4"></script>

Managers

Managers are a really powerful way to use gardens for larger codebases. For details on their usage and why you should use them, read their documentation.

Configuration

Configurations can be set per instance, and updated at any time. Each garden has the following options.

Note: The scopeStyle option is used to configure the style of the scope name when printed. In Node.js and Deno it supports the backgroundColor, color, fontStyle, fontWeight, and textDecoration CSS properties. Support in browsers should technically be any CSS property, but the exact support depends on the implementation of the browser itself.

garden.configure({
  stream: {
    write() {
      // Anything with a write function will work
    }
  },
  outputType: 'ansi', // or 'console', 'html' or 'text',
  scopeStyle: {
    color: '#34dfcb',
    fontWeight: 700
  },
  verbose: true,
  displayDate: true,
  displayTime: true
})

Configuring streams

For the sake of being easy to use with custom outputs, each garden only cares that the stream given in its options implements a write method. One such browserland object that already implements a write function is document, but I would not recommend that, because it erases the previous contents, which is sad.

When setting a stream other than the default, the outputType is always set to text to keep things simple. If you want colors, be sure to set this option correctly.

log, info, success, warn, warning, and fail

These methods all just dump the arguments given out to the console like you would expect. The output is prefixed with the scope name and output type. (log, warning, etc.)

// These are all for general logging
garden.log( 'message' )
garden.info( 'new message' )
garden.success( 'yay!' )
garden.warn( 'uhh oh' )
garden.warning( 'also uhh oh' )
garden.fail( 'oh no!' )

styled

Takes a string and a CSS-style object, and prints the string using the given styles. Mostly useful in browsers where there is a lot of CSS console support.

garden.styled( 'Look at me!', {
  backgroundColor: '#474350',
  color: '#b568b4',
  fontSize: '50px',
  fontWeight: 700,
})

debug and trace

The debug method is similar to log, but it will only print if options.verbose is truthy. If this is falsish then the call will do nothing.

The story for trace is similar, though it behaves more like catch than log, meaning that if it is verbose, it will print a call stack.

garden.configure({ verbose: true })
garden.debug( 'interesting information!' )
garden.trace( 'look at my call stack!' )

error, typeerror, referenceerror, and catch

These methods will automagically create an Error, TypeError or ReferenceError using the first argument as the message argument when constructing it. It will then log the error including the full call stack for you to easily find where the error came from without having to do the dirty work yourself. All you have to do is call one function with a generic string as the argument. Easy peasy.

catch is similar to error, but will check if the first argument is already an error. It will only generate a new Error itself if the first argument is not already an Error, TypeError, or ReferenceError. If the value you are dealing with may or may not be an error, and you don't want to manually check yourself, then use this method.

garden.error( 'something went wrong!!1!' )
garden.typeerror( 'you gave me the incorrect thing!' )
garden.referenceerror( 'you gave me nothing!' )
garden.catch( aThrownError )

time and timeEnd

Each method takes a String, Symbol, or undefined as the first argument. time should be called at the begin of what you would like to time with a name or Symbol representing what you are timing, and timeEnd should be called once the task has been completed with the same name. The time taken to complete the task will be tracked with a precision of up to 1 nano second, if the environment you're running supports high resolution timing.

garden.time( name ) // Doesn't print anything
garden.timeEnd( name ) // Will print the time in between calling .time() and now

let tracker = Symbol()
garden.time( tracker )
garden.timeEnd( tracker )

count

Takes a String, Symbol, or undefined as an argument, and then logs how many times count has been called with that specific argument.

garden.count() // 1
garden.count() // 2
garden.count( 'hello sailor' ) // 1
garden.count( 'hello sailor' ) // 2

let secret = Symbol()
garden.count( secret ) // 1
garden.count( secret ) // 2

assert and friends

Four assert functions are also provided for the sake of completeness. assert and assert_eq behave as you would expect. deny is basically assert but for things that should be falsey. throws takes a function that should throw, and will throw if it doesn't, but will catch the error if it does. Additional arguments can be passed to provide additional details on what was expected, and possibly why the assert fails.

garden.assert( true, 'Expected to be true' ) // Does nothing
garden.assert( false, 'Expected to be true' ) // Throws

garden.assert_eq( 1, 1, 'Expect 1 to equal 1', stateOfSomethingRelated ) // Does nothing
garden.assert_eq( 1, 2, 'Expect 1 to equal 2', stateOfSomethingRelated ) // Throws

garden.deny( false, 'Expected to be false' ) // Does nothing
garden.deny( true, 'Expected to be false' ) // Throws

let variableThatDoesExist = true
garden.throws( () => someUndefinedVariable ) // Does nothing
garden.throws( () => variableThatDoesExist ) // Throws

raw

Passes all given arguments directly to the output stream, without scopes, time stamps, or any formatting. As the name implies, it just prints raw data.