cvx-kit 0.0.3 → 0.0.4

package/src/tenancy.ts

@@ -1,110 +0,0 @@
-import {
-	wrapDatabaseReader,
-	wrapDatabaseWriter,
-	type RLSConfig,
-	type Rules,
-} from 'convex-helpers/server/rowLevelSecurity'
-import type {
-	GenericDataModel,
-	TableNamesInDataModel,
-} from 'convex/server'
-import { defaultErrors, type ErrorFactory } from './errors'
-
-export { wrapDatabaseReader, wrapDatabaseWriter }
-export type { RLSConfig, Rules }
-
-/** The server-owned tenancy field stamped on every tenant table row. */
-export const TENANT_FIELD = 'tenant' as const
-
-type TenantRow = { [TENANT_FIELD]?: unknown }
-
-/**
- * Deny-oriented row-level security rules generated mechanically from a table
- * registry: read/insert/modify pass only when the row's tenant matches.
- * Registering a table here is the entire onboarding — there is no second
- * per-table step to forget.
- */
-export function createTenantRules<DataModel extends GenericDataModel>(
-	tenant: string,
-	tables: readonly TableNamesInDataModel<DataModel>[],
-): Rules<unknown, DataModel> {
-	const owned = async (_ctx: unknown, doc: TenantRow) =>
-		doc[TENANT_FIELD] === tenant
-	return Object.fromEntries(
-		tables.map((table) => [
-			table,
-			{ read: owned, insert: owned, modify: owned },
-		]),
-	) as unknown as Rules<unknown, DataModel>
-}
-
-/**
- * AND-composes rule sets: a row passes an operation only when every rule set
- * that defines a rule for it passes. Lets tenant isolation and role-level
- * rules coexist on the same wrapped database.
- */
-export function composeRules<Ctx, DataModel extends GenericDataModel>(
-	...sets: readonly Rules<Ctx, DataModel>[]
-): Rules<Ctx, DataModel> {
-	const tables = new Set(sets.flatMap((set) => Object.keys(set)))
-	const composed: Record<string, Record<string, unknown>> = {}
-	for (const table of tables) {
-		const operations: Record<string, unknown> = {}
-		for (const operation of ['read', 'insert', 'modify'] as const) {
-			const rules = sets
-				.map((set) => (set as Record<string, Record<string, unknown>>)[table])
-				.map((tableRules) => tableRules?.[operation])
-				.filter((rule): rule is (ctx: Ctx, doc: never) => Promise<boolean> =>
-					typeof rule === 'function',
-				)
-			if (rules.length === 0) continue
-			operations[operation] = async (ctx: Ctx, doc: never) => {
-				for (const rule of rules) {
-					if (!(await rule(ctx, doc))) return false
-				}
-				return true
-			}
-		}
-		composed[table] = operations
-	}
-	return composed as Rules<Ctx, DataModel>
-}
-
-/**
- * Loads a client-referenced document and verifies tenant ownership without
- * disclosing existence: a missing row and a foreign row fail identically
- * with REFERENCE_NOT_FOUND. Use for every id argument a client supplies.
- */
-export async function requireTenantReference<
-	Document extends { [TENANT_FIELD]?: unknown },
->(
-	tenant: string,
-	load: () => Promise<Document | null>,
-	errors: ErrorFactory = defaultErrors,
-): Promise<Document> {
-	const document = await load()
-	if (!document || document[TENANT_FIELD] !== tenant) {
-		return errors.throw({
-			code: 'REFERENCE_NOT_FOUND',
-			message: 'The referenced row is unavailable',
-		})
-	}
-	return document
-}
-
-/** Asserts a loaded document belongs to the tenant; use on internal paths. */
-export function assertTenantOwned<
-	Document extends { [TENANT_FIELD]?: unknown },
->(
-	tenant: string,
-	document: Document,
-	errors: ErrorFactory = defaultErrors,
-): Document {
-	if (document[TENANT_FIELD] !== tenant) {
-		return errors.throw({
-			code: 'CROSS_TENANT_REFERENCE',
-			message: 'The document belongs to another tenant',
-		})
-	}
-	return document
-}

package/src/triggers.ts

@@ -1,124 +0,0 @@
-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`)
-			}
-		})
-	}
-}
-
-/**
- * Post-image tenant invariant for tenantTable rows. Row-level security
- * authorizes a modification against the PRE-image, so ownership must also be
- * enforced against the post-image: inserts must carry a tenant, and updates
- * may never reassign it. Register for every tenant table (same registry that
- * drives createTenantRules).
- */
-export function tenantOwnership<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') {
-				const document = change.newDoc as { tenant?: unknown }
-				if (
-					typeof document.tenant !== 'string' ||
-					document.tenant.length === 0
-				) {
-					throw new Error(`${table} rows require a tenant`)
-				}
-				return
-			}
-			if (change.operation === 'update') {
-				const previous = change.oldDoc as { tenant?: unknown }
-				const current = change.newDoc as { tenant?: unknown }
-				if (previous.tenant !== current.tenant) {
-					throw new Error(`${table} tenant ownership cannot be reassigned`)
-				}
-			}
-		})
-	}
-}
-
-/**
- * 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

@@ -1,283 +0,0 @@
-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(),
-		},
-	}
-}
-
-const tenantShape = {
-	tenant: z.string().min(1),
-} satisfies Shape
-
-type TenantShape = typeof tenantShape
-
-/**
- * A zodTable whose rows are tenant-owned: injects the server-owned `tenant`
- * field (the tenancy boundary — see cvx-kit/tenancy). Like timestamps, it is
- * excluded from insert/update/command boundaries; handlers stamp it from
- * ctx.tenant, row-level security matches on it, and the tenantOwnership
- * trigger forbids reassigning it. Expose it via publicFields only when a DTO
- * genuinely needs it.
- */
-export function tenantTable<
-	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 & TenantShape & TimestampShape
-	>[] = readonly [],
->(
-	tableName: Table,
-	fields: (id: typeof zid) => Fields,
-	options: TableBoundaryOptions<
-		Fields & TenantShape,
-		readonly (ServerFields[number] | 'tenant')[],
-		CommandFields,
-		PublicFields
-	> = {},
-) {
-	return zodTable(
-		tableName,
-		(id) => ({ ...fields(id), ...tenantShape }),
-		{
-			...options,
-			serverFields: [
-				...((options.serverFields ?? []) as readonly (
-					| ServerFields[number]
-					| 'tenant'
-				)[]),
-				'tenant',
-			] as never,
-		} as never,
-	) as ReturnType<
-		typeof zodTable<
-			Table,
-			Fields & TenantShape,
-			readonly (ServerFields[number] | 'tenant')[],
-			CommandFields,
-			PublicFields
-		>
-	>
-}
-
-/**
- * Merges per-module table maps into the application schema map, rejecting
- * duplicate table names across modules — the module-registry combinator for
- * domain/table.ts: `defineSchema(createModule(catalogTables, salesTables))`.
- */
-export function createModule<
-	const Maps extends readonly Record<string, TableDefinition<any>>[],
->(...maps: Maps): UnionToIntersection<Maps[number]> {
-	const combined: Record<string, TableDefinition<any>> = {}
-	for (const map of maps) {
-		for (const [tableName, definition] of Object.entries(map)) {
-			if (tableName in combined) {
-				throw new Error(
-					`Table "${tableName}" is declared by more than one module`,
-				)
-			}
-			combined[tableName] = definition
-		}
-	}
-	return combined as UnionToIntersection<Maps[number]>
-}
-
-type UnionToIntersection<Union> = (
-	Union extends unknown
-		? (member: Union) => void
-		: never
-) extends (member: infer Intersection) => void
-	? Intersection
-	: never
-
-/** 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]>
-}