@objectstack/client-react 4.0.2 → 4.0.3

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/client-react@4.0.2 build /home/runner/work/framework/framework/packages/client-react
+> @objectstack/client-react@4.0.3 build /home/runner/work/framework/framework/packages/client-react
 > tsup src/index.tsx --config ../../tsup.config.ts
 
 CLI Building entry: src/index.tsx
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     13.30 KB
-ESM dist/index.mjs.map 38.08 KB
-ESM ⚡️ Build success in 53ms
-CJS dist/index.js     16.10 KB
-CJS dist/index.js.map 38.11 KB
-CJS ⚡️ Build success in 54ms
+CJS dist/index.js     18.71 KB
+CJS dist/index.js.map 45.97 KB
+CJS ⚡️ Build success in 34ms
+ESM dist/index.mjs     15.48 KB
+ESM dist/index.mjs.map 46.02 KB
+ESM ⚡️ Build success in 34ms
 DTS Build start
-DTS ⚡️ Build success in 4192ms
-DTS dist/index.d.mts 12.67 KB
-DTS dist/index.d.ts  12.67 KB
+DTS ⚡️ Build success in 3244ms
+DTS dist/index.d.mts 16.49 KB
+DTS dist/index.d.ts  16.49 KB

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @objectstack/client-react
 
+## 4.0.3
+
+### Patch Changes
+
+- @objectstack/spec@4.0.3
+- @objectstack/core@4.0.3
+- @objectstack/client@4.0.3
+
 ## 4.0.2
 
 ### Patch Changes

package/dist/index.d.mts

@@ -3,6 +3,7 @@ import { ReactNode } from 'react';
 import { ObjectStackClient, PaginatedResult } from '@objectstack/client';
 export { ClientConfig, ObjectStackClient } from '@objectstack/client';
 import { QueryAST, FilterCondition } from '@objectstack/spec/data';
+import { DataEvent, MetadataEvent } from '@objectstack/spec/api';
 
 /**
  * ObjectStack React Context
@@ -423,4 +424,148 @@ declare function useFields(objectName: string, options?: UseMetadataOptions): Us
  */
 declare function useMetadata<T = any>(fetcher: (client: ReturnType<typeof useClient>) => Promise<T>, options?: Omit<UseMetadataOptions, 'useCache' | 'ifNoneMatch' | 'ifModifiedSince'>): UseMetadataResult<T>;
 
-export { ObjectStackContext, ObjectStackProvider, type ObjectStackProviderProps, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMetadataOptions, type UseMetadataResult, type UseMutationOptions, type UseMutationResult, type UsePaginationOptions, type UsePaginationResult, type UseQueryOptions, type UseQueryResult, useClient, useFields, useInfiniteQuery, useMetadata, useMutation, useObject, usePagination, useQuery, useView };
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useMetadataSubscription(type: string, options?: {
+    packageId?: string;
+}): MetadataEvent | null;
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useDataSubscription(object: string, options?: {
+    recordId?: string;
+}): DataEvent | null;
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useMetadataSubscriptionCallback(type: string, callback: (event: MetadataEvent) => void, options?: {
+    packageId?: string;
+}): void;
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useDataSubscriptionCallback(object: string, callback: (event: DataEvent) => void, options?: {
+    recordId?: string;
+}): void;
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+declare function useRealtimeConnection(): boolean;
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useAutoRefresh(object: string, refetch: () => void, options?: {
+    recordId?: string;
+}): void;
+
+export { ObjectStackContext, ObjectStackProvider, type ObjectStackProviderProps, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMetadataOptions, type UseMetadataResult, type UseMutationOptions, type UseMutationResult, type UsePaginationOptions, type UsePaginationResult, type UseQueryOptions, type UseQueryResult, useAutoRefresh, useClient, useDataSubscription, useDataSubscriptionCallback, useFields, useInfiniteQuery, useMetadata, useMetadataSubscription, useMetadataSubscriptionCallback, useMutation, useObject, usePagination, useQuery, useRealtimeConnection, useView };

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { ReactNode } from 'react';
 import { ObjectStackClient, PaginatedResult } from '@objectstack/client';
 export { ClientConfig, ObjectStackClient } from '@objectstack/client';
 import { QueryAST, FilterCondition } from '@objectstack/spec/data';
+import { DataEvent, MetadataEvent } from '@objectstack/spec/api';
 
 /**
  * ObjectStack React Context
@@ -423,4 +424,148 @@ declare function useFields(objectName: string, options?: UseMetadataOptions): Us
  */
 declare function useMetadata<T = any>(fetcher: (client: ReturnType<typeof useClient>) => Promise<T>, options?: Omit<UseMetadataOptions, 'useCache' | 'ifNoneMatch' | 'ifModifiedSince'>): UseMetadataResult<T>;
 
-export { ObjectStackContext, ObjectStackProvider, type ObjectStackProviderProps, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMetadataOptions, type UseMetadataResult, type UseMutationOptions, type UseMutationResult, type UsePaginationOptions, type UsePaginationResult, type UseQueryOptions, type UseQueryResult, useClient, useFields, useInfiniteQuery, useMetadata, useMutation, useObject, usePagination, useQuery, useView };
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useMetadataSubscription(type: string, options?: {
+    packageId?: string;
+}): MetadataEvent | null;
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useDataSubscription(object: string, options?: {
+    recordId?: string;
+}): DataEvent | null;
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useMetadataSubscriptionCallback(type: string, callback: (event: MetadataEvent) => void, options?: {
+    packageId?: string;
+}): void;
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useDataSubscriptionCallback(object: string, callback: (event: DataEvent) => void, options?: {
+    recordId?: string;
+}): void;
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+declare function useRealtimeConnection(): boolean;
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useAutoRefresh(object: string, refetch: () => void, options?: {
+    recordId?: string;
+}): void;
+
+export { ObjectStackContext, ObjectStackProvider, type ObjectStackProviderProps, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMetadataOptions, type UseMetadataResult, type UseMutationOptions, type UseMutationResult, type UsePaginationOptions, type UsePaginationResult, type UseQueryOptions, type UseQueryResult, useAutoRefresh, useClient, useDataSubscription, useDataSubscriptionCallback, useFields, useInfiniteQuery, useMetadata, useMetadataSubscription, useMetadataSubscriptionCallback, useMutation, useObject, usePagination, useQuery, useRealtimeConnection, useView };

package/dist/index.js

@@ -33,14 +33,20 @@ __export(index_exports, {
   ObjectStackClient: () => import_client.ObjectStackClient,
   ObjectStackContext: () => ObjectStackContext,
   ObjectStackProvider: () => ObjectStackProvider,
+  useAutoRefresh: () => useAutoRefresh,
   useClient: () => useClient,
+  useDataSubscription: () => useDataSubscription,
+  useDataSubscriptionCallback: () => useDataSubscriptionCallback,
   useFields: () => useFields,
   useInfiniteQuery: () => useInfiniteQuery,
   useMetadata: () => useMetadata,
+  useMetadataSubscription: () => useMetadataSubscription,
+  useMetadataSubscriptionCallback: () => useMetadataSubscriptionCallback,
   useMutation: () => useMutation,
   useObject: () => useObject,
   usePagination: () => usePagination,
   useQuery: () => useQuery,
+  useRealtimeConnection: () => useRealtimeConnection,
   useView: () => useView
 });
 module.exports = __toCommonJS(index_exports);
@@ -506,6 +512,87 @@ function useMetadata(fetcher, options = {}) {
   };
 }
 
+// src/realtime-hooks.tsx
+var import_react4 = require("react");
+function useMetadataSubscription(type, options) {
+  const client = useClient();
+  const [event, setEvent] = (0, import_react4.useState)(null);
+  (0, import_react4.useEffect)(() => {
+    if (!client) return;
+    const unsubscribe = client.events.subscribeMetadata(
+      type,
+      (e) => setEvent(e),
+      options
+    );
+    return () => {
+      unsubscribe();
+    };
+  }, [client, type, options?.packageId]);
+  return event;
+}
+function useDataSubscription(object, options) {
+  const client = useClient();
+  const [event, setEvent] = (0, import_react4.useState)(null);
+  (0, import_react4.useEffect)(() => {
+    if (!client) return;
+    const unsubscribe = client.events.subscribeData(
+      object,
+      (e) => setEvent(e),
+      options
+    );
+    return () => {
+      unsubscribe();
+    };
+  }, [client, object, options?.recordId]);
+  return event;
+}
+function useMetadataSubscriptionCallback(type, callback, options) {
+  const client = useClient();
+  (0, import_react4.useEffect)(() => {
+    if (!client) return;
+    const unsubscribe = client.events.subscribeMetadata(
+      type,
+      callback,
+      options
+    );
+    return () => {
+      unsubscribe();
+    };
+  }, [client, type, callback, options?.packageId]);
+}
+function useDataSubscriptionCallback(object, callback, options) {
+  const client = useClient();
+  (0, import_react4.useEffect)(() => {
+    if (!client) return;
+    const unsubscribe = client.events.subscribeData(
+      object,
+      callback,
+      options
+    );
+    return () => {
+      unsubscribe();
+    };
+  }, [client, object, callback, options?.recordId]);
+}
+function useRealtimeConnection() {
+  const client = useClient();
+  const [connected, setConnected] = (0, import_react4.useState)(true);
+  (0, import_react4.useEffect)(() => {
+    if (!client) {
+      setConnected(false);
+      return;
+    }
+    setConnected(true);
+  }, [client]);
+  return connected;
+}
+function useAutoRefresh(object, refetch, options) {
+  const handleEvent = (0, import_react4.useCallback)((_event) => {
+    refetch();
+  }, [refetch]);
+  useDataSubscriptionCallback(object, handleEvent, options);
+}
+
 // src/index.tsx
 var import_client = require("@objectstack/client");
 // Annotate the CommonJS export names for ESM import in node:
@@ -513,14 +600,20 @@ var import_client = require("@objectstack/client");
   ObjectStackClient,
   ObjectStackContext,
   ObjectStackProvider,
+  useAutoRefresh,
   useClient,
+  useDataSubscription,
+  useDataSubscriptionCallback,
   useFields,
   useInfiniteQuery,
   useMetadata,
+  useMetadataSubscription,
+  useMetadataSubscriptionCallback,
   useMutation,
   useObject,
   usePagination,
   useQuery,
+  useRealtimeConnection,
   useView
 });
 //# sourceMappingURL=index.js.map