A TypeScript package that provides common type definitions for the VizHub ecosystem. This package serves as the foundation for type safety and consistency across all VizHub projects.
viz-types is a types-only package - it exports TypeScript type definitions without any JavaScript runtime code, making it extremely lightweight. It defines the core data structures used throughout the VizHub ecosystem, ensuring type consistency across all dependent projects.
npm install @vizhub/viz-typesImport the types you need in your TypeScript files:
import { VizFile, VizFiles, VizContent, VizId } from "@vizhub/viz-types";
// Use the types in your code
const myFile: VizFile = {
name: "index.html",
text: "<body>Hello World</body>",
};The package provides several core types:
- FileCollection: A simple key-value collection of files
- VizFiles: A collection of VizFile objects with unique IDs
- VizFile: Represents a single file with name and content
- VizId: Unique identifier for a visualization
- VizLicense: SPDX license identifier
- VizTimestamp: Unix timestamp for tracking time
- VizChats: A collection of AI chat conversations
- VizChat: A single AI chat conversation
- VizChatMessage: Individual messages within a chat
- VizChatMessageId: Unique identifier for a chat message
- VizContent: The complete content of a visualization
A simple collection of files where:
- Keys are file names (e.g., "index.html")
- Values are file contents (e.g., "Hello")
- Used for scenarios requiring simple file operations without the complexity of a full VizFile structure
type FileCollection = Record<string, string>;A collection of VizFile objects where:
- Keys are unique file IDs (VizFileId), not file names or array indices
- This design simplifies Operational Transformation with ShareDB when files are renamed or deleted
- The file ID remains stable even when the file name changes or files are added/deleted
type VizFiles = {
[fileId: VizFileId]: VizFile;
};A unique identifier for a file:
- Represented as a random string
- Provides stability for tracking files even when they're renamed or moved
type VizFileId = string;Represents a single file with:
- name: The file name (e.g., "index.html")
- text: The text content of the file (e.g., "Hello")
type VizFile = {
name: string;
text: string;
};A unique identifier for a visualization:
- Common between Info and Content for a given visualization
- Implemented as a UUID v4 string with dashes removed (for ease of URL copying)
type VizId = string;The license associated with a visualization:
- Represented as an SPDX License Identifier
- References the "Identifier" column in the SPDX license list (https://spdx.org/licenses/)
type VizLicense = string;A timestamp down to the second:
- Represented as (Unix epoch milliseconds) / 1000
- Used for tracking creation and modification times
type VizTimestamp = number;A unique identifier for a chat:
- Represented as a random string
- Provides stability for tracking chat conversations
type VizChatId = string;The role of a message in a chat conversation:
- Based on LangChain's unified message types
- Supports "system", "user", "assistant", and "tool" roles
type VizChatMessageRole = "system" | "user" | "assistant" | "tool";A unique identifier for a chat message:
- Represented as a string
- Used to track individual messages within chat conversations
type VizChatMessageId = string;A single message in a chat conversation:
- role: The role of the message sender (system/user/assistant/tool)
- content: The text content of the message
- timestamp: When the message was created (VizTimestamp)
- id: Optional chat message identifier
type VizChatMessage = {
role: VizChatMessageRole;
content: string;
timestamp: VizTimestamp;
id?: VizChatMessageId;
};A single AI chat conversation:
- id: Unique identifier for this chat (VizChatId)
- title: Optional title/name of the chat conversation
- messages: Ordered array of messages in the conversation
- Follows LangChain pattern: system first (optional), then alternating user → assistant → tool
- createdAt: Timestamp when the chat was created
- updatedAt: Timestamp when the chat was last updated
type VizChat = {
id: VizChatId;
title?: string;
messages: VizChatMessage[];
createdAt: VizTimestamp;
updatedAt: VizTimestamp;
};A collection of AI chats associated with a visualization:
- Keys are unique chat IDs (VizChatId)
- Values are chat objects (VizChat)
- Similar structure to VizFiles for consistency
- Designed to work with LangChain's conversation patterns
type VizChats = {
[chatId: VizChatId]: VizChat;
};The complete content of a visualization:
- id: The VizId that this content is associated with
- files: The VizFiles in the visualization
- title: The title of the visualization (same as Info.title)
- Tracked here so it can be versioned
- Restoring an old version should restore its old title
- Optional field
- height: The customized height of the visualization in pixels
- Not defined if the user hasn't customized it
- If not defined, the default height is used
- Optional field
- license: The customized license associated with this visualization
- Not defined if the user hasn't customized it
- Optional field
- isInteracting: Indicates user interaction state
truewhen the user is interacting via interactive code widgets (e.g., Alt+drag)- Hot reloading is throttled when this is
true
- Hot reloading is throttled when this is
falseorundefinedwhen they are not (e.g., normal typing)- Hot reloading is debounced when this is
false
- Hot reloading is debounced when this is
- Optional field
- chats: The AI chats associated with this visualization
- Collection of VizChat objects for AI-powered conversations
- Optional field
type VizContent = {
id: VizId;
files: VizFiles;
title?: string;
height?: number;
license?: VizLicense;
isInteracting?: boolean;
chats?: VizChats;
};The types in this package are designed with specific considerations:
- Operational Transformation (OT) Friendly: File IDs remain stable even when files are renamed or moved, simplifying OT with ShareDB
- Lightweight: Zero runtime footprint
- Consistent: Provides a single source of truth for types across the ecosystem
This package is a core dependency for the following VizHub projects:
- viz-utils - Utility functions for the VizHub ecosystem
- vizhub-runtime - Runtime environment for VizHub visualizations
- editcodewithai - AI-powered code editor for VizHub
- vzcode - Manual code editor for VizHub
- vizhub - Main VizHub application
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.