stunk 1.2.5 → 1.4.6

package/README.md

@@ -98,7 +98,7 @@ nameChunk.set("Olamide"); // ❌ this will throw an error, because it is a reado
 
 ## Batch Updates
 
-Batch Update group multiple **state changes** together and notify **subscribers** only once at the end of the **batch**. This is particularly useful for **optimizing performance** when you need to **update multiple** chunks at the same time.
+Batch Update group multiple **state changes** together and notify **subscribers** only once at the end of the `batch`. This is particularly useful for **optimizing performance** when you need to **update multiple** chunks at the same time.
 
 ```typescript
 import { chunk, batch } from "stunk";
@@ -152,7 +152,7 @@ console.log(fullInfoChunk.get());
 // ✅ { fullName: "Ola Doe", isAdult: true }
 ```
 
-Computed chunks are ideal for scenarios where state depends on multiple sources or needs complex calculations. They ensure your application remains performant and maintainable.
+`computed` chunks are ideal for scenarios where state depends on multiple sources or needs complex calculations. They ensure your application remains performant and maintainable.
 
 ## Advanced Examples
 
@@ -243,7 +243,7 @@ age.set(-5); // ❌ Throws an error: "Value must be non-negative!"
 
 ## Time Travel (Middleware)
 
-The withHistory middleware extends a chunk to support undo and redo functionality. This allows you to navigate back and forth between previous states, making it useful for implementing features like undo/redo, form history, and state time travel.
+The `withHistory` middleware extends a chunk to support undo and redo functionality. This allows you to navigate back and forth between previous states, making it useful for implementing features like undo/redo, form history, and state time travel.
 
 ```typescript
 import { chunk } from "stunk";
@@ -277,7 +277,6 @@ const counter = withHistory(chunk(0), { maxHistory: 5 });
 
 This prevents the history from growing indefinitely and ensures efficient memory usage.
 
-
 ## State Persistence (Middleware)
 
 Stunk provides a persistence middleware to automatically save state changes to storage (localStorage, sessionStorage, etc).
@@ -315,6 +314,35 @@ const encryptedChunk = withPersistence(baseChunk, {
 });
 ```
 
+## Once
+
+`Once` utility is a function that ensures a given piece of code or a function is executed only once, no matter how many times it's called. It's typically used to optimize performance by preventing redundant calculations or event handlers from running multiple times.
+
+How It Works:
+
+- It wraps a function and tracks whether it has been called.
+- On the first call, it executes the function and saves the result.
+- On subsequent calls, it simply returns the saved result without executing the function again.
+
+```typescript
+const numbersChunk = chunk([1, 2, 3, 4, 5]);
+
+const expensiveCalculation = once(() => {
+  console.log("Expensive calculation running...");
+  return numbersChunk.get().reduce((sum, num) => sum + num, 0);
+});
+
+// Derived chunk using the once utility
+const totalChunk = numbersChunk.derive(() => expensiveCalculation());
+
+totalChunk.subscribe((total) => {
+  console.log("Total:", total);
+});
+
+// Even if numbersChunk updates, the expensive calculation runs only once
+numbersChunk.set([10, 20, 30, 40, 50]);
+```
+
 ## Async State
 
 Async Chunks in Stunk are designed to manage asynchronous state seamlessly. They handle loading, error, and data states automatically, making it easier to work with APIs and other asynchronous operations.
@@ -385,6 +413,53 @@ user.mutate(currentUser => ({
 }));
 ```
 
+## Combine Async Chunk
+
+`combineAsyncChunks` utility is used for managing multiple related async chunks.
+
+- Maintains reactivity through the entire chain
+- Preserves previous data during reloading
+- Proper error propagation
+
+```typescript
+// Basic fetch
+const userChunk = asyncChunk(async () => {
+  const response = await fetch("/api/user");
+  return response.json();
+});
+
+// With options
+const postsChunk = asyncChunk(
+  async () => {
+    const response = await fetch("/api/posts");
+    return response.json();
+  },
+  {
+    initialData: [],
+    retryCount: 3,
+    retryDelay: 2000,
+    onError: (error) => console.error("Failed to fetch posts:", error),
+  }
+);
+
+// Combining chunks
+const profileChunk = combineAsyncChunks({
+  user: userChunk,
+  posts: postsChunk,
+});
+
+// Reactive updates
+profileChunk.subscribe(({ loading, error, data }) => {
+  if (loading) {
+    showLoadingSpinner();
+  } else if (error) {
+    showError(error);
+  } else {
+    updateUI(data);
+  }
+});
+```
+
 ## API Reference
 
 ### Core

package/dist/core/asyncChunk.d.ts

@@ -0,0 +1,22 @@
+import { Chunk } from "./core";
+import { AsyncChunkOpt } from "./types";
+export interface AsyncState<T> {
+    loading: boolean;
+    error: Error | null;
+    data: T | null;
+}
+export interface AsyncChunk<T> extends Chunk<AsyncState<T>> {
+    /**
+     * Reload the data from the source.
+     */
+    reload: () => Promise<void>;
+    /**
+     * Mutate the data directly.
+     */
+    mutate: (mutator: (currentData: T | null) => T) => void;
+    /**
+     * Reset the state to the initial value.
+     */
+    reset: () => void;
+}
+export declare function asyncChunk<T>(fetcher: () => Promise<T>, options?: AsyncChunkOpt<T>): AsyncChunk<T>;

package/dist/core/computed.d.ts

@@ -0,0 +1,10 @@
+import { Chunk } from "./core";
+export type ChunkValue<T> = T extends Chunk<infer U> ? U : never;
+export type DependencyValues<T extends Chunk<any>[]> = {
+    [K in keyof T]: T[K] extends Chunk<any> ? ChunkValue<T[K]> : never;
+};
+export interface Computed<T> extends Chunk<T> {
+    isDirty: () => boolean;
+    recompute: () => void;
+}
+export declare function computed<TDeps extends Chunk<any>[], TResult>(dependencies: [...TDeps], computeFn: (...args: DependencyValues<TDeps>) => TResult): Computed<TResult>;

package/dist/core/core.d.ts

@@ -0,0 +1,20 @@
+export type Subscriber<T> = (newValue: T) => void;
+export type Middleware<T> = (value: T, next: (newValue: T) => void) => void;
+export interface Chunk<T> {
+    /** Get the current value of the chunk. */
+    get: () => T;
+    /** Set a new value for the chunk. */
+    set: (value: T) => void;
+    /** Update existing value efficiently */
+    update: (updater: (currentValue: T) => T) => void;
+    /** Subscribe to changes in the chunk. Returns an unsubscribe function. */
+    subscribe: (callback: Subscriber<T>) => () => void;
+    /** Create a derived chunk based on this chunk's value. */
+    derive: <D>(fn: (value: T) => D) => Chunk<D>;
+    /** Reset the chunk to its initial value. */
+    reset: () => void;
+    /** Destroy the chunk and all its subscribers. */
+    destroy: () => void;
+}
+export declare function batch(callback: () => void): void;
+export declare function chunk<T>(initialValue: T, middleware?: Middleware<T>[]): Chunk<T>;

package/dist/core/selector.d.ts

@@ -0,0 +1,2 @@
+import { Chunk } from "./core";
+export declare function select<T, S>(sourceChunk: Chunk<T>, selector: (value: T) => S): Chunk<S>;

package/dist/core/types.d.ts

@@ -0,0 +1,16 @@
+import { AsyncChunk } from "./asyncChunk";
+export type AsyncChunkOpt<T> = {
+    initialData?: T | null;
+    onError?: (error: Error) => void;
+    retryCount?: number;
+    retryDelay?: number;
+};
+export type InferAsyncData<T> = T extends AsyncChunk<infer U> ? U : never;
+export type CombinedData<T> = {
+    [K in keyof T]: InferAsyncData<T[K]> | null;
+};
+export type CombinedState<T> = {
+    loading: boolean;
+    error: Error | null;
+    data: CombinedData<T>;
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { chunk, batch } from './core/core';
+export { asyncChunk } from './core/asyncChunk';
+export { computed } from './core/computed';
+export { select } from './core/selector';
+export { combineAsyncChunks, once, isChunk, isValidChunkValue } from './utils';
+export type { Chunk, Middleware } from './core/core';
+export * as middleware from "./middleware";

package/dist/index.js

@@ -2,5 +2,5 @@ export { chunk, batch } from './core/core';
 export { asyncChunk } from './core/asyncChunk';
 export { computed } from './core/computed';
 export { select } from './core/selector';
-export { combineAsyncChunks } from './utils';
-export * from "./middleware";
+export { combineAsyncChunks, once, isChunk, isValidChunkValue } from './utils';
+export * as middleware from "./middleware";

package/dist/middleware/history.d.ts

@@ -0,0 +1,30 @@
+import { Chunk } from "../core/core";
+export interface ChunkWithHistory<T> extends Chunk<T> {
+    /**
+   * Reverts to the previous state (if available).
+   */
+    undo: () => void;
+    /**
+     * Moves to the next state (if available).
+     */
+    redo: () => void;
+    /**
+     * Returns true if there is a previous state to revert to.
+     */
+    canUndo: () => boolean;
+    /**
+     * Returns true if there is a next state to move to.
+     */
+    canRedo: () => boolean;
+    /**
+     * Returns an array of all the values in the history.
+     */
+    getHistory: () => T[];
+    /**
+     * Clears the history, keeping only the current value.
+     */
+    clearHistory: () => void;
+}
+export declare function withHistory<T>(baseChunk: Chunk<T>, options?: {
+    maxHistory?: number;
+}): ChunkWithHistory<T>;

package/dist/middleware/index.d.ts

@@ -0,0 +1,4 @@
+export { logger } from "./logger";
+export { nonNegativeValidator } from "./validator";
+export { withHistory } from "./history";
+export { withPersistence } from './persistence';

package/dist/middleware/logger.d.ts

@@ -0,0 +1,2 @@
+import { Middleware } from "../core/core";
+export declare const logger: Middleware<any>;

package/dist/middleware/persistence.d.ts

@@ -0,0 +1,8 @@
+import { Chunk } from "../core/core";
+export interface PersistOptions<T> {
+    key: string;
+    storage?: Storage;
+    serialize?: (value: T) => string;
+    deserialize?: (value: string) => T;
+}
+export declare function withPersistence<T>(baseChunk: Chunk<T>, options: PersistOptions<T>): Chunk<T>;

package/dist/middleware/validator.d.ts

@@ -0,0 +1,2 @@
+import { Middleware } from "../core/core";
+export declare const nonNegativeValidator: Middleware<number>;

package/dist/use-react/hooks/useAsyncChunk.d.ts

@@ -0,0 +1,14 @@
+import { AsyncChunk, AsyncState } from "../../core/asyncChunk";
+/**
+ * A hook that handles asynchronous state with built-in reactivity.
+ * Provides loading, error, and data states.
+ */
+export declare function useAsyncChunk<T>(asyncChunk: AsyncChunk<T>): {
+    state: AsyncState<T>;
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+    reload: () => Promise<void>;
+    mutate: (mutator: (currentData: T | null) => T) => void;
+    reset: () => void;
+};

package/dist/use-react/hooks/useAsyncChunk.js

@@ -0,0 +1,27 @@
+import { useState, useEffect, useCallback } from "react";
+/**
+ * A hook that handles asynchronous state with built-in reactivity.
+ * Provides loading, error, and data states.
+ */
+export function useAsyncChunk(asyncChunk) {
+    const [state, setState] = useState(() => asyncChunk.get());
+    useEffect(() => {
+        const unsubscribe = asyncChunk.subscribe((newState) => {
+            setState(newState);
+        });
+        return () => unsubscribe();
+    }, [asyncChunk]);
+    const reload = useCallback(() => asyncChunk.reload(), [asyncChunk]);
+    const mutate = useCallback((mutator) => asyncChunk.mutate(mutator), [asyncChunk]);
+    const reset = useCallback(() => asyncChunk.reset(), [asyncChunk]);
+    const { data, loading, error } = state;
+    return {
+        state,
+        data,
+        loading,
+        error,
+        reload,
+        mutate,
+        reset
+    };
+}

package/dist/use-react/hooks/useChunk.d.ts

@@ -0,0 +1,6 @@
+import type { Chunk } from "../../core/core";
+/**
+ * A lightweight hook that subscribes to a chunk and returns its current value, along with setters, selector, reset and destroy.
+ * Ensures reactivity and prevents unnecessary re-renders.
+ */
+export declare function useChunk<T, S = T>(chunk: Chunk<T>, selector?: (value: T) => S): readonly [S, (value: T) => void, (updater: (currentValue: T) => T) => void, () => void, () => void];

package/dist/use-react/hooks/useChunk.js

@@ -0,0 +1,29 @@
+import { useState, useEffect, useCallback } from "react";
+import { select } from "../../core/selector";
+/**
+ * A lightweight hook that subscribes to a chunk and returns its current value, along with setters, selector, reset and destroy.
+ * Ensures reactivity and prevents unnecessary re-renders.
+ */
+export function useChunk(chunk, selector) {
+    const selectedChunk = selector ? select(chunk, selector) : chunk;
+    const [state, setState] = useState(() => selectedChunk.get());
+    useEffect(() => {
+        const unsubscribe = selectedChunk.subscribe((newValue) => {
+            setState(() => newValue);
+        });
+        return () => unsubscribe();
+    }, [selectedChunk]);
+    const set = useCallback((value) => {
+        chunk.set(value);
+    }, [chunk]);
+    const update = useCallback((updater) => {
+        chunk.update(updater);
+    }, [chunk]);
+    const reset = useCallback(() => {
+        chunk.reset();
+    }, [chunk]);
+    const destroy = useCallback(() => {
+        chunk.destroy();
+    }, [chunk]);
+    return [state, set, update, reset, destroy];
+}

package/dist/use-react/hooks/useChunkProperty.d.ts

@@ -0,0 +1,6 @@
+import type { Chunk } from "../../core/core";
+/**
+ * A hook that subscribes to a specific property of a chunk.
+ * This optimizes renders by only updating when the selected property changes.
+ */
+export declare function useChunkProperty<T, K extends keyof T>(chunk: Chunk<T>, property: K): T[K];

package/dist/use-react/hooks/useChunkProperty.js

@@ -0,0 +1,10 @@
+import { useMemo } from "react";
+import { useChunkValue } from "./useChunkValue";
+/**
+ * A hook that subscribes to a specific property of a chunk.
+ * This optimizes renders by only updating when the selected property changes.
+ */
+export function useChunkProperty(chunk, property) {
+    const selector = useMemo(() => (state) => state[property], [property]);
+    return useChunkValue(chunk, selector);
+}

package/dist/use-react/hooks/useChunkValue.d.ts

@@ -0,0 +1,6 @@
+import type { Chunk } from "../../core/core";
+/**
+ * A lightweight hook that subscribes to a chunk and returns only its current value.
+ * Useful for read-only components that don't need to update the chunk.
+ */
+export declare function useChunkValue<T, S = T>(chunk: Chunk<T>, selector?: (value: T) => S): S;

package/dist/use-react/hooks/useChunkValue.js

@@ -0,0 +1,9 @@
+import { useChunk } from "./useChunk";
+/**
+ * A lightweight hook that subscribes to a chunk and returns only its current value.
+ * Useful for read-only components that don't need to update the chunk.
+ */
+export function useChunkValue(chunk, selector) {
+    const [value] = useChunk(chunk, selector);
+    return value;
+}

package/dist/use-react/hooks/useChunkValues.d.ts

@@ -0,0 +1,8 @@
+import type { Chunk } from "../../core/core";
+/**
+ * Hook to read values from multiple chunks at once.
+ * Only re-renders when any of the chunk values change.
+ */
+export declare function useChunkValues<T extends Chunk<any>[]>(chunks: [...T]): {
+    [K in keyof T]: T[K] extends Chunk<infer U> ? U : never;
+};

package/dist/use-react/hooks/useChunkValues.js

@@ -0,0 +1,25 @@
+import { useState, useEffect } from "react";
+/**
+ * Hook to read values from multiple chunks at once.
+ * Only re-renders when any of the chunk values change.
+ */
+export function useChunkValues(chunks) {
+    const [values, setValues] = useState(() => {
+        return chunks.map(chunk => chunk.get());
+    });
+    useEffect(() => {
+        const unsubscribes = chunks.map((chunk, index) => {
+            return chunk.subscribe((newValue) => {
+                setValues(prev => {
+                    const newValues = [...prev];
+                    newValues[index] = newValue;
+                    return newValues;
+                });
+            });
+        });
+        return () => {
+            unsubscribes.forEach(unsubscribe => unsubscribe());
+        };
+    }, [chunks]);
+    return values;
+}

package/dist/use-react/hooks/useComputed.d.ts

@@ -0,0 +1,7 @@
+import { DependencyValues } from "../../core/computed";
+import type { Chunk } from "../../core/core";
+/**
+ * A hook that computes a value based on multiple chunks.
+ * Automatically re-computes when any dependency changes.
+ */
+export declare function useComputed<TDeps extends Chunk<any>[], TResult>(dependencies: [...TDeps], computeFn: (...args: DependencyValues<TDeps>) => TResult): TResult;

package/dist/use-react/hooks/useComputed.js

@@ -0,0 +1,22 @@
+import { useState, useEffect, useMemo } from "react";
+import { computed } from "../../core/computed";
+/**
+ * A hook that computes a value based on multiple chunks.
+ * Automatically re-computes when any dependency changes.
+ */
+export function useComputed(dependencies, computeFn) {
+    // Create the computed value - memoize it based on dependencies to prevent recreation
+    const computedValue = useMemo(() => computed(dependencies, computeFn), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [...dependencies]);
+    const [state, setState] = useState(() => computedValue.get());
+    useEffect(() => {
+        const unsubscribe = computedValue.subscribe((newValue) => {
+            setState(newValue);
+        });
+        return () => {
+            unsubscribe();
+        };
+    }, [computedValue]);
+    return state;
+}

package/dist/use-react/hooks/useDerive.d.ts

@@ -0,0 +1,6 @@
+import type { Chunk } from "../../core/core";
+/**
+ * A hook for creating a read-only derived value from a chunk.
+ * Ensures reactivity and updates when the source chunk changes.
+ */
+export declare function useDerive<T, D>(chunk: Chunk<T>, fn: (value: T) => D): D;

package/dist/use-react/hooks/useDerive.js

@@ -0,0 +1,11 @@
+import { useMemo } from "react";
+import { useChunk } from "./useChunk";
+/**
+ * A hook for creating a read-only derived value from a chunk.
+ * Ensures reactivity and updates when the source chunk changes.
+ */
+export function useDerive(chunk, fn) {
+    const derivedChunk = useMemo(() => chunk.derive(fn), [chunk, fn]);
+    const [derivedValue] = useChunk(derivedChunk);
+    return derivedValue;
+}

package/dist/use-react/index.d.ts

@@ -0,0 +1,7 @@
+export { useChunk } from './hooks/useChunk';
+export { useDerive } from './hooks/useDerive';
+export { useComputed } from './hooks/useComputed';
+export { useChunkValue } from './hooks/useChunkValue';
+export { useChunkProperty } from './hooks/useChunkProperty';
+export { useChunkValues } from './hooks/useChunkValues';
+export { useAsyncChunk } from './hooks/useAsyncChunk';

package/dist/use-react/index.js

@@ -0,0 +1,7 @@
+export { useChunk } from './hooks/useChunk';
+export { useDerive } from './hooks/useDerive';
+export { useComputed } from './hooks/useComputed';
+export { useChunkValue } from './hooks/useChunkValue';
+export { useChunkProperty } from './hooks/useChunkProperty';
+export { useChunkValues } from './hooks/useChunkValues';
+export { useAsyncChunk } from './hooks/useAsyncChunk';

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import { Chunk, Middleware } from "./core/core";
+import { AsyncChunk } from "./core/asyncChunk";
+import { InferAsyncData } from "./core/types";
+export declare function isValidChunkValue(value: any): boolean;
+export declare function isChunk<T>(value: any): value is Chunk<T>;
+export declare function once<T>(fn: () => T): () => T;
+export declare function combineAsyncChunks<T extends Record<string, AsyncChunk<any>>>(chunks: T): Chunk<{
+    loading: boolean;
+    error: Error | null;
+    data: {
+        [K in keyof T]: InferAsyncData<T[K]> | null;
+    };
+}>;
+export declare function processMiddleware<T>(initialValue: T, middleware?: Middleware<T>[]): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stunk",
-  "version": "1.2.5",
+  "version": "1.4.6",
   "description": "Stunk is a lightweight, framework-agnostic state management library for JavaScript and TypeScript. It uses chunk-based state units for efficient updates, reactivity, and performance optimization in React, Vue, Svelte, and Vanilla JS/TS applications.",
   "repository": {
     "type": "git",
@@ -11,7 +11,21 @@
     "url": "https://github.com/I-am-abdulazeez/stunk/issues"
   },
   "main": "dist/index.js",
-  "types": "dist/types/index.d.ts",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./middleware": {
+      "import": "./dist/middleware/index.js",
+      "types": "./dist/middleware/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/use-react/index.js",
+      "types": "./dist/use-react/index.d.ts"
+    }
+  },
   "scripts": {
     "build": "tsc",
     "test": "jest --runInBand",
@@ -51,9 +65,15 @@
   "license": "MIT",
   "devDependencies": {
     "@types/jest": "^29.5.14",
+    "@types/react": "^19.0.10",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "ts-jest": "^29.2.5",
     "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
   }
 }

package/src/core/computed.ts

@@ -1,10 +1,10 @@
-import { Chunk, chunk, batch } from "./core";
+import { Chunk, chunk } from "./core";
 
 // Helper type to extract the value type from a Chunk
-type ChunkValue<T> = T extends Chunk<infer U> ? U : never;
+export type ChunkValue<T> = T extends Chunk<infer U> ? U : never;
 
 // Helper type to transform an array of Chunks into an array of their value types
-type DependencyValues<T extends Chunk<any>[]> = {
+export type DependencyValues<T extends Chunk<any>[]> = {
   [K in keyof T]: T[K] extends Chunk<any> ? ChunkValue<T[K]> : never;
 };
 

package/src/index.ts

@@ -3,8 +3,8 @@ export { asyncChunk } from './core/asyncChunk';
 export { computed } from './core/computed';
 export { select } from './core/selector'
 
-export { combineAsyncChunks } from './utils';
+export { combineAsyncChunks, once, isChunk, isValidChunkValue } from './utils';
 
 export type { Chunk, Middleware } from './core/core';
 
-export * from "./middleware";
+export * as middleware from "./middleware";

package/src/use-react/hooks/useAsyncChunk.ts

@@ -0,0 +1,38 @@
+import { useState, useEffect, useCallback } from "react";
+
+import { AsyncChunk, AsyncState } from "../../core/asyncChunk";
+
+/**
+ * A hook that handles asynchronous state with built-in reactivity.
+ * Provides loading, error, and data states.
+ */
+export function useAsyncChunk<T>(asyncChunk: AsyncChunk<T>) {
+  const [state, setState] = useState<AsyncState<T>>(() => asyncChunk.get());
+
+  useEffect(() => {
+    const unsubscribe = asyncChunk.subscribe((newState) => {
+      setState(newState);
+    });
+
+    return () => unsubscribe();
+  }, [asyncChunk]);
+
+  const reload = useCallback(() => asyncChunk.reload(), [asyncChunk]);
+  const mutate = useCallback(
+    (mutator: (currentData: T | null) => T) => asyncChunk.mutate(mutator),
+    [asyncChunk]
+  );
+  const reset = useCallback(() => asyncChunk.reset(), [asyncChunk]);
+
+  const { data, loading, error } = state;
+
+  return {
+    state,
+    data,
+    loading,
+    error,
+    reload,
+    mutate,
+    reset
+  };
+}

package/src/use-react/hooks/useChunk.ts

@@ -0,0 +1,47 @@
+import { useState, useEffect, useCallback } from "react";
+
+import { select } from "../../core/selector";
+
+import type { Chunk } from "../../core/core";
+
+/**
+ * A lightweight hook that subscribes to a chunk and returns its current value, along with setters, selector, reset and destroy.
+ * Ensures reactivity and prevents unnecessary re-renders.
+ */
+
+export function useChunk<T, S = T>(
+  chunk: Chunk<T>,
+  selector?: (value: T) => S
+) {
+  const selectedChunk = selector ? select(chunk, selector) : chunk;
+
+  const [state, setState] = useState<S>(() => selectedChunk.get() as S);
+
+  useEffect(() => {
+    const unsubscribe = selectedChunk.subscribe((newValue) => {
+      setState(() => newValue as S);
+    });
+    return () => unsubscribe();
+  }, [selectedChunk]);
+
+  const set = useCallback((value: T) => {
+    chunk.set(value);
+  }, [chunk]);
+
+  const update = useCallback(
+    (updater: (currentValue: T) => T) => {
+      chunk.update(updater);
+    },
+    [chunk]
+  );
+
+  const reset = useCallback(() => {
+    chunk.reset();
+  }, [chunk]);
+
+  const destroy = useCallback(() => {
+    chunk.destroy();
+  }, [chunk]);
+
+  return [state, set, update, reset, destroy] as const;
+}

package/src/use-react/hooks/useChunkProperty.ts

@@ -0,0 +1,21 @@
+import { useMemo } from "react";
+
+import { useChunkValue } from "./useChunkValue";
+
+import type { Chunk } from "../../core/core";
+
+/**
+ * A hook that subscribes to a specific property of a chunk.
+ * This optimizes renders by only updating when the selected property changes.
+ */
+export function useChunkProperty<T, K extends keyof T>(
+  chunk: Chunk<T>,
+  property: K
+): T[K] {
+  const selector = useMemo(
+    () => (state: T) => state[property],
+    [property]
+  );
+
+  return useChunkValue(chunk, selector);
+}

package/src/use-react/hooks/useChunkValue.ts

@@ -0,0 +1,15 @@
+import { useChunk } from "./useChunk";
+
+import type { Chunk } from "../../core/core";
+
+/**
+ * A lightweight hook that subscribes to a chunk and returns only its current value.
+ * Useful for read-only components that don't need to update the chunk.
+ */
+export function useChunkValue<T, S = T>(
+  chunk: Chunk<T>,
+  selector?: (value: T) => S
+): S {
+  const [value] = useChunk(chunk, selector);
+  return value;
+}

package/src/use-react/hooks/useChunkValues.ts

@@ -0,0 +1,35 @@
+import { useState, useEffect } from "react";
+
+import type { Chunk } from "../../core/core";
+
+/**
+ * Hook to read values from multiple chunks at once.
+ * Only re-renders when any of the chunk values change.
+ */
+export function useChunkValues<T extends Chunk<any>[]>(
+  chunks: [...T]
+): { [K in keyof T]: T[K] extends Chunk<infer U> ? U : never } {
+  type ReturnType = { [K in keyof T]: T[K] extends Chunk<infer U> ? U : never };
+
+  const [values, setValues] = useState<ReturnType>(() => {
+    return chunks.map(chunk => chunk.get()) as ReturnType;
+  });
+
+  useEffect(() => {
+    const unsubscribes = chunks.map((chunk, index) => {
+      return chunk.subscribe((newValue) => {
+        setValues(prev => {
+          const newValues = [...prev] as ReturnType;
+          newValues[index] = newValue;
+          return newValues;
+        });
+      });
+    });
+
+    return () => {
+      unsubscribes.forEach(unsubscribe => unsubscribe());
+    };
+  }, [chunks]);
+
+  return values;
+}

package/src/use-react/hooks/useComputed.ts

@@ -0,0 +1,34 @@
+import { useState, useEffect, useMemo } from "react";
+
+import { computed, DependencyValues } from "../../core/computed";
+import type { Chunk } from "../../core/core";
+
+/**
+ * A hook that computes a value based on multiple chunks.
+ * Automatically re-computes when any dependency changes.
+ */
+export function useComputed<TDeps extends Chunk<any>[], TResult>(
+  dependencies: [...TDeps],
+  computeFn: (...args: DependencyValues<TDeps>) => TResult
+): TResult {
+  // Create the computed value - memoize it based on dependencies to prevent recreation
+  const computedValue = useMemo(
+    () => computed(dependencies, computeFn),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [...dependencies]
+  );
+
+  const [state, setState] = useState<TResult>(() => computedValue.get());
+
+  useEffect(() => {
+    const unsubscribe = computedValue.subscribe((newValue) => {
+      setState(newValue);
+    });
+
+    return () => {
+      unsubscribe();
+    };
+  }, [computedValue]);
+
+  return state;
+}

package/src/use-react/hooks/useDerive.ts

@@ -0,0 +1,15 @@
+import { useMemo } from "react";
+
+import { useChunk } from "./useChunk";
+import type { Chunk } from "../../core/core";
+
+/**
+ * A hook for creating a read-only derived value from a chunk.
+ * Ensures reactivity and updates when the source chunk changes.
+ */
+export function useDerive<T, D>(chunk: Chunk<T>, fn: (value: T) => D): D {
+  const derivedChunk = useMemo(() => chunk.derive(fn), [chunk, fn]);
+  const [derivedValue] = useChunk(derivedChunk);
+
+  return derivedValue;
+}

package/src/use-react/index.ts

@@ -0,0 +1,9 @@
+export { useChunk } from './hooks/useChunk'
+export { useDerive } from './hooks/useDerive'
+export { useComputed } from './hooks/useComputed'
+
+export { useChunkValue } from './hooks/useChunkValue'
+export { useChunkProperty } from './hooks/useChunkProperty'
+export { useChunkValues } from './hooks/useChunkValues'
+
+export { useAsyncChunk } from './hooks/useAsyncChunk'

package/tsconfig.json

@@ -5,12 +5,19 @@
     "moduleResolution": "Node",
     "outDir": "./dist",
     "declaration": true,
-    "declarationDir": "./dist/types",
+    "declarationDir": "./dist",
+    "baseUrl": "./src",
+    "paths": {
+      "stunk/middleware": ["middleware"],
+      "stunk/react": ["use-react"]
+    },
     "typeRoots": ["./node_modules/@types", "./types"],
     "strict": true,
+    "skipLibCheck": true,
+    "jsx": "react",
     "esModuleInterop": true,
-    "skipLibCheck": true
+    "allowSyntheticDefaultImports": true
   },
-  "include": ["src/**/*", "types/stunk.d.ts"],
+  "include": ["src/**/*"],
   "exclude": ["node_modules", "dist"]
 }

package/types/stunk.d.ts

@@ -1,12 +0,0 @@
-declare module 'stunk' {
-  export type Subscriber<T> = (newValue: T) => void;
-
-  export interface Chunk<T> {
-    get: () => T;
-    set: (value: T) => void;
-    subscribe: (callback: Subscriber<T>) => () => void;
-    derive?: <D>(fn: (value: T) => D) => Chunk<D>;
-  }
-
-  export function chunk<T>(initialValue: T): Chunk<T>;
-}