@assistant-ui/core 0.1.0

package/src/store/utils/notification-manager.ts

@@ -0,0 +1,114 @@
+import { resource } from "@assistant-ui/tap";
+import type { ClientStack } from "./tap-client-stack-context";
+import type {
+  AssistantEventName,
+  AssistantEventPayload,
+} from "../types/events";
+import { Unsubscribe } from "../types/client";
+import { tapConst } from "@assistant-ui/tap";
+
+type InternalCallback = (payload: unknown, clientStack: ClientStack) => void;
+
+export type NotificationManager = {
+  on<TEvent extends AssistantEventName>(
+    event: TEvent,
+    callback: (
+      payload: AssistantEventPayload[TEvent],
+      clientStack: ClientStack,
+    ) => void,
+  ): Unsubscribe;
+  emit<TEvent extends Exclude<AssistantEventName, "*">>(
+    event: TEvent,
+    payload: AssistantEventPayload[TEvent],
+    clientStack: ClientStack,
+  ): void;
+  subscribe(callback: () => void): Unsubscribe;
+  notifySubscribers(): void;
+};
+
+export const NotificationManager = resource((): NotificationManager => {
+  return tapConst(() => {
+    const listeners = new Map<string, Set<InternalCallback>>();
+    const wildcardListeners = new Set<InternalCallback>();
+    const subscribers = new Set<() => void>();
+
+    return {
+      on(event, callback) {
+        const cb = callback as InternalCallback;
+        if (event === "*") {
+          wildcardListeners.add(cb);
+          return () => wildcardListeners.delete(cb);
+        }
+
+        let set = listeners.get(event);
+        if (!set) {
+          set = new Set();
+          listeners.set(event, set);
+        }
+        set.add(cb);
+
+        return () => {
+          set!.delete(cb);
+          if (set!.size === 0) listeners.delete(event);
+        };
+      },
+
+      emit(event, payload, clientStack) {
+        const eventListeners = listeners.get(event);
+        if (!eventListeners && wildcardListeners.size === 0) return;
+
+        queueMicrotask(() => {
+          const errors = [];
+          if (eventListeners) {
+            for (const cb of eventListeners) {
+              try {
+                cb(payload, clientStack);
+              } catch (e) {
+                errors.push(e);
+              }
+            }
+          }
+          if (wildcardListeners.size > 0) {
+            const wrapped = { event, payload };
+            for (const cb of wildcardListeners) {
+              try {
+                cb(wrapped, clientStack);
+              } catch (e) {
+                errors.push(e);
+              }
+            }
+          }
+
+          if (errors.length > 0) {
+            if (errors.length === 1) {
+              throw errors[0];
+            } else {
+              for (const error of errors) {
+                console.error(error);
+              }
+              throw new AggregateError(
+                errors,
+                "Errors occurred during event emission",
+              );
+            }
+          }
+        });
+      },
+
+      subscribe(callback) {
+        subscribers.add(callback);
+        return () => subscribers.delete(callback);
+      },
+
+      notifySubscribers() {
+        for (const cb of subscribers) {
+          try {
+            cb();
+          } catch (e) {
+            console.error("NotificationManager: subscriber callback error", e);
+          }
+        }
+      },
+    };
+  }, []);
+});

package/src/store/utils/proxied-assistant-state.ts

@@ -0,0 +1,55 @@
+import { getClientState } from "./tap-client-resource";
+import type { AssistantClient, AssistantState } from "../types/client";
+import {
+  BaseProxyHandler,
+  handleIntrospectionProp,
+} from "./base-proxy-handler";
+
+export const PROXIED_ASSISTANT_STATE_SYMBOL = Symbol(
+  "assistant-ui.store.proxiedAssistantState",
+);
+
+const isIgnoredKey = (key: string | symbol): key is "on" | "subscribe" => {
+  return key === "on" || key === "subscribe" || typeof key === "symbol";
+};
+
+/**
+ * Proxied state that lazily accesses scope states
+ */
+export const createProxiedAssistantState = (
+  client: AssistantClient,
+): AssistantState => {
+  class ProxiedAssistantStateProxyHandler
+    extends BaseProxyHandler
+    implements ProxyHandler<AssistantState>
+  {
+    get(_: unknown, prop: string | symbol) {
+      const introspection = handleIntrospectionProp(prop, "AssistantState");
+      if (introspection !== false) return introspection;
+      const scope = prop as keyof AssistantClient;
+      if (isIgnoredKey(scope)) return undefined;
+      return getClientState(client[scope]());
+    }
+
+    ownKeys(): ArrayLike<string | symbol> {
+      return Object.keys(client).filter((key) => !isIgnoredKey(key));
+    }
+
+    has(_: unknown, prop: string | symbol): boolean {
+      return !isIgnoredKey(prop) && prop in client;
+    }
+  }
+
+  return new Proxy<AssistantState>(
+    {} as AssistantState,
+    new ProxiedAssistantStateProxyHandler(),
+  );
+};
+
+export const getProxiedAssistantState = (
+  client: AssistantClient,
+): AssistantState => {
+  return (
+    client as unknown as { [PROXIED_ASSISTANT_STATE_SYMBOL]: AssistantState }
+  )[PROXIED_ASSISTANT_STATE_SYMBOL];
+};

package/src/store/utils/split-clients.ts

@@ -0,0 +1,82 @@
+import { Derived, DerivedElement } from "./derived";
+import type {
+  AssistantClient,
+  ClientElement,
+  ClientNames,
+} from "../types/client";
+import {
+  getTransformScopes,
+  type ScopesConfig,
+} from "./attach-transform-scopes";
+import { tapMemo } from "@assistant-ui/tap";
+
+export type RootClients = Partial<
+  Record<ClientNames, ClientElement<ClientNames>>
+>;
+export type DerivedClients = Partial<
+  Record<ClientNames, DerivedElement<ClientNames>>
+>;
+
+/**
+ * Splits a clients object into root clients and derived clients,
+ * applying transformScopes from root client elements.
+ */
+function splitClients(clients: ScopesConfig, baseClient: AssistantClient) {
+  // 1. Collect transforms from root elements and run them iteratively
+  let scopes = { ...clients } as Record<
+    string,
+    ClientElement<ClientNames> | DerivedElement<ClientNames>
+  >;
+  const visited = new Set<(...args: any[]) => any>();
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const clientElement of Object.values(scopes)) {
+      if (clientElement.type === (Derived as unknown)) continue;
+      if (visited.has(clientElement.type)) continue;
+      visited.add(clientElement.type);
+
+      const transform = getTransformScopes(clientElement.type);
+      if (transform) {
+        scopes = transform(scopes, baseClient) as typeof scopes;
+        changed = true;
+        break; // restart iteration since scopes may have new root elements
+      }
+    }
+  }
+
+  // 2. Split result into root/derived
+  const rootClients: RootClients = {};
+  const derivedClients: DerivedClients = {};
+
+  for (const [key, clientElement] of Object.entries(scopes) as [
+    ClientNames,
+    ClientElement<ClientNames> | DerivedElement<ClientNames>,
+  ][]) {
+    if (clientElement.type === (Derived as unknown)) {
+      derivedClients[key] = clientElement as DerivedElement<ClientNames>;
+    } else {
+      rootClients[key] = clientElement as ClientElement<ClientNames>;
+    }
+  }
+
+  return { rootClients, derivedClients };
+}
+
+const tapShallowMemoObject = <T extends object>(object: T) => {
+  // biome-ignore lint/correctness/useExhaustiveDependencies: shallow memo
+  return tapMemo(() => object, [...Object.entries(object).flat()]);
+};
+
+export const tapSplitClients = (
+  clients: ScopesConfig,
+  baseClient: AssistantClient,
+) => {
+  const { rootClients, derivedClients } = splitClients(clients, baseClient);
+
+  return {
+    rootClients: tapShallowMemoObject(rootClients),
+    derivedClients: tapShallowMemoObject(derivedClients),
+  };
+};

package/src/store/utils/tap-assistant-context.ts

@@ -0,0 +1,58 @@
+import {
+  createResourceContext,
+  tap,
+  withContextProvider,
+  tapEffectEvent,
+} from "@assistant-ui/tap";
+import type {
+  AssistantEventName,
+  AssistantEventPayload,
+} from "../types/events";
+import type { AssistantClient } from "../types/client";
+import { tapClientStack, type ClientStack } from "./tap-client-stack-context";
+
+type EmitFn = <TEvent extends Exclude<AssistantEventName, "*">>(
+  event: TEvent,
+  payload: AssistantEventPayload[TEvent],
+  clientStack: ClientStack,
+) => void;
+
+export type AssistantTapContextValue = {
+  clientRef: { parent: AssistantClient; current: AssistantClient | null };
+  emit: EmitFn;
+};
+
+const AssistantTapContext =
+  createResourceContext<AssistantTapContextValue | null>(null);
+
+export const withAssistantTapContextProvider = <TResult>(
+  value: AssistantTapContextValue,
+  fn: () => TResult,
+) => {
+  return withContextProvider(AssistantTapContext, value, fn);
+};
+
+const tapAssistantTapContext = () => {
+  const ctx = tap(AssistantTapContext);
+  if (!ctx) throw new Error("AssistantTapContext is not available");
+
+  return ctx;
+};
+
+export const tapAssistantClientRef = () => {
+  return tapAssistantTapContext().clientRef;
+};
+
+export const tapAssistantEmit = () => {
+  const { emit } = tapAssistantTapContext();
+  const clientStack = tapClientStack();
+
+  return tapEffectEvent(
+    <TEvent extends Exclude<AssistantEventName, "*">>(
+      event: TEvent,
+      payload: AssistantEventPayload[TEvent],
+    ) => {
+      emit(event, payload, clientStack);
+    },
+  );
+};

package/src/store/utils/tap-client-list.ts

@@ -0,0 +1,121 @@
+import { tapConst, tapState, withKey } from "@assistant-ui/tap";
+import type { ContravariantResource } from "@assistant-ui/tap";
+import { tapClientLookup } from "./tap-client-lookup";
+import type { ClientMethods } from "../types/client";
+
+type InferClientState<TMethods> = TMethods extends {
+  getState: () => infer S;
+}
+  ? S
+  : unknown;
+
+type DataHandle<TData> = { data: TData | undefined; hasData: boolean };
+
+const createProps = <TData>(
+  key: string,
+  data: DataHandle<TData>,
+  remove: () => void,
+): tapClientList.ResourceProps<TData> => {
+  return {
+    key,
+    getInitialData: () => {
+      if (!data.hasData) {
+        throw new Error(
+          "getInitialData may only be called during initial render",
+        );
+      }
+      return data.data!;
+    },
+    remove,
+  };
+};
+
+export const tapClientList = <TData, TMethods extends ClientMethods>(
+  props: tapClientList.Props<TData, TMethods>,
+): {
+  state: InferClientState<TMethods>[];
+  get: (lookup: { index: number } | { key: string }) => TMethods;
+  add: (initialData: TData) => void;
+} => {
+  const { initialValues, getKey, resource: Resource } = props;
+
+  type Props = tapClientList.ResourceProps<TData>;
+
+  const initialDataHandles: DataHandle<TData>[] = tapConst(() => [], []);
+
+  const [items, setItems] = tapState<Record<string, Props>>(() => {
+    const entries: [string, Props][] = [];
+    for (const data of initialValues) {
+      const key = getKey(data);
+      const handle = { data, hasData: true };
+      entries.push([
+        key,
+        createProps(key, handle, () => {
+          setItems((items) => {
+            const newItems = { ...items };
+            delete newItems[key];
+            return newItems;
+          });
+        }),
+      ]);
+      initialDataHandles.push(handle);
+    }
+    return Object.fromEntries(entries);
+  });
+
+  const lookup = tapClientLookup<TMethods>(
+    () =>
+      Object.values(items).map((props) => withKey(props.key, Resource(props))),
+    [items, Resource],
+  );
+
+  initialDataHandles.forEach((handle) => {
+    handle.data = undefined;
+    handle.hasData = false;
+  });
+
+  const add = (data: TData) => {
+    const key = getKey(data);
+    setItems((items) => {
+      if (key in items) {
+        throw new Error(
+          `Tried to add item with a key ${key} that already exists`,
+        );
+      }
+
+      const handle = { data, hasData: true };
+      initialDataHandles.push(handle);
+
+      return {
+        ...items,
+        [key]: createProps(key, handle, () => {
+          setItems((items) => {
+            const newItems = { ...items };
+            delete newItems[key];
+            return newItems;
+          });
+        }),
+      };
+    });
+  };
+
+  return {
+    state: lookup.state,
+    get: lookup.get,
+    add,
+  };
+};
+
+export namespace tapClientList {
+  export type ResourceProps<TData> = {
+    key: string;
+    getInitialData: () => TData;
+    remove: () => void;
+  };
+
+  export type Props<TData, TMethods extends ClientMethods> = {
+    initialValues: TData[];
+    getKey: (data: TData) => string;
+    resource: ContravariantResource<TMethods, ResourceProps<TData>>;
+  };
+}

package/src/store/utils/tap-client-lookup.ts

@@ -0,0 +1,79 @@
+import {
+  tapMemo,
+  tapResource,
+  tapResources,
+  type ResourceElement,
+} from "@assistant-ui/tap";
+import type { ClientMethods } from "../types/client";
+import { ClientResource } from "./tap-client-resource";
+import { wrapperResource } from "./wrapper-resource";
+
+type InferClientState<TMethods> = TMethods extends {
+  getState: () => infer S;
+}
+  ? S
+  : unknown;
+
+const ClientResourceWithKey = wrapperResource(
+  <TMethods extends ClientMethods>(el: ResourceElement<TMethods>) => {
+    if (el.key === undefined) {
+      throw new Error("tapClientResource: Element has no key");
+    }
+    return tapResource(ClientResource(el)) as {
+      methods: TMethods;
+      state: InferClientState<TMethods>;
+      key: string | number;
+    };
+  },
+);
+
+export function tapClientLookup<TMethods extends ClientMethods>(
+  getElements: () => readonly ResourceElement<TMethods>[],
+  getElementsDeps: readonly unknown[],
+): {
+  state: InferClientState<TMethods>[];
+  get: (lookup: { index: number } | { key: string }) => TMethods;
+} {
+  const resources = tapResources(
+    () => getElements().map((el) => ClientResourceWithKey(el)),
+    // biome-ignore lint/correctness/useExhaustiveDependencies: getElementsDeps is passed through from caller
+    getElementsDeps,
+  );
+
+  const keys = tapMemo(() => Object.keys(resources), [resources]);
+
+  // For arrays, track element key -> index mapping
+  const keyToIndex = tapMemo(() => {
+    return resources.reduce(
+      (acc, resource, index) => {
+        acc[resource.key] = index;
+        return acc;
+      },
+      {} as Record<string, number>,
+    );
+  }, [resources]);
+
+  const state = tapMemo(() => {
+    return resources.map((r) => r.state);
+  }, [resources]);
+
+  return {
+    state,
+    get: (lookup: { index: number } | { key: string }) => {
+      if ("index" in lookup) {
+        if (lookup.index < 0 || lookup.index >= keys.length) {
+          throw new Error(
+            `tapClientLookup: Index ${lookup.index} out of bounds (length: ${keys.length})`,
+          );
+        }
+        return resources[lookup.index]!.methods;
+      }
+
+      const index = keyToIndex[lookup.key];
+      if (index === undefined) {
+        throw new Error(`tapClientLookup: Key "${lookup.key}" not found`);
+      }
+      return resources[index]!.methods;
+    },
+  };
+}

package/src/store/utils/tap-client-resource.ts

@@ -0,0 +1,187 @@
+import {
+  tapEffect,
+  tapMemo,
+  tapRef,
+  type ResourceElement,
+  tapResource,
+} from "@assistant-ui/tap";
+import type { ClientMethods } from "../types/client";
+import {
+  tapClientStack,
+  tapWithClientStack,
+  SYMBOL_CLIENT_INDEX,
+} from "./tap-client-stack-context";
+import {
+  BaseProxyHandler,
+  handleIntrospectionProp,
+} from "./base-proxy-handler";
+import { wrapperResource } from "./wrapper-resource";
+
+/**
+ * Symbol used internally to get state from ClientProxy.
+ * This allows getState() to be optional in the user-facing client.
+ */
+const SYMBOL_GET_OUTPUT = Symbol("assistant-ui.store.getValue");
+
+type ClientInternal = {
+  [SYMBOL_GET_OUTPUT]: ClientMethods;
+};
+
+export const getClientState = (client: ClientMethods) => {
+  const output = (client as unknown as ClientInternal)[SYMBOL_GET_OUTPUT];
+  if (!output) {
+    throw new Error(
+      "Client scope contains a non-client resource. " +
+        "Ensure your Derived get() returns a client created with tapClientResource(), not a plain resource.",
+    );
+  }
+  return (output as any).getState?.();
+};
+
+// Global cache for function templates by field name
+const fieldAccessFns = new Map<
+  string | symbol,
+  (this: unknown, ...args: unknown[]) => unknown
+>();
+
+function getOrCreateProxyFn(prop: string | symbol) {
+  let template = fieldAccessFns.get(prop);
+  if (!template) {
+    template = function (this: unknown, ...args: unknown[]) {
+      if (!this || typeof this !== "object") {
+        throw new Error(
+          `Method "${String(prop)}" called without proper context. ` +
+            `This may indicate the function was called incorrectly.`,
+        );
+      }
+
+      const output = (this as ClientInternal)[SYMBOL_GET_OUTPUT];
+      if (!output) {
+        throw new Error(
+          `Method "${String(prop)}" called on invalid client proxy. ` +
+            `Ensure you are calling this method on a valid client instance.`,
+        );
+      }
+
+      const method = output[prop];
+      if (!method)
+        throw new Error(`Method "${String(prop)}" is not implemented.`);
+      if (typeof method !== "function")
+        throw new Error(`"${String(prop)}" is not a function.`);
+      return method(...args);
+    };
+    fieldAccessFns.set(prop, template);
+  }
+  return template;
+}
+
+class ClientProxyHandler
+  extends BaseProxyHandler
+  implements ProxyHandler<object>
+{
+  private boundFns: Map<string | symbol, Function> | undefined;
+  private cachedReceiver: unknown;
+
+  constructor(
+    private readonly outputRef: {
+      current: ClientMethods;
+    },
+    private readonly index: number,
+  ) {
+    super();
+  }
+
+  get(_: unknown, prop: string | symbol, receiver: unknown) {
+    if (prop === SYMBOL_GET_OUTPUT) return this.outputRef.current;
+    if (prop === SYMBOL_CLIENT_INDEX) return this.index;
+    const introspection = handleIntrospectionProp(prop, "ClientProxy");
+    if (introspection !== false) return introspection;
+    const value = this.outputRef.current[prop];
+    if (typeof value === "function") {
+      if (this.cachedReceiver !== receiver) {
+        this.boundFns = new Map();
+        this.cachedReceiver = receiver;
+      }
+      let bound = this.boundFns!.get(prop);
+      if (!bound) {
+        bound = getOrCreateProxyFn(prop).bind(receiver);
+        this.boundFns!.set(prop, bound);
+      }
+      return bound;
+    }
+    return value;
+  }
+
+  ownKeys(): ArrayLike<string | symbol> {
+    return Object.keys(this.outputRef.current);
+  }
+
+  has(_: unknown, prop: string | symbol) {
+    if (prop === SYMBOL_GET_OUTPUT) return true;
+    if (prop === SYMBOL_CLIENT_INDEX) return true;
+    return prop in this.outputRef.current;
+  }
+}
+
+/**
+ * Resource that wraps a plain resource element to create a stable client proxy.
+ *
+ * Takes a ResourceElement that returns methods (with optional getState()) and
+ * wraps it to produce a stable client proxy. This adds the client to the
+ * client stack, enabling event scoping.
+ *
+ * @internal
+ */
+export const ClientResource = wrapperResource(
+  <TMethods extends ClientMethods>(
+    element: ResourceElement<TMethods>,
+  ): {
+    methods: TMethods;
+    state: unknown;
+    key: string | number | undefined;
+  } => {
+    const valueRef = tapRef(null as unknown as TMethods);
+
+    const index = tapClientStack().length;
+    const methods = tapMemo(
+      () =>
+        new Proxy<TMethods>(
+          {} as TMethods,
+          new ClientProxyHandler(valueRef, index),
+        ),
+      [index],
+    );
+
+    const value = tapWithClientStack(methods, () => tapResource(element));
+    if (!valueRef.current) {
+      valueRef.current = value;
+    }
+
+    tapEffect(() => {
+      valueRef.current = value;
+    });
+
+    const state = (value as any).getState?.();
+    return { methods, state, key: element.key };
+  },
+);
+
+type InferClientState<TMethods> = TMethods extends {
+  getState: () => infer S;
+}
+  ? S
+  : undefined;
+
+export const tapClientResource = <TMethods extends ClientMethods>(
+  element: ResourceElement<TMethods>,
+): {
+  state: InferClientState<TMethods>;
+  methods: TMethods;
+  key: string | number | undefined;
+} => {
+  return tapResource(ClientResource(element)) as {
+    state: InferClientState<TMethods>;
+    methods: TMethods;
+    key: string | number | undefined;
+  };
+};