refactor: organize public type contracts

src/core/createShallowStore.ts

@@ -1,7 +1,11 @@
 import { createStore } from "zustand";
 import { createStoreSelectionBindings } from "../hooks";
-import type { MutatorsStateCreator, StoreApiWithMutators, StoreMutatorTuple } from "../types";
-import type { ShallowStoreBindings } from "./createShallowStore.types";
+import type {
+  MutatorsStateCreator,
+  ShallowStoreBindings,
+  StoreApiWithMutators,
+  StoreMutatorTuple,
+} from "../types";
 
 /**
  * Creates a Zustand store with shallow-first selector semantics.

src/core/createStoreToolkit.ts

@@ -1,9 +1,12 @@
 import { createResolvedStoreHooks } from "../hooks";
 import { createStoreProvider } from "../providers";
 import { createShallowStore } from "./createShallowStore";
-import type { StoreProviderResult } from "../providers";
-import type { MutatorsStateCreator, StoreMutatorTuple } from "../types";
-import type { StoreToolkit } from "./createStoreToolkit.types";
+import type {
+  MutatorsStateCreator,
+  StoreMutatorTuple,
+  StoreProviderResult,
+  StoreToolkit,
+} from "../types";
 
 /**
  * Creates a complete Zustand store toolkit with global store, provider, and resolution hooks

src/core/index.ts

@@ -1,4 +1,3 @@
 export { createShallowStore } from "./createShallowStore";
 export { createStoreToolkit } from "./createStoreToolkit";
-export type { ShallowStoreBindings } from "./createShallowStore.types";
-export type { StoreToolkit } from "./createStoreToolkit.types";
+export type { ShallowStoreBindings, StoreToolkit } from "../types";

src/hooks/createResolvedStoreHooks.ts

@@ -1,6 +1,5 @@
-import { useStoreSelection, useStoreSelectionPlain } from "./storeSelection";
-import type { StoreApiWithMutators, StoreMutatorTuple } from "../types";
-import type { ResolvedStoreBindings } from "./createResolvedStoreHooks.types";
+import { createStoreSelectionBindings } from "./storeSelection";
+import type { ResolvedStoreBindings, StoreApiWithMutators, StoreMutatorTuple } from "../types";
 
 /**
  * Creates hooks that resolve between context store and global store
@@ -23,25 +22,8 @@ export function createResolvedStoreHooks<TState, TMutators extends Array<StoreMu
     return contextStore ?? globalStoreApi;
   }
 
-  function useResolvedValue(): TState;
-  function useResolvedValue<T>(
-    selector: (state: TState) => T,
-    equalityFn?: (a: T, b: T) => boolean
-  ): T;
-  function useResolvedValue<T>(
-    selector?: (state: TState) => T,
-    equalityFn?: (a: T | TState, b: T | TState) => boolean
-  ): T | TState {
-    const store = useResolvedStoreApi();
-    return useStoreSelection(store, selector, equalityFn);
-  }
-
-  function useResolvedStorePlain(): TState;
-  function useResolvedStorePlain<T>(selector: (state: TState) => T): T;
-  function useResolvedStorePlain<T>(selector?: (state: TState) => T): T | TState {
-    const store = useResolvedStoreApi();
-    return useStoreSelectionPlain(store, selector);
-  }
+  const { useStoreValue: useResolvedValue, useStorePlain: useResolvedStorePlain } =
+    createStoreSelectionBindings(useResolvedStoreApi);
 
   return {
     useResolvedStoreApi,

src/hooks/index.ts

@@ -1,5 +1,5 @@
 export { createResolvedStoreHooks } from "./createResolvedStoreHooks";
-export type { ResolvedStoreBindings } from "./createResolvedStoreHooks.types";
+export type { ResolvedStoreBindings, StorePlainHook, StoreValueHook } from "../types";
 export { useSelectorWithEquality } from "./useSelectorWithEquality";
 export type {
   UseSelectorWithEqualityEqualityFn,
@@ -9,9 +9,4 @@ export type {
 } from "./useSelectorWithEquality";
 export { createStoreSelectionBindings } from "./storeSelection";
 export { useStoreSelection, useStoreSelectionPlain } from "./storeSelection";
-export type {
-  StorePlainHook,
-  StoreResolver,
-  StoreSelectionBindings,
-  StoreValueHook,
-} from "./storeSelection";
+export type { StoreResolver, StoreSelectionBindings } from "./storeSelection";

src/hooks/storeSelection/index.ts

@@ -1,8 +1,3 @@
 export { createStoreSelectionBindings } from "./createStoreSelectionBindings";
 export { useStoreSelection, useStoreSelectionPlain } from "./useStoreSelection";
-export type {
-  StorePlainHook,
-  StoreResolver,
-  StoreSelectionBindings,
-  StoreValueHook,
-} from "./storeSelection.types";
+export type { StoreResolver, StoreSelectionBindings } from "./storeSelection.types";

src/hooks/storeSelection/storeSelection.types.ts

@@ -1,20 +1,11 @@
 import type { StoreApi } from "zustand";
+import type { StorePlainHook, StoreValueHook } from "../../types/store-hooks.types";
 
 export type SelectionStore<TState> = Pick<
   StoreApi<TState>,
   "getState" | "getInitialState" | "subscribe"
 >;
 
-export interface StoreValueHook<TState> {
-  (): TState;
-  <T>(selector: (state: TState) => T, equalityFn?: (left: T, right: T) => boolean): T;
-}
-
-export interface StorePlainHook<TState> {
-  (): TState;
-  <T>(selector: (state: TState) => T): T;
-}
-
 export type StoreResolver<TState> = () => SelectionStore<TState>;
 
 export interface StoreSelectionBindings<TState> {

src/index.ts

@@ -1,22 +1,27 @@
 // Core utilities
 export { createShallowStore, createStoreToolkit } from "./core";
-export type { ShallowStoreBindings, StoreToolkit } from "./core";
 
 // Provider utilities
 export { createStoreProvider } from "./providers";
-export type { StoreProviderConfig, StoreProviderProps, StoreProviderResult } from "./providers";
 
 // Hook utilities
 export { createResolvedStoreHooks } from "./hooks";
-export type { ResolvedStoreBindings, StorePlainHook, StoreValueHook } from "./hooks";
 
 // React 19 utilities
 export { createTransitionAction, useActionStateAdapter, useOptimisticReducer } from "./react19";
 
-// Shared store types
+// Types
 export type {
   MutatorsStateCreator,
+  ResolvedStoreBindings,
+  ShallowStoreBindings,
   SimpleStateCreator,
   StoreApiWithMutators,
+  StorePlainHook,
+  StoreProviderConfig,
+  StoreProviderProps,
+  StoreProviderResult,
   StoreMutatorTuple,
+  StoreToolkit,
+  StoreValueHook,
 } from "./types";

src/providers/createStoreProvider.tsx

@@ -1,8 +1,13 @@
 import { type ReactNode, createContext, useContext, useEffect, useRef, useState } from "react";
 import { createStore } from "zustand";
-import { useStoreSelection, useStoreSelectionPlain } from "../hooks";
-import type { MutatorsStateCreator, StoreApiWithMutators, StoreMutatorTuple } from "../types";
-import type { StoreProviderProps, StoreProviderResult } from "./createStoreProvider.types";
+import { createStoreSelectionBindings } from "../hooks";
+import type {
+  MutatorsStateCreator,
+  StoreApiWithMutators,
+  StoreMutatorTuple,
+  StoreProviderProps,
+  StoreProviderResult,
+} from "../types";
 
 /**
  * Creates a React Context provider for isolated Zustand store instances.
@@ -193,33 +198,13 @@ export function createStoreProvider<TState, TMutators extends Array<StoreMutator
     return useContext(StoreContext);
   }
 
-  function useContextStoreWithSelector(): TState;
-  function useContextStoreWithSelector<T>(selector: (state: TState) => T): T;
-  function useContextStoreWithSelector<T>(
-    selector: (state: TState) => T,
-    equalityFn: (a: T, b: T) => boolean
-  ): T;
-  function useContextStoreWithSelector<T>(
-    selector?: (state: TState) => T,
-    equalityFn?: (a: T | TState, b: T | TState) => boolean
-  ): T | TState {
-    const store = useStoreContext();
-
-    return useStoreSelection(store, selector, equalityFn);
-  }
-
-  function useContextStorePlain(): TState;
-  function useContextStorePlain<T>(selector: (state: TState) => T): T;
-  function useContextStorePlain<T>(selector?: (state: TState) => T): T | TState {
-    const store = useStoreContext();
-
-    return useStoreSelectionPlain(store, selector);
-  }
+  const { useStoreValue: useContextStore, useStorePlain: useContextStorePlain } =
+    createStoreSelectionBindings(useStoreContext);
 
   return {
     Provider,
     useContextStoreApi: useStoreContext,
-    useContextStore: useContextStoreWithSelector,
+    useContextStore,
     useContextStorePlain,
     useIsInsideProvider,
     useContextStoreOptional,

src/providers/index.ts

@@ -1,6 +1,2 @@
 export { createStoreProvider } from "./createStoreProvider";
-export type {
-  StoreProviderConfig,
-  StoreProviderProps,
-  StoreProviderResult,
-} from "./createStoreProvider.types";
+export type { StoreProviderConfig, StoreProviderProps, StoreProviderResult } from "../types";

src/type-tests/README.md

@@ -0,0 +1,11 @@
+# Compile-time type tests
+
+This folder contains TypeScript programs that verify the package's public type contracts. They are
+compiled by `npm run typecheck` through the root `tsconfig.json`; they are not Vitest runtime tests.
+
+Each `*.type-test.ts` file should exercise a public consumer scenario that must either compile or
+produce a deliberate `@ts-expect-error`. Keep runtime behavior tests beside their owning modules in
+`__tests__` folders.
+
+The package build starts from the public entry point, so these files do not become runtime exports
+or bundled JavaScript.

src/type-tests/middlewareCompatibility.type-test.ts

@@ -0,0 +1,150 @@
+import { createJSONStorage, devtools, persist, subscribeWithSelector } from "zustand/middleware";
+import { immer } from "zustand/middleware/immer";
+import {
+  type ResolvedStoreBindings,
+  createResolvedStoreHooks,
+  createShallowStore,
+  createStoreProvider,
+  createStoreToolkit,
+} from "../index";
+
+interface CounterState {
+  count: number;
+  increment: () => void;
+}
+
+type Assert<T extends true> = T;
+type HasKey<T, K extends PropertyKey> = K extends keyof T ? true : false;
+type IsCallable<T> = T extends (...args: Array<never>) => unknown ? true : false;
+
+const storage = createJSONStorage<CounterState>(() => ({
+  getItem: () => null,
+  setItem: () => undefined,
+  removeItem: () => undefined,
+}));
+
+const _devtoolsStore = createShallowStore<CounterState, [["zustand/devtools", never]]>(
+  devtools(
+    (set) => ({
+      count: 0,
+      increment: () => {
+        set((state) => ({ count: state.count + 1 }));
+      },
+    }),
+    { name: "DevtoolsStore" }
+  )
+);
+
+type DevtoolsCleanupAssertion = Assert<
+  IsCallable<typeof _devtoolsStore.useStoreApi.devtools.cleanup>
+>;
+
+const _persistStore = createShallowStore<CounterState, [["zustand/persist", CounterState]]>(
+  persist(
+    (set) => ({
+      count: 0,
+      increment: () => {
+        set((state) => ({ count: state.count + 1 }));
+      },
+    }),
+    { name: "PersistStore", storage }
+  )
+);
+
+type PersistApiAssertion = Assert<HasKey<typeof _persistStore.useStoreApi, "persist">>;
+
+const _subscribeStore = createShallowStore<
+  CounterState,
+  [["zustand/subscribeWithSelector", never]]
+>(
+  subscribeWithSelector((set) => ({
+    count: 0,
+    increment: () => {
+      set((state) => ({ count: state.count + 1 }));
+    },
+  }))
+);
+
+const _unsubscribe = _subscribeStore.useStoreApi.subscribe(
+  (state) => state.count,
+  (selected, previous) => {
+    const nextCount: number = selected;
+    const prevCount: number = previous;
+
+    void nextCount;
+    void prevCount;
+  },
+  { fireImmediately: true }
+);
+
+void _unsubscribe;
+
+const _immerStore = createShallowStore<CounterState, [["zustand/immer", never]]>(
+  immer((set) => ({
+    count: 0,
+    increment: () => {
+      set({ count: 1 });
+    },
+  }))
+);
+
+const _immerUpdater: Parameters<typeof _immerStore.useStoreApi.setState>[0] = (
+  draft: CounterState
+) => {
+  draft.count += 1;
+};
+
+void _immerUpdater;
+
+type CombinedMutators = [["zustand/persist", CounterState], ["zustand/devtools", never]];
+
+const combinedCreator = persist<CounterState, [], [["zustand/devtools", never]], CounterState>(
+  devtools<CounterState>(
+    (set) => ({
+      count: 0,
+      increment: () => {
+        set((state) => ({ count: state.count + 1 }));
+      },
+    }),
+    { name: "CombinedStore" }
+  ),
+  { name: "CombinedStore", storage }
+);
+
+const _provider = createStoreProvider<CounterState, CombinedMutators>(combinedCreator);
+const _toolkit = createStoreToolkit<CounterState, CombinedMutators>(combinedCreator);
+const _standaloneResolved = createResolvedStoreHooks<CounterState, CombinedMutators>(
+  _toolkit.useStoreApi,
+  _provider.useContextStoreOptional
+);
+const _toolkitResolvedContract: ResolvedStoreBindings<CounterState, CombinedMutators> = _toolkit;
+const _standaloneResolvedContract: ResolvedStoreBindings<CounterState, CombinedMutators> =
+  _standaloneResolved;
+
+type ProviderPersistAssertion = Assert<
+  HasKey<ReturnType<typeof _provider.useContextStoreApi>, "persist">
+>;
+type ProviderDevtoolsAssertion = Assert<
+  HasKey<ReturnType<typeof _provider.useContextStoreApi>, "devtools">
+>;
+type ToolkitPersistAssertion = Assert<HasKey<typeof _toolkit.useStoreApi, "persist">>;
+type ToolkitDevtoolsAssertion = Assert<HasKey<typeof _toolkit.useStoreApi, "devtools">>;
+type ResolvedPersistAssertion = Assert<
+  HasKey<ReturnType<typeof _toolkit.useResolvedStoreApi>, "persist">
+>;
+type StandaloneResolvedDevtoolsAssertion = Assert<
+  HasKey<ReturnType<typeof _standaloneResolvedContract.useResolvedStoreApi>, "devtools">
+>;
+
+void _toolkitResolvedContract;
+
+export type MiddlewareCompatibilityAssertions = [
+  DevtoolsCleanupAssertion,
+  PersistApiAssertion,
+  ProviderPersistAssertion,
+  ProviderDevtoolsAssertion,
+  ToolkitPersistAssertion,
+  ToolkitDevtoolsAssertion,
+  ResolvedPersistAssertion,
+  StandaloneResolvedDevtoolsAssertion,
+];