@assistant-ui/store 0.0.0

package/dist/useAssistantState.js

@@ -0,0 +1,53 @@
+// src/useAssistantState.tsx
+import { useMemo, useSyncExternalStore, useDebugValue } from "react";
+import { useAssistantClient } from "./useAssistantClient.js";
+var ProxiedAssistantState = class _ProxiedAssistantState {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  #getScope(key) {
+    const scopeField = this.#client[key];
+    if (!scopeField) {
+      throw new Error(`Scope "${String(key)}" not found in client`);
+    }
+    const api = scopeField();
+    const state = api.getState();
+    return state;
+  }
+  // Create a Proxy to dynamically handle property access
+  static create(client) {
+    const instance = new _ProxiedAssistantState(client);
+    return new Proxy(instance, {
+      get(target, prop) {
+        if (typeof prop === "string" && prop in client) {
+          return target.#getScope(prop);
+        }
+        return void 0;
+      }
+    });
+  }
+};
+var useAssistantState = (selector) => {
+  const client = useAssistantClient();
+  const proxiedState = useMemo(
+    () => ProxiedAssistantState.create(client),
+    [client]
+  );
+  const slice = useSyncExternalStore(
+    client.subscribe,
+    () => selector(proxiedState),
+    () => selector(proxiedState)
+  );
+  useDebugValue(slice);
+  if (slice instanceof ProxiedAssistantState) {
+    throw new Error(
+      "You tried to return the entire AssistantState. This is not supported due to technical limitations."
+    );
+  }
+  return slice;
+};
+export {
+  useAssistantState
+};
+//# sourceMappingURL=useAssistantState.js.map

package/dist/useAssistantState.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useAssistantState.tsx"],"sourcesContent":["import { useMemo, useSyncExternalStore, useDebugValue } from \"react\";\nimport type { AssistantClient, AssistantState } from \"./types\";\nimport { useAssistantClient } from \"./useAssistantClient\";\n\n/**\n * Proxied state that lazily accesses scope states\n */\nclass ProxiedAssistantState {\n  #client: AssistantClient;\n\n  constructor(client: AssistantClient) {\n    this.#client = client;\n  }\n\n  #getScope<K extends keyof AssistantState>(key: K): AssistantState[K] {\n    const scopeField = this.#client[key];\n    if (!scopeField) {\n      throw new Error(`Scope \"${String(key)}\" not found in client`);\n    }\n\n    const api = scopeField();\n    const state = api.getState();\n    return state as AssistantState[K];\n  }\n\n  // Create a Proxy to dynamically handle property access\n  static create(client: AssistantClient): AssistantState {\n    const instance = new ProxiedAssistantState(client);\n    return new Proxy(instance, {\n      get(target, prop) {\n        if (typeof prop === \"string\" && prop in client) {\n          return target.#getScope(prop as keyof AssistantState);\n        }\n        return undefined;\n      },\n    }) as unknown as AssistantState;\n  }\n}\n\n/**\n * Hook to access a slice of the assistant state with automatic subscription\n *\n * @param selector - Function to select a slice of the state\n * @returns The selected state slice\n *\n * @example\n * ```typescript\n * const client = useAssistantClient({\n *   foo: RootScope({ ... }),\n * });\n *\n * const bar = useAssistantState((state) => state.foo.bar);\n * ```\n */\nexport const useAssistantState = <T,>(\n  selector: (state: AssistantState) => T,\n): T => {\n  const client = useAssistantClient();\n\n  const proxiedState = useMemo(\n    () => ProxiedAssistantState.create(client),\n    [client],\n  );\n\n  const slice = useSyncExternalStore(\n    client.subscribe,\n    () => selector(proxiedState),\n    () => selector(proxiedState),\n  );\n\n  useDebugValue(slice);\n\n  if (slice instanceof ProxiedAssistantState) {\n    throw new Error(\n      \"You tried to return the entire AssistantState. This is not supported due to technical limitations.\",\n    );\n  }\n\n  return slice;\n};\n"],"mappings":";AAAA,SAAS,SAAS,sBAAsB,qBAAqB;AAE7D,SAAS,0BAA0B;AAKnC,IAAM,wBAAN,MAAM,uBAAsB;AAAA,EAC1B;AAAA,EAEA,YAAY,QAAyB;AACnC,SAAK,UAAU;AAAA,EACjB;AAAA,EAEA,UAA0C,KAA2B;AACnE,UAAM,aAAa,KAAK,QAAQ,GAAG;AACnC,QAAI,CAAC,YAAY;AACf,YAAM,IAAI,MAAM,UAAU,OAAO,GAAG,CAAC,uBAAuB;AAAA,IAC9D;AAEA,UAAM,MAAM,WAAW;AACvB,UAAM,QAAQ,IAAI,SAAS;AAC3B,WAAO;AAAA,EACT;AAAA;AAAA,EAGA,OAAO,OAAO,QAAyC;AACrD,UAAM,WAAW,IAAI,uBAAsB,MAAM;AACjD,WAAO,IAAI,MAAM,UAAU;AAAA,MACzB,IAAI,QAAQ,MAAM;AAChB,YAAI,OAAO,SAAS,YAAY,QAAQ,QAAQ;AAC9C,iBAAO,OAAO,UAAU,IAA4B;AAAA,QACtD;AACA,eAAO;AAAA,MACT;AAAA,IACF,CAAC;AAAA,EACH;AACF;AAiBO,IAAM,oBAAoB,CAC/B,aACM;AACN,QAAM,SAAS,mBAAmB;AAElC,QAAM,eAAe;AAAA,IACnB,MAAM,sBAAsB,OAAO,MAAM;AAAA,IACzC,CAAC,MAAM;AAAA,EACT;AAEA,QAAM,QAAQ;AAAA,IACZ,OAAO;AAAA,IACP,MAAM,SAAS,YAAY;AAAA,IAC3B,MAAM,SAAS,YAAY;AAAA,EAC7B;AAEA,gBAAc,KAAK;AAEnB,MAAI,iBAAiB,uBAAuB;AAC1C,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;","names":[]}

package/dist/utils/splitScopes.d.ts

@@ -0,0 +1,24 @@
+import type { 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 declare function splitScopes(scopes: ScopesInput): {
+    rootScopes: ScopesInput;
+    derivedScopes: ScopesInput;
+};
+//# sourceMappingURL=splitScopes.d.ts.map

package/dist/utils/splitScopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"splitScopes.d.ts","sourceRoot":"","sources":["../../src/utils/splitScopes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA+B,WAAW,EAAE,MAAM,UAAU,CAAC;AAEzE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW;;;EAgB9C"}

package/dist/utils/splitScopes.js

@@ -0,0 +1,18 @@
+// src/utils/splitScopes.ts
+import { DerivedScope } from "../DerivedScope.js";
+function splitScopes(scopes) {
+  const rootScopes = {};
+  const derivedScopes = {};
+  for (const [key, scopeElement] of Object.entries(scopes)) {
+    if (scopeElement.type === DerivedScope) {
+      derivedScopes[key] = scopeElement;
+    } else {
+      rootScopes[key] = scopeElement;
+    }
+  }
+  return { rootScopes, derivedScopes };
+}
+export {
+  splitScopes
+};
+//# sourceMappingURL=splitScopes.js.map

package/dist/utils/splitScopes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/splitScopes.ts"],"sourcesContent":["import { DerivedScope } from \"../DerivedScope\";\nimport type { AssistantScopes, ScopeInput, ScopesInput } from \"../types\";\n\n/**\n * Splits a scopes object into root scopes and derived scopes.\n *\n * @param scopes - The scopes input object to split\n * @returns An object with { rootScopes, derivedScopes }\n *\n * @example\n * ```typescript\n * const scopes = {\n *   foo: RootScope({ ... }),\n *   bar: DerivedScope({ ... }),\n * };\n *\n * const { rootScopes, derivedScopes } = splitScopes(scopes);\n * // rootScopes = { foo: ... }\n * // derivedScopes = { bar: ... }\n * ```\n */\nexport function splitScopes(scopes: ScopesInput) {\n  const rootScopes: ScopesInput = {};\n  const derivedScopes: ScopesInput = {};\n\n  for (const [key, scopeElement] of Object.entries(scopes) as [\n    keyof ScopesInput,\n    ScopeInput<AssistantScopes[keyof ScopesInput]>,\n  ][]) {\n    if (scopeElement.type === DerivedScope) {\n      derivedScopes[key] = scopeElement;\n    } else {\n      rootScopes[key] = scopeElement;\n    }\n  }\n\n  return { rootScopes, derivedScopes };\n}\n"],"mappings":";AAAA,SAAS,oBAAoB;AAqBtB,SAAS,YAAY,QAAqB;AAC/C,QAAM,aAA0B,CAAC;AACjC,QAAM,gBAA6B,CAAC;AAEpC,aAAW,CAAC,KAAK,YAAY,KAAK,OAAO,QAAQ,MAAM,GAGlD;AACH,QAAI,aAAa,SAAS,cAAc;AACtC,oBAAc,GAAG,IAAI;AAAA,IACvB,OAAO;AACL,iBAAW,GAAG,IAAI;AAAA,IACpB;AAAA,EACF;AAEA,SAAO,EAAE,YAAY,cAAc;AACrC;","names":[]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@assistant-ui/store",
+  "description": "Tap-based state management for @assistant-ui",
+  "version": "0.0.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "source": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@assistant-ui/tap": "0.3.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/react": "19.2.5",
+    "tsx": "^4.20.6",
+    "@assistant-ui/x-buildutils": "0.0.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "homepage": "https://www.assistant-ui.com/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/assistant-ui/assistant-ui/tree/main/packages/store"
+  },
+  "bugs": {
+    "url": "https://github.com/assistant-ui/assistant-ui/issues"
+  },
+  "scripts": {
+    "build": "tsx scripts/build.mts",
+    "lint": "eslint ."
+  }
+}

package/src/AssistantContext.tsx

@@ -0,0 +1,64 @@
+import React, { createContext, useContext } from "react";
+import type { AssistantClient, AssistantScopes, ScopeField } from "./types";
+import { hasRegisteredScope } from "./ScopeRegistry";
+
+const NO_OP_SUBSCRIBE = () => () => {};
+const NO_OP_FLUSH_SYNC = () => {};
+const NO_OP_SCOPE_FIELD = (() => {
+  const fn = (() => {
+    throw new Error(
+      "You need to wrap this component/hook in <AssistantProvider>",
+    );
+  }) as ScopeField<never>;
+  fn.source = null;
+  fn.query = null;
+  return fn;
+})();
+
+/**
+ * React Context for the AssistantClient
+ */
+export const AssistantContext = createContext<AssistantClient>(
+  new Proxy({} as AssistantClient, {
+    get(_, prop: string) {
+      // Allow access to subscribe and flushSync without error
+      if (prop === "subscribe") return NO_OP_SUBSCRIBE;
+
+      if (prop === "flushSync") return NO_OP_FLUSH_SYNC;
+
+      // If this is a registered scope, return a function that errors when called or accessed
+      if (hasRegisteredScope(prop as keyof AssistantScopes))
+        return NO_OP_SCOPE_FIELD;
+
+      return null;
+    },
+  }),
+);
+
+export const useAssistantContextValue = (): AssistantClient => {
+  return useContext(AssistantContext);
+};
+
+/**
+ * Provider component for AssistantClient
+ *
+ * @example
+ * ```typescript
+ * <AssistantProvider client={client}>
+ *   <YourApp />
+ * </AssistantProvider>
+ * ```
+ */
+export const AssistantProvider = ({
+  client,
+  children,
+}: {
+  client: AssistantClient;
+  children: React.ReactNode;
+}): React.ReactElement => {
+  return (
+    <AssistantContext.Provider value={client}>
+      {children}
+    </AssistantContext.Provider>
+  );
+};

package/src/DerivedScope.ts

@@ -0,0 +1,21 @@
+import { resource } from "@assistant-ui/tap";
+import type { ScopeDefinition, ScopeValue, DerivedScopeProps } from "./types";
+
+/**
+ * Creates a derived scope field that memoizes based on source and query.
+ * The get callback always calls the most recent version (useEffectEvent pattern).
+ *
+ * @example
+ * ```typescript
+ * const MessageScope = DerivedScope<MessageScopeDefinition>({
+ *   source: "thread",
+ *   query: { type: "index", index: 0 },
+ *   get: () => messageApi,
+ * });
+ * ```
+ */
+export const DerivedScope = resource(
+  <T extends ScopeDefinition>(config: DerivedScopeProps<T>): ScopeValue<T> => {
+    return config;
+  },
+);

package/src/ScopeRegistry.ts

@@ -0,0 +1,58 @@
+import type { AssistantScopes } from "./types";
+import type { ResourceElement } from "@assistant-ui/tap";
+
+type ScopeRegistryEntry<K extends keyof AssistantScopes> = {
+  name: K;
+  defaultInitialize:
+    | ResourceElement<AssistantScopes[K]["value"]>
+    | { error: string };
+};
+
+const scopeRegistry = new Map<
+  keyof AssistantScopes,
+  ResourceElement<any> | { error: string }
+>();
+
+/**
+ * Register a default scope implementation.
+ * This allows scopes to have default values when not explicitly provided.
+ *
+ * @example With a resource:
+ * ```typescript
+ * registerAssistantScope({
+ *   name: "myScope",
+ *   defaultInitialize: MyResource(),
+ * });
+ * ```
+ *
+ * @example With an error:
+ * ```typescript
+ * registerAssistantScope({
+ *   name: "myScope",
+ *   defaultInitialize: { error: "MyScope is not configured" },
+ * });
+ * ```
+ */
+export function registerAssistantScope<K extends keyof AssistantScopes>(
+  config: ScopeRegistryEntry<K>,
+): void {
+  scopeRegistry.set(config.name, config.defaultInitialize);
+}
+
+/**
+ * Get the default initializer for a scope, if registered.
+ */
+export function getDefaultScopeInitializer<K extends keyof AssistantScopes>(
+  name: K,
+):
+  | (ResourceElement<AssistantScopes[K]["value"]> | { error: string })
+  | undefined {
+  return scopeRegistry.get(name);
+}
+
+/**
+ * Get all registered scope names.
+ */
+export function hasRegisteredScope(name: keyof AssistantScopes): boolean {
+  return scopeRegistry.has(name);
+}

package/src/asStore.ts

@@ -0,0 +1,40 @@
+import {
+  tapMemo,
+  tapEffect,
+  ResourceElement,
+  resource,
+  createResource,
+} from "@assistant-ui/tap";
+import { Unsubscribe } from "./types";
+
+export interface Store<TState> {
+  /**
+   * Get the current state of the store.
+   */
+  getState(): TState;
+
+  /**
+   * Subscribe to the store.
+   */
+  subscribe(listener: () => void): Unsubscribe;
+
+  /**
+   * Synchronously flush all the updates to the store.
+   */
+  flushSync(): void;
+}
+
+export const asStore = resource(
+  <TState, TProps>(element: ResourceElement<TState, TProps>): Store<TState> => {
+    const resource = tapMemo(
+      () => createResource(element, true),
+      [element.type],
+    );
+
+    tapEffect(() => {
+      resource.updateInput(element.props);
+    });
+
+    return resource;
+  },
+);

package/src/index.ts

@@ -0,0 +1,13 @@
+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 type { AssistantScopeRegistry } from "./types";

package/src/tapApi.ts

@@ -0,0 +1,91 @@
+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

@@ -0,0 +1,62 @@
+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

@@ -0,0 +1,133 @@
+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,
+  };
+};