Legend State

https://www.legendapp.com/open-source/state/v3/
Admin
Legend State is a fast, all-in-one local and remote state management library for React that provides...
Tokens:115,630
Snippets:894
Trust Score:8.2
Update:5 days ago
Show doc for...
Tokens:
Raw
### Full Supabase Sync Setup and Usage

Source: https://www.legendapp.com/open-source/state/v3/sync/supabase

Complete example showing how to set up a Supabase client, configure the sync plugin with a custom ID generator, create a synced observable for a 'messages' collection, and define functions to add and update messages. The observable is activated with get(), and setting values triggers Supabase actions.

```typescript
import { createClient } from '@supabase/supabase-js'
import { Database } from './database.types'
import { observable } from '@legendapp/state'
import { configureSyncedSupabase, syncedSupabase } from '@legendapp/state/sync-plugins/supabase'
import { v4 as uuidv4 } from "uuid"

const supabase = createClient<Database>(process.env.SUPABASE_URL, process.env.SUPABASE_ANON_KEY)

// provide a function to generate ids locally
const generateId = () => uuidv4()
configureSyncedSupabase({
    generateId
})
const uid = ''

const messages$ = observable(syncedSupabase({
    supabase,
    collection: 'messages',
    // Optional:
    // Select only id and text fields
    select: (from) => from.select('id,text'),
    // Filter by the current user
    filter: (select) => select.eq('user_id', uid),
    // Don't allow delete
    actions: ['read', 'create', 'update'],
    // Realtime filter by user_id
    realtime: { filter: `user_id=eq.${uid}` },
    // Persist data and pending changes locally
    persist: { name: 'messages', retrySync: true },
    // Sync only diffs
    changesSince: 'last-sync'
}))

// get() activates and starts syncing
const messages = messages$.get()

function addMessage(text: string) {
    const id = generateId()
    // Add keyed by id to the messages$ observable to trigger a create in Supabase
    messages$[id].set({
        id,
        text,
        created_at: null,
        updated_at: null
    })
}

function updateMessage(id: string, text: string) {
    // Just set values in the observable to trigger an update to Supabase
    messages$[id].text.set(text)
}
```

--------------------------------

### Full Keel Sync Setup with syncedKeel

Source: https://www.legendapp.com/open-source/state/v3/sync/keel

Complete example showing how to configure syncedKeel with an APIClient, persist to local storage, and sync observables with Keel queries and mutations. Includes authentication gating via isAuthed$ and keyed observable updates to trigger create/update actions.

```typescript
import { observable } from '@legendapp/state'
import { ObservablePersistLocalStorage } from '@legendapp/state/persist-plugins/local-storage'
import { configureSynced } from '@legendapp/state/sync'
import KSUID from 'ksuid'
import { syncedKeel } from '@legendapp/state/sync-plugins/keel'
import { APIClient } from './keelClient'

const client = new APIClient({
  baseUrl: process.env.API_BASE_URL
})

const isAuthed$ = observable(false);

// Set defaults
const sync = configureSynced(syncedKeel, {
    client,
    persist: {
        plugin: ObservablePersistLocalStorage,
        retrySync: true
    },
    debounceSet: 500,
    retry: {
        infinite: true,
    },
    changesSince: 'last-sync',
    waitFor: isAuthed$
})

// enable sync after authentication succeeds
async function doAuth() {
    // authenticate the client
    await keel.auth.authenticateWithPassword(email, pass)

    // check that the client is authenticated
    const isAuthenticated = await keel.auth.isAuthenticated()

    // Set isAuthed$ to start syncing
    isAuthed$.set(true)
}

// Set up your observables with Keel queries
const { mutations, queries } = client.api

// create an observable with the action functions
const messages$ = observable(sync({
    list: queries.getMessages,
    create: mutations.createMessage,
    update: mutations.updateMessage,
    delete: mutations.deleteMessage,
    persist: { name: 'messages' },
}))

// get() activates and starts syncing
const messages = messages$.get()

function addMessage(text: string) {
    const id = KSUID.randomSync().string
    // Add keyed by id to the messages$ observable to trigger the create action
    messages$[id].set({
        id,
        text,
        createdAt: undefined,
        updatedAt: undefined
    })
}

function updateMessage(id: string, text: string) {
    // Just set valudes in the observable to trigger the update action
    messages$[id].text.set(text)
}
```

--------------------------------

### synced: Advanced options example

Source: https://www.legendapp.com/open-source/state/v3/sync/persist-sync

Advanced synced example with many options: get and set functions, persistence with retrySync and custom plugin, initial value, mode for updating initial value, subscribe for external triggers, retry with backoff, and debounceSet to batch changes. Note: the example has a missing comma after the set function, which is a syntax error in the source.

```javascript
import { observable } from '@legendapp/state'
import { synced } from '@legendapp/state/sync'
import { ObservablePersistMMKV } from '@legendapp/state/persist-plugins/mmkv'

const state$ = observable(synced({
    get: () => {
        // get is an observing function which will re-run whenever any accessed observables
        // change. You can use that for paging getting data for a specific user.
        return fetch('https://url.to.get/page=' + page.get())
                .then((res) => res.json())
    },
    set: ({ value }) => {
        // set is run when the observable changes, debounced by the debounceSet option
        fetch('https://url.to.set', { method: 'POST', data: JSON.stringify(value) })
    }
    persist: {
        // The name to be saved in the local persistence
        name: 'test',
        // Set the plugin to override the global setting
        plugin: ObservablePersistMMKV,
        // persist pending changes to be retried after the app restarts
        retrySync: true,
        options: {
            // Customize the persist plugin options
        }
    },
    // The initial value before the remote data loads or if it doesn't exist.
    initial: {
        numUsers: 0,
        messages: []
    },
    // How to update the initial value when the remote data comes in.
    // defaults to "set"
    mode: 'set' | 'assign' | 'merge' | 'append' | 'prepend',
    // The subscribe function is called once to give you an opportunity to
    // subscribe to another service to trigger refresh
    subscribe: ({ refresh, update }) => {
        const unsubscribe = pusher.subscribe({ /*...*/ }, (data) => {
            // Either update with the received data
            update(data)
            // Or trigger a refresh of the get function
            refresh()
        })
        // return unsubscribe function
        return unsubscribe
    },
    // Options for retrying in case of error. Applies to both get and set.
    retry: {
        infinite: true,
        backoff: 'exponential',
        maxDelay: 30
    },
    // A time to debounce changes before sending them to the server. Use this to
    // batch multiple changes together or preventing saving every keystroke.
    debounceSet: 500,
}))
```

--------------------------------

### Install Legend-State with npm

Source: https://www.legendapp.com/open-source/state/v3/intro/getting-started

Install the beta version of @legendapp/state using npm. This is the first step to using Legend-State in your project.

```bash
npm install @legendapp/state@beta
```

--------------------------------

### Install ksuid library

Source: https://www.legendapp.com/open-source/state/v3/sync/keel

Install the ksuid library, which the Keel plugin uses to generate IDs locally in the same way as Keel's backend.

```bash
npm install ksuid
```

--------------------------------

### Install react-native-mmkv

Source: https://www.legendapp.com/open-source/state/v3/sync/persist-sync

Installs the react-native-mmkv package for MMKV persistence in React Native.

```bash
npm install react-native-mmkv
```

--------------------------------

### Keel model example

Source: https://www.legendapp.com/open-source/state/v3/sync/keel

A basic Keel model with fields and actions for get, create, update, and delete operations.

```keel
model Profile {
    fields {
        name Text
    }

    actions {
        get getProfile()
        create createProfile() with (name)
        update updateProfile(id) with (name)
        delete deleteProfile(id)
    }
}
```

--------------------------------

### Install AsyncStorage

Source: https://www.legendapp.com/open-source/state/v3/sync/persist-sync

Installs the @react-native-async-storage/async-storage package for AsyncStorage persistence in React Native.

```bash
npm install @react-native-async-storage/async-storage
```

--------------------------------

### Install expo-sqlite

Source: https://www.legendapp.com/open-source/state/v3/sync/persist-sync

Installs the expo-sqlite package for Expo SQLite persistence.

```bash
npm install expo-sqlite
```

--------------------------------

### Basic observable usage with get, set, observe, and useValue

Source: https://www.legendapp.com/open-source/state/v3/intro/introduction

Shows how to create an observable object, use get() and set() to access and modify data, and use observe() and useValue() to track changes and re-render components.

```javascript
import { observable, observe } from "@legendapp/state"
import { useValue } from "@legendapp/state/react"

// Observables can be primitives or deep objects
const settings$ = observable({
    theme: 'dark'
    // Computed observables with just a function
    isDark: () => settings$.theme.get() === 'dark'
})

// get returns the raw data
settings$.theme.get() // 'dark'
// set sets
settings$.theme.set('light')

// observing contexts re-run when tracked observables change
observe(() => {
    console.log(settings$.theme.get())
})

function Component() {
    const theme = useValue(state$.settings.theme)
    // useValue tracks get() calls to automatically re-render on changes
    const isDark = useValue(() => state$.settings.theme.get() === 'dark')

    return <div>Theme: {theme}</div>
}
```

--------------------------------

### Router example with pageHash and pageHashParams

Source: https://www.legendapp.com/open-source/state/v3/llms-full.txt

Use this snippet to implement hash-based routing with Legend State. It imports useRef, Memo, Switch, pageHash, and pageHashParams. The example provides buttons to set or delete the page parameter, displays the current hash, and uses Switch to render content based on the page value, including a default case for unknown pages.

```jsx
import { useRef } from "react"
import { Memo, Switch } from "@legendapp/state/react"
import { pageHash } from "@legendapp/state/helpers/pageHash"
import { pageHashParams } from "@legendapp/state/helpers/pageHashParams"

function RouterExample() {
  const renderCount = ++useRef(0).current

  return (
    <Box width={240}>
      <div>Renders: {renderCount}</div>
      <div>
        <Button onClick={() => pageHashParams.page.delete()}>
          Go to root
        </Button>
        <Button onClick={() => pageHashParams.page.set('')}>
          Go to Page
        </Button>
        <Button onClick={() => pageHashParams.page.set('Home')}>
          Go Home
        </Button>
        <Button onClick={() => pageHashParams.page.set('asdf')}>
          Go to unknown
        </Button>
      </div>
        <div>Hash: <Memo>{pageHash}</Memo></div>
        <div className="p-4 bg-zinc-600 rounded-xl">
          <Switch value={pageHashParams.page}>
            {{
              undefined: () => <div>Root</div>,
              '': () => <div>Page</div>,
              Home: () => <div>Home</div>,
              default: () => <div>Unknown page</div>,
            }}
          </Switch>
        </div>
    </Box>
  )
}
```

--------------------------------

### Full Example: Todo App with Legend-State

Source: https://www.legendapp.com/open-source/state/v3/intro/getting-started

A complete example combining a global observable store, computed values, and React components. It demonstrates creating an observable with the `observable` function, using `useValue` and `useObservable` hooks, and rendering lists with the `For` component. The example includes a `TodoItem` component that receives an `item$` prop and updates the store directly.

```typescript
import { observable } from "@legendapp/state"
import { observer, useValue, useObservable } from "@legendapp/state/react"

interface Todo {
  id: number;
  text: string;
  completed?: boolean;
}

interface Store {
  todos: Todo[];
  total: number;
  numCompleted: number;
  addTodo: () => void;
}

// Create a global observable for the Todos
let nextId = 0;
const store$ = observable<Store>({
todos: [],
// Computeds
total: (): number => {
  return store$.todos.length;
},
numCompleted: (): number => {
  return store$.todos.get().filter((todo) => todo.completed).length;
},
addTodo: () => {
  const todo: Todo = {
    id: nextId++,
    text: "New todo",
  };
  store$.todos.push(todo);
},
});

// Receives item$ prop from the For component
function TodoItem({ item$ }) {
  const onKeyDown = (e) => {
      // Call addTodo from the global store$
      if (e.key === 'Enter') store$.addTodo()
  }

  return (
      <div className="flex items-center">
          <Checkbox $value={item$.completed} />
          <input
              value={useValue(item$.text)}
              onChange={(e) => item$.text.set(e.target.value)}
              onKeyDown={onKeyDown}
              style={{
                color: 'inherit',
                backgroundColor: 'rgba(255,255,255,0.1)',
                border: '1px solid #6b7280',
                borderRadius: '4px',
                padding: '4px 8px',
                marginLeft: '8px',
                width: '120px'
              }}
          />
      </div>
  );
}

function App() {
  const theme$ = useObservable('dark')
  const theme = useValue(theme$)
  const total = useValue(store$.total)
  const completed = useValue(store$.numCompleted)

  const onClickClear = () => store$.todos.set([])

  return (
      <Box theme={theme}>
          <ThemeButton $value={theme$} />
          <div>Total: {total}</div>
          <div>Completed: {completed}</div>
          <For each={store$.todos} item={TodoItem} />
          <div className="flex justify-between">
              <Button onClick={store$.addTodo}>Add</Button>
              <Button onClick={onClickClear}>Clear</Button>
          </div>
      </Box>
  )
}

```

```typescript
import { observable } from "@legendapp/state"import { observer, useValue, useObservable } from "@legendapp/state/react"interface Todo {  id: number;  text: string;  completed?: boolean;}interface Store {  todos: Todo[];  total: number;  numCompleted: number;  addTodo: () => void;}// Create a global observable for the Todoslet nextId = 0;const store$ = observable<Store>({todos: [],// Computedstotal: (): number => {  return store$.todos.length;},numCompleted: (): number => {  return store$.todos.get().filter((todo) => todo.completed).length;},addTodo: () => {  const todo: Todo = {    id: nextId++,
    text: "New todo",
  };
  store$.todos.push(todo);
},
});// Receives item$ prop from the For componentfunction TodoItem({ item$ }) {  const onKeyDown = (e) => {      // Call addTodo from the global store$      if (e.key === 'Enter') store$.addTodo()  }  return (      <div className="flex items-center">          <Checkbox $value={item$.completed} />          <input              value={useValue(item$.text)}              onChange={(e) => item$.text.set(e.target.value)}              onKeyDown={onKeyDown}              style={{                color: 'inherit',                backgroundColor: 'rgba(255,255,255,0.1)',                border: '1px solid #6b7280',                borderRadius: '4px',                padding: '4px 8px',                marginLeft: '8px',                width: '120px'              }}          />      </div>  );}function App() {  const theme$ = useObservable('dark')  const theme = useValue(theme$)  const total = useValue(store$.total)  const completed = useValue(store$.numCompleted)  const onClickClear = () => store$.todos.set([])  return (      <Box theme={theme}>          <ThemeButton $value={theme$} />          <div>Total: {total}</div>          <div>Completed: {completed}</div>          <For each={store$.todos} item={TodoItem} />          <div className="flex justify-between">              <Button onClick={store$.addTodo}>Add</Button>              <Button onClick={onClickClear}>Clear</Button>          </div>      </Box>  )}
```

--------------------------------

### Live editable example: toggle theme with useValue

Source: https://www.legendapp.com/open-source/state/v3/intro/introduction

A live editable example showing a component that uses useValue to track the theme observable and a toggle function that updates it. The code is displayed in two formats: a formatted version and a minified version.

```javascript
import { observable } from "@legendapp/state"
import { useValue } from "@legendapp/state/react"

// Create an observable object
const settings$ = observable({ theme: 'dark' })

// This is the code for the example on your right ----->
function Component() {
  // theme is automatically tracked for changes
  const theme = useValue(settings$.theme)

  const toggle = () => {
    settings$.theme.set(theme =>
      theme === 'dark' ? 'light' : 'dark'
    )
  }

  return (
    <Box theme={theme}>
      <div>Theme: {theme}</div>
      <Button theme={theme} onClick={toggle}>
        Toggle theme
      </Button>
    </Box>
  )
}
```

```javascript
import { observable } from "@legendapp/state"import { useValue } from "@legendapp/state/react"// Create an observable objectconst settings$ = observable({ theme: 'dark' })// This is the code for the example on your right ----->function Component() {  // theme is automatically tracked for changes  const theme = useValue(settings$.theme)  const toggle = () => {    settings$.theme.set(theme =>      theme === 'dark' ? 'light' : 'dark'    )  }  return (    <Box theme={theme}>      <div>Theme: {theme}</div>      <Button theme={theme} onClick={toggle}>        Toggle theme      </Button>    </Box>  )}
```

--------------------------------

### Live editable example: toggle theme

Source: https://www.legendapp.com/open-source/state/v3/llms-full.txt

An editable example showing a React component that uses `useValue` to track an observable and a toggle button to switch between dark and light themes.

```jsx
import { observable } from "@legendapp/state"
import { useValue } from "@legendapp/state/react"

// Create an observable object
const settings$ = observable({ theme: 'dark' })

// This is the code for the example on your right ----->
function Component() {
    // theme is automatically tracked for changes
    const theme = useValue(settings$.theme)

    const toggle = () => {
      settings$.theme.set(theme =>
        theme === 'dark' ? 'light' : 'dark'
      )
    }

    return (
      <Box theme={theme}>
        <div>Theme: {theme}</div>
        <Button theme={theme} onClick={toggle}>
          Toggle theme
        </Button>
      </Box>
    )
}
```

--------------------------------

### get(true) - shallow listener

Source: https://www.legendapp.com/open-source/state/v3/usage/observable

Shows how to call get(true) to create a shallow listener that only tracks when keys are added/removed, not deep changes.

```typescript
state$.get(true) // Create a shallow listener
```

--------------------------------

### Basic observable usage with get, set, and observe

Source: https://www.legendapp.com/open-source/state/v3/intro/why

Shows the core observable API: creating an observable, reading with get(), writing with set(), and using observe() to track changes automatically. This is the fundamental pattern for using Legend-State.

```javascript
const state$ = observable({ value: 1 });
state$.value.get();
state$.value.set(2);

// Tracks automatically and runs on every change
observe(() => {
  console.log(state$.value.get());
});
```

--------------------------------

### Show component with selector and imports

Source: https://www.legendapp.com/open-source/state/v3/react/fine-grained-reactivity

A complete Show example using a selector function for the if prop, with imports from @legendapp/state/react and framer-motion.

```jsx
import { Show, useObservable } from "@legendapp/state/react";
import { AnimatePresence } from "framer-motion";

function ShowExampleWithSelector() {
  const state$ = useObservable({ collection: [] });
  return (
    <Show
      if={() => state$.collection.get().length > 0}
      else={() => <div>Nothing to see here</div>}
      wrap={AnimatePresence}
    >
      {() => <Modal />}
    </Show>
  );
}
```

--------------------------------

### synced: Basic persistence setup

Source: https://www.legendapp.com/open-source/state/v3/sync/persist-sync

Use synced to create an observable that persists locally and syncs with remote data. It creates a lazy computed function that activates on get(). The get function is an observing context, so it re-runs when accessed observables change, useful for paging or updating queries.

```javascript
import { observable } from '@legendapp/state'
import { synced } from '@legendapp/state/sync'

const state$ = observable(synced({
    get: () =>
        fetch('https://url.to.get').then((res) => res.json()),
    set: ({ value }) =>
        fetch('https://url.to.set', { method: 'POST', data: JSON.stringify(value) }),
    persist: {
        name: 'test',
    },
}))
```

--------------------------------

### useMeasure basic usage

Source: https://www.legendapp.com/open-source/state/v3/react/helpers-and-hooks

useMeasure returns an observable with the size ({ width, height }) of the target element. It starts with undefined values that get set after initial mount and whenever the element resizes.

```jsx
import { useMeasure } from "@legendapp/state/react-hooks/useMeasure";
import { useRef } from "react";

function Component() {
  const ref = useRef();
  const { width, height } = useMeasure(ref);

  return (
    <div ref={ref}>
      Width: {width}, Height: {height}
    </div>
  );
}
```

--------------------------------

### syncedQuery outside of React

Source: https://www.legendapp.com/open-source/state/v3/sync/tanstack-query

Use this function to integrate TanStack Query with Legend State outside of React. It takes normal Query parameters and a queryClient, and uses @tanstack/query-core. The observable is created with observable() and syncing starts when the value is accessed via get() inside observe().

```javascript
import { observable } from "@legendapp/state";
import { syncedQuery } from '@legendapp/state/sync-plugins/tanstack-query';
import { QueryClient } from '@tanstack/react-query';

const queryClient = new QueryClient()

const state$ = observable(syncedQuery({
    queryClient,
    query: {
        queryKey: ['user'],
        queryFn: async () => {
            return fetch('https://reqres.in/api/users/1').then((v) => v.json())
        },
    },
    mutation: {
        mutationFn: async (variables) => {
            return fetch(
                'https://reqres.in/api/users/1',
                { body: JSON.stringify(variables), method: 'POST' }
            )
        },
    },
}))

observe(() => {
    // get() the value to start syncing, and it will be reactive to updates coming in
    console.log(state$.get())
})
```

--------------------------------

### useObservableSyncedQuery React hook

Source: https://www.legendapp.com/open-source/state/v3/sync/tanstack-query

Use this hook to integrate TanStack Query with Legend State in React. It takes normal Query parameters for query and mutation, and gets the queryClient from Context. The returned observable can be used with useValue to start sync, or bound directly to an input via $React.input.

```javascript
import { $React } from "@legendapp/state/react-web";
import { useObservableSyncedQuery } from '@legendapp/state/sync-plugins/tanstack-react-query';
import { useQueryClient } from '@tanstack/react-query';
import { useValue } from '@legendapp/state/react';

function Component() {
    const state$ = useObservableSyncedQuery({
        query: {
            queryKey: ['user'],
            queryFn: async () => {
                return fetch('https://reqres.in/api/users/1').then((v) => v.json())
            },
        },
        mutation: {
            mutationFn: async (variables) => {
                return fetch(
                    'https://reqres.in/api/users/1',
                    { body: JSON.stringify(variables), method: 'POST' }
                )
            },
        },
    })

    // get it with useValue to start the sync
    const state = useValue(state$)

    // Or bind an input directly to a property, which will also start the sync
    return (
        <div>
            <$React.input $value={state$.first_name} />
        </div>
    )
}
```

--------------------------------

### Create a custom synced plugin with fetch

Source: https://www.legendapp.com/open-source/state/v3/llms-full.txt

Defines a customSynced function that returns a synced observable configured with get, set, retry, persist, waitFor, and subscribe. It uses fetch to call API endpoints for list, delete, and upsert operations. The example shows how to use it to create an observable for users.

```ts
import { observable } from '@legendapp/state'
import { synced } from '@legendapp/state/sync'

const isAuthed$ = observable(false);

// Create a custom synced that just needs a name in your API
const customSynced = ({ name }) => {
    const basePath = 'https://url/api/v1/'
    const doFetch = (path) => {
        return fetch(basePath + path).then((res) => res.json())
    }

    return synced({
        get: () => doFetch(`list-${name}s`),
        set: ({ value }) => {
            if (value === null || value === undefined) {
                return doFetch('delete-' + name)
            } else {
                return doFetch('upsert-' + name)
            }
        },
        retry: { infinite: true },
        persist: {
            name
        },
        waitFor: isAuthed$,
        subscribe: ({ refresh }) => {
            // Subscribe to realtime service
        },
    })
}

const store$ = observable({
    users: customSynced('user')
})

```

--------------------------------

### observe with get()

Source: https://www.legendapp.com/open-source/state/v3/usage/reactivity

Shows how to use observe to run code when an observable changes. The callback automatically tracks accessed observables and re-runs on changes.

```javascript
observe(() => {
    console.log(settings$.theme.get())
})
```

--------------------------------

### Persist an observable with syncObservable and ObservablePersistMMKV

Source: https://www.legendapp.com/open-source/state/v3/intro/getting-started

Sets up persistence for the store$ observable using the global persist plugin. The observable is synced to storage under the name 'gettingStarted' using the MMKV plugin. Any changes after this call are automatically saved.

```typescript
import { observable } from "@legendapp/state"
import { syncObservable } from '@legendapp/state/sync'
import { ObservablePersistMMKV } from "@legendapp/state/persist-plugins/mmkv"

const store$ = observable<Store>({
    todos: {},
})

// Persist the observable to the named key of the global persist plugin
syncObservable(store$, {
    persist: {
        name: 'gettingStarted',
        plugin: ObservablePersistMMKV
    }
})
```

--------------------------------

### SQL: Add columns and trigger for Supabase diff sync

Source: https://www.legendapp.com/open-source/state/v3/sync/supabase

Run this SQL to add `created_at` and `updated_at` columns and a trigger that sets them automatically. Replace `YOUR_TABLE_NAME` with your actual table name. The `deleted` column is optional for soft deletes; remove it if not needed.

```sql
-- Add new columns to table named `created_at` and `updated_at`
ALTER TABLE YOUR_TABLE_NAME
ADD COLUMN created_at timestamptz default now(),
ADD COLUMN updated_at timestamptz default now(),
-- Add column for soft deletes, remove this if you don't need that
ADD COLUMN deleted boolean default false;

-- This will set the `created_at` column on create and `updated_at` column on every update
CREATE OR REPLACE FUNCTION handle_times()
    RETURNS trigger AS
    $$
    BEGIN
    IF (TG_OP = 'INSERT') THEN
        NEW.created_at := now();
        NEW.updated_at := now();
    ELSEIF (TG_OP = 'UPDATE') THEN
        NEW.created_at = OLD.created_at;
        NEW.updated_at = now();
    END IF;
    RETURN NEW;
    END;
    $$ language plpgsql;

CREATE TRIGGER handle_times
    BEFORE INSERT OR UPDATE ON YOUR_TABLE_NAME
    FOR EACH ROW
EXECUTE PROCEDURE handle_times();
```

--------------------------------

### syncedCrud with get action

Source: https://www.legendapp.com/open-source/state/v3/sync/crud

Use syncedCrud with a get action to sync a single value. If get returns null, setting any value creates; if it returns a value, updating any value updates; setting to null or calling delete() deletes.

```javascript
import { observable } from "@legendapp/state";
import { syncedCrud } from '@legendapp/state/sync-plugins/crud'

const profile$ = observable(syncedCrud({
    get: getProfile,
    create: createProfile,
    update: updateProfile,
    delete: deleteProfile,
}))

profile$.get() // => Profile
```

--------------------------------

### syncObservable

Source: https://www.legendapp.com/open-source/state/v3/sync/persist-sync

Sets up sync/persistence on an existing observable with the same options as synced. Can also accept a sync plugin as the second argument.

```APIDOC
## syncObservable

### Description
Sets up sync/persistence on an existing observable with the same options as synced. Can also accept a sync plugin as the second argument.

### Method
syncObservable

### Signature
syncObservable(observable, options)

### Parameters
- **observable** (Observable) - Required - The observable to sync/persist.
- **options** (object | plugin) - Required - The sync options or a sync plugin.

### Options
- **get** (function) - Optional - A function that returns a promise resolving to the remote data.
- **set** (function) - Optional - A function that sends changes to the remote.
- **persist** (object) - Optional - Persistence configuration with a `name` property.

### Example
```javascript
import { observable } from '@legendapp/state'
import { syncObservable } from '@legendapp/state/sync'

const state$ = observable({ initialKey: 'initialValue' })

syncObservable(state$, {
    get: () =>
        fetch('https://url.to.get').then((res) => res.json()),
    set: ({ value }) =>
        fetch('https://url.to.set', { method: 'POST', data: JSON.stringify(value) }),
    persist: {
        name: 'test'
    }
})
```

### Plugin Example
```javascript
import { observable } from '@legendapp/state'
import { syncObservable } from '@legendapp/state/sync'
import { syncedFetch } from "@legendapp/state/sync-plugins/fetch"

const users$ = observable([])

syncObservable(users$, syncedFetch({
    // When the fetch resolves it will update the observable
    get: 'https://reqres.in/api/users',
    // When the observable is changed it will send the changes back to the server.
    set: 'https://reqres.in/api/users'
}))
```
```

--------------------------------

### Configure Local Storage persistence

Source: https://www.legendapp.com/open-source/state/v3/other/migrating

Set up Local Storage as the persistence plugin at the start of your app, required since it is no longer the default.

```javascript
import { configureObservablePersistence } from "@legendapp/state/persist";
import { ObservablePersistLocalStorage } from "@legendapp/state/local-storage";

configureObservablePersistence({
  persistLocal: ObservablePersistLocalStorage,
});
```

--------------------------------

### Enable $ get/set shorthand with enable$GetSet

Source: https://www.legendapp.com/open-source/state/v3/usage/observable

Optional extension to allow direct assignment via $ property. Requires importing and calling enable$GetSet() from @legendapp/state/config/enable$GetSet.

```javascript
import { enable$GetSet } from "@legendapp/state/config/enable$GetSet"
enable$GetSet()

// Now you can use $ as a shorthand for get()
const testValue = state$.test.$

// Assign to $ as a shorthand for set()
state$.test.$ = "hello"

// Assign objects too just like you can with set()
state$.$ = { test: "hello" }
```

--------------------------------

### Using $ shorthand for get and set

Source: https://www.legendapp.com/open-source/state/v3/usage/configuring

After enabling enable$GetSet, use $ to get and set observable values directly, including assigning objects and incrementing numbers.

```typescript
import { observable } from "@legendapp/state"

const state$ = observable({ test: "hi", num: 0 })

// $ is a shorthand for get()
const testValue = state$.test.$

// Assign to $ as a shorthand for set()
state$.test.$ = "hello"

// Assign objects too just like you can with set()
state$.$ = { test: "hello" }

// Incrementing works as you'd expect
state$.num.$++
```

--------------------------------

### JavaScript: Enable diff sync with syncedSupabase and configureSyncedSupabase

Source: https://www.legendapp.com/open-source/state/v3/sync/supabase

Use `changesSince: 'last-sync'` with `fieldCreatedAt` and `fieldUpdatedAt` to sync only changes since the last sync. Optionally set `fieldDeleted` for soft deletes. The second example shows global configuration via `configureSyncedSupabase`.

```javascript
// Sync diffs of a list
syncedSupabase({
    supabase,
    collection: 'messages',
    persist: {
        name: 'messages'
    },
    // Enable syncing only changes since last-sync
    changesSince: 'last-sync',
    fieldCreatedAt: 'created_at',
    fieldUpdatedAt: 'updated_at',
    // Optionally enable soft deletes
    fieldDeleted: 'deleted'
})

// Or you can configure this optional globally so it will apply to every instance of syncedSupabase.
configureSyncedSupabase({
    changesSince: 'last-sync',
    fieldCreatedAt: 'created_at',
    fieldUpdatedAt: 'updated_at',
    // Optionally enable soft deletes
    fieldDeleted: 'deleted'
})
```

--------------------------------

### useTraceListeners() example

Source: https://www.legendapp.com/open-source/state/v3/react/tracing

Call useTraceListeners() inside an observer component to log a list of every observable being tracked for changes. The example logs the tracked observable 'count'.

```javascript
import { observable } from "@legendapp/state";
import { observer, useValue } from "@legendapp/state/react";
import { useTraceListeners } from "@legendapp/state/trace";

const state$ = observable({ count: 0 });

const Component = observer(function Component(props) {
  // Call useTraceListeners anywhere inside the component
  useTraceListeners();

  const count = useValue(state$.count);

  return <div>{count}</div>;

  /* This logs:

    [legend-state] tracking 1 observable:
    1: count

    */
});
```

--------------------------------

### Observable with persistence and sync

Source: https://www.legendapp.com/open-source/state/v3/intro/why

Configures an observable with initial data, a get function to fetch from a URL, a set function to post changes, and a persist plugin using LocalStorage. This demonstrates the built-in persistence and sync capabilities.

```javascript
import { ObservablePersistLocalStorage } from '@legendapp/state/persist-plugins/local-storage'
import { synced } from '@legendapp/state/sync'
import { observable } from '@legendapp/state'

const state$ = observable({
    initial: {
        { bigObject: { ... } }
    },
    get: () => fetch('url').then(res => res.json()),
    set: ({ value }) =>
        fetch('https://url.to.set', { method: 'POST', data: JSON.stringify(value) }),
    persist: {
        name: 'test'
    }
})
```

--------------------------------

### useTraceUpdates() example

Source: https://www.legendapp.com/open-source/state/v3/react/tracing

Call useTraceUpdates() inside an observer component to log information about the observable change that causes each render. The example logs the change of 'count' from 0 to 1.

```javascript
import { observable } from "@legendapp/state";
import { observer, useValue } from "@legendapp/state/react";
import { useTraceUpdates } from "@legendapp/state/trace";

const state$ = observable({ count: 0 });

const Component = observer(function Component(props) {
  // Call useTraceUpdates anywhere inside the component
  useTraceUpdates();

  const count = useValue(state$.count);

  return <div>{count}</div>;

  /* This logs:

    [legend-state] Rendering because "count" changed:
    from: 0
    to: 1

    */
});
```

--------------------------------

### peek() - get value without tracking

Source: https://www.legendapp.com/open-source/state/v3/usage/observable

Shows how to use peek() to get the raw value without automatically tracking it, preventing updates to the component/observing context when the value changes.

```typescript
const state$ = observable({ name: 'Test user' })

// get the underlying value from the observable
const name = state$.name.peek()
```

--------------------------------

### syncObservable with get/set and persist

Source: https://www.legendapp.com/open-source/state/v3/sync/persist-sync

Sets up sync and persistence on an already-created observable using syncObservable with the same options as synced. The get function fetches data and updates the observable, set sends changes to the server, and persist stores locally under the name 'test'.

```javascript
import { observable } from '@legendapp/state'
import { syncObservable } from '@legendapp/state/sync'

const state$ = observable({ initialKey: 'initialValue' })

syncObservable(state$, {
    get: () =>
        fetch('https://url.to.get').then((res) => res.json()),
    set: ({ value }) =>
        fetch('https://url.to.set', { method: 'POST', data: JSON.stringify(value) }),
    persist: {
        name: 'test'
    }
})
```

--------------------------------

### Get action with syncedKeel

Source: https://www.legendapp.com/open-source/state/v3/sync/keel

Creates an observable for a single record using the get action. The observable value is the returned value, and setting it to null or calling delete() will delete the record.

```javascript
const { mutations, queries } = client.api

const profile$ = observable(syncedKeel({
    get: queries.getProfile,
    create: mutations.createProfile,
    update: mutations.updateProfile,
    delete: mutations.deleteProfile,
}))
// profile$.get() is a Profile
```

--------------------------------

### Using observe with event parameter

Source: https://www.legendapp.com/open-source/state/v3/other/migrating

Shows how to use the new event parameter in observe to cancel listening and add a cleanup function. Set e.cancel = true to stop observing, and e.cleanup = () => ... for cleanup.

```javascript
observe((e) => {
    // Cancel observing any future changes
    e.cancel = true

    // A cleanup function
    e.cleanup = () => ...
})
```

--------------------------------

### get() - retrieve raw data for expensive computations

Source: https://www.legendapp.com/open-source/state/v3/usage/observable

Shows how to use get() on the root observable to retrieve the raw data, avoiding proxy creation for every property access during expensive operations.

```typescript
const state$ = observable({ data: someHugeThing })
const { data } = state$.get()

// Nothing special happens when working with the raw data
processData(data)
```
Tokens:
Raw