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

{
  "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

import { createFolder } from 'treenest';

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

Adding an Image

import { createImage } from 'treenest';

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

Moving Items

import { moveItems } from 'treenest';

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

Deleting Items from a Folder

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

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

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.