import { Meta, Source } from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/en/figma-code/Classes/FigmaStorage - Working with document storage'/>

# Class `FigmaStorage`

A high-level wrapper for Figma's `setPluginData` and `getPluginData` APIs. It allows for storing structured data directly within the Figma document, either globally (`figma.root`) or attached to specific nodes. These data are shared among all users collaborating on the file.

## Key Features

- **Node-Specific Storage** — Data can be bound to any Figma node (Frame, Group, etc.) or the document root.
- **Shared Access** — Unlike client storage, plugin data is saved inside the `.fig` file and is synchronized across all users.
- **Instance Management** — The class uses internal caching to ensure that multiple calls for the same key on the same node return the same instance.
- **Automatic Serialization** — Handles JSON conversion for complex data structures transparently.

## Initialization

Access an instance using static methods. You can provide a raw node or a node ID.

```typescript
import { FigmaStorage } from '@dxtmisha/figma-code'

// Get instance for the entire document
const globalStorage = FigmaStorage.getInstance<object>('app-settings')

// Get instance for a specific node by ID
const nodeStorage = await FigmaStorage.getInstanceById<string>('element-name', '1:123')
```

## Methods

### Data Access

Methods for managing data stored in the document.

- `get(defaultValue?: T | (() => T)): T | undefined` — Retrieves data from the node. Sets a default value if the storage is empty.
- `set(value?: T | (() => T)): T | undefined` — Updates the data for the node and returns the new value.
- `remove(): this` — Clears the plugin data for the specified key on the node.

### Instance Management (Static)

Methods for retrieving class instances.

- `static getInstance<T>(name: string, item: UiFigmaNode): FigmaStorage<T>` — Returns an instance for a specific node.
- `static getInstanceById<T>(name: string, id?: string): Promise<FigmaStorage<T>>` — Asynchronously retrieves an instance using a node ID.
