@almadar/cli 1.0.6 → 1.0.7

package/shells/typescript-shell/packages/client/src/renderer/useClientEffects.ts

@@ -1,236 +0,0 @@
-/**
- * useClientEffects Hook
- *
- * React hook for executing client effects from server responses.
- * Handles effect tracking to prevent duplicate executions and
- * integrates with the client effect executor.
- *
- * Used by both Builder preview and compiled shell trait hooks.
- *
- * @packageDocumentation
- */
-
-import { useEffect, useRef, useCallback } from 'react';
-import { executeClientEffects } from './client-effect-executor';
-import type { ClientEffect, ClientEffectExecutorConfig } from './types';
-
-// ============================================================================
-// Hook Types
-// ============================================================================
-
-/**
- * Options for the useClientEffects hook
- */
-export interface UseClientEffectsOptions extends ClientEffectExecutorConfig {
-  /**
-   * Whether to execute effects. Defaults to true.
-   * Set to false to temporarily disable effect execution.
-   */
-  enabled?: boolean;
-
-  /**
-   * Debug mode - logs effect execution details.
-   */
-  debug?: boolean;
-}
-
-/**
- * Result of useClientEffects hook
- */
-export interface UseClientEffectsResult {
-  /**
-   * Number of effects executed in the last batch.
-   */
-  executedCount: number;
-
-  /**
-   * Whether effects are currently being executed.
-   */
-  executing: boolean;
-
-  /**
-   * Manually trigger effect execution.
-   * Useful for imperative control.
-   */
-  execute: (effects: ClientEffect[]) => void;
-}
-
-// ============================================================================
-// Hook Implementation
-// ============================================================================
-
-/**
- * Execute client effects from server response.
- *
- * This hook automatically executes effects when they change,
- * tracking which effects have been executed to prevent duplicates.
- *
- * @param effects - Array of client effects to execute (from server response)
- * @param options - Configuration including effect implementations
- * @returns Hook result with execution state and manual trigger
- *
- * @example
- * ```typescript
- * function useMyTrait() {
- *   const [state, setState] = useState({ pendingEffects: [] });
- *   const effectConfig = useClientEffectConfig();
- *
- *   useClientEffects(state.pendingEffects, {
- *     ...effectConfig,
- *     onComplete: () => setState(s => ({ ...s, pendingEffects: [] }))
- *   });
- *
- *   // ...
- * }
- * ```
- */
-export function useClientEffects(
-  effects: ClientEffect[] | undefined,
-  options: UseClientEffectsOptions
-): UseClientEffectsResult {
-  const {
-    enabled = true,
-    debug = false,
-    onComplete,
-    ...config
-  } = options;
-
-  // Track executed effects to prevent duplicate execution
-  const executedRef = useRef<Set<string>>(new Set());
-  const executingRef = useRef(false);
-  const executedCountRef = useRef(0);
-
-  // Generate a unique key for an effect (for deduplication)
-  const getEffectKey = useCallback((effect: ClientEffect): string => {
-    return JSON.stringify(effect);
-  }, []);
-
-  // Manual execute function
-  const execute = useCallback((effectsToExecute: ClientEffect[]) => {
-    if (executingRef.current || effectsToExecute.length === 0) {
-      return;
-    }
-
-    executingRef.current = true;
-
-    // Filter out already executed effects
-    const newEffects = effectsToExecute.filter((effect) => {
-      const key = getEffectKey(effect);
-      if (executedRef.current.has(key)) {
-        if (debug) {
-          console.log('[useClientEffects] Skipping duplicate effect:', effect);
-        }
-        return false;
-      }
-      return true;
-    });
-
-    if (newEffects.length === 0) {
-      executingRef.current = false;
-      return;
-    }
-
-    if (debug) {
-      console.log('[useClientEffects] Executing effects:', newEffects);
-    }
-
-    // Mark effects as executed
-    newEffects.forEach((effect) => {
-      executedRef.current.add(getEffectKey(effect));
-    });
-
-    // Execute effects
-    executeClientEffects(newEffects, {
-      ...config,
-      onComplete: () => {
-        executedCountRef.current = newEffects.length;
-        executingRef.current = false;
-        onComplete?.();
-      },
-    });
-  }, [config, debug, getEffectKey, onComplete]);
-
-  // Automatic execution on effects change
-  useEffect(() => {
-    if (!enabled || !effects || effects.length === 0) {
-      return;
-    }
-
-    execute(effects);
-  }, [effects, enabled, execute]);
-
-  // Reset executed tracking when effects array reference changes
-  // (indicates a new batch of effects from a new event response)
-  const prevEffectsRef = useRef<ClientEffect[] | undefined>();
-  useEffect(() => {
-    if (effects !== prevEffectsRef.current) {
-      // New effects array - this is a new batch
-      // Keep the executed set but allow these new effects to execute
-      prevEffectsRef.current = effects;
-    }
-  }, [effects]);
-
-  return {
-    executedCount: executedCountRef.current,
-    executing: executingRef.current,
-    execute,
-  };
-}
-
-// ============================================================================
-// Effect Config Context Hook
-// ============================================================================
-
-/**
- * Context for client effect configuration.
- * This should be provided at the app root by OrbitalProvider.
- */
-import { createContext, useContext } from 'react';
-
-const ClientEffectConfigContext = createContext<ClientEffectExecutorConfig | null>(null);
-
-/**
- * Provider for client effect configuration.
- */
-export const ClientEffectConfigProvider = ClientEffectConfigContext.Provider;
-
-/**
- * Hook to get the client effect configuration from context.
- *
- * @throws Error if used outside of ClientEffectConfigProvider
- *
- * @example
- * ```typescript
- * function MyTraitHook() {
- *   const effectConfig = useClientEffectConfig();
- *
- *   useClientEffects(pendingEffects, {
- *     ...effectConfig,
- *     onComplete: () => clearPendingEffects()
- *   });
- * }
- * ```
- */
-export function useClientEffectConfig(): ClientEffectExecutorConfig {
-  const context = useContext(ClientEffectConfigContext);
-
-  if (!context) {
-    throw new Error(
-      'useClientEffectConfig must be used within a ClientEffectConfigProvider. ' +
-      'Make sure your component tree is wrapped with OrbitalProvider.'
-    );
-  }
-
-  return context;
-}
-
-/**
- * Hook to get client effect configuration, returning null if not available.
- * Use this for optional integration where effects may not be configured.
- */
-export function useClientEffectConfigOptional(): ClientEffectExecutorConfig | null {
-  return useContext(ClientEffectConfigContext);
-}
-
-// Export the context for direct use
-export { ClientEffectConfigContext };

package/shells/typescript-shell/packages/client/src/stores/entityStore.ts

@@ -1,233 +0,0 @@
-/**
- * Entity Store
- *
- * Simple module-level store for runtime entities.
- * No providers needed - hooks import and use directly.
- *
- * NOTE: Mutations create new Map instances to trigger React rerenders
- * when using useSyncExternalStore.
- */
-
-import {
-    type EntityFilterValue,
-    type FilterOperator,
-    type EntityFilters,
-    applyFilters,
-    createFilter
-} from './filtering';
-
-// Re-export filtering types for convenience
-export type { EntityFilterValue, FilterOperator, EntityFilters };
-export { applyFilters, createFilter };
-
-export interface Entity {
-  id: string;
-  type: string;
-  [key: string]: unknown;
-}
-
-type Listener = () => void;
-
-// Module-level state - use `let` so we can reassign to new Map on mutations
-let entities = new Map<string, Entity>();
-let filters = new Map<string, EntityFilters>();
-const listeners = new Set<Listener>();
-let idCounter = 0;
-
-/**
- * Subscribe to store changes
- */
-export function subscribe(listener: Listener): () => void {
-  listeners.add(listener);
-  return () => listeners.delete(listener);
-}
-
-/**
- * Notify all listeners of changes
- */
-function notify(): void {
-  listeners.forEach(listener => listener());
-}
-
-/**
- * Get all entities
- */
-export function getEntities(): Map<string, Entity> {
-  return entities;
-}
-
-/**
- * Get entity by ID
- */
-export function getEntity(id: string): Entity | undefined {
-  return entities.get(id);
-}
-
-/**
- * Get entities by type
- */
-export function getByType(type: string | string[]): Entity[] {
-  const types = Array.isArray(type) ? type : [type];
-  return [...entities.values()].filter(e => types.includes(e.type));
-}
-
-/**
- * Get all entities as array
- */
-export function getAllEntities(): Entity[] {
-  return [...entities.values()];
-}
-
-/**
- * Get singleton entity by type (first of that type)
- */
-export function getSingleton(type: string): Entity | undefined {
-  return [...entities.values()].find(e => e.type === type);
-}
-
-/**
- * Spawn a new entity
- */
-export function spawnEntity(config: { type: string; id?: string; [key: string]: unknown }): string {
-  const id = config.id ?? `entity_${++idCounter}`;
-  const entity: Entity = { ...config, id };
-  // Create new Map to trigger React rerender
-  entities = new Map(entities);
-  entities.set(id, entity);
-  notify();
-  return id;
-}
-
-/**
- * Update an entity
- */
-export function updateEntity(id: string, updates: Partial<Entity>): void {
-  const entity = entities.get(id);
-  if (entity) {
-    // Create new Map to trigger React rerender
-    entities = new Map(entities);
-    entities.set(id, { ...entity, ...updates });
-    notify();
-  }
-}
-
-/**
- * Update singleton entity by type
- */
-export function updateSingleton(type: string, updates: Partial<Entity>): void {
-  const entity = getSingleton(type);
-  if (entity) {
-    updateEntity(entity.id, updates);
-  }
-}
-
-/**
- * Remove an entity
- */
-export function removeEntity(id: string): void {
-  if (entities.has(id)) {
-    // Create new Map to trigger React rerender
-    entities = new Map(entities);
-    entities.delete(id);
-    notify();
-  }
-}
-
-/**
- * Clear all entities
- */
-export function clearEntities(): void {
-  // Create new Map to trigger React rerender
-  entities = new Map();
-  notify();
-}
-
-// ============================================================================
-// Filter Management
-// ============================================================================
-
-/**
- * Set a filter for an entity type
- * @param entityType - The entity type to filter (e.g., "Player", "Enemy")
- * @param field - The filter key (e.g., 'status' or 'date_from')
- * @param value - The filter value
- * @param operator - The comparison operator
- * @param targetField - The actual record field to compare (defaults to field)
- */
-export function setFilter(
-  entityType: string,
-  field: string,
-  value: unknown,
-  operator: FilterOperator = 'eq',
-  targetField?: string
-): void {
-  filters = new Map(filters);
-  const entityFilters = new Map(filters.get(entityType) || []);
-  entityFilters.set(field, createFilter(field, value, operator, targetField));
-  filters.set(entityType, entityFilters);
-  notify();
-}
-
-/**
- * Clear a specific filter
- */
-export function clearFilter(entityType: string, field: string): void {
-  const entityFilters = filters.get(entityType);
-  if (entityFilters && entityFilters.has(field)) {
-    filters = new Map(filters);
-    const newFilters = new Map(entityFilters);
-    newFilters.delete(field);
-    filters.set(entityType, newFilters);
-    notify();
-  }
-}
-
-/**
- * Clear all filters for an entity type
- */
-export function clearAllFilters(entityType: string): void {
-  if (filters.has(entityType)) {
-    filters = new Map(filters);
-    filters.set(entityType, new Map());
-    notify();
-  }
-}
-
-/**
- * Get active filters for an entity type
- */
-export function getFilters(entityType: string): EntityFilters {
-  return filters.get(entityType) || new Map();
-}
-
-/**
- * Get entities by type with optional filtering
- */
-export function getByTypeFiltered(type: string | string[]): Entity[] {
-  const types = Array.isArray(type) ? type : [type];
-  let result = [...entities.values()].filter(e => types.includes(e.type));
-
-  // Apply filters for each type
-  for (const t of types) {
-    const typeFilters = filters.get(t);
-    if (typeFilters && typeFilters.size > 0) {
-      result = applyFilters(result, typeFilters);
-    }
-  }
-
-  return result;
-}
-
-/**
- * Get snapshot for React useSyncExternalStore
- */
-export function getSnapshot(): Map<string, Entity> {
-  return entities;
-}
-
-/**
- * Get filter snapshot for React useSyncExternalStore
- */
-export function getFilterSnapshot(): Map<string, EntityFilters> {
-  return filters;
-}

package/shells/typescript-shell/packages/client/src/stores/filtering.ts

@@ -1,180 +0,0 @@
-/**
- * Entity Filtering Utilities
- *
- * Provides filter types and utility functions for filtering entity records.
- * Used by EntityStore and can be imported by runtime preview.
- */
-
-// ============================================================================
-// Types
-// ============================================================================
-
-/** Filter value for a single field (entity filtering) */
-export interface EntityFilterValue {
-    /** The field key (may include suffix like _from, _to for date ranges) */
-    field: string;
-    /** The actual record field to compare against (defaults to field if not specified) */
-    targetField?: string;
-    value: unknown;
-    /** Comparison operator for filtering
-     * - eq: exact match (default)
-     * - contains: substring match for strings
-     * - in: value is in array
-     * - date_eq: same date (ignoring time)
-     * - date_gte: on or after date
-     * - date_lte: on or before date
-     */
-    operator?: FilterOperator;
-}
-
-/** Operator type for filter */
-export type FilterOperator = 'eq' | 'contains' | 'in' | 'date_eq' | 'date_gte' | 'date_lte' | 'search';
-
-/** Filter state for an entity - Map of field key to filter value */
-export type EntityFilters = Map<string, EntityFilterValue>;
-
-/** Record type that can be filtered */
-export interface FilterableRecord {
-    id: string;
-    [key: string]: unknown;
-}
-
-// ============================================================================
-// Utility Functions
-// ============================================================================
-
-/**
- * Extract date part from ISO string or Date object.
- * Returns format: "YYYY-MM-DD"
- */
-export function getDateString(value: unknown): string | null {
-    if (!value) return null;
-    if (typeof value === 'string') {
-        // Handle ISO dates "2024-01-15T00:00:00.000Z" -> "2024-01-15"
-        // Also handle plain date strings "2024-01-15"
-        const match = value.match(/^(\d{4}-\d{2}-\d{2})/);
-        return match ? match[1] : null;
-    }
-    if (value instanceof Date) {
-        return value.toISOString().split('T')[0];
-    }
-    return null;
-}
-
-/**
- * Apply a single filter to check if a record matches.
- * Returns true if the record passes the filter.
- */
-export function matchesFilter(record: FilterableRecord, filter: EntityFilterValue): boolean {
-    // Use targetField if specified, otherwise fall back to field
-    const fieldToCompare = filter.targetField || filter.field;
-    const recordValue = record[fieldToCompare];
-    const filterValue = filter.value;
-    const operator = filter.operator || 'eq';
-
-    // Skip if filter value is null/undefined/empty (means "all")
-    if (filterValue === null || filterValue === undefined || filterValue === '') {
-        return true;
-    }
-
-    switch (operator) {
-        case 'eq':
-            // Case-insensitive comparison for strings
-            if (typeof recordValue === 'string' && typeof filterValue === 'string') {
-                return recordValue.toLowerCase() === filterValue.toLowerCase();
-            }
-            return recordValue === filterValue;
-
-        case 'contains':
-            if (typeof recordValue !== 'string') return false;
-            return recordValue.toLowerCase().includes(String(filterValue).toLowerCase());
-
-        case 'in':
-            if (Array.isArray(filterValue)) {
-                // Case-insensitive for string arrays
-                const normalizedFilterValues = filterValue.map(v =>
-                    typeof v === 'string' ? v.toLowerCase() : v
-                );
-                const normalizedRecordValue = typeof recordValue === 'string'
-                    ? recordValue.toLowerCase()
-                    : recordValue;
-                return normalizedFilterValues.includes(normalizedRecordValue);
-            }
-            return false;
-
-        case 'date_eq': {
-            // Compare dates ignoring time
-            const recordDate = getDateString(recordValue);
-            const filterDate = getDateString(filterValue);
-            return Boolean(recordDate && filterDate && recordDate === filterDate);
-        }
-
-        case 'date_gte': {
-            // Record date >= filter date
-            const recordDate = getDateString(recordValue);
-            const filterDate = getDateString(filterValue);
-            return Boolean(recordDate && filterDate && recordDate >= filterDate);
-        }
-
-        case 'date_lte': {
-            // Record date <= filter date
-            const recordDate = getDateString(recordValue);
-            const filterDate = getDateString(filterValue);
-            return Boolean(recordDate && filterDate && recordDate <= filterDate);
-        }
-
-        case 'search': {
-            // Search across ALL string/number fields in the record
-            // The filterValue is the search term, recordValue is ignored
-            // We search all fields, not just the targetField
-            if (typeof filterValue !== 'string' || !filterValue.trim()) {
-                return true; // Empty search matches all
-            }
-            const searchTerm = filterValue.toLowerCase();
-            return Object.values(record).some((value) => {
-                if (value === null || value === undefined) return false;
-                return String(value).toLowerCase().includes(searchTerm);
-            });
-        }
-
-        default:
-            return true;
-    }
-}
-
-/**
- * Apply all filters to a list of records.
- * Returns only records that match ALL filters.
- */
-export function applyFilters<T extends FilterableRecord>(
-    records: T[],
-    entityFilters: EntityFilters
-): T[] {
-    if (entityFilters.size === 0) return records;
-
-    return records.filter(record => {
-        for (const [, filter] of entityFilters) {
-            if (!matchesFilter(record, filter)) {
-                return false;
-            }
-        }
-        return true;
-    });
-}
-
-/**
- * Create a filter value with proper defaults.
- */
-export function createFilter(
-    field: string,
-    value: unknown,
-    operator: FilterOperator = 'eq',
-    targetField?: string
-): EntityFilterValue {
-    return {
-        field,
-        value,
-        operator,
-        targetField: targetField || field
-    };
-}

package/shells/typescript-shell/packages/client/src/stores/index.ts

@@ -1,11 +0,0 @@
-/**
- * Stores
- *
- * Module-level state management for entities and filtering.
- */
-
-// Export filtering types and utilities
-export * from './filtering';
-
-// Export entity store
-export * from './entityStore';