\r\n\r\n# Woby\r\n\r\nA high-performance framework with fine-grained observable-based reactivity for building rich applications. Woby is built upon the [Soby](https://github.com/wobyjs/soby) reactive core, providing an enhanced API for component-based development.\r\n\r\n## Features\r\n\r\nThis works similarly to [Solid](https://www.solidjs.com), but without a custom Babel transform and with a different API.\r\n\r\n- **No VDOM**: there's no VDOM overhead, the framework deals with raw DOM nodes directly.\r\n- **No stale closures**: functions are always executed afresh, no need to worry about previous potential executions of the current function, ever.\r\n- **No rules of hooks**: hooks are regular functions that can be nested indefinitely, called conditionally, and used outside components, providing maximum flexibility for developers.\r\n- **No dependencies arrays**: the framework is able to detect what depends on what else automatically, no need to specify dependencies manually.\r\n- **No props diffing**: updates are fine grained, there's no props diffing, whenever an attribute/property/class/handler/etc. should be updated it's updated directly and immediately.\r\n- **No key prop**: developers can map over arrays directly or use the `For` component with an array of unique values, eliminating the need to specify keys explicitly.\r\n- **No Babel**: this framework works with plain JavaScript (plus JSX support), eliminating the need for Babel transforms. As a result, there are zero transform function bugs since no code transformation is required.\r\n- **No magic**: Woby follows a transparent approach where your code behaves exactly as written, with no hidden transformations or unexpected behavior.\r\n- **Client-focused**: this framework is currently focused on client-side rich applications. Server-related features such as hydration, server components, SSR, and streaming are not implemented at this time.\r\n- **Observable-based**: observables are at the core of the reactivity system. While the approach differs significantly from React-like systems and may require an initial learning investment, it provides substantial benefits in terms of performance and developer experience.\r\n- **Minimal dependencies**: Woby is designed with a focus on minimal third-party dependencies, providing a streamlined API for developers who prefer a lightweight solution. The framework draws inspiration from [Solid](https://www.solidjs.com) while offering its own unique approach to reactive programming.\r\n- **Built-in Class Management**: Woby includes powerful built-in class management that supports complex class expressions similar to `classnames` and `clsx` libraries, with full reactive observable support.\r\n- **Web Components Support**: First-class support for creating and using custom elements with reactive properties.\r\n- **Advanced Context API**: Powerful context system that works seamlessly with both JSX components and custom elements.\r\n- **Advanced Nested Property Support**: Unique feature allowing deeply nested properties to be set directly through HTML attributes using both `$` and `.` notation - a capability not available in React or SolidJS.\r\n\r\n## 📚 Documentation\r\n\r\n**[📖 Complete Documentation Wiki](./docs/README.md)** - Comprehensive guides, tutorials, and API reference\r\n\r\n### Quick Links\r\n- **[Installation Guide](./docs/Installation.md)** - Get started with Woby\r\n- **[Quick Start Tutorial](./docs/Quick-Start.md)** - Build your first app\r\n- **[API Reference](./docs/Core-Methods.md)** - Complete API documentation\r\n- **[Reactive Utilities](./docs/Reactive-Utilities.md)** - Working with observables and the `$$` function\r\n- **[Reactivity System](./docs/Reactivity-System.md)** - Understanding Woby's reactivity model\r\n- **[Examples Gallery](./docs/Examples.md)** - Practical examples and patterns\r\n- **[Class Management](./docs/Class-Management.md)** - Advanced class handling with reactive support\r\n- **[Best Practices](./docs/Best-Practices.md)** - Recommended patterns and practices\r\n- **[Woby vs React](./docs/Woby-vs-React.md)** - API differences and migration guide\r\n- **[FAQ](./docs/FAQ.md)** - Common questions and answers\r\n- **[Type Synchronization](./docs/Type-Synchronization.md)** - How HTML attributes sync with component props\r\n- **[Simple Type Synchronization](./docs/Type-Sync-Simple.md)** - Straightforward approach to type sync\r\n\r\n### Specialized Documentation\r\n- **[Context API](./docs/CONTEXT_API.md)** - Advanced context management for components and custom elements\r\n- **[Custom Elements](./docs/CUSTOM_ELEMENTS.md)** - Creating and using Web Components with Woby\r\n\r\n## Key Features\r\n\r\n### Context API\r\n\r\nWoby provides a powerful Context API that works seamlessly with both JSX components and custom elements:\r\n\r\n```tsx\r\n// Create a context\r\nconst ThemeContext = createContext('light')\r\n\r\n// Use in JSX components\r\nconst ThemedButton = () => {\r\n const theme = useContext(ThemeContext)\r\n return \r\n}\r\n\r\n// Use in custom elements\r\nconst ThemedElement = defaults(() => ({}), () => {\r\n const [theme, mount] = useMountedContext(ThemeContext)\r\n return
{mount}Theme: {theme}
\r\n})\r\n\r\ncustomElement('themed-element', ThemedElement)\r\n```\r\n\r\n[Learn more about the Context API](./docs/CONTEXT_API.md)\r\n\r\n### Custom Elements\r\n\r\nWoby provides first-class support for creating custom HTML elements with reactive properties:\r\n\r\n```tsx\r\n// Define a component with default props\r\nconst Counter = defaults(() => ({\r\n value: $(0, { type: 'number' } as const),\r\n title: $('Counter')\r\n}), ({ value, title }) => (\r\n
\r\n
{title}
\r\n
Count: {value}
\r\n \r\n
\r\n))\r\n\r\n// Register as a custom element\r\ncustomElement('counter-element', Counter)\r\n\r\n// Use in JSX or HTML\r\n// JSX: \r\n// HTML: \r\n```\r\n\r\n### Advanced Nested Property Support\r\n\r\nOne of Woby's unique features is its advanced nested property support, allowing you to set deeply nested properties directly through HTML attributes:\r\n\r\n```html\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```\r\n\r\nThis feature is not available in React or SolidJS, making Woby a more powerful choice for creating highly configurable custom elements that can be used directly in HTML.\r\n\r\n[Learn more about Custom Elements](./docs/CUSTOM_ELEMENTS.md)\r\n\r\n## Demos\r\n\r\nYou can find some demos and benchmarks below, more demos are contained inside the repository.\r\n\r\n- Playground: https://codesandbox.io/s/playground-7w2pxg\r\n- Benchmark: https://krausest.github.io/js-framework-benchmark/current.html\r\n- Counter: https://codesandbox.io/s/demo-counter-23fv5\r\n- Clock: https://codesandbox.io/s/demo-clock-w1e7yb\r\n- Emoji Counter: https://codesandbox.io/s/demo-emoji-counter-j91iz2\r\n- HyperScript: https://codesandbox.io/s/demo-hyperscript-h4rf38\r\n- HTML Template Literal: https://codesandbox.io/s/demo-html-lvfeyo\r\n- Single-file HTML: https://codesandbox.io/s/demo-html-dueygt?file=/public/index.html\r\n- Spiral: https://codesandbox.io/s/demo-spiral-ux33p6\r\n- Store Counter: https://codesandbox.io/s/demo-store-counter-kvoqrw\r\n- Triangle: https://codesandbox.io/s/demo-triangle-l837v0\r\n- Boxes: https://codesandbox.io/s/demo-boxes-wx6rqb\r\n\r\n## AI Assistant Instructions\r\n\r\n### For AI Coding Assistants\r\n\r\nWhen using AI coding assistants to help with Woby development, please provide these explicit instructions to ensure proper understanding of Woby patterns:\r\n\r\n1. **Framework Specific Instructions**: \"Use Woby patterns, NOT React patterns. Woby uses observables with `$()` and `$()` functions, not React hooks like useState, useEffect with dependency arrays, or useCallback.\"\r\n\r\n2. **Observable-Based Reactivity**: \"In Woby, declare reactive variables with `$()`, and access their values with `$()` in reactive contexts. Woby automatically tracks dependencies when you use `$()`.\"\r\n\r\n3. **No Dependency Arrays**: \"Woby hooks like `useEffect` and `useMemo` do not require dependency arrays. Dependencies are automatically tracked when accessed with `$()`.\"\r\n\r\n4. **Reactive Patterns**: \"Direct observable passing (`{userName}`) is preferred for simple reactive content. For complex expressions, use function expressions (`{() => $(userName)}`) which are automatically tracked.\"\r\n\r\n### Common Anti-Patterns to Avoid\r\n\r\n``tsx\r\n// ❌ Anti-pattern: React-style useState\r\nconst [count, setCount] = useState(0)\r\n\r\n// ✅ Woby pattern\r\nconst count = $(0)\r\n\r\n// ❌ Anti-pattern: React useEffect with dependency array\r\nuseEffect(() => {\r\n console.log(count)\r\n}, [count])\r\n\r\n// ✅ Woby pattern\r\nuseEffect(() => {\r\n console.log($(count))\r\n})\r\n\r\n// ❌ Anti-pattern: Non-reactive content\r\n
}\r\n```\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please read our [contributing guidelines](./docs/Contributing.md) before submitting pull requests.\r\n\r\n## Thanks\r\n\r\n- **[S](https://github.com/adamhaile/S)**: for pioneering reactive programming approaches that inspired this framework.\r\n- **[sinuous/observable](https://github.com/luwes/sinuous/tree/master/packages/sinuous/observable)**: for providing an excellent Observable implementation that served as the foundation for this library.\r\n- **[solid](https://www.solidjs.com)**: for serving as a reference implementation, popularizing signal-based reactivity, and building a strong community.\r\n- **[solid](https://www.solidjs.com)**: for serving as a reference implementation, popularizing signal-based reactivity, and building a strong community.\r\n- **[trkl](https://github.com/jbreckmckye/trkl)**: for demonstrating the power of minimal, focused implementations.\r\n\r\n## License\r\n\r\nMIT\r\n }\r\n return currentTodos\r\n })\r\n\r\n const activeCount = useMemo(() => {\r\n return $(todos).filter(todo => !todo.completed).length\r\n })\r\n\r\n return (\r\n
\r\n
My Todo App
\r\n \r\n {/* Add new todo */}\r\n
\r\n input(e.target.value)}\r\n placeholder=\"Add a new todo...\"\r\n onKeyPress={(e) => e.key === 'Enter' && addTodo()}\r\n class=\"flex-1 p-2 border border-gray-300 rounded\"\r\n />\r\n \r\n
\r\n\r\n```\r\n\r\nModifying the value attribute on triggers an immediate update to its associated observable.\r\n\r\n### Advanced Class Management\r\n\r\nWoby provides powerful built-in class management that supports complex class expressions with full reactive observable support, similar to popular libraries like `classnames` and `clsx`.\r\n\r\n#### Class Array Support\r\n\r\nWoby supports complex class expressions including arrays, objects, and functions:\r\n\r\n```tsx\r\n// Array of classes\r\n
\r\n```\r\n\r\n#### Reactive Classes\r\n\r\nAll class expressions support reactive observables that automatically update when values change:\r\n\r\n```tsx\r\nconst isActive = $(false)\r\nconst theme = $('dark')\r\n\r\n// Reactive boolean\r\n
Toggle me
\r\n\r\n// Reactive string\r\n
`btn btn-${theme()}`}>Themed button
\r\n\r\n// Complex reactive expression\r\n
isActive() ? 'active' : 'inactive',\r\n { 'loading': loadingState() }\r\n]}>Dynamic element
\r\n```\r\n\r\n#### Class Object Syntax\r\n\r\nWoby supports object syntax for conditional classes where keys are class names and values are boolean conditions:\r\n\r\n```tsx\r\nconst error = $(false)\r\nconst warning = $(false)\r\n\r\n
Status element
\r\n```\r\n\r\n#### Function-based Classes\r\n\r\nClasses can be computed using functions that return class strings or other class expressions:\r\n\r\n```tsx\r\nconst count = $(0)\r\n\r\n
\r\n```\r\n\r\n### Built-in Classnames/CLSX/Tailwind-Merge Support\r\n\r\nWoby's class system provides built-in functionality equivalent to popular libraries:\r\n\r\n- **Classnames/CLSX-like syntax**: Supports all the same patterns as the popular `classnames` and `clsx` libraries\r\n- **Tailwind CSS ready**: Works seamlessly with Tailwind CSS class patterns\r\n- **No external dependencies**: Built-in implementation eliminates the need for external libraries\r\n- **Reactive by default**: All class expressions automatically update when observables change\r\n- **Performance optimized**: Efficient implementation that minimizes DOM updates\r\n\r\n#### Migration from CLSX\r\n\r\nIf you're familiar with `clsx`, Woby's class system works similarly:\r\n\r\n```tsx\r\n// Instead of: clsx('foo', true && 'bar', 'baz')\r\n
\r\n```\r\n\r\n#### Integration with Tailwind Merge\r\n\r\nFor advanced Tailwind CSS class merging, you can wrap your expressions with a custom merge function:\r\n\r\n```tsx\r\nimport { twMerge } from 'tailwind-merge'\r\n\r\nconst mergedClass = useMemo(() => twMerge(\r\n 'px-4 py-2 bg-blue-500',\r\n isActive() ? 'bg-blue-700' : 'bg-blue-500'\r\n))\r\n\r\n
Merged classes
\r\n```\r\n\r\nAll reactive elements in class expressions should be wrapped in `useMemo` or arrow functions `() =>` to ensure proper reactivity:\r\n\r\n```tsx\r\n// Correct - wrapped in useMemo\r\nconst dynamicClass = useMemo(() => ({\r\n 'active': isActive(),\r\n 'disabled': isDisabled()\r\n}))\r\n\r\n
Content
\r\n\r\n// Correct - wrapped in arrow function\r\n
\r\n```\r\n\r\n### Methods\r\n\r\nThe following top-level functions are provided.\r\n\r\n#### `\r\n\r\nThis function is just the default export of `soby`, it can be used to wrap a value in an observable.\r\n\r\nNo additional methods are attached to this function. Everything that `soby` attaches to it is instead exported as components and hooks.\r\n\r\n[Read upstream documentation](https://github.com/wobyjs/soby#core).\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction $ (): Observable;\r\nfunction $ ( value: undefined, options?: ObservableOptions ): Observable;\r\nfunction $ ( value: T, options?: ObservableOptions ): Observable;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {$} from 'woby';\r\n\r\n// Create an observable without an initial value\r\n\r\n$ ();\r\n\r\n// Create an observable with an initial value\r\n\r\n$(1);\r\n\r\n// Create an observable with an initial value and a custom equality function\r\n\r\nconst equals = ( value, valuePrev ) => Object.is ( value, valuePrev );\r\n\r\nconst o = $( 1, { equals } );\r\n\r\n// Create an observable with an initial value and a special \"false\" equality function, which is a shorthand for `() => false`, which causes the observable to always emit when its setter is called\r\n\r\nconst oFalse = $( 1, { equals: false } );\r\n\r\n// Getter\r\n\r\no (); // => 1\r\n\r\n// Setter\r\n\r\no ( 2 ); // => 2\r\n\r\n// Setter via a function, which gets called with the current value\r\n\r\no ( value => value + 1 ); // => 3\r\n\r\n// Setter that sets a function, it has to be wrapped in another function because the above form exists\r\n\r\nconst noop = () => {};\r\n\r\no ( () => noop );\r\n```\r\n\r\n#### `\r\n\r\nThis function unwraps a potentially observable value.\r\n\r\n[Read upstream documentation](https://github.com/wobyjs/soby#get).\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction $ ( value: T ): (T extends ObservableReadonly ? U : T);\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {$} from 'woby';\r\n\r\n// Getting the value out of an observable\r\n\r\nconst o = $(123);\r\n\r\n$ ( o ); // => 123\r\n\r\n// Getting the value out of a function\r\n\r\n$ ( () => 123 ); // => 123\r\n\r\n// Getting the value out of an observable but not out of a function\r\n\r\n$ ( o, false ); // => 123\r\n$ ( () => 123, false ); // => () => 123\r\n\r\n// Getting the value out of a non-observable and non-function\r\n\r\n$ ( 123 ); // => 123\r\n```\r\n\r\n#### `$$`\r\n\r\nThis function unwraps a potentially observable value. Recent enhancements to Soby (which Woby uses as its reactive core) have added automatic `valueOf()` and `toString()` methods to observable functions, making them behave more naturally in JavaScript contexts where primitives are expected.\r\n\r\n[Read upstream documentation](https://github.com/wobyjs/soby#get).\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction $$ ( value: T ): (T extends ObservableReadonly ? U : T);\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {$$} from 'woby';\r\n\r\n// Getting the value out of an observable\r\n\r\nconst o = $(123);\r\n\r\n$$ ( o ); // => 123\r\n\r\n// Getting the value out of a function\r\n\r\n$$ ( () => 123 ); // => 123\r\n\r\n// Getting the value out of an observable but not out of a function\r\n\r\n$$ ( o, false ); // => 123\r\n$$ ( () => 123, false ); // => () => 123\r\n\r\n// Getting the value out of a non-observable and non-function\r\n\r\n$$ ( 123 ); // => 123\r\n```\r\n\r\n##### Enhanced Observable Functions\r\n\r\nRecent enhancements to Soby have added automatic `valueOf()` and `toString()` methods to observable functions. These methods use `deepResolve()` to automatically resolve observables to their current values in various contexts.\r\n\r\n###### Technical Implementation\r\n\r\nThe enhancement was implemented in Soby's `src/objects/callable.ts` by adding the following lines to both `readable` and `writable` observable function generators:\r\n\r\n```typescript\r\nfn.valueOf = () => deepResolve(fn)\r\nfn.toString = () => fn.valueOf().toString()\r\n```\r\n\r\nThis change affects the creation of observable functions, making them behave more naturally in JavaScript contexts where primitives are expected.\r\n\r\n###### Automatic String Conversion\r\n\r\nObservables now automatically resolve to their values in string contexts:\r\n\r\n```typescript\r\nimport {$} from 'woby'\r\n\r\n// In template literals\r\nconst name = $('John')\r\nconsole.log(`Hello, ${name}!`) // Outputs: \"Hello, John!\"\r\n\r\n// In JSX expressions\r\nconst App = () => {\r\n const count = $(5)\r\n return
Count: {count}
// Renders: \"Count: 5\"\r\n}\r\n```\r\n\r\n###### Mathematical Operations\r\n\r\nObservables automatically resolve in mathematical operations:\r\n\r\n```typescript\r\nimport {$} from 'woby'\r\n\r\nconst count = $(5)\r\nconst result = count + 10 // Results in 15 automatically\r\n\r\nconst price = $(19.99)\r\nconst tax = $(0.08)\r\nconst total = price * (1 + tax) // Automatically calculates with current values\r\n```\r\n\r\n###### DOM Attribute Binding\r\n\r\nWhen binding observables to DOM attributes, they automatically convert to appropriate string representations:\r\n\r\n```typescript\r\nimport {$} from 'woby'\r\n\r\nconst isVisible = $(true)\r\nconst opacity = $(0.5)\r\n\r\n// These will automatically convert to appropriate string values\r\nconst element =
Content
\r\n```\r\n\r\n###### Performance Considerations\r\n\r\nThe `deepResolve` function recursively resolves observables, which means for deeply nested structures there could be performance implications in hot paths. The resolution happens every time `valueOf()` or `toString()` is called.\r\n\r\nFor performance-critical applications with deeply nested structures, explicit unwrapping with `$$()` may be preferred:\r\n\r\n```typescript\r\n// This maintains reactivity by directly passing the observable\r\nconst reactive =
{deeplyNestedObject}
\r\n\r\n// This unwraps the observable to get its static value, losing reactivity\r\nconst staticValue =
{$$(deeplyNestedObject)}
\r\n\r\n// With the valueOf enhancement, mathematical operations are simplified\r\nconst price = $(19.99);\r\nconst quantity = $(3);\r\nconst total =
Total: {() => price * quantity}
; // Automatically computes 59.97\r\n```\r\n\r\n###### Backward Compatibility\r\n\r\nThis enhancement improves rather than breaks existing functionality:\r\n\r\n1. All existing code continues to work as before\r\n2. Explicit unwrapping with `$$()` still works and may be preferred in performance-critical situations\r\n3. The enhancement provides additional convenience without removing any capabilities\r\n\r\n#### `batch`\r\n\r\nThis function holds onto updates within its scope and flushes them out once it exits.\r\n\r\n[Read upstream documentation](https://github.com/wobyjs/soby#batch).\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction batch ( fn: () => T ): T;\r\nfunction batch ( value: T ): T;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {batch} from 'woby';\r\n\r\nbatch // => Same as require ( 'soby' ).batch\r\n```\r\n\r\n#### `createContext`\r\n\r\nThis function creates a context object, optionally with a default value, which can later be used to provide a new value for the context or to read the current value.\r\n\r\nA context's `Provider` will register the context with its children, which is always what you want, but it can lead to messy code due to nesting.\r\n\r\nA context's `register` function will register the context with the current parent observer, which is usually only safe to do at the root level, but it will lead to very readable code.\r\n\r\nInterface:\r\n\r\n```ts\r\ntype ContextProvider = ( props: { value: T, children: JSX.Element } ) => JSX.Element;\r\ntype ContextRegister = ( value: T ) => void;\r\ntype Context = { Provider: ContextProvider, register: ContextRegister };\r\n\r\nfunction createContext ( defaultValue?: T ): Context;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {createContext, useContext} from 'woby';\r\n\r\nconst App = () => {\r\n const Context = createContext ( 123 );\r\n return (\r\n <>\r\n {() => {\r\n const value = useContext ( Context );\r\n return
;\r\n }}\r\n \r\n \r\n );\r\n};\r\n```\r\n\r\n#### `createDirective`\r\n\r\nThis function creates a directive provider, which can be used to register a directive with its children.\r\n\r\nA directive is a function that always receives an `Element` as its first argument, which is basically a ref to the target element, and arbitrary user-provided arguments after that.\r\n\r\nEach directive has a unique name and it can be called by simply writing `use:directivename={[arg1, arg2, ...argN]]}` in the JSX.\r\n\r\nDirectives internally are registered using context providers, so you can also override directives for a particular scope just by registering another directive with the same name closer to where you are reading it.\r\n\r\nA directive's `Provider` will register the directive with its children, which is always what you want, but it can lead to messy code due to nesting.\r\n\r\nA directive's `register` function will register the directive with the current parent observer, which is usually only safe to do at the root level, but it will lead to very readable code.\r\n\r\nInterface:\r\n\r\n```ts\r\ntype DirectiveFunction = ( ref: Element, ...args: T ) => void;\r\ntype DirectiveProvider = ( props: { children: JSX.Element } ) => JSX.Element;\r\ntype DirectiveRef = ( ...args: T ) => (( ref: Element ) => void);\r\ntype DirectiveRegister = () => void;\r\ntype Directive = { Provider: DirectiveProvider, ref: DirectiveRef, register: DirectiveRegister };\r\n\r\nfunction createDirective ( name: string, fn: DirectiveFunction, options?: DirectiveOptions ): Directive;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {createDirective, useEffect} from 'woby';\r\n\r\n// First of all if you are using TypeScript you should extend the \"JSX.Directives\" interface, so that TypeScript will know about your new directive\r\n\r\nnamespace JSX {\r\n interface Directives {\r\n tooltip: [title: string] // Mapping the name of the directive to the array of arguments it accepts\r\n }\r\n}\r\n\r\n// Then you should create a directive provider\r\n\r\nconst TooltipDirective = createDirective ( 'tooltip', ( ref, title: string ) => {\r\n\r\n useEffect ( () => {\r\n\r\n if ( !ref () ) return; // The element may not be available yet, or it might have been unmounted\r\n\r\n // Code that implements a tooltip for the given element here...\r\n\r\n });\r\n\r\n});\r\n\r\n// Then you can use the new \"tooltip\" directive anywhere inside the \"TooltipDirective.Provider\"\r\n\r\nconst App = () => {\r\n return (\r\n \r\n \r\n \r\n );\r\n};\r\n\r\n// You can also use directives directly by padding them along as refs\r\n\r\nconst App = () => {\r\n return ;\r\n};\r\n```\r\n\r\n#### `createElement`\r\n\r\nThis is the internal function that will make DOM nodes and call/instantiate components, it will be called for you automatically via JSX.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction createElement
( component: JSX.Component
, props: P | null, ...children: JSX.Element[] ): () => JSX.Element);\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {createElement} from 'woby';\r\n\r\nconst element = createElement ( 'div', { class: 'foo' }, 'child' ); // => () => HTMLDivElement\r\n```\r\n\r\n#### `h`\r\n\r\nThis function is just an alias for the `createElement` function, it's more convenient to use if you want to use Woby in hyperscript mode just because it has a much shorter name.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction h
( component: JSX.Component
, props: P | null, ...children: JSX.Element[] ): () => JSX.Element);\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {h} from 'woby';\r\n\r\nconst element = h ( 'div', { class: 'foo' }, 'child' ); // => () => HTMLDivElement\r\n```\r\n\r\n#### `html`\r\n\r\nThis function provides an alternative way to use the framework, without writing JSX or using the `h` function manually, it instead allows you to write your markup as tagged template literals.\r\n\r\n[`htm`](https://github.com/developit/htm) is used under the hood, read its documentation.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction html ( strings: TemplateStringsArray, ...values: any[] ): JSX.Element;```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {html, If} from 'woby';\r\n\r\nconst Counter = (): JSX.Element => {\r\n const value = $(0);\r\n const increment = () => value ( prev => prev + 1 );\r\n const decrement = () => value ( prev => prev - 1 );\r\n return html`\r\n
Counter
\r\n
${value}
\r\n \r\n \r\n `;\r\n};\r\n\r\n// Using a custom component without registering it\r\n\r\nconst NoRegistration = (): JSX.Element => {\r\n return html`\r\n <${If} when=${true}>\r\n
content
\r\n \r\n `;\r\n};\r\n\r\n// Using a custom component after registering it, so you won't need to interpolate it anymore\r\n\r\nhtml.register ({ If });\r\n\r\nconst NoRegistration = (): JSX.Element => {\r\n return html`\r\n \r\n
content
\r\n \r\n `;\r\n};\r\n```\r\n\r\n#### `isBatching`\r\n\r\nThis function tells you if batching is currently active or not.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction isBatching (): boolean;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {batch, isBatching} from 'woby';\r\n\r\n// Checking if currently batching\r\n\r\nisBatching (); // => false\r\n\r\nbatch ( () => {\r\n\r\n isBatching (); // => true\r\n\r\n});\r\n\r\nisBatching (); // => false\r\n```\r\n\r\n#### `isObservable`\r\n\r\nThis function tells you if a variable is an observable or not.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction isObservable ( value: unknown ): value is Observable | ObservableReadonly;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {$, isObservable} from 'woby';\r\n\r\nisObservable ( 123 ); // => false\r\nisObservable ( $(123) ); // => true\r\n```\r\n\r\n#### `isServer`\r\n\r\nThis function tells you if your code is executing in a browser environment or not.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction isServer (): boolean;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {isServer} from 'woby';\r\n\r\nisServer (); // => true or false\r\n```\r\n\r\n#### `isStore`\r\n\r\nThis function tells you if a variable is a store or not.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction isStore ( value: unknown ): boolean;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {store, isStore} from 'woby';\r\n\r\nisStore ( {} ); // => false\r\nisStore ( store ( {} ) ); // => true\r\n```\r\n\r\n#### `lazy`\r\n\r\nThis function creates a lazy component, which is loaded via the provided function only when/if needed.\r\n\r\nThis function uses `useResource` internally, so it's significant for `Suspense` too.\r\n\r\nInterface:\r\n\r\n```ts\r\ntype LazyComponent
= ( props: P ) => ObservableReadonly;\r\ntype LazyFetcher
;\r\n```\r\n\r\nUsage:\r\n\r\n```ts\r\nimport {lazy} from 'woby';\r\n\r\nconst LazyComponent = lazy ( () => import ( './component' ) );\r\n```\r\n\r\n#### `render`\r\n\r\nThis function mounts a component inside a provided DOM element and returns a disposer function for unmounting it and stopping all reactivity inside it.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction render ( child: JSX.Element, parent?: HTMLElement | null ): Disposer;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {render} from 'woby';\r\n\r\nconst App = () =>
Hello, World!
;\r\n\r\nconst dispose = render ( , document.body );\r\n\r\ndispose (); // Unmounted and all reactivity inside it stopped\r\n```\r\n\r\n#### `renderToString`\r\n\r\nThis function operates similarly to `render`, but returns a Promise that resolves to the HTML representation of the rendered component.\r\n\r\nThe current implementation works within browser-like environments. For server-side usage, [JSDOM](https://github.com/jsdom/jsdom) or similar solutions are required.\r\n\r\nThis function automatically waits for all `Suspense` boundaries to resolve before returning the HTML.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction renderToString ( child: JSX.Element ): Promise;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {renderToString} from 'woby';\r\n\r\nconst App = () =>
Hello, World!
;\r\n\r\nconst html = await renderToString ( );\r\n```\r\n\r\n#### `resolve`\r\n\r\nThis function resolves all reactivity within the provided argument, replacing each function with a memo that captures the function's value.\r\n\r\nWhile developers may not need to use this function directly, it is internally necessary to ensure proper tracking of child values by their parent computations.\r\n\r\n[Read upstream documentation](https://github.com/wobyjs/soby#resolve).\r\n\r\nInterface:\r\n\r\n```ts\r\ntype ResolvablePrimitive = null | undefined | boolean | number | bigint | string | symbol;\r\ntype ResolvableArray = Resolvable[];\r\ntype ResolvableObject = { [Key in string | number | symbol]?: Resolvable };\r\ntype ResolvableFunction = () => Resolvable;\r\ntype Resolvable = ResolvablePrimitive | ResolvableObject | ResolvableArray | ResolvableFunction;\r\n\r\nfunction resolve ( value: T ): T extends Resolvable ? T : never;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {resolve} from 'woby';\r\n\r\nresolve // => Same as require ( 'soby' ).resolve\r\n```\r\n\r\n#### `store`\r\n\r\nThis function returns a deeply reactive version of the passed object, where property accesses and writes are automatically interpreted as Observables reads and writes for you.\r\n\r\n[Read upstream documentation](https://github.com/wobyjs/soby#store).\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction store ( value: T, options?: StoreOptions ): T;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {store} from 'woby';\r\n\r\nstore // => Same as require ( 'soby' ).store\r\n```\r\n\r\n#### `template`\r\n\r\nThis function enables constructing elements with [Solid](https://www.solidjs.com)-level performance without using the Babel transform, but also without the convenience of that.\r\n\r\nThis function works similarly to [sinuous](https://github.com/luwes/sinuous/tree/master)'s template function but provides a cleaner API, as props are accessed identically inside and outside the template.\r\n\r\nThis function can be used to wrap components that do not directly create observables or call hooks, significantly improving performance during component instantiation.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction template
( fn: (( props: P ) => JSX.Element) ): (( props: P ) => () => Element);\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {template} from 'woby';\r\n\r\nconst Row = template ( ({ id, cls, label, onSelect, onRemove }) => { // Now Row is super fast to instantiate\r\n return (\r\n
\r\n );\r\n});\r\n\r\nconst Table = () => {\r\n const rows = [ /* props for all your rows here */ ];\r\n return rows.map ( row => );\r\n};\r\n```\r\n\r\n#### `untrack`\r\n\r\nThis function executes the provided function without creating dependencies on observables retrieved inside it.\r\n\r\n[Read upstream documentation](https://github.com/wobyjs/soby#untrack).\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction untrack ( fn: () => T ): T;\r\nfunction untrack ( value: T ): T;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {untrack} from 'woby';\r\n\r\nuntrack // => Same as require ( 'soby' ).untrack\r\n```\r\n\r\n### Components\r\n\r\nThe following components are provided.\r\n\r\nCrucially some components are provided for control flow, since regular JavaScript control flow primitives are not reactive, and we need to have reactive alternatives to them to have great performance.\r\n\r\n#### `Dynamic`\r\n\r\nThis component is just an alternative to `createElement` that can be used in JSX, it's useful to create a new element dynamically.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction Dynamic
\r\n \r\n \r\n );\r\n};\r\n\r\nconst SomeComponentThatThrows = () => {\r\n throw new Error('whatever');\r\n};\r\n\r\nconst App = () => {\r\n return (\r\n \r\n \r\n \r\n );\r\n};\r\n```\r\n\r\n#### `For`\r\n\r\nThis component is the reactive alternative to natively mapping over an array.\r\n\r\nIt must be called with an array, or a function that returns an array, of _unique_ values, and each of them are passed to the child function to render something.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction For ( props: { values: FunctionMaybe, fallback?: JSX.Element, children: (( value: T, index: FunctionMaybe ) => JSX.Element) }): ObservableReadonly;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {For} from 'woby';\r\n\r\nconst App = () => {\r\n const numbers = [1, 2, 3, 4, 5];\r\n return (\r\n \r\n {( value ) => {\r\n return
Value: {value}
\r\n }}\r\n \r\n );\r\n};\r\n```\r\n\r\n#### `ForIndex`\r\n\r\nThis component is a reactive alternative to natively mapping over an array, but it takes the index as the unique key instead of the value.\r\n\r\nThis is an alternative to `For` that uses the index of the value in the array for caching, rather than the value itself.\r\n\r\nIt's recommended to use `ForIndex` for arrays containing duplicate values and/or arrays containing primitive values, and `For` for everything else.\r\n\r\nThe passed function will always be called with a read-only observable containing the current value at the index being mapped.\r\n\r\nInterface:\r\n\r\n```ts\r\ntype Value = T extends ObservableReadonly ? ObservableReadonly : ObservableReadonly;\r\n\r\nfunction ForIndex ( props: { values: FunctionMaybe, fallback?: JSX.Element, children: (( value: Value, index: number ) => JSX.Element) }): ObservableReadonly;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {ForIndex} from 'woby';\r\n\r\nconst App = () => {\r\n const numbers = [1, 2, 3, 4, 5];\r\n return (\r\n \r\n {( value ) => {\r\n return
Double value: {() => value () ** 2}
\r\n }}\r\n \r\n );\r\n};\r\n```\r\n\r\n#### `ForValue`\r\n\r\nThis component is a reactive alternative to natively mapping over an array, but it caches results for values that didn't change, _and_ repurposes results for items that got discarded for new items that need to be rendered.\r\n\r\nThis is an alternative to `For` and `ForIndex` that enables reusing the same result for different items, when possible. Reusing the same result means also reusing everything in it, including DOM nodes.\r\n\r\nBasically `Array.prototype.map` doesn't wrap the value nor the index in an observable, `For` wraps the index only in an observable, `ForIndex` wraps the value only in an observable, and `ForValue` wraps both the value and the index in observables.\r\n\r\nThis is useful for use cases like virtualized rendering, where `For` would cause some nodes to be discarded and others to be created, `ForIndex` would cause _all_ nodes to be repurposed, but `ForValue` allows you to only repurpose the nodes that would have been discareded by `For`, not all of them.\r\n\r\nThis is a more advanced component, it's recommended to simply use `For` or `ForIndex`, until you really understand how to squeeze extra performance with this, and you actually need that performance.\r\n\r\nInterface:\r\n\r\n```ts\r\ntype Value = T extends ObservableReadonly ? ObservableReadonly : ObservableReadonly;\r\n\r\nfunction ForValue ( props: { values: FunctionMaybe, fallback?: JSX.Element, children: (( value: Value, index: ObservableReadonly ) => JSX.Element) }): ObservableReadonly;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {ForValue} from 'woby';\r\n\r\nconst App = () => {\r\n const numbers = [1, 2, 3, 4, 5];\r\n return (\r\n \r\n {( value ) => {\r\n return
Double value: {() => value () ** 2}
\r\n }}\r\n \r\n );\r\n};```\r\n\r\n#### `Fragment`\r\n\r\nThis is just the internal component used for rendering fragments: `<>`, you probably would never use this directly even if you are not using JSX, since you can return plain arrays from your components anyway.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction Fragment ( props: { children: JSX.Element }): JSX.Element;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {Fragment} from 'woby';\r\n\r\nconst App = () => {\r\n return (\r\n \r\n
child 1
\r\n
child 2
\r\n \r\n );\r\n};\r\n```\r\n\r\n#### `If`\r\n\r\nThis component is the reactive alternative to the native `if`.\r\n\r\nIf a function is passed as the children then it will be called with a read-only observable that contains the current, always truthy, value of the \"when\" condition.\r\n\r\nInterface:\r\n\r\n```ts\r\ntype Truthy = Extract;\r\n\r\nfunction If ( props: { when: FunctionMaybe, fallback?: JSX.Element, children: JSX.Element | (( value: (() => Truthy) ) => JSX.Element) }): ObservableReadonly;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {If} from 'woby';\r\n\r\nconst App = () => {\r\n const visible = $(false);\r\n const toggle = () => visible ( !visible () );\r\n return (\r\n <>\r\n \r\n \r\n
Hello!
\r\n \r\n \r\n );\r\n};\r\n```\r\n\r\n#### `Portal`\r\n\r\nThis component mounts its children inside a provided DOM element, or inside `document.body` otherwise.\r\n\r\nThe `mount` prop can also be an observable, if its value changes the portal is reparented.\r\n\r\nThe `when` prop can be used to apply the portal conditionally, if it explicitly resolves to false then children are mounted normally, as if they weren't wrapped in a portal.\r\n\r\nEvents will propagate natively, according to the resulting DOM hierarchy, not the components hierarchy.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction Portal ( props: { when: boolean, mount?: JSX.Element, wrapper?: JSX.Element, children: JSX.Element }): (() => JSX.Element | null) & ({ metadata: { portal: HTMLDivElement } });\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport Portal from 'woby';\r\n\r\nconst Modal = () => {\r\n // Some modal component maybe...\r\n};\r\n\r\nconst App = () => {\r\n return (\r\n \r\n \r\n \r\n );\r\n};\r\n```\r\n\r\n#### `Suspense`\r\n\r\nThis component is like `If`, the reactive alternative to the native `if`, but the fallback branch is shown automatically while there are some resources loading in the main branch, and the main branch is kept alive under the hood.\r\n\r\nSo this can be used to show some fallback content while the actual content is loading in the background.\r\n\r\nThis component relies on `useResource` to understand if there's a resource loading or not.\r\n\r\nThis component also supports a manual \"when\" prop for manually deciding whether the fallback branch should be rendered or not.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction Suspense ( props: { when?: FunctionMaybe, fallback?: JSX.Element, children: JSX.Element }): ObservableReadonly;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {Suspense} from 'woby';\r\n\r\nconst App = () => {\r\n const Content = () => {\r\n const resource = useResource ( () => makeSomePromise () );\r\n return (\r\n !resource ().pending && !resource ().error}>\r\n {resource ().value}\r\n \r\n );\r\n };\r\n const Spinner = () => {\r\n return
Loading...
;\r\n };\r\n return (\r\n }>\r\n \r\n \r\n );\r\n};\r\n```\r\n\r\n#### `Switch`\r\n\r\nThis component is the reactive alternative to the native `switch`.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction Switch ( props: { when: FunctionMaybe, fallback?: JSX.Element, children: JSX.Element }): ObservableReadonly;\r\n\r\nSwitch.Case = function ( props: { when: T, children: JSX.Element } ): (() => JSX.Element) & ({ metadata: [T, JSX.Element] });\r\nSwitch.Default = function ( props: { children: JSX.Element } ): (() => JSX.Element) & ({ metadata: [JSX.Element] });\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {Switch} from 'woby';\r\n\r\nconst App = () => {\r\n const value = $(0);\r\n const increment = () => value ( value () + 1 );\r\n const decrement = () => value ( value () - 1 );\r\n return (\r\n <>\r\n \r\n \r\n
0, the boundary between positives and negatives! (?)
\r\n \r\n \r\n
1, the multiplicative identity!
\r\n \r\n \r\n
{value}, I don't have anything interesting to say about that :(
\r\n \r\n \r\n \r\n \r\n \r\n );\r\n};\r\n```\r\n\r\n#### `Ternary`\r\n\r\nThis component is the reactive alternative to the native ternary operator.\r\n\r\nThe first child will be rendered when the condition is truthy, otherwise the second child will be rendered.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction Ternary ( props: { when: FunctionMaybe, children: [JSX.Element, JSX.Element] } ): ObservableReadonly;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {Ternary} from 'woby';\r\n\r\nconst App = () => {\r\n const visible = $(false);\r\n const toggle = () => visible ( !visible () );\r\n return (\r\n <>\r\n \r\n \r\n
Visible :)
\r\n
Invisible :(
\r\n \r\n \r\n );\r\n};\r\n```\r\n\r\n### Hooks\r\n\r\nThe following hooks are provided.\r\n\r\nMany of these are just functions that `soby` provides, re-exported as `use*` functions, the rest are largely just alternatives to web built-ins that can also accept observables as arguments and can dispose of themselves automatically when the parent computation is disposed.\r\n\r\nHooks are just regular functions, if their name starts with `use` then we call them hooks just because.\r\n\r\n#### `useAbortController`\r\n\r\nThis hook is just an alternative to `new AbortController ()` that automatically aborts itself when the parent computation is disposed.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction useAbortController ( signals?: ArrayMaybe ): AbortController;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {useAbortController} from 'woby';\r\n\r\nconst controller = useAbortController ();\r\n```\r\n\r\n#### `useAbortSignal`\r\n\r\nThis hook is just a convenient alternative to `useAbortController`, if you are only interested in its signal, which is automatically aborted when the parent computation is disposed.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction useAbortSignal ( signals?: ArrayMaybe ): AbortSignal;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {useAbortSignal} from 'woby';\r\n\r\nconst signal = useAbortSignal ();\r\n```\r\n\r\n#### `useAnimationFrame`\r\n\r\nThis hook is just an alternative to `requestAnimationFrame` that automatically clears itself when the parent computation is disposed.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction useAnimationFrame ( callback: ObservableMaybe ): Disposer;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {useAnimationFrame} from 'woby';\r\n\r\nuseAnimationFrame ( () => console.log ( 'called' ) );\r\n```\r\n\r\n#### `useAnimationLoop`\r\n\r\nThis hook is just a version of `useAnimationFrame` that loops until the parent computation is disposed.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction useAnimationLoop ( callback: ObservableMaybe ): Disposer;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {useAnimationLoop} from 'woby';\r\n\r\nuseAnimationLoop ( () => console.log ( 'called' ) );\r\n```\r\n\r\n#### `useBoolean`\r\n\r\nThis hook is like the reactive equivalent of the `!!` operator, it returns you a boolean, or a function to a boolean, depending on the input that you give it.\r\n\r\n[Read upstream documentation](https://github.com/wobyjs/soby#boolean).\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction useBoolean ( value: FunctionMaybe ): FunctionMaybe;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {useBoolean} from 'woby';\r\n\r\nuseBoolean // => Same as require ( 'soby' ).boolean\r\n```\r\n\r\n#### `useCleanup`\r\n\r\nThis hook registers a function to be called when the parent computation is disposed.\r\n\r\n[Read upstream documentation](https://github.com/wobyjs/soby#cleanup).\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction useCleanup ( fn: () => void ): void;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {useCleanup} from 'woby';\r\n\r\nuseCleanup // => Same as require ( 'soby' ).cleanup\r\n```\r\n\r\n#### `useContext`\r\n\r\nThis hook retrieves the value out of a context object.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction useContext ( context: Context ): T | undefined;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {createContext, useContext} from 'woby';\r\n\r\nconst App = () => {\r\n const ctx = createContext ( 123 );\r\n const value = useContext ( ctx );\r\n return
{value}
;\r\n};\r\n```\r\n\r\n#### `useDisposed`\r\n\r\nThis hook returns a boolean read-only observable that is set to `true` when the parent computation gets disposed of.\r\n\r\n[Read upstream documentation](https://github.com/wobyjs/soby#disposed).\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction useDisposed (): ObservableReadonly;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {useDisposed} from 'woby';\r\n\r\nuseDisposed // => Same as require ( 'soby' ).disposed\r\n```\r\n\r\n#### `useEffect`\r\n\r\nThis hook registers a function to be called when any of its dependencies change. If a function is returned it's automatically registered as a cleanup function.\r\n\r\n[Read upstream documentation](https://github.com/wobyjs/soby#effect).\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction useEffect ( fn: () => (() => void) | void ): (() => void);\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {useEffect} from 'woby';\r\n\r\nuseEffect // => Same as require ( 'soby' ).effect\r\n```\r\n\r\n#### `useError`\r\n\r\nThis hook registers a function to be called when the parent computation throws.\r\n\r\n[Read upstream documentation](https://github.com/wobyjs/soby#error).\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction useError ( fn: ( error: Error ) => void ): void;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {useError} from 'woby';\r\n\r\nuseError // => Same as require ( 'soby' ).error\r\n```\r\n\r\n#### `useEventListener`\r\n\r\nThis hook is just an alternative to `addEventListener` that automatically clears itself when the parent computation is disposed.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction useEventListener ( target: FunctionMaybe, event: FunctionMaybe, handler: ObservableMaybe<( event: Event ) => void>, options?: FunctionMaybe ): Disposer;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {useEventListener} from 'woby';\r\n\r\nuseEventListener ( document, 'click', console.log );\r\n```\r\n\r\n#### `useFetch`\r\n\r\nThis hook wraps the output of a fetch request in an observable, so that you can be notified when it resolves or rejects. The request is also aborted automatically when the parent computation gets disposed of.\r\n\r\nThis hook uses `useResource` internally, so it's significant for `Suspense` too.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction useFetch ( request: FunctionMaybe, init?: FunctionMaybe ): ObservableReadonly>;\r\n```\r\n\r\nUsage:\r\n\r\n```tsx\r\nimport {useFetch} from 'woby';\r\n\r\nconst App = () => {\r\n const state = useFetch ( 'https://my.api' );\r\n return state.on ( state => {\r\n if ( state.pending ) return
pending...
;\r\n if ( state.error ) return
{state.error.message}
;\r\n return
Status: {state.value.status}
\r\n });\r\n};```\r\n\r\n#### `useIdleCallback`\r\n\r\nThis hook is just an alternative to `requestIdleCallback` that automatically clears itself when the parent computation is disposed.\r\n\r\nInterface:\r\n\r\n```ts\r\nfunction useIdleCallback ( callback: Ob","readmeFilename":"readme.md"}
![\"Woby's](\"./resources/banner/png/banner-light-rounded.png\")
\r\n \r\n