Core Types Library

Core Types is the foundation library of our monorepo, providing shared type definitions, the SafeAny system, and common interfaces used across all other libraries and applications.

📍 Library Details

• Location: libs/core-models/
• Dependencies: None (foundation layer)
• Type: Foundation Library
• Tags: npm:public
• Purpose: Shared type definitions and type safety utilities

🌟 Core Purpose

Core Types serves as the foundation for our entire type system by:

1. Providing SafeAny - A safe alternative to TypeScript's any type
2. Defining shared interfaces - Common types used across libraries
3. Preventing circular dependencies - Central location for shared types
4. Ensuring type consistency - Standardized type definitions

🔧 Key Exports

SafeAny Type System

The SafeAny type provides runtime safety while maintaining flexibility:

// Core SafeAny definition
export type SafeAny = unknown;

// Usage examples
interface MyComponentProps {
  data: SafeAny;
  config: Record<string, SafeAny>;
  callback?: (result: SafeAny) => void;
}

// Good ✅
import type { SafeAny } from '@core';

// Avoid ❌
const data: any = {}; // Never use any directly

UI Component Interfaces

Common interfaces for UI components:

// Select component types
export interface SelectOption {
  value: string;
  label: string;
  disabled?: boolean;
  group?: string;
}

export interface MultiSelectOption extends SelectOption {
  selected?: boolean;
}

export interface FormControlOption extends SelectOption {
  description?: string;
  icon?: string;
}

export interface SelectConfig {
  placeholder?: string;
  multiple?: boolean;
  searchable?: boolean;
  clearable?: boolean;
  disabled?: boolean;
}

Responsive System Types

Types for responsive design system:

// Breakpoint definitions
export interface Breakpoints {
  xs: number;
  sm: number;
  md: number;
  lg: number;
  xl: number;
  xxl: number;
}

export const DEFAULT_BREAKPOINTS: Breakpoints = {
  xs: 0,
  sm: 576,
  md: 768,
  lg: 992,
  xl: 1200,
  xxl: 1400
};

// Responsive value system
export interface ResponsiveValue<T> {
  xs?: T;
  sm?: T;
  md?: T;
  lg?: T;
  xl?: T;
  xxl?: T;
  default: T;
}

Page System Types

Comprehensive page and content modeling:

// Page status and metadata
export enum PageStatus {
  DRAFT = 'draft',
  PUBLISHED = 'published',
  ARCHIVED = 'archived',
  PENDING_REVIEW = 'pending_review'
}

// Cosmic system types
export interface PageWorldAssignment {
  id: string;
  label?: string;
  priority?: number;
}

export interface PageCosmos {
  galaxies: PageWorldAssignment[];
  world?: PageWorldAssignment;
}

// Core page interface
export interface Page {
  id: string;
  title: string;
  slug: string;
  description?: string;
  status: PageStatus;
  cosmos?: PageCosmos;
  version: number;
  createdAt: Date;
  updatedAt: Date;
}

Widget System Types

Foundation types for the widget system:

// Widget base interface
export interface Widget {
  id: string;
  type: string;
  config: SafeAny;
  position?: WidgetPosition;
  responsive?: ResponsiveValue<SafeAny>;
}

export interface WidgetPosition {
  x: number;
  y: number;
  width: number;
  height: number;
}

// Widget configuration
export interface WidgetConfig {
  type: string;
  props: Record<string, SafeAny>;
  responsive?: ResponsiveValue<SafeAny>;
}

Utility Types

Common utility types and helpers:

// UUID utilities
export class UUID {
  static generate(): string {
    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
      const r = Math.random() * 16 | 0;
      const v = c === 'x' ? r : (r & 0x3 | 0x8);
      return v.toString(16);
    });
  }
}

// Type guards
export function isString(value: SafeAny): value is string {
  return typeof value === 'string';
}

export function isNumber(value: SafeAny): value is number {
  return typeof value === 'number' && !isNaN(value);
}

export function isObject(value: SafeAny): value is Record<string, SafeAny> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

🏗️ Architecture Principles

Foundation Layer

Core Types is the foundation layer with no dependencies:

Applications (space-map, editor-web, ux-test)
    ↑ imports from
Feature Libraries (widgets, editor-ui, shared-ui)
    ↑ imports from  
Framework Libraries (ux-framework, theme-system)
    ↑ imports from
Core Libraries (core, permissions)
    ↑ imports from
Foundation Library (core-types) ← No dependencies

Type Safety Strategy

Core Types implements a comprehensive type safety strategy:

1. SafeAny over any - Provides runtime safety
2. Explicit type imports - import type { ... }
3. Shared definitions - Prevents circular dependencies
4. Strict typing - TypeScript strict mode compatibility

🔧 Usage Patterns

Import Patterns

Always use explicit type imports for types:

// Good ✅ - Type-only import
import type { SafeAny, SelectOption } from '@core';

// Good ✅ - Explicit value import
import { UUID, DEFAULT_BREAKPOINTS } from '@core';

// Avoid ❌ - Mixed imports
import { SafeAny, UUID } from '@core';

SafeAny Usage

Replace all any usage with SafeAny:

// Good ✅
interface ComponentProps {
  data: SafeAny;
  config: Record<string, SafeAny>;
  onUpdate: (value: SafeAny) => void;
}

// Avoid ❌
interface ComponentProps {
  data: any;
  config: any;
  onUpdate: (value: any) => void;
}

Type Guards with SafeAny

Use type guards for safe type narrowing:

function processData(data: SafeAny): string {
  if (isString(data)) {
    return data.toUpperCase(); // TypeScript knows data is string
  }
  
  if (isObject(data) && isString(data.title)) {
    return data.title;
  }
  
  return 'Unknown';
}

📦 Public API

Type Exports

// Core types
export type { SafeAny };

// UI component types
export type { 
  SelectOption, 
  MultiSelectOption, 
  FormControlOption,
  SelectConfig 
};

// Responsive system
export type { 
  ResponsiveValue, 
  Breakpoints 
};

// Page system
export type { 
  Page, 
  PageStatus, 
  PageCosmos,
  PageWorldAssignment 
};

// Widget system
export type { 
  Widget, 
  WidgetConfig, 
  WidgetPosition 
};

Value Exports

// Constants
export { DEFAULT_BREAKPOINTS };

// Enums
export { PageStatus };

// Utilities
export { UUID };

// Type guards
export { isString, isNumber, isObject };

🛠️ Development

Building the Library

# Build core-types (always build first)
npx nx build core-types

# Build with watch mode
npx nx build core-types --watch

# Check build output
ls dist/libs/core-models/

Testing

# Run tests
npx nx test core-types

# Run tests with coverage
npx nx test core-types --coverage

# Run linting
npx nx lint core-types

Library Structure

libs/core-models/
├── src/
│   ├── lib/
│   │   ├── models/          # Type definitions
│   │   │   ├── ui-components.model.ts
│   │   │   ├── page.model.ts
│   │   │   ├── widget.model.ts
│   │   │   └── responsive/
│   │   ├── utils/           # Utility functions
│   │   │   ├── uuid.ts
│   │   │   └── type-guards.ts
│   │   └── index.ts         # Internal exports
│   └── index.ts             # Public API
│   
├── project.json             # NX configuration
├── package.json             # Package metadata
└── README.md                # Library documentation

📋 Best Practices

Type Definition Guidelines

1. Use SafeAny instead of any
2. Export types explicitly with type keyword
3. Provide clear interfaces with JSDoc comments
4. Avoid circular references by keeping dependencies minimal

Integration Patterns

// Library consuming core-types
import type { SafeAny, SelectOption } from '@core';

export interface MyComponentProps {
  options: SelectOption[];
  config: SafeAny;
}

export class MyComponent {
  constructor(private props: MyComponentProps) {}
}

Version Management

Core Types follows semantic versioning:

• Major: Breaking changes to public APIs
• Minor: New types and interfaces
• Patch: Bug fixes and documentation updates

🎯 Key Benefits

Type Safety

• Runtime safety with SafeAny
• Compile-time checks with TypeScript
• Consistent interfaces across libraries

Developer Experience

• Clear API contracts with well-defined types
• IDE support with comprehensive type definitions
• Reduced errors through type checking

Architecture Benefits

• No circular dependencies as foundation layer
• Shared vocabulary across all libraries
• Consistent patterns for type definitions

🔗 Related Resources

• Space Map Application - Real usage examples
• UX Framework - Component type implementations
• Theme System - Responsive type usage
• Development Guide - How to use in new libraries

🌟 Evolution and Future

Core Types evolves carefully to maintain stability:

1. Additive changes - New types are added without breaking existing ones
2. Deprecation process - Old types are deprecated before removal
3. Community feedback - Changes are discussed and reviewed
4. Documentation updates - All changes are thoroughly documented

As the foundation of our type system, Core Types ensures consistency, safety, and maintainability across our entire monorepo ecosystem.