Provider authoring API

Generated public TypeScript reference for @relkit/provider.

For configuration and examples, read provider authoring.

Public imports

• @relkit/provider — 88 exports

All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API’s inline sample, a maintained repository usage, or the shared module walkthrough.

adapter-builder.ts

DefineProviderAdapterOptions

Signature

declare const DefineProviderAdapterOptions: DefineProviderAdapterOptions<
  Capability,
  AdapterId,
  Connection,
  Behavior
>;

Source

defineProviderAdapter

Define and validate a pure provider adapter synchronously.

Throws

TypeError for unknown fields, invalid features, or invalid identifiers.

Example

defineProviderAdapter(options);

Signature

declare const defineProviderAdapter: <
  const Capability extends ProviderCapability,
  const AdapterId extends string,
  const Connection extends ProviderConnectionValues,
  const Behavior extends ProviderBehavior,
>(
  options: DefineProviderAdapterOptions<Capability, AdapterId, Connection, Behavior>,
) => BuiltProviderAdapter<Capability, AdapterId, Connection, Behavior>;

Source

defineProviderAdapterEffect

Define and validate a pure provider adapter in an Effect.

Example

Effect.runSync(defineProviderAdapterEffect(options));

Signature

declare const defineProviderAdapterEffect: <
  const Capability extends ProviderCapability,
  const AdapterId extends string,
  const Connection extends ProviderConnectionValues,
  const Behavior extends ProviderBehavior,
>(
  options: DefineProviderAdapterOptions<Capability, AdapterId, Connection, Behavior>,
) => Effect.Effect<
  BuiltProviderAdapter<Capability, AdapterId, Connection, Behavior>,
  ProviderError
>;

Source

adapter-builder.types.ts

BuiltProviderAdapter (type alias)

Adapter produced from a typed builder input.

Signature

type BuiltProviderAdapter<
  Capability extends ProviderCapability,
  AdapterId extends string,
  Connection extends ProviderConnectionValues,
  Behavior extends ProviderBehavior,
> = ProviderAdapter<Capability, AdapterId, Connection, Behavior>;

Source

DefineProviderAdapterOptions (interface)

Inputs accepted by a provider adapter builder.

Signature

export interface DefineProviderAdapterOptions<
  Capability extends ProviderCapability,
  AdapterId extends string,
  Connection extends ProviderConnectionValues,
  Behavior extends ProviderBehavior,
> {
  readonly integration: IntegrationReference;
  readonly capability: Capability;
  readonly adapterId: AdapterId;
  readonly connectionContract: ProviderConnectionContract;
  readonly connection: Connection;
  readonly behavior: Behavior;
  readonly features?: readonly ProviderFeature<Capability["id"]>[];
  readonly localRecipe?: ProviderLocalRecipeReference;
}

Source

binding-normalization.ts

NormalizeProviderBindingOptions

Signature

declare const NormalizeProviderBindingOptions: NormalizeProviderBindingOptions;

Source

ProviderFeatureMismatchError

Signature

declare const ProviderFeatureMismatchError: typeof ProviderFeatureMismatchError;

Source

normalizeProviderBinding

Normalize a selected binding for synchronous callers.

Throws

ProviderFeatureMismatchError when required features are absent.

Example

normalizeProviderBinding(selection, { descriptorId: "cart" });

Signature

declare const normalizeProviderBinding: (
  selection: ProviderProfileSelection,
  options: NormalizeProviderBindingOptions,
) => NormalizedProviderBinding;

Source

normalizeProviderBindingEffect

Normalize a selected binding in an Effect after checking features.

Example

Effect.runSync(normalizeProviderBindingEffect(selection, { descriptorId: "cart" }));

Signature

declare const normalizeProviderBindingEffect: (
  selection: ProviderProfileSelection,
  options: NormalizeProviderBindingOptions,
) => Effect.Effect<NormalizedProviderBinding, ProviderError>;

Source

binding-normalization.types.ts

Required features for a logical descriptor’s selected provider.

NormalizeProviderBindingOptions (interface)

Required features for a logical descriptor’s selected provider.

Signature

export interface NormalizeProviderBindingOptions {
  readonly descriptorId: string;
  readonly requiredFeatures?: readonly string[];
}

Source

binding-resolution.ts

ProviderBindingResolutionCode

Signature

declare const ProviderBindingResolutionCode: ProviderBindingResolutionCode;

Source

ProviderBindingResolutionError

Signature

declare const ProviderBindingResolutionError: typeof ProviderBindingResolutionError;

Source

ProviderConnectionDescriptor

Signature

declare const ProviderConnectionDescriptor: ProviderConnectionDescriptor;

Source

ResolveProviderConnectionOptions

Signature

declare const ResolveProviderConnectionOptions: ResolveProviderConnectionOptions;

Source

resolveProviderConnection

Resolve provider connection values synchronously for legacy callers.

Throws

ProviderBindingResolutionError for missing or conflicting values; TypeError for invalid input.

Example

resolveProviderConnection(adapter, { profile: "default" });

Signature

declare const resolveProviderConnection: (
  adapter: ProviderConnectionDescriptor,
  options: ResolveProviderConnectionOptions,
) => Readonly<Record<string, JsonValue>>;

Source

resolveProviderConnectionEffect

Resolve a provider’s connection values in an Effect with tagged failures.

Example

Effect.runSync(resolveProviderConnectionEffect(adapter, { profile: "default" }));

Signature

declare const resolveProviderConnectionEffect: (
  adapter: ProviderConnectionDescriptor,
  options: ResolveProviderConnectionOptions,
) => Effect.Effect<Readonly<Record<string, JsonValue>>, ProviderError>;

Source

binding-resolution.types.ts

ProviderConnectionDescriptor (interface)

Minimal adapter shape accepted by connection resolution.

Signature

export interface ProviderConnectionDescriptor {
  readonly capability: Readonly<{ readonly id: string }>;
  readonly connectionContract: Readonly<{
    readonly fields: Readonly<Record<string, ProviderConnectionField>>;
  }>;
  readonly connection: ProviderConnectionValues;
}

Source

ResolveProviderConnectionOptions (interface)

Inputs for resolving authored, local, infrastructure, and named values.

Signature

export interface ResolveProviderConnectionOptions {
  readonly profile: string;
  readonly bindingId?: string;
  readonly local?: Readonly<Record<string, JsonValue>>;
  readonly infrastructure?: Readonly<Record<string, JsonValue>>;
  readonly values?: Readonly<Record<string, JsonValue>>;
}

Source

binding-values.ts

createBindingValueRef

Create a binding-local value reference synchronously.

Throws

TypeError for an invalid name.

Example

createBindingValueRef("CACHE_URL", "secret-string");

Signature

declare const createBindingValueRef: <
  const Name extends string,
  Value = unknown,
  const Type extends BindingValueType = BindingValueType,
>(
  name: Name,
  type: Type,
) => BindingValueRef<Name, Value, Type>;

Source

createBindingValueRefEffect

Create a binding-local named value reference in an Effect.

Example

Effect.runSync(createBindingValueRefEffect("CACHE_URL", "secret-string"));

Signature

declare const createBindingValueRefEffect: <
  const Name extends string,
  Value = unknown,
  const Type extends BindingValueType = BindingValueType,
>(
  name: Name,
  type: Type,
) => Effect.Effect<BindingValueRef<Name, Value, Type>, ProviderError>;

Source

isBindingValueRef

Check an exact binding-local reference synchronously.

Example

isBindingValueRef(value);

Signature

declare const isBindingValueRef: (value: unknown) => value is BindingValueRef;

Source

isBindingValueRefCore

Pure predicate shared by observed provider operations.

Example

isBindingValueRefCore({ kind: "binding-value-ref", name: "URL", type: "string", sensitive: false });

Signature

declare const isBindingValueRefCore: (value: unknown) => value is BindingValueRef;

Source

isBindingValueRefEffect

Check an exact binding-local reference in an Effect.

Example

Effect.runSync(isBindingValueRefEffect(value));

Signature

declare const isBindingValueRefEffect: (value: unknown) => Effect.Effect<boolean, ProviderError>;

Source

dependency-preflight.service.ts

Validates only selected capability/phase requirements before readiness. The Layer captures read-only resolution; checks resolve adapters from projects and peers from adapters, aggregate missing/version diagnostics, and never install.

“./dependency-preflight.types.js” (namespace export)

Re-exports all named exports from the “./dependency-preflight.types.js” module.

Signature

export * from "./dependency-preflight.types.js";

Source

DependencyResolutionFailure

Signature

declare const DependencyResolutionFailure: typeof DependencyResolutionFailure;

Source

DependencySource

Signature

declare const DependencySource: typeof DependencySource;

Source

DependencySourceLive

Signature

declare const DependencySourceLive: Layer.Layer<DependencySource, never, never>;

Source

SelectedDependencies (class)

Shared startup/compiler validator; each call retains its own selection and roots.

Signature

declare class SelectedDependencies

Source

SelectedDependenciesLayer

Domain Layer leaves its native source replaceable without changing check behavior.

Signature

declare const SelectedDependenciesLayer: Layer.Layer<SelectedDependencies, never, DependencySource>;

Source

SelectedDependenciesLive

Live compiler/runtime composition has no CLI/compiler or concrete SDK dependency.

Signature

declare const SelectedDependenciesLive: Layer.Layer<SelectedDependencies, never, never>;

Source

SelectedDependencyFailure

Signature

declare const SelectedDependencyFailure: typeof SelectedDependencyFailure;

Source

SelectedDependencyInitializationFailure

Signature

declare const SelectedDependencyInitializationFailure: typeof SelectedDependencyInitializationFailure;

Source

checkIntegrationDependencies

Signature

declare const checkIntegrationDependencies: (
  plan: RuntimeIntegrationPlan,
  options: {
    readonly projectRoot: string;
    readonly phase: IntegrationDependencyPhase;
    readonly manager?: DependencyPackageManager;
  },
) => Effect.Effect<
  Array<Array<InstalledPackageIdentity>>,
  DependencyResolutionFailure | SelectedDependencyFailure,
  SelectedDependencies
>;

Source

initializeIntegration

Signature

declare const initializeIntegration: <Module>(
  packageName: string,
  load: () => Promise<Module>,
) => Effect.Effect<Module, SelectedDependencyInitializationFailure, never>;

Source

identity-builders.ts

defineIntegrationReference

Define a static integration identity synchronously.

Throws

TypeError for invalid identifiers.

Example

defineIntegrationReference("redis");

Signature

declare const defineIntegrationReference: <const Id extends string>(
  integrationId: Id,
) => IntegrationReference<Id>;

Source

defineIntegrationReferenceEffect

Define a static integration identity in an Effect.

Example

Effect.runSync(defineIntegrationReferenceEffect("redis"));

Signature

declare const defineIntegrationReferenceEffect: <const Id extends string>(
  integrationId: Id,
) => Effect.Effect<IntegrationReference<Id>, ProviderError>;

Source

defineLocalRecipeReference

Define versioned local-recipe provenance synchronously.

Throws

TypeError for invalid versions or identifiers.

Example

defineLocalRecipeReference(redis, "redis-docker", 1);

Signature

declare const defineLocalRecipeReference: (
  integration: IntegrationReference,
  recipeId: string,
  recipeVersion: number,
) => ProviderLocalRecipeReference;

Source

defineLocalRecipeReferenceEffect

Define versioned local-recipe provenance in an Effect.

Example

Effect.runSync(defineLocalRecipeReferenceEffect(redis, "redis-docker", 1));

Signature

declare const defineLocalRecipeReferenceEffect: (
  integration: IntegrationReference,
  recipeId: string,
  recipeVersion: number,
) => Effect.Effect<ProviderLocalRecipeReference, ProviderError>;

Source

defineProviderCapability

Define a stable capability synchronously.

Throws

TypeError for invalid identifiers.

Example

defineProviderCapability("cache");

Signature

declare const defineProviderCapability: <const Id extends string>(id: Id) => ProviderCapability<Id>;

Source

defineProviderCapabilityEffect

Define a stable provider capability in an Effect.

Example

Effect.runSync(defineProviderCapabilityEffect("cache"));

Signature

declare const defineProviderCapabilityEffect: <const Id extends string>(
  id: Id,
) => Effect.Effect<ProviderCapability<Id>, ProviderError>;

Source

defineProviderFeature

Define an adapter feature synchronously.

Throws

TypeError for invalid identifiers.

Example

defineProviderFeature(cache, "atomicIncrement");

Signature

declare const defineProviderFeature: <
  const Capability extends ProviderCapability,
  const Id extends string,
>(
  capability: Capability,
  id: Id,
) => ProviderFeature<Capability["id"], Id>;

Source

defineProviderFeatureEffect

Define an adapter feature in an Effect.

Example

Effect.runSync(defineProviderFeatureEffect(cache, "atomicIncrement"));

Signature

declare const defineProviderFeatureEffect: <
  const Capability extends ProviderCapability,
  const Id extends string,
>(
  capability: Capability,
  id: Id,
) => Effect.Effect<ProviderFeature<Capability["id"], Id>, ProviderError>;

Source

index.ts

“./binding-normalization.js” (namespace export)

Re-exports all named exports from the “./binding-normalization.js” module.

Signature

export * from "./binding-normalization.js";

Source

“./binding-resolution.js” (namespace export)

Re-exports all named exports from the “./binding-resolution.js” module.

Signature

export * from "./binding-resolution.js";

Source

“./profile-normalization.js” (namespace export)

Re-exports all named exports from the “./profile-normalization.js” module.

Signature

export * from "./profile-normalization.js";

Source

“./protocol-builders.js” (namespace export)

Re-exports all named exports from the “./protocol-builders.js” module.

Signature

export * from "./protocol-builders.js";

Source

“./protocol.js” (namespace export)

Re-exports all named exports from the “./protocol.js” module.

Signature

export * from "./protocol.js";

Source

“./protocol.types.js” (namespace export)

Re-exports all named exports from the “./protocol.types.js” module.

Signature

export * from "./protocol.types.js";

Source

“./provider-observability.js” (namespace export)

Re-exports all named exports from the “./provider-observability.js” module.

Signature

export * from "./provider-observability.js";

Source

“./runtime.types.js” (namespace export)

Re-exports all named exports from the “./runtime.types.js” module.

Signature

export * from "./runtime.types.js";

Source

ProviderBindingResolutionFailure

Signature

declare const ProviderBindingResolutionFailure: typeof ProviderBindingResolutionFailure;

Source

ProviderFeatureMismatchFailure

Signature

declare const ProviderFeatureMismatchFailure: typeof ProviderFeatureMismatchFailure;

Source

ProviderProfileSelectionFailure

Signature

declare const ProviderProfileSelectionFailure: typeof ProviderProfileSelectionFailure;

Source

ProviderValidationError

Signature

declare const ProviderValidationError: typeof ProviderValidationError;

Source

createBindingValueRef

Signature

declare const createBindingValueRef: <
  const Name extends string,
  Value = unknown,
  const Type extends BindingValueType = BindingValueType,
>(
  name: Name,
  type: Type,
) => BindingValueRef<Name, Value, Type>;

Source

createBindingValueRefEffect

Signature

declare const createBindingValueRefEffect: <
  const Name extends string,
  Value = unknown,
  const Type extends BindingValueType = BindingValueType,
>(
  name: Name,
  type: Type,
) => Effect<BindingValueRef<Name, Value, Type>, ProviderError>;

Source

defineInfrastructureProviderSource

Signature

declare const defineInfrastructureProviderSource: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
  integration: IntegrationReference,
  options: JsonValue,
  access?: ProviderAccess,
) => InfrastructureProviderSource<Adapter>;

Source

defineInfrastructureProviderSourceEffect

Signature

declare const defineInfrastructureProviderSourceEffect: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
  integration: IntegrationReference,
  options: JsonValue,
  access?: ProviderAccess,
) => Effect<InfrastructureProviderSource<Adapter>, ProviderError>;

Source

defineLocalProviderSource

Signature

declare const defineLocalProviderSource: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
) => LocalProviderSource<Adapter>;

Source

defineLocalProviderSourceEffect

Signature

declare const defineLocalProviderSourceEffect: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
) => Effect<LocalProviderSource<Adapter>, ProviderError>;

Source

isBindingValueRef

Signature

declare const isBindingValueRef: (value: unknown) => value is BindingValueRef;

Source

isBindingValueRefEffect

Signature

declare const isBindingValueRefEffect: (value: unknown) => Effect<boolean, ProviderError>;

Source

normalizeProviderSource

Signature

declare const normalizeProviderSource: <const Adapter extends ProviderAdapter>(
  input: ProviderSourceInput<Adapter>,
) => NormalizedProviderSource<Adapter>;

Source

normalizeProviderSourceEffect

Signature

declare const normalizeProviderSourceEffect: <const Adapter extends ProviderAdapter>(
  input: ProviderSourceInput<Adapter>,
) => Effect<NormalizedProviderSource<Adapter>, ProviderError>;

Source

profile-normalization.ts

NormalizedProviderProfiles

Signature

declare const NormalizedProviderProfiles: NormalizedProviderProfiles<Adapter>;

Source

ProviderInput

Signature

declare const ProviderInput: ProviderInput<Binding>;

Source

ProviderProfileSelection

Signature

declare const ProviderProfileSelection: ProviderProfileSelection<Adapter>;

Source

ProviderProfileSelectionError

Signature

declare const ProviderProfileSelectionError: typeof ProviderProfileSelectionError;

Source

ProviderProfileSelectionSource

Signature

declare const ProviderProfileSelectionSource: ProviderProfileSelectionSource;

Source

SelectProviderProfileOptions

Signature

declare const SelectProviderProfileOptions: SelectProviderProfileOptions;

Source

normalizeProviderProfiles

Normalize provider profiles for synchronous callers.

Throws

TypeError when a profile is empty, duplicated, or mismatched.

Example

normalizeProviderProfiles(cache, adapter);

Signature

declare const normalizeProviderProfiles: <Adapter extends ProviderAdapter>(
  capability: ProviderCapability,
  input: ProviderInput<ProviderSourceInput<Adapter>>,
) => NormalizedProviderProfiles<Adapter>;

Source

normalizeProviderProfilesEffect

Normalize a direct source or named profile map in an Effect.

Example

Effect.runSync(normalizeProviderProfilesEffect(cache, adapter));

Signature

declare const normalizeProviderProfilesEffect: <Adapter extends ProviderAdapter>(
  capability: ProviderCapability,
  input: ProviderInput<ProviderSourceInput<Adapter>>,
) => Effect.Effect<NormalizedProviderProfiles<Adapter>, ProviderError>;

Source

selectProviderProfile

Select a provider profile synchronously for legacy callers.

Throws

ProviderProfileSelectionError for ambiguity or an unknown profile.

Example

selectProviderProfile(profiles, { descriptorId: "cart" });

Signature

declare const selectProviderProfile: <Adapter extends ProviderAdapter>(
  normalized: NormalizedProviderProfiles<Adapter>,
  options: SelectProviderProfileOptions,
) => ProviderProfileSelection<Adapter>;

Source

selectProviderProfileEffect

Select a descriptor, default, or sole provider profile in an Effect.

Example

Effect.runSync(selectProviderProfileEffect(profiles, { descriptorId: "cart" }));

Signature

declare const selectProviderProfileEffect: <Adapter extends ProviderAdapter>(
  normalized: NormalizedProviderProfiles<Adapter>,
  options: SelectProviderProfileOptions,
) => Effect.Effect<ProviderProfileSelection<Adapter>, ProviderError>;

Source

profile-normalization.types.ts

NormalizedProviderProfiles (interface)

Immutable provider sources keyed by normalized profile name.

Signature

export interface NormalizedProviderProfiles<Adapter extends ProviderAdapter = ProviderAdapter> {
  readonly kind: "normalized-provider-profiles";
  readonly capability: string;
  readonly profiles: Readonly<Record<string, NormalizedProviderSource<Adapter>>>;
}

Source

ProviderInput (type alias)

A direct binding or a map of named provider profiles.

Signature

type ProviderInput<Binding> = Binding | Readonly<Record<string, Binding>>;

Source

ProviderProfileSelection (interface)

Selected profile with the matching normalized binding.

Signature

export interface ProviderProfileSelection<Adapter extends ProviderAdapter = ProviderAdapter> {
  readonly capability: string;
  readonly profile: string;
  readonly source: ProviderProfileSelectionSource;
  readonly binding: NormalizedProviderSource<Adapter>;
}

Source

ProviderProfileSelectionSource (type alias)

How a profile was selected.

Signature

type ProviderProfileSelectionSource = "descriptor" | "default" | "sole";

Source

ProviderProfileSource (type alias)

Source accepted by profile normalization.

Signature

type ProviderProfileSource<Adapter extends ProviderAdapter> = ProviderInput<
  ProviderSourceInput<Adapter>
>;

Source

SelectProviderProfileOptions (interface)

Descriptor and optional application-level default profile selection.

Signature

export interface SelectProviderProfileOptions {
  readonly descriptorId: string;
  readonly profile?: string;
  readonly defaultProfile?: string;
}

Source

protocol.ts

Current provider descriptor protocol version.

PROVIDER_PROTOCOL_VERSION

Current provider descriptor protocol version.

Signature

declare const PROVIDER_PROTOCOL_VERSION: 1;

Source

protocol.types.ts

BindingValueRef (type alias)

Opaque reference to a binding-local runtime value.

Signature

type BindingValueRef<
  Name extends string = string,
  Value = unknown,
  Type extends BindingValueType = BindingValueType,
> = Readonly<{
  kind: "binding-value-ref";
  name: Name;
  type: Type;
  sensitive: Type extends "secret-string" ? true : false;
  __value?: Value;
}> &
  ProviderProtocolType<"binding-value-ref">;

Source

BindingValueType (type alias)

Supported named binding value kinds.

Signature

type BindingValueType = "string" | "number" | "boolean" | "port" | "url" | "json" | "secret-string";

Source

InfrastructureProviderSource (type alias)

Adapter and infrastructure materialization request.

Signature

type InfrastructureProviderSource<Adapter extends ProviderAdapter = ProviderAdapter> = Readonly<{
  kind: "provider-infrastructure-source";
  adapter: Adapter;
  integration: IntegrationReference;
  options: JsonValue;
  access?: ProviderAccess;
}> &
  ProviderProtocolType<"infrastructure-source">;

Source

IntegrationReference (type alias)

Static integration identity without an import path.

Signature

type IntegrationReference<Id extends string = string> = Readonly<{
  kind: "integration-reference";
  integrationId: Id;
}> &
  ProviderProtocolType<"integration-reference">;

Source

LocalProviderSource (type alias)

Adapter wrapped with its declared local recipe.

Signature

type LocalProviderSource<Adapter extends ProviderAdapter = ProviderAdapter> = Readonly<{
  kind: "provider-local-source";
  adapter: Adapter;
}> &
  ProviderProtocolType<"local-source">;

Source

NormalizedProviderAdapter (interface)

Runtime-facing projection of an adapter’s immutable fields.

Signature

export interface NormalizedProviderAdapter {
  readonly integrationId: string;
  readonly adapterId: string;
  readonly protocolVersion: ProviderProtocolVersion;
  readonly behavior: JsonValue;
  readonly connectionContract: ProviderConnectionFields;
  readonly connection: ProviderConnectionValues;
  readonly features: readonly string[];
}

Source

NormalizedProviderBinding (type alias)

Selected provider binding consumed by the runtime.

Signature

type NormalizedProviderBinding = Readonly<{
  kind: "provider-binding";
  capability: string;
  profile: string;
  adapter: NormalizedProviderAdapter;
  source: ProviderBindingSource;
  local?: ProviderLocalRecipeReference;
  access?: JsonValue;
}> &
  ProviderProtocolType<"normalized-binding">;

Source

NormalizedProviderSource (type alias)

Frozen source descriptor consumed by profile normalization.

Signature

type NormalizedProviderSource<Adapter extends ProviderAdapter = ProviderAdapter> = Readonly<{
  kind: "normalized-provider-source";
  adapter: Adapter;
  source: ProviderBindingSource;
  local?: ProviderLocalRecipeReference;
  access?: JsonValue;
}> &
  ProviderProtocolType<"normalized-source">;

Source

ProviderAccess (type alias)

Access policy metadata for an infrastructure source.

Signature

type ProviderAccess<Value extends JsonValue = JsonValue> = Readonly<{
  kind: "provider-access";
  value: Value;
}> &
  ProviderProtocolType<"access">;

Source

ProviderAdapter (type alias)

Immutable adapter descriptor for one integration capability.

Signature

type ProviderAdapter<
  Capability extends ProviderCapability = ProviderCapability,
  AdapterId extends string = string,
  Connection extends ProviderConnectionValues = ProviderConnectionValues,
  Behavior extends ProviderBehavior = ProviderBehavior,
> = Readonly<{
  kind: "provider-adapter";
  protocolVersion: ProviderProtocolVersion;
  integration: IntegrationReference;
  capability: Capability;
  adapterId: AdapterId;
  connectionContract: ProviderConnectionContract;
  connection: Connection;
  behavior: Behavior;
  features: readonly ProviderFeature<Capability["id"]>[];
  localRecipe?: ProviderLocalRecipeReference;
}> &
  ProviderProtocolType<"adapter">;

Source

ProviderBehavior (type alias)

Immutable behavioral metadata separate from connection values.

Signature

type ProviderBehavior<Value extends JsonValue = JsonValue> = Readonly<{
  kind: "provider-behavior";
  value: Value;
}> &
  ProviderProtocolType<"behavior">;

Source

ProviderBindingSource (type alias)

Source mode selected for a normalized provider binding.

Signature

type ProviderBindingSource =
  | Readonly<{ kind: "connected" }>
  | Readonly<{ kind: "local-only" }>
  | Readonly<{
      kind: "infrastructure";
      integrationId: string;
      options: JsonValue;
    }>;

Source

ProviderCapability (type alias)

Nominal capability identity shared by features and adapters.

Signature

type ProviderCapability<Id extends string = string> = Readonly<{
  kind: "provider-capability";
  id: Id;
}> &
  ProviderProtocolType<"capability">;

Source

ProviderConnectionContract (type alias)

Nominal connection contract for a provider adapter.

Signature

type ProviderConnectionContract<
  Fields extends ProviderConnectionFields = ProviderConnectionFields,
> = Readonly<{
  kind: "provider-connection-contract";
  fields: Fields;
}> &
  ProviderProtocolType<"connection-contract">;

Source

ProviderConnectionField (interface)

Normalized field contract with explicit defaults.

Signature

export interface ProviderConnectionField {
  readonly required: boolean;
  readonly sensitive: boolean;
  readonly authoredValue: ProviderConnectionValueMode;
  readonly default?: JsonValue;
}

Source

ProviderConnectionFieldInput (interface)

Authoring options for one connection field.

Signature

export interface ProviderConnectionFieldInput {
  readonly required?: boolean;
  readonly sensitive?: boolean;
  readonly authoredValue?: ProviderConnectionValueMode;
  readonly default?: JsonValue;
}

Source

ProviderConnectionFields (type alias)

Named connection fields in an adapter contract.

Signature

type ProviderConnectionFields = Readonly<Record<string, ProviderConnectionField>>;

Source

ProviderConnectionValue (type alias)

Literal JSON or a named binding value reference.

Signature

type ProviderConnectionValue = JsonValue | BindingValueRef;

Source

ProviderConnectionValueMode (type alias)

Whether authored connection values are fixed or allow outputs to replace them.

Signature

type ProviderConnectionValueMode = "fixed" | "fallback";

Source

ProviderConnectionValues (type alias)

Authored connection field values.

Signature

type ProviderConnectionValues = Readonly<Record<string, ProviderConnectionValue>>;

Source

ProviderFeature (type alias)

Nominal feature identity within one provider capability.

Signature

type ProviderFeature<Capability extends string = string, Id extends string = string> = Readonly<{
  kind: "provider-feature";
  capability: Capability;
  id: Id;
}> &
  ProviderProtocolType<"feature">;

Source

ProviderLocalRecipeReference (interface)

Versioned local recipe provenance for an adapter.

Signature

export interface ProviderLocalRecipeReference {
  readonly integrationId: string;
  readonly recipeId: string;
  readonly recipeVersion: number;
}

Source

ProviderProtocolVersion (type alias)

Current version accepted by provider descriptors.

Signature

type ProviderProtocolVersion = typeof PROVIDER_PROTOCOL_VERSION;

Source

ProviderSourceInput (type alias)

Direct adapter or one source wrapper.

Signature

type ProviderSourceInput<Adapter extends ProviderAdapter = ProviderAdapter> =
  Adapter | LocalProviderSource<Adapter> | InfrastructureProviderSource<Adapter>;

Source

provider-compat-errors.ts

ProviderBindingResolutionError (class)

Synchronous connection error retained for compatibility.

Example

throw new ProviderBindingResolutionError(
  "MISSING_CONNECTION_VALUE",
  "cache.default",
  "url",
  "is required",
);

Signature

declare class ProviderBindingResolutionError {
  constructor(
    code: ProviderBindingResolutionCode,
    bindingId: string,
    field: string,
    reason: string,
  );
}

Source

code (property)

Signature

readonly code: ProviderBindingResolutionCode

Source

bindingId (property)

Signature

readonly bindingId: string

Source

field (property)

Signature

readonly field: string

Source

reason (property)

Signature

readonly reason: string

Source

ProviderFeatureMismatchError (class)

Synchronous missing-feature error retained for compatibility.

Example

throw new ProviderFeatureMismatchError("cache", "default", "cart", ["atomic"]);

Signature

declare class ProviderFeatureMismatchError {
  constructor(
    capability: string,
    profile: string,
    descriptorId: string,
    features: readonly string[],
  );
}

Source

code (property)

Signature

readonly code: "MISSING_PROVIDER_FEATURE"

Source

capability (property)

Signature

readonly capability: string

Source

profile (property)

Signature

readonly profile: string

Source

descriptorId (property)

Signature

readonly descriptorId: string

Source

features (property)

Signature

readonly features: ReadonlyArray<string>

Source

ProviderInputError (class)

Internal marker for expected provider input failures.

Example

throw new ProviderInputError("Invalid provider ID");

Signature

declare class ProviderInputError

Source

ProviderProfileSelectionError (class)

Synchronous profile selection error retained for compatibility.

Example

throw new ProviderProfileSelectionError(
  "UNKNOWN_PROVIDER_PROFILE",
  "cache",
  "cart",
  [],
  "selected unknown profile",
);

Signature

declare class ProviderProfileSelectionError {
  constructor(
    code: ProviderProfileSelectionError["code"],
    capability: string,
    descriptorId: string,
    profiles: readonly string[],
    reason: string,
  );
}

Source

code (property)

Signature

readonly code: "AMBIGUOUS_PROVIDER_PROFILE" | "UNKNOWN_PROVIDER_PROFILE"

Source

capability (property)

Signature

readonly capability: string

Source

descriptorId (property)

Signature

readonly descriptorId: string

Source

profiles (property)

Signature

readonly profiles: ReadonlyArray<string>

Source

reason (property)

Signature

readonly reason: string

Source

provider-errors.ts

ProviderBindingResolutionCode

Signature

declare const ProviderBindingResolutionCode: ProviderBindingResolutionCode;

Source

ProviderBindingResolutionFailure (class)

Tagged connection failure in the Effect error channel.

Example

Effect.catchTag("ProviderBindingResolutionError", (error) => Effect.logWarning(error.message));

Signature

declare class ProviderBindingResolutionFailure

Source

ProviderFeatureMismatchFailure (class)

Tagged missing-feature failure in the Effect error channel.

Example

Effect.catchTag("ProviderFeatureMismatchError", (error) => Effect.logWarning(error.message));

Signature

declare class ProviderFeatureMismatchFailure

Source

ProviderProfileSelectionFailure (class)

Tagged profile failure in the Effect error channel.

Example

Effect.catchTag("ProviderProfileSelectionError", (error) => Effect.logWarning(error.message));

Signature

declare class ProviderProfileSelectionFailure

Source

ProviderValidationCode

Signature

declare const ProviderValidationCode: ProviderValidationCode;

Source

ProviderValidationError (class)

Tagged invalid provider input, with a stable category and safe message.

Example

Effect.catchTag("ProviderValidationError", (error) => Effect.logWarning(error.message));

Signature

declare class ProviderValidationError

Source

provider-errors.types.ts

Stable validation codes for provider authoring failures.

ProviderBindingResolutionCode (type alias)

Stable codes for connection resolution failures.

Signature

type ProviderBindingResolutionCode =
  "CONFLICTING_CONNECTION_VALUE" | "MISSING_CONNECTION_VALUE" | "UNKNOWN_CONNECTION_OUTPUT";

Source

ProviderValidationCode (type alias)

Stable validation codes for provider authoring failures.

Signature

type ProviderValidationCode =
  "INVALID_ID" | "INVALID_DESCRIPTOR" | "INVALID_CONNECTION" | "INVALID_PROFILE";

Source

provider-observability.ts

ProviderError

Signature

declare const ProviderError: ProviderError;

Source

ProviderOperation

Signature

declare const ProviderOperation: ProviderOperation;

Source

ProviderTelemetry (class)

Injectable telemetry for provider operations.

Example

Effect.provide(defineProviderCapabilityEffect("cache"), ProviderTelemetryLive);

Signature

declare class ProviderTelemetry

Source

ProviderTelemetryLive

Live spans and metrics for provider operations.

Example

Effect.runSync(Effect.provide(defineProviderCapabilityEffect("cache"), ProviderTelemetryLive));

Signature

declare const ProviderTelemetryLive: Layer.Layer<ProviderTelemetry, never, never>;

Source

ProviderTelemetryService

Signature

declare const ProviderTelemetryService: ProviderTelemetryService;

Source

observeProvider

Records a fixed provider operation with substitutable telemetry.

Example

observeProvider("capability.define", Effect.succeed("cache"));

Signature

declare const observeProvider: <A, E, R>(
  operation: ProviderOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;

Source

providerCalculation

Runs synchronous provider logic inside Effect and tags known validation failures.

Example

providerCalculation("INVALID_ID", () => "cache");

Signature

declare const providerCalculation: <A>(
  code: ProviderValidationError["code"],
  evaluate: () => A,
) => Effect.Effect<A, ProviderError>;

Source

runProvider

Runs a public synchronous compatibility adapter.

Throws

A TypeError for general validation, a named domain error, or an unexpected defect.

Example

runProvider(Effect.succeed("cache"));

Signature

declare const runProvider: <A, E>(effect: Effect.Effect<A, E>) => A;

Source

provider-observability.types.ts

Names provider operations and typed failures for substitutable instrumentation that preserves Effect result channels.

ProviderError (type alias)

Expected tagged failures from provider operations.

Signature

type ProviderError =
  | ProviderValidationError
  | ProviderProfileSelectionFailure
  | ProviderFeatureMismatchFailure
  | ProviderBindingResolutionFailure;

Source

ProviderOperation (type alias)

Fixed names for provider operations; never derived from user input.

Signature

type ProviderOperation =
  | "dependency.resolve"
  | "dependency.manager"
  | "dependency.check"
  | "dependency.initialize"
  | "binding-value.create"
  | "binding-value.is-ref"
  | "binding.resolve"
  | "binding.normalize"
  | "profile.normalize"
  | "profile.select"
  | "source.local"
  | "source.infrastructure"
  | "source.normalize"
  | "capability.define"
  | "feature.define"
  | "connection.define"
  | "behavior.define"
  | "access.define"
  | "integration.define"
  | "recipe.define"
  | "adapter.define";

Source

ProviderTelemetryService (interface)

Substitutable operation telemetry used by public Effect functions.

Signature

export interface ProviderTelemetryService {
  /** Observe an operation without changing its result or failure.
   * @param operation - Fixed operation name.
   * @param effect - Effect to observe.
   * @returns The same success and error channels.
   * @example telemetry.observe("capability.define", Effect.succeed("cache"));
   */
  readonly observe: <A, E, R>(
    operation: ProviderOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}

Source

runtime.types.ts

RuntimeProviderContext (interface)

Binding data passed to a runtime provider generation.

Signature

export interface RuntimeProviderContext {
  readonly generationId: string;
  readonly bindingId: string;
  readonly capability: string;
  readonly profile: string;
  readonly executionModel?: "task" | "legacy-function";
  readonly behavior: JsonValue;
  readonly connection: Readonly<Record<string, JsonValue>>;
  readonly signal?: AbortSignal;
}

Source

RuntimeProviderGeneration (interface)

Acquired runtime value and optional readiness and disposal hooks.

Signature

export interface RuntimeProviderGeneration {
  readonly value: unknown;
  readonly ready?: () => MaybePromise<void>;
  readonly readiness?: () => MaybePromise<void>;
  readonly release?: () => MaybePromise<void>;
  readonly dispose?: () => MaybePromise<void>;
}

Source

RuntimeProviderIntegration (interface)

Collection of runtime provider registrations owned by an integration.

Signature

export interface RuntimeProviderIntegration<IntegrationId extends string = string> {
  readonly kind: "runtime-integration";
  readonly integrationId: IntegrationId;
  readonly registrations: readonly RuntimeProviderRegistration[];
}

Source

RuntimeProviderRegistration (interface)

Registration factory for one runtime provider capability.

Signature

export interface RuntimeProviderRegistration extends RuntimeIntegrationRegistrationMetadata {
  readonly create: (context: RuntimeProviderContext) => MaybePromise<RuntimeProviderGeneration>;
}

Source

source-normalization.ts

defineInfrastructureProviderSource

Add an infrastructure source synchronously.

Throws

TypeError when the adapter is invalid or has no local recipe.

Example

defineInfrastructureProviderSource(adapter, integration, {});

Signature

declare const defineInfrastructureProviderSource: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
  integration: IntegrationReference,
  options: JsonValue,
  access?: ProviderAccess,
) => InfrastructureProviderSource<Adapter>;

Source

defineInfrastructureProviderSourceEffect

Add an infrastructure source in an Effect.

Example

Effect.runSync(defineInfrastructureProviderSourceEffect(adapter, integration, {}));

Signature

declare const defineInfrastructureProviderSourceEffect: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
  integration: IntegrationReference,
  options: JsonValue,
  access?: ProviderAccess,
) => Effect.Effect<InfrastructureProviderSource<Adapter>, ProviderError>;

Source

defineLocalProviderSource

Add an adapter’s local recipe for synchronous callers.

Throws

TypeError when the adapter is invalid or has no local recipe.

Example

defineLocalProviderSource(adapter);

Signature

declare const defineLocalProviderSource: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
) => LocalProviderSource<Adapter>;

Source

defineLocalProviderSourceEffect

Add an adapter’s local recipe without starting it.

Example

Effect.runSync(defineLocalProviderSourceEffect(adapter));

Signature

declare const defineLocalProviderSourceEffect: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
) => Effect.Effect<LocalProviderSource<Adapter>, ProviderError>;

Source

normalizeProviderSource

Normalize a provider source synchronously.

Throws

TypeError for invalid descriptors, nested wrappers, or missing values.

Example

normalizeProviderSource(adapter);

Signature

declare const normalizeProviderSource: <const Adapter extends ProviderAdapter>(
  input: ProviderSourceInput<Adapter>,
) => NormalizedProviderSource<Adapter>;

Source

normalizeProviderSourceCore

Pure normalization shared by observed source and profile operations.

Throws

TypeError for invalid descriptors or missing required values.

Example

normalizeProviderSourceCore(adapter);

Signature

declare const normalizeProviderSourceCore: <const Adapter extends ProviderAdapter>(
  input: ProviderSourceInput<Adapter>,
) => NormalizedProviderSource<Adapter>;

Source

normalizeProviderSourceEffect

Normalize any provider source in an Effect.

Example

Effect.runSync(normalizeProviderSourceEffect(adapter));

Signature

declare const normalizeProviderSourceEffect: <const Adapter extends ProviderAdapter>(
  input: ProviderSourceInput<Adapter>,
) => Effect.Effect<NormalizedProviderSource<Adapter>, ProviderError>;

Source

value-builders.ts

defineConnectionContract

Define connection fields synchronously.

Throws

TypeError for invalid or duplicate fields.

Example

defineConnectionContract({ url: { sensitive: true } });

Signature

declare const defineConnectionContract: (
  fields: Readonly<Record<string, ProviderConnectionFieldInput>>,
) => ProviderConnectionContract;

Source

defineConnectionContractEffect

Define connection fields in an Effect with deterministic key order.

Example

Effect.runSync(defineConnectionContractEffect({ url: { sensitive: true } }));

Signature

declare const defineConnectionContractEffect: (
  fields: Readonly<Record<string, ProviderConnectionFieldInput>>,
) => Effect.Effect<ProviderConnectionContract, ProviderError>;

Source

defineProviderAccess

Define immutable access metadata synchronously.

Throws

TypeError for invalid JSON.

Example

defineProviderAccess({ actions: ["cache:read"] });

Signature

declare const defineProviderAccess: <const Value extends JsonValue>(
  value: Value,
) => ProviderAccess<Value>;

Source

defineProviderAccessEffect

Define immutable access metadata in an Effect.

Example

Effect.runSync(defineProviderAccessEffect({ actions: ["cache:read"] }));

Signature

declare const defineProviderAccessEffect: <const Value extends JsonValue>(
  value: Value,
) => Effect.Effect<ProviderAccess<Value>, ProviderError>;

Source

defineProviderBehavior

Define immutable provider behavior synchronously.

Throws

TypeError for invalid JSON.

Example

defineProviderBehavior({ keyPrefix: "cart" });

Signature

declare const defineProviderBehavior: <const Value extends JsonValue>(
  value: Value,
) => ProviderBehavior<Value>;

Source

defineProviderBehaviorEffect

Define immutable provider behavior in an Effect.

Example

Effect.runSync(defineProviderBehaviorEffect({ keyPrefix: "cart" }));

Signature

declare const defineProviderBehaviorEffect: <const Value extends JsonValue>(
  value: Value,
) => Effect.Effect<ProviderBehavior<Value>, ProviderError>;

Source