lazyconvex 0.0.0

package/README.md

@@ -0,0 +1,926 @@
+# lazyconvex
+
+Typesafe fullstack in minutes. Zod schema → Convex backend → React frontend.
+
+Define a Zod schema once → get CRUD endpoints, typesafe forms, file handling, real-time queries, conflict detection, and optimistic updates with zero boilerplate. No REST routes, no API layer, no manual validation.
+
+```tsx
+// WITHOUT: ~80 lines per table (route handler + validation + auth + pagination + error handling + form)
+export const createProduct = mutation({
+  args: { title: v.string(), price: v.number(), photo: v.id('_storage') },
+  handler: async (ctx, args) => {
+    const user = await getAuthUserId(ctx)
+    if (!user) throw new ConvexError('NOT_AUTHENTICATED')
+    return ctx.db.insert('product', { ...args, userId: user, createdAt: Date.now(), updatedAt: Date.now() })
+  }
+})
+// + updateProduct, deleteProduct, getProduct, listProducts, searchProducts, countProducts...
+// + file cleanup on delete, cascade deletes, soft delete, conflict detection, ownership checks...
+// + React form with Zod validation, file upload, error handling, optimistic updates...
+
+// WITH: 3 lines. Same result, fully typesafe.
+const { create, pub, rm, update } = crud('product', owned.product)
+export const { all, count, list, read, search } = pub
+export { create, rm, update }
+```
+
+## Install
+
+```bash
+bun i lazyconvex
+```
+
+## Setup (5 minutes)
+
+### 1. Define your schemas with Zod
+
+```tsx
+// schemas.ts
+import { array, boolean, number, object, string } from 'zod/v4'
+import { zid } from 'convex-helpers/server/zod4'
+import { cvFile, cvFiles } from 'lazyconvex/schema'
+
+export const owned = {
+  product: object({
+    title: string().min(1),
+    price: number().min(0),
+    photo: cvFile().nullable(),
+    attachments: cvFiles().max(5).optional()
+  }),
+  blog: object({
+    title: string().min(1),
+    content: string(),
+    published: boolean(),
+    tags: array(string()).max(10).optional()
+  })
+}
+
+export const orgScoped = {
+  wiki: object({
+    title: string().min(1),
+    content: string().optional(),
+    status: zenum(['draft', 'published']),
+    editors: array(zid('users')).max(100).optional()
+  })
+}
+```
+
+### 2. Register tables in your Convex schema
+
+```tsx
+// convex/schema.ts
+import { defineSchema } from 'convex/server'
+import { orgTable, orgTables, ownedTable, uploadTables } from 'lazyconvex/server'
+import { orgScoped, owned } from '../schemas'
+
+export default defineSchema({
+  ...uploadTables,
+  ...orgTables,
+  product: ownedTable(owned.product),
+  blog: ownedTable(owned.blog),
+  wiki: orgTable(orgScoped.wiki),
+})
+```
+
+### 3. Initialize lazyconvex
+
+```tsx
+// convex/lazy.ts
+import { getAuthUserId } from '@convex-dev/auth/server'
+import { action, internalMutation, internalQuery, mutation, query } from './_generated/server'
+import { setup } from 'lazyconvex/server'
+
+export const { crud, orgCrud, childCrud, cacheCrud, uniqueCheck, pq, q, m } = setup({
+  query, mutation, action, internalQuery, internalMutation,
+  getAuthUserId,
+})
+```
+
+### 4. Create endpoints — one line per table
+
+```tsx
+// convex/product.ts
+import { crud } from './lazy'
+import { owned } from '../schemas'
+
+const { create, pub, rm, update } = crud('product', owned.product)
+export const { all, count, list, read, search } = pub
+export { create, rm, update }
+```
+
+### 5. Use in React
+
+```tsx
+import { useQuery, useMutation } from 'convex/react'
+import { api } from '../convex/_generated/api'
+
+const products = useQuery(api.product.all)
+const createProduct = useMutation(api.product.create)
+```
+
+That's it. You have a fully typed, real-time, authenticated CRUD API with file handling, pagination, search, and ownership checks.
+
+## Contents
+
+- [Quick Start](#quick-start) · [Recipes](#recipes) · [Which Hook?](#which-hook)
+- [Table Types](#table-types) · [CRUD Factory](#crud-factory) · [Child CRUD](#child-crud) · [Cache Factory](#cache-factory)
+- [Frontend](#frontend): [Data Fetching](#data-fetching) · [Forms](#forms-create) · [`useFormMutation`](#useformmutation) · [`pickValues`](#forms-update) · [File Upload](#file-upload) · [Optimistic Updates](#optimistic-updates)
+- [Custom Queries](#custom-queries) · [Relations](#relations) · [Where Clauses](#where-clause-reference)
+- [Error Handling](#error-handling)
+- [Organizations](#organizations) · [ACL (Editors)](#acl-editors)
+- [Known Limitations](#known-limitations) · [Imports Reference](#imports-reference)
+
+## Quick Start
+
+### Owned Table (user-private data)
+
+```tsx
+// 1. Schema
+owned = {
+  product: object({
+    title: string().min(1),
+    price: number().min(0),
+    photo: cvFile().nullable(),
+  })
+}
+// 2. Register: product: ownedTable(owned.product)
+// 3. Endpoints
+const { create, pub, rm, update } = crud('product', owned.product)
+export const { all, count, list, read, search } = pub
+export { create, rm, update }
+// 4. React
+const products = useQuery(api.product.all)
+const createProduct = useMutation(api.product.create)
+```
+
+### Org-Scoped Table with ACL
+
+```tsx
+// 1. Schema
+orgScoped = {
+  wiki: object({
+    title: string().min(1),
+    content: string().optional(),
+    status: zenum(['draft', 'published']),
+    editors: array(zid('users')).max(100).optional()
+  })
+}
+// 2. Register: wiki: orgTable(orgScoped.wiki)
+// 3. Endpoints — acl: true auto-generates editor endpoints
+const { addEditor, all, create, editors, list, read, removeEditor, rm, setEditors, update } = orgCrud(
+  'wiki', orgScoped.wiki, { acl: true }
+)
+export { addEditor, all, create, editors, list, read, removeEditor, rm, setEditors, update }
+// 4. React (inside OrgProvider)
+const wikis = useOrgQuery(api.wiki.list, { paginationOpts: { cursor: null, numItems: 20 } })
+const editorsList = useOrgQuery(api.wiki.editors, { wikiId })
+```
+
+## Recipes
+
+End-to-end patterns for common pages. Org examples assume `<OrgProvider>` context.
+
+### List Page
+
+```tsx
+const items = useOrgQuery(api.project.list, { paginationOpts: { cursor: null, numItems: 20 } })
+const bulkRm = useMutation(api.project.bulkRm)
+const { selected, toggleSelect, handleBulkDelete } = useBulkSelection({
+  bulkRm, items: items?.page ?? [], label: 'project(s)', orgId: org._id
+})
+```
+
+### Create Page
+
+```tsx
+const form = useFormMutation({
+  mutation: api.wiki.create,
+  schema: orgScoped.wiki,
+  transform: d => ({ ...d, orgId: org._id }),
+  onSuccess: () => { toast.success('Created'); router.push(`/org/${org.slug}/wiki`) },
+  resetOnSuccess: true
+})
+
+<Form form={form} render={({ Text, Choose, Submit }) => (
+  <>
+    <Text name='title' label='Title' />
+    <Choose name='status' label='Status' />
+    <Submit>Create</Submit>
+  </>
+)} />
+```
+
+### Edit Page
+
+```tsx
+const doc = useOrgQuery(api.wiki.read, { id: wikiId })
+const remove = useOrgMutation(api.wiki.rm)
+const editorsList = useOrgQuery(api.wiki.editors, { wikiId })
+const canEditDoc = canEditResource({ editorsList, isAdmin, resource: doc, userId: me._id })
+const form = useFormMutation({
+  mutation: api.wiki.update,
+  schema: orgScoped.wiki,
+  values: doc ? pickValues(orgScoped.wiki, doc) : undefined,
+  transform: d => ({ ...d, id: wikiId, orgId: org._id }),
+  onSuccess: () => { toast.success('Updated'); router.push(`/org/${org.slug}/wiki`) }
+})
+
+<PermissionGuard canAccess={canEditDoc} backHref={backUrl} backLabel='wiki' resource='wiki'>
+  <Form form={form} render={({ Text, Choose, Submit }) => (
+    <>
+      <Text name='title' label='Title' />
+      <Submit>Save</Submit>
+    </>
+  )} />
+</PermissionGuard>
+```
+
+### Derived Schemas
+
+Use `.partial()`, `.omit()` for edit vs create forms:
+
+```tsx
+const createBlog = owned.blog.omit({ published: true })
+const editBlog = owned.blog.partial()
+```
+
+## Which Hook?
+
+| Task | Hook | When |
+|------|------|------|
+| Query (owned/public) | `useQuery(api.x.y, args)` | No org context |
+| Query (org-scoped) | `useOrgQuery(api.x.y, args?)` | Inside `OrgProvider`, auto-injects `orgId` |
+| Mutation (owned/public) | `useMutation(api.x.y)` | No org context |
+| Mutation (org-scoped) | `useOrgMutation(api.x.y)` | Inside `OrgProvider`, auto-injects `orgId` |
+| Form (custom submit) | `useForm({ schema, onSubmit })` | Need custom submit logic |
+| Form + mutation | `useFormMutation({ mutation, schema })` | Standard create/update pattern |
+| Edit form values | `pickValues(schema, doc)` | Extract doc fields matching schema |
+
+`useOrgQuery` supports `'skip'` as second arg. `useOrgMutation` returns `(args?) => Promise`. Both omit `orgId` from caller args.
+
+## Table Types
+
+| Type | Factory | Schema Registration | Use Case |
+|------|---------|---------------------|----------|
+| `owned` | `crud()` | `ownedTable()` | User-owned data (has `userId`) |
+| `orgScoped` | `orgCrud()` | `orgTable()` | Org-scoped data (has `orgId` + membership check) |
+| `children` | `childCrud()` | `orgChildTable()` | Nested under parent (e.g., tasks in project) |
+| `base` | `cacheCrud()` | `baseTable()` | External API cache (e.g., TMDB movies) |
+
+## CRUD Factory
+
+```tsx
+const {
+  create, update, rm,                              // mutations
+  pub: { all, count, list, read, search },          // public queries
+  auth: { all, count, list, read, search },         // auth-required queries
+  bulkUpdate, bulkRm,                               // batch ops (max 100)
+  restore                                           // only with softDelete: true
+} = crud('product', owned.product, {
+  cascade: false,     // opt out of cascade deletes (default: true)
+  softDelete: true    // enable soft delete + restore
+})
+```
+
+**Soft Delete**: Add `deletedAt: number().optional()` to your Zod schema.
+
+### `orgCrud` Return Shape
+
+```tsx
+const {
+  create, update, rm,             // mutations (membership required)
+  list, read, all,                // queries (membership required)
+  bulkUpdate, bulkRm,            // batch ops (admin only, max 100)
+  // only when acl: true:
+  addEditor, removeEditor,       // mutations (admin only)
+  editors,                        // query (any member) → { userId, name, email }[]
+  setEditors                      // mutation (admin only)
+} = orgCrud('wiki', orgScoped.wiki, { acl: true })
+```
+
+Without `acl: true`, the editor endpoints are not returned.
+
+## Child CRUD
+
+For entities nested under a parent (messages in a chat, tasks in a project):
+
+```tsx
+import { child } from 'lazyconvex/schema'
+const children = {
+  message: child({
+    parent: 'chat',
+    foreignKey: 'chatId',
+    schema: object({ text: string() })
+  })
+}
+const { create, list, update, rm } = childCrud('message', children.message)
+```
+
+Parent ownership is verified automatically. `list` uses the `by_${parent}` index by default. `foreignKey` is type-checked — a typo raises a compile error.
+
+### Cascade Delete
+
+Deleting a parent removes all children automatically (enabled by default):
+
+```tsx
+await rm({ id: chatId }) // removes chat + all messages
+// Opt out:
+const { rm } = crud('chat', owned.chat, { cascade: false })
+```
+
+Cascade relationships are derived from `children.*.parent` — define once, works everywhere.
+
+### Org Cascade (`orgCascade`)
+
+For org-scoped tables, use `orgCascade` for typed cascade config:
+
+```tsx
+import { orgCascade } from 'lazyconvex/server'
+
+const ops = orgCrud('project', orgScoped.project, {
+  acl: true,
+  cascade: orgCascade({ foreignKey: 'projectId', table: 'task' })
+})
+```
+
+Both `foreignKey` and `table` are type-checked against your schema — typos raise compile errors.
+
+## Cache Factory
+
+For caching external API responses with automatic TTL expiration:
+
+```tsx
+const c = cacheCrud({
+  table: 'movie',
+  schema: base.movie,
+  key: 'tmdb_id',
+  ttl: 7 * 24 * 60 * 60 * 1000, // 7 days
+  fetcher: async (ctx, id) => fetchFromTMDB(id)
+})
+
+export const { load, refresh, get, all, invalidate, purge } = c
+```
+
+| Method | Description |
+|--------|-------------|
+| `load` | Returns cached or fetches if missing/expired |
+| `refresh` | Force re-fetch and update cache |
+| `get` | Get cached only (null if expired) |
+| `all` | List all cached entries |
+| `invalidate` | Delete specific cache entry |
+| `purge` | Delete all expired entries |
+
+```tsx
+const movie = await ctx.runAction(api.movie.load, { tmdb_id: 550 })
+const fresh = await ctx.runAction(api.movie.refresh, { tmdb_id: 550 })
+const cached = useQuery(api.movie.get, { tmdb_id: 550 })
+const movies = useQuery(api.movie.all, { includeExpired: false })
+```
+
+| TTL | Use Case |
+|-----|----------|
+| 1 hour | Real-time prices, stock data |
+| 24 hours | User profiles, frequently updated |
+| 7 days | Movie metadata, static content |
+| 30 days | Rarely changing reference data |
+
+## Frontend
+
+### Data Fetching
+
+```tsx
+// Real-time subscription
+const products = useQuery(api.product.all)
+// Filters (see Where Clause Reference)
+const published = useQuery(api.blog.all, { where: { published: true } })
+const expensive = useQuery(api.product.all, { where: { price: { $gte: 100 } } })
+// Own filter (current user's docs only)
+const myPosts = useQuery(api.blog.all, { where: { own: true } })
+// Skip
+const data = useQuery(api.product.all, isOpen ? {} : 'skip')
+// Pagination
+const { results, loadMore, status } = usePaginatedQuery(api.product.list, {}, { initialNumItems: 20 })
+// Indexed queries (fast lookups)
+const bySlug = useQuery(api.blog.pubIndexed, { index: 'by_slug', key: 'slug', value: 'my-post' })
+```
+
+### Forms (Create)
+
+`values` is optional — defaults are derived from the schema (strings → `''`, numbers → `0`, booleans → `false`, arrays → `[]`, files → `null`, enums → first option). Empty optional strings are auto-coerced to `undefined` on submit.
+
+```tsx
+import { useForm } from 'lazyconvex/react'
+import { Form } from 'lazyconvex/components'
+
+const form = useForm({
+  schema: owned.product,
+  onSubmit: data => create(data),
+  onSuccess: () => toast.success('Created')
+})
+
+<Form form={form} render={({ Text, Num, File, Submit }) => (
+  <>
+    <Text name='title' label='Title' />
+    <Num name='price' label='Price' />
+    <File name='photo' label='Photo' accept='image/*' />
+    <Submit>Save</Submit>
+  </>
+)} />
+```
+
+**Field Components:** `Text`, `Num`, `Choose`, `MultiSelect`, `Arr`, `Toggle`, `Datepick`, `File`, `Files`, `Colorpick`, `Slider`, `Rating`, `Timepick`, `Combobox`, `Submit`
+
+### `useFormMutation`
+
+Combines `useMutation` + `useForm` — avoids separate wiring:
+
+```tsx
+const form = useFormMutation({
+  mutation: api.wiki.update,
+  schema: orgScoped.wiki,
+  values: wiki ? pickValues(orgScoped.wiki, wiki) : undefined,
+  transform: d => ({ ...d, id: wikiId, orgId: org._id }),
+  onSuccess: () => toast.success('Updated'),
+  resetOnSuccess: true
+})
+```
+
+Options: `mutation`, `schema`, `values?`, `transform?`, `onSuccess?`, `onError?`, `onConflict?`, `resetOnSuccess?`.
+
+### Forms (Update)
+
+Use `pickValues` to extract schema-matching fields from an existing doc:
+
+```tsx
+import { pickValues } from 'lazyconvex/zod'
+
+const doc = useQuery(api.product.read, { id })
+const form = useForm({
+  schema: editProduct,
+  values: doc ? pickValues(editProduct, doc) : undefined,
+  onSubmit: async data => {
+    await update({ id, ...data })
+    return data
+  },
+  onSuccess: () => toast.success('Saved')
+})
+```
+
+**Conflict Detection**: Pass `expectedUpdatedAt` to detect concurrent edits:
+
+```tsx
+onSubmit: async data => {
+  await update({ id, ...data, expectedUpdatedAt: doc?.updatedAt })
+}
+```
+
+If another user modified the record, a conflict dialog appears with options to cancel, reload, or overwrite.
+
+**Navigation Guard**: Forms automatically warn about unsaved changes when navigating away.
+
+### Async Validation
+
+Validate against the backend (e.g., check uniqueness):
+
+```tsx
+// Backend
+export const isSlugAvailable = uniqueCheck('blog', 'slug')
+
+// Frontend
+<Text
+  name='slug'
+  label='Slug'
+  asyncValidate={async (value) => {
+    const available = await isSlugAvailable({ value, exclude: id })
+    return available ? undefined : 'Slug already taken'
+  }}
+  asyncDebounceMs={500}
+/>
+```
+
+`uniqueCheck` is fully typesafe — only valid string fields are accepted.
+
+### Auto-Save
+
+```tsx
+const form = useForm({
+  schema: owned.product,
+  onSubmit: data => update({ id, ...data }),
+  autoSave: { enabled: true, debounceMs: 1000 }
+})
+<AutoSaveIndicator lastSaved={form.lastSaved} />
+```
+
+### File Upload
+
+```tsx
+import { useUpload } from 'lazyconvex/react'
+
+const { upload, isUploading, progress } = useUpload()
+const result = await upload(file)
+if (result.ok) await create({ photo: result.storageId })
+```
+
+Image fields auto-compress by default (max 1920px, 0.8 quality):
+
+```tsx
+<File name='photo' />                    // compressed (default)
+<File name='photo' compressImg={false} /> // original quality
+```
+
+`cvFile()` for single file, `cvFiles()` for arrays. Auto-cleanup on doc update/delete. Max 10MB, rate limited 10 uploads/min.
+
+**Auto URL resolution:** Query results include resolved URLs — `photo` (storage ID) → `photoUrl` (string URL), `attachments` (ID array) → `attachmentsUrls` (URL array). No manual `storage.getUrl()` calls.
+
+### Optimistic Updates
+
+```tsx
+import { useOptimisticMutation } from 'lazyconvex/react'
+
+// Delete
+const { execute, isPending, error } = useOptimisticMutation({
+  mutation: api.product.rm,
+  onOptimistic: ({ id }) => setProducts(p => p.filter(x => x._id !== id)),
+  onSuccess: (result, args) => toast.success('Deleted'),
+  onRollback: (args, error) => toast.error('Failed to delete')
+})
+
+// Update
+const { execute } = useOptimisticMutation({
+  mutation: api.product.update,
+  onOptimistic: ({ id, title }) => {
+    setProducts(p => p.map(x => x._id === id ? { ...x, title } : x))
+  },
+  onRollback: () => refetch()
+})
+```
+
+## Custom Queries
+
+When the CRUD factory doesn't cover your access pattern (indexed lookups, joins, aggregations):
+
+```tsx
+// pq = public query (optional auth)
+// q  = auth required query
+// m  = auth required mutation
+const bySlug = pq({
+  args: { slug: z.string() },
+  handler: async (c, { slug }) => {
+    const doc = await c.db.query('blog')
+      .withIndex('by_slug', q => q.eq('slug', slug))
+      .unique()
+    return doc ? (await c.withAuthor([doc]))[0] : null
+  }
+})
+const publish = m({
+  args: { id: zid('blog') },
+  handler: async (c, { id }) => {
+    await c.get(id) // throws if not owner
+    return c.patch(id, { published: true })
+  }
+})
+```
+
+## Relations
+
+Owned tables automatically include author info via `withAuthor`:
+
+```tsx
+const posts = useQuery(api.blog.all)
+// Each post has: { ...data, author: { name, email, ... }, own: boolean }
+```
+
+For custom relations in handlers:
+
+```tsx
+const bySlug = pq({
+  args: { slug: z.string() },
+  handler: async (c, { slug }) => {
+    const doc = await c.db.query('blog')
+      .withIndex('by_slug', q => q.eq('slug', slug))
+      .unique()
+    if (!doc) return null
+    const author = await c.db.get(doc.userId)
+    return { ...doc, author }
+  }
+})
+```
+
+## Where Clause Reference
+
+### Comparison Operators
+
+```tsx
+{ where: { price: { $gt: 100 } } }                // greater than
+{ where: { price: { $gte: 100 } } }               // greater than or equal
+{ where: { price: { $lt: 50 } } }                 // less than
+{ where: { price: { $lte: 50 } } }                // less than or equal
+{ where: { price: { $between: [10, 100] } } }     // inclusive range
+```
+
+### Combining Conditions
+
+```tsx
+{ where: { category: 'tech', published: true } }                          // AND
+{ where: { or: [{ category: 'tech' }, { category: 'life' }] } }          // OR
+```
+
+### Ownership Filter
+
+```tsx
+const myPosts = useQuery(api.blog.all, { where: { own: true } })
+const myPublished = useQuery(api.blog.all, { where: { published: true, own: true } })
+// Single doc ownership check
+const post = useQuery(api.blog.read, { id, own: true })  // null if not owner
+```
+
+| Query | Unauthenticated | Authenticated (owner) | Authenticated (not owner) |
+|-------|:---:|:---:|:---:|
+| `read({ id })` | Returns doc | Returns doc | Returns doc |
+| `read({ id, own: true })` | `null` | Returns doc | `null` |
+| `all({ where: { own: true } })` | `[]` | User's docs | User's docs |
+
+`{ own: true }` automatically uses the `by_user` index for fast lookups. Combinable with other filters.
+
+### Default Where (Factory-Level)
+
+Pre-filter endpoints so consumers only see relevant data:
+
+```tsx
+crud('blog', owned.blog, {
+  pub: { where: { published: true } },
+  auth: { where: { published: true } }
+})
+```
+
+## Error Handling
+
+### Error Codes
+
+| Code | Meaning |
+|------|---------|
+| `NOT_AUTHENTICATED` | User not logged in |
+| `NOT_FOUND` | Doc doesn't exist or not owned |
+| `NOT_AUTHORIZED` | No permission |
+| `CONFLICT` | Concurrent edit detected |
+| `INVALID_WHERE` | Invalid filter syntax |
+| `RATE_LIMITED` | Too many requests |
+| `FILE_TOO_LARGE` | File exceeds 10MB |
+| `INVALID_FILE_TYPE` | File type not allowed |
+| `EDITOR_REQUIRED` | ACL edit permission required |
+
+### Frontend Error Handling
+
+```tsx
+import { handleConvexError, getErrorCode, getErrorMessage } from 'lazyconvex/server'
+
+// Pattern matching
+handleConvexError(error, {
+  NOT_AUTHENTICATED: () => router.push('/login'),
+  CONFLICT: () => toast.error('Someone else edited this'),
+  default: () => toast.error('Something went wrong')
+})
+
+// Or extract info
+const code = getErrorCode(error)  // ErrorCode | undefined
+const msg = getErrorMessage(error)  // human-readable string
+```
+
+`<Form>` shows submit errors automatically. Override with `showError={false}`.
+
+## Organizations
+
+Multi-tenant support with org-scoped data, membership, roles, and invites.
+
+### Roles
+
+- **owner** — stored as `org.userId`, full control
+- **admin** — `orgMember.isAdmin = true`, manage members + bulk ops
+- **member** — read/write own org data
+
+Use `getOrgRole(org, userId, member)` to derive role.
+
+### Permission Model
+
+| Operation | Member (own) | Member (other's) | Editor (`acl: true`) | Admin | Owner |
+|-----------|:---:|:---:|:---:|:---:|:---:|
+| `create` | Y | - | - | Y | Y |
+| `list` / `read` / `all` | Y | Y | Y | Y | Y |
+| `update` | Y | N | Y | Y any | Y any |
+| `rm` | Y | N | Y | Y any | Y any |
+| `bulkUpdate` / `bulkRm` | N | N | N | Y | Y |
+| `addEditor` / `removeEditor` / `setEditors` | N | N | N | Y | Y |
+
+### Define Org-Scoped Table
+
+```tsx
+// Schema
+orgScoped = {
+  project: object({
+    name: string().min(1),
+    editors: array(zid('users')).max(100).optional(),
+    status: zenum(['active', 'archived', 'completed']).optional()
+  })
+}
+// Register: project: orgTable(orgScoped.project)
+// Endpoints — with ACL + cascade delete tasks
+const ops = orgCrud('project', orgScoped.project, {
+  acl: true,
+  cascade: orgCascade({ foreignKey: 'projectId', table: 'task' })
+})
+export const { addEditor, bulkRm, create, editors, list, read, removeEditor, rm, setEditors, update } = ops
+```
+
+### Frontend Usage
+
+```tsx
+import { OrgProvider, useOrg, useOrgQuery, useOrgMutation, canEditResource } from 'lazyconvex/react'
+
+// Wrap org routes in layout
+<OrgProvider membership={membership} org={org} role={role}>
+  {children}
+</OrgProvider>
+
+// Inside org pages
+const { org, role, isAdmin, isOwner, canManageMembers } = useOrg()
+const projects = useOrgQuery(api.project.list, { paginationOpts: { cursor: null, numItems: 20 } })
+const members = useOrgQuery(api.org.members)
+const remove = useOrgMutation(api.project.rm)
+await remove({ id: projectId }) // orgId auto-injected
+
+// Non-org queries still use raw useQuery/useMutation
+const me = useQuery(api.user.me, {})
+```
+
+### Active Org (Cookie-Based)
+
+Active org stored in cookie for SSR/SSG. OrgSwitcher can render anywhere.
+
+```tsx
+import { getActiveOrg } from 'lazyconvex/next'
+import { setActiveOrgCookieClient } from 'lazyconvex/react'
+
+// Server component
+const org = await getActiveOrg(token)
+
+// Client component
+const { activeOrg, setActiveOrg } = useActiveOrg()
+```
+
+### Org Helpers (Server)
+
+```tsx
+import { getOrgMember, getOrgRole, requireOrgMember, requireOrgRole } from 'lazyconvex/server'
+
+const role = getOrgRole(org, userId, member)              // 'owner' | 'admin' | 'member' | null
+const member = await getOrgMember(db, orgId, userId)       // membership record
+const ctx = await requireOrgMember(db, orgId, userId)      // throws if not member
+const ctx = await requireOrgRole({ db, orgId, userId, minRole: 'admin' }) // throws if insufficient
+```
+
+### Org API
+
+```tsx
+// Management
+api.org.create({ name, slug })
+api.org.update({ orgId, name, slug })
+api.org.get({ orgId })
+api.org.getBySlug({ slug })
+api.org.myOrgs
+api.org.remove({ orgId })
+// Membership
+api.org.membership({ orgId })
+api.org.members({ orgId })
+api.org.setAdmin({ orgId, targetUserId, isAdmin })
+api.org.removeMember({ orgId, targetUserId })
+api.org.leave({ orgId })
+api.org.transferOwnership({ orgId, targetUserId })
+// Invites (7-day expiry, single-use)
+api.org.invite({ orgId, email, isAdmin })
+api.org.acceptInvite({ token })
+api.org.revokeInvite({ inviteId })
+api.org.pendingInvites({ orgId })
+// Join requests
+api.org.requestJoin({ orgId, message })
+api.org.approveJoinRequest({ requestId })
+api.org.rejectJoinRequest({ requestId })
+api.org.pendingJoinRequests({ orgId })
+```
+
+## ACL (Editors)
+
+Grant specific org members edit permission on individual items. Other members can only view.
+
+### Enable
+
+Pass `acl: true` to `orgCrud`. The `editors` field (`array(zid('users')).optional()`) must be in your schema.
+
+```tsx
+const ops = orgCrud('wiki', orgScoped.wiki, { acl: true })
+export const { addEditor, all, create, editors, list, read, removeEditor, rm, setEditors, update } = ops
+```
+
+### Auto-Generated Endpoints
+
+The item ID arg is named `${table}Id` (e.g., `projectId`, `wikiId`):
+
+| Endpoint | Args | Access | Returns |
+|----------|------|--------|---------|
+| `addEditor` | `{ orgId, ${table}Id, editorId }` | Admin only | Updated doc |
+| `removeEditor` | `{ orgId, ${table}Id, editorId }` | Admin only | Updated doc |
+| `editors` | `{ orgId, ${table}Id }` | Any member | `{ userId, name, email }[]` |
+| `setEditors` | `{ orgId, ${table}Id, editorIds }` | Admin only | Updated doc |
+
+### Permission Hierarchy
+
+| Role | Can Edit? |
+|------|-----------|
+| Org owner/admin | Always |
+| Item creator | Always (own docs) |
+| In `editors[]` | Yes (when `acl: true`) |
+| Regular member | View only |
+
+### ACL Inheritance (`aclFrom`)
+
+Child tables can inherit ACL from a parent — project editors can edit tasks in that project:
+
+```tsx
+const ops = orgCrud('task', orgScoped.task, {
+  aclFrom: { field: 'projectId', table: 'project' }
+})
+```
+
+`field` is typed against `Doc<T>` — a typo raises a compile error. No ACL endpoints are generated for `aclFrom` tables (editors are managed on the parent).
+
+### `canEditResource` (Frontend)
+
+```tsx
+import { canEditResource } from 'lazyconvex/react'
+
+const canEdit = canEditResource({ editorsList, isAdmin, resource: doc, userId: me._id })
+```
+
+### `canEdit` (Server)
+
+```tsx
+import { canEdit } from 'lazyconvex/server'
+
+const allowed = canEdit({ acl: true, doc: { editors: project.editors, userId: project.userId }, role, userId })
+```
+
+### Components
+
+```tsx
+import { EditorsSection, PermissionGuard } from 'lazyconvex/components'
+
+// Editor management UI
+<EditorsSection
+  editorsList={editorsList}
+  members={members}
+  onAdd={userId => addEditor({ wikiId, editorId: userId })}
+  onRemove={userId => removeEditor({ wikiId, editorId: userId })}
+/>
+
+// Permission gate for edit pages
+<PermissionGuard canAccess={canEdit} backHref={backUrl} backLabel='wiki' resource='wiki'>
+  <EditForm />
+</PermissionGuard>
+```
+
+### Bulk Selection
+
+```tsx
+import { useBulkSelection } from 'lazyconvex/react'
+
+const { clear, handleBulkDelete, selected, toggleSelect, toggleSelectAll } = useBulkSelection({
+  bulkRm, items: wikis?.page ?? [], label: 'wiki page(s)', orgId: org._id
+})
+```
+
+## Imports Reference
+
+| Module | Key Exports |
+|--------|------------|
+| `lazyconvex/server` | `setup`, `ownedTable`, `orgTable`, `baseTable`, `orgChildTable`, `orgTables`, `uploadTables`, `orgCascade`, `canEdit`, `getOrgMember`, `getOrgRole`, `requireOrgMember`, `requireOrgRole`, `handleConvexError`, `getErrorCode`, `getErrorMessage`, `makeOrg`, `makeFileUpload`, `makeTestAuth` |
+| `lazyconvex/react` | `useForm`, `useFormMutation`, `useOptimisticMutation`, `useUpload`, `useBulkSelection`, `useOnlineStatus`, `OrgProvider`, `useOrg`, `useOrgQuery`, `useOrgMutation`, `useMyOrgs`, `useActiveOrg`, `canEditResource`, `setActiveOrgCookieClient`, `buildMeta` |
+| `lazyconvex/components` | `Form`, `EditorsSection`, `PermissionGuard`, `OfflineIndicator`, `OrgAvatar`, `RoleBadge`, `AutoSaveIndicator`, `ConflictDialog`, `FileFieldImpl`, `fields` |
+| `lazyconvex/schema` | `child`, `cvFile`, `cvFiles`, `orgSchema` |
+| `lazyconvex/zod` | `pickValues`, `defaultValues`, `enumToOptions`, `unwrapZod`, `isStringType`, `isNumberType`, `isBooleanType`, `isArrayType`, `isDateType`, `isOptionalField`, `cvMetaOf`, `cvFileKindOf` |
+| `lazyconvex/next` | `getActiveOrg`, `setActiveOrgCookie`, `clearActiveOrgCookie`, `getToken`, `isAuthenticated`, `makeImageRoute` |
+| `lazyconvex/retry` | `withRetry`, `fetchWithRetry` |
+
+## Known Limitations
+
+### Where Clauses Use Runtime Filtering
+
+Most `where` filtering (`$gt`, `$gte`, `$lt`, `$lte`, `$between`, `or`) uses Convex `.filter()` — runtime scan, not index lookup. Exception: `{ own: true }` uses the `by_user` index automatically. Fine for hundreds of docs; for high-volume tables (thousands+), use indexed queries via `pubIndexed`/`authIndexed`.
+
+**Runtime warnings**: `all()` and `count()` log `crud:large_result` / `crud:large_count` when results exceed 1,000 docs. `search()` logs `crud:search_fallback` when falling back to full-text scan. Check server logs.
+
+### Generic Type Boundaries
+
+CRUD factories use `as never` casts at the Zod ↔ Convex type boundary. Localized inside factory internals — consumer code is fully typesafe with no casts needed.
+
+### Bulk Operations
+
+`bulkUpdate` and `bulkRm` cap at 100 items per call. No built-in rate limiting on call frequency — add application-level throttling if needed for public-facing endpoints.