lazyconvex 0.0.0

package/src/next/image.ts

@@ -0,0 +1,134 @@
+'use server'
+import type { FunctionReference } from 'convex/server'
+import type { NextRequest } from 'next/server'
+import type { Sharp } from 'sharp'
+
+import { ConvexHttpClient } from 'convex/browser'
+import { NextResponse } from 'next/server'
+import sharp from 'sharp'
+
+type Format = 'jpeg' | 'png' | 'webp'
+interface FormatOpts {
+  contentType: string
+  format: Format | undefined
+  quality: number
+}
+interface ImageRouteConfig {
+  convexUrl: string
+  fileInfoQuery?: string
+}
+interface ProcessOptions {
+  compress?: { quality?: number }
+  format?: Format
+  resize?: { fit?: 'contain' | 'cover' | 'fill' | 'inside' | 'outside'; height?: number; width?: number }
+}
+interface TransformOpts {
+  contentType: string
+  options: ProcessOptions | undefined
+  pipeline: Sharp
+  thumbnail: boolean
+}
+
+const IMAGE_TYPES = new Set(['image/gif', 'image/jpeg', 'image/png', 'image/svg+xml', 'image/webp']),
+  isImageType = (contentType: string): boolean => IMAGE_TYPES.has(contentType),
+  formatToMime: Record<Format, string> = {
+    jpeg: 'image/jpeg',
+    png: 'image/png',
+    webp: 'image/webp'
+  },
+  applyFormat = ({ contentType, format, pipeline, quality }: FormatOpts & { pipeline: Sharp }): Sharp => {
+    if (format === 'jpeg') return pipeline.jpeg({ quality })
+    if (format === 'png') return pipeline.png({ quality })
+    if (format === 'webp') return pipeline.webp({ quality })
+    const [, ext] = contentType.split('/')
+    if (ext === 'jpeg' || ext === 'jpg') return pipeline.jpeg({ quality })
+    if (ext === 'png') return pipeline.png({ quality })
+    if (ext === 'webp') return pipeline.webp({ quality })
+    return pipeline
+  },
+  applyTransforms = ({ contentType, options, pipeline, thumbnail }: TransformOpts): Sharp => {
+    const quality = options?.compress?.quality ?? 80
+    if (thumbnail) return pipeline.resize({ fit: 'cover', height: 200, width: 200 }).webp({ quality: 80 })
+    let result = pipeline
+    if (options?.resize)
+      result = result.resize({
+        fit: options.resize.fit ?? 'cover',
+        height: options.resize.height,
+        width: options.resize.width
+      })
+    if (options?.format || options?.compress)
+      result = applyFormat({ contentType, format: options.format, pipeline: result, quality })
+    return result
+  },
+  fetchImage = async ({
+    client,
+    queryRef,
+    storageId
+  }: {
+    client: ConvexHttpClient
+    queryRef: string
+    storageId: string
+  }): Promise<{ buffer: Buffer; contentType: string } | { error: string; status: number }> => {
+    const info = (await client.query(queryRef as unknown as FunctionReference<'query'>, { id: storageId })) as null | {
+        url: string
+      },
+      url = info?.url
+    if (!url) return { error: 'File not found', status: 404 }
+    const response = await fetch(url)
+    if (!response.ok) return { error: 'Failed to fetch image', status: 500 }
+    const contentType = response.headers.get('content-type') ?? ''
+    if (!isImageType(contentType)) return { error: 'Not an image file', status: 400 }
+    return { buffer: Buffer.from(await response.arrayBuffer()), contentType }
+  },
+  makeGet =
+    ({ getClient, queryRef }: { getClient: () => ConvexHttpClient; queryRef: string }) =>
+    async (req: NextRequest): Promise<NextResponse> => {
+      try {
+        const storageId = req.nextUrl.searchParams.get('id')
+        if (!storageId) return NextResponse.json({ error: 'id is required' }, { status: 400 })
+        const result = await fetchImage({ client: getClient(), queryRef, storageId })
+        if ('error' in result) return NextResponse.json({ error: result.error }, { status: result.status })
+        return new NextResponse(new Uint8Array(result.buffer), {
+          headers: { 'Cache-Control': 'public, max-age=31536000, immutable', 'Content-Type': result.contentType }
+        })
+      } catch (error) {
+        return NextResponse.json(
+          { error: error instanceof Error ? error.message : 'Failed to fetch image' },
+          { status: 500 }
+        )
+      }
+    },
+  makePost =
+    ({ getClient, queryRef }: { getClient: () => ConvexHttpClient; queryRef: string }) =>
+    async (req: NextRequest): Promise<NextResponse> => {
+      try {
+        const body = (await req.json()) as { options?: ProcessOptions; storageId: string; thumbnail?: boolean },
+          { options, storageId, thumbnail } = body
+        if (!storageId) return NextResponse.json({ error: 'storageId is required' }, { status: 400 })
+        const result = await fetchImage({ client: getClient(), queryRef, storageId })
+        if ('error' in result) return NextResponse.json({ error: result.error }, { status: result.status })
+        const { buffer, contentType } = result,
+          pipeline = applyTransforms({
+            contentType,
+            options,
+            pipeline: sharp(buffer),
+            thumbnail: thumbnail ?? false
+          }),
+          outputBuffer = await pipeline.toBuffer(),
+          outputMime = thumbnail ? 'image/webp' : options?.format ? formatToMime[options.format] : contentType
+        return new NextResponse(new Uint8Array(outputBuffer), {
+          headers: { 'Cache-Control': 'public, max-age=31536000, immutable', 'Content-Type': outputMime }
+        })
+      } catch (error) {
+        return NextResponse.json({ error: error instanceof Error ? error.message : 'Processing failed' }, { status: 500 })
+      }
+    },
+  /* eslint-disable @typescript-eslint/promise-function-async, @typescript-eslint/require-await */
+  makeImageRoute = async ({ convexUrl, fileInfoQuery = 'file:info' }: ImageRouteConfig) => {
+    const getClient = () => new ConvexHttpClient(convexUrl),
+      opts = { getClient, queryRef: fileInfoQuery }
+    return { GET: makeGet(opts), POST: makePost(opts) }
+  }
+/* eslint-enable @typescript-eslint/promise-function-async, @typescript-eslint/require-await */
+
+export { makeImageRoute }

package/src/next/index.ts

@@ -0,0 +1,3 @@
+export { clearActiveOrgCookie, getActiveOrg, setActiveOrgCookie } from './active-org'
+export { getToken, isAuthenticated } from './auth'
+export { makeImageRoute } from './image'

package/src/react/form-meta.ts

@@ -0,0 +1,53 @@
+/* eslint-disable max-statements */
+import type { ZodObject, ZodRawShape } from 'zod/v4'
+
+import type { ZodSchema } from '../zod'
+
+import {
+  cvFileKindOf,
+  elementOf,
+  isArrayType,
+  isBooleanType,
+  isDateType,
+  isNumberType,
+  isStringType,
+  unwrapZod
+} from '../zod'
+
+type FieldKind = 'boolean' | 'date' | 'file' | 'files' | 'number' | 'string' | 'stringArray' | 'unknown'
+interface FieldMeta {
+  kind: FieldKind
+  max?: number
+}
+type FieldMetaMap = Record<string, FieldMeta>
+
+const getMax = (schema: undefined | ZodSchema): number | undefined => {
+    const checks = schema?.def.checks as (undefined | { _zod: { def: { check: string; maximum?: number } } })[] | undefined
+    if (checks)
+      for (const c of checks)
+        if (c?._zod.def.check === 'max_length' && c._zod.def.maximum !== undefined) return c._zod.def.maximum
+  },
+  getMeta = (s: unknown): FieldMeta => {
+    const { schema: base, type } = unwrapZod(s),
+      fk = cvFileKindOf(s)
+    if (fk === 'file') return { kind: 'file' }
+    if (fk === 'files') return { kind: 'files', max: getMax(base) }
+    if (isArrayType(type)) {
+      const el = unwrapZod(elementOf(base))
+      return { kind: isStringType(el.type) ? 'stringArray' : 'unknown', max: getMax(base) }
+    }
+    if (isStringType(type)) return { kind: 'string' }
+    if (isNumberType(type)) return { kind: 'number' }
+    if (isBooleanType(type)) return { kind: 'boolean' }
+    if (isDateType(type)) return { kind: 'date' }
+    return { kind: 'unknown' }
+  },
+  buildMeta = (s: ZodObject<ZodRawShape>): FieldMetaMap => {
+    const m: FieldMetaMap = {}
+    // biome-ignore lint/nursery/noForIn: x
+    for (const k in s.shape) if (Object.hasOwn(s.shape, k)) m[k] = getMeta(s.shape[k])
+    return m
+  }
+
+export type { FieldKind, FieldMeta, FieldMetaMap }
+export { buildMeta, getMeta }

package/src/react/form.ts

@@ -0,0 +1,201 @@
+/* eslint-disable react-hooks/rules-of-hooks */
+// biome-ignore-all lint/correctness/useHookAtTopLevel: watch hook is called inside component render context
+'use client'
+import type { StandardSchemaV1 } from '@tanstack/form-core'
+import type { FormValidateOrFn, ReactFormExtendedApi } from '@tanstack/react-form'
+import type { FunctionReference } from 'convex/server'
+import type { output, ZodObject, ZodRawShape } from 'zod/v4'
+
+import { useForm as useTanStackForm } from '@tanstack/react-form'
+import { useStore } from '@tanstack/react-store'
+import { useMutation } from 'convex/react'
+import { useEffect, useMemo, useRef, useState } from 'react'
+
+import type { FieldMetaMap } from './form-meta'
+
+import { getErrorCode, getErrorMessage, isRecord } from '../server/error'
+import { coerceOptionals, defaultValues as dv } from '../zod'
+import { buildMeta } from './form-meta'
+
+type Api<T extends Record<string, unknown>> = ReactFormExtendedApi<
+  T,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  FormValidateOrFn<T>,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  unknown
+>
+
+interface ConflictData {
+  code: string
+  current?: unknown
+  incoming?: unknown
+}
+
+interface FormReturn<T extends Record<string, unknown>, S extends ZodObject<ZodRawShape>> {
+  conflict: ConflictData | null
+  error: Error | null
+  instance: Api<T>
+  isDirty: boolean
+  isPending: boolean
+  lastSaved: null | number
+  meta: FieldMetaMap
+  reset: (values?: T) => void
+  resolveConflict: (action: 'cancel' | 'overwrite' | 'reload') => void
+  schema: S
+  watch: <K extends keyof T>(name: K) => T[K]
+}
+
+const submitError = (e: unknown): Error => new Error(getErrorMessage(e), { cause: e }),
+  handleConflict = (error: unknown): ConflictData | null => {
+    if (getErrorCode(error) !== 'CONFLICT') return null
+    const { data } = error as { data?: { current?: unknown; incoming?: unknown } }
+    return {
+      code: 'CONFLICT',
+      current: data?.current,
+      incoming: data?.incoming
+    }
+  },
+  useForm = <S extends ZodObject<ZodRawShape>>({
+    autoSave,
+    onConflict,
+    onError,
+    onSubmit,
+    onSuccess,
+    resetOnSuccess,
+    schema,
+    values
+  }: {
+    autoSave?: { debounceMs: number; enabled: boolean }
+    onConflict?: (data: ConflictData) => void
+    onError?: (e: unknown) => void
+    onSubmit: (d: output<S>, force?: boolean) => output<S> | Promise<output<S> | undefined> | undefined
+    onSuccess?: () => void
+    resetOnSuccess?: boolean
+    schema: S
+    values?: output<S>
+  }) => {
+    const resolved = values ?? dv(schema),
+      [conflict, setConflict] = useState<ConflictData | null>(null),
+      [er, setEr] = useState<Error | null>(null),
+      [forceSubmit, setForceSubmit] = useState(false),
+      [lastSaved, setLastSaved] = useState<null | number>(null),
+      vRef = useRef(resolved),
+      autoSaveTimerRef = useRef<NodeJS.Timeout | null>(null)
+
+    vRef.current = resolved
+    if (Object.keys(resolved).some(k => !(k in schema.shape))) throw new Error('Form values include keys not in schema')
+    const meta = useMemo(() => buildMeta(schema), [schema]),
+      instance = useTanStackForm({
+        defaultValues: resolved,
+        // eslint-disable-next-line max-statements
+        onSubmit: async ({ value }) => {
+          setEr(null)
+          try {
+            const coerced = coerceOptionals(schema, value),
+              result = await onSubmit(coerced, forceSubmit),
+              newValues = resetOnSuccess && isRecord(result) ? result : value
+            instance.reset(newValues)
+            if (resetOnSuccess && isRecord(result)) vRef.current = result
+            setForceSubmit(false)
+            setLastSaved(Date.now())
+            onSuccess?.()
+          } catch (error) {
+            const conflictData = handleConflict(error)
+            if (conflictData) {
+              setConflict(conflictData)
+              onConflict?.(conflictData)
+              return
+            }
+            const err = submitError(error)
+            setEr(err)
+            onError?.(err)
+          }
+        },
+        validators: { onSubmit: schema as unknown as StandardSchemaV1<output<S>, unknown> }
+      }) as unknown as Api<output<S>>,
+      { isDirty, isSubmitting } = useStore(instance.store, s => ({ isDirty: s.isDirty, isSubmitting: s.isSubmitting }))
+
+    useEffect(() => {
+      if (!(autoSave?.enabled && isDirty)) return
+      if (autoSaveTimerRef.current) clearTimeout(autoSaveTimerRef.current)
+      autoSaveTimerRef.current = setTimeout(() => {
+        instance.handleSubmit()
+      }, autoSave.debounceMs)
+      return () => {
+        if (autoSaveTimerRef.current) clearTimeout(autoSaveTimerRef.current)
+      }
+    }, [autoSave?.enabled, autoSave?.debounceMs, isDirty, instance])
+    return {
+      conflict,
+      error: er,
+      instance,
+      isDirty,
+      isPending: isSubmitting,
+      lastSaved,
+      meta,
+      reset: (vals?: output<S>) => {
+        const resetVals = vals ?? vRef.current
+        instance.reset(resetVals)
+        if (vals) vRef.current = vals
+        setEr(null)
+        setLastSaved(null)
+      },
+      resolveConflict: (action: 'cancel' | 'overwrite' | 'reload') => {
+        if (action === 'overwrite') {
+          setConflict(null)
+          setForceSubmit(true)
+          instance.handleSubmit()
+        } else if (action === 'reload') {
+          setConflict(null)
+          instance.reset(vRef.current)
+        } else setConflict(null)
+      },
+      schema,
+      watch: <K extends keyof output<S>>(name: K) =>
+        useStore(instance.store, s => s.values[name as string]) as output<S>[K]
+    } satisfies FormReturn<output<S>, S>
+  },
+  useFormMutation = <S extends ZodObject<ZodRawShape>>({
+    mutation: mutationRef,
+    onConflict,
+    onError,
+    onSuccess,
+    resetOnSuccess = true,
+    schema,
+    transform,
+    values
+  }: {
+    mutation: FunctionReference<'mutation'>
+    onConflict?: (data: ConflictData) => void
+    onError?: (e: unknown) => void
+    onSuccess?: () => void
+    resetOnSuccess?: boolean
+    schema: S
+    transform?: (d: output<S>) => Record<string, unknown>
+    values?: output<S>
+  }) => {
+    const mutate = useMutation(mutationRef)
+    return useForm({
+      onConflict,
+      onError,
+      onSubmit: async (d: output<S>) => {
+        const args = transform ? transform(d) : d
+        await mutate(args)
+        return d
+      },
+      onSuccess,
+      resetOnSuccess,
+      schema,
+      values
+    })
+  }
+
+export type { Api, ConflictData, FieldMetaMap, FormReturn }
+export { buildMeta, useForm, useFormMutation }

package/src/react/index.ts

@@ -0,0 +1,8 @@
+export { useForm, useFormMutation } from './form'
+export { buildMeta, getMeta } from './form-meta'
+export { canEditResource, OrgProvider, useMyOrgs, useOrg, useOrgMutation, useOrgQuery } from './org'
+export { setActiveOrgCookieClient, useActiveOrg } from './use-active-org'
+export { useBulkSelection } from './use-bulk-selection'
+export { default as useOnlineStatus } from './use-online-status'
+export { useOptimisticMutation } from './use-optimistic'
+export { default as useUpload } from './use-upload'

package/src/react/org.tsx

@@ -0,0 +1,96 @@
+/* eslint-disable @typescript-eslint/no-unnecessary-type-parameters, @typescript-eslint/no-unsafe-return */
+'use client'
+
+import type { FunctionReference } from 'convex/server'
+import type { ReactNode } from 'react'
+
+import { useMutation, useQuery } from 'convex/react'
+import { createContext, use, useCallback, useMemo } from 'react'
+
+import type { OrgRole } from '../server/types'
+
+interface OrgContextValue<O extends OrgDoc = OrgDoc, M = unknown> {
+  canDeleteOrg: boolean
+  canManageAdmins: boolean
+  canManageMembers: boolean
+  isAdmin: boolean
+  isMember: boolean
+  isOwner: boolean
+  membership: M | null
+  org: O
+  orgId: string
+  role: OrgRole
+}
+
+interface OrgDoc {
+  [key: string]: unknown
+  _id: string
+}
+
+const OrgContext = createContext<null | OrgContextValue>(null)
+
+interface OrgProviderProps<O extends OrgDoc, M> {
+  children: ReactNode
+  membership: M | null
+  org: O
+  role: OrgRole
+}
+
+const OrgProvider = <O extends OrgDoc, M>({ children, membership, org, role }: OrgProviderProps<O, M>) => {
+    const value = useMemo<OrgContextValue<O, M>>(() => {
+      const isOwner = role === 'owner',
+        isAdmin = role === 'owner' || role === 'admin'
+      return {
+        canDeleteOrg: isOwner,
+        canManageAdmins: isOwner,
+        canManageMembers: isAdmin,
+        isAdmin,
+        isMember: true,
+        isOwner,
+        membership,
+        org,
+        orgId: org._id,
+        role
+      }
+    }, [membership, org, role])
+
+    return <OrgContext value={value as OrgContextValue}>{children}</OrgContext>
+  },
+  useOrg = <O extends OrgDoc = OrgDoc, M = unknown>() => {
+    const ctx = use(OrgContext)
+    if (!ctx) throw new Error('useOrg must be used inside OrgProvider')
+    return ctx as OrgContextValue<O, M>
+  },
+  useOrgQuery = <F extends FunctionReference<'query'>>(
+    query: F,
+    args?: 'skip' | Omit<F['_args'], 'orgId'>
+  ): F['_returnType'] | undefined => {
+    const { orgId } = useOrg()
+    return useQuery(query as FunctionReference<'query'>, args === 'skip' ? 'skip' : { ...args, orgId })
+  },
+  useOrgMutation = <F extends FunctionReference<'mutation'>>(mutation: F) => {
+    const { orgId } = useOrg(),
+      mutate = useMutation(mutation as FunctionReference<'mutation'>)
+    return useCallback(
+      async (args?: Omit<F['_args'], 'orgId'>): Promise<F['_returnType']> => mutate({ ...args, orgId }),
+      [mutate, orgId]
+    )
+  },
+  canEditResource = ({
+    editorsList,
+    isAdmin,
+    resource,
+    userId
+  }: {
+    editorsList: { userId: string }[]
+    isAdmin: boolean
+    resource: { userId: string }
+    userId: string
+  }): boolean => isAdmin || resource.userId === userId || editorsList.some(e => e.userId === userId),
+  useMyOrgs = <O extends OrgDoc>(myOrgsQuery: FunctionReference<'query'>) => {
+    const data = useQuery(myOrgsQuery) as undefined | { org: O; role: OrgRole }[]
+    return { isLoading: data === undefined, orgs: (data ?? []) as { org: O; role: OrgRole }[] }
+  }
+
+export type { OrgContextValue, OrgDoc, OrgProviderProps }
+export { canEditResource, OrgProvider, useMyOrgs, useOrg, useOrgMutation, useOrgQuery }

package/src/react/use-active-org.ts

@@ -0,0 +1,48 @@
+/* eslint-disable @typescript-eslint/no-unnecessary-type-parameters */
+'use client'
+
+import type { FunctionReference } from 'convex/server'
+
+import { useQuery } from 'convex/react'
+import { useCallback, useState } from 'react'
+
+interface OrgDoc {
+  [key: string]: unknown
+  _id: string
+  slug: string
+}
+
+const ACTIVE_ORG_REGEX = /activeOrgId=(?<id>[^;]+)/u,
+  getActiveOrgIdFromCookie = (): null | string => {
+    if (typeof document === 'undefined') return null
+    const match = ACTIVE_ORG_REGEX.exec(document.cookie)
+    return match?.groups?.id ?? null
+  },
+  setActiveOrgCookieClient = ({ orgId, slug }: { orgId: string; slug: string }) => {
+    const maxAge = 60 * 60 * 24 * 365
+    document.cookie = `activeOrgId=${orgId}; path=/; max-age=${maxAge}`
+    document.cookie = `activeOrgSlug=${slug}; path=/; max-age=${maxAge}`
+  },
+  useActiveOrg = <O extends OrgDoc>(orgGetQuery: FunctionReference<'query'>) => {
+    const [activeOrgId, setActiveOrgId] = useState<null | string>(getActiveOrgIdFromCookie),
+      activeOrg = useQuery(orgGetQuery, activeOrgId ? { orgId: activeOrgId } : 'skip') as null | O | undefined,
+      setActiveOrg = useCallback((org: OrgDoc) => {
+        setActiveOrgCookieClient({ orgId: org._id, slug: org.slug })
+        setActiveOrgId(org._id)
+      }, []),
+      clearActiveOrg = useCallback(() => {
+        document.cookie = 'activeOrgId=; path=/; max-age=0'
+        document.cookie = 'activeOrgSlug=; path=/; max-age=0'
+        setActiveOrgId(null)
+      }, [])
+
+    return {
+      activeOrg: activeOrg ?? null,
+      activeOrgId,
+      clearActiveOrg,
+      isLoading: activeOrgId ? activeOrg === undefined : false,
+      setActiveOrg
+    }
+  }
+
+export { setActiveOrgCookieClient, useActiveOrg }

package/src/react/use-bulk-selection.ts

@@ -0,0 +1,47 @@
+/* oxlint-disable promise/prefer-await-to-then */
+'use client'
+
+import { useState } from 'react'
+
+interface UseBulkSelectionOpts {
+  bulkRm: (args: { ids: string[]; orgId: string }) => Promise<unknown>
+  items: { _id: string }[]
+  onError?: (error: unknown) => void
+  onSuccess?: (count: number) => void
+  orgId: string
+}
+
+const useBulkSelection = ({ bulkRm, items, onError, onSuccess, orgId }: UseBulkSelectionOpts) => {
+  const [selected, setSelected] = useState<Set<string>>(new Set()),
+    clear = () => {
+      setSelected(new Set<string>())
+    },
+    toggleSelect = (id: string) => {
+      setSelected(prev => {
+        const next = new Set(prev)
+        if (next.has(id)) next.delete(id)
+        else next.add(id)
+        return next
+      })
+    },
+    toggleSelectAll = () => {
+      if (selected.size === items.length) setSelected(new Set<string>())
+      else setSelected(new Set(items.map(i => i._id)))
+    },
+    handleBulkDelete = () => {
+      if (selected.size === 0) return
+      const count = selected.size
+      bulkRm({ ids: [...selected], orgId })
+        .then(() => {
+          onSuccess?.(count)
+          setSelected(new Set<string>())
+          return null
+        })
+        .catch((bulkError: unknown) => onError?.(bulkError))
+    }
+
+  return { clear, handleBulkDelete, selected, toggleSelect, toggleSelectAll }
+}
+
+export type { UseBulkSelectionOpts }
+export { useBulkSelection }

package/src/react/use-online-status.ts

@@ -0,0 +1,21 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+const useOnlineStatus = () => {
+  const [online, setOnline] = useState(true)
+  useEffect(() => {
+    setOnline(navigator.onLine)
+    const handleOnline = () => setOnline(true),
+      handleOffline = () => setOnline(false)
+    window.addEventListener('online', handleOnline)
+    window.addEventListener('offline', handleOffline)
+    return () => {
+      window.removeEventListener('online', handleOnline)
+      window.removeEventListener('offline', handleOffline)
+    }
+  }, [])
+  return online
+}
+
+export default useOnlineStatus

package/src/react/use-optimistic.ts

@@ -0,0 +1,54 @@
+/* eslint-disable max-statements, @typescript-eslint/no-unsafe-return */
+'use client'
+
+import type { FunctionReference, FunctionReturnType, OptionalRestArgs } from 'convex/server'
+
+import { useMutation } from 'convex/react'
+import { useCallback, useRef, useState } from 'react'
+
+type Args<T extends MutationFn> = OptionalRestArgs<T>[0]
+type MutationFn = FunctionReference<'mutation'>
+
+interface OptimisticOptions<T extends MutationFn, R = FunctionReturnType<T>> {
+  mutation: T
+  onOptimistic?: (args: Args<T>) => void
+  onRollback?: (args: Args<T>, catchError: Error) => void
+  onSuccess?: (result: R, args: Args<T>) => void
+}
+
+const useOptimisticMutation = <T extends MutationFn>({
+  mutation,
+  onOptimistic,
+  onRollback,
+  onSuccess
+}: OptimisticOptions<T>) => {
+  const mutate = useMutation(mutation),
+    [isPending, setIsPending] = useState(false),
+    [mutationError, setMutationError] = useState<Error | null>(null),
+    pendingCount = useRef(0),
+    execute = useCallback(
+      async (args: Args<T>): Promise<FunctionReturnType<T> | null> => {
+        pendingCount.current += 1
+        setIsPending(true)
+        setMutationError(null)
+        onOptimistic?.(args)
+        try {
+          const result = await (mutate as (a: Args<T>) => Promise<FunctionReturnType<T>>)(args)
+          onSuccess?.(result, args)
+          return result
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error('Mutation failed')
+          setMutationError(err)
+          onRollback?.(args, err)
+          return null
+        } finally {
+          pendingCount.current -= 1
+          if (pendingCount.current === 0) setIsPending(false)
+        }
+      },
+      [mutate, onOptimistic, onRollback, onSuccess]
+    )
+  return { error: mutationError, execute, isPending }
+}
+
+export { useOptimisticMutation }