lazyconvex 0.0.0

package/src/react/use-upload.ts

@@ -0,0 +1,101 @@
+// oxlint-disable unicorn/prefer-add-event-listener
+/* eslint-disable no-await-in-loop, max-statements */
+/** biome-ignore-all lint/performance/noAwaitInLoops: retry logic */
+'use client'
+
+import type { FunctionReference } from 'convex/server'
+
+import { useMutation } from 'convex/react'
+import { useRef, useState } from 'react'
+
+interface UploadOptions {
+  retries?: number
+  retryDelay?: number
+}
+
+type UploadResult =
+  | { code: 'ABORTED' | 'INVALID_RESPONSE' | 'NETWORK' | 'URL'; ok: false }
+  | { code: 'HTTP'; ok: false; status: number }
+  | { ok: true; storageId: string }
+
+const sleep = async (ms: number) =>
+    // oxlint-disable-next-line promise/avoid-new
+    new Promise<void>(resolve => {
+      setTimeout(resolve, ms)
+    }),
+  useUpload = (uploadMutation: FunctionReference<'mutation'>, options?: UploadOptions) => {
+    const { retries = 3, retryDelay = 1000 } = options ?? {},
+      getUrl = useMutation(uploadMutation),
+      [progress, setProgress] = useState(0),
+      [uploading, setUploading] = useState(false),
+      [attempt, setAttempt] = useState(0),
+      xhr = useRef<null | XMLHttpRequest>(null),
+      reset = () => {
+        setUploading(false)
+        setProgress(0)
+        setAttempt(0)
+      },
+      uploadOnce = async (file: File): Promise<UploadResult> => {
+        try {
+          const url = (await getUrl()) as string
+          // oxlint-disable-next-line promise/avoid-new
+          return await new Promise(res => {
+            const x = new XMLHttpRequest()
+            xhr.current = x
+            x.upload.onprogress = e => e.lengthComputable && setProgress(Math.round((e.loaded / e.total) * 100))
+            x.onload = () => {
+              if (x.status < 200 || x.status >= 300) return res({ code: 'HTTP', ok: false, status: x.status })
+              try {
+                const parsed: unknown = JSON.parse(x.responseText),
+                  storageId =
+                    typeof parsed === 'object' && parsed !== null && 'storageId' in parsed
+                      ? (parsed as { storageId: unknown }).storageId
+                      : undefined
+                if (typeof storageId !== 'string') return res({ code: 'INVALID_RESPONSE', ok: false })
+                setProgress(100)
+                res({ ok: true, storageId })
+              } catch {
+                res({ code: 'INVALID_RESPONSE', ok: false })
+              }
+            }
+            x.onerror = () => res({ code: 'NETWORK', ok: false })
+            x.onabort = () => res({ code: 'ABORTED', ok: false })
+            x.open('POST', url)
+            x.setRequestHeader('Content-Type', file.type || 'application/octet-stream')
+            x.send(file)
+          })
+        } catch {
+          return { code: 'URL', ok: false }
+        }
+      },
+      upload = async (file: File): Promise<UploadResult> => {
+        setUploading(true)
+        setProgress(0)
+        setAttempt(0)
+        try {
+          for (let i = 0; i < retries; i += 1) {
+            setAttempt(i + 1)
+            const result = await uploadOnce(file)
+            if (result.ok || result.code === 'ABORTED') return result
+            if (i < retries - 1) await sleep(retryDelay * (i + 1))
+          }
+          return { code: 'NETWORK', ok: false }
+        } finally {
+          setUploading(false)
+        }
+      }
+    return {
+      attempt,
+      cancel: () => {
+        xhr.current?.abort()
+        reset()
+      },
+      isUploading: uploading,
+      progress,
+      reset,
+      upload
+    }
+  }
+
+export type { UploadOptions, UploadResult }
+export default useUpload

package/src/retry.ts

@@ -0,0 +1,47 @@
+/* eslint-disable no-await-in-loop */
+// biome-ignore-all lint/performance/noAwaitInLoops: x
+// biome-ignore-all lint/suspicious/useAwait: x
+
+interface RetryOptions {
+  base?: number
+  initialDelayMs?: number
+  maxAttempts?: number
+  maxDelayMs?: number
+}
+const DEFAULT_OPTIONS: Required<RetryOptions> = {
+    base: 2,
+    initialDelayMs: 500,
+    maxAttempts: 3,
+    maxDelayMs: 10_000
+  },
+  sleep = async (ms: number) =>
+    // oxlint-disable-next-line promise/avoid-new
+    new Promise<void>(resolve => {
+      setTimeout(resolve, ms)
+    }),
+  calculateDelay = (attempt: number, opts: Required<RetryOptions>) => {
+    const jitter = Math.random() * 0.3 + 0.85
+    return Math.min(opts.initialDelayMs * opts.base ** attempt * jitter, opts.maxDelayMs)
+  },
+  withRetry = async <T>(fn: () => Promise<T>, options: RetryOptions = {}): Promise<T> => {
+    const opts = { ...DEFAULT_OPTIONS, ...options }
+    let lastError: Error = new Error('Retry failed')
+    for (let attempt = 0; attempt < opts.maxAttempts; attempt += 1)
+      try {
+        return await fn()
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error))
+        if (attempt < opts.maxAttempts - 1) await sleep(calculateDelay(attempt, opts))
+      }
+    throw lastError
+  },
+  fetchWithRetry = async (url: string, options?: RequestInit & { retry?: RetryOptions }): Promise<Response> => {
+    const { retry, ...fetchOptions } = options ?? {}
+    return withRetry(async () => {
+      const response = await fetch(url, fetchOptions)
+      if (!response.ok && response.status >= 500) throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+      return response
+    }, retry)
+  }
+
+export { fetchWithRetry, withRetry }

package/src/schema.ts

@@ -0,0 +1,30 @@
+import type { ZodObject, ZodRawShape } from 'zod/v4'
+
+import { zid } from 'convex-helpers/server/zod4'
+import { array, object, string } from 'zod/v4'
+
+const cvFile = () => zid('_storage').meta({ cv: 'file' as const }),
+  cvFiles = () => array(cvFile()).meta({ cv: 'files' as const }),
+  child = <const P extends string, const S extends ZodRawShape, const FK extends keyof S & string>(config: {
+    foreignKey: FK
+    index?: string
+    parent: P
+    schema: ZodObject<S>
+  }): {
+    foreignKey: FK
+    index: string
+    parent: P
+    schema: ZodObject<S>
+  } => ({
+    ...config,
+    index: config.index ?? `by_${config.parent}`
+  }),
+  orgSchema = object({
+    avatarId: zid('_storage').nullable().optional(),
+    name: string().min(1),
+    slug: string()
+      .min(1)
+      .regex(/^[a-z0-9-]+$/u)
+  })
+
+export { child, cvFile, cvFiles, orgSchema }

package/src/server/cache-crud.ts

@@ -0,0 +1,175 @@
+/* eslint-disable no-await-in-loop, @typescript-eslint/no-unnecessary-type-parameters */
+import type { GenericDataModel } from 'convex/server'
+import type { ZodObject, ZodRawShape } from 'zod/v4'
+
+import { zodOutputToConvexFields as z2c, zid } from 'convex-helpers/server/zod4'
+import { anyApi } from 'convex/server'
+import { v } from 'convex/values'
+import { boolean } from 'zod/v4'
+
+import type { ActionCtxLike, CacheBuilders, CacheCrudResult, DbCtx, FilterLike, IndexLike, Rec } from './types'
+
+import { dbDelete, dbInsert, dbPatch } from './db'
+import { err, noFetcher, pgOpts, pickFields, time } from './helpers'
+
+const makeCacheCrud = <S extends ZodRawShape, K extends string, DM extends GenericDataModel = GenericDataModel>({
+  builders: b,
+  fetcher,
+  key,
+  schema,
+  table,
+  ttl = 7 * 24 * 60 * 60 * 1000
+}: {
+  builders: CacheBuilders<DM>
+  fetcher?: (c: unknown, key: unknown) => Promise<unknown>
+  key: K
+  schema: ZodObject<S>
+  table: string
+  ttl?: number
+}): CacheCrudResult<S> => {
+  const keys = Object.keys(schema.shape),
+    pick = (d: Rec) => pickFields(d, keys),
+    valid = (d: Rec) => ((d.updatedAt as number | undefined) ?? (d._creationTime as number)) + ttl > Date.now(),
+    partial = schema.partial(),
+    idx = `by_${key}` as const,
+    kArgs = z2c({ [key]: schema.shape[key] } as never) as Rec,
+    idArgs = { id: zid(table) },
+    expArgs = { includeExpired: boolean().optional() },
+    listArgs = { includeExpired: boolean().optional(), paginationOpts: pgOpts },
+    retFields = z2c(schema.extend({ cacheHit: boolean() }).shape) as Rec,
+    kVal = kArgs[key] ?? err('INVALID_WHERE'),
+    byK = (x: unknown) => ((i: IndexLike) => i.eq(key, x)) as never,
+    getInt = b.internalQuery({
+      args: kArgs as never,
+      handler: (async (c: DbCtx, a: Rec) => c.db.query(table).withIndex(idx, byK(a[key])).first()) as never
+    }),
+    get = b.query({
+      args: kArgs as never,
+      handler: (async (c: DbCtx, a: Rec) => {
+        const d = await c.db.query(table).withIndex(idx, byK(a[key])).first()
+        return d && valid(d) ? { ...d, cacheHit: true } : null
+      }) as never
+    }),
+    read = b.cq({ args: idArgs, handler: (async (c: DbCtx, { id }: { id: string }) => c.db.get(id)) as never }),
+    all = b.cq({
+      args: expArgs,
+      handler: (async (c: DbCtx, { includeExpired: ie }: { includeExpired?: boolean }) => {
+        const d = await c.db.query(table).order('desc').collect()
+        return ie ? d : d.filter(valid)
+      }) as never
+    }),
+    list = b.cq({
+      args: listArgs,
+      handler: (async (
+        c: DbCtx,
+        { includeExpired: ie, paginationOpts: op }: { includeExpired?: boolean; paginationOpts: Rec }
+      ) => {
+        const qr = c.db.query(table).order('desc')
+        if (ie) return qr.paginate(op)
+        const { page, ...rest } = await qr.paginate({ ...op, numItems: (op.numItems as number) * 2 })
+        return { ...rest, page: page.filter(valid).slice(0, op.numItems as number) }
+      }) as never
+    }),
+    upsert = async (c: DbCtx, data: Rec) => {
+      const ex = await c.db.query(table).withIndex(idx, byK(data[key])).first(),
+        wt = { ...data, ...time() }
+      if (ex) {
+        await dbPatch(c.db, ex._id as string, wt)
+        return ex._id
+      }
+      return dbInsert(c.db, table, wt)
+    },
+    set = b.internalMutation({
+      args: { data: v.object(z2c(schema.shape) as never) },
+      handler: (async (c: DbCtx, { data }: { data: Rec }) => {
+        await upsert(c, pick(data))
+      }) as never
+    }),
+    create = b.cm({ args: schema.shape, handler: (async (c: DbCtx, d: Rec) => upsert(c, d)) as never }),
+    update = b.cm({
+      args: { ...idArgs, ...partial.shape },
+      handler: (async (c: DbCtx, a: Rec) => {
+        const { id, ...d } = a as Rec & { id: string },
+          ex = await c.db.get(id),
+          t = time()
+        if (!ex) return err('NOT_FOUND')
+        await dbPatch(c.db, id, { ...d, ...t })
+        return { ...ex, ...d, ...t }
+      }) as never
+    }),
+    rm = b.cm({
+      args: idArgs,
+      handler: (async (c: DbCtx, { id }: { id: string }) => {
+        const d = await c.db.get(id)
+        if (d) await c.db.delete(id)
+        return d
+      }) as never
+    }),
+    invalidate = b.mutation({
+      args: kArgs as never,
+      handler: (async (c: DbCtx, a: Rec) => {
+        const d = await c.db.query(table).withIndex(idx, byK(a[key])).first()
+        if (d) await dbDelete(c.db, d._id as string)
+        return d
+      }) as never
+    }),
+    purge = b.cm({
+      args: {},
+      handler: (async (c: DbCtx) => {
+        const cut = Date.now() - ttl,
+          exp = await c.db
+            .query(table)
+            .filter((qr: FilterLike) => qr.lt(qr.field('_creationTime'), cut))
+            .collect()
+        // biome-ignore lint/performance/noAwaitInLoops: x
+        for (const d of exp) await dbDelete(c.db, d._id as string)
+        return exp.length
+      }) as never
+    }),
+    tPath = (anyApi as Rec)[table] as Rec,
+    tKArgs = { [key]: kVal } as Rec,
+    doFetch = async (c: ActionCtxLike, kv: unknown) => {
+      const d = pick((await fetcher?.(c, kv)) as Rec)
+      await c.runMutation(tPath.set as string, { data: d })
+      return { ...d, cacheHit: false }
+    },
+    load = fetcher
+      ? b.action({
+          args: tKArgs as never,
+          handler: (async (c: ActionCtxLike, a: Rec) => {
+            const kv = a[key],
+              d = await c.runQuery(tPath.getInternal as string, { [key]: kv })
+            return d && valid(d as Rec) ? { ...pick(d as Rec), cacheHit: true } : doFetch(c, kv)
+          }) as never,
+          returns: v.object(retFields as never)
+        })
+      : b.action(noFetcher as never),
+    refresh = fetcher
+      ? b.action({
+          args: tKArgs as never,
+          handler: (async (c: ActionCtxLike, a: Rec) => {
+            const kv = a[key]
+            await c.runMutation(tPath.invalidate as string, { [key]: kv })
+            return doFetch(c, kv)
+          }) as never,
+          returns: v.object(retFields as never)
+        })
+      : b.action(noFetcher as never)
+  return {
+    all,
+    create,
+    get,
+    getInternal: getInt,
+    invalidate,
+    list,
+    load,
+    purge,
+    read,
+    refresh,
+    rm,
+    set,
+    update
+  } as unknown as CacheCrudResult<S>
+}
+
+export { makeCacheCrud }

package/src/server/check-schema.ts

@@ -0,0 +1,29 @@
+import type { ZodObject, ZodRawShape } from 'zod/v4'
+
+import { elementOf, isArrayType, unwrapZod } from '../zod'
+import { isRecord } from './error'
+
+interface Output {
+  path: string
+  zodType: string
+}
+
+const unsupportedTypes = new Set(['pipe', 'transform']),
+  scan = (schema: unknown, path: string, out: Output[]) => {
+    const b = unwrapZod(schema)
+    if (b.type && unsupportedTypes.has(b.type)) out.push({ path, zodType: b.type })
+    if (isArrayType(b.type)) return scan(elementOf(b.schema), `${path}[]`, out)
+    if (b.type === 'object' && b.schema && isRecord((b.schema as unknown as { shape?: unknown }).shape))
+      for (const [k, v] of Object.entries((b.schema as unknown as { shape: Record<string, unknown> }).shape))
+        scan(v, path ? `${path}.${k}` : k, out)
+  },
+  checkSchema = (schemas: Record<string, ZodObject<ZodRawShape>>) => {
+    const res: Output[] = []
+    for (const [table, schema] of Object.entries(schemas)) scan(schema, table, res)
+    if (res.length) {
+      for (const f of res) process.stderr.write(`${f.path}: unsupported zod type "${f.zodType}"\n`)
+      process.exitCode = 1
+    }
+  }
+
+export { checkSchema }

package/src/server/child.ts

@@ -0,0 +1,98 @@
+import type { ZodObject, ZodRawShape } from 'zod/v4'
+
+import { zid } from 'convex-helpers/server/zod4'
+
+import type { BaseBuilders, ChildCrudResult, IndexLike, Rec, UserCtx } from './types'
+
+import { dbDelete, dbInsert, dbPatch } from './db'
+import { err, pickFields, time } from './helpers'
+
+interface ChildMeta<S extends ZodRawShape = ZodRawShape> {
+  foreignKey: string
+  index: string
+  parent: string
+  schema: ZodObject<S>
+}
+
+const makeChildCrud = <S extends ZodRawShape>({
+  builders,
+  meta,
+  table
+}: {
+  builders: BaseBuilders
+  meta: ChildMeta<S>
+  table: string
+}): ChildCrudResult<S> => {
+  const { m, q } = builders,
+    { foreignKey, index, parent, schema } = meta,
+    getFK = (doc: Rec): string => doc[foreignKey] as string,
+    schemaKeys = Object.keys(schema.shape),
+    partial = schema.partial(),
+    idArgs = { id: zid(table) },
+    // oxlint-disable-next-line unicorn/consistent-function-scoping
+    verifyParentOwnership = async (ctx: UserCtx, parentId: string) => {
+      const p = await ctx.db.get(parentId)
+      return p && p.userId === ctx.user._id ? p : null
+    },
+    create = m({
+      args: { ...schema.shape, [foreignKey]: zid(parent) },
+      handler: (async (ctx: UserCtx, a: Rec) => {
+        const args = a,
+          parentId = args[foreignKey] as string,
+          data = schema.parse(pickFields(args, schemaKeys))
+        if (!(await verifyParentOwnership(ctx, parentId))) return err('NOT_FOUND', `${table}:create`)
+        return dbInsert(ctx.db, table, { ...data, [foreignKey]: parentId, ...time() })
+      }) as never
+    }),
+    update = m({
+      args: { ...idArgs, ...partial.shape },
+      handler: (async (ctx: UserCtx, a: Rec) => {
+        const args = a as Rec & { id: string },
+          { id, ...rest } = args,
+          data = partial.parse(pickFields(rest, schemaKeys)),
+          doc = await ctx.db.get(id)
+        if (!doc) return err('NOT_FOUND', `${table}:update`)
+        const parentId = getFK(doc)
+        if (!(await verifyParentOwnership(ctx, parentId))) return err('NOT_FOUND', `${table}:update`)
+        await dbPatch(ctx.db, id, { ...data, ...time() })
+        return ctx.db.get(id)
+      }) as never
+    }),
+    rm = m({
+      args: idArgs,
+      handler: (async (ctx: UserCtx, { id }: { id: string }) => {
+        const doc = await ctx.db.get(id)
+        if (!doc) return err('NOT_FOUND', `${table}:rm`)
+        const parentId = getFK(doc)
+        if (!(await verifyParentOwnership(ctx, parentId))) return err('NOT_FOUND', `${table}:rm`)
+        await dbDelete(ctx.db, id)
+        return doc
+      }) as never
+    }),
+    list = q({
+      args: { [foreignKey]: zid(parent) },
+      handler: (async (ctx: UserCtx, a: Rec) => {
+        const args = a,
+          parentId = args[foreignKey] as string
+        if (!(await verifyParentOwnership(ctx, parentId))) return err('NOT_AUTHORIZED', `${table}:list`)
+        return ctx.db
+          .query(table)
+          .withIndex(index, ((i: IndexLike) => i.eq(foreignKey, parentId)) as never)
+          .order('asc')
+          .collect()
+      }) as never
+    }),
+    get = q({
+      args: idArgs,
+      handler: (async (ctx: UserCtx, { id }: { id: string }) => {
+        const doc = await ctx.db.get(id)
+        if (!doc) return null
+        const parentId = getFK(doc)
+        if (!(await verifyParentOwnership(ctx, parentId))) return err('NOT_AUTHORIZED', `${table}:get`)
+        return doc
+      }) as never
+    })
+  return { create, get, list, rm, update } as unknown as ChildCrudResult<S>
+}
+
+export { makeChildCrud }