node-ray

node-ray

node-ray

Debug your NodeJS code with Ray to fix problems faster

This package can be installed in any NodeJS application to send messages to the Ray app.

Installation

Install with npm:

npm install node-ray

or yarn:

yarn add node-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

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 (the default builds won't work in a browser environment).

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().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
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
• 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.1.0

7 February 2021

• update changelog d898525
• add reference/section on className() method 18c4486
• add section on working with screens cf12acd