cvx-kit 0.0.2 → 0.0.4

package/src/components/foundation/modules/command/command.ts

@@ -1,154 +0,0 @@
-export type Parseable<Output> = Readonly<{ parse: (value: unknown) => Output }>
-
-export type CommandRegistry = Readonly<Record<string, CommandDefinition>>
-
-export type CommandInput<
-	Registry extends CommandRegistry,
-	Key extends Operation<Registry>,
-> = Parsed<Registry[Key]['command']>
-
-export type CommandResult<
-	Registry extends CommandRegistry,
-	Key extends Operation<Registry>,
-> = Parsed<Registry[Key]['result']>
-
-export type CommandExecution<
-	Context,
-	Registry extends CommandRegistry,
-	Key extends Operation<Registry>,
-> = Readonly<{
-	context: Context
-	operation: Key
-	definition: Registry[Key]
-	command: CommandInput<Registry, Key>
-	parseResult: (value: unknown) => CommandResult<Registry, Key>
-	run: () => Promise<CommandResult<Registry, Key>>
-}>
-
-type CommandDefinition = Readonly<{
-	command: Parseable<unknown>
-	result: Parseable<unknown>
-}>
-
-type Operation<Registry extends CommandRegistry> = Extract<
-	keyof Registry,
-	string
->
-type Parsed<Schema> = Schema extends Parseable<infer Output> ? Output : never
-type MaybePromise<Value> = Value | Promise<Value>
-type Execute<Context, Registry extends CommandRegistry> = <
-	Key extends Operation<Registry>,
->(
-	execution: CommandExecution<Context, Registry, Key>,
-) => Promise<CommandResult<Registry, Key>>
-
-type FixedExecutor<
-	Context,
-	Registry extends CommandRegistry,
-	Key extends Operation<Registry>,
-> = Readonly<{
-	operation: Key
-	handler: (
-		context: Context,
-		command: CommandInput<Registry, Key>,
-	) => MaybePromise<CommandResult<Registry, Key>>
-}>
-
-type DynamicExecutor<
-	Context,
-	Registry extends CommandRegistry,
-	Dispatcher,
-	Key extends Operation<Registry>,
-> = Readonly<{
-	dispatcher: Parseable<Dispatcher>
-	select: (dispatcher: Dispatcher) => Key
-	handler: (
-		context: Context,
-		command: CommandInput<Registry, Key>,
-	) => MaybePromise<CommandResult<Registry, Key>>
-}>
-
-class CommandConfigurationError extends Error {
-	readonly code = 'COMMAND_OPERATION_NOT_CONFIGURED'
-	readonly name = 'CommandConfigurationError'
-
-	constructor() {
-		super('The selected command operation is not configured')
-	}
-}
-
-/** Generic command kernel. Host policy is injected by the owning domain. */
-export class Command<Context, const Registry extends CommandRegistry> {
-	readonly #operations: Registry
-	readonly #execute: Execute<Context, Registry>
-
-	constructor(configuration: {
-		readonly operations: Registry
-		readonly execute: Execute<Context, Registry>
-	}) {
-		this.#operations = configuration.operations
-		this.#execute = configuration.execute
-	}
-
-	exec<const Key extends Operation<Registry>>(
-		executor: FixedExecutor<Context, Registry, Key>,
-	): (
-		context: Context,
-		command: CommandInput<Registry, Key>,
-	) => Promise<CommandResult<Registry, Key>>
-	exec<Dispatcher, const Key extends Operation<Registry>>(
-		executor: DynamicExecutor<Context, Registry, Dispatcher, Key>,
-	): (
-		context: Context,
-		command: Dispatcher,
-	) => Promise<CommandResult<Registry, Key>>
-	exec(
-		executor:
-			| FixedExecutor<Context, Registry, Operation<Registry>>
-			| DynamicExecutor<Context, Registry, unknown, Operation<Registry>>,
-	) {
-		return async (context: Context, value: unknown) => {
-			const selected =
-				'operation' in executor
-					? { operation: executor.operation, value }
-					: (() => {
-							const dispatcher = executor.dispatcher.parse(value)
-							return {
-								operation: executor.select(dispatcher),
-								value: dispatcher,
-							}
-						})()
-			if (
-				!Object.prototype.hasOwnProperty.call(
-					this.#operations,
-					selected.operation,
-				)
-			) {
-				throw new CommandConfigurationError()
-			}
-			const operation = selected.operation as Operation<Registry>
-			const definition = this.#operations[operation]
-			const command = definition.command.parse(selected.value) as CommandInput<
-				Registry,
-				Operation<Registry>
-			>
-			const parseResult = (result: unknown) =>
-				definition.result.parse(result) as CommandResult<
-					Registry,
-					Operation<Registry>
-				>
-			const handler = executor.handler as (
-				context: Context,
-				command: CommandInput<Registry, Operation<Registry>>,
-			) => MaybePromise<CommandResult<Registry, Operation<Registry>>>
-			return this.#execute({
-				context,
-				operation,
-				definition,
-				command,
-				parseResult,
-				run: async () => parseResult(await handler(context, command)),
-			})
-		}
-	}
-}

package/src/components/foundation/modules/observability/__tests__/observability.test.ts

@@ -1,79 +0,0 @@
-import { describe, expect, it, vi } from 'vite-plus/test'
-
-import { Observability } from '../observability'
-
-describe('Foundation Observability', () => {
-	it('emits bounded semantic metadata without payloads', async () => {
-		const emit = vi.fn()
-		const observability = new Observability({
-			enabled: true,
-			clock: tickingClock(),
-			classifyError: () => ({
-				outcome: 'failed',
-				errorCode: 'UNEXPECTED_ERROR',
-			}),
-			emit,
-		})
-
-		await expect(
-			observability.observe(
-				{ operation: 'assignments.claim', classification: 'writer' },
-				() => 'claimed',
-			),
-		).resolves.toBe('claimed')
-		expect(emit).toHaveBeenCalledWith({
-			operation: 'assignments.claim',
-			classification: 'writer',
-			outcome: 'completed',
-			durationMs: 5,
-		})
-	})
-
-	it('classifies denial and preserves the original failure', async () => {
-		const emit = vi.fn()
-		const original = new Error('sensitive reason')
-		const observability = new Observability({
-			enabled: true,
-			clock: tickingClock(),
-			classifyError: () => ({ outcome: 'denied', errorCode: 'FORBIDDEN' }),
-			emit,
-		})
-
-		await expect(
-			observability.observe(
-				{ operation: 'assignments.assign', classification: 'admin' },
-				() => {
-					throw original
-				},
-			),
-		).rejects.toBe(original)
-		expect(JSON.stringify(emit.mock.calls)).not.toContain('sensitive reason')
-	})
-
-	it('drops invalid semantic fields and contains emitter failures', async () => {
-		const emit = vi.fn(() => {
-			throw new Error('telemetry unavailable')
-		})
-		const observability = new Observability({
-			enabled: true,
-			classifyError: () => ({
-				outcome: 'failed',
-				errorCode: 'UNEXPECTED_ERROR',
-			}),
-			emit,
-		})
-
-		await expect(
-			observability.observe(
-				{ operation: 'contains secret whitespace', classification: 'writer' },
-				() => 'unchanged',
-			),
-		).resolves.toBe('unchanged')
-		expect(emit).not.toHaveBeenCalled()
-	})
-})
-
-function tickingClock(): () => number {
-	let now = 10
-	return () => (now += 5)
-}

package/src/components/foundation/modules/observability/observability.ts

@@ -1,95 +0,0 @@
-export type CommandObservation = Readonly<{
-	operation: string
-	classification: string
-	outcome: 'completed' | 'denied' | 'failed'
-	errorCode?: string
-	durationMs: number
-}>
-
-export type ObservabilityOptions = Readonly<{
-	enabled?: boolean | (() => boolean)
-	classifyError: (error: unknown) => Readonly<{
-		outcome: 'denied' | 'failed'
-		errorCode: string
-	}>
-	emit?: (observation: CommandObservation) => void
-	clock?: () => number
-}>
-
-const identifier = /^[A-Za-z][A-Za-z0-9_.-]{0,159}$/
-const errorCode = /^[A-Z][A-Z0-9_]{0,95}$/
-
-/** Payload-free command telemetry that cannot change command behavior. */
-export class Observability {
-	readonly #options: ObservabilityOptions
-
-	constructor(options: ObservabilityOptions) {
-		this.#options = options
-	}
-
-	async observe<Result>(
-		activation: Readonly<{ operation: string; classification: string }>,
-		execute: () => Result | Promise<Result>,
-	): Promise<Result> {
-		const started = this.#now()
-		try {
-			const result = await execute()
-			this.#emit({
-				...activation,
-				outcome: 'completed',
-				durationMs: this.#duration(started),
-			})
-			return result
-		} catch (error) {
-			try {
-				this.#emit({
-					...activation,
-					...this.#options.classifyError(error),
-					durationMs: this.#duration(started),
-				})
-			} catch {
-				// Preserve the original command failure when telemetry fails.
-			}
-			throw error
-		}
-	}
-
-	#emit(observation: CommandObservation): void {
-		try {
-			const enabled =
-				typeof this.#options.enabled === 'function'
-					? this.#options.enabled()
-					: this.#options.enabled
-			if (
-				enabled !== true ||
-				!identifier.test(observation.operation) ||
-				!identifier.test(observation.classification) ||
-				(observation.errorCode !== undefined &&
-					!errorCode.test(observation.errorCode))
-			) {
-				return
-			}
-			if (this.#options.emit) {
-				this.#options.emit(Object.freeze(observation))
-				return
-			}
-			console.info(
-				JSON.stringify({ event: 'command.execution', ...observation }),
-			)
-		} catch {
-			// Observability is intentionally behaviorally inert.
-		}
-	}
-
-	#now(): number {
-		try {
-			return this.#options.clock?.() ?? Date.now()
-		} catch {
-			return Date.now()
-		}
-	}
-
-	#duration(started: number): number {
-		return Math.max(0, Math.min(600_000, this.#now() - started))
-	}
-}

package/src/components/foundation/modules/query/__tests__/query.test.ts

@@ -1,25 +0,0 @@
-import { describe, expect, it } from 'vite-plus/test'
-
-import { Query } from '../query'
-
-describe('Foundation Query', () => {
-	it('runs injected policy before its handler', async () => {
-		const order: string[] = []
-		const query = new Query({
-			defaults: { classification: 'authenticated' as const },
-			execute: async (execution) => {
-				order.push(`policy:${execution.metadata.classification}`)
-				return execution.run()
-			},
-		})
-		const execute = query.exec({
-			handler: (_context: unknown, id: string) => {
-				order.push('handler')
-				return id
-			},
-		})
-
-		await expect(execute({}, 'assignment-1')).resolves.toBe('assignment-1')
-		expect(order).toEqual(['policy:authenticated', 'handler'])
-	})
-})

package/src/components/foundation/modules/query/query.ts

@@ -1,47 +0,0 @@
-export type QueryExecution<Context, Metadata, Result> = Readonly<{
-	context: Context
-	metadata: Metadata
-	run: () => Promise<Result>
-}>
-
-type MaybePromise<Value> = Value | Promise<Value>
-
-/** Generic query kernel. Authorization remains an injected host policy. */
-export class Query<Context, Defaults extends object> {
-	readonly #defaults: Defaults
-	readonly #execute: <Metadata extends object, Result>(
-		execution: QueryExecution<Context, Defaults & Metadata, Result>,
-	) => Promise<Result>
-
-	constructor(configuration: {
-		readonly defaults: Defaults
-		readonly execute: <Metadata extends object, Result>(
-			execution: QueryExecution<Context, Defaults & Metadata, Result>,
-		) => Promise<Result>
-	}) {
-		this.#defaults = configuration.defaults
-		this.#execute = configuration.execute
-	}
-
-	exec<
-		Arguments extends readonly unknown[],
-		Result,
-		Metadata extends object = object,
-	>(executor: {
-		readonly metadata?: Metadata
-		readonly handler: (
-			context: Context,
-			...args: Arguments
-		) => MaybePromise<Result>
-	}): (context: Context, ...args: Arguments) => Promise<Result> {
-		return (context, ...args) =>
-			this.#execute({
-				context,
-				metadata: {
-					...this.#defaults,
-					...(executor.metadata ?? ({} as Metadata)),
-				},
-				run: async () => executor.handler(context, ...args),
-			})
-	}
-}

package/src/components/foundation/result.ts

@@ -1,77 +0,0 @@
-import type { TransactionMetrics } from 'convex/server'
-
-export type TransactionMetricsContext = Readonly<{
-	meta: Readonly<{
-		getTransactionMetrics: () => Promise<TransactionMetrics>
-	}>
-}>
-
-export type Result<Value, Failure> =
-	| Readonly<{ ok: true; value: Value }>
-	| Readonly<{ ok: false; error: Failure }>
-
-export type ResultBoundary<Failure> = Readonly<{
-	ok: <Value>(value: Value) => Result<Value, Failure>
-	handledError: <Value = never>(failure: Failure) => Result<Value, Failure>
-	dataOf: (error: unknown) => Failure | undefined
-}>
-
-const metricNames = [
-	'bytesRead',
-	'bytesWritten',
-	'databaseQueries',
-	'documentsRead',
-	'documentsWritten',
-	'functionsScheduled',
-	'scheduledFunctionArgsBytes',
-] as const satisfies readonly (keyof TransactionMetrics)[]
-
-const effectMetricNames = [
-	'bytesWritten',
-	'documentsWritten',
-	'functionsScheduled',
-	'scheduledFunctionArgsBytes',
-] as const satisfies readonly (keyof TransactionMetrics)[]
-
-/** Return handled failures only before effects; otherwise rethrow for rollback. */
-export async function executeResultBoundary<Value, Failure>(
-	ctx: TransactionMetricsContext,
-	operation: () => Promise<Value>,
-	boundary: ResultBoundary<Failure>,
-): Promise<Result<Value, Failure>> {
-	try {
-		return boundary.ok(await operation())
-	} catch (error) {
-		const handled = boundary.dataOf(error)
-		if (handled === undefined) throw error
-		try {
-			if (hasEffects(await ctx.meta.getTransactionMetrics())) throw error
-		} catch {
-			throw error
-		}
-		return boundary.handledError(handled)
-	}
-}
-
-export function projectResult<Value, Failure>(
-	result: Result<Value, Failure>,
-	projectFailure: (failure: Failure) => never,
-): Value {
-	return result.ok ? result.value : projectFailure(result.error)
-}
-
-function hasEffects(metrics: TransactionMetrics): boolean {
-	for (const name of metricNames) {
-		const metric = metrics[name]
-		if (
-			!metric ||
-			!Number.isFinite(metric.used) ||
-			metric.used < 0 ||
-			!Number.isFinite(metric.remaining) ||
-			metric.remaining < 0
-		) {
-			throw new Error('Unreadable transaction metrics')
-		}
-	}
-	return effectMetricNames.some((name) => metrics[name].used > 0)
-}

package/src/components/foundation/schema.ts

@@ -1,4 +0,0 @@
-import { defineSchema } from 'convex/server'
-
-/** Foundation is a capability-free in-process kernel and owns no business data. */
-export default defineSchema({})

package/src/components/foundation/telemetry.ts

@@ -1,23 +0,0 @@
-type SemanticValue = string | number | boolean
-
-const semanticToken = /^[A-Za-z][A-Za-z0-9_.-]{0,159}$/
-
-/** Emit bounded semantic fields only; free-form payloads and identifiers drop. */
-export function emitSemanticEvent(
-	event: string,
-	fields: Readonly<Record<string, SemanticValue | undefined>> = {},
-): void {
-	try {
-		if (!semanticToken.test(event)) return
-		const safe: Record<string, SemanticValue> = { event }
-		for (const [key, value] of Object.entries(fields)) {
-			if (!semanticToken.test(key) || value === undefined) continue
-			if (typeof value === 'string' && !semanticToken.test(value)) continue
-			if (typeof value === 'number' && !Number.isFinite(value)) continue
-			safe[key] = value
-		}
-		console.info(JSON.stringify(safe))
-	} catch {
-		// Telemetry must never change command behavior.
-	}
-}

package/src/errors.ts

@@ -1,25 +0,0 @@
-/** Structured application error carried across Convex function boundaries. */
-export class KitError extends Error {
-	readonly code: string
-
-	constructor(input: { code: string; message?: string }) {
-		super(input.message ?? input.code)
-		this.name = 'KitError'
-		this.code = input.code
-	}
-}
-
-/**
- * Injection seam for host error policy. Hosts with their own error taxonomy
- * (e.g. an App.errors singleton) adapt it to this shape; everyone else uses
- * the default factory below.
- */
-export type ErrorFactory = {
-	throw(input: { code: string; message?: string }): never
-}
-
-export const defaultErrors: ErrorFactory = {
-	throw(input) {
-		throw new KitError(input)
-	},
-}

package/src/index.ts

@@ -1,41 +0,0 @@
-export {
-	defaultErrors,
-	KitError,
-	type ErrorFactory,
-} from './errors'
-export {
-	jsonSafeZid,
-	TIMESTAMP_FIELDS,
-	zodTable,
-	zodVariantTable,
-	type TableBoundaryOptions,
-} from './zod-table'
-export {
-	createAuthFunctions,
-	createInclude,
-	defaultRoleMap,
-	type Actor,
-	type AuthBundle,
-	type AuthFunctionsConfig,
-	type DefaultRole,
-	type Include,
-	type IncludedQuery,
-} from './auth'
-export {
-	appendOnly,
-	createTriggers,
-	noDelete,
-	timestamps,
-	Triggers,
-	type Change,
-	type Trigger,
-} from './triggers'
-export {
-	Foundation,
-	type ApplicationCommand,
-	type AuditedOperation,
-	type AuditedRegistry,
-	type AuditEntryInput,
-	type AuditWriter,
-	type FoundationOptions,
-} from './components/foundation/client'

package/src/triggers.ts

@@ -1,90 +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`)
-			}
-		})
-	}
-}
-
-/**
- * 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)
-			}
-		})
-	}
-}