viz-utils

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.

Installation

npm install @vizhub/viz-utils

Dependencies

This package depends on @vizhub/viz-types, which defines the TypeScript types used throughout the VizHub ecosystem.

API

ID Generation

`generateVizId(): string`

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. "12345678901234567890123456789012"

`generateVizFileId(): string`

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. "12345678"

Validation

`isVizId(str: string): boolean`

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"); // false

File Operations

`getFileText(content: VizContent, fileName: string): string | null`

Gets 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
}

`vizFilesToFileCollection(files?: VizFiles): Record<string, string>`

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 = {
  file1: { name: "index.html", text: "<html>Test</html>" },
  file2: { name: "script.js", text: 'console.log("Hello");' },
};

const fileCollection = vizFilesToFileCollection(vizFiles);
// Result: { "index.html": "<html>Test</html>", "script.js": 'console.log("Hello");' }

Types

This package uses the following types from @vizhub/viz-types:

VizId: A 32-character hexadecimal string that uniquely identifies a visualization
VizFileId: An 8-character hexadecimal string that uniquely identifies a file within a visualization
VizContent: The content of a visualization, including its files
VizFile: A file with a name and text content
VizFiles: A collection of files, indexed by their VizFileId

License

MIT