cvx-kit 0.0.1 → 0.0.2

package/docs/triggers.md

@@ -0,0 +1,70 @@
+# `cvx-kit/triggers` — one application-wide mutation interceptor registry
+
+A single `Triggers` registry (from convex-helpers) is created once per app and
+handed to `createAuthFunctions`. From then on, every `authMutation`,
+`roleMutation`, and `systemMutation` runs its writes through
+`triggers.wrapDB(ctx)` — trigger enforcement is **structural, not a
+convention**. A handler cannot skip a trigger because it never sees an
+unwrapped `ctx.db`.
+
+## Setup
+
+```ts
+// convex/triggers.ts — the single registry
+import { appendOnly, createTriggers, noDelete, timestamps } from 'cvx-kit/triggers'
+import type { DataModel } from './_generated/dataModel'
+
+export const triggers = createTriggers<DataModel>()
+
+// Server-owned lifecycle timestamps (see zod-table.md)
+timestamps(triggers, 'documents', 'projects', 'members')
+
+// Evidence tables: inserts only — updates/deletes throw and roll back
+appendOnly(triggers, 'votes', 'history')
+
+// Soft-delete discipline: hard deletes throw
+noDelete(triggers, 'documents')
+
+// Domain triggers register on the same instance
+triggers.register('documents', async (ctx, change) => {
+  if (change.operation === 'insert') { /* denormalize, validate, cascade */ }
+})
+```
+
+```ts
+// convex/functions.ts
+createAuthFunctions<DataModel>({ ..., triggers })
+```
+
+## The built-in helpers
+
+- **`timestamps(triggers, ...tables)`** — maintains zod-table's opinionated
+  fields: sets `createdAt` + `updatedAt` on insert, moves `updatedAt` on every
+  update. `archivedAt` stays under application control. Contains its own
+  recursion guard (a write that already moved `updatedAt` — including the
+  trigger's own patch — is left alone). Register once per table.
+- **`appendOnly(triggers, ...tables)`** — inserts pass; any update or delete
+  throws, which **rolls back the whole transaction**. The pattern for
+  votes/history/audit-style evidence tables.
+- **`noDelete(triggers, ...tables)`** — forbids hard deletes only; updates
+  pass. Pair with `archivedAt` for soft deletion.
+
+`Triggers`, `Change`, and `Trigger` are re-exported for custom registrations.
+
+## Footguns
+
+1. **Anything outside the kit constructors bypasses every trigger.** Raw
+   `mutation`/`internalMutation` from `_generated/server`, and `ctx.db` inside
+   `convex-test`'s `t.run(...)`, are unwrapped. Never build a mutation outside
+   your `functions.ts`, and expect test-side `t.run` writes to be trigger-free
+   (useful for seeding, dangerous for assertions about trigger behavior).
+2. **Wrapper spread order matters** if you compose ctx manually:
+   `{ ...wrapDB(ctx), ...otherStuff }` — `wrapDB` returns a full ctx, so
+   spreading it *after* anything that carries `db` restores the raw database.
+   The kit's constructors already order this correctly
+   (`{ ...wrapDB(ctx), include, ...authBundle }`).
+3. **A throwing trigger aborts the transaction.** That is the point for
+   `appendOnly`/`noDelete`, but remember it when writing custom triggers —
+   validation triggers should throw; best-effort denormalization should not.
+4. **Triggers run per write, in registration order.** Keep them small; heavy
+   work belongs in a scheduled function, not in a trigger.

package/docs/zod-table.md

@@ -0,0 +1,150 @@
+# `cvx-kit/zod-table` — one zod shape per entity, masked into every boundary
+
+The core idea: an entity's shape is declared **once** as a zod object, and every
+boundary that shape crosses — storage, insert, update, command input, public
+DTO, LLM tool input — is a *derived mask* of that single declaration. There is
+no second source of truth to drift.
+
+```ts
+import { z } from 'zod'
+import { zodTable } from 'cvx-kit/zod-table'
+
+export const documents = zodTable(
+  'documents',
+  (id) => ({
+    title: z.string(),
+    ownerId: id('users'),        // `id` is convex-helpers' zid — typed Id<'users'>
+    secretNote: z.string(),
+    reviewState: z.enum(['draft', 'published']),
+  }),
+  {
+    serverFields: ['reviewState'],       // excluded from inserts — server assigns it
+    commandFields: ['title'],            // the ONLY fields a command may carry
+    publicFields: ['title', 'ownerId'],  // the DTO allowlist — everything else is redacted
+  },
+)
+```
+
+## What you get back
+
+| Property | What it is | Where you use it |
+|---|---|---|
+| `table` | `defineTable(...)` from the storage shape | `convex/schema.ts` |
+| `storage` | zod object of the raw row (no `_id`/`_creationTime`) | validating rows |
+| `schema` | `storage` + `_id` + `_creationTime` | full-document validation |
+| `insertSchema` | storage minus timestamps minus `serverFields` | mutation args |
+| `updateSchema` | `insertSchema.partial()` | patch mutation args |
+| `commandInput` | strict pick of `commandFields` | command protocol inputs |
+| `publicDto` | strict pick of `publicFields` | query return validators |
+| `toPublicDto(row)` | projects **and re-parses** a row into the DTO | query handlers |
+| `insert(omit?)` / `update(omit?)` | schema with per-callsite field omission | specialized mutations |
+| `tools.insert` / `tools.update` / `tools.id` | ready-made LLM tool input schemas | agent tool definitions |
+| `tableName` | the literal table name | indexes, triggers registration |
+
+## Redaction is runtime, not just types
+
+`toPublicDto` does not merely `pick` at the type level — it re-parses the
+projected object through the strict `publicDto` schema. A field that leaks into
+the projection throws instead of shipping to the client. Use it on **every**
+row a public query returns:
+
+```ts
+export const get = authQuery({
+  args: { id: zid('documents') },
+  returns: documents.publicDto,
+  handler: async (ctx, { id }) => {
+    const row = await ctx.db.get(id)
+    if (!row) throw new KitError({ code: 'NOT_FOUND' })
+    return documents.toPublicDto(row) // secretNote can never leak
+  },
+})
+```
+
+## Opinionated timestamps
+
+Every `zodTable` bakes in three optional, **server-owned** fields:
+
+- `createdAt` — set once on insert
+- `updatedAt` — moved on every update
+- `archivedAt` — soft-delete marker, under application control
+
+They are always excluded from `insertSchema`, `updateSchema`, and
+`commandInput` — a client or command can never write them. They are *not* in
+`publicFields` by default; list them explicitly when a DTO needs them
+(`publicFields: ['title', 'createdAt']`).
+
+They maintain themselves only if you register the `timestamps` trigger once
+per table (see `triggers.md`). Without the trigger they stay `undefined`.
+
+Prefer `createdAt` over `_creationTime` in DTOs so the whole lifecycle
+vocabulary is yours; `_creationTime` remains available for index ordering.
+
+## Field masks — who sees what
+
+Think of the options as three independent allowlists over the same shape:
+
+- `serverFields` — *the server assigns these.* Excluded from `insertSchema`
+  and `updateSchema`. Example: `reviewState`, denormalized counters.
+- `commandFields` — *a command may say these.* The command protocol's input
+  is exactly this pick, strict. Everything else must be derived by the handler.
+- `publicFields` — *a client may see these.* The DTO is exactly this pick;
+  may include timestamp fields.
+
+All derived objects are `.strict()` — unknown keys are rejected, in both
+directions.
+
+## `zodVariantTable` — discriminated unions
+
+For tables whose rows are a discriminated union (events, polymorphic
+resources), `zodTable`'s object-shape model doesn't apply. `zodVariantTable`
+keeps the same "one owner per table" convention while accepting any zod type
+as storage:
+
+```ts
+const events = zodVariantTable('events', z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('created'), by: zid('users') }),
+  z.object({ kind: z.literal('archived'), reason: z.string() }),
+]))
+// events.table → defineTable, events.insertSchema → the union itself
+```
+
+Note: variant tables do not get the timestamp fields or boundary masks — the
+union is the boundary.
+
+## `jsonSafeZid` — Ids in LLM tool schemas
+
+JSON-schema generators turn `zid('users')` into an opaque custom type that
+confuses LLM tool calling. `jsonSafeZid('users')` presents as a plain
+described string in the generated JSON schema while keeping `Id<'users'>` at
+the type level:
+
+```ts
+const assignInput = z.object({
+  documentId: jsonSafeZid('documents'), // LLM sees: string, "Convex document id for table \"documents\""
+})
+```
+
+## Wiring into `schema.ts`
+
+```ts
+// convex/schema.ts
+import { defineSchema } from 'convex/server'
+import { documents } from './tables/documents'
+
+export default defineSchema({
+  documents: documents.table
+    .index('by_owner', ['ownerId'])
+    .index('by_owner_archived', ['ownerId', 'archivedAt']),
+})
+```
+
+Indexes are chained on `.table` exactly like a hand-written `defineTable`.
+
+## Rules of thumb
+
+1. One `zodTable` per entity, in its own module, exported by name.
+2. Never define an inline `defineTable` or a second zod object for the same
+   entity — masks only.
+3. Every public query returns `publicDto`-shaped data via `toPublicDto`.
+4. Every command input is `commandInput` (or a documented composition of it).
+5. Timestamps are trigger-maintained; handlers never write them.

package/package.json

@@ -1,13 +1,15 @@
 {
 	"name": "cvx-kit",
-	"version": "0.0.1",
+	"version": "0.0.2",
 	"description": "Reusable Convex application kit: foundation kernels, approvals component, zod table boundaries, WorkOS-backed auth function constructors, and audited command protocol.",
 	"type": "module",
 	"license": "MIT",
 	"sideEffects": false,
 	"files": [
 		"dist",
-		"src"
+		"src",
+		"!src/docs",
+		"docs"
 	],
 	"exports": {
 		"./package.json": "./package.json",
@@ -67,7 +69,8 @@
 		"build": "vp pack",
 		"typecheck": "tsc --noEmit",
 		"test": "vp test run",
-		"prepublishOnly": "bun run typecheck && bun run test && bun run build",
+		"docs:sync": "rm -f docs/*.md && cp src/docs/*.md docs/",
+		"prepublishOnly": "bun run typecheck && bun run test && bun run build && bun run docs:sync",
 		"build:codegen": "convex codegen --component-dir ./src/components/foundation && convex codegen --component-dir ./src/components/approvals && vp pack",
 		"release": "npm version patch && git push --follow-tags",
 		"release:minor": "npm version minor && git push --follow-tags"