@prisma-next/framework-components

@prisma-next/framework-components

Internal package. This package is an implementation detail of prisma-next and is published only to support its runtime. Its API is unstable and may change without notice. Do not depend on this package directly; install prisma-next instead.

Framework component types, authoring logic, control stack assembly, and emission SPI for Prisma Next.

What this package provides

• Component types (./components): Base descriptor and instance interfaces for framework components (family, target, adapter, driver, extension), pack refs, and type renderer system
• Authoring types (./authoring): Declarative authoring contribution types, template resolution, and validation for type constructors and field presets
• Codec base interface (./codec): The cross-family Codec base type that SQL Codec and Mongo MongoCodec extend
• Control stack (./control): Assembly functions that combine component descriptors into a unified ControlStack with derived state (codec imports, renderers, authoring contributions)
• Emission SPI (./emission): Types for the emission pipeline — TargetFamilyHook, ValidationContext, GenerateContractTypesOptions, TypeRenderEntry, TypeRenderer, ParameterizedCodecDescriptor, and related types
• Execution types (./execution): Execution-plane stack and instance interfaces
• Runtime SPI (./runtime): Abstract RuntimeCore<TPlan, TExec, TMiddleware> base class, RuntimeMiddleware interface, and the canonical runWithMiddleware orchestrator helper. Family runtimes (@prisma-next/sql-runtime, @prisma-next/mongo-runtime) extend RuntimeCore directly per ADR 204.

Subpath exports

import { ComponentMetadata, FamilyDescriptor, normalizeRenderer } from '@prisma-next/framework-components/components';
import { AuthoringContributions, instantiateAuthoringTypeConstructor } from '@prisma-next/framework-components/authoring';
import type { Codec } from '@prisma-next/framework-components/codec';
import { createControlStack, ControlStack } from '@prisma-next/framework-components/control';
import type { EmissionSpi } from '@prisma-next/framework-components/emission';
import { RuntimeCore, runWithMiddleware, type RuntimeMiddleware } from '@prisma-next/framework-components/runtime';

Codec interface

The base Codec interface lands on the seam between query-time methods (per-row, IO-relevant) and build-time methods (per-contract-load):

• Query-time: encode(value): Promise<TWire> and decode(wire): Promise<TInput> are required and Promise-returning at the public boundary, regardless of whether the codec body is synchronous or asynchronous. Family factories (codec() for SQL, mongoCodec() for Mongo) accept either sync or async author functions and lift sync ones to Promise-shaped methods, so authors write whichever shape is natural per method without annotations.
• Build-time: encodeJson, decodeJson, and the optional renderOutputType are synchronous so validateContract and client construction stay synchronous.

There is no runtime / kind / equivalent async marker on the interface and no TRuntime generic. The runtime always awaits the query-time methods. See ADR 204 — Single-Path Async Codec Runtime for the full design.

Codec call context (ctx)

Codecs receive a second ctx options argument; you may ignore it. The runtime allocates one CodecCallContext per execute() call and threads the same reference to every codec dispatch site as a non-optional argument — when no signal is supplied the runtime still threads an empty {}, never undefined. The framework CodecCallContext is signal-only:

export interface CodecCallContext {
  readonly signal?: AbortSignal;
}

The internal Codec interface declares the parameter as required:

encode(value: TInput, ctx: CodecCallContext): Promise<TWire>;
decode(wire: TWire, ctx: CodecCallContext): Promise<TInput>;

Codec authors who write (value) => … continue to compile via TypeScript's bivariance for trailing parameters; nothing at the author surface changes.

Family layers extend the context where they have a per-call concept that doesn't generalise. SQL declares SqlCodecCallContext extends CodecCallContext { column?: SqlColumnRef } (see @prisma-next/sql-relational-core); Mongo continues to use the framework type directly. Codec authors that take a (value, ctx) author signature can forward ctx.signal to network SDKs:

// Sketch — actual factory lives in a family package (codec() / mongoCodec()).
encode: async (v: string, ctx) =>
  kms.encrypt({ plaintext: v }, { signal: ctx?.signal });

Aborts surface to the caller as RUNTIME.ABORTED with details.phase ∈ { 'encode', 'decode', 'stream' }. Codec bodies that ignore the signal complete in the background (cooperative cancellation). The runtimeAborted(phase, cause?) envelope helper and the raceAgainstAbort(work, signal, phase) race helper are exported from @prisma-next/framework-components/runtime.

See ADR 207 — Codec call context: per-query AbortSignal and column metadata for the full design.

Why SPI types live here (dependency inversion)

This package sits in the core layer — below the tooling layer where family-specific emitters and control implementations live. SPI interfaces like EmissionSpi define the contract between framework orchestration code (control-plane emission, CLI) and family-specific implementations (SQL emitter, Mongo emitter).

By placing these interfaces in the core layer rather than alongside their implementations:

• Orchestration code (control-plane, CLI) can depend on the SPI interfaces without pulling in family-specific packages.
• Family implementations (SQL emitter, Mongo emitter) implement these interfaces and depend on this package — the dependency arrow points inward toward the core.
• The contract package (@prisma-next/contract) remains a true leaf in the foundation layer with zero framework-domain dependencies.

This is the dependency inversion principle applied to package layering. The same pattern applies to component descriptors, control-plane types, and execution-plane types in this package.

See ADR 185 — SPI types live at the lowest consuming layer.

Relationship to other packages

This package is the canonical source for framework component types, assembly logic, and emission SPI types. New code should import directly from @prisma-next/framework-components.