node-ray

node-ray

node-ray

Debug your NodeJS code with Ray to fix problems faster

This package can be installed in any NodeJS, ES6+, or TypeScript application to send messages to the Ray app.

Installation

Install with npm:

npm install node-ray

or yarn:

yarn add node-ray

Available environments

node-ray offers several variants to allow you to use it in either NodeJS or Browser environments.

NodeJS

When using in a NodeJS environment (the default), import the package as you would normally:

// es module import:
import { ray } from 'node-ray';

// commonjs import:
const ray = require('node-ray').ray;

Browser bundle

If you're bundling your scripts for use in a Browser environment (i.e. using webpack), import the /web variant:

// es module import:
import { ray } from 'node-ray/web';

// commonjs import:
const ray = require('node-ray/web').ray;

Browser standalone

If you'd like to use node-ray directly in a webpage, you may inject it via a CDN package. The standalone version is bundled with everything except the axios library.

    <script src="https://cdn.jsdelivr.net/npm/axios@latest"></script>
    <script src="https://cdn.jsdelivr.net/npm/node-ray@latest/dist/standalone.min.js"></script>

You may access the helper ray() method as Ray.ray().

Usage

The majority of the API from the original PHP package is supported. See the api reference for more information.

// es module import:
import { ray } from 'node-ray';

// commonjs import:
const ray = require('node-ray').ray;

ray('a string');

ray(['several', 'arguments'], 'can', {be: provided});

ray().table(['one two', {a: 100, b: 200, c: 300}, [9, 8, 7]).blue();

ray().html('<em>large text</em>').large().green();

ray().image('https://placekitten.com/200/300');

ray().clearAll();

ray().disable(); // disable sending data to Ray at runtime
ray().xml('<one>11</one>'); // disabled, data not sent to Ray

Configuration

Note: This section only applies if you are using node-ray in the NodeJS environment.

node-ray will search for ray.config.js. You should place this file in your project's root directory, similiar to the way ray.php is placed in the root directory when using spatie/ray.

This is optional and the package will use the default settings if no configuration file is found.

Example:

// ray.config.js

module.exports = {
    enable: true,
    host: 'localhost',
    port: 23517,
}

About

This package attempts to replicate the entire PHP API for Ray to provide a robust solution for debugging NodeJS projects.

How is this different from js-ray?

This is a more complete implementation written in typescript, and its primary use case is for NodeJS projects, although it can be used in Browser environments as well.

The codebase was translated to Typescript directly from the original PHP source code of spatie/ray.

As a result, node-ray supports the majority of features that exist in the original package; js-ray does not.

We did draw some inspiration for portions of the code from js-ray, however.

Using the package

See using the package.

Reference

Call	Description
ray(variable)	Display a string, array or object
ray(var1, var2, …)	Ray accepts multiple arguments
ray(…).blue()	Output in color. Use green, orange, red, blue,purple or gray
ray().clearScreen()	Clear current screen
ray().clearAll()	Clear current and all previous screens
ray().className(obj)	Display the classname for an object
ray().count(name)	Count how many times a piece of code is called, with optional name
ray().die()	Halt code execution - NodeJS only
ray().disable()	Disable sending stuff to Ray
ray().disabled()	Check if Ray is disabled
ray().enable()	Enable sending stuff to Ray
ray().enabled()	Check if Ray is enabled
ray().error(err)	Display information about an Error/Exception
ray().file(filename)	Display contents of a file - NodeJS only
ray(…).hide()	Display something in Ray and make it collapse immediately
ray().hideApp()	Programmatically hide the Ray app window
ray().html(string)	Send HTML to Ray
ray().image(url)	Display an image in Ray
ray().json([…])	Send JSON to Ray
ray().newScreen()	Start a new screen
ray().newScreen('title')	Start a new named screen
ray(…).notify(message)	Display a notification
ray(…).pass(variable)	Display something in Ray and return the value instead of a Ray instance
ray().pause()	Pause code execution within your code; must be called using await
ray().showApp()	Programmatically show the Ray app window
ray(…).showIf(true)	Conditionally show things based on a truthy value or callable
ray(…).showWhen(true)	Conditionally show things based on a truthy value or callable
ray(…).small()	Output text smaller or bigger. Use large or small
ray().table([…])	Display an array of items formatted as a table; Objects and arrays are pretty-printed
ray().xml(string)	Send XML to Ray

Development setup

• npm install
• npm run build:all
• npm run test
• node build/test.js

Testing

node-ray uses Jest for unit tests. To run the test suite:

npm run test

To update the test snapshots:

npm run test -- -u

---

License

The MIT License (MIT). Please see License File for more information.

Changelog

v1.2.0

7 February 2021

• add available environments doc c05eb6d
• add support for browser environments/bundles, so the package can be used for NodeJS/ES6/TypeScript projects, regardless of the target environment 43b9436