- {message.user.name}: {message.content}
-
- )}
- />
- )
-}
-```
-
-### ChatInput
-
-Entrada para enviar mensajes:
-
-```tsx
-import { ChatInput } from "@effectify/chat-solid/components/chat-input"
-import { useChatRoom } from "@effectify/chat-solid/hooks/use-chat-room"
-
-function MessageInput() {
- const { sendMessage, isConnected } = useChatRoom()
- return (
-
- (
-
- )
-}
-```
diff --git a/apps/docs/src/content/docs/es/solid/packages/solid-effect-atom.md b/apps/docs/src/content/docs/es/solid/packages/solid-effect-atom.md
new file mode 100644
index 00000000..4d1efade
--- /dev/null
+++ b/apps/docs/src/content/docs/es/solid/packages/solid-effect-atom.md
@@ -0,0 +1,188 @@
+---
+title: "@effectify/solid-effect-atom"
+description: Herramientas reactivas para Effect con SolidJS
+sidebar:
+ label: "@effectify/solid-effect-atom"
+ order: 1
+---
+
+Bindings de SolidJS para la primitiva `Atom` de Effect. Esta librería permite utilizar el estado reactivo de Effect (`Atom`) dentro de componentes SolidJS de manera eficiente y segura.
+
+## Instalación
+
+```bash
+npm install @effectify/solid-effect-atom @effect-atom/atom effect solid-js
+```
+
+## Configuración
+
+Para usar los átomos, debes envolver tu aplicación (o la parte que los use) con `RegistryProvider`. Esto provee el contexto necesario para el registro de átomos.
+
+```tsx
+import { RegistryProvider } from "@effectify/solid-effect-atom"
+
+function App() {
+ return (
+ Usuarios en línea
-
-
- {user.name}
-
- )}
- />
-
+
+ )
+}
+```
+
+## Uso Avanzado
+
+### useAtomSet
+
+Útil cuando solo necesitas actualizar el átomo sin suscribirte a sus cambios.
+
+```tsx
+import { useAtomSet } from "@effectify/solid-effect-atom"
+
+function ResetButton() {
+ const setCount = useAtomSet(counterAtom)
+ return
+}
+```
+
+### useAtomSubscribe
+
+Se suscribe a los cambios del átomo manualmente. Útil para efectos secundarios (logging, analytics, etc.).
+
+```tsx
+import { useAtomSubscribe } from "@effectify/solid-effect-atom"
+
+function Logger() {
+ useAtomSubscribe(counterAtom, (val) => {
+ console.log("Counter changed:", val)
+ })
+ return null
+}
+```
+
+### useAtomMount
+
+Monta manualmente un átomo. Útil si quieres mantener un átomo vivo en el registro sin leer su valor.
+
+```tsx
+import { useAtomMount } from "@effectify/solid-effect-atom"
+
+function Keeper() {
+ useAtomMount(counterAtom)
+ return null
+}
+```
+
+### useAtomInitialValues
+
+Útil para SSR o inicializar estado desde props.
+
+```tsx
+import { useAtomInitialValues } from "@effectify/solid-effect-atom"
+
+function Initializer() {
+ useAtomInitialValues([[counterAtom, 100]])
+ return null
+}
+```
+
+### useAtomRefresh
+
+Fuerza la reevaluación o reinicio de un átomo.
+
+```tsx
+import { useAtomRefresh } from "@effectify/solid-effect-atom"
+
+function Refresher() {
+ const refresh = useAtomRefresh(counterAtom)
+ return
+}
+```
+
+### useAtomRef
+
+Para trabajar con referencias mutables (`AtomRef`).
+
+```tsx
+import * as AtomRef from "@effect-atom/atom/AtomRef"
+import { useAtomRef } from "@effectify/solid-effect-atom"
+
+const configRef = AtomRef.make({ theme: "dark" })
+
+function Config() {
+ const config = useAtomRef(configRef)
+
+ return (
+
+ )
+}
+```
+
+## Referencia de API
+
+### Hooks
+
+- **`useAtom(atom)`**: Retorna `[accessor, setter]`.
+- **`useAtomValue(atom, selector?)`**: Retorna `accessor`.
+- **`useAtomSet(atom)`**: Retorna solo el `setter`.
+- **`useAtomSubscribe(atom, callback)`**: Se suscribe a cambios.
+- **`useAtomMount(atom)`**: Monta el átomo en el registro.
+- **`useAtomInitialValues(values)`**: Inicializa átomos en el registro actual.
+- **`useAtomRefresh(atom)`**: Retorna una función para refrescar el átomo.
+- **`useAtomRef(ref)`**: Se suscribe a un `AtomRef`.
+
+### Componentes
+
+- **`RegistryProvider`**: Proveedor de contexto para el registro de átomos.
+
+---
+
+> **Nota**: Esta librería está diseñada para funcionar con Effect v3 y `@effect-atom/atom`.
diff --git a/apps/docs/src/content/docs/es/solid/reference/solid-effect-atom.md b/apps/docs/src/content/docs/es/solid/reference/solid-effect-atom.md
new file mode 100644
index 00000000..251e9bec
--- /dev/null
+++ b/apps/docs/src/content/docs/es/solid/reference/solid-effect-atom.md
@@ -0,0 +1,119 @@
+---
+title: "@effectify/solid-effect-atom"
+description: Referencia de API para @effectify/solid-effect-atom
+sidebar:
+ label: Solid Effect Atom Reference
+---
+
+## Hooks
+
+### useAtom
+
+Se suscribe a un átomo y retorna una tupla `[accessor, setter]`.
+
+```ts
+function useAtomCount: {count()}
+Doubled: {doubled()}
+
-
- )
-}
-```
-
-## Components
-
-### ChatProvider
-
-The root provider that manages chat state and WebSocket connections:
-
-```tsx
-import { ChatProvider } from "@effectify/chat-solid/components/chat-provider"
-
-function App() {
- return (
-
-
-
-
-
-
-
-
- )
-}
-```
-
-### ChatMessages
-
-Displays a list of chat messages with proper formatting:
-
-```tsx
-import { ChatMessages } from "@effectify/chat-solid/components/chat-messages"
-import { useChatRoom } from "@effectify/chat-solid/hooks/use-chat-room"
-
-function MessageArea() {
- const { messages } = useChatRoom()
-
- return (
-
- {message.user.name}: {message.content}
-
- )}
- />
- )
-}
-```
-
-### ChatInput
-
-Input component for sending messages:
-
-```tsx
-import { ChatInput } from "@effectify/chat-solid/components/chat-input"
-import { useChatRoom } from "@effectify/chat-solid/hooks/use-chat-room"
-
-function MessageInput() {
- const { sendMessage, isConnected } = useChatRoom()
-
- return (
-
- (
-
- )
-}
-```
-
-## Hooks
-
-### useChatRoom
-
-Main hook for accessing chat room state and actions:
-
-```tsx
-import { useChatRoom } from "@effectify/chat-solid/hooks/use-chat-room"
-
-function ChatComponent() {
- const {
- // State
- messages,
- users,
- currentUser,
- isConnected,
- isLoading,
- error,
-
- // Actions
- sendMessage,
- joinRoom,
- leaveRoom,
-
- // Typing indicators
- typingUsers,
- startTyping,
- stopTyping,
- } = useChatRoom()
-
- const handleSendMessage = (content: string) => {
- sendMessage({ content, type: "text" })
- }
-
- return (
- Online Users
-
-
- {user.name}
-
- )}
- />
- Error: {error()?.message}
- Connected: {isConnected() ? "Yes" : "No"}
- Messages: {messages().length}
- Users: {users().length}
-
-
- {(message) => (
-
-
- )
-}
-```
-
-## Reactive Patterns
-
-### Real-time Message Updates
-
-```tsx
-import { createEffect } from "solid-js"
-
-function ChatNotifications() {
- const { messages } = useChatRoom()
-
- createEffect(() => {
- const latestMessage = messages()[messages().length - 1]
- if (latestMessage && latestMessage.userId !== currentUser()?.id) {
- // Show notification for new message
- new Notification(`New message from ${latestMessage.user.name}`)
- }
- })
-
- return null
-}
-```
-
-### Typing Indicators
-
-```tsx
-import { createEffect, createSignal } from "solid-js"
-
-function TypingIndicator() {
- const { typingUsers, startTyping, stopTyping } = useChatRoom()
- const [isTyping, setIsTyping] = createSignal(false)
-
- let typingTimeout: number
-
- const handleInputChange = (value: string) => {
- if (value.length > 0 && !isTyping()) {
- setIsTyping(true)
- startTyping()
- }
-
- clearTimeout(typingTimeout)
- typingTimeout = setTimeout(() => {
- setIsTyping(false)
- stopTyping()
- }, 3000)
- }
-
- return (
-
- {message.content}
-
-
- )}
-
- handleInputChange(e.currentTarget.value)}
- placeholder="Type a message..."
- />
- 0}>
-
-
- )
-}
-```
-
-### Message Reactions
-
-```tsx
-import { MessageReactions } from "@effectify/chat-solid/components/message-reactions"
-
-function MessageWithReactions(props: { message: Message }) {
- const { reactToMessage } = useChatMessages()
-
- return (
-
- )
-}
-```
-
-## Services
-
-### ChatService
-
-Effect-based service for chat operations:
-
-```tsx
-import { ChatService } from "@effectify/chat-solid/services/chat-service"
-import { Effect } from "effect"
-
-// Send a message
-const sendMessageEffect = ChatService.sendMessage({
- roomId: "room-123",
- content: "Hello, world!",
- type: "text",
-})
-
-// Join a room
-const joinRoomEffect = ChatService.joinRoom("room-123")
-
-// Get message history
-const getHistoryEffect = ChatService.getMessageHistory({
- roomId: "room-123",
- limit: 50,
- before: new Date(),
-})
-
-// Usage in component
-function ChatComponent() {
- const sendMessage = (content: string) => {
- Effect.runPromise(
- sendMessageEffect.pipe(
- Effect.catchAll((error) => {
- console.error("Failed to send message:", error)
- return Effect.succeed(null)
- }),
- ),
- )
- }
-
- return
- {typingUsers().map((u) => u.name).join(", ")}
- {typingUsers().length === 1 ? " is" : " are"} typing...
-
- {/* component JSX */}
-}
-```
-
-## Advanced Features
-
-### File Uploads
-
-```tsx
-import { FileUpload } from "@effectify/chat-solid/components/file-upload"
-
-function ChatWithFiles() {
- const { sendMessage } = useChatRoom()
-
- const handleFileUpload = (file: File) => {
- sendMessage({
- type: "file",
- content: file.name,
- fileData: file,
- })
- }
-
- return (
-
-
- )
-}
-```
-
-### Message Search
-
-```tsx
-import { createMemo, createSignal } from "solid-js"
-
-function MessageSearch() {
- const { messages } = useChatRoom()
- const [searchTerm, setSearchTerm] = createSignal("")
-
- const filteredMessages = createMemo(() => {
- const term = searchTerm().toLowerCase()
- if (!term) return messages()
-
- return messages().filter((message) =>
- message.content.toLowerCase().includes(term) ||
- message.user.name.toLowerCase().includes(term)
- )
- })
-
- return (
-
- setSearchTerm(e.currentTarget.value)}
- placeholder="Search messages..."
- />
-
- {(message) => (
-
- )}
-
-
- )
-}
-```
-
-## Configuration
-
-### WebSocket Configuration
-
-```tsx
-const chatConfig = {
- websocketUrl: 'ws://localhost:3001',
- reconnectAttempts: 5,
- reconnectDelay: 1000,
- heartbeatInterval: 30000,
- messageQueueSize: 100,
- typingTimeout: 3000
-}
-
-
-
- )}
- >
- Chat Error
-{error.message}
- -
-
- )
-}
-```
-
-## Best Practices
-
-### 1. Handle Connection States
-
-```tsx
-function ChatStatus() {
- const { isConnected, error } = useChatRoom()
-
- return (
-
- )
-}
-```
-
-### 2. Implement Message Queuing
-
-```tsx
-function ReliableMessageSender() {
- const { sendMessage, isConnected } = useChatRoom()
- const [messageQueue, setMessageQueue] = createSignal
-
- {(virtualItem) => (
-
-
-
-
- )}
-
+
+ )
+}
+```
+
+## Advanced Usage
+
+### useAtomSet
+
+Useful when you only need to update the atom without subscribing to its changes.
+
+```tsx
+import { useAtomSet } from "@effectify/solid-effect-atom"
+
+function ResetButton() {
+ const setCount = useAtomSet(counterAtom)
+ return
+}
+```
+
+### useAtomSubscribe
+
+Subscribes to atom changes manually. Useful for side effects (logging, analytics, etc.).
+
+```tsx
+import { useAtomSubscribe } from "@effectify/solid-effect-atom"
+
+function Logger() {
+ useAtomSubscribe(counterAtom, (val) => {
+ console.log("Counter changed:", val)
+ })
+ return null
+}
+```
+
+### useAtomMount
+
+Manually mounts an atom. Useful if you want to keep an atom alive in the registry without rendering its value.
+
+```tsx
+import { useAtomMount } from "@effectify/solid-effect-atom"
+
+function Keeper() {
+ useAtomMount(counterAtom)
+ return null
+}
+```
+
+### useAtomInitialValues
+
+Useful for SSR or initializing state from props.
+
+```tsx
+import { useAtomInitialValues } from "@effectify/solid-effect-atom"
+
+function Initializer() {
+ useAtomInitialValues([[counterAtom, 100]])
+ return null
+}
+```
+
+### useAtomRefresh
+
+Forces an atom to re-evaluate or reset.
+
+```tsx
+import { useAtomRefresh } from "@effectify/solid-effect-atom"
+
+function Refresher() {
+ const refresh = useAtomRefresh(counterAtom)
+ return
+}
+```
+
+### useAtomRef
+
+For working with mutable references (`AtomRef`).
+
+```tsx
+import * as AtomRef from "@effect-atom/atom/AtomRef"
+import { useAtomRef } from "@effectify/solid-effect-atom"
+
+const configRef = AtomRef.make({ theme: "dark" })
+
+function Config() {
+ const config = useAtomRef(configRef)
+
+ return (
+
+ )
+}
+```
+
+## API Reference
+
+### Hooks
+
+- **`useAtom(atom)`**: Returns `[accessor, setter]`.
+- **`useAtomValue(atom, selector?)`**: Returns `accessor`.
+- **`useAtomSet(atom)`**: Returns only the `setter`.
+- **`useAtomSubscribe(atom, callback)`**: Subscribes to changes.
+- **`useAtomMount(atom)`**: Mounts the atom in the registry.
+- **`useAtomInitialValues(values)`**: Initializes atoms in the current registry.
+- **`useAtomRefresh(atom)`**: Returns a function to refresh the atom.
+- **`useAtomRef(ref)`**: Subscribes to an `AtomRef`.
+
+### Components
+
+- **`RegistryProvider`**: Context provider for atom registry.
+
+---
+
+> **Note**: This library is designed to work with Effect v3 and `@effect-atom/atom`.
diff --git a/apps/docs/src/content/docs/solid/reference/solid-effect-atom.md b/apps/docs/src/content/docs/solid/reference/solid-effect-atom.md
new file mode 100644
index 00000000..28aef143
--- /dev/null
+++ b/apps/docs/src/content/docs/solid/reference/solid-effect-atom.md
@@ -0,0 +1,119 @@
+---
+title: "@effectify/solid-effect-atom"
+description: API Reference for @effectify/solid-effect-atom
+sidebar:
+ label: Solid Effect Atom Reference
+---
+
+## Hooks
+
+### useAtom
+
+Subscribes to an atom and returns a tuple of `[accessor, setter]`.
+
+```ts
+function useAtomCount: {count()}
+Doubled: {doubled()}
+
+
+ )
+}
+
+function DoubledCounter() {
+ const doubled = useAtomValue(counterAtom, (n: number) => n * 2)
+ return (
+ Counter (useAtom)
+{count()}
+
+
+
+
+
+
+ )
+}
+
+function InitialValuesDemo() {
+ useAtomInitialValues([[textAtom, "Overridden Initial Value"]])
+ const [text] = useAtom(textAtom)
+
+ return (
+ Doubled (useAtomValue)
+{doubled()}
+Derived from counter value * 2
+
+
+ )
+}
+
+function RefreshDemo() {
+ const refresh = useAtomRefresh(counterAtom)
+ return (
+ Initial Values
+"{text()}"
+Initialized via useAtomInitialValues
+
+
+ )
+}
+
+function AtomRefDemo() {
+ const state = useAtomRef(refAtom)
+
+ return (
+ Refresh Atom
+Forces re-evaluation/reset of the atom
+ +
+
+ )
+}
+
+function SetOnlyDemo() {
+ const setCount = useAtomSet(setOnlyAtom)
+ const count = useAtomValue(setOnlyAtom)
+
+ return (
+ AtomRef
+
+
+
+ Count: {state().count}
+Name: {state().name}
+
+
+ )
+}
+
+function SubscribeDemo() {
+ const [logs, setLogs] = createSignalSet Only (useAtomSet)
+{count()}
+ +
+
+ )
+}
+
+function MountDemo() {
+ // This atom will log when mounted/unmounted if we added effects to it
+ // For this demo, we just show that useAtomMount can be called
+ useAtomMount(mountAtom)
+
+ return (
+ Subscribe (useAtomSubscribe)
+ +
+ {logs().map((log) =>
+ {log}
)}
+ {logs().length === 0 && No changes yet...
}
+
+
+ )
+}
+
+function AtomDemo() {
+ return (
+ Mount (useAtomMount)
+Manually mounts an atom without reading its value.
+
+
+ Atom Mounted
+
+
+
+
+
+ + + Effect Atom + {" "} + Demo +
+ ++ Demonstrating @effectify/solid-effect-atom v0.3.0 +
+ +
+
+
-
- )
-}
+```tsx
+import { RegistryProvider } from "@effectify/solid-effect-atom"
function App() {
return (
Count: {count()}
- -Hello, {name()}!
+```ts +import * as Atom from "@effect-atom/atom/Atom" + +const counterAtom = Atom.make(0) ``` ### useAtom -Get both the current value and a setter function for an atom. +Hook to read and write an atom. Similar to Solid's `createSignal`. ```tsx -const [count, setCount] = useAtom(() => countAtom) -``` +import { useAtom } from "@effectify/solid-effect-atom" -### useAtomSet - -Get only the setter function for an atom. +function Counter() { + const [count, setCount] = useAtom(counterAtom) -```tsx -const setCount = useAtomSet(() => countAtom) + return +} ``` -## Advanced Features - -### Async Atoms +### useAtomValue -Handle async operations with built-in loading states: +Hook to only read an atom's value. You can pass a selector function to transform the value (computed). ```tsx -import { Effect } from "effect" -import { useAtomSuspenseResult } from "@effectify/solid-effect-atom" - -const dataAtom = Atom.fn(() => - Effect.gen(function*() { - const response = yield* Effect.promise(() => fetch("/api/data")) - return yield* Effect.promise(() => response.json()) - }) -) +import { useAtomValue } from "@effectify/solid-effect-atom" -function AsyncData() { - const result = useAtomSuspenseResult(() => dataAtom) +function Display() { + const count = useAtomValue(counterAtom) + const doubled = useAtomValue(counterAtom, (n) => n * 2) return (
- {result.loading &&
)
}
```
-### Computed Atoms
+## Advanced Usage
+
+### useAtomSet
-Create derived state that automatically updates:
+Useful when you only need to update the atom without subscribing to its changes.
```tsx
-const firstNameAtom = Atom.make("John")
-const lastNameAtom = Atom.make("Doe")
-const fullNameAtom = Atom.make((get) => `${get(firstNameAtom)} ${get(lastNameAtom)}`)
+import { useAtomSet } from "@effectify/solid-effect-atom"
-function FullName() {
- const fullName = useAtomValue(() => fullNameAtom)
- return Loading...
} - {result.error &&Error: {result.error.message}
} - {result.data &&Data: {JSON.stringify(result.data)}
} +Count: {count()}
+Doubled: {doubled()}
{fullName()}
+function ResetButton() { + const setCount = useAtomSet(counterAtom) + return } ``` -## Performance Benefits - -SolidJS's fine-grained reactivity system means that atom-solid can update only the specific parts of your UI that depend on changed atoms, without re-rendering entire components. - -### Benchmark Results - -Based on our performance benchmarks: - -- **Atom Creation**: ~2M ops/sec -- **Registry Get**: ~6M ops/sec -- **Registry Set**: ~4M ops/sec -- **Computed Atoms**: ~454K ops/sec -- **Subscriptions**: ~1M ops/sec -- **Memory Usage**: ~5KB per 1000 atoms +### useAtomSubscribe -Run benchmarks yourself: `pnpm benchmark` +Subscribes to atom changes manually. Useful for side effects (logging, analytics, etc.). -### Comparison with React - -| Feature | atom-react | atom-solid | -| -------------- | ---------------------- | -------------------- | -| Re-renders | Component re-renders | Fine-grained updates | -| Performance | Good | Excellent | -| Bundle size | ~15kb | ~12kb | -| Learning curve | Familiar to React devs | SolidJS concepts | +```tsx +import { useAtomSubscribe } from "@effectify/solid-effect-atom" -## Migration from atom-react +function Logger() { + useAtomSubscribe(counterAtom, (val) => { + console.log("Counter changed:", val) + }) + return null +} +``` -### Key Differences +### useAtomMount -#### 1. **Hook Signatures** +Manually mounts an atom. Useful if you want to keep an atom alive in the registry without rendering its value. ```tsx -// atom-react -const value = useAtomValue(myAtom) +import { useAtomMount } from "@effectify/solid-effect-atom" -// atom-solid -const value = useAtomValue(() => myAtom) +function Keeper() { + useAtomMount(counterAtom) + return null +} ``` -#### 2. **Return Values** +### useAtomInitialValues + +Useful for SSR or initializing state from props. ```tsx -// atom-react - Direct values -const count = useAtomValue(countAtom) -return{count}
+import { useAtomInitialValues } from "@effectify/solid-effect-atom"
-// atom-solid - Signal accessors
-const count = useAtomValue(() => countAtom)
-return {count()}
+function Initializer() {
+ useAtomInitialValues([[counterAtom, 100]])
+ return null
+}
```
-#### 3. **Suspense Implementation**
+### useAtomRefresh
+
+Forces an atom to re-evaluate or reset.
```tsx
-// atom-react - Direct Promise throwing
-const result = useAtomSuspense(asyncAtom)
+import { useAtomRefresh } from "@effectify/solid-effect-atom"
-// atom-solid - createResource integration
-const result = useAtomSuspense(() => asyncAtom)
+function Refresher() {
+ const refresh = useAtomRefresh(counterAtom)
+ return
+}
```
-#### 4. **Performance Characteristics**
+### useAtomRef
-- **atom-react**: React reconciliation, component re-renders
-- **atom-solid**: Fine-grained updates, no virtual DOM
+For working with mutable references (`AtomRef`).
-### Migration Steps
-
-1. **Update hook calls**: Add factory functions
-2. **Update JSX**: Add `()` to access signal values
-3. **Update Suspense**: Wrap with SolidJS Suspense components
-4. **Test thoroughly**: Different reactivity model may expose edge cases
+```tsx
+import * as AtomRef from "@effect-atom/atom/AtomRef"
+import { useAtomRef } from "@effectify/solid-effect-atom"
-## Examples
+const configRef = AtomRef.make({ theme: "dark" })
-Check out the [sample application](../../sample/solid) for complete examples including:
+function Config() {
+ const config = useAtomRef(configRef)
-- Counter with computed values
-- Async data fetching
-- Todo list management
-- Shared state between components
+ return (
+
+ )
+}
+```
## API Reference
-### Core Hooks
+### Hooks
-- `useAtomValue` - Read atom values
-- `useAtom` - Read and write atom values
-- `useAtomSet` - Write-only atom access
+- **`useAtom(atom)`**: Returns `[accessor, setter]`.
+- **`useAtomValue(atom, selector?)`**: Returns `accessor`.
+- **`useAtomSet(atom)`**: Returns only the `setter`.
+- **`useAtomSubscribe(atom, callback)`**: Subscribes to changes.
+- **`useAtomMount(atom)`**: Mounts the atom in the registry.
+- **`useAtomInitialValues(values)`**: Initializes atoms in the current registry.
+- **`useAtomRefresh(atom)`**: Returns a function to refresh the atom.
+- **`useAtomRef(ref)`**: Subscribes to an `AtomRef`.
-### Advanced Hooks
+### Components
-- `useAtomSuspenseResult` - Handle async atoms with loading states
-- `useAtomSubscribe` - Subscribe to atom changes for side effects
-- `useAtomMount` - Ensure atoms are mounted and active
+- **`RegistryProvider`**: Context provider for atom registry.
-### Context
+---
-- `RegistryProvider` - Provide atom registry to component tree
-- `useRegistry` - Access the current registry
-
-## Best Practices
-
-1. **Use atom factories**: Always pass a function that returns the atom
- ```tsx
- // ✅ Good
- const value = useAtomValue(() => myAtom)
-
- // ❌ Bad
- const value = useAtomValue(myAtom)
- ```
-
-2. **Prefer computed atoms**: Use computed atoms for derived state
- ```tsx
- // ✅ Good
- const doubledAtom = Atom.make((get) => get(countAtom) * 2)
-
- // ❌ Bad
- const doubled = useAtomValue(() => countAtom, (count) => count * 2)
- ```
-
-3. **Use useAtomSet for write-only operations**: When you only need to update
- ```tsx
- // ✅ Good
- const setCount = useAtomSet(() => countAtom)
-
- // ❌ Bad
- const [, setCount] = useAtom(() => countAtom)
- ```
-
-## Documentation
-
-Full documentation: [https://github.com/devx-op/effectify/tree/master/packages/solid/effect-atom/docs](https://github.com/devx-op/effectify/tree/master/packages/solid/effect-atom/docs)
-
-## License
-
-MIT
-
-## Links
-
-- [Effect Website](https://effect.website)
-- [SolidJS Website](https://solidjs.com)
-- [GitHub Repository](https://github.com/devx-op/effectify)
-
-```
-```
+> **Note**: This library is designed to work with Effect v3 and `@effect-atom/atom`.
diff --git a/packages/solid/effect-atom/docs/advanced-hooks.ts.md b/packages/solid/effect-atom/docs/advanced-hooks.ts.md
deleted file mode 100644
index c44c5f19..00000000
--- a/packages/solid/effect-atom/docs/advanced-hooks.ts.md
+++ /dev/null
@@ -1,381 +0,0 @@
----
-title: "AdvancedHooks.ts"
-parent: "@effectify/solid-effect-atom"
-nav_order: 4
----
-
-# Advanced Hooks
-
-Advanced hooks for complex use cases and async atom management.
-
-## useAtomSuspenseResult
-
-Handle async atoms with built-in loading, success, and error states without throwing.
-
-### Signature
-
-```typescript
-export const useAtomSuspenseResult: (
- atomFactory: () => Atom.Atom
- {result.loading &&
- )
-}
-```
-
-#### With Refresh Functionality
-
-```tsx
-const refreshableDataAtom = Atom.fn(() =>
- Effect.gen(function*() {
- const timestamp = new Date().toLocaleTimeString()
- yield* Effect.sleep("500 millis")
- return `Data loaded at ${timestamp}`
- })
-)
-
-function RefreshableData() {
- const result = useAtomSuspenseResult(() => refreshableDataAtom)
- const refreshData = useAtomSet(() => refreshableDataAtom)
-
- return (
- Loading data...
} - {result.error && ( -- Error: {result.error.message} -
- )} - {result.data && ( -
-
- )}
- Data loaded successfully!
-{JSON.stringify(result.data, null, 2)}
-
- {result.loading &&
- )
-}
-```
-
-#### Error Handling
-
-```tsx
-const riskyAtom = Atom.fn(() =>
- Effect.gen(function*() {
- const shouldFail = Math.random() > 0.5
- if (shouldFail) {
- yield* Effect.fail(new Error("Random failure"))
- }
- return "Success!"
- })
-)
-
-function RiskyOperation() {
- const result = useAtomSuspenseResult(() => riskyAtom)
- const retry = useAtomSet(() => riskyAtom)
-
- return (
- Loading...
} - {result.error &&Error: {result.error.message}
} - {result.data && ( -
-
- )}
- {result.data}
- -
- {result.loading &&
- )
-}
-```
-
----
-
-## useAtomSubscribe
-
-Subscribe to atom changes for side effects without reading the atom value.
-
-### Signature
-
-```typescript
-export const useAtomSubscribe: (
- atomFactory: () => Atom.Atom,
- callback: (value: A) => void,
-) => void
-```
-
-### Parameters
-
-- `atomFactory`: A function that returns the atom to subscribe to
-- `callback`: Function called whenever the atom value changes
-
-### Examples
-
-#### Logging Changes
-
-```tsx
-import { useAtomSubscribe } from "@effectify/solid-effect-atom"
-
-const countAtom = Atom.make(0)
-
-function Logger() {
- useAtomSubscribe(() => countAtom, (count) => {
- console.log(`Count changed to: ${count}`)
- })
-
- return null // This component doesn't render anything
-}
-
-function App() {
- return (
- Attempting operation...
} - {result.error && ( -
-
- )}
- {result.data && (
- - Operation failed: {result.error.message} -
- -- {result.data} -
- )} -
-
- )
-}
-```
-
-#### Local Storage Sync
-
-```tsx
-const userPreferencesAtom = Atom.make({
- theme: "light",
- language: "en",
-})
-
-function LocalStorageSync() {
- useAtomSubscribe(() => userPreferencesAtom, (preferences) => {
- localStorage.setItem("userPreferences", JSON.stringify(preferences))
- })
-
- return null
-}
-```
-
-#### Analytics Tracking
-
-```tsx
-const pageViewAtom = Atom.make("")
-
-function AnalyticsTracker() {
- useAtomSubscribe(() => pageViewAtom, (page) => {
- if (page) {
- // Track page view
- analytics.track("page_view", { page })
- }
- })
-
- return null
-}
-```
-
----
-
-## useAtomMount
-
-Ensure an atom is mounted and active in the registry.
-
-### Signature
-
-```typescript
-export const useAtomMount: (atomFactory: () => Atom.Atom) => void
-```
-
-### Parameters
-
-- `atomFactory`: A function that returns the atom to mount
-
-### Examples
-
-#### Preloading Data
-
-```tsx
-const expensiveDataAtom = Atom.fn(() =>
- Effect.gen(function*() {
- // Expensive computation or API call
- yield* Effect.sleep("2 seconds")
- return "Expensive data"
- })
-)
-
-function DataPreloader() {
- // Mount the atom to start loading immediately
- useAtomMount(() => expensiveDataAtom)
-
- return null
-}
-
-function App() {
- return (
-
-
- )
-}
-```
-
-#### Keeping Atoms Alive
-
-```tsx
-const importantAtom = Atom.make("important data")
-
-function AtomKeeper() {
- // Keep this atom mounted even if no components are using it
- useAtomMount(() => importantAtom)
-
- return null
-}
-```
-
----
-
-## Performance and Best Practices
-
-### When to Use Advanced Hooks
-
-#### useAtomSuspenseResult
-
-- ✅ When you need to handle loading/error states manually
-- ✅ When you want to show custom loading/error UI
-- ✅ When you need to access error details
-- ❌ When you want automatic suspense behavior (use regular hooks instead)
-
-#### useAtomSubscribe
-
-- ✅ For side effects (logging, analytics, storage sync)
-- ✅ When you don't need the atom value in render
-- ✅ For triggering other actions based on atom changes
-- ❌ For rendering data (use `useAtomValue` instead)
-
-#### useAtomMount
-
-- ✅ For preloading expensive atoms
-- ✅ For keeping important atoms alive
-- ✅ For background data fetching
-- ❌ For atoms that are already used by components
-
-### Memory Management
-
-Advanced hooks are automatically cleaned up when components unmount:
-
-```tsx
-function MyComponent() {
- // Subscription is automatically cleaned up on unmount
- useAtomSubscribe(() => myAtom, callback)
-
- // Mount is automatically released on unmount
- useAtomMount(() => expensiveAtom)
-
- return ...
-}
-```
-
-### Error Boundaries
-
-For better error handling with async atoms, consider using error boundaries:
-
-```tsx
-import { ErrorBoundary } from "solid-js"
-
-function App() {
- return (
- Error: {err.message}
}>
-
-
- )
-}
-```
-
----
-
-## Registry Concepts
-
-### What is a Registry?
-
-A registry is the central store that manages atom state and subscriptions. It:
-
-- **Stores atom values**: Keeps track of the current value of each atom
-- **Manages subscriptions**: Handles which components are listening to which atoms
-- **Coordinates updates**: Ensures that all subscribers are notified when atoms change
-- **Handles cleanup**: Automatically cleans up unused atoms and subscriptions
-
-### Registry Lifecycle
-
-1. **Creation**: Registry is created when `RegistryProvider` mounts
-2. **Atom mounting**: Atoms are mounted when first accessed by hooks
-3. **Subscription management**: Components subscribe/unsubscribe as they mount/unmount
-4. **Cleanup**: Unused atoms are cleaned up based on TTL settings
-5. **Disposal**: Registry is disposed when provider unmounts
-
-### Multiple Registries
-
-You can have multiple registries in your application for different scopes:
-
-```tsx
-function App() {
- return (
- Registry timeout resolution: {registry.timeoutResolution}ms
-Default idle TTL: {registry.defaultIdleTTL}ms
-
- {/* Global registry */}
-
-
-
-
-
- )
-}
-```
-
-### Performance Considerations
-
-#### Registry Configuration
-
-- **timeoutResolution**: Lower values = more frequent cleanup checks = higher CPU usage
-- **defaultIdleTTL**: Lower values = more aggressive cleanup = lower memory usage
-- **scheduleTask**: Custom schedulers can optimize for specific use cases
-
-#### Best Practices
-
-1. **Use a single registry per app**: Unless you need isolation, one registry is usually sufficient
-2. **Configure timeouts appropriately**: Balance between memory usage and cleanup overhead
-3. **Avoid direct registry access**: Use hooks instead of direct registry manipulation
-4. **Initialize heavy atoms lazily**: Don't put expensive computations in initial values
-
-### Error Handling
-
-The registry handles errors gracefully:
-
-```tsx
-// Atoms that fail will be marked as failed
-const failingAtom = Atom.fn(() => Effect.fail("Something went wrong"))
-
-function ErrorHandling() {
- const result = useAtomSuspenseResult(() => failingAtom)
-
- if (result.error) {
- return Error: {result.error.message}
- }
-
- return Success: {result.data}
-}
-```
-
-### Testing with Registries
-
-For testing, you can provide a clean registry for each test:
-
-```tsx
-import { Registry } from "@effect-atom/atom"
-import { render } from "@solidjs/testing-library"
-
-test("component with atoms", () => {
- const testRegistry = Registry.make()
-
- render(() => (
-
-
- )
-}
-
-// Usage
-{name}
-{JSON.stringify(value(), null, 2)}
-
-
- )
-}
-```
-
-### 2. SSR State Inspection
-
-```tsx
-// Server-side debugging
-export async function renderApp() {
- const registry = createSSRRegistry()
-
- // Debug preloaded atoms
- const result = await preloadAtoms(registry, criticalAtoms)
- console.log("SSR State:", {
- atoms: result.dehydratedState.length,
- errors: result.errors,
- timeouts: result.timeouts,
- })
-
- return { html, state: result.dehydratedState }
-}
-```
-
-## Error Handling
-
-### 1. Atom Error Boundaries
-
-```tsx
-function AtomErrorBoundary(props: { children: JSX.Element }) {
- return (
- Hydration status: {isHydrated() ? "Hydrated" : "SSR"}
- {/* Your components */} -
-
- )}
- >
- {props.children}
- Atom Error
-
-
-
- Error Details
-{err.stack}
- -
-
- No todos found } -
-
- {(filterOption) => (
-
- )}
-
-
- )
-}
-
-function TodoStats() {
- const stats = useAtomValue(() => todoStatsAtom)
-
- return (
-
- Total: {stats().total}
- Active: {stats().active}
- Completed: {stats().completed}
-
- )
-}
-
-export function TodoApp() {
- return (
-
-
- )
-}
-```
-
-## Shopping Cart
-
-A shopping cart with product catalog, cart management, and checkout.
-
-### Atoms
-
-```tsx
-// atoms/shopping.ts
-import { Atom } from "@effectify/solid-effect-atom"
-import { Effect } from "effect"
-
-export interface Product {
- id: string
- name: string
- price: number
- image: string
- description: string
-}
-
-export interface CartItem {
- product: Product
- quantity: number
-}
-
-// Base atoms
-export const productsAtom = Atom.makeTodo App
-
- 
-
- )
-}
-
-function ProductCatalog() {
- const products = useAtomValue(() => productsAtom)
-
- return (
- {props.product.name}
-{props.product.description}
-${props.product.price.toFixed(2)}
- -
-
- )
-}
-
-function CartItem(props: { item: CartItem }) {
- const updateQuantity = useAtomSet(() => updateQuantityAtom)
- const removeFromCart = useAtomSet(() => removeFromCartAtom)
-
- return (
- Products
-
-
- {(product) =>
-
-
- 
-
- )
-}
-
-function ShoppingCart() {
- const cart = useAtomValue(() => cartAtom)
- const total = useAtomValue(() => cartTotalAtom)
-
- return (
-
-
- {props.item.product.name}
-${props.item.product.price.toFixed(2)}
-
-
- {props.item.quantity}
-
-
-
-
-
- {(item) =>
-
- )
-}
-
-function CartBadge() {
- const itemCount = useAtomValue(() => cartItemCountAtom)
-
- return (
- Shopping Cart
- {cart().length === 0 ?Your cart is empty
: ( - <> -
-
-
- )}
- Total: ${total().toFixed(2)}
- -
- 🛒 {itemCount() > 0 && {itemCount()}}
-
- )
-}
-
-export function ShoppingApp() {
- return (
-
-
-
-
-
-
- )
-}
-```
diff --git a/packages/solid/effect-atom/docs/guides.md b/packages/solid/effect-atom/docs/guides.md
deleted file mode 100644
index 1a5f5b6d..00000000
--- a/packages/solid/effect-atom/docs/guides.md
+++ /dev/null
@@ -1,687 +0,0 @@
----
-title: "Usage Guides"
-parent: "@effectify/solid-effect-atom"
-nav_order: 2
----
-
-# Usage Guides
-
-Practical guides for common patterns and use cases with `@effectify/solid-effect-atom`.
-
-## Table of Contents
-
-- [Getting Started](#getting-started)
-- [State Management Patterns](#state-management-patterns)
-- [Async Operations](#async-operations)
-- [Performance Optimization](#performance-optimization)
-- [Error Handling](#error-handling)
-- [Testing](#testing)
-
-## Getting Started
-
-### Project Setup
-
-1. **Install dependencies**:
-
-```bash
-pnpm add @effectify/solid-effect-atom @effect-atom/atom effect solid-js
-```
-
-2. **Setup your app**:
-
-```tsx
-// src/index.tsx
-import { render } from "solid-js/web"
-import { RegistryProvider } from "@effectify/solid-effect-atom"
-import App from "./App"
-
-render(() => (
- Shopping App
-
-
- )
-}
-```
-
-## State Management Patterns
-
-### 1. Shared State
-
-Share state between multiple components:
-
-```tsx
-// atoms.ts
-export const themeAtom = Atom.make<"light" | "dark">("light")
-
-// Header.tsx
-function Header() {
- const [theme, setTheme] = useAtom(() => themeAtom)
-
- return (
- Counter: {count()}
- - - -
-
- )
-}
-```
-
-### 3. Form State
-
-Manage complex form state:
-
-```tsx
-// atoms.ts
-interface UserForm {
- name: string
- email: string
- age: number
-}
-
-export const userFormAtom = Atom.makeTotal: {stats().total}
-Completed: {stats().completed}
-Remaining: {stats().remaining}
-Progress: {Math.round(stats().completionRate * 100)}%
-
- setUserId(parseInt(e.currentTarget.value))}
- />
-
- {(() => {
- const current = result()
- if (current.loading) return
- )
-}
-```
-
-### 2. Optimistic Updates
-
-```tsx
-// atoms.ts
-export const optimisticTodosAtom = Atom.makeLoading user...
- if (current.error) returnError: {String(current.error)}
- - return ( -
-
- )
- })()}
- {current.data.name}
-{current.data.email}
- -
- {!shouldLoad() ?
- (
-
- ) :
-
- )
-}
-
-function DataDisplay() {
- const result = useAtomSuspenseResult(() => lazyDataAtom)
- // Data only loads when this component mounts
-
- return (
-
- {(() => {
- const current = result()
- if (current.loading) return
- )
-}
-```
-
-## Error Handling
-
-### 1. Graceful Error Recovery
-
-```tsx
-// atoms.ts
-export const apiDataAtom = Atom.fn(() =>
- Effect.gen(function*() {
- const data = yield* Effect.tryPromise(() => fetch("/api/data").then((r) => r.json()))
- return data
- }).pipe(
- Effect.catchAll((error) => Effect.succeed({ error: String(error), data: null })),
- )
-)
-
-// ErrorBoundary.tsx
-function DataWithErrorHandling() {
- const result = useAtomSuspenseResult(() => apiDataAtom)
-
- return (
- Loading...
- if (current.error) returnError loading data
- return{JSON.stringify(current.data, null, 2)}
- })()}
-
- {(() => {
- const current = result()
- if (current.loading) return
- )
-}
-```
-
-### 2. Error Boundaries
-
-```tsx
-// ErrorBoundary.tsx
-import { ErrorBoundary } from "solid-js"
-
-function AppWithErrorBoundary() {
- return (
- Loading...
- - if (current.data?.error) { - return ( -
-
- )
- }
-
- return Failed to load data: {current.data.error}
- -
-
- )}
- >
- Something went wrong
-{err.message}
- -
-
- )
-}
-
-function App() {
- return (
- Count: {count()}
- -
-
- )
-}
-```
-
-### Computed Values
-
-```tsx
-import { Atom, useAtomValue } from "@effectify/solid-effect-atom"
-
-const baseAtom = Atom.make(10)
-const doubledAtom = Atom.make((get) => get(baseAtom) * 2)
-
-function ComputedExample() {
- const base = useAtomValue(() => baseAtom)
- const doubled = useAtomValue(() => doubledAtom)
-
- return (
- Count: {count()}
- - - -
-
- )
-}
-```
-
-### Async Data
-
-```tsx
-import { Atom, useAtomSet, useAtomSuspenseResult } from "@effectify/solid-effect-atom"
-import { Effect } from "effect"
-
-const dataAtom = Atom.fn(() =>
- Effect.gen(function*() {
- yield* Effect.sleep(1000)
- return `Data loaded at ${new Date().toLocaleTimeString()}`
- })
-)
-
-function AsyncExample() {
- const result = useAtomSuspenseResult(() => dataAtom)
- const refresh = useAtomSet(() => dataAtom)
-
- return (
- Base: {base()}
-Doubled: {doubled()}
-
- {(() => {
- const current = result()
- if (current.loading) return
- )
-}
-```
-
-## Performance
-
-`@effectify/solid-effect-atom` is highly optimized:
-
-- **~10M operations/second** for async atom operations
-- **~2KB memory per atom** in stress tests
-- **Fine-grained updates** - only affected components re-render
-- **Automatic cleanup** - no memory leaks
-
-## Comparison with React
-
-| Feature | atom-solid | atom-react |
-| ------------------- | ------------ | --------------- |
-| Bundle Size | ~15KB | ~25KB |
-| Runtime Performance | 20%+ faster | Baseline |
-| Memory Usage | 15%+ less | Baseline |
-| Reactivity | Fine-grained | Component-level |
-| TypeScript | Excellent | Good |
-
-## Migration from atom-react
-
-The APIs are very similar, with the main difference being that atom-solid returns signals:
-
-```tsx
-// atom-react
-const value = useAtomValue(atom)
-return Loading...
- if (current.error) returnError: {String(current.error)}
- returnData: {current.data}
- })()} - -{value}
-
-// atom-solid
-const value = useAtomValue(() => atom)
-return {value()}
// Note the function call
-```
-
-## Best Practices
-
-1. **Use atom factories**: Pass functions to hooks to enable proper reactivity
-2. **Leverage computed atoms**: Create derived state with `Atom.make((get) => ...)`
-3. **Handle async properly**: Use `useAtomSuspenseResult` for async atoms
-4. **Clean up subscriptions**: Use `useAtomSubscribe` for side effects
-5. **Optimize renders**: Take advantage of fine-grained reactivity
-
-## Documentation
-
-### Comprehensive Guides
-
-- [Usage Guides](./guides.md) - Comprehensive usage patterns and best practices
-- [Examples](./examples.md) - Complete examples including Todo App and Shopping Cart
-- [SSR Guide](./ssr-guide.md) - Server-side rendering with SolidStart
-- [Debugging Guide](./debugging-guide.md) - Advanced debugging techniques and tools
-- [Troubleshooting](./troubleshooting.md) - Common problems and solutions
-
-## Troubleshooting
-
-### Common Issues
-
-**Atoms not updating**: Make sure you're using atom factories (`() => atom`) in hooks.
-
-**Memory leaks**: Ensure you're using `RegistryProvider` and not creating registries manually.
-
-**TypeScript errors**: Check that you have the correct peer dependencies installed.
-
-For more detailed troubleshooting, see the [Troubleshooting Guide](./troubleshooting.md).
-
-## Contributing
-
-See the main [Effect Atom repository](https://github.com/tim-smart/effect-atom) for contribution guidelines.
diff --git a/packages/solid/effect-atom/docs/index.ts.md b/packages/solid/effect-atom/docs/index.ts.md
deleted file mode 100644
index ba3af68d..00000000
--- a/packages/solid/effect-atom/docs/index.ts.md
+++ /dev/null
@@ -1,225 +0,0 @@
----
-title: "index.ts"
-parent: "@effectify/solid-effect-atom"
-nav_order: 1
----
-
-# @effectify/solid-effect-atom
-
-**Reactive state management for SolidJS applications using Effect atoms**
-
-`@effectify/solid-effect-atom` provides seamless integration between [Effect](https://effect.website) atoms and [SolidJS](https://solidjs.com) applications, leveraging SolidJS's fine-grained reactivity system for optimal performance.
-
-## Installation
-
-```bash
-npm install @effectify/solid-effect-atom
-# or
-pnpm add @effectify/solid-effect-atom
-# or
-yarn add @effectify/solid-effect-atom
-```
-
-## Quick Start
-
-```tsx
-import { Atom } from "@effect-atom/atom"
-import { RegistryProvider, useAtom, useAtomValue } from "@effectify/solid-effect-atom"
-
-// Create an atom
-const countAtom = Atom.make(0)
-
-function Counter() {
- const [count, setCount] = useAtom(() => countAtom)
-
- return (
-
-
- )
-}
-
-function App() {
- return (
- Count: {count()}
- -Name: {name()}
-} -``` - -### useAtom - -Get both the current value and a setter function for an atom. - -```tsx -import { useAtom } from "@effectify/solid-effect-atom" - -function NameInput() { - const [name, setName] = useAtom(() => nameAtom) - - return ( - setName(e.currentTarget.value)} - /> - ) -} -``` - -### useAtomSet - -Get only the setter function for an atom. - -```tsx -import { useAtomSet } from "@effectify/solid-effect-atom" - -function ResetButton() { - const resetName = useAtomSet(() => nameAtom) - - return ( - - ) -} -``` - -## Advanced Usage - -### Async Atoms with Suspense - -Handle async atoms with built-in loading states. - -```tsx -import { useAtomSuspenseResult } from "@effectify/solid-effect-atom" - -function AsyncData() { - const result = useAtomSuspenseResult(() => dataAtom) - - return ( -
- {result.loading &&
- )
-}
-```
-
-### Atom Subscriptions
-
-Subscribe to atom changes for side effects.
-
-```tsx
-import { useAtomSubscribe } from "@effectify/solid-effect-atom"
-
-function Logger() {
- useAtomSubscribe(() => countAtom, (value) => {
- console.log("Count changed to:", value)
- })
-
- return null
-}
-```
-
-## Performance Benefits
-
-SolidJS's fine-grained reactivity system means that atom-solid can update only the specific parts of your UI that depend on changed atoms, without re-rendering entire components. This results in:
-
-- **Faster updates**: Only affected DOM nodes are updated
-- **Better performance**: No unnecessary re-renders or reconciliation
-- **Smoother UX**: Consistent performance even with complex state
-
-## Comparison with React
-
-| Feature | atom-react | atom-solid |
-| -------------- | ---------------------- | -------------------- |
-| Re-renders | Component re-renders | Fine-grained updates |
-| Performance | Good | Excellent |
-| Bundle size | ~15kb | ~12kb |
-| Learning curve | Familiar to React devs | SolidJS concepts |
-
-## Examples
-
-Check out the [sample application](https://github.com/tim-smart/effect-atom/tree/main/sample/solid) for complete examples including:
-
-- Counter with computed values
-- Async data fetching
-- Todo list management
-- Shared state between components
-
-## API Reference
-
-See the individual hook documentation for detailed API information:
-
-- [Primitives](./Primitives.ts.html) - Core hooks (useAtomValue, useAtom, useAtomSet)
-- [Context](./Context.ts.html) - Registry provider and context
-- [AdvancedHooks](./AdvancedHooks.ts.html) - Advanced hooks for complex use cases
diff --git a/packages/solid/effect-atom/docs/primitives.md b/packages/solid/effect-atom/docs/primitives.md
deleted file mode 100644
index bbb7b410..00000000
--- a/packages/solid/effect-atom/docs/primitives.md
+++ /dev/null
@@ -1,278 +0,0 @@
----
-title: "Primitives.ts"
-parent: "@effectify/solid-effect-atom"
-nav_order: 2
----
-
-# Primitives
-
-Core hooks for integrating Effect atoms with SolidJS components.
-
-## useAtomValue
-
-Read the current value of an atom and subscribe to changes.
-
-### Signature
-
-```typescript
-export const useAtomValue: {
- (atomFactory: () => Atom.Atom): Accessor
- Loading...
} - {result.error &&Error: {result.error.message}
} - {result.data &&Data: {JSON.stringify(result.data)}
} -Hello, {name()}!
-} -``` - -#### With Transform Function - -```tsx -const countAtom = Atom.make(5) - -function DisplayDoubled() { - const doubled = useAtomValue(() => countAtom, (count) => count * 2) - - returnDoubled: {doubled()}
-} -``` - -#### With Computed Atoms - -```tsx -const firstNameAtom = Atom.make("John") -const lastNameAtom = Atom.make("Doe") -const fullNameAtom = Atom.make((get) => `${get(firstNameAtom)} ${get(lastNameAtom)}`) - -function DisplayFullName() { - const fullName = useAtomValue(() => fullNameAtom) - - returnFull name: {fullName()}
-} -``` - ---- - -## useAtom - -Get both the current value and a setter function for an atom. - -### Signature - -```typescript -export const useAtom: ( - atomFactory: () => Atom.Writable
-
- )
-}
-```
-
-#### With Function Updater
-
-```tsx
-function Counter() {
- const [count, setCount] = useAtom(() => countAtom)
-
- return (
- Count: {count()}
- - -
-
- )
-}
-```
-
-#### Form Input
-
-```tsx
-const nameAtom = Atom.make("")
-
-function NameInput() {
- const [name, setName] = useAtom(() => nameAtom)
-
- return (
- setName(e.currentTarget.value)}
- placeholder="Enter your name"
- />
- )
-}
-```
-
----
-
-## useAtomSet
-
-Get only the setter function for an atom. Useful when you only need to update an atom without reading its value.
-
-### Signature
-
-```typescript
-export const useAtomSet: (
- atomFactory: () => Atom.WritableCount: {count()}
- - -
-
-
-
- )
-}
-```
-
----
-
-## Performance Notes
-
-### Fine-grained Reactivity
-
-SolidJS's fine-grained reactivity system ensures that only the specific parts of your UI that depend on changed atoms are updated. This means:
-
-- **No component re-renders**: Unlike React, SolidJS doesn't re-render entire components
-- **Surgical updates**: Only the DOM nodes that need to change are updated
-- **Consistent performance**: Performance remains consistent regardless of component complexity
-
-### Best Practices
-
-1. **Use atom factories**: Always pass a function that returns the atom, not the atom directly:
- ```tsx
- // ✅ Good
- const value = useAtomValue(() => myAtom)
-
- // ❌ Bad
- const value = useAtomValue(myAtom)
- ```
-
-2. **Memoize expensive computations**: Use computed atoms for expensive calculations:
- ```tsx
- // ✅ Good - computed once, cached
- const expensiveAtom = Atom.make((get) => expensiveCalculation(get(dataAtom)))
-
- // ❌ Bad - recalculated on every render
- const value = useAtomValue(() => dataAtom, expensiveCalculation)
- ```
-
-3. **Prefer useAtomSet for write-only operations**: When you only need to update an atom:
- ```tsx
- // ✅ Good - no unnecessary subscription
- const setCount = useAtomSet(() => countAtom)
-
- // ❌ Bad - creates unnecessary subscription
- const [, setCount] = useAtom(() => countAtom)
- ```
diff --git a/packages/solid/effect-atom/docs/ssr-guide.md b/packages/solid/effect-atom/docs/ssr-guide.md
deleted file mode 100644
index a871381b..00000000
--- a/packages/solid/effect-atom/docs/ssr-guide.md
+++ /dev/null
@@ -1,463 +0,0 @@
----
-title: "SSR Guide"
-parent: "@effectify/solid-effect-atom"
-nav_order: 4
----
-
-# Server-Side Rendering (SSR) Guide
-
-Complete guide for using `@effectify/solid-effect-atom` with Server-Side Rendering, including SolidStart integration.
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Basic SSR Setup](#basic-ssr-setup)
-- [SolidStart Integration](#solidstart-integration)
-- [Hydration Strategies](#hydration-strategies)
-- [Best Practices](#best-practices)
-
-## Overview
-
-`@effectify/solid-effect-atom` provides comprehensive SSR support through:
-
-- **HydrationBoundary**: Component for managing client-side hydration
-- **SSR Utilities**: Helper functions for server-side atom preloading
-- **Isomorphic Atoms**: Atoms that behave differently on server vs client
-- **State Serialization**: Safe serialization/deserialization of atom state
-
-## Basic SSR Setup
-
-### 1. Server-Side Rendering
-
-```tsx
-// server.tsx
-import { renderToString } from "solid-js/web"
-import { createSSRRegistry, preloadAtoms, RegistryProvider, serializeState } from "@effectify/solid-effect-atom"
-import { App } from "./App"
-import { criticalAtoms } from "./atoms"
-
-export async function renderApp(url: string) {
- // Create SSR-optimized registry
- const registry = createSSRRegistry({
- timeout: 5000,
- includeErrors: false,
- })
-
- // Preload critical atoms
- const ssrResult = await preloadAtoms(registry, criticalAtoms, {
- timeout: 3000,
- })
-
- // Render app to string
- const html = renderToString(() => (
- {{HTML}}
-
-
-
-
-```
-
-## SolidStart Integration
-
-### 1. Root Component Setup
-
-```tsx
-// src/root.tsx
-import { Suspense } from "solid-js"
-import { Body, ErrorBoundary, FileRoutes, Head, Html, Meta, Routes, Scripts, Title } from "solid-start"
-import { deserializeState, HydrationBoundary, RegistryProvider } from "@effectify/solid-effect-atom"
-
-export default function Root() {
- // Get hydration state from server
- const getHydrationState = () => {
- if (typeof window !== "undefined") {
- const stateElement = document.getElementById("atom-state")
- if (stateElement) {
- return deserializeState(stateElement.textContent || "[]")
- }
- }
- return []
- }
-
- return (
-
-
-
-
- )
-}
-```
-
-### 3. API Routes for Data
-
-```tsx
-// src/routes/api/users/[id].ts
-import { json } from "solid-start/api"
-import type { APIEvent } from "solid-start/api"
-
-export async function GET({ params }: APIEvent) {
- const userId = params.id
-
- // Fetch user data from database
- const user = await fetchUserFromDB(userId)
-
- if (!user) {
- return new Response("User not found", { status: 404 })
- }
-
- return json(user)
-}
-
-async function fetchUserFromDB(id: string) {
- // Your database logic here
- return {
- id,
- name: `User ${id}`,
- email: `user${id}@example.com`,
- }
-}
-```
-
-## Hydration Strategies
-
-### 1. Progressive Hydration
-
-```tsx
-// atoms/progressive.ts
-import { Atom, createSSRAtom, isHydrating } from "@effectify/solid-effect-atom"
-import { Effect } from "effect"
-
-// Critical data that should be SSR'd
-export const criticalDataAtom = Atom.fn(() =>
- Effect.gen(function*() {
- const data = yield* Effect.tryPromise(() => fetch("/api/critical-data").then((r) => r.json()))
- return data
- })
-)
-
-// Non-critical data that can load after hydration
-export const nonCriticalDataAtom = Atom.fn(() =>
- Effect.gen(function*() {
- // Only load after hydration is complete
- if (isHydrating()) {
- return null
- }
-
- const data = yield* Effect.tryPromise(() => fetch("/api/non-critical-data").then((r) => r.json()))
- return data
- })
-)
-
-// Fallback atom for SSR
-export const userPreferencesAtom = createSSRAtom(
- // Server fallback
- { theme: "light", language: "en" },
- // Client atom
- Atom.fn(() =>
- Effect.gen(function*() {
- const prefs = localStorage.getItem("user-preferences")
- return prefs ? JSON.parse(prefs) : { theme: "light", language: "en" }
- })
- ),
-)
-```
-
-### 2. Selective Hydration
-
-```tsx
-// components/SelectiveHydration.tsx
-import { createSignal, onMount } from "solid-js"
-import { isSSR, useAtomValue } from "@effectify/solid-effect-atom"
-import { heavyDataAtom } from "../atoms"
-
-export function HeavyComponent() {
- const [shouldHydrate, setShouldHydrate] = createSignal(false)
-
- // Only hydrate when component becomes visible
- onMount(() => {
- if (!isSSR()) {
- const observer = new IntersectionObserver((entries) => {
- if (entries[0].isIntersecting) {
- setShouldHydrate(true)
- observer.disconnect()
- }
- })
-
- const element = document.getElementById("heavy-component")
- if (element) observer.observe(element)
- }
- })
-
- return (
- User Profile
- {(() => { - const userData = user() - if (!userData) returnLoading...
- - return ( -
-
- )
- })()}
- {userData.name}
-{userData.email}
-
- {shouldHydrate() ?
- )
-}
-
-function HydratedContent() {
- const data = useAtomValue(() => heavyDataAtom)
-
- return (
- Loading heavy content...
}
-
- {/* Heavy content here */}
-
- )
-}
-```
-
-### 3. Error Boundaries for SSR
-
-```tsx
-// components/SSRErrorBoundary.tsx
-import { ErrorBoundary } from "solid-js"
-import { isSSR } from "@effectify/solid-effect-atom"
-
-export function SSRErrorBoundary(props: { children: any }) {
- return (
- {JSON.stringify(data(), null, 2)}
- Server error occurred
- }
-
- return (
-
-
- )
- }}
- >
- {props.children}
- Something went wrong
-{error.message}
- -{value()}
-}
-```
-
-**Solution**: Wrap your app with RegistryProvider:
-
-```tsx
-// ✅ With RegistryProvider
-function App() {
- return (
- {value()}
-}
-```
-
-### Circular Dependency Error
-
-**Problem**: Atoms depend on each other circularly.
-
-```tsx
-// ❌ Circular dependency
-const atomA = Atom.make((get) => get(atomB) + 1)
-const atomB = Atom.make((get) => get(atomA) + 1) // Error!
-```
-
-**Solution**: Restructure dependencies:
-
-```tsx
-// ✅ Use a base atom
-const baseAtom = Atom.make(0)
-const atomA = Atom.make((get) => get(baseAtom) + 1)
-const atomB = Atom.make((get) => get(baseAtom) + 2)
-
-// ✅ Or use a derived pattern
-const configAtom = Atom.make({ a: 1, b: 2 })
-const atomA = Atom.make((get) => get(configAtom).a)
-const atomB = Atom.make((get) => get(configAtom).b)
-```
-
-## Performance Issues
-
-### Slow Rendering
-
-**Problem**: UI updates are slow or janky.
-
-**Diagnosis**: Check for expensive computations in atoms:
-
-```tsx
-// ❌ Expensive computation on every access
-const expensiveAtom = Atom.make((get) => {
- const data = get(dataAtom)
- return data.map((item) => heavyComputation(item)) // Slow!
-})
-```
-
-**Solution**: Optimize computations:
-
-```tsx
-// ✅ Memoize expensive computations
-const expensiveAtom = Atom.make((get) => {
- const data = get(dataAtom)
- return data.map((item) => memoizedHeavyComputation(item))
-})
-
-// ✅ Or split into smaller atoms
-const processedDataAtom = Atom.make((get) => {
- const data = get(dataAtom)
- return data.map(processItem)
-})
-```
-
-### Memory Leaks
-
-**Problem**: Memory usage keeps growing.
-
-**Diagnosis**: Check for atoms that aren't being cleaned up:
-
-```tsx
-// ❌ keepAlive atoms without cleanup
-const persistentAtom = Atom.make(data).pipe(Atom.keepAlive)
-```
-
-**Solution**: Proper cleanup:
-
-```tsx
-// ✅ Auto-dispose atoms (default behavior)
-const autoAtom = Atom.make(data) // Cleaned up when not used
-
-// ✅ Manual cleanup for keepAlive atoms
-onCleanup(() => {
- registry.dispose()
-})
-```
-
-### Too Many Re-renders
-
-**Problem**: Components re-render too frequently.
-
-**Diagnosis**: Check atom dependencies:
-
-```tsx
-// ❌ Atom depends on frequently changing data
-const derivedAtom = Atom.make((get) => {
- const timestamp = get(timestampAtom) // Updates every second
- const data = get(dataAtom)
- return { data, timestamp }
-})
-```
-
-**Solution**: Split dependencies:
-
-```tsx
-// ✅ Separate concerns
-const dataAtom = Atom.make(initialData)
-const timestampAtom = Atom.make(Date.now())
-
-// Only subscribe to what you need
-function MyComponent() {
- const data = useAtomValue(() => dataAtom) // Only updates when data changes
- return {JSON.stringify(data())}
-}
-```
-
-## SolidJS Specific Issues
-
-### Signal vs Atom Confusion
-
-**Problem**: Mixing SolidJS signals with atoms incorrectly.
-
-```tsx
-// ❌ Don't mix signals and atoms directly
-const [signal, setSignal] = createSignal(0)
-const atom = Atom.make((get) => signal()) // Won't react to signal changes
-```
-
-**Solution**: Use atoms consistently:
-
-```tsx
-// ✅ Use atoms for shared state
-const atom = Atom.make(0)
-const [value, setValue] = useAtom(() => atom)
-
-// ✅ Or convert signals to atoms if needed
-const signalAtom = Atom.make(() => signal())
-```
-
-### SSR Hydration Issues
-
-**Problem**: Hydration mismatches between server and client.
-
-```tsx
-// ❌ Different values on server vs client
-const timeAtom = Atom.make(new Date().toISOString())
-```
-
-**Solution**: Use SSR-safe patterns:
-
-```tsx
-// ✅ SSR-safe atom
-const timeAtom = Atom.make(() => {
- if (typeof window === "undefined") {
- return "SSR" // Server value
- }
- return new Date().toISOString() // Client value
-})
-
-// ✅ Or use SSR utilities
-const ssrTimeAtom = createSSRAtom("SSR", clientTimeAtom)
-```
-
-### Suspense Boundary Issues
-
-**Problem**: Suspense boundaries not working with async atoms.
-
-```tsx
-// ❌ Using regular useAtomValue with async atom
-function MyComponent() {
- const data = useAtomValue(() => asyncAtom) // May not suspend properly
- return {data()}
-}
-```
-
-**Solution**: Use proper suspense hooks:
-
-```tsx
-// ✅ Use useAtomSuspense for async atoms
-function MyComponent() {
- const data = useAtomSuspense(() => asyncAtom)
- return {data}
-}
-
-// ✅ Or handle loading states manually
-function MyComponent() {
- const result = useAtomValue(() => asyncAtom)
-
- return (
-
- {result()._tag === "Success" &&
- )
-}
-```
-
-## Getting Help
-
-If you're still experiencing issues:
-
-1. **Check the documentation**: Review the [guides](./guides.md) and [examples](./examples.md)
-2. **Search existing issues**: Look through [GitHub issues](https://github.com/effect-ts/atom/issues)
-3. **Create a minimal reproduction**: Use [StackBlitz](https://stackblitz.com) or [CodeSandbox](https://codesandbox.io)
-4. **Ask for help**: Open a new issue with your reproduction case
-
-## Common Patterns
-
-### Debugging Checklist
-
-When something isn't working:
-
-- [ ] Is the atom created outside the component?
-- [ ] Is the component wrapped in RegistryProvider?
-- [ ] Are you using the correct hook for your use case?
-- [ ] Are there any circular dependencies?
-- [ ] Is TypeScript configured correctly?
-- [ ] Are peer dependencies installed?
-
-### Performance Checklist
-
-When performance is poor:
-
-- [ ] Are expensive computations memoized?
-- [ ] Are atoms split appropriately?
-- [ ] Are you avoiding unnecessary re-renders?
-- [ ] Are keepAlive atoms cleaned up properly?
-- [ ] Is the bundle size reasonable?
diff --git a/packages/solid/effect-atom/package.json b/packages/solid/effect-atom/package.json
index fb1a8514..964edcfe 100644
--- a/packages/solid/effect-atom/package.json
+++ b/packages/solid/effect-atom/package.json
@@ -1,6 +1,6 @@
{
"name": "@effectify/solid-effect-atom",
- "version": "0.2.1",
+ "version": "0.3.0",
"description": "Reactive toolkit for Effect with SolidJS",
"type": "module",
"publishConfig": {
diff --git a/packages/solid/effect-atom/src/advanced-hooks.ts b/packages/solid/effect-atom/src/advanced-hooks.ts
deleted file mode 100644
index 718d51d6..00000000
--- a/packages/solid/effect-atom/src/advanced-hooks.ts
+++ /dev/null
@@ -1,163 +0,0 @@
-/**
- * @since 1.0.0
- */
-
-import type * as Atom from "@effect-atom/atom/Atom"
-import type * as Result from "@effect-atom/atom/Result"
-import * as Cause from "effect/Cause"
-import { type Accessor, createEffect, createMemo, createResource, createSignal, onCleanup } from "solid-js"
-import { useRegistry } from "./context.js"
-
-/**
- * @since 1.0.0
- * @category hooks
- */
-export const useAtomSuspense = {result().value}
}
- {result()._tag === "Initial" && Loading...
}
- {result()._tag === "Failure" && Error occurred
}
- {value()}
- }
-
- render(() => {value()}
- }
-
- render(() => {value()}
- }
-
- render(() => (
-
-
- )
- }
-
- render(() => (
- {count()}
- {doubled()}
-
- {value()}
- }
-
- render(() =>
-
- )
- }
-
- render(() => {count()}
-
-
-
- )
- }
-
- render(() => {count()}
-
-
-
- )
- }
-
- render(() => {value()}
-
- {value()}
- }
-
- render(() => (
- {value()}
- }
-
- render(() => (
- Loading...
- }
-
- return {current.data}
- }
+ describe("useAtomMount", () => {
+ it("mounts the atom", () => {
+ const registry = Registry.make()
+ const atom = Atom.make(0)
- render(() => Loading...
- }
-
- if (current.error) {
- return Error
- }
-
- return {current.data}
- }
-
- render(() => Loading...
- }
-
- if (current.error) {
- return Error
- }
-
- return {current.data}
- }
-
- render(() => {resource()}
- }
-
- render(() => (
- {value().value}
- }
-
- render(() => (
- {value().value}
- }
-
- render(() => (
- {value()._tag}
- }
-
- function ErrorFallback(_error: any) {
- return Error caught
- }
-
- render(() => (
- {value()}
- }
-
- function Result1() {
- const value = useAtomValue(() => atomResult1)
- return Result.match(value(), {
- onSuccess: (value) => {value.value}
,
- onFailure: () => Error
,
- onInitial: () => Loading...
,
- })
- }
-
- function Result2() {
- const value = useAtomValue(() => atomResult2)
- return Result.match(value(), {
- onSuccess: (value) => {value.value}
,
- onFailure: () => Error
,
- onInitial: () => Loading...
,
- })
- }
-
- function Result3() {
- const value = useAtomValue(() => atomResult3)
- return Result.match(value(), {
- onSuccess: (value) => {value.value}
,
- onFailure: () => Error
,
- onInitial: () => Loading...
,
- })
- }
-
- render(() => (
- {value()._tag}
- }
-
- render(() => (
- // provide a fresh registry each time to simulate hydration
- {value()}
- }
-
- // Render multiple components using the same atom
- render(() => (
- {value()}
- }
-
- render(() => (
- {value()}
- }
-
- const { unmount } = render(() => (
- {value()}
- }
-
- // Render components for first 100 atoms
- const components: JSX.Element[] = []
- for (let i = 0; i < 100; i++) {
- components.push({value()}
- }
-
- render(() => (
-