{"id":19689945,"url":"https://github.com/permafrost-dev/node-ray","last_synced_at":"2025-04-04T21:06:06.184Z","repository":{"id":37078402,"uuid":"336133471","full_name":"permafrost-dev/node-ray","owner":"permafrost-dev","description":"Debug your NodeJS, TS \u0026 web code with Ray to understand and fix bugs faster","archived":false,"fork":false,"pushed_at":"2024-10-14T18:38:13.000Z","size":815,"stargazers_count":62,"open_issues_count":13,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T20:05:53.865Z","etag":null,"topics":["debugging","es6","javascript","nodejs","npm-package","ray","typescript","web-development"],"latest_commit_sha":null,"homepage":"https://permafrost.dev/open-source","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/permafrost-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"permafrost-dev","custom":"https://permafrost.dev/open-source"}},"created_at":"2021-02-05T01:47:08.000Z","updated_at":"2025-03-21T11:27:27.000Z","dependencies_parsed_at":"2022-06-24T17:03:46.954Z","dependency_job_id":"9f83a007-645f-47b4-9b9f-5712babd409e","html_url":"https://github.com/permafrost-dev/node-ray","commit_stats":{"total_commits":616,"total_committers":7,"mean_commits":88.0,"dds":0.1915584415584416,"last_synced_commit":"77592c3a4962a3e3a2e1a499c4ded532f0fccf82"},"previous_names":[],"tags_count":71,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/permafrost-dev%2Fnode-ray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/permafrost-dev%2Fnode-ray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/permafrost-dev%2Fnode-ray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/permafrost-dev%2Fnode-ray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/permafrost-dev","download_url":"https://codeload.github.com/permafrost-dev/node-ray/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249524,"owners_count":20908212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debugging","es6","javascript","nodejs","npm-package","ray","typescript","web-development"],"created_at":"2024-11-11T19:03:46.353Z","updated_at":"2025-04-04T21:06:06.164Z","avatar_url":"https://github.com/permafrost-dev.png","language":"TypeScript","funding_links":["https://github.com/sponsors/permafrost-dev","https://permafrost.dev/open-source"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://repository-images.githubusercontent.com/336133471/01ea1b91-c6bb-4fae-a9a6-94e3fb661f85\" alt=\"node-ray\" height=\"450\" style=\"block\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/permafrost-dev/node-ray/run-tests.yml?branch=main\u0026label=tests\u0026logo=github\u0026style=flat-square\u0026nocache=1\" alt=\"test status\"\u003e\n    \u003cimg src=\"https://shields.io/npm/v/node-ray?style=flat-square\u0026logo=npm\" alt=\"npm version\"\u003e\n    \u003cimg src=\"https://shields.io/github/license/permafrost-dev/node-ray?style=flat-square\u0026logo=opensourceinitiative\u0026logoColor=%23fff\" alt=\"license\"\u003e\n    \u003cbr\u003e\n    \u003cimg alt=\"Codecov\" src=\"https://img.shields.io/codecov/c/github/permafrost-dev/node-ray?color=%234c1\u0026label=coverage\u0026logo=codecov\u0026logoColor=%23ef6f6f\u0026style=flat-square\u0026token=YW2BTKSNEO\" alt=\"codecov\"\u003e\n    \u003cimg alt=\"tech debt\" src=\"https://img.shields.io/codeclimate/tech-debt/permafrost-dev/node-ray?label=tech%20debt\u0026logo=codeclimate\u0026style=flat-square\"\u003e\n    \u003cimg src=\"https://img.shields.io/codeclimate/maintainability/permafrost-dev/node-ray?logo=codeclimate\u0026style=flat-square\" /\u003e \n    \u003cbr\u003e\n    \u003cbr\u003e\n    \u003c!--img src=\"https://bestpractices.coreinfrastructure.org/projects/6837/badge\" alt=\"best practuices\"\u003e\n    \u003cimg src=\"https://badgen.net/github/dependabot/permafrost-dev/node-ray?style=flat-square\u0026logo=github\" alt=\"dependabot status\"\u003e\n    \u003cbr--\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dt/node-ray.svg?style=flat-square\u0026logo=npm\u0026logoColor=white\" alt=\"npm downloads\"\u003e\n    \u003cimg alt=\"jsDelivr hits (npm)\" src=\"https://img.shields.io/jsdelivr/npm/hm/node-ray?logo=jsdelivr\u0026logoColor=%23fff\u0026style=flat-square\u0026period=year\"\u003e\n    \u003cimg alt=\"npm-installs-monthly\" src=\"https://img.shields.io/npm/dm/node-ray?style=flat-square\u0026logo=npm\u0026logoColor=white\u0026label=installs\"\u003e\n\u003c/p\u003e\n\n# node-ray\n### The official Node/JS \u0026 TypeScript integration for Ray - Understand and fix bugs faster.\n\nThe package can be installed in any NodeJS, ES6+, or TypeScript application to send data to the [Ray app](https://myray.app).\n\n\u003cbr\u003e\n\n## Installation\n\nInstall with npm:\n\n```bash\nnpm install node-ray\n```\n\nor bun:\n\n```bash\nbun add node-ray\n```\n\n## Available environments\n\n`node-ray` offers several options to allow you to use it in either NodeJS, Web-based TypeScript or Javascript projects, and browser environments.\n\n\u003eIf you're using NextJs/React, take a look at [permafrost-dev/react-ray](https://github.com/permafrost-dev/react-ray).\n\u003e\n\u003eIf you're using Vue, check out [permafrost-dev/vue-ray](https://github.com/permafrost-dev/vue-ray).\n\n### NodeJS\n\nWhen using in a NodeJS environment (the default), import the package as you would normally:\n\n```js\n// es module import:\nimport { ray } from 'node-ray';\n\n// commonjs import:\nconst ray = require('node-ray').ray;\n```\n\n### Browser bundle\n\nWhen bundling scripts for use in a Browser environment _(i.e., using webpack or vite)_, import the `/web` export:\n\n```js\nimport { ray } from 'node-ray/web';\n\n// or a commonjs import:\nconst { ray } = require('node-ray/web');\n```\n\n### Browser standalone\n\nThere are two standalone versions of `node-ray` available: one with axios included, and one without _(slim version)_.\n\n`node-ray` may be directly used within a web page via a script tag. The standalone version includes all required libraries, **including** axios.\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/node-ray@latest/dist/standalone.min.js\"\u003e\u003c/script\u003e\n```\n\nOr use the slim version _(without axios)_ if you already have axios included in your project:\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/node-ray@latest/dist/standalone-slim.min.js\"\u003e\u003c/script\u003e\n```\n\n#### Recommended Standalone Initialization\n\nAs of version `2.0.0`, you no longer need to manually initialize the global `ray` objects; it is now performed automatically on load:\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/node-ray@latest/dist/standalone.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n    // nothing to do here, just use `window.ray()` as normal\n\u003c/script\u003e\n```\n\n### Laravel Mix\n\nTo use `node-ray` with Laravel Mix, include the following in `resources/js/bootstrap.js`:\n\n```js\nconst { ray } = require('node-ray/web');\n\nwindow.ray = ray;\n```\n\nCompile the bundle _(`npm run dev`)_as usual. After including `js/app.js` in your view, you may access `ray()` within your scripts.\n\n### Laravel + Vite\n\nTo use `node-ray` with Laravel + Vite, include the following in `resources/js/bootstrap.js`:\n\n```js\nimport { ray } from 'node-ray/web';\n\nwindow.ray = ray;\n```\n\n`ray()` is immediately available to other scripts such as `app.js`, however note that `window.ray()` is NOT immediately available in `\u003cscript\u003e` tags embedded in the view.\n\n## Usage\n\nMost of the API from the [original PHP package](https://github.com/spatie/ray) is supported. See the [api reference](https://spatie.be/docs/ray/v1/usage/reference) for more information.\n\n```js\n// es module import:\nimport { ray } from 'node-ray';\n\n// commonjs import:\nconst { ray } = require('node-ray');\n```\n\nTo modify the host or port:\n\n```js\n// make sure you import the Ray class (capital \"R\")\nimport { Ray, ray } from 'node-ray';\n\nRay.useDefaultSettings({ host: '127.0.0.1', port: 3000 });\n\n// or just modify the port:\nRay.useDefaultSettings({ port: 3000 });\n\n// ...and use ray() as normal\n```\n\n**When using NodeJS,** you must call `await Ray.initSettings()` to initialize the settings before using `ray()`.\nThis is not necessary when using the browser bundle.\n\n```js\nray('a string');\n\nray(['several', 'arguments'], 'can', {be: provided});\n\nray().table(['one two', {a: 100, b: 200, c: 300}, [9, 8, 7]]).blue();\n\nray().chain(ray =\u003e ray.html('\u003cem\u003elarge text\u003c/em\u003e').large().green());\n\nray().image('https://placekitten.com/200/300');\n\nray().clearAll();\n\nray().disable(); // disable sending data to Ray at runtime\nray().xml('\u003cone\u003e11\u003c/one\u003e'); // previous call disabled sending data, XML not sent to Ray\n```\n\n## Configuration\n\n### NodeJS config\n\n_Note: This section only applies when using `node-ray` in the NodeJS environment, NOT a browser environment._\n\n`node-ray` will search for `ray.config.js`, which should be in the project's root directory.\n\nUsing a configuration file is optional, and the package will use the default settings if no configuration file is specified.\n\n_Example:_\n\n```js\n// ray.config.js\n\nmodule.exports = {\n    enable: true,\n    host: 'localhost',\n    port: 23517,\n    scheme: 'http', //only change this if you know what you're doing!\n\n    // calls to console.log() are redirected to Ray\n    intercept_console_log: true,\n\n    // determine the enabled state using the specified callback\n    // the 'enable' setting is also considered when using this setting.\n    enabled_callback: () =\u003e {\n        return functionThatReturnsABoolean();\n    },\n\n    sending_payload_callback: (rayInstance, payloads) =\u003e {\n        if (payloads[0].getType() === 'custom') {\n            payloads[0].html += ' \u003cstrong\u003e- modified!\u003c/strong\u003e';\n        }\n    },\n\n    sent_payload_callback: (rayInstance) =\u003e {\n        // automatically make all payloads sent to Ray green.\n        rayInstance.green();\n    },\n}\n```\n\nWhen running `node-ray` within a NodeJS environment, you may set the environment variable `NODE_ENV` to \"production\" or \"staging\" to disable sending data to Ray from calls to `ray()`.\n\n### Browser config\n\nThis section only applies within a browser environment _(i.e., webpack)_.\n\nYou can configure `node-ray` by importing the `Ray` class and calling the `useDefaultSettings()` method.\n\n```js\nimport { Ray, ray } from 'node-ray/web';\n\n// set several settings at once:\nRay.useDefaultSettings({\n    host: '192.168.1.20',\n    port: 23517\n});\n\n// or set individual settings only:\nRay.useDefaultSettings({ port: 23517 });\n\n// use ray() normally:\nray().html('\u003cstrong\u003ehello world\u003c/strong\u003e');\n```\n\nThese settings persist across calls to `ray()`, so they only need to be defined once.\n\n### Enabled state\n\nIf providing a callback for the `enabled_callback` setting _(a function that returns a boolean)_, payloads will only be sent to Ray if:\n\n- the `enable` setting is set to `true`.\n- the callback returns a value of `true`.\n\nIf either condition is `false`, then no payloads will be sent to Ray.\n\nSet the `enabled_callback` setting to `null` or leave it `undefined` to consider the `enable` setting _(the default)_.\n\n### Sending/sent payload callbacks\n\nSpecify the `sending_payload_callback` or `sent_payload_callback` settings to trigger a callback before _(sending)_ or after _(sent)_ sending a payload.\n\nThis feature is helpful when sending additional payloads or modifying all payloads _(i.e., changing the color)_.\n\n### Chaining payloads\n\nYou can chain payloads together using the `chain()` method. This allows you to send multiple payloads at once, which may be necessary when performing multiple chained\ncalls to `ray()` in an asynchronous context.\n\n```js\nray().chain((ray) =\u003e {\n    ray.text('first payload')\n        .blue()\n        .small()\n        .label('test');\n});\n```\n\n## About\n\nThis package attempts to replicate the entire PHP API for Ray to provide a robust solution for debugging NodeJS, TypeScript, Javascript and web-based projects.\n\n## Using the package\n\nSee [using the package](docs/usage.md).\n\n## Reference\n\n| Call | Description |\n| --- | --- |\n| `ray(variable)` | Display a string, array or object |\n| `ray(var1, var2, …)` | Ray accepts multiple arguments |\n| `ray().blue()` | Output in color. Use `green`, `orange`, `red`, `blue`,`purple` or `gray` |\n| `ray().caller()` | **Asynchronous.** Show the calling class and method |\n| `ray().chain(callback)` | Chain multiple Ray payloads and send them all at once. `callback: (ray: Ray) =\u003e void` |\n| `ray().clearScreen()` | Clear current screen |\n| `ray().clearAll()` | Clear current and all previous screens |\n| `ray().className(obj)` | Display the classname for an object |\n| `ray().confetti()` | Display Confetti in Ray |\n| `ray().count(name)` | Count how many times a piece of code is called, with optional name |\n| `ray().date(date, format)` | Display a formatted date, the timezone, and its timestamp |\n| `ray().die()` | Halt code execution - NodeJS only |\n| `ray().disable()` | Disable sending stuff to Ray |\n| `ray().disabled()` | Check if Ray is disabled |\n| `ray().enable()` | Enable sending stuff to Ray |\n| `ray().enabled()` | Check if Ray is enabled |\n| `ray().error(err)` | Display information about an Error/Exception |\n| `ray().event(name, data)` | Display information about an event with optional data |\n| `ray().exception(err)` | **Asynchronous.** Display extended information and stack trace for an Error/Exception |\n| `ray().file(filename)` | **NodeJS only.** Display contents of a file |\n| `ray().hide()` | Display something in Ray and make it collapse immediately |\n| `ray().hideApp()` | Programmatically hide the Ray app window |\n| `ray().html(string)` | Send HTML to Ray |\n| `ray().htmlMarkup(string)` | Display syntax-highlighted HTML code in Ray |\n| `ray().if(true, callback)` | Conditionally show things based on a truthy value or callable, optionally calling the callback with a `ray` argument |\n| `ray().image(url)` | Display an image in Ray |\n| `ray().interceptor()` | Access ConsoleInterceptor; call `.enable()` to show `console.log()` calls in Ray |\n| `ray().json([…])` | Send JSON to Ray |\n| `ray().label(string)` | Add a text label to the payload |\n| `ray().limit(N)` | **Asynchronous.** Limit the number of payloads that can be sent to Ray to N; used for debugging within loops |\n| `ray().macro(name, callable)` | Add a custom method to the Ray class. make sure not to use an arrow function if returning `this` |\n| `ray().measure(callable)` | Measure the performance of a callback function |\n| `ray().measure()` | Begin measuring the overall time and elapsed time since previous `measure()` call |\n| `ray().newScreen()` | Start a new screen |\n| `ray().newScreen('title')` | Start a new named screen |\n| `ray().nodeinfo()` | **NodeJS only.** Display statistics about node, such as the v8 version and memory usage |\n| `ray().notify(message)` | Display a notification |\n| `ray().once(arg1, …)` | **Asynchronous.** Only send a payload once when in a loop |\n| `ray().pass(variable)` | Display something in Ray and return the value instead of a Ray instance |\n| `ray().pause()` | Pause code execution within your code; must be called using `await` |\n| `ray().projectName(name)` | Change the active project name |\n| `ray().remove()` | Remove an item from Ray   |\n| `ray().screenColor(color)` | Changes the screen color to the specified color |\n| `ray().separator()` | Display a separator |\n| `ray().showApp()` | Programmatically show the Ray app window |\n| `ray().small()` | Output text smaller or bigger. Use `large` or `small`|\n| `ray().stopTime(name)` | Removes a named stopwatch if specified, otherwise removes all stopwatches |\n| `ray().table(…)` | Display an array or an object formatted as a table; Objects and arrays are pretty-printed |\n| `ray().text(string)` | Display raw text in Ray while preserving whitespace formatting |\n| `ray().toJson(variable)` | Convert a variable using `JSON.stringify()` and display the result |\n| `ray().trace()` | Display a stack trace |\n| `ray().xml(string)` | Send XML to Ray |\n\n## FAQ\n\n- Is `node-ray` only for NodeJS? _Not at all! It can be used in a web environment with javascript as well._\n\n- Can `node-ray` be used with React/Vue? _yes, be sure to import `node-ray/web`_. Alternatively, check out the [react-ray](https://github.com/permafrost-dev/react-ray) and [vue-ray](https://github.com/permafrost-dev/vue-ray) packages.\n\n- Can `node-ray` be used with webpack-based projects? _Yes! Just be sure to import `node-ray/web`_.\n\n## Development setup\n\n```sh\nnpm install`\nnpm run build:dev\nnpm run test\n```\n\n## Testing\n\n`node-ray` uses Vitest for unit tests. To execute the test suite, run the following command:\n\n```sh\nnpm run test\n```\n\n---\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Security Vulnerabilities\n\nPlease review [our security policy](../../security/policy) on how to report security vulnerabilities.\n\n## Credits\n\n- [Patrick Organ](https://github.com/patinthehat)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpermafrost-dev%2Fnode-ray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpermafrost-dev%2Fnode-ray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpermafrost-dev%2Fnode-ray/lists"}