---
url: https://plugin.stripo.email/extensions/reference/nodes/BaseImmutableNode.md
---
# BaseImmutableNode

Foundational interface for all immutable nodes in the Stripo Email Editor Extensions SDK.

```typescript
interface BaseImmutableNode<T extends ImmutableHtmlNode | ImmutableCssNode>
```

## Description

`BaseImmutableNode` is the foundational interface that provides common querying and traversal methods for both HTML and CSS nodes. It enables navigation through the document tree, searching for elements, and accessing node relationships.

## Import

```typescript
import { BaseImmutableNode } from '@stripoinc/ui-editor-extensions';
```

## Type Parameters

| Parameter | Constraint | Description |
|-----------|------------|-------------|
| `T` | `ImmutableHtmlNode \| ImmutableCssNode` | The specific node type (HTML or CSS) |

## Methods

### Query Methods

#### querySelector()

Finds a single matching child element within the node's subtree.

```typescript
querySelector(selector: string): T | undefined
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `selector` | `string` | CSS selector for HTML nodes, special syntax for CSS nodes |

**Returns:** `T | undefined` - First matching node, or `undefined` if no match

**HTML Selector Syntax:**

* Standard CSS selectors: `.class`, `#id`, `tag`, `[attribute]`

**CSS Node Selector Syntax:**

* `@{max-width:100px}` - Media query, exact match
* `@*{max-width}` - Media query, partial match
* `#test.class-2` - Selector, exact match
* `*#test` - Selector, partial match
* `{display}` - Attribute, exact match
* `&{comment text}` - Comment, exact match
* `&*{comment}` - Comment, partial match

**Example:**

```typescript
// HTML node
const button = htmlNode.querySelector('.btn-primary');

// CSS node
const mediaQuery = cssNode.querySelector('@{media only screen and (max-width: 600px)}');
```

***

#### querySelectorAll()

Returns all matching elements within the current node's subtree.

```typescript
querySelectorAll(selector: string): T[]
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `selector` | `string` | CSS selector for HTML nodes, special syntax for CSS nodes |

**Returns:** `T[]` - Array of matching nodes, empty array if no matches

**Example:**

```typescript
// Find all buttons
const buttons = htmlNode.querySelectorAll('button');

// Find all CSS rules with display property
const displayRules = cssNode.querySelectorAll('{display}');
```

***

#### closest()

Finds the closest ancestor matching the selector.

```typescript
closest(selector: string): T | undefined
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `selector` | `string` | Selector to match parent nodes |

**Returns:** `T | undefined` - Closest matching parent, or `undefined` if not found

**Example:**

```typescript
// Find closest container
const container = element.closest('.container');

// Find parent media query
const mediaParent = cssRule.closest('@*{max-width}');
```

***

### Navigation Methods

#### parent()

Retrieves the parent node.

```typescript
parent(): T | undefined
```

**Returns:** `T | undefined` - Parent node, or `undefined` if no parent

**Example:**

```typescript
const parentElement = node.parent();
if (parentElement) {
    console.log('Parent found');
}
```

***

#### children()

Retrieves direct child element nodes (excludes text nodes).

```typescript
children(): T[]
```

**Returns:** `T[]` - Array of child element nodes

**Example:**

```typescript
const childElements = container.children();
console.log(`Container has ${childElements.length} child elements`);
```

***

#### childNodes()

Retrieves all child nodes including text nodes.

```typescript
childNodes(): T[]
```

**Returns:** `T[]` - Array of all child nodes

**Example:**

```typescript
const allChildren = element.childNodes();
// Includes both element and text nodes
```

***

#### siblings()

Retrieves sibling nodes of the current node.

```typescript
siblings(): T[]
```

**Returns:** `T[]` - Array of sibling nodes (excludes current node)

**Example:**

```typescript
const siblings = node.siblings();
siblings.forEach(sibling => {
    // Process each sibling
});
```

***

#### nextSibling()

Retrieves the next sibling node.

```typescript
nextSibling(): T | undefined
```

**Returns:** `T | undefined` - Next sibling, or `undefined` if none

**Example:**

```typescript
let current = firstNode;
while (current) {
    // Process node
    current = current.nextSibling();
}
```

***

#### nextElementSibling()

Retrieves the next sibling that is an element node.

```typescript
nextElementSibling(): T | undefined
```

**Returns:** `T | undefined` - Next element sibling, or `undefined` if none

**Example:**

```typescript
const nextElement = node.nextElementSibling();
// Skips text nodes
```

***

#### previousSibling()

Retrieves the previous sibling node.

```typescript
previousSibling(): T | undefined
```

**Returns:** `T | undefined` - Previous sibling, or `undefined` if none

***

#### previousElementSibling()

Retrieves the previous sibling that is an element node.

```typescript
previousElementSibling(): T | undefined
```

**Returns:** `T | undefined` - Previous element sibling, or `undefined` if none

***

### Node Information Methods

#### getType()

Retrieves the type of the node.

```typescript
getType(): string | undefined
```

**Returns:** `string | undefined` - Node type

**HTML Node Types:**

* `'element'` - HTML element
* `'text'` - Text node
* `'comment'` - Comment node
* `'document'` - Document node
* `'doctype'` - DOCTYPE declaration
* `'documentFragment'` - Document fragment

**CSS Node Types:**

* `'attr'` - CSS attribute/property
* `'comment'` - CSS comment
* `'rule'` - CSS rule
* `'media'` - Media query
* `'document'` - CSS document

**Example:**

```typescript
if (node.getType() === 'element') {
    // Handle element node
}
```

***

#### getNodeConfig()

Retrieves the configuration object of the node.

```typescript
getNodeConfig(): Record<string, any>
```

**Returns:** `Record<string, any>` - Node configuration object

**Example:**

```typescript
const config = node.getNodeConfig();
if (config.customProperty) {
    // Use custom configuration
}
```

***

#### getClosestModuleId()

Retrieves the ID of the closest module associated with the current node.

```typescript
getClosestModuleId(): number | undefined
```

**Returns:** `number | undefined` - Module ID, or `undefined` if not within a module

**Example:**

```typescript
const moduleId = node.getClosestModuleId();
if (moduleId) {
    console.log(`Node is within module ${moduleId}`);
}
```

***

#### getClosestModuleElement()

Retrieves the closest module element associated with the current node.

```typescript
getClosestModuleElement(): T | undefined
```

**Returns:** `T | undefined` - The immutable node representing the module element, or `undefined` if not within a module

**Example:**

```typescript
const moduleElement = node.getClosestModuleElement();
if (moduleElement) {
    console.log('Module element:', moduleElement);
   
}
```

***

#### getModuleElementsById()

Returns module elements by module ID.

```typescript
getModuleElementsById(id: number): T[]
```

**Returns:** `T[]` - Array of module elements matching the ID

**Example:**

```typescript
const modules = node.getModuleElementsById(123);
```

***

#### getModuleElements()

Returns all module elements within the document.

```typescript
getModuleElements(): T[]
```

**Returns:** `T[]` - Array of all module elements

**Example:**

```typescript
const allModules = node.getModuleElements();
```

## Best Practices

1. **Check for undefined**: Many methods return `undefined` when no match is found
2. **Use appropriate selectors**: HTML and CSS nodes have different selector syntaxes
3. **Type checking**: Use `getType()` to determine node type before operations
4. **Efficient traversal**: Use specific methods like `children()` vs `childNodes()` based on needs
5. **Cache results**: Store frequently accessed nodes to avoid repeated queries