@objectstack/client-react 4.0.4 → 4.1.0

package/src/metadata-hooks.tsx

@@ -1,314 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Metadata Hooks
- * 
- * React hooks for accessing ObjectStack metadata (schemas, views, fields)
- */
-
-import { useState, useEffect, useCallback } from 'react';
-import { useClient } from './context';
-
-/**
- * Metadata query options
- */
-export interface UseMetadataOptions {
-  /** Enable/disable automatic query execution */
-  enabled?: boolean;
-  /** Use cached metadata if available */
-  useCache?: boolean;
-  /** ETag for conditional requests */
-  ifNoneMatch?: string;
-  /** If-Modified-Since header for conditional requests */
-  ifModifiedSince?: string;
-  /** Callback on successful query */
-  onSuccess?: (data: any) => void;
-  /** Callback on error */
-  onError?: (error: Error) => void;
-}
-
-/**
- * Metadata query result
- */
-export interface UseMetadataResult<T = any> {
-  /** Metadata data */
-  data: T | null;
-  /** Loading state */
-  isLoading: boolean;
-  /** Error state */
-  error: Error | null;
-  /** Refetch the metadata */
-  refetch: () => Promise<void>;
-  /** ETag from last fetch */
-  etag?: string;
-  /** Whether data came from cache (304 Not Modified) */
-  fromCache: boolean;
-}
-
-/**
- * Hook for fetching object schema/metadata
- * 
- * @example
- * ```tsx
- * function ObjectSchemaViewer({ objectName }: { objectName: string }) {
- *   const { data: schema, isLoading, error } = useObject(objectName);
- * 
- *   if (isLoading) return <div>Loading schema...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- * 
- *   return (
- *     <div>
- *       <h2>{schema.label}</h2>
- *       <p>Fields: {Object.keys(schema.fields).length}</p>
- *     </div>
- *   );
- * }
- * ```
- */
-export function useObject(
-  objectName: string,
-  options: UseMetadataOptions = {}
-): UseMetadataResult {
-  const client = useClient();
-  const [data, setData] = useState<any>(null);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const [etag, setEtag] = useState<string>();
-  const [fromCache, setFromCache] = useState(false);
-
-  const {
-    enabled = true,
-    useCache = true,
-    ifNoneMatch,
-    ifModifiedSince,
-    onSuccess,
-    onError
-  } = options;
-
-  const fetchMetadata = useCallback(async () => {
-    if (!enabled) return;
-
-    try {
-      setIsLoading(true);
-      setError(null);
-      setFromCache(false);
-
-      if (useCache) {
-        // Use cached metadata endpoint
-        const result = await client.meta.getCached(objectName, {
-          ifNoneMatch: ifNoneMatch || etag,
-          ifModifiedSince
-        });
-
-        if (result.notModified) {
-          setFromCache(true);
-        } else {
-          setData(result.data);
-          if (result.etag) {
-            setEtag(result.etag.value);
-          }
-        }
-
-        onSuccess?.(result.data || data);
-      } else {
-        // Direct fetch without cache
-        const result = await client.meta.getItem('object', objectName);
-        setData(result);
-        onSuccess?.(result);
-      }
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error('Failed to fetch object metadata');
-      setError(error);
-      onError?.(error);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [client, objectName, enabled, useCache, ifNoneMatch, ifModifiedSince, etag, data, onSuccess, onError]);
-
-  useEffect(() => {
-    fetchMetadata();
-  }, [fetchMetadata]);
-
-  const refetch = useCallback(async () => {
-    await fetchMetadata();
-  }, [fetchMetadata]);
-
-  return {
-    data,
-    isLoading,
-    error,
-    refetch,
-    etag,
-    fromCache
-  };
-}
-
-/**
- * Hook for fetching view configuration
- * 
- * @example
- * ```tsx
- * function ViewConfiguration({ objectName }: { objectName: string }) {
- *   const { data: view, isLoading } = useView(objectName, 'list');
- * 
- *   if (isLoading) return <div>Loading view...</div>;
- * 
- *   return (
- *     <div>
- *       <h3>List View for {objectName}</h3>
- *       <p>Columns: {view?.columns?.length}</p>
- *     </div>
- *   );
- * }
- * ```
- */
-export function useView(
-  objectName: string,
-  viewType: 'list' | 'form' = 'list',
-  options: UseMetadataOptions = {}
-): UseMetadataResult {
-  const client = useClient();
-  const [data, setData] = useState<any>(null);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  const { enabled = true, onSuccess, onError } = options;
-
-  const fetchView = useCallback(async () => {
-    if (!enabled) return;
-
-    try {
-      setIsLoading(true);
-      setError(null);
-
-      const result = await client.meta.getView(objectName, viewType);
-      setData(result);
-      onSuccess?.(result);
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error('Failed to fetch view configuration');
-      setError(error);
-      onError?.(error);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [client, objectName, viewType, enabled, onSuccess, onError]);
-
-  useEffect(() => {
-    fetchView();
-  }, [fetchView]);
-
-  const refetch = useCallback(async () => {
-    await fetchView();
-  }, [fetchView]);
-
-  return {
-    data,
-    isLoading,
-    error,
-    refetch,
-    fromCache: false
-  };
-}
-
-/**
- * Hook for extracting fields from object schema
- * 
- * @example
- * ```tsx
- * function FieldList({ objectName }: { objectName: string }) {
- *   const { data: fields, isLoading } = useFields(objectName);
- * 
- *   if (isLoading) return <div>Loading fields...</div>;
- * 
- *   return (
- *     <ul>
- *       {fields?.map(field => (
- *         <li key={field.name}>{field.label} ({field.type})</li>
- *       ))}
- *     </ul>
- *   );
- * }
- * ```
- */
-export function useFields(
-  objectName: string,
-  options: UseMetadataOptions = {}
-): UseMetadataResult<any[]> {
-  const objectResult = useObject(objectName, options);
-
-  const fields = objectResult.data?.fields
-    ? Object.entries(objectResult.data.fields).map(([name, field]: [string, any]) => ({
-        name,
-        ...field
-      }))
-    : null;
-
-  return {
-    ...objectResult,
-    data: fields
-  };
-}
-
-/**
- * Generic metadata hook for custom metadata queries
- * 
- * @example
- * ```tsx
- * function CustomMetadata() {
- *   const { data, isLoading } = useMetadata(async (client) => {
- *     // Custom metadata fetching logic
- *     const object = await client.meta.getObject('custom_object');
- *     const view = await client.meta.getView('custom_object', 'list');
- *     return { object, view };
- *   });
- * 
- *   return <pre>{JSON.stringify(data, null, 2)}</pre>;
- * }
- * ```
- */
-export function useMetadata<T = any>(
-  fetcher: (client: ReturnType<typeof useClient>) => Promise<T>,
-  options: Omit<UseMetadataOptions, 'useCache' | 'ifNoneMatch' | 'ifModifiedSince'> = {}
-): UseMetadataResult<T> {
-  const client = useClient();
-  const [data, setData] = useState<T | null>(null);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  const { enabled = true, onSuccess, onError } = options;
-
-  const fetchMetadata = useCallback(async () => {
-    if (!enabled) return;
-
-    try {
-      setIsLoading(true);
-      setError(null);
-
-      const result = await fetcher(client);
-      setData(result);
-      onSuccess?.(result);
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error('Failed to fetch metadata');
-      setError(error);
-      onError?.(error);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [client, fetcher, enabled, onSuccess, onError]);
-
-  useEffect(() => {
-    fetchMetadata();
-  }, [fetchMetadata]);
-
-  const refetch = useCallback(async () => {
-    await fetchMetadata();
-  }, [fetchMetadata]);
-
-  return {
-    data,
-    isLoading,
-    error,
-    refetch,
-    fromCache: false
-  };
-}

package/src/realtime-hooks.tsx

@@ -1,262 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Real-time Event Subscription Hooks
- *
- * Provides React hooks for subscribing to metadata and data events.
- * Events are automatically cleaned up when components unmount.
- */
-
-import { useEffect, useState, useCallback } from 'react';
-import type { MetadataEvent, DataEvent } from '@objectstack/spec/api';
-import { useClient } from './context';
-
-/**
- * Hook to subscribe to metadata events
- *
- * @param type - Metadata type to subscribe to (e.g., 'object', 'view', 'agent')
- * @param options - Optional filters (packageId)
- * @returns Latest metadata event or null
- *
- * @example
- * ```tsx
- * function ObjectList() {
- *   const event = useMetadataSubscription('object');
- *
- *   useEffect(() => {
- *     if (event?.type === 'metadata.object.created') {
- *       console.log('New object:', event.name);
- *       // Refresh list
- *     }
- *   }, [event]);
- *
- *   return <div>...</div>;
- * }
- * ```
- */
-export function useMetadataSubscription(
-  type: string,
-  options?: { packageId?: string }
-): MetadataEvent | null {
-  const client = useClient();
-  const [event, setEvent] = useState<MetadataEvent | null>(null);
-
-  useEffect(() => {
-    if (!client) return;
-
-    const unsubscribe = client.events.subscribeMetadata(
-      type,
-      (e) => setEvent(e),
-      options
-    );
-
-    return () => {
-      unsubscribe();
-    };
-  }, [client, type, options?.packageId]);
-
-  return event;
-}
-
-/**
- * Hook to subscribe to data record events
- *
- * @param object - Object name to subscribe to
- * @param options - Optional filters (recordId for specific record)
- * @returns Latest data event or null
- *
- * @example
- * ```tsx
- * function TaskDetail({ taskId }: { taskId: string }) {
- *   const event = useDataSubscription('project_task', { recordId: taskId });
- *
- *   useEffect(() => {
- *     if (event?.type === 'data.record.updated') {
- *       console.log('Task updated:', event.changes);
- *       // Refresh task data
- *     }
- *   }, [event]);
- *
- *   return <div>...</div>;
- * }
- * ```
- */
-export function useDataSubscription(
-  object: string,
-  options?: { recordId?: string }
-): DataEvent | null {
-  const client = useClient();
-  const [event, setEvent] = useState<DataEvent | null>(null);
-
-  useEffect(() => {
-    if (!client) return;
-
-    const unsubscribe = client.events.subscribeData(
-      object,
-      (e) => setEvent(e),
-      options
-    );
-
-    return () => {
-      unsubscribe();
-    };
-  }, [client, object, options?.recordId]);
-
-  return event;
-}
-
-/**
- * Hook to subscribe to metadata events with a callback
- *
- * This variant doesn't store events in state, it just triggers a callback.
- * Useful for triggering refetches or side effects without re-renders.
- *
- * @param type - Metadata type to subscribe to
- * @param callback - Callback to invoke on events
- * @param options - Optional filters
- *
- * @example
- * ```tsx
- * function ObjectList() {
- *   const { refetch } = useQuery(...);
- *
- *   useMetadataSubscriptionCallback('object', () => {
- *     refetch(); // Refetch list when objects change
- *   });
- *
- *   return <div>...</div>;
- * }
- * ```
- */
-export function useMetadataSubscriptionCallback(
-  type: string,
-  callback: (event: MetadataEvent) => void,
-  options?: { packageId?: string }
-): void {
-  const client = useClient();
-
-  useEffect(() => {
-    if (!client) return;
-
-    const unsubscribe = client.events.subscribeMetadata(
-      type,
-      callback,
-      options
-    );
-
-    return () => {
-      unsubscribe();
-    };
-  }, [client, type, callback, options?.packageId]);
-}
-
-/**
- * Hook to subscribe to data events with a callback
- *
- * @param object - Object name to subscribe to
- * @param callback - Callback to invoke on events
- * @param options - Optional filters
- *
- * @example
- * ```tsx
- * function TaskList() {
- *   const { refetch } = useQuery(...);
- *
- *   useDataSubscriptionCallback('project_task', () => {
- *     refetch(); // Refetch list when tasks change
- *   });
- *
- *   return <div>...</div>;
- * }
- * ```
- */
-export function useDataSubscriptionCallback(
-  object: string,
-  callback: (event: DataEvent) => void,
-  options?: { recordId?: string }
-): void {
-  const client = useClient();
-
-  useEffect(() => {
-    if (!client) return;
-
-    const unsubscribe = client.events.subscribeData(
-      object,
-      callback,
-      options
-    );
-
-    return () => {
-      unsubscribe();
-    };
-  }, [client, object, callback, options?.recordId]);
-}
-
-/**
- * Hook to get connection status of realtime events
- *
- * @returns Whether realtime is connected
- *
- * @example
- * ```tsx
- * function ConnectionIndicator() {
- *   const connected = useRealtimeConnection();
- *
- *   return (
- *     <div>
- *       {connected ? '🟢 Connected' : '🔴 Disconnected'}
- *     </div>
- *   );
- * }
- * ```
- */
-export function useRealtimeConnection(): boolean {
-  const client = useClient();
-  const [connected, setConnected] = useState(true);
-
-  useEffect(() => {
-    if (!client) {
-      setConnected(false);
-      return;
-    }
-
-    // For now, assume always connected with in-memory adapter
-    // In production, this would listen to WebSocket connection events
-    setConnected(true);
-  }, [client]);
-
-  return connected;
-}
-
-/**
- * Hook for auto-refreshing queries when data changes
- *
- * Combines data subscription with query refetch.
- *
- * @param object - Object name to watch
- * @param refetch - Refetch function from useQuery
- * @param options - Optional filters
- *
- * @example
- * ```tsx
- * function TaskList() {
- *   const { data, refetch } = useQuery('project_task', {});
- *
- *   useAutoRefresh('project_task', refetch);
- *
- *   return <div>{data.map(...)}</div>;
- * }
- * ```
- */
-export function useAutoRefresh(
-  object: string,
-  refetch: () => void,
-  options?: { recordId?: string }
-): void {
-  const handleEvent = useCallback((_event: DataEvent) => {
-    // Refetch on any data change
-    refetch();
-  }, [refetch]);
-
-  useDataSubscriptionCallback(object, handleEvent, options);
-}

package/tsconfig.json

@@ -1,14 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "declaration": true,
-    "declarationMap": true,
-    "jsx": "react",
-    "lib": ["ES2020", "DOM", "DOM.Iterable"],
-    "types": ["node", "react"]
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.test.ts"]
-}