Data Structures and Types

Overview

The Dynamic JSON Visualizer uses TypeScript to define clear data structures that ensure type safety throughout the application. This document explains the core types that define how data is structured, stored, and manipulated.

Core Data Types

JSONValue

export type JSONValue = 
  | string
  | number
  | boolean
  | null
  | JSONValue[]
  | { [key: string]: JSONValue };

JSONValue represents any valid JSON data type. This is a union type (indicated by the | symbols) that can be:

• A string like "hello"
• A number like 42 or 3.14
• A boolean true or false
• null
• An array of other JSONValues like [1, "text", true]
• An object with string keys and JSONValue values like {"name": "John", "age": 30}

This recursive definition allows for deeply nested JSON structures of any complexity.

JSONObject

export type JSONObject = {
  [key: string]: JSONValue;
  __id?: string;
  __flags?: Record<string, boolean>;
};

JSONObject extends a basic JSON object with special application-specific fields:

• [key: string]: JSONValue - Can contain any number of properties with string keys and JSONValue values
• __id?: string - Optional unique identifier added by the application (the ? means optional)
• __flags?: Record<string, boolean> - Optional object storing flag states as key-value pairs

Example:

{
  "name": "John Doe",
  "age": 30,
  "active": true,
  "__id": "abc123",
  "__flags": {
    "important": true,
    "reviewed": false
  }
}

The double underscore prefix (__) indicates these are internal application fields, not part of the original JSON data.

User Interface Types

ViewMode

export type ViewMode = 'card' | 'table';

A simple string literal type that restricts the view mode to exactly two options:

• 'card' - Display data as individual cards
• 'table' - Display data in a table format

SortConfig

export type SortConfig = {
  key: string;
  direction: 'asc' | 'desc';
};

Defines how data should be sorted:

• key - The field name to sort by (e.g., "name", "age")
• direction - Either ascending ('asc') or descending ('desc')

Customization Types

FlagType

export type FlagType = {
  id: string;
  name: string;
  color: string;
  icon: string;
};

Defines a custom flag that users can create to categorize their data:

• id - Unique identifier for the flag type
• name - Display name (e.g., "Important", "Needs Review")
• color - CSS color value for visual representation
• icon - Icon identifier from the Lucide icon library

Example:

{
  "id": "flag_001",
  "name": "High Priority",
  "color": "#ef4444",
  "icon": "AlertTriangle"
}

AppConfig

export type AppConfig = {
  uniqueFields: string[];
  imageField: string | null;
  displayFields: string[];
};

Stores user preferences for how data should be displayed:

• uniqueFields - Array of field names that should be treated as unique identifiers
• imageField - Field name containing image URLs, or null if none
• displayFields - Array of field names to show in the interface

Context Type

DataContextType

export type DataContextType = {
  // Data state
  data: JSONObject[];
  originalData: JSONObject[];
  loading: boolean;
  
  // UI state
  flagTypes: FlagType[];
  viewMode: ViewMode;
  searchTerm: string;
  isRegexSearch: boolean;
  sortConfig: SortConfig | null;
  
  // Configuration
  uniqueFields: string[];
  imageField: string | null;
  displayFields: string[];
  
  // Functions (methods)
  loadJsonData: (jsonData: JSONObject[], fields?: string[]) => Promise<{ newCount: number, updatedCount: number } | undefined>;
  clearAllData: () => Promise<void>;
  deleteObjects: (ids: string[]) => Promise<void>;
  updateFlag: (id: string, flagId: string, value: boolean) => Promise<void>;
  setViewMode: (mode: ViewMode) => void;
  setIsRegexSearch: (isRegex: boolean) => void;
  setSortConfig: (config: SortConfig | null) => void;
  addFlagType: (name: string, color: string, icon: string) => Promise<void>;
  removeFlagType: (id: string) => Promise<void>;
  setUniqueFields: (fields: string[]) => Promise<void>;
  setImageField: (field: string | null) => Promise<void>;
  setDisplayFields: (fields: string[]) => Promise<void>;
};

This is the interface for the React Context that manages all application state. It's divided into three categories:

Data State:

• Current filtered/sorted data and original unmodified data
• Loading status for async operations

UI State:

• Current view mode, search settings, and sort configuration
• Available flag types for categorization

Configuration:

• User preferences for data display and field handling

Functions:

• Methods for data manipulation (loading, deleting, flagging)
• Methods for updating UI state and configuration
• All data operations return Promise objects since they involve IndexedDB operations

Type Safety Benefits

These TypeScript types provide several advantages:

1. Compile-time checking - Errors are caught before the code runs
2. IntelliSense support - IDEs can provide autocomplete and suggestions
3. Documentation - Types serve as inline documentation of expected data shapes
4. Refactoring safety - Changes to types automatically highlight areas that need updates

The type system ensures that data flows correctly between components and that the application handles JSON data consistently throughout its lifecycle.