treenest
v0.0.119
Published
Image Gallery Management Library
Downloads
5
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
{
"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
, andimage3
. - Nested Folders: Inside
folder1
issubfolder1
, which containsimage1
andimage2
.
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.