NodeJS
The API for the NodeJS package closely mirrors the official spatie/ray
package API, so it's likely that if it exists there, it's available to use in your NodeJS project.
Importing the package
When working with NodeJS, import the package as you would normally:
// es module import:
import { ray } from 'node-ray';
// commonjs import:
const { ray } = require('node-ray');
When creating a bundle for use within a browser-based environment (i.e. with webpack), import the /web
variant:
// es module import:
import { ray } from 'node-ray/web';
// commonjs import:
const { ray } = require('node-ray/web');
To use node-ray
directly in a webpage, include the standalone umd-format script via CDN. The standalone version is bundled with everything except the axios library, which must be included separately and before the standalone script.
<script src="https://cdn.jsdelivr.net/npm/axios@latest"></script>
<script src="https://cdn.jsdelivr.net/npm/node-ray@latest/dist/standalone.js"></script>
<script>
window.ray = Ray.ray;
window.Ray = Ray.Ray;
</script>
Enabling and disabling
Ray can be enabled or disabled at runtime using enable()
or disable()
.
ray('this is sent');
ray().disable();
ray('this is not sent');
ray().enable();
ray('this is also sent');
Working with screens
Ray can create or clear new screens of information.
ray().newScreen();
ray().newScreen('my new screen');
ray().clearScreen();
ray().clearAll();
App visibility
The Ray app can be shown or hidden programmatically.
ray().showApp();
ray().hideApp();
Payload types
Ray can display payloads of several types, including JSON, file contents, images, XML, and HTML.
ray().json('['a' => 1, 'b' => ['c' => 3]]');
ray().toJson({name: 'my object'});
ray().file('test.txt');
ray().image('https://placekitten.com/200/300');
ray().html('<strong>hello</strong> world');
ray().xml('<one><two><three>3</three></two></one>');
Using colors
Ray can display the data you send with different colors.
Available colors:
- green
- orange
- red
- blue
- purple
- gray
ray('this is green').green();
ray('this is purple').purple();
Using sizes
Ray can display stuff in large, normal, or small text.
ray('small').small();
ray('regular');
ray('large').large();
Displaying tables
Ray can display an object formatted in a table. Complex items such as arrays and objects are pretty-printed and highlighted to make their contents pleasant to read.
ray().table({
First: 'First value',
Second: 'Second value',
Third: 'Third value',
});
An array of items can also be displayed with formatted values.
ray().table(['John', 'Paul', 'George', 'Ringo'], 'Beatles');
Counting
Ray can count the number of times a piece of code is called, optionally with a specific name.
for(const n in [...Array(12).keys()]) {
ray().count('first');
}
[1, 2].forEach(n => ray().count());
Reset counters
Counter values persist across multiple calls to ray()
. Reset all counters with clearCounters()
:
ray().count('first');
ray().count('first');
console.log(Ray.counters.get('first'); // displays '2'
ray().clearCounters();
console.log(Ray.counters.get('first'); // displays '0'
Conditionally showing items
You can conditionally show things using the showIf
and showWhen
methods. If you pass a truthy value, the item will be displayed.
You may also pass a callback that returns a boolean value.
ray('will be shown').showIf(() => true);
ray('will be shown').showWhen(true);
ray('will not be shown').showIf(false);
ray('will not be shown').showWhen(() => false);
See the caller of a function
Sometimes you want to know where your code is being called. You can quickly determine that by using the caller
function.
ray().caller();
If you want to see the entire stack trace, use the trace
function.
ray().trace();
Pausing code execution
Ray can pause code execution within async code.
async function test() {
ray('before pausing');
await ray().pause();
ray('after resuming');
});
test();
Displaying a notification
You can use Ray to display a notification.
ray().notify('This is my notification');
Working with errors
Ray can display information about an Error
or exception with the error
method.
ray().error(new Error('my error message'));
Displaying class information
You can display the classname of an object with className()
.
const obj = new MyClass1();
ray().className(obj);
Working with dates
Ray can display information about a date in a nicely formatted table using the date()
method.
Specifying the format is optional. It uses the dayjs formatting style.
ray().date(new Date(), 'YYYY-MM-DD hh:mm:ss');
Measuring performance
You can use the measure
function to display runtime and memory usage. When measure
is called again, the time between
this and previous call is also displayed.
const sleep = (seconds) => {
const start = new Date().getTime();
while (new Date().getTime() < start + (seconds * 1000)) { }
};
ray().measure();
sleep(1);
ray().measure();
sleep(2);
ray().measure();
The measure
call optionally accepts a callable. Ray will output the time needed to run the callable and the maximum
memory used.
const sleep = (seconds) => {
const start = new Date().getTime();
while (new Date().getTime() < start + (seconds * 1000)) { }
};
ray().measure(() => {
sleep(5);
});
The stopTime
method can remove a stopwatch if you've previous called measure()
with a name:
ray().measure('my timer');
sleep(1);
ray().measure('my timer');
ray().stopTime('my timer');
Calling stopTime()
without specifying a name will delete all existing stopwatches.
Showing events
You can information about an event that has executed by calling event(name, data)
, with data
being optional.
ray().event('TestEvent', ['my argument']);
Feature demo
Here's a sample script that demonstrates a number of the features, both basic and advanced.
Save as demo.js
, and run with node demo.js
:
const { ray } = require('node-ray');
function test1() {
return ray().count('test one');
}
function test2() {
return ray().count();
}
async function alternatingColorCounter() {
return new Promise(resolve => {
const myRay = ray();
for(const i in [...Array(10).keys()]) {
setTimeout( () => {
const colorName = ['green', 'red', 'blue', 'orange'][i % 4];
myRay.html(`counter: <strong>${i + 1}</strong>`).color(colorName);
if (i === 9) {
resolve(true);
}
}, i * 1500);
}
});
}
async function main() {
ray().showApp();
ray().xml('<one><two><three>3333</three></two></one>');
ray().table(['a string', true, [1, 2, 3], {a:1, b:2}]);
ray().sendCustom({ name: 'object' });
await alternatingColorCounter();
await ray().pause();
[1,2].forEach(n => test1());
[1,2,3,4].forEach(n => test2());
ray().image('https://placekitten.com/200/300').blue();
ray().html('<strong>hello world</strong>').small();
}
main();