cvx-kit 0.0.1

package/src/triggers.ts

@@ -0,0 +1,90 @@
+import {
+	Triggers,
+	type Change,
+	type Trigger,
+} from 'convex-helpers/server/triggers'
+import type {
+	GenericDataModel,
+	TableNamesInDataModel,
+} from 'convex/server'
+
+export { Triggers }
+export type { Change, Trigger }
+
+/**
+ * One application-wide mutation interceptor registry. Pass it to
+ * createAuthFunctions({ triggers }) so every authMutation/roleMutation/
+ * systemMutation runs writes through it — trigger enforcement becomes
+ * structural, not a convention.
+ */
+export function createTriggers<
+	DataModel extends GenericDataModel,
+>(): Triggers<DataModel> {
+	return new Triggers<DataModel>()
+}
+
+/**
+ * Marks tables as append-only evidence tables: inserts pass, every update or
+ * delete throws. The ontology pattern for votes/history/audit-style tables.
+ */
+export function appendOnly<DataModel extends GenericDataModel>(
+	triggers: Triggers<DataModel>,
+	...tables: readonly TableNamesInDataModel<DataModel>[]
+) {
+	for (const table of tables) {
+		triggers.register(table, async (_ctx, change) => {
+			if (change.operation !== 'insert') {
+				throw new Error(`${table} is append-only`)
+			}
+		})
+	}
+}
+
+/** Forbids hard deletes on the given tables (soft-delete discipline). */
+export function noDelete<DataModel extends GenericDataModel>(
+	triggers: Triggers<DataModel>,
+	...tables: readonly TableNamesInDataModel<DataModel>[]
+) {
+	for (const table of tables) {
+		triggers.register(table, async (_ctx, change) => {
+			if (change.operation === 'delete') {
+				throw new Error(`${table} rows cannot be deleted`)
+			}
+		})
+	}
+}
+
+/**
+ * Maintains zod-table's opinionated lifecycle timestamps: createdAt and
+ * updatedAt on insert, updatedAt on every update. archivedAt stays under
+ * application control. Register once per table; writes made through the
+ * auth constructors keep these fields correct automatically.
+ */
+export function timestamps<DataModel extends GenericDataModel>(
+	triggers: Triggers<DataModel>,
+	...tables: readonly TableNamesInDataModel<DataModel>[]
+) {
+	for (const table of tables) {
+		triggers.register(table, async (ctx, change) => {
+			if (change.operation === 'delete') return
+			const now = Date.now()
+			if (change.operation === 'insert') {
+				const document = change.newDoc as { createdAt?: number }
+				if (document.createdAt === undefined) {
+					await ctx.innerDb.patch(change.id, {
+						createdAt: now,
+						updatedAt: now,
+					} as never)
+				}
+				return
+			}
+			const previous = change.oldDoc as { updatedAt?: number }
+			const current = change.newDoc as { updatedAt?: number }
+			// A write that already moved updatedAt (including our own patch)
+			// is left alone — this is the recursion guard.
+			if (current.updatedAt === previous.updatedAt) {
+				await ctx.innerDb.patch(change.id, { updatedAt: now } as never)
+			}
+		})
+	}
+}

package/src/zod-table.ts

@@ -0,0 +1,197 @@
+import {
+	type ConvexValidatorFromZod,
+	zid,
+	zodToConvex,
+} from 'convex-helpers/server/zod4'
+import { defineTable, type TableDefinition } from 'convex/server'
+import type { GenericId } from 'convex/values'
+import { z } from 'zod'
+
+type Shape = Record<string, z.ZodType>
+type ShapeKey<Fields extends Shape> = Extract<keyof Fields, string>
+
+/**
+ * Opinionated lifecycle timestamps — every table has them, server-owned,
+ * always excluded from insert/command boundaries. Maintained by the
+ * `timestamps` trigger helper (see cvx-kit/triggers).
+ */
+const timestampShape = {
+	createdAt: z.number().optional(),
+	updatedAt: z.number().optional(),
+	archivedAt: z.number().optional(),
+} satisfies Shape
+
+type TimestampShape = typeof timestampShape
+
+export const TIMESTAMP_FIELDS = [
+	'createdAt',
+	'updatedAt',
+	'archivedAt',
+] as const
+
+export type TableBoundaryOptions<
+	Fields extends Shape,
+	ServerFields extends readonly ShapeKey<Fields>[],
+	CommandFields extends readonly ShapeKey<Fields>[],
+	PublicFields extends readonly ShapeKey<Fields & TimestampShape>[],
+> = {
+	serverFields?: ServerFields
+	commandFields?: CommandFields
+	publicFields?: PublicFields
+}
+
+/** Defines one table and derives its storage, document, write, and DTO boundaries. */
+export function zodTable<
+	Table extends string,
+	Fields extends Shape,
+	const ServerFields extends readonly ShapeKey<Fields>[] = readonly [],
+	const CommandFields extends readonly ShapeKey<Fields>[] = readonly [],
+	const PublicFields extends readonly ShapeKey<
+		Fields & TimestampShape
+	>[] = readonly [],
+>(
+	tableName: Table,
+	fields: (id: typeof zid) => Fields,
+	options: TableBoundaryOptions<
+		Fields,
+		ServerFields,
+		CommandFields,
+		PublicFields
+	> = {},
+) {
+	const shape = { ...fields(zid), ...timestampShape } as Fields &
+		TimestampShape
+	const storage = z.object(shape).strict()
+	const schema = storage.extend({
+		_id: zid(tableName),
+		_creationTime: z.number(),
+	})
+	const insertSchema = z
+		.object(
+			omitShape(shape, [
+				...TIMESTAMP_FIELDS,
+				...(options.serverFields ?? ([] as never)),
+			] as never),
+		)
+		.strict() as z.ZodObject<
+		Omit<Fields, ServerFields[number] | (typeof TIMESTAMP_FIELDS)[number]>
+	>
+	const updateSchema = insertSchema.partial()
+	const commandInput = z
+		.object(pickShape(shape, options.commandFields ?? ([] as never)))
+		.strict()
+	const publicDto = z
+		.object(pickShape(shape, options.publicFields ?? ([] as never)))
+		.strict()
+	const toPublicDto = (row: z.input<typeof storage>) =>
+		publicDto.parse(
+			Object.fromEntries(
+				Object.keys(publicDto.shape).map((key) => [
+					key,
+					(row as Record<string, unknown>)[key],
+				]),
+			),
+		)
+
+	type InsertSchema = typeof insertSchema
+	type UpdateSchema = typeof updateSchema
+	type InsertMask = z.util.Mask<keyof InsertSchema['shape']>
+	type UpdateMask = z.util.Mask<keyof UpdateSchema['shape']>
+
+	function insert(): InsertSchema
+	function insert<OmitMask extends InsertMask>(
+		omit: OmitMask,
+	): ZodObjectOmit<InsertSchema, OmitMask>
+	function insert(omit?: InsertMask) {
+		return omit ? insertSchema.omit(omit as never) : insertSchema
+	}
+
+	function update(): UpdateSchema
+	function update<OmitMask extends UpdateMask>(
+		omit: OmitMask,
+	): ZodObjectOmit<UpdateSchema, OmitMask>
+	function update(omit?: UpdateMask) {
+		return omit ? updateSchema.omit(omit as never) : updateSchema
+	}
+
+	return {
+		tableName,
+		schema,
+		storage,
+		insertSchema,
+		updateSchema,
+		commandInput,
+		publicDto,
+		toPublicDto,
+		table: defineTable(zodToConvex(storage)) as TableDefinition<
+			ConvexValidatorFromZod<typeof storage, 'required'>
+		>,
+		insert,
+		update,
+		tools: {
+			insert: commandInput,
+			update: z
+				.object({ data: commandInput.partial(), id: zid(tableName) })
+				.strict(),
+			id: z.object({ id: zid(tableName) }).strict(),
+		},
+	}
+}
+
+/** Preserves discriminated-union storage while retaining the same table owner. */
+export function zodVariantTable<Table extends string, Schema extends z.ZodType>(
+	tableName: Table,
+	storage: Schema,
+) {
+	return {
+		tableName,
+		storage,
+		insertSchema: storage,
+		table: defineTable(zodToConvex(storage)),
+	}
+}
+
+/**
+ * A zid that presents as a plain string in generated JSON schemas so
+ * LLM-tool inputs stay primitive, while keeping the Id type at compile time.
+ */
+export function jsonSafeZid<Table extends string>(tableName: Table) {
+	return z
+		.string()
+		.describe(
+			`Convex document id for table "${tableName}"`,
+		) as unknown as z.ZodType<GenericId<Table>, string>
+}
+
+type ZodObjectOmit<
+	Schema extends z.ZodObject<any, any>,
+	OmitMask extends z.util.Mask<keyof Schema['shape']>,
+> =
+	Schema extends z.ZodObject<infer ObjectShape, infer Config>
+		? z.ZodObject<
+				z.util.Flatten<
+					Omit<ObjectShape, Extract<keyof ObjectShape, keyof OmitMask>>
+				>,
+				Config
+			>
+		: never
+
+function pickShape<
+	Fields extends Shape,
+	const Keys extends readonly ShapeKey<Fields>[],
+>(fields: Fields, keys: Keys) {
+	return Object.fromEntries(keys.map((key) => [key, fields[key]])) as Pick<
+		Fields,
+		Keys[number]
+	>
+}
+
+function omitShape<
+	Fields extends Shape,
+	const Keys extends readonly ShapeKey<Fields>[],
+>(fields: Fields, keys: Keys) {
+	const omitted = new Set<string>(keys)
+	return Object.fromEntries(
+		Object.entries(fields).filter(([key]) => !omitted.has(key)),
+	) as Omit<Fields, Keys[number]>
+}