@objectstack/client-react 17.0.0-rc.0 → 17.0.0-rc.2

package/dist/index.d.mts

@@ -3,7 +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';
+import { BulkDataEvent, DataEvent, MetadataEvent } from '@objectstack/spec/api';
 
 /**
  * ObjectStack React Context
@@ -527,6 +527,64 @@ declare function useMetadataSubscriptionCallback(type: string, callback: (event:
 declare function useDataSubscriptionCallback(object: string, callback: (event: DataEvent) => void, options?: {
     recordId?: string;
 }): void;
+/**
+ * Hook to subscribe to bulk (predicate-write) data events
+ *
+ * A `multi: true` update/delete reaches the driver's `updateMany`/`deleteMany`,
+ * which report an affected COUNT and name no rows — so it publishes
+ * `data.records.updated` / `data.records.deleted` rather than the per-record
+ * events {@link useDataSubscription} delivers (#4639).
+ *
+ * The event carries `object` and `matched` — there is no `recordId` and no
+ * record body, which is why this is a separate hook rather than more types
+ * flowing through `useDataSubscription`: a `DataEvent` callback receiving one
+ * of these would read `undefined` for every field it expects.
+ *
+ * Use it to invalidate a list, show "40 records changed", or trigger a
+ * refetch — not to patch a per-record cache, which a count cannot drive.
+ *
+ * @param object - Object name to subscribe to
+ * @returns Latest bulk data event or null
+ *
+ * @example
+ * ```tsx
+ * function TaskList() {
+ *   const bulk = useBulkDataSubscription('project_task');
+ *
+ *   useEffect(() => {
+ *     if (bulk) {
+ *       console.log(`${bulk.matched} tasks changed in one write`);
+ *     }
+ *   }, [bulk]);
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+declare function useBulkDataSubscription(object: string): BulkDataEvent | null;
+/**
+ * Hook to subscribe to bulk data events with a callback
+ *
+ * The callback variant of {@link useBulkDataSubscription} — no state, no
+ * re-render, for triggering refetches and side effects.
+ *
+ * @param object - Object name to subscribe to
+ * @param callback - Callback to invoke on events
+ *
+ * @example
+ * ```tsx
+ * function TaskList() {
+ *   const { refetch } = useQuery(...);
+ *
+ *   useBulkDataSubscriptionCallback('project_task', () => {
+ *     refetch(); // a predicate write touched an unknown set of rows
+ *   });
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+declare function useBulkDataSubscriptionCallback(object: string, callback: (event: BulkDataEvent) => void): void;
 /**
  * Hook to get connection status of realtime events
  *
@@ -551,6 +609,18 @@ declare function useRealtimeConnection(): boolean;
  *
  * Combines data subscription with query refetch.
  *
+ * Watches BOTH event streams (#4678): per-record `data.record.*` writes and
+ * the aggregate `data.records.*` a predicate (`multi: true`) write publishes.
+ * A bulk write is the case that dirties a list hardest — one statement can
+ * change or delete every row on screen — so a refresh hook that ignored it
+ * would sit still exactly when it matters most, while still refreshing for a
+ * single-row edit.
+ *
+ * Mixing the two streams is safe here in a way it is not for
+ * {@link useDataSubscription}: this hook's output is a refetch signal, not an
+ * event body, so the shape difference that keeps the two contracts apart
+ * (no `recordId`, no record) never reaches the caller.
+ *
  * @param object - Object name to watch
  * @param refetch - Refetch function from useQuery
  * @param options - Optional filters
@@ -570,4 +640,4 @@ declare function useAutoRefresh(object: string, refetch: () => void, options?: {
     recordId?: string;
 }): void;
 
-export { ObjectStackContext, ObjectStackLocaleContext, 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, useObjectStackLocale, usePagination, useQuery, useRealtimeConnection, useView };
+export { ObjectStackContext, ObjectStackLocaleContext, ObjectStackProvider, type ObjectStackProviderProps, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMetadataOptions, type UseMetadataResult, type UseMutationOptions, type UseMutationResult, type UsePaginationOptions, type UsePaginationResult, type UseQueryOptions, type UseQueryResult, useAutoRefresh, useBulkDataSubscription, useBulkDataSubscriptionCallback, useClient, useDataSubscription, useDataSubscriptionCallback, useFields, useInfiniteQuery, useMetadata, useMetadataSubscription, useMetadataSubscriptionCallback, useMutation, useObject, useObjectStackLocale, usePagination, useQuery, useRealtimeConnection, useView };

package/dist/index.d.ts

@@ -3,7 +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';
+import { BulkDataEvent, DataEvent, MetadataEvent } from '@objectstack/spec/api';
 
 /**
  * ObjectStack React Context
@@ -527,6 +527,64 @@ declare function useMetadataSubscriptionCallback(type: string, callback: (event:
 declare function useDataSubscriptionCallback(object: string, callback: (event: DataEvent) => void, options?: {
     recordId?: string;
 }): void;
+/**
+ * Hook to subscribe to bulk (predicate-write) data events
+ *
+ * A `multi: true` update/delete reaches the driver's `updateMany`/`deleteMany`,
+ * which report an affected COUNT and name no rows — so it publishes
+ * `data.records.updated` / `data.records.deleted` rather than the per-record
+ * events {@link useDataSubscription} delivers (#4639).
+ *
+ * The event carries `object` and `matched` — there is no `recordId` and no
+ * record body, which is why this is a separate hook rather than more types
+ * flowing through `useDataSubscription`: a `DataEvent` callback receiving one
+ * of these would read `undefined` for every field it expects.
+ *
+ * Use it to invalidate a list, show "40 records changed", or trigger a
+ * refetch — not to patch a per-record cache, which a count cannot drive.
+ *
+ * @param object - Object name to subscribe to
+ * @returns Latest bulk data event or null
+ *
+ * @example
+ * ```tsx
+ * function TaskList() {
+ *   const bulk = useBulkDataSubscription('project_task');
+ *
+ *   useEffect(() => {
+ *     if (bulk) {
+ *       console.log(`${bulk.matched} tasks changed in one write`);
+ *     }
+ *   }, [bulk]);
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+declare function useBulkDataSubscription(object: string): BulkDataEvent | null;
+/**
+ * Hook to subscribe to bulk data events with a callback
+ *
+ * The callback variant of {@link useBulkDataSubscription} — no state, no
+ * re-render, for triggering refetches and side effects.
+ *
+ * @param object - Object name to subscribe to
+ * @param callback - Callback to invoke on events
+ *
+ * @example
+ * ```tsx
+ * function TaskList() {
+ *   const { refetch } = useQuery(...);
+ *
+ *   useBulkDataSubscriptionCallback('project_task', () => {
+ *     refetch(); // a predicate write touched an unknown set of rows
+ *   });
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+declare function useBulkDataSubscriptionCallback(object: string, callback: (event: BulkDataEvent) => void): void;
 /**
  * Hook to get connection status of realtime events
  *
@@ -551,6 +609,18 @@ declare function useRealtimeConnection(): boolean;
  *
  * Combines data subscription with query refetch.
  *
+ * Watches BOTH event streams (#4678): per-record `data.record.*` writes and
+ * the aggregate `data.records.*` a predicate (`multi: true`) write publishes.
+ * A bulk write is the case that dirties a list hardest — one statement can
+ * change or delete every row on screen — so a refresh hook that ignored it
+ * would sit still exactly when it matters most, while still refreshing for a
+ * single-row edit.
+ *
+ * Mixing the two streams is safe here in a way it is not for
+ * {@link useDataSubscription}: this hook's output is a refetch signal, not an
+ * event body, so the shape difference that keeps the two contracts apart
+ * (no `recordId`, no record) never reaches the caller.
+ *
  * @param object - Object name to watch
  * @param refetch - Refetch function from useQuery
  * @param options - Optional filters
@@ -570,4 +640,4 @@ declare function useAutoRefresh(object: string, refetch: () => void, options?: {
     recordId?: string;
 }): void;
 
-export { ObjectStackContext, ObjectStackLocaleContext, 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, useObjectStackLocale, usePagination, useQuery, useRealtimeConnection, useView };
+export { ObjectStackContext, ObjectStackLocaleContext, ObjectStackProvider, type ObjectStackProviderProps, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMetadataOptions, type UseMetadataResult, type UseMutationOptions, type UseMutationResult, type UsePaginationOptions, type UsePaginationResult, type UseQueryOptions, type UseQueryResult, useAutoRefresh, useBulkDataSubscription, useBulkDataSubscriptionCallback, useClient, useDataSubscription, useDataSubscriptionCallback, useFields, useInfiniteQuery, useMetadata, useMetadataSubscription, useMetadataSubscriptionCallback, useMutation, useObject, useObjectStackLocale, usePagination, useQuery, useRealtimeConnection, useView };