@assistant-ui/store 0.0.2 → 0.0.3

package/src/tapApi.ts

@@ -1,91 +0,0 @@
-import { tapEffect, tapMemo, tapRef } from "@assistant-ui/tap";
-
-/**
- * API object type
- */
-export interface ApiObject {
-  [key: string]: ((...args: any[]) => any) | ApiObject;
-}
-
-/**
- * Readonly API handler for creating stable proxies
- */
-class ReadonlyApiHandler<TApi extends ApiObject> implements ProxyHandler<TApi> {
-  constructor(private readonly getApi: () => TApi) {}
-
-  get(_: unknown, prop: string | symbol) {
-    return this.getApi()[prop as keyof TApi];
-  }
-
-  ownKeys(): ArrayLike<string | symbol> {
-    return Object.keys(this.getApi() as object);
-  }
-
-  has(_: unknown, prop: string | symbol) {
-    return prop in (this.getApi() as object);
-  }
-
-  getOwnPropertyDescriptor(_: unknown, prop: string | symbol) {
-    return Object.getOwnPropertyDescriptor(this.getApi(), prop);
-  }
-
-  set() {
-    return false;
-  }
-  defineProperty() {
-    return false;
-  }
-  deleteProperty() {
-    return false;
-  }
-}
-
-/**
- * Wraps an API object to make it stable across renders while keeping getState reactive.
- * This is the recommended pattern for scope resources.
- *
- * @example
- * ```typescript
- * export const FooResource = resource(() => {
- *   const [state, setState] = tapState({ bar: "Hello" });
- *
- *   const updateBar = (newBar: string) => {
- *     setState({ bar: newBar });
- *   };
- *
- *   return tapApi({
- *     getState: () => state,
- *     updateBar,
- *   });
- * });
- * ```
- */
-export const tapApi = <TApi extends ApiObject & { getState: () => any }>(
-  api: TApi,
-  options?: {
-    key?: string | undefined;
-  },
-) => {
-  const ref = tapRef(api);
-  tapEffect(() => {
-    ref.current = api;
-  });
-
-  const apiProxy = tapMemo(
-    () =>
-      new Proxy<TApi>({} as TApi, new ReadonlyApiHandler(() => ref.current)),
-    [],
-  );
-
-  const key = options?.key;
-  const state = api.getState();
-
-  return tapMemo(
-    () => ({
-      key,
-      state,
-      api: apiProxy,
-    }),
-    [state, key],
-  );
-};

package/src/tapLookupResources.ts

@@ -1,62 +0,0 @@
-import { ResourceElement, tapResources } from "@assistant-ui/tap";
-import { ApiObject } from "./tapApi";
-
-/**
- * Creates a lookup-based resource collection for managing lists of items.
- * Returns both the combined state array and an API function to lookup specific items.
- *
- * @param elements - Array of resource elements, each returning { key, state, api }
- * @returns Object with { state: TState[], api: (lookup) => TApi }
- *
- * The api function accepts { index: number } or { key: string } for lookups.
- * Consumers can wrap it to rename the key field (e.g., to "id" or "toolCallId").
- *
- * @example
- * ```typescript
- * const foos = tapLookupResources(
- *   items.map((item) => FooItem({ id: item.id }, { key: item.id }))
- * );
- *
- * // Access state array
- * const allStates = foos.state;
- *
- * // Wrap to rename key field to "id"
- * const wrappedApi = (lookup: { index: number } | { id: string }) => {
- *   if ("id" in lookup) {
- *     return foos.api({ key: lookup.id });
- *   } else {
- *     return foos.api(lookup);
- *   }
- * };
- * ```
- */
-export const tapLookupResources = <TState, TApi extends ApiObject>(
-  elements: ResourceElement<{
-    key: string | undefined;
-    state: TState;
-    api: TApi;
-  }>[],
-): {
-  state: TState[];
-  api: (lookup: { index: number } | { key: string }) => TApi;
-} => {
-  const resources = tapResources(elements);
-
-  return {
-    state: resources.map((r) => r.state),
-    api: (lookup: { index: number } | { key: string }) => {
-      const value =
-        "index" in lookup
-          ? resources[lookup.index]?.api
-          : resources.find((r) => r.key === lookup.key)?.api;
-
-      if (!value) {
-        throw new Error(
-          `tapLookupResources: Resource not found for lookup: ${JSON.stringify(lookup)}`,
-        );
-      }
-
-      return value;
-    },
-  };
-};

package/src/tapStoreList.ts

@@ -1,133 +0,0 @@
-import { tapState } from "@assistant-ui/tap";
-import type { ContravariantResource } from "@assistant-ui/tap";
-import { tapLookupResources } from "./tapLookupResources";
-import { ApiObject } from "./tapApi";
-
-/**
- * Resource props that will be passed to each item resource
- */
-export type TapStoreListResourceProps<TProps> = {
-  initialValue: TProps;
-  remove: () => void;
-};
-
-/**
- * Configuration for tapStoreList hook
- */
-export type TapStoreListConfig<TProps, TState, TApi extends ApiObject> = {
-  /**
-   * Initial values for the list items
-   */
-  initialValues: TProps[];
-
-  // TODO we can't use Resource type here because of contravariance
-  // I think we need a special type in tap that correctly handles the contravariance
-  // or change the behavior of the Resource type
-
-  /**
-   * Resource function that creates an element for each item
-   * Should return a ResourceElement with { key, state, api }
-   *
-   * The resource will receive { initialValue, remove } as props.
-   */
-  resource: ContravariantResource<
-    {
-      key: string | undefined;
-      state: TState;
-      api: TApi;
-    },
-    TapStoreListResourceProps<TProps>
-  >;
-  /**
-   * Optional ID generator function for new items
-   * If not provided, items must include an ID when added
-   */
-  idGenerator?: () => string;
-};
-
-/**
- * Creates a stateful list with add functionality, rendering each item via the provided resource.
- * Returns state array, api lookup function, and add method.
- *
- * @param config - Configuration object with initialValues, resource, and optional idGenerator
- * @returns Object with { state: TState[], api: (lookup) => TApi, add: (id?) => void }
- *
- * @example
- * ```typescript
- * const todoList = tapStoreList({
- *   initialValues: [
- *     { id: "1", text: "First todo" },
- *     { id: "2", text: "Second todo" }
- *   ],
- *   resource: (props) => TodoItemResource(props, { key: props.id }),
- *   idGenerator: () => `todo-${Date.now()}`
- * });
- *
- * // Access state array
- * const allTodos = todoList.state;
- *
- * // Lookup specific item
- * const firstTodo = todoList.api({ index: 0 });
- * const specificTodo = todoList.api({ key: "1" });
- *
- * // Add new item
- * todoList.add(); // Uses idGenerator
- * todoList.add("custom-id"); // Uses provided id
- * ```
- */
-export const tapStoreList = <
-  TProps extends { id: string },
-  TState,
-  TApi extends ApiObject,
->(
-  config: TapStoreListConfig<TProps, TState, TApi>,
-): {
-  state: TState[];
-  api: (lookup: { index: number } | { id: string }) => TApi;
-  add: (id?: string) => void;
-} => {
-  const { initialValues, resource: Resource, idGenerator } = config;
-
-  const [items, setItems] = tapState<TProps[]>(initialValues);
-
-  const lookup = tapLookupResources(
-    items.map((item) =>
-      Resource(
-        {
-          initialValue: item,
-          remove: () => {
-            setItems(items.filter((i) => i !== item));
-          },
-        },
-        {
-          key: item.id,
-        },
-      ),
-    ),
-  );
-
-  const add = (id?: string) => {
-    const newId = id ?? idGenerator?.();
-    if (!newId) {
-      throw new Error(
-        "tapStoreList: Either provide an id to add() or configure an idGenerator",
-      );
-    }
-
-    // Create a new item with the generated/provided id
-    // This assumes TProps has an 'id' field - users will need to ensure their props type supports this
-    const newItem = { id: newId } as TProps;
-    setItems([...items, newItem]);
-  };
-
-  return {
-    state: lookup.state,
-    api: (query: { index: number } | { id: string }) => {
-      if ("index" in query) {
-        return lookup.api({ index: query.index });
-      }
-      return lookup.api({ key: query.id });
-    },
-    add,
-  };
-};

package/src/types.ts

@@ -1,119 +0,0 @@
-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 TMeta - Source/query metadata (use ScopeMeta or discriminated union)
- * @template TEvents - Optional events that this scope can emit
- * @internal
- */
-export type ScopeDefinition<
-  TValue extends ScopeValueType = ScopeValueType,
-  TMeta extends ScopeMetaType = ScopeMetaType,
-  TEvents extends Record<string, unknown> = Record<string, unknown>,
-> = {
-  value: TValue;
-  meta: TMeta;
-  events: TEvents;
-};
-
-/**
- * Module augmentation interface for assistant-ui store type extensions.
- *
- * @example
- * ```typescript
- * declare module "@assistant-ui/store" {
- *   interface AssistantScopeRegistry {
- *     foo: {
- *       value: { getState: () => { bar: string }; updateBar: (bar: string) => void };
- *       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>;
- *     };
- *   }
- * }
- * ```
- */
-export interface AssistantScopeRegistry {}
-
-export type AssistantScopes = keyof AssistantScopeRegistry extends never
-  ? Record<"ERROR: No scopes were defined", ScopeDefinition>
-  : { [K in keyof AssistantScopeRegistry]: AssistantScopeRegistry[K] };
-/**
- * Type for a scope field - a function that returns the current API value,
- * with source/query metadata attached (derived from meta)
- */
-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) => T["value"];
-  source: T["meta"]["source"];
-  query: T["meta"]["query"];
-};
-
-/**
- * Input type for scope definitions - ResourceElement that returns the API value
- * Can optionally include source/query metadata via DerivedScope
- */
-export type ScopeInput<T extends ScopeDefinition> = ResourceElement<{
-  api: T["value"];
-}>;
-
-/**
- * Map of scope names to their input definitions
- */
-export type ScopesInput = {
-  [K in keyof AssistantScopes]?: ScopeInput<AssistantScopes[K]>;
-};
-
-/**
- * Unsubscribe function type
- */
-export type Unsubscribe = () => void;
-
-/**
- * State type extracted from all scopes
- */
-export type AssistantState = {
-  [K in keyof AssistantScopes]: ReturnType<
-    AssistantScopes[K]["value"]["getState"]
-  >;
-};
-
-/**
- * The assistant client type with all registered scopes
- */
-export type AssistantClient = {
-  [K in keyof AssistantScopes]: ScopeField<AssistantScopes[K]>;
-} & {
-  subscribe(listener: () => void): Unsubscribe;
-  flushSync(): void;
-  on<TEvent extends AssistantEvent>(
-    selector: AssistantEventSelector<TEvent>,
-    callback: AssistantEventCallback<TEvent>,
-  ): Unsubscribe;
-};

package/src/utils/splitScopes.ts

@@ -1,38 +0,0 @@
-import { DerivedScope } from "../DerivedScope";
-import type { AssistantScopes, ScopeInput, ScopesInput } from "../types";
-
-/**
- * Splits a scopes object into root scopes and derived scopes.
- *
- * @param scopes - The scopes input object to split
- * @returns An object with { rootScopes, derivedScopes }
- *
- * @example
- * ```typescript
- * const scopes = {
- *   foo: RootScope({ ... }),
- *   bar: DerivedScope({ ... }),
- * };
- *
- * const { rootScopes, derivedScopes } = splitScopes(scopes);
- * // rootScopes = { foo: ... }
- * // derivedScopes = { bar: ... }
- * ```
- */
-export function splitScopes(scopes: ScopesInput) {
-  const rootScopes: ScopesInput = {};
-  const derivedScopes: ScopesInput = {};
-
-  for (const [key, scopeElement] of Object.entries(scopes) as [
-    keyof ScopesInput,
-    ScopeInput<AssistantScopes[keyof ScopesInput]>,
-  ][]) {
-    if (scopeElement.type === DerivedScope) {
-      derivedScopes[key] = scopeElement;
-    } else {
-      rootScopes[key] = scopeElement;
-    }
-  }
-
-  return { rootScopes, derivedScopes };
-}