@assistant-ui/store 0.0.0 → 0.0.2

package/src/types.ts

@@ -1,20 +1,30 @@
 import type { ResourceElement } from "@assistant-ui/tap";
+import type {
+  AssistantEvent,
+  AssistantEventCallback,
+  AssistantEventSelector,
+} from "./EventContext";
+
+type ScopeValueType = Record<string, unknown> & {
+  getState: () => Record<string, unknown>;
+};
+type ScopeMetaType = { source: string; query: Record<string, unknown> };
 
 /**
  * Definition of a scope in the assistant client (internal type)
  * @template TValue - The API type (must include getState() and any actions)
- * @template TSource - The parent scope name (or "root" for top-level scopes)
- * @template TQuery - The query parameters needed to access this scope from its source
+ * @template TMeta - Source/query metadata (use ScopeMeta or discriminated union)
+ * @template TEvents - Optional events that this scope can emit
  * @internal
  */
 export type ScopeDefinition<
-  TValue = any,
-  TSource extends string | "root" = any,
-  TQuery = any,
+  TValue extends ScopeValueType = ScopeValueType,
+  TMeta extends ScopeMetaType = ScopeMetaType,
+  TEvents extends Record<string, unknown> = Record<string, unknown>,
 > = {
   value: TValue;
-  source: TSource;
-  query: TQuery;
+  meta: TMeta;
+  events: TEvents;
 };
 
 /**
@@ -26,58 +36,43 @@ export type ScopeDefinition<
  *   interface AssistantScopeRegistry {
  *     foo: {
  *       value: { getState: () => { bar: string }; updateBar: (bar: string) => void };
- *       source: "root";
- *       query: Record<string, never>;
+ *       meta: { source: "root"; query: Record<string, never> };
+ *       events: {
+ *         "foo.updated": { id: string; newValue: string };
+ *         "foo.deleted": { id: string };
+ *       };
+ *     };
+ *     // Example with multiple sources (discriminated union):
+ *     bar: {
+ *       value: { getState: () => { id: string } };
+ *       meta:
+ *         | { source: "fooList"; query: { index: number } }
+ *         | { source: "barList"; query: { id: string } };
+ *       events: Record<string, never>;
  *     };
  *   }
  * }
  * ```
  */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface AssistantScopeRegistry {}
 
 export type AssistantScopes = keyof AssistantScopeRegistry extends never
   ? Record<"ERROR: No scopes were defined", ScopeDefinition>
   : { [K in keyof AssistantScopeRegistry]: AssistantScopeRegistry[K] };
-
-/**
- * Helper type to extract the value type from a scope definition
- */
-export type ScopeValue<T extends ScopeDefinition> = T["value"];
-
-/**
- * Helper type to extract the source type from a scope definition
- */
-export type ScopeSource<T extends ScopeDefinition> = T["source"];
-
-/**
- * Helper type to extract the query type from a scope definition
- */
-export type ScopeQuery<T extends ScopeDefinition> = T["query"];
-
 /**
  * Type for a scope field - a function that returns the current API value,
- * with source and query metadata attached
+ * with source/query metadata attached (derived from meta)
  */
-export type ScopeField<T extends ScopeDefinition> = (() => ScopeValue<T>) &
-  (
-    | {
-        source: ScopeSource<T>;
-        query: ScopeQuery<T>;
-      }
-    | {
-        source: null;
-        query: null;
-      }
-  );
+export type ScopeField<T extends ScopeDefinition> = (() => T["value"]) &
+  (T["meta"] | { source: null; query: null });
 
 /**
  * Props passed to a derived scope resource element
  */
 export type DerivedScopeProps<T extends ScopeDefinition> = {
-  get: (parent: AssistantClient) => ScopeValue<T>;
-  source: ScopeSource<T>;
-  query: ScopeQuery<T>;
+  get: (parent: AssistantClient) => T["value"];
+  source: T["meta"]["source"];
+  query: T["meta"]["query"];
 };
 
 /**
@@ -85,7 +80,7 @@ export type DerivedScopeProps<T extends ScopeDefinition> = {
  * Can optionally include source/query metadata via DerivedScope
  */
 export type ScopeInput<T extends ScopeDefinition> = ResourceElement<{
-  api: ScopeValue<T>;
+  api: T["value"];
 }>;
 
 /**
@@ -117,4 +112,8 @@ export type AssistantClient = {
 } & {
   subscribe(listener: () => void): Unsubscribe;
   flushSync(): void;
+  on<TEvent extends AssistantEvent>(
+    selector: AssistantEventSelector<TEvent>,
+    callback: AssistantEventCallback<TEvent>,
+  ): Unsubscribe;
 };

package/src/useAssistantClient.tsx

@@ -6,6 +6,7 @@ import {
   tapResource,
   tapResources,
   tapEffectEvent,
+  tapInlineResource,
   ResourceElement,
 } from "@assistant-ui/tap";
 import type {
@@ -19,6 +20,34 @@ import type {
 import { asStore } from "./asStore";
 import { useAssistantContextValue } from "./AssistantContext";
 import { splitScopes } from "./utils/splitScopes";
+import {
+  EventManager,
+  normalizeEventSelector,
+  type AssistantEvent,
+  type AssistantEventCallback,
+  type AssistantEventSelector,
+} from "./EventContext";
+import { withStoreContextProvider } from "./StoreContext";
+
+/**
+ * Resource that renders a store with the store context provider.
+ * This ensures the context is re-established on every re-render.
+ */
+const RootScopeStoreResource = resource(
+  <K extends keyof AssistantScopes>({
+    element,
+    events,
+    parent,
+  }: {
+    element: ScopeInput<AssistantScopes[K]>;
+    events: EventManager;
+    parent: AssistantClient;
+  }) => {
+    return withStoreContextProvider({ events, parent }, () =>
+      tapInlineResource(element),
+    );
+  },
+);
 
 /**
  * Resource for a single root scope
@@ -28,18 +57,24 @@ const RootScopeResource = resource(
   <K extends keyof AssistantScopes>({
     scopeName,
     element,
+    events,
+    parent,
   }: {
     scopeName: K;
     element: ScopeInput<AssistantScopes[K]>;
+    events: EventManager;
+    parent: AssistantClient;
   }) => {
-    const store = tapResource(asStore(element));
+    const store = tapResource(
+      asStore(RootScopeStoreResource({ element, events, parent })),
+    );
 
     return tapMemo(() => {
       const scopeFunction = (() => store.getState().api) as ScopeField<
         AssistantScopes[K]
       >;
       scopeFunction.source = "root";
-      scopeFunction.query = {} as AssistantScopes[K]["query"];
+      scopeFunction.query = {};
 
       return [
         scopeName,
@@ -57,62 +92,81 @@ const RootScopeResource = resource(
  * Resource for all root scopes
  * Mounts each root scope and returns an object mapping scope names to their stores
  */
-const RootScopesResource = resource((scopes: ScopesInput) => {
-  const resultEntries = tapResources(
-    Object.entries(scopes).map(([scopeName, element]) =>
-      RootScopeResource(
-        {
-          scopeName: scopeName as keyof AssistantScopes,
-          element: element as ScopeInput<
-            AssistantScopes[keyof AssistantScopes]
-          >,
-        },
-        { key: scopeName },
+const RootScopesResource = resource(
+  ({ scopes, parent }: { scopes: ScopesInput; parent: AssistantClient }) => {
+    const events = tapInlineResource(EventManager());
+
+    const resultEntries = tapResources(
+      Object.entries(scopes).map(([scopeName, element]) =>
+        RootScopeResource(
+          {
+            scopeName: scopeName as keyof AssistantScopes,
+            element: element as ScopeInput<
+              AssistantScopes[keyof AssistantScopes]
+            >,
+            events,
+            parent,
+          },
+          { key: scopeName },
+        ),
       ),
-    ),
-  );
+    );
 
-  return tapMemo(() => {
-    if (resultEntries.length === 0) {
-      return {
-        scopes: {},
-      };
-    }
+    const on = <TEvent extends AssistantEvent>(
+      selector: AssistantEventSelector<TEvent>,
+      callback: AssistantEventCallback<TEvent>,
+    ) => {
+      const { event } = normalizeEventSelector(selector);
+      return events.on(event, callback);
+    };
 
-    return {
-      scopes: Object.fromEntries(
-        resultEntries.map(([scopeName, { scopeFunction }]) => [
-          scopeName,
-          scopeFunction,
-        ]),
-      ) as {
-        [K in keyof typeof scopes]: ScopeField<AssistantScopes[K]>;
-      },
-      subscribe: (callback: () => void) => {
-        const unsubscribes = resultEntries.map(([, { subscribe }]) => {
-          return subscribe(() => {
-            console.log("Callback called for");
-            callback();
-          });
-        });
-        return () => {
-          unsubscribes.forEach((unsubscribe) => unsubscribe());
+    return tapMemo(() => {
+      if (resultEntries.length === 0) {
+        return {
+          scopes: {},
+          on,
         };
-      },
-      flushSync: () => {
-        resultEntries.forEach(([, { flushSync }]) => {
-          flushSync();
-        });
-      },
-    };
-  }, [...resultEntries]);
-});
+      }
+
+      return {
+        scopes: Object.fromEntries(
+          resultEntries.map(([scopeName, { scopeFunction }]) => [
+            scopeName,
+            scopeFunction,
+          ]),
+        ) as {
+          [K in keyof typeof scopes]: ScopeField<AssistantScopes[K]>;
+        },
+        subscribe: (callback: () => void) => {
+          const unsubscribes = resultEntries.map(([, { subscribe }]) => {
+            return subscribe(() => {
+              console.log("Callback called for");
+              callback();
+            });
+          });
+          return () => {
+            unsubscribes.forEach((unsubscribe) => unsubscribe());
+          };
+        },
+        flushSync: () => {
+          resultEntries.forEach(([, { flushSync }]) => {
+            flushSync();
+          });
+        },
+        on,
+      };
+    }, [...resultEntries, events]);
+  },
+);
 
 /**
  * Hook to mount and access root scopes
  */
-export const useRootScopes = (rootScopes: ScopesInput) => {
-  return useResource(RootScopesResource(rootScopes));
+export const useRootScopes = (
+  rootScopes: ScopesInput,
+  parent: AssistantClient,
+) => {
+  return useResource(RootScopesResource({ scopes: rootScopes, parent }));
 };
 
 /**
@@ -201,7 +255,7 @@ const useExtendedAssistantClientImpl = (
   const { rootScopes, derivedScopes } = splitScopes(scopes);
 
   // Mount the scopes to keep them alive
-  const rootFields = useRootScopes(rootScopes);
+  const rootFields = useRootScopes(rootScopes, baseClient);
   const derivedFields = useDerivedScopes(derivedScopes, baseClient);
 
   return useMemo(() => {
@@ -213,6 +267,7 @@ const useExtendedAssistantClientImpl = (
       ...derivedFields,
       subscribe: rootFields.subscribe ?? baseClient.subscribe,
       flushSync: rootFields.flushSync ?? baseClient.flushSync,
+      on: rootFields.on ?? baseClient.on,
     } as AssistantClient;
   }, [baseClient, rootFields, derivedFields]);
 };
@@ -241,10 +296,8 @@ export function useAssistantClient(): AssistantClient;
 export function useAssistantClient(scopes: ScopesInput): AssistantClient;
 export function useAssistantClient(scopes?: ScopesInput): AssistantClient {
   if (scopes) {
-    // eslint-disable-next-line react-hooks/rules-of-hooks
     return useExtendedAssistantClientImpl(scopes);
   } else {
-    // eslint-disable-next-line react-hooks/rules-of-hooks
     return useAssistantContextValue();
   }
 }

package/src/useAssistantEvent.ts

@@ -0,0 +1,22 @@
+import { useEffect, useEffectEvent } from "react";
+import { useAssistantClient } from "./useAssistantClient";
+import type {
+  AssistantEvent,
+  AssistantEventCallback,
+  AssistantEventSelector,
+} from "./EventContext";
+import { normalizeEventSelector } from "./EventContext";
+
+export const useAssistantEvent = <TEvent extends AssistantEvent>(
+  selector: AssistantEventSelector<TEvent>,
+  callback: AssistantEventCallback<TEvent>,
+) => {
+  const client = useAssistantClient();
+  const callbackRef = useEffectEvent(callback);
+
+  const { scope, event } = normalizeEventSelector(selector);
+  useEffect(
+    () => client.on({ scope, event }, callbackRef),
+    [client, scope, event],
+  );
+};