A collection of utility functions for use across VizHub packages. This library provides common functionality for working with VizHub visualizations, including ID generation and file manipulation.
npm install @vizhub/viz-utilsThis package depends on @vizhub/viz-types, which defines the TypeScript types used throughout the VizHub ecosystem.
Generates a unique VizId (a UUID v4 string without dashes) for a visualization. The generated ID is a 32-character hexadecimal string with the 13th character always being "4" (following UUID v4 format).
import { generateVizId } from "@vizhub/viz-utils";
const newVizId = generateVizId(); // e.g. "550e8400e29b41d4a716446655440000"Generates a unique VizFileId (an 8-character hexadecimal string) for a file within a visualization.
import { generateVizFileId } from "@vizhub/viz-utils";
const newFileId = generateVizFileId(); // e.g. "550e8400"Checks if a string is a valid VizId. A valid VizId must:
- Be exactly 32 characters long
- Contain only hexadecimal characters (0-9, a-f)
- Have "4" as the 13th character (following UUID v4 format)
import { isVizId } from "@vizhub/viz-utils";
isVizId("12345678901234567890123456789012"); // true if valid
isVizId("invalid-id"); // falseGets the text content of a file with the given name from a VizContent object. Returns null if:
- The file is not found
- The content is undefined
- The content has no files property
If multiple files with the same name exist, returns the content of the first matching file.
import { getFileText } from "@vizhub/viz-utils";
const htmlContent = getFileText(vizContent, "index.html");
if (htmlContent) {
// Use the file content
}Converts VizFiles (keyed by file ID) to a simpler file collection format (keyed by filename). Returns an empty object if:
- No files are provided
- The files object is empty
import { vizFilesToFileCollection } from "@vizhub/viz-utils";
const vizFiles = {
"550e8400": { name: "index.html", text: "<html>Test</html>" },
e29b41d4: { name: "script.js", text: 'console.log("Hello");' },
};
const fileCollection = vizFilesToFileCollection(vizFiles);
// Result: { "index.html": "<html>Test</html>", "script.js": 'console.log("Hello");' }Converts a simple file collection (keyed by filename) to VizFiles format (keyed by generated file ID). Returns an empty object if:
- No files are provided
- The files object is empty
import { fileCollectionToVizFiles } from "@vizhub/viz-utils";
const fileCollection = {
"index.html": "<html>Test</html>",
"script.js": 'console.log("Hello");',
};
const vizFiles = fileCollectionToVizFiles(fileCollection);
// Result: {
// "550e8400": { name: "index.html", text: "<html>Test</html>" },
// "e29b41d4": { name: "script.js", text: 'console.log("Hello");' }
// }This package uses the following types from @vizhub/viz-types:
VizId: A 32-character hexadecimal string that uniquely identifies a visualizationVizFileId: An 8-character hexadecimal string that uniquely identifies a file within a visualizationVizContent: The content of a visualization, including its filesVizFile: A file with a name and text contentVizFiles: A collection of files, indexed by their VizFileId
MIT