@object-ui/data-objectstack 17.3.0 → 17.6.0

package/src/cache/MetadataCache.ts

@@ -1,289 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-/**
- * Represents a cached schema entry with metadata
- */
-interface CachedSchema {
-  data: unknown;
-  timestamp: number;
-  accessCount: number;
-  lastAccessed: number;
-}
-
-/**
- * Statistics reported by {@link MetadataCache.getStats} for monitoring.
- *
- * NOT the spec's `CacheStats` (`@objectstack/spec/contracts`), whose name this
- * interface wore until objectui#3160 (objectstack#4115 ledger batch 6). That one
- * describes the platform's `ICacheService` — a server-side KV cache measured by
- * `keyCount` and `memoryUsage`. This one describes the browser-side LRU in front
- * of `/api/v1/meta/*`: it is bounded (`size`/`maxSize`), it evicts, it coalesces
- * concurrent fetches onto one in-flight promise, and it reports a `hitRate`.
- * Neither type has a key the other has, so this is a name collision, not a
- * dialect — deriving would have replaced every field.
- */
-export interface MetadataCacheStats {
-  size: number;
-  maxSize: number;
-  hits: number;
-  misses: number;
-  evictions: number;
-  /** Number of concurrent fetches that were coalesced onto an in-flight request. */
-  coalesced: number;
-  hitRate: number;
-}
-
-/**
- * MetadataCache - LRU cache with TTL expiration for schema metadata
- * 
- * Features:
- * - LRU (Least Recently Used) eviction policy
- * - TTL (Time To Live) based expiration (fixed from creation, not sliding)
- * - Memory limit controls
- * - Async-safe operations
- * - Performance statistics tracking
- * 
- * Concurrent requests for the same uncached key are deduplicated via an
- * internal in-flight Promise map: only the first call invokes the fetcher,
- * and subsequent callers receive the same Promise.
- * 
- * @example
- * ```typescript
- * const cache = new MetadataCache({ maxSize: 100, ttl: 300000 });
- * 
- * const schema = await cache.get('users', async () => {
- *   return await fetchSchemaFromServer('users');
- * });
- * 
- * console.log(cache.getStats());
- * ```
- */
-export class MetadataCache {
-  private cache: Map<string, CachedSchema>;
-  private inflight: Map<string, Promise<unknown>>;
-  private maxSize: number;
-  private ttl: number;
-  private stats: {
-    hits: number;
-    misses: number;
-    evictions: number;
-    coalesced: number;
-  };
-
-  /**
-   * Create a new MetadataCache instance
-   * 
-   * @param options - Configuration options
-   * @param options.maxSize - Maximum number of entries (default: 100)
-   * @param options.ttl - Time to live in milliseconds (default: 5 minutes)
-   */
-  constructor(options: { maxSize?: number; ttl?: number } = {}) {
-    this.cache = new Map();
-    this.inflight = new Map();
-    this.maxSize = options.maxSize || 100;
-    this.ttl = options.ttl || 5 * 60 * 1000; // 5 minutes default
-    this.stats = {
-      hits: 0,
-      misses: 0,
-      evictions: 0,
-      coalesced: 0,
-    };
-  }
-
-  /**
-   * Get a value from cache or fetch it using the provided fetcher function
-   * 
-   * @param key - Cache key
-   * @param fetcher - Async function to fetch data if not in cache
-   * @returns Promise resolving to the cached or fetched data
-   */
-  async get<T = unknown>(key: string, fetcher: () => Promise<T>): Promise<T> {
-    const now = Date.now();
-    const cached = this.cache.get(key);
-
-    // Check if cache entry exists and is not expired
-    if (cached) {
-      const age = now - cached.timestamp;
-      
-      if (age < this.ttl) {
-        // Cache hit - update access metadata
-        cached.accessCount++;
-        cached.lastAccessed = now;
-        this.stats.hits++;
-        
-        // Move to end (most recently used) by re-inserting
-        this.cache.delete(key);
-        this.cache.set(key, cached);
-        
-        return cached.data as T;
-      } else {
-        // Expired entry - remove it
-        this.cache.delete(key);
-      }
-    }
-
-    // Cache miss - dedupe concurrent fetches for the same key
-    const existing = this.inflight.get(key);
-    if (existing) {
-      this.stats.coalesced++;
-      return existing as Promise<T>;
-    }
-
-    this.stats.misses++;
-    const promise = (async () => {
-      try {
-        const data = await fetcher();
-        this.set(key, data);
-        return data;
-      } finally {
-        this.inflight.delete(key);
-      }
-    })();
-    this.inflight.set(key, promise as Promise<unknown>);
-    return promise;
-  }
-
-  /**
-   * Prime the cache with a pre-fetched value. Useful when a bulk endpoint
-   * (e.g. list of all object schemas) returns data that would otherwise
-   * be fetched again per item.
-   */
-  prime(key: string, data: unknown): void {
-    this.set(key, data);
-  }
-
-  /**
-   * Set a value in the cache
-   * 
-   * @param key - Cache key
-   * @param data - Data to cache
-   */
-  private set(key: string, data: unknown): void {
-    const now = Date.now();
-
-    // Check if we need to evict entries
-    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
-      this.evictLRU();
-    }
-
-    // Add or update the entry
-    this.cache.set(key, {
-      data,
-      timestamp: now,
-      accessCount: 1,
-      lastAccessed: now,
-    });
-  }
-
-  /**
-   * Evict the least recently used entry
-   */
-  private evictLRU(): void {
-    // The first entry in the Map is the least recently used
-    // (since we move accessed items to the end)
-    const firstKey = this.cache.keys().next().value;
-    
-    if (firstKey !== undefined) {
-      this.cache.delete(firstKey);
-      this.stats.evictions++;
-    }
-  }
-
-  /**
-   * Invalidate a specific cache entry or all entries
-   * 
-   * @param key - Optional key to invalidate. If omitted, invalidates all entries
-   */
-  invalidate(key?: string): void {
-    if (key) {
-      this.cache.delete(key);
-    } else {
-      this.cache.clear();
-    }
-  }
-
-  /**
-   * Clear all cache entries and reset statistics
-   */
-  clear(): void {
-    this.cache.clear();
-    this.inflight.clear();
-    this.stats = {
-      hits: 0,
-      misses: 0,
-      evictions: 0,
-      coalesced: 0,
-    };
-  }
-
-  /**
-   * Get cache statistics
-   * 
-   * @returns Cache statistics including hit rate
-   */
-  getStats(): MetadataCacheStats {
-    const total = this.stats.hits + this.stats.misses;
-    const hitRate = total > 0 ? this.stats.hits / total : 0;
-
-    return {
-      size: this.cache.size,
-      maxSize: this.maxSize,
-      hits: this.stats.hits,
-      misses: this.stats.misses,
-      evictions: this.stats.evictions,
-      coalesced: this.stats.coalesced,
-      hitRate: hitRate,
-    };
-  }
-
-  /**
-   * Get a cached value synchronously without triggering a fetch.
-   * Returns undefined if not in cache or expired.
-   */
-  getCachedSync<V = unknown>(key: string): V | undefined {
-    const entry = this.cache.get(key);
-    if (!entry) return undefined;
-
-    // Check TTL
-    if (this.ttl > 0 && Date.now() - entry.timestamp > this.ttl) {
-      this.cache.delete(key);
-      return undefined;
-    }
-
-    // Update access order for LRU
-    this.cache.delete(key);
-    this.cache.set(key, entry);
-    this.stats.hits++;
-
-    return entry.data as V;
-  }
-
-  /**
-   * Check if a key exists in the cache (and is not expired)
-   * 
-   * @param key - Cache key to check
-   * @returns true if the key exists and is not expired
-   */
-  has(key: string): boolean {
-    const cached = this.cache.get(key);
-    
-    if (!cached) {
-      return false;
-    }
-
-    const age = Date.now() - cached.timestamp;
-    
-    if (age >= this.ttl) {
-      this.cache.delete(key);
-      return false;
-    }
-
-    return true;
-  }
-}

package/src/cloud.ts

@@ -1,109 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-/**
- * Cloud namespace integration for @objectstack/spec v3.0.0
- * Replaces the legacy Hub namespace for cloud deployment, hosting, and marketplace schemas.
- */
-
-export interface CloudDeploymentConfig {
-  /** Target environment */
-  environment: 'development' | 'staging' | 'production';
-  /** Cloud region */
-  region?: string;
-  /** Auto-scaling configuration */
-  scaling?: {
-    minInstances: number;
-    maxInstances: number;
-    targetCPU?: number;
-  };
-  /** Environment variables */
-  envVars?: Record<string, string>;
-}
-
-export interface CloudHostingConfig {
-  /** Custom domain */
-  customDomain?: string;
-  /** SSL configuration */
-  ssl?: {
-    enabled: boolean;
-    autoRenew: boolean;
-  };
-  /** CDN configuration */
-  cdn?: {
-    enabled: boolean;
-    regions?: string[];
-  };
-}
-
-export interface CloudMarketplaceEntry {
-  /** Plugin or app ID */
-  id: string;
-  /** Display name */
-  name: string;
-  /** Description */
-  description: string;
-  /** Version */
-  version: string;
-  /** Author */
-  author: string;
-  /** Category */
-  category: string;
-  /** Tags */
-  tags: string[];
-  /** Rating (1-5) */
-  rating?: number;
-  /** Install count */
-  installCount?: number;
-  /** Price (0 = free) */
-  price?: number;
-}
-
-/**
- * Cloud operations helper for ObjectStack adapter.
- * Provides methods for cloud deployment, hosting, and marketplace operations.
- */
-export class CloudOperations {
-  constructor(private getClient: () => any) {}
-
-  /**
-   * Deploy an application to the cloud.
-   */
-  async deploy(appId: string, config: CloudDeploymentConfig): Promise<{ deploymentId: string; status: string }> {
-    const client = this.getClient();
-    const result = await client.cloud?.deploy?.(appId, config);
-    return result ?? { deploymentId: `deploy-${Date.now()}`, status: 'pending' };
-  }
-
-  /**
-   * Get deployment status.
-   */
-  async getDeploymentStatus(deploymentId: string): Promise<{ status: string; url?: string }> {
-    const client = this.getClient();
-    const result = await client.cloud?.getDeployment?.(deploymentId);
-    return result ?? { status: 'unknown' };
-  }
-
-  /**
-   * Search marketplace entries.
-   */
-  async searchMarketplace(query?: string, category?: string): Promise<CloudMarketplaceEntry[]> {
-    const client = this.getClient();
-    const result = await client.cloud?.marketplace?.search?.({ query, category });
-    return result?.items ?? [];
-  }
-
-  /**
-   * Install a marketplace plugin.
-   */
-  async installPlugin(pluginId: string): Promise<{ success: boolean }> {
-    const client = this.getClient();
-    const result = await client.cloud?.marketplace?.install?.(pluginId);
-    return result ?? { success: false };
-  }
-}

package/src/connection.test.ts

@@ -1,188 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import {
-  ObjectStackAdapter,
-  ConnectionState,
-  ConnectionStateEvent,
-  BatchProgressEvent,
-  clearSharedDiscoveryCache,
-} from './index';
-
-describe('Connection State Monitoring', () => {
-  let adapter: ObjectStackAdapter;
-
-  beforeEach(() => {
-    adapter = new ObjectStackAdapter({
-      baseUrl: 'http://localhost:3000',
-      autoReconnect: false, // Disable auto-reconnect for testing
-    });
-  });
-
-  it('should initialize with disconnected state', () => {
-    expect(adapter.getConnectionState()).toBe('disconnected');
-    expect(adapter.isConnected()).toBe(false);
-  });
-
-  it('should allow subscribing to connection state changes', () => {
-    const listener = vi.fn();
-    const unsubscribe = adapter.onConnectionStateChange(listener);
-
-    expect(typeof unsubscribe).toBe('function');
-    expect(listener).not.toHaveBeenCalled();
-
-    // Cleanup
-    unsubscribe();
-  });
-
-  it('should allow subscribing to batch progress events', () => {
-    const listener = vi.fn();
-    const unsubscribe = adapter.onBatchProgress(listener);
-
-    expect(typeof unsubscribe).toBe('function');
-    expect(listener).not.toHaveBeenCalled();
-
-    // Cleanup
-    unsubscribe();
-  });
-
-  it('should unsubscribe connection state listener', () => {
-    const listener = vi.fn();
-    const unsubscribe = adapter.onConnectionStateChange(listener);
-
-    // Unsubscribe
-    unsubscribe();
-
-    // Listener should not be called after unsubscribe
-    // (We can't easily test this without triggering a connection state change)
-  });
-
-  it('should unsubscribe batch progress listener', () => {
-    const listener = vi.fn();
-    const unsubscribe = adapter.onBatchProgress(listener);
-
-    // Unsubscribe
-    unsubscribe();
-
-    // Listener should not be called after unsubscribe
-  });
-
-  it('should support auto-reconnect configuration', () => {
-    const adapterWithReconnect = new ObjectStackAdapter({
-      baseUrl: 'http://localhost:3000',
-      autoReconnect: true,
-      maxReconnectAttempts: 5,
-      reconnectDelay: 2000,
-    });
-
-    expect(adapterWithReconnect.getConnectionState()).toBe('disconnected');
-  });
-});
-
-describe('Batch Progress Events', () => {
-  let adapter: ObjectStackAdapter;
-
-  beforeEach(() => {
-    adapter = new ObjectStackAdapter({
-      baseUrl: 'http://localhost:3000',
-    });
-  });
-
-  it('should allow subscribing to batch progress', () => {
-    const listener = vi.fn();
-    const unsubscribe = adapter.onBatchProgress(listener);
-
-    expect(typeof unsubscribe).toBe('function');
-
-    // Cleanup
-    unsubscribe();
-  });
-});
-
-describe('getDiscovery', () => {
-  beforeEach(() => {
-    clearSharedDiscoveryCache();
-  });
-
-  it('should return discoveryInfo from the underlying client after connect', async () => {
-    const mockDiscovery = {
-      name: 'test-server',
-      version: '1.0.0',
-      services: {
-        auth: { enabled: false, status: 'unavailable' },
-        data: { enabled: true, status: 'available' },
-      },
-    };
-
-    const fetchImpl = vi.fn(async () =>
-      ({
-        ok: true,
-        json: async () => ({ success: true, data: mockDiscovery }),
-      }) as unknown as Response,
-    );
-
-    const adapter = new ObjectStackAdapter({
-      baseUrl: 'http://localhost:3000',
-      autoReconnect: false,
-      fetch: fetchImpl,
-    });
-
-    await adapter.connect();
-
-    const discovery = await adapter.getDiscovery();
-    expect(discovery).toEqual(mockDiscovery);
-    expect((discovery as any)?.services?.auth?.enabled).toBe(false);
-    expect(fetchImpl).toHaveBeenCalledTimes(1);
-    expect((fetchImpl.mock.calls[0] as unknown as unknown[])[0]).toContain('/api/v1/discovery');
-  });
-
-  it('should return null when connection fails', async () => {
-    const fetchImpl = vi.fn(async () => {
-      throw new Error('Connection failed');
-    });
-
-    const adapter = new ObjectStackAdapter({
-      baseUrl: 'http://localhost:3000',
-      autoReconnect: false,
-      fetch: fetchImpl as any,
-    });
-
-    await expect(adapter.connect()).rejects.toThrow();
-
-    const discovery = await adapter.getDiscovery();
-    expect(discovery).toBeNull();
-  });
-
-  it('should share a single discovery fetch across adapters with the same baseUrl', async () => {
-    const mockDiscovery = { name: 'shared', version: '1.0.0' };
-    const fetchImpl = vi.fn(async () =>
-      ({
-        ok: true,
-        json: async () => ({ success: true, data: mockDiscovery }),
-      }) as unknown as Response,
-    );
-
-    const a1 = new ObjectStackAdapter({
-      baseUrl: 'http://localhost:3000',
-      autoReconnect: false,
-      fetch: fetchImpl,
-    });
-    const a2 = new ObjectStackAdapter({
-      baseUrl: 'http://localhost:3000',
-      autoReconnect: false,
-      fetch: fetchImpl,
-    });
-
-    await Promise.all([a1.connect(), a2.connect()]);
-
-    expect(fetchImpl).toHaveBeenCalledTimes(1);
-    expect(await a1.getDiscovery()).toEqual(mockDiscovery);
-    expect(await a2.getDiscovery()).toEqual(mockDiscovery);
-  });
-});

package/src/contracts.ts

@@ -1,115 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-/**
- * Contracts module integration for @objectstack/spec v3.0.0
- * Provides plugin contract validation and marketplace publishing utilities.
- */
-
-export interface PluginContract {
-  /** Plugin name */
-  name: string;
-  /** Plugin version */
-  version: string;
-  /** Required peer dependencies */
-  peerDependencies?: Record<string, string>;
-  /** Exported component types */
-  exports: PluginExport[];
-  /** Required permissions */
-  permissions?: string[];
-  /** API surface contract */
-  api?: PluginAPIContract;
-}
-
-export interface PluginExport {
-  /** Export name */
-  name: string;
-  /** Export type */
-  type: 'component' | 'hook' | 'utility' | 'provider';
-  /** Description */
-  description?: string;
-}
-
-export interface PluginAPIContract {
-  /** Consumed data sources */
-  dataSources?: string[];
-  /** Required object schemas */
-  requiredSchemas?: string[];
-  /** Event subscriptions */
-  events?: string[];
-}
-
-export interface ContractValidationResult {
-  valid: boolean;
-  errors: ContractValidationError[];
-  warnings: string[];
-}
-
-export interface ContractValidationError {
-  field: string;
-  message: string;
-  code: string;
-}
-
-/**
- * Validate a plugin contract against the ObjectStack spec.
- */
-export function validatePluginContract(contract: PluginContract): ContractValidationResult {
-  const errors: ContractValidationError[] = [];
-  const warnings: string[] = [];
-
-  if (!contract.name || contract.name.trim().length === 0) {
-    errors.push({ field: 'name', message: 'Plugin name is required', code: 'MISSING_NAME' });
-  }
-
-  if (!contract.version || !/^\d+\.\d+\.\d+/.test(contract.version)) {
-    errors.push({ field: 'version', message: 'Valid semver version is required', code: 'INVALID_VERSION' });
-  }
-
-  if (!contract.exports || contract.exports.length === 0) {
-    errors.push({ field: 'exports', message: 'At least one export is required', code: 'NO_EXPORTS' });
-  }
-
-  if (contract.exports) {
-    const validTypes = ['component', 'hook', 'utility', 'provider'];
-    for (const exp of contract.exports) {
-      if (!exp.name) {
-        errors.push({ field: 'exports.name', message: 'Export name is required', code: 'MISSING_EXPORT_NAME' });
-      }
-      if (!validTypes.includes(exp.type)) {
-        errors.push({ field: 'exports.type', message: `Invalid export type: ${exp.type}`, code: 'INVALID_EXPORT_TYPE' });
-      }
-    }
-  }
-
-  if (!contract.permissions || contract.permissions.length === 0) {
-    warnings.push('No permissions declared — plugin will have minimal access');
-  }
-
-  return { valid: errors.length === 0, errors, warnings };
-}
-
-/**
- * Generate a plugin contract manifest for marketplace publishing.
- */
-export function generateContractManifest(contract: PluginContract): Record<string, unknown> {
-  return {
-    $schema: 'https://objectui.org/schemas/plugin-contract-v1.json',
-    name: contract.name,
-    version: contract.version,
-    peerDependencies: contract.peerDependencies ?? {},
-    exports: contract.exports.map(exp => ({
-      name: exp.name,
-      type: exp.type,
-      description: exp.description ?? '',
-    })),
-    permissions: contract.permissions ?? [],
-    api: contract.api ?? {},
-    generatedAt: new Date().toISOString(),
-  };
-}