@object-ui/data-objectstack 17.5.0 → 17.7.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-surface-retired-4152.pin.test.ts

@@ -1,171 +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.
- */
-
-/**
- * The retired cloud surface stays retired — negative pin (objectui#4152).
- *
- * `packages/data-objectstack/src/cloud.ts` exported a `CloudOperations` class
- * and three `Cloud*` types, all re-exported from this package's `index.ts`, so
- * they were published surface of `@object-ui/data-objectstack`. Every one of
- * the class's four methods optional-chained into `client.cloud?.…` — a
- * namespace no released `@objectstack/client` has ever exported (measured again
- * at `17.0.0-rc.6` while removing it: the module exports exactly
- * `ObjectStackClient`, `ScopedProjectClient`, `RealtimeAPI`, `QueryBuilder`,
- * `FilterBuilder`, `createQuery`, `createFilter`, and a constructed instance's
- * `.cloud` is `undefined`) — and then returned a fallback literal:
- *
- * | method | what it returned, always |
- * |:--|:--|
- * | `deploy` | `{ deploymentId: 'deploy-' + Date.now(), status: 'pending' }` |
- * | `getDeploymentStatus` | `{ status: 'unknown' }` |
- * | `searchMarketplace` | `[]` |
- * | `installPlugin` | `{ success: false }` |
- *
- * The maintainer ruling of 2026-08-11 removed it. The reason worth keeping in
- * front of whoever reads this file: `deploy()` did not degrade to an error, it
- * **manufactured a plausible success**. A caller — especially an AI one, which
- * will not get suspicious — received a well-formed `deploymentId` for an
- * operation that never left the process, then polled it forever against
- * `{ status: 'unknown' }`. Fabricated success is banned by that ruling; a stub
- * that must exist for compile compatibility throws instead.
- *
- * ## Why a negative pin, and why it reads BOTH surfaces
- *
- * Nothing else can see this regression. The gates in this repo run from a
- * declaration to its usage; a re-added export has a declaration and no usage,
- * which is exactly the shape that has no alarm on it — the same gap
- * objectui#4145's retirement pin was built for.
- *
- * The two halves are not redundant, because a class and a type do not fail the
- * same way:
- *
- *   - the **runtime** half enumerates `./index`'s bindings, which catches
- *     `CloudOperations` (a class survives to runtime) but is structurally blind
- *     to `CloudDeploymentConfig` and friends, since `export type` erases;
- *   - the **source-text** half reads `index.ts` for the names and for a
- *     re-export of `./cloud`, which is the only instrument that can see a
- *     returning *type*.
- *
- * Drop either one and half the retired surface can come back green.
- *
- * ## Why the source is read through `ts.sys` rather than `node:fs`
- *
- * Inherited from the pin this file replaces: this package's `tsconfig.json`
- * compiles its whole test tree, and keeping `@types/node` out of a browser-side
- * adapter's type environment is deliberate. TypeScript's own system host is
- * typed by the `typescript` devDependency.
- *
- * ## What happened to objectui#3720's pin
- *
- * `cloud-environment-vocabulary.pin.test.ts` pinned the doc comment on
- * `CloudDeploymentConfig.environment` — the deploy-target vocabulary and the
- * `staging` trap. Its subject was deleted here, so it retired with it rather
- * than being re-pointed: every fact it held was a claim ABOUT that comment, and
- * its spec-side assertions (`DiscoveryEnvironmentSchema` / `EnvironmentTypeSchema`
- * member lists) existed only to keep those claims honest — with the comment
- * gone they would pin an upstream library's enums on behalf of no local reader,
- * which is the same phantom shape objectui#4152 is closing. #3720's own
- * conclusion is unaffected and now moot: it found no producer-side deploy-target
- * type to converge onto, because the producer did not exist. This file records
- * the same measurement one step further along.
- *
- * ## If a real cloud API lands
- *
- * Then this pin is what you delete, deliberately, in the PR that binds the new
- * `@objectstack/client` surface — with methods that call it and fail loudly when
- * it is absent. Re-adding the names alone, ahead of a producer, is the thing
- * being prevented.
- */
-
-import { describe, it, expect } from 'vitest';
-import ts from 'typescript';
-
-import * as adapter from './index';
-
-/** Every name the retirement removed from the package's public surface. */
-const RETIRED_EXPORTS = [
-  'CloudOperations',
-  'CloudDeploymentConfig',
-  'CloudHostingConfig',
-  'CloudMarketplaceEntry',
-] as const;
-
-/** This file, as an absolute path — `index.ts` is its sibling. */
-const HERE = new URL(import.meta.url).pathname;
-const INDEX_TS = HERE.replace(/[^/]+$/, 'index.ts');
-const CLOUD_TS = HERE.replace(/[^/]+$/, 'cloud.ts');
-
-function readIndexSource(): string {
-  const raw = ts.sys.readFile(INDEX_TS);
-  if (!raw) throw new Error(`cannot read ${INDEX_TS}`);
-  return raw;
-}
-
-const INDEX_SOURCE = readIndexSource();
-
-describe('the probe itself works', () => {
-  it('read a plausible index.ts', () => {
-    expect(INDEX_SOURCE.length).toBeGreaterThan(1000);
-    expect(INDEX_SOURCE).toContain('export class ObjectStackAdapter');
-  });
-});
-
-describe('the cloud surface is gone from the runtime exports', () => {
-  it.each(RETIRED_EXPORTS)('`%s` is not a runtime binding of the package entry', (name) => {
-    expect(
-      Object.prototype.hasOwnProperty.call(adapter, name),
-      `\`${name}\` is exported from @object-ui/data-objectstack again. It was ` +
-        `retired by objectui#4152 because it optional-chained into a ` +
-        `\`client.cloud\` namespace @objectstack/client does not have, and ` +
-        `returned a fabricated success instead of failing. If a real cloud API ` +
-        `has landed, bind it and delete this pin deliberately — do not restore ` +
-        `the old fallbacks.`,
-    ).toBe(false);
-  });
-
-  it('exports no other `Cloud`-prefixed binding either', () => {
-    const strays = Object.keys(adapter).filter((name) => name.startsWith('Cloud'));
-    expect(
-      strays,
-      `unexpected \`Cloud*\` export(s) on the package entry. objectui#4152 ` +
-        `removed this prefix wholesale; a new one needs a producer behind it.`,
-    ).toEqual([]);
-  });
-});
-
-describe('the cloud surface is gone from the source, types included', () => {
-  it('index.ts re-exports nothing from `./cloud`', () => {
-    expect(
-      /from\s+'\.\/cloud'/.test(INDEX_SOURCE),
-      `index.ts re-exports from './cloud' again (objectui#4152 removed that ` +
-        `module). \`export type\` erases at runtime, so the assertions above ` +
-        `cannot see a returning type — this one is what catches it.`,
-    ).toBe(false);
-  });
-
-  it.each(RETIRED_EXPORTS)('index.ts does not name `%s`', (name) => {
-    // The retirement note left behind in index.ts mentions the family in prose
-    // (`Cloud*Config`), never a retired identifier, so a hit here is a real
-    // re-export rather than the comment.
-    expect(
-      INDEX_SOURCE.includes(name),
-      `index.ts mentions \`${name}\` again. If this is a comment rather than an ` +
-        `export, rewrite the comment — this pin deliberately cannot tell the ` +
-        `difference, because a type export is invisible to every other check.`,
-    ).toBe(false);
-  });
-
-  it('the cloud.ts module itself is gone', () => {
-    expect(
-      ts.sys.fileExists(CLOUD_TS),
-      `${CLOUD_TS} is back. The module header claimed to integrate ` +
-        `"@objectstack/spec v3.0.0" cloud schemas the package never consumed; ` +
-        `objectui#4152 deleted both the claim and the surface.`,
-    ).toBe(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);
-  });
-});