/** * Configuration surface for the Convex projection. * * THIS IS THE CONSUMER-FACING CONFIG SCHEMA. * * Every Convex-specific concept (table name, validator override, indexes, * reference field naming, identity mode) is supplied here at projection time. * NONE of these enter Manifest core grammar or IR. The projection translates * IR + this options bag into Convex artifacts. * * Shape invariant (matches the Prisma projection): all per-property options use * the NESTED form `Record>`. No dotted-string * `"Entity.property"` keys exist anywhere on this surface. * * ## Naming precedence * * 1. App-wide `naming.normalization` (via Manifest config) owns identifier * spelling when enabled. Canonical IR names and Manifest table forms win. * 2. Convex-local `naming` is a **compatibility escape hatch** only. When * app-wide normalization is on, local `naming` is ignored so this projection * cannot silently invent a second spelling. * 3. `tableMappings` / `references` are storage escape hatches (legacy DBs / * imported schemas). They never change Manifest’s canonical names. */ import type { NamingConventionInput } from '../shared/naming.js'; import type { ResolvedNamingConfig } from '../../naming-config.js'; import type { ProjectionDiagnostic } from '../interface.js'; import type { IR } from '../../ir.js'; export type { NamingConventionInput }; /** Entity name as it appears in IR (`IREntity.name`). */ export type EntityName = string; /** Property name as it appears in IR (`IRProperty.name`). */ export type PropertyName = string; /** * One index entry. Plain `string[]` is a composite index over those columns; * the object form lets the consumer supply an explicit Convex index name. */ export type IndexEntry = string[] | { fields: string[]; name?: string; }; /** * How `belongsTo` / `ref` relationships are represented in the schema. * * - `'convexId'` (default) → `: v.id("")`. Idiomatic Convex * for **new** Manifest-generated apps. * - `'stringId'` → `: v.string()`. **Compatibility escape hatch** when * references must carry external/app-level string ids (imported data or an * outside system). New greenfield apps should keep `'convexId'`. */ export type ReferenceMode = 'convexId' | 'stringId'; /** * @internal Injected by `resolveProjectionOptions` — not a consumer option. * Carries app-wide naming policy (normalization + legacy storage remaps). */ export type ManifestNamingInjection = ResolvedNamingConfig; /** * Internal options bag keys that may appear on `request.options` after config * resolution. Kept off {@link ConvexProjectionOptions} so consumers never set them. */ export interface ConvexInternalOptionsBag { __manifestNaming?: ManifestNamingInjection; } export interface ConvexProjectionOptions { /** * Output path hint for the emitted artifact. The projection does not write * files; this flows through to `ProjectionArtifact.pathHint`. * Default: `"convex/schema.ts"`. */ output?: string; /** * **Compatibility escape hatch** — not for normal greenfield apps. * Maps a Manifest entity to an existing Convex table name (legacy DB, * imported schema, or an outside system you cannot rename). Prefer fixing * Manifest naming / reporting a generator bug over hand-mapping new apps. * tableMappings: { CateringEvent: "events" } */ tableMappings?: Record; /** * **Compatibility escape hatch** — not for normal greenfield apps. * Per-property Convex validator literal when the default mapping is wrong * for a deployed/imported column. Incorrect generated validators for * ordinary Manifest types should be reported as Manifest bugs, not papered * over here. * typeMappings: { Invoice: { total: "v.number()" } } */ typeMappings?: Record>; /** * Per-entity composite/named index definitions. Each entry becomes a * `.index("name", [...])` call on the table. * indexes: { Order: [["tenantId", "createdAt"], { fields: ["sku"], name: "by_sku" }] } */ indexes?: Record; /** * **Compatibility escape hatch** — not for normal greenfield apps. * Renames a relationship’s foreign-key field at the Convex storage boundary * only (e.g. Manifest `author` → stored `writerId`). Application-facing / * Manifest names stay canonical. Use for legacy columns; do not invent * divergent FK names in new apps. * references: { Book: { author: "writerId" } } */ references?: Record>; /** * Identity representation for references. Default `'convexId'` (prefer for * new apps). See {@link ReferenceMode}. `'stringId'` is a compatibility * escape hatch for external string ids. */ referenceMode?: ReferenceMode; /** * **Compatibility escape hatch** — physical table casing for this projection * only. Prefer app-wide `naming` / `naming.normalization` in Manifest config. * When app-wide normalization is enabled, this option is **ignored** so Convex * cannot silently emit a second spelling. Defaults to Convex-idiomatic * `{ table: 'camelCase', pluralizeTables: true }` only when app-wide * normalization is off and no convention was inherited from config. */ naming?: NamingConventionInput; /** * Emit a system events table in the schema (the reactive event log that * governed mutations append to). Default `true`. The functions surface * inserts event rows into this table. */ emitEventsTable?: boolean; /** * Name of the system events table. Default `"manifestEvents"`. If the * resolved name collides with an entity's table, it is deterministically * suffixed to stay unique (with a diagnostic). */ eventsTable?: string; /** * Name of the webhook idempotency-keys table auto-emitted in the schema when * any webhook declares `idempotencyHeader`. Default `"webhookIdempotencyKeys"`. * The generated http surface also references this table name for dedup storage. */ idempotencyTable?: string; /** * Emit command-level idempotency storage and accept optional `idempotencyKey` * on every governed mutation. When supplied, duplicate keys return the cached * mutation result without re-executing guards, writes, emits, or reactions. * Default `true`. */ enableCommandIdempotency?: boolean; /** * Table storing cached command results keyed by caller `idempotencyKey`. * Default `"commandIdempotencyKeys"`. Emitted when * {@link enableCommandIdempotency} is on. */ commandIdempotencyTable?: string; /** * Sliding-window rate-limit buckets for commands that declare `rateLimit`. * Default `"commandRateLimitBuckets"`. Emitted automatically when any * command has a rateLimit clause (not for policy/read rateLimit). */ commandRateLimitTable?: string; /** * Authorization-policy enforcement in generated mutations. Default * `'enforce'`. Requires {@link authContextImport} whenever the IR has * authorization policies — Manifest identity is not available on bare * `ctx.auth`. Set `'skip'` only for local demos with no auth (also turn off * tenant filtering if you have no identity module). */ policyMode?: 'enforce' | 'skip'; /** * Module that maps Convex’s real identity (`ctx.auth.getUserIdentity()` and * your claims) into Manifest’s `{ role, , … }` shape via * `getAuthContext(ctx)`. **Required** when tenant filtering or policy * enforcement is active — without it, generation fails with * `CONVEX_AUTH_CONTEXT_REQUIRED` instead of emitting ineffective * `(ctx as any).auth` reads. Example: `"./lib/authContext"`. */ authContextImport?: string; /** * Module exporting `flag(name: string): unknown` (truthy = on). Required for * public Convex queries whose read/`all` policies call `flag()`. Without it, * those queries stay `internalQuery` (fail closed). Same import is used by * generated mutations instead of a stub. Example: `"./lib/flags"`. */ flagProviderImport?: string; /** * Module exporting `encrypt(plaintext, metadata)` and * `decrypt(ciphertext, keyId, metadata)` for properties carrying the * `encrypted` modifier. Metadata is `{ ctx, entity, property }`. Required * whenever a persistent entity has encrypted fields. */ encryptionImport?: string; /** * Keep list/get results inside the caller’s tenant. Default `true`. * When on, generated reads never take a client-supplied tenant id; they use * the authenticated tenant from {@link authContextImport}. Requires that * import whenever the IR declares a tenant column. */ includeTenantFilter?: boolean; /** * Hide soft-deleted rows from list/get. Default `true`. * Rows with a non-null soft-delete timestamp (see {@link deletedAtProperty}) * are filtered out of reads when the entity declares that column. */ includeSoftDeleteFilter?: boolean; /** * Override the tenant property name used for read scoping. Defaults to the * IR's declared tenant property (`ir.tenant.property`) when omitted. */ tenantIdProperty?: string; /** * Soft-delete property name. Default `"deletedAt"`. A read excludes rows * whose value for this property is non-null when `includeSoftDeleteFilter` * is on and the entity declares the column. */ deletedAtProperty?: string; /** * How callers receive computed fields. Default `'helpers'`. * - `'helpers'` → separate `compute(doc)` helpers you call from app code * - `'inline'` → fold self-only computeds into get/list return values * Missing/unresolved computeds always surface as diagnostics (no silent drop). */ computedProperties?: 'helpers' | 'inline'; /** * Authenticated HTTP command dispatcher at * `POST /api/manifest/{entity}/commands/{command}` (Convex `httpRouter` * `pathPrefix`). Default `{ enabled: true }`. Uses `ctx.auth.getUserIdentity()` * then `ctx.runMutation` on the existing governed command mutation — never * accepts identity fields from the request body. */ dispatcher?: { /** When false, omit the authenticated command HTTP route. Default true. */ enabled?: boolean; }; } /** * Defaults, exported so consumers and tests can introspect them. */ export declare const CONVEX_PROJECTION_DEFAULTS: { readonly output: "convex/schema.ts"; readonly referenceMode: ReferenceMode; readonly emitEventsTable: true; readonly eventsTable: "manifestEvents"; readonly idempotencyTable: "webhookIdempotencyKeys"; readonly enableCommandIdempotency: true; readonly commandIdempotencyTable: "commandIdempotencyKeys"; readonly commandRateLimitTable: "commandRateLimitBuckets"; readonly policyMode: "enforce" | "skip"; readonly includeTenantFilter: true; readonly includeSoftDeleteFilter: true; readonly deletedAtProperty: "deletedAt"; readonly computedProperties: "helpers" | "inline"; readonly dispatcher: { readonly enabled: true; }; }; /** * Convex-idiomatic physical table convention when app-wide normalization is * off and no inherited/local naming escape hatch is set. */ export declare const CONVEX_DEFAULT_NAMING: NamingConventionInput; export type NormalizedConvexOptions = Required> & Pick & { dispatcher: { enabled: boolean; }; /** @internal App-wide naming policy when injected by config resolution. */ manifestNaming?: ManifestNamingInjection; }; /** * Normalize a raw `request.options` bag into a fully-typed options object. * Single trust boundary: after this, the projection trusts the contents. * Strips `__manifestNaming` from the consumer shape and keeps it internal. */ export declare function normalizeOptions(raw: Record | undefined): NormalizedConvexOptions; /** Diagnostics for local naming ignored under app-wide normalization. */ export declare function collectConvexNamingPrecedenceDiagnostics(raw: Record | undefined, options: NormalizedConvexOptions): ProjectionDiagnostic[]; /** * Resolve the Convex table key for an entity. * Precedence: tableMappings → app-wide normalized table form → local/default naming. */ export declare function resolveConvexTableName(entityName: string, options: NormalizedConvexOptions): string; /** * Fail closed when authorization or tenant protection would otherwise depend on * the ineffective legacy `(ctx as any).auth` bag. */ export declare function collectConvexAuthConfigDiagnostics(ir: IR, options: NormalizedConvexOptions): ProjectionDiagnostic[]; //# sourceMappingURL=options.d.ts.map