API Reference

bun add noboil

bun add noboil

import { noboil } from 'noboil/convex/server'
import { s } from './s'

const api = noboil({
  query, mutation, action, internalQuery, internalMutation, getAuthUserId,
  tables: ({ table }) => ({
    blog: table(s.blog, { rateLimit: { max: 10, window: 60_000 }, search: 'content' }),
    profile: table(s.blogProfile),
    project: table(s.project, { acl: true }),
    message: table(s.message, { pub: { parentField: 'isPublic' } })
  })
})

const { pq, q, m } = api.setup

import { setup } from 'noboil/convex/server'
import { getAuthUserId } from '@convex-dev/auth/server'
import {
  action,
  internalMutation,
  internalQuery,
  mutation,
  query
} from './_generated/server'

const { crud, orgCrud, singletonCrud, cacheCrud, pq, q, m } = setup({
  query,
  mutation,
  action,
  internalQuery,
  internalMutation,
  getAuthUserId
})

export const { create, list, read, rm, update } = crud(
  'blog',
  owned.blog,
  {
    rateLimit: { max: 10, window: 60_000 },
    search: 'content',
    softDelete: true
  }
)

export const {
  create,
  rm,
  update,
  pub: { list, read, search }
} = crud('blog', owned.blog, { search: 'content' })

export const {
  addEditor,
  create,
  editors,
  list,
  read,
  removeEditor,
  rm,
  setEditors,
  update
} = orgCrud('project', orgScoped.project, {
  acl: true,
  cascade: orgCascade(orgScoped.task, { foreignKey: 'projectId', table: 'task' })
})

export const { get, upsert } = singletonCrud('profile', singleton.profile)

export const { all, get, load, refresh, invalidate, purge } = cacheCrud({
  table: 'movie',
  schema: base.movie,
  key: 'tmdb_id',
  ttl: 86400,
  fetcher: async (_, tmdbId) => {
    const res = await fetch(`https://api.themoviedb.org/3/movie/${tmdbId}`)
    return res.json()
  }
})

// backend/convex/lazy.ts — register
tables: ({ table }) => ({
  vote: table(s.vote, { softDelete: true, rateLimit: 30 })
})
// backend/convex/convex/vote.ts — re-export
export const {
  append, appendBulk, auth, list, listAfter, purgeByParent, read,
  restoreByParent, rm, update
} = api.vote

tables: ({ table }) => ({
  siteConfig: table(s.siteConfig, { softDelete: true })
})
export const { get, list, restore, rm, set } = api.siteConfig

tables: ({ table }) => ({
  pollVoteQuota: table(s.pollVoteQuota)
})
export const { check, consume, record } = api.pollVoteQuota

import { noboil } from 'noboil/spacetimedb/server'
import { s } from '../s'

export default noboil({ tables: ({ table }) => ({
  blog: table(s.blog, { pub: 'published' }),
  profile: table(s.profile),
  project: table(s.project),
  team: table(s.team, { unique: ['slug'] }),
  movie: table(s.movie, { key: 'tmdbId' }),
  message: table(s.message)
}) })

const blog = table(owned.blog, { pub: 'published' })
const project = table(orgScoped.project)
const org = table(org.team, { unique: ['slug'] })
const profile = table(singleton.profile)
const message = table(children.message)
const movie = table(base.movie, { key: 'tmdbId' })
const file = table.file()

table(s.blog, { pub: 'published' }) // visible when published=true OR own row
table(s.chat, { pub: 'isPublic' })  // visible when isPublic=true OR own row
table(s.chat, { pub: true })        // fully public, no RLS filter
table(s.blog)                       // private — only own rows visible

import { makePresence } from 'noboil/spacetimedb/server'

const presenceFns = makePresence(spacetimedb, {
  dataField: t.string(),
  roomIdField: t.string(),
  pk: tbl => tbl.id,
  table: db => db.presence,
  tableName: 'presence'
})

import { makeFileUpload } from 'noboil/spacetimedb/server'

const fileCrud = makeFileUpload(spacetimedb, {
  fields: {
    contentType: t.string(),
    filename: t.string(),
    size: t.number(),
    data: t.byteArray()
  },
  idField: t.u32(),
  namespace: 'file',
  pk: tbl => tbl.id,
  table: db => db.file,
  options: {
    maxFileSize: 10 * 1024 * 1024,
    allowedTypes: new Set(['image/jpeg', 'image/png', 'application/pdf'])
  }
})

import { useList, useOwnRows, usePresence, useInfiniteList, useSearch } from 'noboil/convex/react'

import { useList, useOwnRows, usePresence, useInfiniteList, useSearch } from 'noboil/spacetimedb/react'

import { useOwnRows } from 'noboil/convex/react'

const blogs = useOwnRows(allBlogs, me ? b => b.userId === me._id : null)

import { useOwnRows } from 'noboil/spacetimedb/react'

const blogs = useOwnRows(
  allBlogs,
  identity ? b => b.userId.isEqual(identity) : null
)

import { usePresence } from 'noboil/convex/react'

const refs = {
  heartbeat: api.presence.heartbeat,
  leave: api.presence.leave,
  list: api.presence.list,
}

const { users, updatePresence } = usePresence(refs, docId, {
  data: { cursor: { x: 0, y: 0 }, status: 'viewing' as const },
})

updatePresence({ cursor: { x: 100, y: 200 }, status: 'editing' })

import { usePresence } from 'noboil/spacetimedb/react'
import { useTable, useReducer } from 'spacetimedb/react'
import { tables, reducers } from '@/generated/module_bindings'

const [presenceRows, isReady] = useTable(tables.presence)
const heartbeat = useReducer(reducers.presence_heartbeat_presence)

const { users, updatePresence } = usePresence(
  presenceRows,
  async ({ data } = {}) => heartbeat({ roomId: 'main', data: JSON.stringify(data ?? {}) }),
  { enabled: true, heartbeatIntervalMs: 15_000, ttlMs: 30_000 }
)

updatePresence({ cursor: { x: 100, y: 200 } })

import { useFormMutation } from 'noboil/convex/react'

const form = useFormMutation({
  schema: blogSchema,
  mutate: api.blogs.create,
  toast: { success: 'Created', error: 'Failed' }
})

import { useFormMutation } from 'noboil/spacetimedb/react'

const form = useFormMutation({
  mutate: useReducer(reducers.createWiki),
  toast: { success: 'Created' },
  onSuccess: () => router.push('/wiki'),
  schema: wiki,
  transform: d => ({ ...d, orgId: Number(org._id) })
})

import { useMutation } from 'noboil/spacetimedb/react'
import { useReducer } from 'spacetimedb/react'
import { reducers } from '@/generated/module_bindings'

const save = useMutation(useReducer, reducers.update_blog, {
  toast: { success: 'Saved', error: 'Save failed' }
})

save({ id: 1, title: 'New title' })

import { useMut } from 'noboil/spacetimedb/react'

const save = useMut(reducers.update_blog, {
  onSuccess: () => toast.success('Saved')
})

import { useOrgQuery } from 'noboil/convex/react'

const projects = useOrgQuery(api.project.read, { status: 'active' })
const skipped = useOrgQuery(api.project.read, 'skip')

import { useOrgMutation } from 'noboil/convex/react'

const remove = useOrgMutation(api.project.rm)
await remove({ id: projectId })

import { useOrgQuery } from 'noboil/spacetimedb/react'

const projects = useOrgQuery(queryProject, { status: 'active' })
const skipped = useOrgQuery(queryProject, 'skip')

import { useOrgMutation } from 'noboil/spacetimedb/react'

const createProject = useOrgMutation(useReducer(reducers.create_project))
await createProject({ name: 'New project' })

import { createOrgHooks } from 'noboil/convex/react'

const { useActiveOrg, useMyOrgs, useOrg, useOrgMutation } = createOrgHooks<MyOrg>()

import { createOrgHooks } from 'noboil/spacetimedb/react'

const { useActiveOrg, useMyOrgs, useOrg, useOrgMutation } = createOrgHooks<
  Org & { _id: string }
>({
  orgIdForMutation: Number
})

const update = useOrgMutation(useReducer(reducers.orgUpdate))
await update(d) // orgId auto-injected as Number(org._id)

import { handleConvexError } from 'noboil/convex/server'

handleConvexError(error, {
  NOT_AUTHENTICATED: () => router.push('/login'),
  CONFLICT: () => toast.error('Someone else edited this'),
  default: () => toast.error('Something went wrong')
})

import { getErrorDetail } from 'noboil/convex/server'

handleConvexError(error, {
  RATE_LIMITED: e => {
    const detail = getErrorDetail(e)
    if (detail?.retryAfter) {
      toast.error(`Too many requests. Try again in ${Math.ceil(detail.retryAfter / 1000)}s`)
    }
  }
})

import { ErrorBoundary } from 'noboil/convex/components'

<ErrorBoundary
  className="p-8"
  fallback={({ error, reset }) => (
    <div>
      <p>Something went wrong</p>
      <button onClick={reset}>Try again</button>
    </div>
  )}
>
  <App />
</ErrorBoundary>

import { extractErrorData, getErrorCode, getErrorMessage } from 'noboil/spacetimedb/server'

try {
  await createPost(data)
} catch (error) {
  const code = getErrorCode(error)
  const message = getErrorMessage(error)
  const detail = extractErrorData(error)
}

import { err, errValidation } from 'noboil/spacetimedb/server'

err('NOT_FOUND')
err('FORBIDDEN', 'User does not own this resource')
errValidation({ title: 'Required', slug: 'Already taken' })

import { ErrorBoundary } from 'noboil/spacetimedb/components'

<ErrorBoundary
  className="p-8"
  fallback={({ error, resetErrorBoundary }) => (
    <div>
      <p>{error.message}</p>
      <button onClick={resetErrorBoundary}>Retry</button>
    </div>
  )}
>
  <MyPage />
</ErrorBoundary>

import { useErrorToast } from 'noboil/convex/react'

const handleError = useErrorToast({
  toast: toast.error,
  handlers: {
    NOT_AUTHENTICATED: () => router.push('/login'),
    CONFLICT: () => toast.error('Someone else edited this')
  }
})

import { useErrorToast } from 'noboil/spacetimedb/react'

const handleError = useErrorToast({
  toast: toast.error,
  handlers: {
    NOT_AUTHENTICATED: () => router.push('/login'),
    FORBIDDEN: () => toast.error('No permission')
  }
})

import { Devtools } from 'noboil/convex/react'

{process.env.NODE_ENV === 'development' && <Devtools />}

import { Devtools } from 'noboil/spacetimedb/react'

{process.env.NODE_ENV === 'development' && <Devtools />}

import { SchemaPlayground } from 'noboil/convex/react'

<SchemaPlayground className="my-8" />

import { SchemaPlayground } from 'noboil/spacetimedb/react'

<SchemaPlayground tables={tables} />

import { defineSteps } from 'noboil/convex/components'

const { StepForm, useStepper } = defineSteps(
  { id: 'profile', label: 'Profile', schema: profileStep },
  { id: 'org', label: 'Organization', schema: orgStep }
)

<StepForm
  stepIndicatorClassNames={{
    button: 'size-9',
    label: 'text-xs',
    nav: 'gap-3',
    separator: 'bg-primary/20',
    step: 'gap-3'
  }}
  stepper={stepper}
/>

import { defineSteps } from 'noboil/spacetimedb/components'

const { StepForm, useStepper, steps } = defineSteps([
  { id: 'profile', label: 'Profile', schema: profileSchema },
  { id: 'org', label: 'Organization', schema: orgSchema }
] as const)

import { auditLog, inputSanitize, slowQueryWarn } from 'noboil/convex/server'

const { crud } = setup({
  // ...
  middleware: [inputSanitize(), auditLog(), slowQueryWarn({ threshold: 200 })]
})

import { noboil, auditLog, inputSanitize, slowQueryWarn } from 'noboil/spacetimedb/server'

export default noboil({
  middleware: [inputSanitize(), auditLog(), slowQueryWarn({ threshold: 200 })],
  tables: ({ table }) => ({ blog: table(s.blog, { pub: 'published' }) })
})

import { pickValues } from 'noboil/convex/zod'

const values = pickValues(singleton.profile, profile)

import type { InferRow, InferCreate, InferUpdate } from 'noboil/spacetimedb/server'
import { schemaVariants } from 'noboil/spacetimedb/zod'
import { partialValues } from 'noboil/spacetimedb/zod'

type PostRow = InferRow<typeof s.post>
type PostCreate = InferCreate<typeof s.post>
type PostUpdate = InferUpdate<typeof s.post>

const { create: createSchema, update: updateSchema } = schemaVariants(postSchema, ['title'])

update(partialValues(editSchema, { id, published: true }))

type PostRow = typeof s.post.$inferRow
type PostCreate = typeof s.post.$inferCreate
type PostUpdate = typeof s.post.$inferUpdate