freesail 0.0.1 → 0.1.0

package/packages/core/src/store.ts

@@ -0,0 +1,452 @@
+/**
+ * Surface Store
+ * 
+ * Reactive state management for A2UX surfaces.
+ * Manages component trees, data models, and subscriptions.
+ */
+
+import type { A2UXComponent, WatchSurfaceResponseMessage } from './types.js';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface Surface {
+  /** Surface unique identifier */
+  surfaceId: string;
+  /** Catalog ID for component definitions */
+  catalogId: string;
+  /** Component tree (flat adjacency list) */
+  components: Map<string, A2UXComponent>;
+  /** Data model state */
+  dataModel: Record<string, unknown>;
+  /** Creation timestamp */
+  createdAt: number;
+  /** Last update timestamp */
+  updatedAt: number;
+}
+
+export interface StoreEventMap {
+  'surfaceCreated': { surfaceId: string; catalogId: string };
+  'surfaceDeleted': { surfaceId: string };
+  'componentsUpdated': { surfaceId: string; componentIds: string[] };
+  'dataModelUpdated': { surfaceId: string; path: string; value: unknown };
+  'watchCallback': WatchSurfaceResponseMessage;
+}
+
+export type StoreEventHandler<K extends keyof StoreEventMap> = 
+  (data: StoreEventMap[K]) => void;
+
+// =============================================================================
+// JSON Pointer Utilities
+// =============================================================================
+
+/**
+ * Parse a JSON Pointer path into an array of keys
+ */
+function parseJsonPointer(pointer: string): string[] {
+  if (!pointer || pointer === '/') return [];
+  
+  return pointer
+    .split('/')
+    .slice(1) // Remove leading empty string from initial /
+    .map(segment => segment.replace(/~1/g, '/').replace(/~0/g, '~'));
+}
+
+/**
+ * Get a value from an object using a JSON Pointer path
+ */
+function getByPointer(obj: Record<string, unknown>, pointer: string): unknown {
+  const keys = parseJsonPointer(pointer);
+  let current: unknown = obj;
+  
+  for (const key of keys) {
+    if (current === null || current === undefined) return undefined;
+    current = (current as Record<string, unknown>)[key];
+  }
+  
+  return current;
+}
+
+/**
+ * Set a value in an object using a JSON Pointer path
+ */
+function setByPointer(
+  obj: Record<string, unknown>, 
+  pointer: string, 
+  value: unknown
+): void {
+  const keys = parseJsonPointer(pointer);
+  
+  if (keys.length === 0) {
+    // Replace entire object
+    Object.keys(obj).forEach(key => delete obj[key]);
+    Object.assign(obj, value);
+    return;
+  }
+  
+  let current: Record<string, unknown> = obj;
+  
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (!(key in current) || current[key] === null || typeof current[key] !== 'object') {
+      current[key] = {};
+    }
+    current = current[key] as Record<string, unknown>;
+  }
+  
+  current[keys[keys.length - 1]] = value;
+}
+
+/**
+ * Remove a value from an object using a JSON Pointer path
+ */
+function removeByPointer(obj: Record<string, unknown>, pointer: string): void {
+  const keys = parseJsonPointer(pointer);
+  
+  if (keys.length === 0) {
+    Object.keys(obj).forEach(key => delete obj[key]);
+    return;
+  }
+  
+  let current: Record<string, unknown> = obj;
+  
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (!(key in current)) return;
+    current = current[key] as Record<string, unknown>;
+  }
+  
+  delete current[keys[keys.length - 1]];
+}
+
+// =============================================================================
+// Surface Store
+// =============================================================================
+
+/**
+ * SurfaceStore manages the state of all A2UX surfaces.
+ * It provides reactive subscriptions for state changes.
+ */
+export class SurfaceStore {
+  private surfaces: Map<string, Surface> = new Map();
+  private listeners: Map<keyof StoreEventMap, Set<StoreEventHandler<keyof StoreEventMap>>> = new Map();
+  private watchCallbacks: Map<string, () => void> = new Map();
+
+  // ===========================================================================
+  // Surface Management
+  // ===========================================================================
+
+  /**
+   * Create a new surface
+   */
+  createSurface(surfaceId: string, catalogId: string): Surface {
+    const surface: Surface = {
+      surfaceId,
+      catalogId,
+      components: new Map(),
+      dataModel: {},
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+
+    this.surfaces.set(surfaceId, surface);
+    this.emit('surfaceCreated', { surfaceId, catalogId });
+    
+    return surface;
+  }
+
+  /**
+   * Get a surface by ID
+   */
+  getSurface(surfaceId: string): Surface | undefined {
+    return this.surfaces.get(surfaceId);
+  }
+
+  /**
+   * Check if a surface exists
+   */
+  hasSurface(surfaceId: string): boolean {
+    return this.surfaces.has(surfaceId);
+  }
+
+  /**
+   * Get all surface IDs
+   */
+  getSurfaceIds(): string[] {
+    return Array.from(this.surfaces.keys());
+  }
+
+  /**
+   * Delete a surface
+   */
+  deleteSurface(surfaceId: string): boolean {
+    const deleted = this.surfaces.delete(surfaceId);
+    if (deleted) {
+      this.watchCallbacks.delete(surfaceId);
+      this.emit('surfaceDeleted', { surfaceId });
+    }
+    return deleted;
+  }
+
+  /**
+   * Clear all surfaces
+   */
+  clear(): void {
+    const surfaceIds = this.getSurfaceIds();
+    surfaceIds.forEach(id => this.deleteSurface(id));
+  }
+
+  // ===========================================================================
+  // Component Management
+  // ===========================================================================
+
+  /**
+   * Update components in a surface
+   */
+  updateComponents(surfaceId: string, components: A2UXComponent[]): void {
+    const surface = this.surfaces.get(surfaceId);
+    if (!surface) {
+      console.warn(`[SurfaceStore] Surface not found: ${surfaceId}`);
+      return;
+    }
+
+    const updatedIds: string[] = [];
+
+    for (const component of components) {
+      surface.components.set(component.id, component);
+      updatedIds.push(component.id);
+    }
+
+    surface.updatedAt = Date.now();
+    this.emit('componentsUpdated', { surfaceId, componentIds: updatedIds });
+  }
+
+  /**
+   * Get a component by ID
+   */
+  getComponent(surfaceId: string, componentId: string): A2UXComponent | undefined {
+    return this.surfaces.get(surfaceId)?.components.get(componentId);
+  }
+
+  /**
+   * Get all components in a surface
+   */
+  getComponents(surfaceId: string): A2UXComponent[] {
+    const surface = this.surfaces.get(surfaceId);
+    return surface ? Array.from(surface.components.values()) : [];
+  }
+
+  /**
+   * Get the root component of a surface
+   */
+  getRootComponent(surfaceId: string): A2UXComponent | undefined {
+    return this.getComponent(surfaceId, 'root');
+  }
+
+  /**
+   * Build component tree from flat list
+   */
+  getComponentTree(surfaceId: string): A2UXComponent | null {
+    const root = this.getRootComponent(surfaceId);
+    if (!root) return null;
+
+    const buildTree = (component: A2UXComponent): A2UXComponent => {
+      const result = { ...component };
+      
+      if (component.children && Array.isArray(component.children)) {
+        result.children = component.children.map(childId => {
+          const child = this.getComponent(surfaceId, childId as string);
+          return child ? buildTree(child) : childId;
+        }) as unknown as string[];
+      }
+      
+      return result;
+    };
+
+    return buildTree(root);
+  }
+
+  // ===========================================================================
+  // Data Model Management
+  // ===========================================================================
+
+  /**
+   * Update the data model of a surface
+   */
+  updateDataModel(
+    surfaceId: string, 
+    path: string = '/', 
+    op: 'add' | 'replace' | 'remove' = 'replace',
+    value?: unknown
+  ): void {
+    const surface = this.surfaces.get(surfaceId);
+    if (!surface) {
+      console.warn(`[SurfaceStore] Surface not found: ${surfaceId}`);
+      return;
+    }
+
+    switch (op) {
+      case 'add':
+      case 'replace':
+        setByPointer(surface.dataModel, path, value);
+        break;
+      case 'remove':
+        removeByPointer(surface.dataModel, path);
+        break;
+    }
+
+    surface.updatedAt = Date.now();
+    this.emit('dataModelUpdated', { surfaceId, path, value });
+  }
+
+  /**
+   * Get a value from the data model using JSON Pointer
+   */
+  getDataValue(surfaceId: string, path: string): unknown {
+    const surface = this.surfaces.get(surfaceId);
+    if (!surface) return undefined;
+    return getByPointer(surface.dataModel, path);
+  }
+
+  /**
+   * Get the entire data model
+   */
+  getDataModel(surfaceId: string): Record<string, unknown> | undefined {
+    return this.surfaces.get(surfaceId)?.dataModel;
+  }
+
+  /**
+   * Get flattened data model with JSON Pointer paths as keys
+   */
+  getFlatDataModel(surfaceId: string): Record<string, unknown> {
+    const surface = this.surfaces.get(surfaceId);
+    if (!surface) return {};
+
+    const result: Record<string, unknown> = {};
+    
+    const flatten = (obj: Record<string, unknown>, prefix: string = ''): void => {
+      for (const [key, value] of Object.entries(obj)) {
+        const path = `${prefix}/${key}`;
+        
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+          flatten(value as Record<string, unknown>, path);
+        } else {
+          result[path] = value;
+        }
+      }
+    };
+
+    flatten(surface.dataModel);
+    return result;
+  }
+
+  // ===========================================================================
+  // Watch Callbacks
+  // ===========================================================================
+
+  /**
+   * Register a callback for watch responses
+   */
+  setWatchCallback(surfaceId: string, callback: () => void): void {
+    this.watchCallbacks.set(surfaceId, callback);
+  }
+
+  /**
+   * Trigger the watch callback for a surface
+   */
+  triggerWatchCallback(surfaceId: string): void {
+    const callback = this.watchCallbacks.get(surfaceId);
+    if (callback) {
+      callback();
+    }
+
+    // Also emit a watchCallback event with the current state
+    const flatData = this.getFlatDataModel(surfaceId);
+    this.emit('watchCallback', {
+      watchSurfaceResponse: {
+        surfaceId,
+        data: flatData,
+      }
+    });
+  }
+
+  // ===========================================================================
+  // Event Handling
+  // ===========================================================================
+
+  on<K extends keyof StoreEventMap>(
+    event: K, 
+    handler: StoreEventHandler<K>
+  ): () => void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    this.listeners.get(event)!.add(handler as StoreEventHandler<keyof StoreEventMap>);
+    
+    return () => this.off(event, handler);
+  }
+
+  off<K extends keyof StoreEventMap>(
+    event: K, 
+    handler: StoreEventHandler<K>
+  ): void {
+    this.listeners.get(event)?.delete(handler as StoreEventHandler<keyof StoreEventMap>);
+  }
+
+  private emit<K extends keyof StoreEventMap>(event: K, data: StoreEventMap[K]): void {
+    this.listeners.get(event)?.forEach(handler => {
+      try {
+        (handler as StoreEventHandler<K>)(data);
+      } catch (error) {
+        console.error(`Error in store event handler for ${event}:`, error);
+      }
+    });
+  }
+
+  // ===========================================================================
+  // Subscriptions (Reactive)
+  // ===========================================================================
+
+  /**
+   * Subscribe to changes in a specific surface
+   */
+  subscribeSurface(
+    surfaceId: string, 
+    callback: (surface: Surface) => void
+  ): () => void {
+    const unsubComponents = this.on('componentsUpdated', ({ surfaceId: id }) => {
+      if (id === surfaceId) {
+        const surface = this.getSurface(surfaceId);
+        if (surface) callback(surface);
+      }
+    });
+
+    const unsubData = this.on('dataModelUpdated', ({ surfaceId: id }) => {
+      if (id === surfaceId) {
+        const surface = this.getSurface(surfaceId);
+        if (surface) callback(surface);
+      }
+    });
+
+    return () => {
+      unsubComponents();
+      unsubData();
+    };
+  }
+
+  /**
+   * Subscribe to a specific data path in a surface
+   */
+  subscribeData(
+    surfaceId: string, 
+    path: string, 
+    callback: (value: unknown) => void
+  ): () => void {
+    return this.on('dataModelUpdated', ({ surfaceId: id, path: updatedPath }) => {
+      if (id === surfaceId && (updatedPath === path || updatedPath.startsWith(path))) {
+        callback(this.getDataValue(surfaceId, path));
+      }
+    });
+  }
+}