# @ulixee/js-path

> The Serialization format to reference Paths to elements/nodes and properties in the DOM

Latest version **2.0.0-alpha.34** (published 2025-09-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install @ulixee/js-path
pnpm add @ulixee/js-path
yarn add @ulixee/js-path
bun add @ulixee/js-path
```

## Health

**Score 40/100 (D)** — status: stable.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 2.0.0-alpha.34 |
| Published | 2025-09-08 |
| First published | 2022-11-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 12 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1559 |
| Author | Data Liberation Foundation |
| Maintainers | blakebyrnes, calebjclark |

## Links

- npm: https://www.npmjs.com/package/@ulixee/js-path
- Repository: git@github.com:ulixee/hero.git
- Homepage: https://ulixee.org
- Issues: https://github.com/ulixee/hero/issues
- npm.io page: https://npm.io/package/@ulixee/js-path

## Recent versions

- 2.0.0-alpha.34 (latest) — 2025-09-08
- 2.0.0-alpha.33 — 2025-05-29
- 2.0.0-alpha.32 — 2025-05-28
- 2.0.0-alpha.31 — 2024-12-07
- 2.0.0-alpha.30 — 2024-10-11
- 2.0.0-alpha.29 — 2024-07-16
- 2.0.0-alpha.28 — 2024-03-11
- 2.0.0-alpha.27 — 2024-03-01
- 2.0.0-alpha.26 — 2024-02-02
- 2.0.0-alpha.25 — 2023-09-28
- 2.0.0-alpha.24 — 2023-08-09
- 2.0.0-alpha.23 — 2023-07-07
- 2.0.0-alpha.22 — 2023-06-12
- 2.0.0-alpha.21 — 2023-04-24
- 2.0.0-alpha.20 — 2023-04-19
- … 6 more at https://npm.io/package/@ulixee/js-path/versions

## README

# JsPath

JsPath is a serializable specification for referencing a path to a DOM node, property or method.

This library was created as a way to create paths to methods and properties of the DOM remotely. Breaking a path into individual steps allows a library to create references to nested objects (eg, passing a Node into a function) without AST parsing a string of code. It also provides a mechanism for creating "references" to nodes (NodePointer.id), dynamically inspecting properties (appending internal state methods), and more without requiring any parsing.

For a fully-typed implementation of accessing a remote DOM, refer to the [AwaitedDOM](https://docs.ulixee.org/docs/hero/basic-interfaces/awaited-dom).

### IJsPath

IJsPath is an array of "steps" to locate (or re-locate) a node. Steps can be the following:

- An [INodePointer](#inodepointer) id `number`. eg: `[1]`.
- A Function `Array`. `[MethodName, ...arguments]`, eg: `['document', ['querySelector','p']]`.
- A Property name `string`. eg: `[1, 'innerText']` will get the innerText of node with NodePointer id = 1.

### INodePointer

INodePointer is a persisted reference to a DOM Node. It includes extra details about a node. An iterable Node type will serialize the properties as well.

NOTE: A DOM Node could also be a querySelector, and can be used to re-retrieve instance properties.

- id: `number`. The Id that can be used in future references to this DOM Node.
- type: `string`. The type of DOM Node. eg, `HTMLDivElement`.
- preview?: `string`. A string preview of the HTML Element or DOM Node.
- iterableIsNodePointers?: `boolean`. If iterableItems are provided, returns `true` if the items are `INodePointers`.
- iterableItems?: `(string | number | boolean | object | INodePointer)[]`. The serialized iterable properties if this result set is iterable. eg, HTMLCollection, NodeList, Attributes, etc.

### INodeVisibility

INodeVisibility interface represents the various attributes of visibility a DOM Node possesses. It can be used to determine if a Node can be interacted with on a Webpage.

NOTE: It is up to an implementation library to create the mechanism for requesting the visibility of a node.

The returned properties will be calculated and returned as follows:

- isVisible `boolean`. The node is visible (`nodeExists`, `hasContainingElement`, `isConnected`, `hasCssOpacity`,`hasCssDisplay`,`hasCssVisibility` `hasDimensions`).
- isClickable `boolean`. The node is visible, in the viewport and unobstructed (`isVisible`, `isOnscreenVertical`, `isOnscreenHorizontal` and `isUnobstructedByOtherElements`).
- nodeExists `boolean`. Was the node found in the DOM.
- isOnscreenVertical `boolean`. The node is on-screen vertically.
- isOnscreenHorizontal `boolean`. The node is on-screen horizontally.
- hasContainingElement `boolean`. The node is an Element or has a containing Element providing layout.
- isConnected `boolean`. The node is connected to the DOM.
- hasCssOpacity `boolean`. The display `opacity` property is not "0".
- hasCssDisplay `boolean`. The display `display` property is not "none".
- hasCssVisibility `boolean`. The visibility `style` property is not "hidden".
- hasDimensions `boolean`. The node has width and height.
- isUnobstructedByOtherElements `boolean`. The node is not hidden or obscured > 50% by another element.

## Installation

```shell script
npm i --save @ulixee/js-path
```


## Contributing

Contributions are welcome.

## License

[MIT](LICENSE)

---
_Source: https://npm.io/package/@ulixee/js-path · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
