# treenest

> Image Gallery Management Library

Latest version **0.0.119** (published 2024-02-15) · ISC license · 0 weekly downloads

## Install

```sh
npm install treenest
pnpm add treenest
yarn add treenest
bun add treenest
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.119 |
| Published | 2024-02-15 |
| First published | 2023-12-28 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 21.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Jordan Coeyman |
| Maintainers | acoyfellow |

## Links

- npm: https://www.npmjs.com/package/treenest
- npm.io page: https://npm.io/package/treenest

## Recent versions

- 0.0.119 (latest) — 2024-02-15
- 0.0.118 — 2023-12-29
- 0.0.117 — 2023-12-29
- 0.0.116 — 2023-12-29
- 0.0.115 — 2023-12-29
- 0.0.114 — 2023-12-29
- 0.0.113 — 2023-12-29
- 0.0.112 — 2023-12-29
- 0.0.111 — 2023-12-28
- 0.0.110 — 2023-12-28
- 0.0.109 — 2023-12-28
- 0.0.106 — 2023-12-28
- 0.0.105 — 2023-12-28
- 0.0.104 — 2023-12-28
- 0.0.103 — 2023-12-28
- … 6 more at https://npm.io/package/treenest/versions

## README

# TreeNest
An Image Gallery Management Library

## Why This Project Exists

This project provides a set of reusable functions designed to manage the structure and content of an image gallery. It's particularly useful for applications that involve organizing, moving, and updating images and folders in a gallery-like structure. The library is built with immutability in mind, ensuring that operations on the gallery structure do not have unintended side effects.

## Data Structure Explanation

The data structure expected by these functions is designed to resemble a hierarchical file system, commonly used for organizing files and folders. Here's a detailed explanation:

### Overview of the Data Structure

- **Root Object**: The top level is a JavaScript object, where each key can represent either an image or a folder.
- **Folders**: Represented as objects with two key properties:
  - `type`: Set to `"folder"`.
  - `items`: An object that contains nested folders or images, following the same structure rules as the root.

### Example Structure

```json
{
  "folder1": {
    "type": "folder",
    "items": {
      "subfolder1": {
        "type": "folder",
        "items": {
          "image1": { "src": "https://example.com/image1.jpg" },
          "image2": { "src": "https://example.com/image2.jpg" }
        }
      }
    }
  },
  "folder2": {
    "type": "folder",
    "items": { }
  },
  "image3": { "src": "https://example.com/image3.jpg" }
}
```

In this structure:
- **Root Level**: Contains `folder1`, `folder2`, and `image3`.
- **Nested Folders**: Inside `folder1` is `subfolder1`, which contains `image1` and `image2`.

### Key Points

- **Hierarchical Nature**: Allows for nesting folders within folders to any depth, mimicking a real-world file system.
- **Flexibility**: Accommodates additional properties for folders and images, like metadata.
- **Identification**: Entities are identified as folders if they have a `type` property set to `"folder"`, and as images otherwise.


## Reusable Functions

- `deepClone(obj={})`: Creates a deep copy of the given object, ensuring that changes to the copied object do not affect the original.
- `showLocation(folderPath=[])`: Returns the path to the current folder as a string.
- `createFolder(gallery={}, parentFolderPath=[], folderName="")`: Adds a new folder to a specified location in the gallery.
- `createImage(gallery={}, parentFolderPath=[], imageName="", src="")`: Adds a new image to a specified location in the gallery.
- `moveItems(gallery={}, fromFolderPath=[], toFolderPath=[], items=[])`: Moves items from one folder to another within the gallery.
- `deleteItems(gallery={}, folderPath=[], items=[])`: Deletes items from a specified folder in the gallery.
- `openFolder(gallery={}, folderPath=[])`: Opens a specified folder, returning its contents.
- `updateItem(gallery={}, folderPath=[], itemKey="", newItem={})`: Updates an item's properties in a specified folder.

## Usage Examples

### Creating a New Folder

```js
import { createFolder } from 'treenest';

const initialGallery = { ... };
const newGallery = createFolder(initialGallery, ['parentFolder'], 'newFolder');
```

### Adding an Image

```js
import { createImage } from 'treenest';

const updatedGallery = createImage(gallery, ['folderPath'], 'imageName', 'imageSrc');
```

### Moving Items

```js
import { moveItems } from 'treenest';

const updatedGallery = moveItems(gallery, ['fromFolder'], ['toFolder'], ['item1', 'item2']);
```

### Deleting Items from a Folder

```js
import { deleteItems } from 'treenest';

const initialGallery = {
  "folder1": {
    "type": "folder",
    "items": {
      "image1": { "src": "https://example.com/image1.jpg" },
      "image2": { "src": "https://example.com/image2.jpg" }
    }
  }
};

const updatedGallery = deleteItems(initialGallery, ['folder1'], ['image1']);
// updatedGallery now does not contain image1 in folder1
```

### Opening a Folder

```js
import { openFolder } from 'treenest';

const gallery = {
  "folder1": {
    "type": "folder",
    "items": {
      "subfolder1": {
        "type": "folder",
        "items": {
          "image1": { "src": "https://example.com/image1.jpg" }
        }
      }
    }
  }
};

const contents = openFolder(gallery, ['folder1', 'subfolder1']);
// contents will be the contents of subfolder1
```


### Updating an Item

```js
import { updateItem } from 'treenest';

const initialGallery = {
  "image1": { "src": "https://example.com/old_image1.jpg" }
};

const updatedGallery = updateItem(initialGallery, [], 'image1', { "src": "https://example.com/new_image1.jpg" });
// updatedGallery now has the updated source URL for image1
```


## Tests (incomplete)

The tests for each function are located in the `tests` folder of the source code. Each function has its own set of tests to ensure functionality and handle edge cases. To run the tests, navigate to the root directory of the project and run the test command configured in your package.json.

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