@assistant-ui/store 0.0.1 → 0.0.3

package/src/attachDefaultPeers.ts

@@ -0,0 +1,78 @@
+import type { ResourceElement } from "@assistant-ui/tap";
+import type { ClientElement, ClientNames } from "./types/client";
+import type { DerivedElement } from "./Derived";
+
+/**
+ * Symbol used to store default peer clients on a resource.
+ */
+const DEFAULT_PEERS = Symbol("assistant-ui.default-peers");
+
+/**
+ * Type for resources that have default peers attached.
+ */
+export type ResourceWithDefaultPeers = {
+  [DEFAULT_PEERS]?: DefaultPeers;
+};
+
+/**
+ * Default peers configuration - can be either root clients or derived clients.
+ */
+export type DefaultPeers = {
+  [K in ClientNames]?: ClientElement<K> | DerivedElement<K>;
+};
+
+/**
+ * Attaches default peer clients to a resource.
+ *
+ * Default peers are only applied if the scope doesn't exist:
+ * - Not defined in parent context
+ * - Not provided by user
+ * - Not already defined by a previous resource's default peers
+ *
+ * First definition wins - no overriding is permitted.
+ *
+ * @param resource - The resource to attach default peers to
+ * @param peers - The default peer clients to attach
+ * @throws Error if a peer key already exists in the resource's default peers
+ *
+ * @example
+ * ```typescript
+ * const ThreadListClient = resource(({ ... }) => { ... });
+ *
+ * attachDefaultPeers(ThreadListClient, {
+ *   // Derived default peers
+ *   thread: Derived({ source: "threads", query: { type: "main" }, get: ... }),
+ *   threadListItem: Derived({ ... }),
+ *   composer: Derived({ getMeta: ..., get: ... }),
+ *
+ *   // Root default peers
+ *   tools: Tools({}),
+ *   modelContext: ModelContext({}),
+ * });
+ * ```
+ */
+export function attachDefaultPeers<
+  T extends (...args: any[]) => ResourceElement<any>,
+>(resource: T, peers: DefaultPeers): void {
+  const resourceWithPeers = resource as T & ResourceWithDefaultPeers;
+  const existing = resourceWithPeers[DEFAULT_PEERS] ?? {};
+
+  for (const key of Object.keys(peers)) {
+    if (key in existing) {
+      throw new Error(
+        `Default peer "${key}" is already attached to this resource`,
+      );
+    }
+  }
+
+  resourceWithPeers[DEFAULT_PEERS] = { ...existing, ...peers };
+}
+
+/**
+ * Gets the default peers attached to a resource, if any.
+ */
+export function getDefaultPeers<
+  T extends (...args: any[]) => ResourceElement<any>,
+>(resource: T): DefaultPeers | undefined {
+  return (resource as T & ResourceWithDefaultPeers)[DEFAULT_PEERS];
+}

package/src/index.ts

@@ -1,31 +1,37 @@
+// hooks
 export { useAssistantClient } from "./useAssistantClient";
 export { useAssistantState } from "./useAssistantState";
-export { AssistantProvider } from "./AssistantContext";
-export type { AssistantScopes, AssistantClient, AssistantState } from "./types";
-export { DerivedScope } from "./DerivedScope";
-export type { ApiObject } from "./tapApi";
-export { tapApi } from "./tapApi";
-export { tapLookupResources } from "./tapLookupResources";
-export { tapStoreList } from "./tapStoreList";
-export type { TapStoreListConfig } from "./tapStoreList";
-export { registerAssistantScope } from "./ScopeRegistry";
+export { useAssistantEvent } from "./useAssistantEvent";
 
-export type { AssistantScopeRegistry } from "./types";
+// components
+export { AssistantIf } from "./AssistantIf";
+export { AssistantProvider } from "./utils/react-assistant-context";
 
-// Events & Store Context
-export { tapStoreContext } from "./StoreContext";
-export type { StoreContextValue } from "./StoreContext";
-export { useAssistantEvent } from "./useAssistantEvent";
-export { normalizeEventSelector, checkEventScope } from "./EventContext";
+// resources
+export { Derived } from "./Derived";
+export { attachDefaultPeers } from "./attachDefaultPeers";
+
+// tap hooks
+export {
+  tapAssistantClientRef,
+  tapAssistantEmit,
+} from "./utils/tap-assistant-context";
+export { tapClientResource } from "./tapClientResource";
+export { tapClientLookup } from "./tapClientLookup";
+export { tapClientList } from "./tapClientList";
+
+// types
 export type {
-  AssistantEvent,
-  AssistantEventRegistry,
-  AssistantEventScopeConfig,
-  AssistantEventMap,
-  AssistantEventScope,
-  AssistantEventSelector,
+  ClientRegistry,
+  ClientOutput,
+  AssistantClient,
+  AssistantState,
+} from "./types/client";
+export type {
+  AssistantEventName,
   AssistantEventCallback,
-  EventSource,
-  SourceByScope,
-  EventManager,
-} from "./EventContext";
+  AssistantEventPayload,
+  AssistantEventSelector,
+  AssistantEventScope,
+} from "./types/events";
+export type { DefaultPeers } from "./attachDefaultPeers";

package/src/tapClientList.ts

@@ -0,0 +1,105 @@
+import { tapState } from "@assistant-ui/tap";
+import type { ContravariantResource } from "@assistant-ui/tap";
+import { tapClientLookup } from "./tapClientLookup";
+import type { ClientMethods, ClientOutputOf } from "./types/client";
+
+const createProps = <TData>(
+  key: string,
+  data: TData,
+  remove: () => void,
+): tapClientList.ResourceProps<TData> => {
+  let initialData: { data: TData } | undefined = { data };
+  return {
+    key,
+    getInitialData: () => {
+      if (!initialData) {
+        throw new Error("getInitialData may only be called once");
+      }
+      const data = initialData.data;
+      initialData = undefined;
+      return data;
+    },
+    remove,
+  };
+};
+
+export const tapClientList = <TData, TState, TMethods extends ClientMethods>(
+  props: tapClientList.Props<TData, TState, TMethods>,
+): {
+  state: TState[];
+  get: (lookup: { index: number } | { key: string }) => TMethods;
+  add: (initialData: TData) => void;
+} => {
+  const { initialValues, getKey, resource: Resource } = props;
+
+  type Props = tapClientList.ResourceProps<TData>;
+
+  const [items, setItems] = tapState<Record<string, Props>>(() => {
+    const entries: [string, Props][] = [];
+    for (const data of initialValues) {
+      const key = getKey(data);
+      entries.push([
+        key,
+        createProps(key, data, () => {
+          setItems((items) => {
+            const newItems = { ...items };
+            delete newItems[key];
+            return newItems;
+          });
+        }),
+      ]);
+    }
+    return Object.fromEntries(entries);
+  });
+
+  const lookup = tapClientLookup<TState, TMethods, Record<string, Props>>(
+    items,
+    Resource,
+    [Resource],
+  );
+
+  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`,
+        );
+      }
+
+      return {
+        ...items,
+        [key]: createProps(key, data, () => {
+          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, TState, TMethods extends ClientMethods> = {
+    initialValues: TData[];
+    getKey: (data: TData) => string;
+    resource: ContravariantResource<
+      ClientOutputOf<TState, TMethods>,
+      ResourceProps<TData>
+    >;
+  };
+}

package/src/tapClientLookup.ts

@@ -0,0 +1,56 @@
+import { ResourceElement, tapMemo, tapResources } from "@assistant-ui/tap";
+import type { ClientMethods, ClientOutputOf } from "./types/client";
+import { ClientResource } from "./tapClientResource";
+
+export const tapClientLookup = <
+  TState,
+  TMethods extends ClientMethods,
+  M extends Record<string | number | symbol, any>,
+>(
+  map: M,
+  getElement: (
+    t: M[keyof M],
+    key: keyof M,
+  ) => ResourceElement<ClientOutputOf<TState, TMethods>>,
+  getElementDeps: any[],
+): {
+  state: TState[];
+  get: (lookup: { index: number } | { key: keyof M }) => TMethods;
+} => {
+  const resources = tapResources(
+    map,
+    (t, key) => ClientResource(getElement(t, key)),
+    getElementDeps,
+  );
+  const keys = tapMemo(() => Object.keys(map) as (keyof M)[], [map]);
+
+  const state = tapMemo(() => {
+    const result = new Array(keys.length);
+    for (let i = 0; i < keys.length; i++) {
+      result[i] = resources[keys[i]!].state;
+    }
+    return result;
+  }, [keys, resources]);
+
+  return {
+    state,
+    get: (lookup: { index: number } | { key: keyof M }) => {
+      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[keys[lookup.index]!]!.methods;
+      }
+
+      const value = resources[lookup.key];
+      if (!value) {
+        throw new Error(
+          `tapClientLookup: Key "${String(lookup.key)}" not found`,
+        );
+      }
+      return value.methods;
+    },
+  };
+};

package/src/tapClientResource.ts

@@ -0,0 +1,152 @@
+import {
+  tapEffect,
+  tapMemo,
+  tapRef,
+  type ResourceElement,
+  tapResource,
+  resource,
+  tapInlineResource,
+} from "@assistant-ui/tap";
+import type { ClientMethods, ClientOutputOf } from "./types/client";
+import {
+  tapClientStack,
+  tapWithClientStack,
+  SYMBOL_CLIENT_INDEX,
+} from "./utils/tap-client-stack-context";
+import {
+  BaseProxyHandler,
+  handleIntrospectionProp,
+} from "./utils/BaseProxyHandler";
+
+/**
+ * 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]: ClientOutputOf<unknown, 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.state;
+};
+
+// Global cache for function templates by field name
+const fieldAccessFns = new Map<
+  string | symbol,
+  (this: ClientInternal, ...args: unknown[]) => unknown
+>();
+
+function getOrCreateProxyFn(prop: string | symbol) {
+  let template = fieldAccessFns.get(prop);
+  if (!template) {
+    template = function (this: ClientInternal | undefined, ...args: unknown[]) {
+      if (!this)
+        throw new Error(
+          `Destructuring the client method "${String(prop)}" is not supported.`,
+        );
+
+      const method = this[SYMBOL_GET_OUTPUT].methods[prop];
+      if (!method)
+        throw new Error(`Method "${String(prop)}" is not implemented.`);
+      return method(...args);
+    };
+    fieldAccessFns.set(prop, template);
+  }
+  return template;
+}
+
+class ClientProxyHandler
+  extends BaseProxyHandler
+  implements ProxyHandler<object>
+{
+  constructor(
+    private readonly outputRef: {
+      current: ClientOutputOf<unknown, ClientMethods>;
+    },
+    private readonly index: number,
+  ) {
+    super();
+  }
+
+  get(_: unknown, prop: string | symbol) {
+    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;
+    return getOrCreateProxyFn(prop);
+  }
+
+  ownKeys(): ArrayLike<string | symbol> {
+    return Object.keys(this.outputRef.current.methods);
+  }
+
+  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.methods;
+  }
+}
+
+/**
+ * Resource that wraps a plain resource element to create a stable client proxy.
+ *
+ * Takes a ResourceElement that returns { state, methods } and
+ * wraps it to produce a stable client proxy. This adds the client to the
+ * client stack, enabling event scoping.
+ *
+ * Use this for 1:1 client mappings where you want event scoping to work correctly.
+ *
+ * @example
+ * ```typescript
+ * const MessageResource = resource(({ messageId }: { messageId: string }) => {
+ *   return tapInlineResource(
+ *     tapClientResource(InnerMessageResource({ messageId }))
+ *   );
+ * });
+ * ```
+ */
+export const ClientResource = resource(
+  <TState, TMethods extends ClientMethods>(
+    element: ResourceElement<ClientOutputOf<TState, TMethods>>,
+  ): ClientOutputOf<TState, TMethods> => {
+    const valueRef = tapRef(
+      null as unknown as ClientOutputOf<TState, TMethods>,
+    );
+
+    const index = tapClientStack().length;
+    const methods = tapMemo(
+      () =>
+        new Proxy<TMethods>(
+          {} as TMethods,
+          new ClientProxyHandler(valueRef, index),
+        ),
+      [],
+    );
+
+    const value = tapWithClientStack(methods, () => tapResource(element));
+    if (!valueRef.current) {
+      valueRef.current = value;
+    }
+
+    tapEffect(() => {
+      valueRef.current = value;
+    });
+
+    return { methods, state: value.state };
+  },
+);
+
+export const tapClientResource = <TState, TMethods extends ClientMethods>(
+  element: ResourceElement<ClientOutputOf<TState, TMethods>>,
+) => {
+  return tapInlineResource(ClientResource(element));
+};

package/src/types/client.ts

@@ -0,0 +1,186 @@
+import type { ResourceElement } from "@assistant-ui/tap";
+import type {
+  AssistantEventName,
+  AssistantEventCallback,
+  AssistantEventSelector,
+} from "./events";
+
+/**
+ * Base type for methods that can be called on a client.
+ */
+export interface ClientMethods {
+  [key: string | symbol]: (...args: any[]) => any;
+}
+
+type ClientMetaType = { source: ClientNames; query: Record<string, unknown> };
+
+/**
+ * Schema of a client in the assistant system (internal type).
+ * @template TState - The state type for this client
+ * @template TMethods - The methods available on this client
+ * @template TMeta - Source/query metadata (optional)
+ * @template TEvents - Events that this client can emit (optional)
+ * @internal
+ */
+export type ClientSchema<
+  TState = unknown,
+  TMethods extends ClientMethods = ClientMethods,
+  TMeta extends ClientMetaType = never,
+  TEvents extends Record<string, unknown> = never,
+> = {
+  state: TState;
+  methods: TMethods;
+  meta?: TMeta;
+  events?: TEvents;
+};
+
+/**
+ * Module augmentation interface for assistant-ui store type extensions.
+ *
+ * @example
+ * ```typescript
+ * declare module "@assistant-ui/store" {
+ *   interface ClientRegistry {
+ *     // Simple client (meta and events are optional)
+ *     foo: {
+ *       state: { bar: string };
+ *       methods: { updateBar: (bar: string) => void };
+ *     };
+ *     // Full client with meta and events
+ *     bar: {
+ *       state: { id: string };
+ *       methods: { update: () => void };
+ *       meta: { source: "fooList"; query: { index: number } };
+ *       events: {
+ *         "bar.updated": { id: string };
+ *       };
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export interface ClientRegistry {}
+
+type ClientEventsType<K extends ClientNames> = Record<
+  `${K}.${string}`,
+  unknown
+>;
+
+type ClientError<E extends string> = {
+  state: E;
+  methods: Record<E, () => E>;
+  meta: { source: ClientNames; query: Record<E, E> };
+  events: Record<`${E}.`, E>;
+};
+
+type ValidateClient<K extends keyof ClientRegistry> =
+  ClientRegistry[K] extends { methods: ClientMethods }
+    ? "meta" extends keyof ClientRegistry[K]
+      ? ClientRegistry[K]["meta"] extends ClientMetaType
+        ? "events" extends keyof ClientRegistry[K]
+          ? ClientRegistry[K]["events"] extends ClientEventsType<K>
+            ? ClientRegistry[K]
+            : ClientError<`ERROR: ${K & string} has invalid events type`>
+          : ClientRegistry[K]
+        : ClientError<`ERROR: ${K & string} has invalid meta type`>
+      : "events" extends keyof ClientRegistry[K]
+        ? ClientRegistry[K]["events"] extends ClientEventsType<K>
+          ? ClientRegistry[K]
+          : ClientError<`ERROR: ${K & string} has invalid events type`>
+        : ClientRegistry[K]
+    : ClientError<`ERROR: ${K & string} has invalid methods type`>;
+
+type ClientSchemas = keyof ClientRegistry extends never
+  ? {
+      "ERROR: No clients were defined": ClientError<"ERROR: No clients were defined">;
+    }
+  : { [K in keyof ClientRegistry]: ValidateClient<K> };
+
+/**
+ * Output type that client resources return with state and methods.
+ *
+ * @example
+ * ```typescript
+ * const FooResource = resource((): ClientResourceOutput<"foo"> => {
+ *   const [state, setState] = tapState({ bar: "hello" });
+ *   return {
+ *     state,
+ *     methods: {
+ *       updateBar: (b) => setState({ bar: b })
+ *     }
+ *   };
+ * });
+ * ```
+ */
+export type ClientOutput<K extends ClientNames> = ClientOutputOf<
+  ClientSchemas[K]["state"],
+  ClientSchemas[K]["methods"] & ClientMethods
+>;
+
+/**
+ * Generic version of ClientResourceOutput for library code.
+ */
+export type ClientOutputOf<TState, TMethods extends ClientMethods> = {
+  state: TState;
+  methods: TMethods;
+};
+
+export type ClientNames = keyof ClientSchemas extends infer U ? U : never;
+
+export type ClientEvents<K extends ClientNames> =
+  "events" extends keyof ClientSchemas[K]
+    ? ClientSchemas[K]["events"] extends ClientEventsType<K>
+      ? ClientSchemas[K]["events"]
+      : never
+    : never;
+
+export type ClientMeta<K extends ClientNames> =
+  "meta" extends keyof ClientSchemas[K]
+    ? Pick<
+        ClientSchemas[K]["meta"] extends ClientMetaType
+          ? ClientSchemas[K]["meta"]
+          : never,
+        "source" | "query"
+      >
+    : never;
+
+export type ClientElement<K extends ClientNames> = ResourceElement<
+  ClientOutput<K>
+>;
+
+/**
+ * Unsubscribe function type.
+ */
+export type Unsubscribe = () => void;
+
+/**
+ * State type extracted from all clients.
+ */
+export type AssistantState = {
+  [K in ClientNames]: ClientSchemas[K]["state"];
+};
+
+/**
+ * Type for a client accessor - a function that returns the methods,
+ * with source/query metadata attached (derived from meta).
+ */
+export type AssistantClientAccessor<K extends ClientNames> =
+  (() => ClientSchemas[K]["methods"]) &
+    (
+      | ClientMeta<K>
+      | { source: "root"; query: Record<string, never> }
+      | { source: null; query: null }
+    );
+
+/**
+ * The assistant client type with all registered clients.
+ */
+export type AssistantClient = {
+  [K in ClientNames]: AssistantClientAccessor<K>;
+} & {
+  subscribe(listener: () => void): Unsubscribe;
+  on<TEvent extends AssistantEventName>(
+    selector: AssistantEventSelector<TEvent>,
+    callback: AssistantEventCallback<TEvent>,
+  ): Unsubscribe;
+};