@llui/effects

Effect builders for LLui. Effects are data -- update() returns them, the runtime dispatches.

pnpm add @llui/effects

Usage

import { http, cancel, debounce, handleEffects } from '@llui/effects'

// Debounced search with cancel
function update(state: State, msg: Msg): [State, Effect[]] {
  switch (msg.type) {
    case 'search':
      return [
        { ...state, query: msg.value },
        [
          cancel('search'),
          debounce(
            'search',
            300,
            http({
              url: `/api/search?q=${msg.value}`,
              onSuccess: (data) => ({ type: 'results', data }),
              onError: (err) => ({ type: 'searchError', err }),
            }),
          ),
        ],
      ]
  }
}

// Wire up in component
const handler = handleEffects&#x3C;Effect, Msg>()
  .use(httpPlugin)
  .else((effect, send) => {
    /* custom effects */
  })

API

Effect Builders

Function	Description
`http({ url, onSuccess, onError })`	HTTP request effect
`cancel(token, inner?)`	Cancel by token, optionally replace with inner
`debounce(key, ms, inner)`	Debounce inner effect by key
`timeout(ms, msg)`	Fire msg after delay
`interval(ms, msg)`	Fire msg on interval
`storageSet(key, value, storage?)`	Write to localStorage/sessionStorage
`storageGet(key, onResult, storage?)`	Read from storage
`storageRemove(key, storage?)`	Remove from storage
`storageWatch(key, onChange)`	Watch storage for changes
`broadcast(channel, data)`	Send on BroadcastChannel
`broadcastListen(channel, onMsg)`	Listen on BroadcastChannel
`sequence([...effects])`	Run effects in order
`race([...effects])`	Run effects concurrently, first wins
`upload({ url, body, onProgress, onSuccess, onError })`	File upload with progress via XHR
`clipboardRead({ onSuccess, onError })`	Read text from clipboard
`clipboardWrite(text)`	Write text to clipboard (fire-and-forget)
`notification(title, opts?)`	Show browser notification (requests permission)
`geolocation({ onSuccess, onError, enableHighAccuracy? })`	One-shot geolocation position

Upload

Upload files with progress tracking via XMLHttpRequest:

import { upload } from '@llui/effects'

const effect = upload({
  url: '/api/upload',
  body: formData,
  headers: { Authorization: `Bearer ${token}` },
  onProgress: (loaded, total) => ({
    type: 'uploadProgress',
    pct: Math.round((loaded / total) * 100),
  }),
  onSuccess: (data, status) => ({ type: 'uploadDone', data, status }),
  onError: (error) => ({ type: 'uploadFailed', error }),
})

Clipboard

Read and write text via the Clipboard API:

import { clipboardRead, clipboardWrite } from '@llui/effects'

// Copy text to clipboard (fire-and-forget)
clipboardWrite('Hello, world!')

// Read text from clipboard
clipboardRead({
  onSuccess: (text) => ({ type: 'pasted', text }),
  onError: (error) => ({ type: 'clipError', error }),
})

Notification

Show browser notifications (requests permission automatically):

import { notification } from '@llui/effects'

notification('New message', {
  body: 'You have a new message from Alice',
  icon: '/avatar.png',
  onClick: () => ({ type: 'openChat' }),
  onError: () => ({ type: 'notifBlocked' }),
})

Geolocation

One-shot position request:

import { geolocation } from '@llui/effects'

geolocation({
  enableHighAccuracy: true,
  onSuccess: (pos) => ({
    type: 'located',
    lat: pos.latitude,
    lng: pos.longitude,
  }),
  onError: (error) => ({ type: 'geoError', error }),
})

Effect Handling

Function	Description
`handleEffects<E, M>()`	Chainable effect handler builder
`.use(plugin)`	Add an effect handler plugin
`.else(handler)`	Fallback for unhandled effects
`resolveEffects(def)`	SSR data loading -- resolves effects server-side

Types

Type	Description
`Async<T, E>`	`idle \| loading \| success \| failure` -- async data state
`ApiError`	`network \| timeout \| notfound \| unauthorized \| forbidden \| ratelimit \| validation \| server`

License

MIT