cvx-kit 0.0.3 → 0.0.4

package/src/components/foundation/_generated/api.ts

@@ -1,62 +0,0 @@
-/* eslint-disable */
-/**
- * Generated `api` utility.
- *
- * THIS CODE IS AUTOMATICALLY GENERATED.
- *
- * To regenerate, run `npx convex dev`.
- * @module
- */
-
-import type * as client from "../client.js";
-import type * as functions from "../functions.js";
-import type * as modules_command_command from "../modules/command/command.js";
-import type * as modules_observability_observability from "../modules/observability/observability.js";
-import type * as modules_query_query from "../modules/query/query.js";
-import type * as result from "../result.js";
-import type * as telemetry from "../telemetry.js";
-
-import type {
-  ApiFromModules,
-  FilterApi,
-  FunctionReference,
-} from "convex/server";
-import { anyApi, componentsGeneric } from "convex/server";
-
-const fullApi: ApiFromModules<{
-  client: typeof client;
-  functions: typeof functions;
-  "modules/command/command": typeof modules_command_command;
-  "modules/observability/observability": typeof modules_observability_observability;
-  "modules/query/query": typeof modules_query_query;
-  result: typeof result;
-  telemetry: typeof telemetry;
-}> = anyApi as any;
-
-/**
- * A utility for referencing Convex functions in your app's public API.
- *
- * Usage:
- * ```js
- * const myFunctionReference = api.myModule.myFunction;
- * ```
- */
-export const api: FilterApi<
-  typeof fullApi,
-  FunctionReference<any, "public">
-> = anyApi as any;
-
-/**
- * A utility for referencing Convex functions in your app's internal API.
- *
- * Usage:
- * ```js
- * const myFunctionReference = internal.myModule.myFunction;
- * ```
- */
-export const internal: FilterApi<
-  typeof fullApi,
-  FunctionReference<any, "internal">
-> = anyApi as any;
-
-export const components = componentsGeneric() as unknown as {};

package/src/components/foundation/_generated/component.ts

@@ -1,29 +0,0 @@
-/* eslint-disable */
-/**
- * Generated `ComponentApi` utility.
- *
- * THIS CODE IS AUTOMATICALLY GENERATED.
- *
- * To regenerate, run `npx convex dev`.
- * @module
- */
-
-import type { FunctionReference } from "convex/server";
-
-/**
- * A utility for referencing a Convex component's exposed API.
- *
- * Useful when expecting a parameter like `components.myComponent`.
- * Usage:
- * ```ts
- * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
- *   return ctx.runQuery(component.someFile.someQuery, { ...args });
- * }
- * ```
- */
-export type ComponentApi<Name extends string | undefined = string | undefined> =
-  {
-    functions: {
-      status: FunctionReference<"query", "internal", {}, "ready", Name>;
-    };
-  };

package/src/components/foundation/_generated/dataModel.ts

@@ -1,60 +0,0 @@
-/* eslint-disable */
-/**
- * Generated data model types.
- *
- * THIS CODE IS AUTOMATICALLY GENERATED.
- *
- * To regenerate, run `npx convex dev`.
- * @module
- */
-
-import type {
-  DataModelFromSchemaDefinition,
-  DocumentByName,
-  TableNamesInDataModel,
-  SystemTableNames,
-} from "convex/server";
-import type { GenericId } from "convex/values";
-import schema from "../schema.js";
-
-/**
- * The names of all of your Convex tables.
- */
-export type TableNames = TableNamesInDataModel<DataModel>;
-
-/**
- * The type of a document stored in Convex.
- *
- * @typeParam TableName - A string literal type of the table name (like "users").
- */
-export type Doc<TableName extends TableNames> = DocumentByName<
-  DataModel,
-  TableName
->;
-
-/**
- * An identifier for a document in Convex.
- *
- * Convex documents are uniquely identified by their `Id`, which is accessible
- * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
- *
- * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
- *
- * IDs are just strings at runtime, but this type can be used to distinguish them from other
- * strings when type checking.
- *
- * @typeParam TableName - A string literal type of the table name (like "users").
- */
-export type Id<TableName extends TableNames | SystemTableNames> =
-  GenericId<TableName>;
-
-/**
- * A type describing your Convex data model.
- *
- * This type includes information about what tables you have, the type of
- * documents stored in those tables, and the indexes defined on them.
- *
- * This type is used to parameterize methods like `queryGeneric` and
- * `mutationGeneric` to make them type-safe.
- */
-export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

package/src/components/foundation/_generated/server.ts

@@ -1,156 +0,0 @@
-/* eslint-disable */
-/**
- * Generated utilities for implementing server-side Convex query and mutation functions.
- *
- * THIS CODE IS AUTOMATICALLY GENERATED.
- *
- * To regenerate, run `npx convex dev`.
- * @module
- */
-
-import type {
-  ActionBuilder,
-  HttpActionBuilder,
-  MutationBuilder,
-  QueryBuilder,
-  GenericActionCtx,
-  GenericMutationCtx,
-  GenericQueryCtx,
-  GenericDatabaseReader,
-  GenericDatabaseWriter,
-} from "convex/server";
-import {
-  actionGeneric,
-  httpActionGeneric,
-  queryGeneric,
-  mutationGeneric,
-  internalActionGeneric,
-  internalMutationGeneric,
-  internalQueryGeneric,
-} from "convex/server";
-import type { DataModel } from "./dataModel.js";
-
-/**
- * Define a query in this Convex app's public API.
- *
- * This function will be allowed to read your Convex database and will be accessible from the client.
- *
- * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
- * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
- */
-export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
-
-/**
- * Define a query that is only accessible from other Convex functions (but not from the client).
- *
- * This function will be allowed to read from your Convex database. It will not be accessible from the client.
- *
- * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
- * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
- */
-export const internalQuery: QueryBuilder<DataModel, "internal"> =
-  internalQueryGeneric;
-
-/**
- * Define a mutation in this Convex app's public API.
- *
- * This function will be allowed to modify your Convex database and will be accessible from the client.
- *
- * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
- * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
- */
-export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
-
-/**
- * Define a mutation that is only accessible from other Convex functions (but not from the client).
- *
- * This function will be allowed to modify your Convex database. It will not be accessible from the client.
- *
- * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
- * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
- */
-export const internalMutation: MutationBuilder<DataModel, "internal"> =
-  internalMutationGeneric;
-
-/**
- * Define an action in this Convex app's public API.
- *
- * An action is a function which can execute any JavaScript code, including non-deterministic
- * code and code with side-effects, like calling third-party services.
- * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
- * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
- *
- * @param func - The action. It receives an {@link ActionCtx} as its first argument.
- * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
- */
-export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
-
-/**
- * Define an action that is only accessible from other Convex functions (but not from the client).
- *
- * @param func - The function. It receives an {@link ActionCtx} as its first argument.
- * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
- */
-export const internalAction: ActionBuilder<DataModel, "internal"> =
-  internalActionGeneric;
-
-/**
- * Define an HTTP action.
- *
- * The wrapped function will be used to respond to HTTP requests received
- * by a Convex deployment if the requests matches the path and method where
- * this action is routed. Be sure to route your httpAction in `convex/http.js`.
- *
- * @param func - The function. It receives an {@link ActionCtx} as its first argument
- * and a Fetch API `Request` object as its second.
- * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
- */
-export const httpAction: HttpActionBuilder = httpActionGeneric;
-
-/**
- * A set of services for use within Convex query functions.
- *
- * The query context is passed as the first argument to any Convex query
- * function run on the server.
- *
- * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
- */
-export type QueryCtx = GenericQueryCtx<DataModel>;
-
-/**
- * A set of services for use within Convex mutation functions.
- *
- * The mutation context is passed as the first argument to any Convex mutation
- * function run on the server.
- *
- * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
- */
-export type MutationCtx = GenericMutationCtx<DataModel>;
-
-/**
- * A set of services for use within Convex action functions.
- *
- * The action context is passed as the first argument to any Convex action
- * function run on the server.
- */
-export type ActionCtx = GenericActionCtx<DataModel>;
-
-/**
- * An interface to read from the database within Convex query functions.
- *
- * The two entry points are {@link DatabaseReader.get}, which fetches a single
- * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
- * building a query.
- */
-export type DatabaseReader = GenericDatabaseReader<DataModel>;
-
-/**
- * An interface to read from and write to the database within Convex mutation
- * functions.
- *
- * Convex guarantees that all writes within a single mutation are
- * executed atomically, so you never have to worry about partial writes leaving
- * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
- * for the guarantees Convex provides your functions.
- */
-export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/components/foundation/client.ts

@@ -1,301 +0,0 @@
-import {
-	Command as CommandKernelClass,
-	type CommandExecution,
-	type CommandInput,
-	type CommandRegistry,
-	type CommandResult,
-} from './modules/command/command'
-import {
-	Observability,
-	type ObservabilityOptions,
-} from './modules/observability/observability'
-import { Query } from './modules/query/query'
-
-/** Shape handed to the injected audit writer; classification comes from the operation. */
-export type AuditEntryInput = {
-	operation: string
-	actorId: string
-	aggregate: { type: string; id: string }
-	metadata?: Record<string, unknown>
-	classification: string
-}
-
-export type AuditWriter = (
-	context: never,
-	entry: AuditEntryInput,
-) => Promise<unknown> | unknown
-
-type MaybePromise<Value> = Value | Promise<Value>
-type OperationKey<Operations extends CommandRegistry> = Extract<
-	keyof Operations,
-	string
->
-
-export type AuditedOperation = Readonly<{
-	command: Readonly<{ parse: (value: unknown) => unknown }>
-	result: Readonly<{ parse: (value: unknown) => unknown }>
-	classification: string
-	/**
-	 * Permission slug required to execute this operation. Checked through the
-	 * Foundation's injected checkPermission BEFORE guards and the handler;
-	 * declaring a permission without injecting a checker fails closed.
-	 */
-	permission?: string
-	/**
-	 * Per-operation precondition, after the permission check and the registry
-	 * default guard, before the handler. Throw to deny — nothing has run yet.
-	 */
-	guard?: (context: never, command: never) => MaybePromise<void>
-	/**
-	 * Allowlist of aggregate types this operation's audit may reference. When
-	 * declared, an audit entry whose aggregate.type is not listed throws —
-	 * the audit vocabulary is enforced, not advisory.
-	 */
-	aggregates?: readonly string[]
-	audit: (
-		resolution: Readonly<{ command: never; result: never }>,
-		context: never,
-	) => MaybePromise<Omit<AuditEntryInput, 'classification'> | null>
-}>
-
-/** Registry-wide defaults applied to every operation of one Command. */
-export type CommandDefaults = Readonly<{
-	/** Runs before every operation's own guard. Throw to deny. */
-	guard?: (context: never) => MaybePromise<void>
-}>
-
-/** Injected permission policy: throw to deny. Host semantics, kit ordering. */
-export type PermissionChecker = (
-	context: never,
-	input: Readonly<{ permission: string; operation: string }>,
-) => MaybePromise<void>
-
-export type AuditedRegistry = Readonly<Record<string, AuditedOperation>>
-
-export type FoundationOptions = Readonly<{
-	observability: ObservabilityOptions &
-		Readonly<{
-			/**
-			 * In-transaction audit writer used by Command. Operations that
-			 * return an audit record get it written here automatically.
-			 */
-			writeAudit?: AuditWriter
-		}>
-	/**
-	 * Permission policy for operations that declare a `permission`. Runs
-	 * before guards and the handler; throw to deny. An operation with a
-	 * permission but no injected checker fails closed.
-	 */
-	checkPermission?: PermissionChecker
-}>
-
-type FoundationComponentApi = Readonly<{
-	functions: Readonly<{ status: unknown }>
-}>
-
-/**
- * Application command protocol bound to a Foundation instance:
- * validate, observe, execute, and audit. `classification` and `audit()`
- * are mandatory per operation — auditing is type-enforced, not opt-in.
- * Obtain it by destructuring the Foundation: `const { Command } = new Foundation(...)`.
- */
-class BoundCommand<Context, const Operations extends AuditedRegistry> {
-	readonly #kernel: CommandKernelClass<Context, Operations>
-	readonly #observability: Observability
-	readonly #writeAudit: AuditWriter
-	readonly #checkPermission: PermissionChecker | undefined
-	readonly #defaults: CommandDefaults
-
-	/** Declared aggregate types per operation — introspectable for tests. */
-	readonly aggregates: Readonly<{
-		[Key in OperationKey<Operations>]: Operations[Key]['aggregates']
-	}>
-
-	static operation<const Definition extends AuditedOperation>(
-		definition: Definition,
-	): Definition {
-		return definition
-	}
-
-	constructor(
-		operations: Operations,
-		deps: {
-			observability: Observability
-			writeAudit: AuditWriter
-			checkPermission?: PermissionChecker
-			defaults?: CommandDefaults
-		},
-	) {
-		this.#observability = deps.observability
-		this.#writeAudit = deps.writeAudit
-		this.#checkPermission = deps.checkPermission
-		this.#defaults = deps.defaults ?? {}
-		this.aggregates = Object.freeze(
-			Object.fromEntries(
-				Object.entries(operations).map(([operation, definition]) => [
-					operation,
-					definition.aggregates,
-				]),
-			),
-		) as this['aggregates']
-		this.#kernel = new CommandKernelClass<Context, Operations>({
-			operations,
-			execute: (execution) => this.#execute(execution),
-		})
-	}
-
-	exec<const Key extends OperationKey<Operations>>(executor: {
-		operation: Key
-		handler: (
-			context: Context,
-			command: CommandInput<Operations, Key>,
-		) => MaybePromise<CommandResult<Operations, Key>>
-	}) {
-		return this.#kernel.exec(executor)
-	}
-
-	async #execute<Key extends OperationKey<Operations>>(
-		execution: CommandExecution<Context, Operations, Key>,
-	): Promise<CommandResult<Operations, Key>> {
-		return this.#observability.observe(
-			{
-				operation: execution.operation,
-				classification: execution.definition.classification,
-			},
-			async () => {
-				// Guards run before the handler: permission → default → operation.
-				const permission = execution.definition.permission
-				if (permission !== undefined) {
-					if (!this.#checkPermission) {
-						throw new CommandPermissionError(execution.operation)
-					}
-					await this.#checkPermission(execution.context as never, {
-						permission,
-						operation: execution.operation,
-					})
-				}
-				await this.#defaults.guard?.(execution.context as never)
-				await execution.definition.guard?.(
-					execution.context as never,
-					execution.command as never,
-				)
-				const result = await execution.run()
-				const audit = await execution.definition.audit(
-					{ command: execution.command, result } as never,
-					execution.context as never,
-				)
-				if (audit) {
-					const allowed = execution.definition.aggregates
-					if (allowed && !allowed.includes(audit.aggregate.type)) {
-						throw new CommandAggregateError(
-							execution.operation,
-							audit.aggregate.type,
-						)
-					}
-					await this.#writeAudit(execution.context as never, {
-						...audit,
-						classification: execution.definition.classification,
-					})
-				}
-				return result
-			},
-		)
-	}
-}
-
-/** The audit referenced an aggregate type outside the operation's allowlist. */
-class CommandAggregateError extends Error {
-	readonly code = 'COMMAND_AGGREGATE_NOT_DECLARED'
-	readonly name = 'CommandAggregateError'
-
-	constructor(operation: string, aggregateType: string) {
-		super(
-			`Operation "${operation}" audited aggregate type "${aggregateType}" outside its declared aggregates`,
-		)
-	}
-}
-
-/** Fails closed: an operation declared a permission but no checker exists. */
-class CommandPermissionError extends Error {
-	readonly code = 'COMMAND_PERMISSION_NOT_CONFIGURED'
-	readonly name = 'CommandPermissionError'
-
-	constructor(operation: string) {
-		super(
-			`Operation "${operation}" declares a permission but the Foundation has no checkPermission`,
-		)
-	}
-}
-
-export type ApplicationCommand<
-	Context,
-	Operations extends AuditedRegistry,
-> = BoundCommand<Context, Operations>
-
-type CommandConstructor = {
-	new <Context, const Operations extends AuditedRegistry>(
-		operations: Operations,
-		defaults?: CommandDefaults,
-	): BoundCommand<Context, Operations>
-	operation: (typeof BoundCommand)['operation']
-}
-
-/**
- * Host facade for a component that owns no application execution capability.
- * Declared once; the sole source of the command protocol, query kernel, and
- * observability: `const { Command, Query, observability } = new Foundation(...)`.
- */
-export class Foundation<
-	Component extends FoundationComponentApi = FoundationComponentApi,
-> {
-	readonly status: Component['functions']['status']
-	readonly Command: CommandConstructor
-	readonly Query = Query
-	readonly observability: Observability
-
-	constructor(component: Component, options: FoundationOptions) {
-		this.status = component.functions.status
-		const observability = new Observability(options.observability)
-		this.observability = observability
-		const writeAudit = options.observability.writeAudit ?? (() => undefined)
-		const checkPermission = options.checkPermission
-		this.Command = class <
-			Context,
-			const Operations extends AuditedRegistry,
-		> extends BoundCommand<Context, Operations> {
-			constructor(operations: Operations, defaults?: CommandDefaults) {
-				super(operations, {
-					observability,
-					writeAudit,
-					checkPermission,
-					defaults,
-				})
-			}
-		}
-	}
-}
-
-export type {
-	CommandExecution,
-	CommandInput,
-	CommandRegistry,
-	CommandResult,
-	Parseable,
-} from './modules/command/command'
-export { Observability } from './modules/observability/observability'
-export type {
-	CommandObservation,
-	ObservabilityOptions,
-} from './modules/observability/observability'
-export { Query } from './modules/query/query'
-export type { QueryExecution } from './modules/query/query'
-export { executeResultBoundary, projectResult } from './result'
-export type {
-	Result,
-	ResultBoundary,
-	TransactionMetricsContext,
-} from './result'
-export { emitSemanticEvent } from './telemetry'
-
-// Component definition as default export: `import foundation from "cvx-kit/components/foundation"` → app.use(foundation)
-export { default } from "./convex.config"

package/src/components/foundation/convex.config.ts

@@ -1,3 +0,0 @@
-import { defineComponent } from 'convex/server'
-
-export default defineComponent('foundation')

package/src/components/foundation/functions.ts

@@ -1,10 +0,0 @@
-import { v } from 'convex/values'
-
-import { query } from './_generated/server'
-
-/** Minimal health signal exposed only through the configured host facade. */
-export const status = query({
-	args: {},
-	returns: v.literal('ready'),
-	handler: async () => 'ready' as const,
-})