createComputed

Author: LadyBluenotes

src/routes/reference/secondary-primitives/create-computed.mdx

@@ -15,30 +15,112 @@ description: >-
   primitives and handle side effects that respond to dependencies.
 ---
 
-```ts
-import { createComputed } from "solid-js"
+Creates a reactive computation that runs immediately before render, mainly used to synchronize or write to other reactive primitives, not for DOM side-effects.
 
-function createComputed<T>(fn: (v: T) => T, value?: T): void
+## Import
 
+```typescript
+import { createComputed } from "solid-js";
 ```
 
-`createComputed` creates a new computation that immediately runs the given function in a tracking scope, thus automatically tracking its dependencies, and automatically reruns the function whenever the dependencies changes. 
-The function gets called with an argument equal to the value returned from the function's last execution, or on the first call, equal to the optional second argument to `createComputed`. 
-Note that the return value of the function is not otherwise exposed; in particular, createComputed has no return value.
+## Type Signature
 
-`createComputed` is the most immediate form of reactivity in Solid, and is most useful for building other reactive primitives. 
-For example, some other Solid primitives are built from `createComputed`. 
-However, it should be used with care, as `createComputed` can easily cause more unnecessary updates than other reactive primitives. 
-Before using it, consider the closely related primitives [`createMemo`](/reference/basic-reactivity/create-memo) and [`createRenderEffect`](/reference/secondary-primitives/create-render-effect).
+```typescript
+function createComputed<Next, Init = Next>(
+ *   fn: (v: Init | Next) => Next,
+ *   value?: Init,
+ *   options?: { name?: string }
+ * ): void;
+```
+
+## Parameters
+
+### `fn`
+
+**Type:** `(v: Init | Next) => Next`
+
+The computation function.
+ Receives the previous value (or initial value, if set) and returns a new value. 
+ Runs reactively when dependencies change.
+
+### `value` 
+
+**Type:** `Init`
+
+Initial value for the computation. 
+If provided, `fn` will never receive `undefined` as its first argument.
+
+### `options` 
+
+**Type:** `{ name?: string }` (optional)
+
+Used in development to identify the computed effect.
+
+## Return Value
+
+**Type:** `void`
+
+Registers a computation in the reactive system. Does _not_ return a value.
+
+## Usage
+
+```typescript
+import { createComputed } from "solid-js";
+
+createComputed((prev) => {
+  // Compute the next value based on the previous value
+  return prev + 1;
+}, 0);
+```
+
+## Advanced Usage
+
+### Using an Initial Value
+
+```typescript
+import { createComputed } from "solid-js";
+
+createComputed((prev) => {
+  // Compute the next value based on the previous value
+  return prev + 1;
+}, 0);
+```
+
+### Synchronizing State
+
+```typescript
+const [source, setSource] = createSignal("initial");
+const [copy, setCopy] = createSignal("");
+
+createComputed(() => setCopy(source()));
+```
+
+## Common Patterns
+
+- Writing to other reactive primitives, such as signals or stores, based on dependencies.
+- Performing computations that must happen before render, not after.
+- Setting up synchronization between multiple signals without side effects.
+
+## How It Works 
+
+`createComputed` defines a reactive computation that tracks any signals or memos accessed within its function. 
+Whenever any of those dependencies change, the computation is rescheduled to run before the next render. 
+It is "pure" in the sense that it is not intended to cause side effects outside of updating other reactive primitives.
+
+## Details
+
+### Development vs Production
+
+In development mode, passing a name in the options object can help with debugging and inspection in developer tools.
+In production, the name has no effect.
+
+### Error Handling
 
-Like `createMemo`, `createComputed` calls its function immediately on updates (unless you're in a [batch](/reference/reactive-utilities/batch), [effect](/reference/basic-reactivity/create-effect), or [transition](/reference/reactive-utilities/use-transition)). 
-However, while `createMemo` functions should be pure (not set any signals), `createComputed` functions can set signals. 
-Related, `createMemo` offers a readonly signal for the return value of the function, whereas to do the same with `createComputed` you would need to set a signal within the function. 
-If it is possible to use pure functions and `createMemo`, this is likely more efficient, as Solid optimizes the execution order of memo updates, whereas updating a signal within `createComputed` will immediately trigger reactive updates some of which may turn out to be unnecessary.
+- Errors thrown from the computation function are caught and reported using Solid's error boundaries or global error handlers.
+- Computations created outside a root (e.g. outside `createRoot` or a component) will never be disposed, and a warning is shown in development.
 
-## Arguments
+### Performance Characteristics
 
-| Name    | Type          | Description                                |
-| :------ | :------------ | :----------------------------------------- |
-| `fn`    | `(v: T) => T` | The function to run in a tracking scope.   |
-| `value` | `T`           | The initial value to pass to the function. |
+- Computed functions are optimized to run only when their tracked dependencies change.
+- Avoid doing expensive work or side effects in createComputed; use for reactive synchronization.
+- For memoized derived values, use createMemo. For post-render side effects (e.g., DOM or network), use createEffect.