diff --git a/README.md b/README.md index 7ec785f..7629dc9 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,6 @@ React Alien Signals is a **TypeScript** library that provides hooks built on top - [Basic Signals](#basic-signals) - [Computed Signals](#computed-signals) - [Effects & Effect Scopes](#effects--effect-scopes) - - [Async Signals](#async-signals) - - [Computed Collections](#computed-collections) - [React Hooks](#react-hooks) - [Contributing](#contributing) - [License](#license) @@ -28,14 +26,11 @@ React Alien Signals is a **TypeScript** library that provides hooks built on top ## Features -- **Basic Signals**: Create and manage reactive state with `createSignal`. -- **Computed Signals**: Derive reactive values based on other signals using `createComputed`. -- **Effects & Effect Scopes**: Run side effects in response to state changes with `createEffect` and manage multiple effects with `createSignalScope`. -- **Async Signals**: Handle asynchronous state with `createAsyncComputed` and `createAsyncEffect`. -- **Computed Collections**: Manage reactive arrays and sets with `createComputedArray` and `createComputedSet`. -- **Equality Computed**: Optimize re-renders with `createEqualityComputed`. -- **React Integration**: Utilize React hooks like `useSignal`, `useSignalValue`, and `useSetSignal` for seamless state management. -- **TypeScript Support**: Fully typed APIs for type safety and IntelliSense. +- **Basic Signals**: Create and manage reactive state with `createSignal` +- **Computed Signals**: Derive reactive values based on other signals using `createComputed` +- **Effects & Effect Scopes**: Run side effects in response to state changes with `createEffect` and manage multiple effects with `createSignalScope` +- **React Integration**: Utilize hooks like `useSignal`, `useSignalValue`, and `useSetSignal` for seamless state management +- **TypeScript Support**: Fully typed APIs for type safety and IntelliSense ## Installation @@ -49,161 +44,70 @@ npm install react-alien-signals alien-signals ### Basic Signals -Create a writable signal and use it within your components. +Create a writable signal and use it within your components: ```tsx -import React from "react"; import { createSignal, useSignal } from "react-alien-signals"; -const countSignal = createSignal(0); +const count = createSignal(0); function Counter() { - const [count, setCount] = useSignal(countSignal); - + const [value, setValue] = useSignal(count); + return ( -
-

Count: {count}

- -
+ ); } - -export default Counter; ``` ### Computed Signals -Derive reactive values based on other signals. +Create derived state that automatically updates: ```tsx -import React from "react"; -import { - createSignal, - createComputed, - useSignalValue, -} from "react-alien-signals"; +import { createSignal, createComputed, useSignalValue } from "react-alien-signals"; -const countSignal = createSignal(1); -const doubleCount = createComputed(() => countSignal.get() * 2); +const count = createSignal(1); +const double = createComputed(() => count() * 2); function Display() { - const double = useSignalValue(doubleCount); - - return
Double Count: {double}
; + const doubleValue = useSignalValue(double); + return
Double: {doubleValue}
; } - -export default Display; ``` ### Effects & Effect Scopes -Run side effects in response to state changes and manage multiple effects. +Run side effects in response to signal changes: ```tsx -import React from "react"; -import { - createSignal, - createEffect, - useSignalScope, -} from "react-alien-signals"; +import { createSignal, createEffect, useSignalScope } from "react-alien-signals"; -const countSignal = createSignal(0); +const count = createSignal(0); function Logger() { - const scope = useSignalScope(); - - scope.run(() => { + useSignalScope(() => { createEffect(() => { - console.log("Count changed:", countSignal.get()); + console.log('Count changed:', count()); }); }); - + return null; } - -export default Logger; -``` - -### Async Signals - -Handle asynchronous state with async computed signals and effects. - -```tsx -import React from "react"; -import { - createSignal, - unstable_createAsyncComputed, - unstable_useAsyncComputedValue, -} from "react-alien-signals"; - -const dataSignal = createSignal("initial"); - -const asyncData = unstable_createAsyncComputed(async function* () { - yield dataSignal; - const response = await fetch( - `https://api.example.com/data?query=${dataSignal.get()}`, - ); - const data = await response.text(); - return data; -}); - -function AsyncDisplay() { - const data = unstable_useAsyncComputedValue(asyncData); - - return
Async Data: {data ?? "Loading..."}
; -} - -export default AsyncDisplay; -``` - -### Computed Collections - -Manage reactive arrays and sets. - -```tsx -import React from "react"; -import { - createSignal, - unstable_createComputedArray, - unstable_createComputedSet, - useSignalValue, -} from "react-alien-signals"; - -const numbersSignal = createSignal([1, 2, 3]); -const doubledNumbers = unstable_createComputedArray( - numbersSignal, - (itemSignal) => () => itemSignal.get() * 2, -); - -const numberSetSignal = createSignal(new Set([1, 2])); -const doubledSet = unstable_createComputedSet(numberSetSignal); - -function CollectionsDisplay() { - const doubled = useSignalValue(doubledNumbers); - const doubledSetValue = useSignalValue(doubledSet); - - return ( -
-

Doubled Numbers: {doubled.join(", ")}

-

Doubled Set: {[...doubledSetValue].join(", ")}

-
- ); -} - -export default CollectionsDisplay; ``` ## React Hooks React Alien Signals provides several hooks to interact with signals: -- `useSignal(signal)`: Returns `[value, setValue]`. -- `useSignalValue(signal)`: Returns the current value (read-only). -- `useSetSignal(signal)`: Returns a setter function (write-only). -- `useSignalEffect(effectFn)`: Runs a side effect based on signal changes. -- `useSignalScope()`: Manages effect scopes within a component. -- `unstable_useAsyncComputedValue(asyncComputed)`: Retrieves the value from an async computed signal. -- `unstable_useAsyncEffect(asyncEffectFn)`: Runs an asynchronous effect. +- `useSignal(signal)`: Returns `[value, setValue]` tuple for reading and writing +- `useSignalValue(signal)`: Returns the current value (read-only) +- `useSetSignal(signal)`: Returns a setter function (write-only) +- `useSignalEffect(effectFn)`: Runs a side effect based on signal changes +- `useSignalScope(callback)`: Manages effect scopes within a component +- `useComputed(getter)`: Creates and subscribes to a computed signal ## Contributing @@ -215,5 +119,4 @@ Contributions are welcome! Please read the [Contributing Guidelines](CONTRIBUTIN ## Acknowledgements -- [Alien Signals](https://github.com/stackblitz/alien-signals) by [StackBlitz](https://stackblitz.com) for the foundational signal implementation. -- [Jotai](https://github.com/pmndrs/jotai) for inspiring the API design. +- [Alien Signals](https://github.com/stackblitz/alien-signals) by [StackBlitz](https://stackblitz.com) for the foundational signal implementation diff --git a/package.json b/package.json index 3ecb38f..def70c2 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "react-alien-signals", - "version": "0.2.0", + "version": "0.2.1", "type": "module", "types": "./dist/index.d.ts", "module": "./dist/index.js",