@almadar/cli 0.3.1 → 0.3.3

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

@@ -0,0 +1,236 @@
+/**
+ * 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

@@ -0,0 +1,233 @@
+/**
+ * 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

@@ -0,0 +1,180 @@
+/**
+ * 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

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