cvx-kit 0.1.3 → 0.1.4

package/docs/auth.md

@@ -12,30 +12,52 @@ host. The kit provides the structure; the app provides the policy.
 // convex/functions.ts (the single place constructors are built)
 import { createAuthFunctions, defaultRoleMap } from 'cvx-kit/auth'
 import {
-  action, internalAction, internalMutation, internalQuery, mutation, query,
+	action,
+	internalAction,
+	internalMutation,
+	internalQuery,
+	mutation,
+	query,
 } from './_generated/server'
 import type { DataModel } from './_generated/dataModel'
 import { triggers } from './triggers'
 import { authKit } from './auth'
 
 export const {
-  authQuery, authMutation, authAction,
-  roleQuery, roleMutation, roleAction,
-  adminQuery, adminMutation, adminAction,
-  systemQuery, systemMutation, systemAction,
-  include, authenticatedUser,
+	authQuery,
+	authMutation,
+	authAction,
+	roleQuery,
+	roleMutation,
+	roleAction,
+	adminQuery,
+	adminMutation,
+	adminAction,
+	systemQuery,
+	systemMutation,
+	systemAction,
+	include,
+	authenticatedUser,
 } = createAuthFunctions<DataModel>({
-  query, mutation, action, internalQuery, internalMutation, internalAction,
-  getAuthUser: (ctx) => authKit.getAuthUser(ctx),
-  mapRole: defaultRoleMap,          // or your own vocabulary (see below)
-  adminRoles: ['admin'],
-  triggers,                          // every mutation write runs through wrapDB
-  verifyMembership: async ({ userId, organizationId }) => {
-    const memberships = await authKit.workos.userManagement
-      .listOrganizationMemberships({ organizationId, userId, statuses: ['active'] })
-    const m = memberships.data.find((c) => c.userId === userId)
-    return m ? { organizationId: m.organizationId, roleSlug: m.role.slug } : null
-  },
+	query,
+	mutation,
+	action,
+	internalQuery,
+	internalMutation,
+	internalAction,
+	getAuthUser: (ctx) => authKit.getAuthUser(ctx),
+	mapRole: defaultRoleMap, // or your own vocabulary (see below)
+	adminRoles: ['admin'],
+	triggers, // every mutation write runs through wrapDB
+	verifyMembership: async ({ userId, organizationId }) => {
+		const memberships = await authKit.workos.userManagement.listOrganizationMemberships({
+			organizationId,
+			userId,
+			statuses: ['active'],
+		})
+		const m = memberships.data.find((c) => c.userId === userId)
+		return m ? { organizationId: m.organizationId, roleSlug: m.role.slug } : null
+	},
 })
 ```
 
@@ -44,14 +66,14 @@ imports from `_generated/server` appear **only** in this file.
 
 ## The constructor families
 
-| Constructor | Visibility | Auth | Extra |
-|---|---|---|---|
-| `authQuery` / `authMutation` / `authAction` | public | any authenticated org member | actions live-verify membership |
-| `roleQuery(...roles)` / `roleMutation(...)` / `roleAction(...)` | public | listed roles only | factory — call with your roles |
-| `adminQuery` / `adminMutation` / `adminAction` | public | `config.adminRoles` | pre-built `role*(...adminRoles)` |
-| `systemQuery` | internal | none (trusted caller) | include-equipped, RLS-unwrapped |
-| `systemMutation` | internal | none (trusted caller) | still trigger-wrapped |
-| `systemAction` | internal | none | plain internal action |
+| Constructor                                                     | Visibility | Auth                         | Extra                            |
+| --------------------------------------------------------------- | ---------- | ---------------------------- | -------------------------------- |
+| `authQuery` / `authMutation` / `authAction`                     | public     | any authenticated org member | actions live-verify membership   |
+| `roleQuery(...roles)` / `roleMutation(...)` / `roleAction(...)` | public     | listed roles only            | factory — call with your roles   |
+| `adminQuery` / `adminMutation` / `adminAction`                  | public     | `config.adminRoles`          | pre-built `role*(...adminRoles)` |
+| `systemQuery`                                                   | internal   | none (trusted caller)        | include-equipped, RLS-unwrapped  |
+| `systemMutation`                                                | internal   | none (trusted caller)        | still trigger-wrapped            |
+| `systemAction`                                                  | internal   | none                         | plain internal action            |
 
 All are `zCustom*` constructors from convex-helpers, so `args` and `returns`
 take zod schemas directly and compose with `zodTable` masks.
@@ -164,14 +186,16 @@ rejects limits outside `1..maxRows` (default 100, configurable via
 
 ```ts
 export const list = authQuery({
-  args: { ownerId: zid('users').optional(), limit: z.number() },
-  returns: z.array(documents.publicDto),
-  handler: (ctx, args) =>
-    ctx.include(ctx.db.query('documents'))
-      .when(args.ownerId, (q, ownerId) =>
-        q.withIndex('by_owner', (ix) => ix.eq('ownerId', ownerId)))
-      .otherwise((q) => q.withIndex('by_owner'))
-      .execute(args.limit, (rows) => rows.map(documents.toPublicDto)),
+	args: { ownerId: zid('users').optional(), limit: z.number() },
+	returns: z.array(documents.publicDto),
+	handler: (ctx, args) =>
+		ctx
+			.include(ctx.db.query('documents'))
+			.when(args.ownerId, (q, ownerId) =>
+				q.withIndex('by_owner', (ix) => ix.eq('ownerId', ownerId)),
+			)
+			.otherwise((q) => q.withIndex('by_owner'))
+			.execute(args.limit, (rows) => rows.map(documents.toPublicDto)),
 })
 ```
 

package/docs/commands.md

@@ -25,16 +25,13 @@ import { Foundation } from 'cvx-kit/components/foundation'
 import { components } from './_generated/api'
 import { writeAuditEntry } from './audit'
 
-export const { Command, Query, observability } = new Foundation(
-  components.foundation,
-  {
-    observability: {
-      enabled: () => process.env.COMMAND_OBSERVABILITY_ENABLED === 'true',
-      classifyError: (error) => classify(error), // → { outcome: 'denied' | 'failed', errorCode }
-      writeAudit: (ctx, entry) => writeAuditEntry(ctx, entry),
-    },
-  },
-)
+export const { Command, Query, observability } = new Foundation(components.foundation, {
+	observability: {
+		enabled: () => process.env.COMMAND_OBSERVABILITY_ENABLED === 'true',
+		classifyError: (error) => classify(error), // → { outcome: 'denied' | 'failed', errorCode }
+		writeAudit: (ctx, entry) => writeAuditEntry(ctx, entry),
+	},
+})
 ```
 
 Host code consumes the Foundation **only through this facade** — never deep
@@ -57,27 +54,27 @@ import type { MutationCtx } from '../../_generated/server'
 const typed = Command.withContext<MutationCtx>()
 
 const operations = {
-  'documents.rename': typed.operation({
-    command: documents.commandInput.extend({ id: zid('documents') }),
-    result: z.object({ ok: z.literal(true) }).strict(),
-    classification: 'business',
-    audit: ({ command }) => ({
-      operation: 'documents.rename',
-      actorId: command.actorId,
-      aggregate: { type: 'document', id: command.id },
-      metadata: { title: command.title },
-    }),
-  }),
+	'documents.rename': typed.operation({
+		command: documents.commandInput.extend({ id: zid('documents') }),
+		result: z.object({ ok: z.literal(true) }).strict(),
+		classification: 'business',
+		audit: ({ command }) => ({
+			operation: 'documents.rename',
+			actorId: command.actorId,
+			aggregate: { type: 'document', id: command.id },
+			metadata: { title: command.title },
+		}),
+	}),
 } as const
 
 const commands = new Command<MutationCtx, typeof operations>(operations)
 
 export const executeRename = commands.exec({
-  operation: 'documents.rename',
-  handler: async (ctx, command) => {
-    await ctx.db.patch(command.id, { title: command.title })
-    return { ok: true }
-  },
+	operation: 'documents.rename',
+	handler: async (ctx, command) => {
+		await ctx.db.patch(command.id, { title: command.title })
+		return { ok: true }
+	},
 })
 ```
 
@@ -119,7 +116,7 @@ The public API layer then wraps the executor in an `authMutation` and passes
 8. **Complete**: await the closure returned by `prepare`, including when audit
    returns null. A failure propagates inside the observation boundary.
 9. **Emit the observation**: `{ operation, classification, outcome,
-   errorCode?, durationMs }` — completed, denied, or failed per
+errorCode?, durationMs }` — completed, denied, or failed per
    `classifyError`.
 
 ### Guards and permissions
@@ -214,32 +211,35 @@ command and result boundary intentionally remains unknown.
 ```ts
 const typed = Command.withContext<Ctx>()
 const operations = {
-  rename: typed.operation({
-    command: z.object({ title: z.string().transform(value => value.length) }),
-    result: z.object({ ok: z.boolean() }),
-    classification: 'business',
-    aggregates: ['document'],
-    guard: (ctx, command) => requireTitleLength(ctx, command.title), // number
-    middleware: [async ({ command, next }) => {
-      const result = await next() // { ok: boolean }, before validation
-      logLength(command.title)
-      return result
-    }],
-    audit: ({ command, result }, ctx) => ({
-      operation: 'rename', actorId: ctx.actorId,
-      aggregate: { type: 'document', id: String(command.title) },
-      metadata: { ok: result.ok },
-    }),
-  }),
+	rename: typed.operation({
+		command: z.object({ title: z.string().transform((value) => value.length) }),
+		result: z.object({ ok: z.boolean() }),
+		classification: 'business',
+		aggregates: ['document'],
+		guard: (ctx, command) => requireTitleLength(ctx, command.title), // number
+		middleware: [
+			async ({ command, next }) => {
+				const result = await next() // { ok: boolean }, before validation
+				logLength(command.title)
+				return result
+			},
+		],
+		audit: ({ command, result }, ctx) => ({
+			operation: 'rename',
+			actorId: ctx.actorId,
+			aggregate: { type: 'document', id: String(command.title) },
+			metadata: { ok: result.ok },
+		}),
+	}),
 }
-const middleware = typed.registryMiddleware(operations, async input => {
-  if (input.operation === 'rename') {
-    input.command.title.toFixed() // discriminator retains schema correlation
-  }
-  return input.next()
+const middleware = typed.registryMiddleware(operations, async (input) => {
+	if (input.operation === 'rename') {
+		input.command.title.toFixed() // discriminator retains schema correlation
+	}
+	return input.next()
 })
 const commands = new Command<Ctx, typeof operations>(operations, {
-  middleware: [middleware],
+	middleware: [middleware],
 })
 ```
 
@@ -320,9 +320,9 @@ rolled back; these transaction guarantees concern Convex mutation writes.
 
 ```ts
 export const executeAny = commands.exec({
-  dispatcher: z.object({ kind: z.enum(OPERATION_KINDS) /* from constants.ts */ }),
-  select: (input) => `documents.${input.kind}` as const,
-  handler,
+	dispatcher: z.object({ kind: z.enum(OPERATION_KINDS) /* from constants.ts */ }),
+	select: (input) => `documents.${input.kind}` as const,
+	handler,
 })
 ```
 

package/docs/conventions.md

@@ -99,16 +99,16 @@ another file's function to shorten an import.
 
 ### Root files
 
-| File | Contains | Never contains |
-|---|---|---|
-| `convex.config.ts` | `defineApp()`, one `app.use(...)` per component, `defineApp({ env })` declarations, `export default app` | anything else |
-| `schema.ts` | `defineSchema(domainTables)` | table definitions, validators |
-| `functions.ts` | the single `createAuthFunctions<DataModel>()` call and its exported constructors | handlers, business policy beyond the injected config |
-| `triggers.ts` | `createTriggers()`, `timestamps`/`appendOnly`/`noDelete` registrations, calls to per-entity `register<Entity>Triggers` | trigger *logic* for a specific entity (that lives in the entity) |
-| `foundation.ts` | the single `new Foundation(...)`, destructured exports | command definitions |
-| `<component>.ts` | `new <Client>(components.<name>)` + minimal admin plumbing | workflow/business definitions |
-| `http.ts` | routes: verify signature → parse payload → delegate to a domain function | webhook business logic |
-| `crons.ts` | `cronJobs()` declarations targeting `internal.domain.<entity>...` | handler logic |
+| File               | Contains                                                                                                               | Never contains                                                   |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `convex.config.ts` | `defineApp()`, one `app.use(...)` per component, `defineApp({ env })` declarations, `export default app`               | anything else                                                    |
+| `schema.ts`        | `defineSchema(domainTables)`                                                                                           | table definitions, validators                                    |
+| `functions.ts`     | the single `createAuthFunctions<DataModel>()` call and its exported constructors                                       | handlers, business policy beyond the injected config             |
+| `triggers.ts`      | `createTriggers()`, `timestamps`/`appendOnly`/`noDelete` registrations, calls to per-entity `register<Entity>Triggers` | trigger _logic_ for a specific entity (that lives in the entity) |
+| `foundation.ts`    | the single `new Foundation(...)`, destructured exports                                                                 | command definitions                                              |
+| `<component>.ts`   | `new <Client>(components.<name>)` + minimal admin plumbing                                                             | workflow/business definitions                                    |
+| `http.ts`          | routes: verify signature → parse payload → delegate to a domain function                                               | webhook business logic                                           |
+| `crons.ts`         | `cronJobs()` declarations targeting `internal.domain.<entity>...`                                                      | handler logic                                                    |
 
 ### `api/<entity>.ts` — the adapter file
 
@@ -176,7 +176,7 @@ compile. Numeric limits and durations the entity owns also live here.
 ### `domain/<entity>/commands.ts` — every state change
 
 1. The frozen operation registry: `Command.operation({ command, result,
-   classification, audit })` per operation, keys `'<entity>.<verb>'`.
+classification, audit })` per operation, keys `'<entity>.<verb>'`.
 2. One `new Command<Ctx, typeof operations>(operations)`.
 3. Exported executors: `export const execute<Verb><Entity> = commands.exec(...)`.
 4. Private handler helpers at the bottom.
@@ -197,7 +197,7 @@ Handlers call rules; rules never call handlers.
 
 ### `domain/<entity>/shared.ts` — entity-private helpers
 
-Code shared by two or more files *of this entity*. If a second entity needs
+Code shared by two or more files _of this entity_. If a second entity needs
 it, it moves to `domain/shared/` — never a sibling import.
 
 ### `domain/<entity>/actions.ts` — external side effects
@@ -234,25 +234,25 @@ ground: code with one consumer moves back to that consumer.
 
 ## 3. Naming grammar
 
-| Thing | Convention | Example shape |
-|---|---|---|
-| Entity directory | plural camelCase, matches table name | `domain/<entities>/` |
-| Table | plural camelCase | `<entities>` |
-| Fields | camelCase; foreign keys `<other>Id`; timestamps only via the kit | `ownerId`, `archivedAt` |
-| Index | `by_<field>` / `by_<field>_and_<field>`, declaration order, nested paths flattened with `_` | `by_ownerId_and_state_status` |
-| Command operation | `<entity>.<verb>` lowercase dotted; must match `/^[A-Za-z][A-Za-z0-9_.-]{0,159}$/` | `<entities>.approve` |
-| Error code | `UPPER_SNAKE`, matching `/^[A-Z][A-Z0-9_]{0,95}$/`, defined in one owner | `INVALID_REQUEST_BOUNDARY` |
-| Vocabulary tuple | `UPPER_SNAKE_CASE` `as const`; derived type PascalCase singular | `<ENTITY>_STATES` / `<Entity>State` |
-| Domain executor | `execute<Verb><Entity>` | `executeApprove<Entity>` |
-| Rule predicate | `can<Verb>` / `is<Condition>` | `canApprove`, `isTransitionLegal` |
-| Trigger registration | `register<Entity>Triggers(triggers)` | exported from the entity, called in root `triggers.ts` |
-| Internal-callback file | `<purpose>_functions.ts`, sibling of `<purpose>.ts` | `approval_functions.ts` |
-| zodTable export | camelCase plural, same as table | `export const <entities> = zodTable(...)` |
-| DTO schema | `<entity><Purpose>Dto` | `<entity>SummaryDto` |
-| Zod schema value | camelCase noun | `commandInput`, `publicDto` |
-| Type | PascalCase; no `I`/`T` prefixes | `<Entity>State` |
-| Test file | `<subject>.test.ts` in `__tests__/` | `commands.test.ts` |
-| Public function path | `api/<entity>:<fn>` — clients never call a root path | — |
+| Thing                  | Convention                                                                                  | Example shape                                          |
+| ---------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| Entity directory       | plural camelCase, matches table name                                                        | `domain/<entities>/`                                   |
+| Table                  | plural camelCase                                                                            | `<entities>`                                           |
+| Fields                 | camelCase; foreign keys `<other>Id`; timestamps only via the kit                            | `ownerId`, `archivedAt`                                |
+| Index                  | `by_<field>` / `by_<field>_and_<field>`, declaration order, nested paths flattened with `_` | `by_ownerId_and_state_status`                          |
+| Command operation      | `<entity>.<verb>` lowercase dotted; must match `/^[A-Za-z][A-Za-z0-9_.-]{0,159}$/`          | `<entities>.approve`                                   |
+| Error code             | `UPPER_SNAKE`, matching `/^[A-Z][A-Z0-9_]{0,95}$/`, defined in one owner                    | `INVALID_REQUEST_BOUNDARY`                             |
+| Vocabulary tuple       | `UPPER_SNAKE_CASE` `as const`; derived type PascalCase singular                             | `<ENTITY>_STATES` / `<Entity>State`                    |
+| Domain executor        | `execute<Verb><Entity>`                                                                     | `executeApprove<Entity>`                               |
+| Rule predicate         | `can<Verb>` / `is<Condition>`                                                               | `canApprove`, `isTransitionLegal`                      |
+| Trigger registration   | `register<Entity>Triggers(triggers)`                                                        | exported from the entity, called in root `triggers.ts` |
+| Internal-callback file | `<purpose>_functions.ts`, sibling of `<purpose>.ts`                                         | `approval_functions.ts`                                |
+| zodTable export        | camelCase plural, same as table                                                             | `export const <entities> = zodTable(...)`              |
+| DTO schema             | `<entity><Purpose>Dto`                                                                      | `<entity>SummaryDto`                                   |
+| Zod schema value       | camelCase noun                                                                              | `commandInput`, `publicDto`                            |
+| Type                   | PascalCase; no `I`/`T` prefixes                                                             | `<Entity>State`                                        |
+| Test file              | `<subject>.test.ts` in `__tests__/`                                                         | `commands.test.ts`                                     |
+| Public function path   | `api/<entity>:<fn>` — clients never call a root path                                        | —                                                      |
 
 The two regexes are enforced at runtime: observability silently drops events
 whose operation/classification/errorCode don't match. The rest is enforced by
@@ -264,14 +264,14 @@ the architecture tests — a naming rule without a test is a wish.
 
 Allowed, per zone (anything not listed is forbidden):
 
-| From | May import |
-|---|---|
-| `api/<entity>.ts` | `functions.ts`, `domain/<entity>/*`, `domain/shared/*`, zod |
-| `domain/<entity>/*` | `functions.ts`, `foundation.ts`, component facades, `domain/shared/*`, own directory, generated `internal`/`api` (references only), kit modules |
-| `domain/shared/*` | kit modules, vendor SDKs (this is the ONLY home for vendor clients) |
-| root facades | kit modules, `components` from generated api |
-| `functions.ts` | `_generated/server` (the only file allowed to) |
-| `components/<name>/**` | its own directory + npm deps only — no host imports, no `process.env` |
+| From                   | May import                                                                                                                                      |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api/<entity>.ts`      | `functions.ts`, `domain/<entity>/*`, `domain/shared/*`, zod                                                                                     |
+| `domain/<entity>/*`    | `functions.ts`, `foundation.ts`, component facades, `domain/shared/*`, own directory, generated `internal`/`api` (references only), kit modules |
+| `domain/shared/*`      | kit modules, vendor SDKs (this is the ONLY home for vendor clients)                                                                             |
+| root facades           | kit modules, `components` from generated api                                                                                                    |
+| `functions.ts`         | `_generated/server` (the only file allowed to)                                                                                                  |
+| `components/<name>/**` | its own directory + npm deps only — no host imports, no `process.env`                                                                           |
 
 Forbidden everywhere: sibling-entity imports, `api/` from `domain/`,
 component internals (anything below a component's client facade),
@@ -286,6 +286,6 @@ component internals (anything below a component's client facade),
 - Zod objects that cross a boundary are `.strict()` — always.
 - `Object.freeze` for registries and long-lived configuration objects.
 - Comments state constraints the code can't (`// Optional only for rows
-  created before <epoch>.`) — never narration of the next line.
+created before <epoch>.`) — never narration of the next line.
 - One entity concept per file; when a file serves two purposes, split it
   along the anatomy in §2.

package/docs/crud.md

@@ -36,11 +36,11 @@ export const create = authMutation({
 
 ## What gets generated
 
-| Operation | Input | Effect | Audit aggregate id |
-|---|---|---|---|
-| `<table>.create` | `commandInput` (strict) + `enrich` stamps | insert | the new row id |
-| `<table>.update` | `{ id, data: commandInput.partial() }` (strict) | patch | the row id |
-| `<table>.archive` | `{ id }` | sets `archivedAt` (soft delete ONLY) | the row id |
+| Operation         | Input                                           | Effect                               | Audit aggregate id |
+| ----------------- | ----------------------------------------------- | ------------------------------------ | ------------------ |
+| `<table>.create`  | `commandInput` (strict) + `enrich` stamps       | insert                               | the new row id     |
+| `<table>.update`  | `{ id, data: commandInput.partial() }` (strict) | patch                                | the row id         |
+| `<table>.archive` | `{ id }`                                        | sets `archivedAt` (soft delete ONLY) | the row id         |
 
 No hard-delete operation is generated — kit doctrine (`noDelete` +
 `archivedAt`).