Local API

Generated public TypeScript reference for @relkit/local.

Common APIs

• localEvent
• localJob

For configuration and examples, read integrations, local providers.

Public imports

• @relkit/local — 64 exports
• @relkit/local/runtime — 48 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.

index.ts

“./providers.js” (namespace export)

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

Signature

export * from "./providers.js";

Source

“@relkit/local-service” (namespace export)

Re-exports all named exports from the “@relkit/local-service” module.

Signature

export * from "@relkit/local-service";

Source

providers.ts

localEvent

Defines the durable filesystem event provider used by local development.

Example

import { localEvent } from "@relkit/local";
const events = localEvent();

Signature

declare const localEvent: (options?: LocalProviderOptions) => LocalEventAdapter;

Source

Since v0.4.0

localJob

Defines the durable filesystem queue provider for unscheduled local jobs.

Example

import { localJob } from "@relkit/local";
const jobs = localJob();

Signature

declare const localJob: (options?: LocalProviderOptions) => LocalJobAdapter;

Source

Since v0.4.0

LocalAgentStateAdapter (type alias)

Signature

type LocalAgentStateAdapter = ProviderAdapter<typeof agentState, "local-agent-state">;

Source

LocalEventAdapter (type alias)

Signature

type LocalEventAdapter = ProviderAdapter<typeof event, "local-event">;

Source

LocalJobAdapter (type alias)

Signature

type LocalJobAdapter = ProviderAdapter<typeof job, "local-job">;

Source

LocalProviderOptions (interface)

Signature

export interface LocalProviderOptions {
  readonly root?: string;
}

Source

LocalRealtimeAdapter (type alias)

Signature

type LocalRealtimeAdapter = ProviderAdapter<typeof realtime, "local-realtime">;

Source

localAgentState

Signature

declare const localAgentState: (options?: LocalProviderOptions) => LocalAgentStateAdapter;

Source

localRealtime

Signature

declare const localRealtime: (options?: LocalProviderOptions) => LocalRealtimeAdapter;

Source

identity.ts

LOCAL_RESOURCE_LABEL

Signature

declare const LOCAL_RESOURCE_LABEL: Readonly<{
  readonly managed: "dev.relkit.managed";
  readonly applicationId: "dev.relkit.application-id";
  readonly localProjectId: "dev.relkit.local-project-id";
  readonly bindingId: "dev.relkit.binding-id";
  readonly environment: "dev.relkit.environment";
  readonly serviceGeneration: "dev.relkit.service-generation";
  readonly unitId: "dev.relkit.unit-id";
  readonly unitKind: "dev.relkit.unit-kind";
  readonly recipeId: "dev.relkit.recipe-id";
  readonly planHash: "dev.relkit.plan-hash";
  readonly endpointHash: "dev.relkit.endpoint-hash";
}>;

Source

LocalProjectIdentity (interface)

Signature

export interface LocalProjectIdentity {
  readonly applicationId: string;
  readonly projectRoot: string;
  readonly localProjectId: string;
}

Source

createLocalProjectIdentity

Signature

declare const createLocalProjectIdentity: (
  requestedRoot: string,
  applicationId: string,
) => LocalProjectIdentity;

Source

localEndpointHash

Signature

declare const localEndpointHash: (
  endpoints: Readonly<Record<string, string>> | undefined,
) => string | undefined;

Source

localProjectLabels

Signature

declare const localProjectLabels: (
  identity: LocalProjectIdentity,
) => Readonly<Record<string, string>>;

Source

localResourceLabels

Signature

declare const localResourceLabels: (
  identity: LocalProjectIdentity,
  resource: LocalResourceIdentity,
) => Readonly<Record<string, string>>;

Source

localResourceName

Signature

declare const localResourceName: (
  identity: LocalProjectIdentity,
  bindingId: string,
  suffix?: string,
) => string;

Source

index.ts

“./identity.js” (namespace export)

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

Signature

export * from "./identity.js";

Source

“./integration.js” (namespace export)

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

Signature

export * from "./integration.js";

Source

“./lease.js” (namespace export)

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

Signature

export * from "./lease.js";

Source

“./local-secrets.js” (namespace export)

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

Signature

export * from "./local-secrets.js";

Source

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

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

Signature

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

Source

“./reconciler.js” (namespace export)

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

Signature

export * from "./reconciler.js";

Source

“./service-state.js” (namespace export)

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

Signature

export * from "./service-state.js";

Source

“./state-paths.js” (namespace export)

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

Signature

export * from "./state-paths.js";

Source

groupServiceInstances

Signature

declare const groupServiceInstances: (
  instances: readonly LocalServiceInstance[],
) => readonly LocalServiceInstance[];

Source

serviceInstanceIds

Signature

declare const serviceInstanceIds: (instance: LocalServiceInstance) => readonly string[];

Source

integration.ts

runtimeIntegration

Signature

declare const runtimeIntegration: RuntimeProviderIntegration<"local">;

Source

lease-files.ts

LeasePaths (interface)

Signature

export interface LeasePaths {
  readonly directory: string;
  readonly lock: string;
}

Source

ensureLeaseDirectory

Signature

declare const ensureLeaseDirectory: (identity: LocalProjectIdentity) => void;

Source

leasePaths

Signature

declare const leasePaths: (identity: LocalProjectIdentity) => LeasePaths;

Source

readLease

Signature

declare const readLease: (identity: LocalProjectIdentity) => LocalProjectLease | undefined;

Source

withLeaseLock

Signature

declare const withLeaseLock: <Value>(
  identity: LocalProjectIdentity,
  paths: LeasePaths,
  isProcessAlive: (pid: number) => boolean,
  operation: () => Value,
) => Value;

Source

writeLease

Signature

declare const writeLease: (identity: LocalProjectIdentity, lease: LocalProjectLease) => void;

Source

lease-types.ts

AcquireLocalProjectLeaseOptions (interface)

Signature

export interface AcquireLocalProjectLeaseOptions {
  readonly mode: LocalProjectLeaseMode;
  readonly sessionId: string;
  readonly pid?: number;
  readonly now?: () => Date;
  readonly isProcessAlive?: (pid: number) => boolean;
}

Source

LOCAL_PROJECT_LEASE_VERSION

Signature

declare const LOCAL_PROJECT_LEASE_VERSION: 1;

Source

LocalProjectLease (interface)

Signature

export interface LocalProjectLease {
  readonly version: typeof LOCAL_PROJECT_LEASE_VERSION;
  readonly localProjectId: string;
  readonly mode: LocalProjectLeaseMode;
  readonly sessionId: string;
  readonly generationId: string;
  readonly createdAt: string;
  readonly ownerPid?: number;
}

Source

LocalProjectLeaseError (class)

Signature

declare class LocalProjectLeaseError { constructor(
    readonly code: LocalProjectLeaseErrorCode,
    message: string,
    readonly owner?: LocalProjectLease,
  ) }

Source

LocalProjectLeaseErrorCode (type alias)

Signature

type LocalProjectLeaseErrorCode =
  "RELKIT_LOCAL_LEASE_HELD" | "RELKIT_LOCAL_LEASE_BUSY" | "RELKIT_LOCAL_LEASE_INVALID";

Source

LocalProjectLeaseHandle (interface)

Signature

export interface LocalProjectLeaseHandle {
  readonly lease: LocalProjectLease;
  readonly status: LocalProjectLeaseStatus;
  readonly release: () => void;
}

Source

LocalProjectLeaseMode (type alias)

Signature

type LocalProjectLeaseMode = "attached" | "detached";

Source

LocalProjectLeaseStatus (type alias)

Signature

type LocalProjectLeaseStatus = "acquired" | "adopted" | "recovered";

Source

lease.ts

“./lease-types.js” (namespace export)

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

Signature

export * from "./lease-types.js";

Source

acquireLocalProjectLease

Signature

declare const acquireLocalProjectLease: (
  identity: LocalProjectIdentity,
  options: AcquireLocalProjectLeaseOptions,
) => LocalProjectLeaseHandle;

Source

readLocalProjectLease

Signature

declare const readLocalProjectLease: (
  identity: LocalProjectIdentity,
) => LocalProjectLease | undefined;

Source

local-secrets.ts

LOCAL_SERVICE_SECRETS_FILE

Signature

declare const LOCAL_SERVICE_SECRETS_FILE: "local-secrets.json";

Source

LocalServiceSecretBinding (interface)

Signature

export interface LocalServiceSecretBinding {
  readonly bindingId: string;
  readonly recipe: Readonly<{
    readonly integrationId: string;
    readonly recipeId: string;
    readonly recipeVersion: number;
  }>;
  readonly values: Readonly<Record<string, string>>;
}

Source

LocalServiceSecretState (interface)

Signature

export interface LocalServiceSecretState {
  readonly version: typeof LOCAL_SERVICE_SECRETS_VERSION;
  readonly applicationId: string;
  readonly localProjectId: string;
  readonly bindings: readonly LocalServiceSecretBinding[];
}

Source

readLocalServiceSecrets

Signature

declare const readLocalServiceSecrets: (
  identity: LocalProjectIdentity,
) => LocalServiceSecretState | undefined;

Source

upsertLocalServiceSecrets

Signature

declare const upsertLocalServiceSecrets: (
  identity: LocalProjectIdentity,
  current: LocalServiceSecretState | undefined,
  bindingId: string,
  recipe: LocalServiceSecretBinding["recipe"],
  values: Readonly<Record<string, string>>,
) => LocalServiceSecretState;

Source

provider-overrides.ts

ProviderOverrideError (class)

Signature

declare class ProviderOverrideError { constructor(readonly code: "RELKIT_LOCAL_OVERRIDE_INVALID" | "RELKIT_LOCAL_OVERRIDE_STALE") }

Source

ProviderOverrideSummary (interface)

Signature

export interface ProviderOverrideSummary {
  readonly generationId: string;
  readonly planHash: string;
  readonly bindingIds: readonly string[];
}

Source

readProviderOverrides

Signature

declare const readProviderOverrides: (
  identity: LocalProjectIdentity,
  expectedPlanHash?: string,
) => ProviderOverrideState | undefined;

Source

removeProviderOverrides

Signature

declare const removeProviderOverrides: (identity: LocalProjectIdentity) => void;

Source

summarizeProviderOverrides

Signature

declare const summarizeProviderOverrides: (state: ProviderOverrideState) => ProviderOverrideSummary;

Source

writeProviderOverrides

Signature

declare const writeProviderOverrides: (
  identity: LocalProjectIdentity,
  planHash: string,
  bindings: readonly ProviderOverrideBinding[],
) => ProviderOverrideSummary;

Source

reconciler-environment.ts

environmentFile

Signature

declare const environmentFile: (
  recipe: LocalServiceRecipeInput,
  secrets: Readonly<Record<string, string>>,
) => string | undefined;

Source

environmentFiles

Signature

declare const environmentFiles: (
  recipe: LocalServiceRecipeInput,
  secrets: Readonly<Record<string, string>>,
) => Readonly<Record<string, string>>;

Source

reconciler-generation.ts

assertHotSwapSafe

Refuses an unsafe source-generation swap while an older service is owned.

Signature

declare const assertHotSwapSafe: (
  bindingId: string,
  instances: readonly LocalServiceInstance[],
  environment: string | undefined,
  serviceGeneration: string | undefined,
) => void;

Source

reconciler-lifecycle.ts

aborted

Signature

declare const aborted: (signal: AbortSignal | undefined) => void;

Source

frozenResult

Signature

declare const frozenResult: (
  overrides: ProviderOverrideSummary,
  state: LocalServiceState,
  reused: readonly string[],
  started: readonly string[],
  removed: readonly string[],
) => LocalServiceReconcileResult;

Source

startService

Signature

declare const startService: (
  options: LocalServiceReconcilerOptions,
  entry: LocalServicePlanEntry,
  recipe: LocalServiceRecipeInput,
  labels: Readonly<Record<string, string>>,
  secrets: Readonly<Record<string, string>>,
  signal?: AbortSignal,
  environmentVariables?: Readonly<Record<string, string>>,
  workerArtifact?: LocalServiceWorkerArtifact,
  environmentVariablesByUnit?: Readonly<Record<string, Readonly<Record<string, string>>>>,
  portBindings?: Readonly<Record<string, Readonly<Record<string, number>>>>,
) => Promise<LocalServiceInstance>;

Source

writeFailureState

Signature

declare const writeFailureState: (
  options: LocalServiceReconcilerOptions,
  request: LocalServiceReconcileRequest,
  active: LocalServicePlanEntry | undefined,
) => void;

Source

reconciler-operation-finalize.ts

finalizeReconcile

Signature

declare const finalizeReconcile: (
  options: LocalServiceReconcilerOptions,
  request: LocalServiceReconcileRequest,
  desired: readonly LocalServicePlanEntry[],
  previous: ProviderOverrideState | undefined,
  next: Map<string, TrackedService>,
  tracked: Map<string, TrackedService>,
  signatures: Map<string, string>,
  bindings: { bindingId: string; values: Readonly<Record<string, JsonValue>> }[],
  reused: string[],
  started: string[],
  removed: string[],
) => Promise<LocalServiceReconcileResult>;

Source

reconciler-operation-run.ts

runReconcileOperation

Signature

declare const runReconcileOperation: (
  options: LocalServiceReconcilerOptions,
  projectLabels: Readonly<Record<string, string>>,
  tracked: Map<string, TrackedService>,
  signatures: Map<string, string>,
  isClosed: () => boolean,
  request: LocalServiceReconcileRequest,
) => Promise<LocalServiceReconcileResult>;

Source

reconciler-operation-service.ts

ensureServiceInstance

Signature

declare const ensureServiceInstance: (
  options: LocalServiceReconcilerOptions,
  request: LocalServiceReconcileRequest,
  entry: LocalServicePlanEntry,
  recipe: LocalServiceRecipeInput,
  labels: Readonly<Record<string, string>>,
  secrets: Readonly<Record<string, string>>,
  candidates: readonly LocalServiceInstance[],
  existing: LocalServiceInstance | undefined,
  keepCandidates: boolean,
  startedIds: string[],
  started: string[],
  reused: string[],
  removed: string[],
) => Promise<LocalServiceInstance>;

Source

keepServiceCandidates

Signature

declare const keepServiceCandidates: (
  recipe: NormalizedLocalServiceRecipe,
  candidates: readonly LocalServiceInstance[],
  request: LocalServiceReconcileRequest,
  bindingId: string,
) => boolean;

Source

reconciler-operation.ts

TrackedService (interface)

Signature

export interface TrackedService {
  readonly instance: LocalServiceInstance;
  readonly signature: string;
  readonly secrets: Readonly<Record<string, string>>;
  readonly owned: boolean;
}

Source

createReconcileOperation

Signature

declare const createReconcileOperation: (
  options: LocalServiceReconcilerOptions,
  projectLabels: Readonly<Record<string, string>>,
  tracked: Map<string, TrackedService>,
  signatures: Map<string, string>,
  isClosed: () => boolean,
) => (request: LocalServiceReconcileRequest) => Promise<LocalServiceReconcileResult>;

Source

reconciler-queue.ts

ReconcileQueue (interface)

Signature

export interface ReconcileQueue {
  readonly enqueue: (request: LocalServiceReconcileRequest) => Promise<LocalServiceReconcileResult>;
  readonly wait: () => Promise<void>;
}

Source

createReconcileQueue

Signature

declare const createReconcileQueue: (
  reconcile: (request: LocalServiceReconcileRequest) => Promise<LocalServiceReconcileResult>,
) => ReconcileQueue;

Source

reconciler-resource.ts

removeInstance

Signature

declare const removeInstance: (
  options: LocalServiceReconcilerOptions,
  instance: LocalServiceInstance,
  signal?: AbortSignal,
) => Promise<void>;

Source

reconciler-support-validation.ts

completeUnits

Signature

declare const completeUnits: (
  instance: LocalServiceInstance,
  expectedUnitIds: readonly string[],
) => boolean;

Source

hash

Signature

declare const hash: (value: unknown) => value is string;

Source

invalid

Signature

declare const invalid: () => never;

Source

sameBindings

Signature

declare const sameBindings: (
  previous: ProviderOverrideState | undefined,
  planHash: string,
  bindings: readonly {
    readonly bindingId: string;
    readonly values: Readonly<Record<string, JsonValue>>;
  }[],
) => boolean;

Source

reconciler-support.ts

compatible

Signature

declare const compatible: (
  instance: LocalServiceInstance,
  expectedRecipe: string,
  planHash: string,
  priorSignature: string | undefined,
  signature: string,
  environment?: string,
  serviceGeneration?: string,
  expectedUnitIds?: readonly string[],
  endpointHash?: string,
) => boolean;

Source

createSecrets

Signature

declare const createSecrets: (recipe: LocalServiceRecipeInput) => Readonly<Record<string, string>>;

Source

desiredServices

Signature

declare const desiredServices: (
  request: LocalServiceReconcileRequest,
) => readonly LocalServicePlanEntry[];

Source

generatedSecrets

Signature

declare const generatedSecrets: (
  recipe: LocalServiceRecipeInput,
  previous: ProviderOverrideState | undefined,
  bindingId: string,
  retained?: Readonly<Record<string, string>>,
  persisted?: Readonly<Record<string, string>>,
) => Readonly<Record<string, string>> | undefined;

Source

groupServiceInstances

Signature

declare const groupServiceInstances: (
  instances: readonly LocalServiceInstance[],
) => readonly LocalServiceInstance[];

Source

outputPorts

Signature

declare const outputPorts: (
  recipe: LocalServiceRecipeInput,
  instance: LocalServiceInstance,
) => Readonly<Record<string, number>>;

Source

recipeFor

Signature

declare const recipeFor: (
  entry: LocalServicePlanEntry,
  recipes: Readonly<Record<string, LocalServiceRecipeInput>>,
  materializerId: string,
) => LocalServiceRecipeInput;

Source

sameBindings

Signature

declare const sameBindings: (
  previous: ProviderOverrideState | undefined,
  planHash: string,
  bindings: readonly {
    readonly bindingId: string;
    readonly values: Readonly<Record<string, JsonValue>>;
  }[],
) => boolean;

Source

serviceInstanceIds

Signature

declare const serviceInstanceIds: (instance: LocalServiceInstance) => readonly string[];

Source

serviceSignature

Signature

declare const serviceSignature: (entry: LocalServicePlanEntry) => string;

Source

reconciler-types.ts

LocalServiceRecipeMap (type alias)

Signature

type LocalServiceRecipeMap = Readonly<Record<string, LocalServiceRecipeInput>>;

Source

LocalServiceReconcileRequest (interface)

Signature

export interface LocalServiceReconcileRequest {
  readonly plan: LocalServicePlan;
  readonly planHash: string;
  readonly recipes: LocalServiceRecipeMap;
  readonly scope: "required" | "all";
  readonly environment?: string;
  readonly serviceGeneration?: string;
  readonly serviceGenerations?: Readonly<Record<string, string>>;
  readonly endpoints?: Readonly<Record<string, Readonly<Record<string, string>>>>;
  readonly environmentOverrides?: Readonly<Record<string, Readonly<Record<string, string>>>>;
  readonly environmentOverridesByUnit?: Readonly<
    Record<string, Readonly<Record<string, Readonly<Record<string, string>>>>>
  >;
  readonly workerArtifacts?: Readonly<Record<string, LocalServiceWorkerArtifact>>;
  readonly signal?: AbortSignal;
}

Source

LocalServiceReconcileResult (interface)

Signature

export interface LocalServiceReconcileResult {
  readonly overrides: ProviderOverrideSummary;
  readonly state: LocalServiceState;
  readonly reused: readonly string[];
  readonly started: readonly string[];
  readonly removed: readonly string[];
}

Source

LocalServiceReconciler (interface)

Signature

export interface LocalServiceReconciler {
  readonly reconcile: (
    request: LocalServiceReconcileRequest,
  ) => Promise<LocalServiceReconcileResult>;
  readonly close: () => Promise<void>;
}

Source

LocalServiceReconcilerOptions (interface)

Signature

export interface LocalServiceReconcilerOptions {
  readonly identity: LocalProjectIdentity;
  readonly materializer: LocalServiceMaterializerRuntime;
  readonly preserveOnClose?: boolean;
}

Source

reconciler-worker.ts

WorkerStartOptions (interface)

Signature

export interface WorkerStartOptions {
  readonly bindMounts?: Readonly<Record<string, readonly LocalServiceBindMount[]>>;
  readonly environmentVariablesByUnit?: Readonly<Record<string, Readonly<Record<string, string>>>>;
}

Source

workerStartOptions

Signature

declare const workerStartOptions: (
  recipe: NormalizedLocalServiceRecipe,
  artifact: LocalServiceWorkerArtifact | undefined,
) => WorkerStartOptions;

Source

reconciler.ts

“./reconciler-types.js” (namespace export)

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

Signature

export * from "./reconciler-types.js";

Source

createLocalServiceReconciler

Signature

declare const createLocalServiceReconciler: (
  options: LocalServiceReconcilerOptions,
) => LocalServiceReconciler;

Source

service-state.ts

readLocalServiceState

Signature

declare const readLocalServiceState: (
  identity: LocalProjectIdentity,
) => LocalServiceState | undefined;

Source

removeLocalServiceState

Signature

declare const removeLocalServiceState: (identity: LocalProjectIdentity) => void;

Source

writeLocalServiceState

Signature

declare const writeLocalServiceState: (
  identity: LocalProjectIdentity,
  planHash: string,
  services: readonly LocalServiceBindingState[],
) => LocalServiceState;

Source

state-paths.ts

LocalStateError (class)

Signature

declare class LocalStateError {
  constructor();
}

Source

code (property)

Signature

readonly code: "RELKIT_LOCAL_STATE_INVALID"

Source

LocalStateFileName (type alias)

Signature

type LocalStateFileName =
  | "lease.json"
  | "local-services.state.json"
  | "provider-overrides.json"
  | "worker-provider-overrides.json"
  | "local-secrets.json";

Source

ensureLocalStateDirectory

Signature

declare const ensureLocalStateDirectory: (identity: LocalProjectIdentity) => string;

Source

localStateDirectory

Signature

declare const localStateDirectory: (identity: LocalProjectIdentity) => string;

Source

readLocalStateText

Signature

declare const readLocalStateText: (
  identity: LocalProjectIdentity,
  name: LocalStateFileName,
) => string | undefined;

Source

removeLocalStateFile

Signature

declare const removeLocalStateFile: (
  identity: LocalProjectIdentity,
  name: LocalStateFileName,
) => void;

Source

withLocalStateTemporaryFile

Signature

declare const withLocalStateTemporaryFile: <Value>(
  identity: LocalProjectIdentity,
  value: string,
  operation: (path: string) => Promise<Value>,
) => Promise<Value>;

Source

writeLocalStateText

Signature

declare const writeLocalStateText: (
  identity: LocalProjectIdentity,
  name: LocalStateFileName,
  value: string,
) => void;

Source

local-service-errors.ts

LocalServiceValidationFailure (class)

Expected validation failure in a local-service Effect operation.

Example

Effect.catchTag("LocalServiceValidationFailure", ({ message }) => Effect.logWarning(message));

Signature

declare class LocalServiceValidationFailure

Source

LocalServiceVersionError (class)

Legacy synchronous error for a stale local-service artifact.

Example

throw new LocalServiceVersionError(
  "RELKIT_LOCAL_SERVICE_PLAN_VERSION_UNSUPPORTED",
  "Local-service plan",
  0,
  1,
  "relkit check",
);

Signature

declare class LocalServiceVersionError { constructor(
    readonly code: LocalServiceVersionErrorCode,
    label: string,
    version: unknown,
    expected: number,
    command: string,
  ) }

Source

LocalServiceVersionFailure (class)

Expected unsupported artifact version in a local-service Effect operation.

Example

Effect.catchTag("LocalServiceVersionFailure", ({ code }) => Effect.logWarning(code));

Signature

declare class LocalServiceVersionFailure

Source

local-service-observability.ts

LocalServiceTelemetry (class)

Substitutable telemetry service for local-service operations.

Example

Effect.provide(normalizeLocalServiceRecipeEffect(recipe), LocalServiceTelemetryLive);

Signature

declare class LocalServiceTelemetry

Source

LocalServiceTelemetryLive

Live operation spans and metrics.

Example

Effect.runSync(
  Effect.provide(normalizeLocalServiceRecipeEffect(recipe), LocalServiceTelemetryLive),
);

Signature

declare const LocalServiceTelemetryLive: Layer.Layer<LocalServiceTelemetry, never, never>;

Source

observeLocalService

Observe one public operation using an injected or live telemetry service.

Example

observeLocalService("recipe.normalize", Effect.succeed(recipe));

Signature

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

Source

runLocalService

Run a synchronous compatibility adapter and restore legacy errors.

Throws

TypeError or LocalServiceVersionError for expected failures; defects propagate.

Example

runLocalService(Effect.succeed("ready"));

Signature

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

Source

local-service-observability.types.ts

LocalServiceOperation (type alias)

Fixed operation names keep metric dimensions bounded.

Example

const operation: LocalServiceOperation = "recipe.normalize";

Signature

type LocalServiceOperation =
  | "recipe.normalize"
  | "plan.assert-version"
  | "state.assert-version"
  | "override.assert-version"
  | "override.binding-values";

Source

LocalServiceTelemetryService (interface)

Injectable tracing and metric behavior for public operations.

Example

const telemetry: LocalServiceTelemetryService = { observe: (_operation, effect) => effect };

Signature

export interface LocalServiceTelemetryService {
  /** Observe an operation without changing its result.
   * @param operation - Fixed operation name.
   * @param effect - Operation to measure.
   * @returns The original Effect success and failure channels.
   * @example telemetry.observe("recipe.normalize", Effect.succeed(recipe));
   */
  readonly observe: <A, E, R>(
    operation: LocalServiceOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}

Source

protocol-version.ts

assertLocalServicePlanVersion

Assert a local-service plan version synchronously.

Throws

LocalServiceVersionError when the version differs.

Example

assertLocalServicePlanVersion({ version: 1 });

Signature

declare const assertLocalServicePlanVersion: (value: unknown) => asserts value is LocalServicePlan;

Source

assertLocalServicePlanVersionEffect

Check a local-service plan version in the Effect error channel.

Example

Effect.runSync(assertLocalServicePlanVersionEffect({ version: 1 }));

Signature

declare const assertLocalServicePlanVersionEffect: (
  value: unknown,
) => Effect.Effect<void, LocalServiceVersionFailure, never>;

Source

assertLocalServiceStateVersion

Assert a local-service state version synchronously.

Throws

LocalServiceVersionError when the version differs.

Example

assertLocalServiceStateVersion({ version: 1 });

Signature

declare const assertLocalServiceStateVersion: (
  value: unknown,
) => asserts value is LocalServiceState;

Source

assertLocalServiceStateVersionEffect

Check a local-service state version in the Effect error channel.

Example

Effect.runSync(assertLocalServiceStateVersionEffect({ version: 1 }));

Signature

declare const assertLocalServiceStateVersionEffect: (
  value: unknown,
) => Effect.Effect<void, LocalServiceVersionFailure, never>;

Source

assertProviderOverrideStateVersion

Assert a provider override version synchronously.

Throws

LocalServiceVersionError when the version differs.

Example

assertProviderOverrideStateVersion({ version: 1 });

Signature

declare const assertProviderOverrideStateVersion: (
  value: unknown,
) => asserts value is ProviderOverrideState;

Source

assertProviderOverrideStateVersionEffect

Check an override artifact version in the Effect error channel.

Example

Effect.runSync(assertProviderOverrideStateVersionEffect({ version: 1 }));

Signature

declare const assertProviderOverrideStateVersionEffect: (
  value: unknown,
) => Effect.Effect<void, LocalServiceVersionFailure, never>;

Source

checkVersionEffect

Check one artifact version without starting a separate public operation span.

Example

Effect.runSync(
  checkVersionEffect(
    { version: 1 },
    1,
    "Local-service plan",
    "RELKIT_LOCAL_SERVICE_PLAN_VERSION_UNSUPPORTED",
    "relkit check",
  ),
);

Signature

declare const checkVersionEffect: (
  value: unknown,
  expected: number,
  label: string,
  code: LocalServiceVersionErrorCode,
  command: string,
) => Effect.Effect<undefined, LocalServiceVersionFailure, never>;

Source

protocol.ts

Version and artifact names for the local-service protocol.

LOCAL_SERVICE_PLAN_FILE

Signature

declare const LOCAL_SERVICE_PLAN_FILE: "local-services.plan.json";

Source

LOCAL_SERVICE_PLAN_VERSION

Signature

declare const LOCAL_SERVICE_PLAN_VERSION: 1;

Source

LOCAL_SERVICE_PROTOCOL_VERSION

Version and artifact names for the local-service protocol.

Signature

declare const LOCAL_SERVICE_PROTOCOL_VERSION: 1;

Source

LOCAL_SERVICE_STATE_FILE

Signature

declare const LOCAL_SERVICE_STATE_FILE: "local-services.state.json";

Source

LOCAL_SERVICE_STATE_VERSION

Signature

declare const LOCAL_SERVICE_STATE_VERSION: 1;

Source

PROVIDER_OVERRIDE_STATE_FILE

Signature

declare const PROVIDER_OVERRIDE_STATE_FILE: "provider-overrides.json";

Source

PROVIDER_OVERRIDE_STATE_VERSION

Signature

declare const PROVIDER_OVERRIDE_STATE_VERSION: 1;

Source

protocol.types.ts

LocalServiceBindingState (interface)

Observed state of one local binding.

Example

const phase: LocalServicePhase = binding.phase;

Signature

export interface LocalServiceBindingState {
  readonly bindingId: string;
  readonly recipe: ProviderLocalRecipeReference;
  readonly phase: LocalServicePhase;
  readonly environment?: string;
  readonly serviceGeneration?: string;
  readonly units?: readonly string[];
  readonly message?: string;
}

Source

LocalServiceMaterializerMetadata (interface)

Identity of a local materializer integration.

Example

const metadata: LocalServiceMaterializerMetadata = {
  kind: "local-service-materializer",
  protocolVersion: 1,
  integrationId: "docker",
};

Signature

export interface LocalServiceMaterializerMetadata<IntegrationId extends string = string> {
  readonly kind: "local-service-materializer";
  readonly protocolVersion: typeof LOCAL_SERVICE_PROTOCOL_VERSION;
  readonly integrationId: IntegrationId;
}

Source

LocalServicePhase (type alias)

Runtime lifecycle phase for one local binding.

Example

const phase: LocalServicePhase = "healthy";

Signature

type LocalServicePhase = "pending" | "starting" | "healthy" | "unhealthy" | "stopped";

Source

LocalServicePlan (interface)

Versioned local service plan.

Example

const entries: readonly LocalServicePlanEntry[] = plan.services;

Signature

export interface LocalServicePlan {
  readonly version: typeof LOCAL_SERVICE_PLAN_VERSION;
  readonly graphHash: string;
  readonly services: readonly LocalServicePlanEntry[];
}

Source

LocalServicePlanEntry (interface)

Planned local binding and its provider recipe.

Example

const entry = plan.services[0] as LocalServicePlanEntry;

Signature

export interface LocalServicePlanEntry {
  readonly bindingId: string;
  readonly capability: string;
  readonly profile: string;
  readonly materializerId: string;
  readonly recipe: ProviderLocalRecipeReference;
  readonly configuration: JsonValue;
  readonly requiredBy: readonly string[];
}

Source

LocalServiceState (interface)

Versioned state for all local bindings.

Example

const bindings: readonly LocalServiceBindingState[] = state.services;

Signature

export interface LocalServiceState {
  readonly version: typeof LOCAL_SERVICE_STATE_VERSION;
  readonly applicationId: string;
  readonly localProjectId: string;
  readonly planHash: string;
  readonly services: readonly LocalServiceBindingState[];
}

Source

LocalServiceVersionErrorCode (type alias)

Stable error codes for unsupported artifact versions.

Example

const code: LocalServiceVersionErrorCode = "RELKIT_LOCAL_SERVICE_PLAN_VERSION_UNSUPPORTED";

Signature

type LocalServiceVersionErrorCode =
  | "RELKIT_LOCAL_SERVICE_PLAN_VERSION_UNSUPPORTED"
  | "RELKIT_LOCAL_SERVICE_STATE_VERSION_UNSUPPORTED"
  | "RELKIT_PROVIDER_OVERRIDE_STATE_VERSION_UNSUPPORTED";

Source

ProviderOverrideBinding (interface)

Resolved override values for one provider binding.

Example

const url = binding.values.url;

Signature

export interface ProviderOverrideBinding {
  readonly bindingId: string;
  readonly values: Readonly<Record<string, JsonValue>>;
}

Source

ProviderOverrideExpectation (interface)

Expected activation identity for provider override lookup.

Example

const expected: ProviderOverrideExpectation = {
  applicationId: "demo",
  planHash,
  generationId: "generation-1",
};

Signature

export interface ProviderOverrideExpectation {
  readonly applicationId: string;
  readonly planHash: string;
  readonly generationId: string;
}

Source

ProviderOverrideState (interface)

Versioned override state bound to one activation.

Example

const bindings: readonly ProviderOverrideBinding[] = overrides.bindings;

Signature

export interface ProviderOverrideState {
  readonly version: typeof PROVIDER_OVERRIDE_STATE_VERSION;
  readonly applicationId: string;
  readonly localProjectId: string;
  readonly planHash: string;
  readonly generationId: string;
  readonly bindings: readonly ProviderOverrideBinding[];
}

Source

provider-overrides.ts

providerOverrideBindingValues

Resolve provider overrides synchronously for existing callers.

Throws

LocalServiceVersionError or TypeError for an invalid artifact.

Example

providerOverrideBindingValues(artifact, expected);

Signature

declare const providerOverrideBindingValues: (
  value: unknown,
  expected: ProviderOverrideExpectation,
) => Readonly<Record<string, Readonly<Record<string, JsonValue>>>>;

Source

providerOverrideBindingValuesEffect

Resolve only the overrides belonging to one activation.

Example

Effect.runSync(providerOverrideBindingValuesEffect(artifact, expected));

Signature

declare const providerOverrideBindingValuesEffect: (
  value: unknown,
  expected: ProviderOverrideExpectation,
) => Effect.Effect<
  Record<string, Readonly<Record<string, JsonValue>>>,
  LocalServiceVersionFailure | LocalServiceValidationFailure,
  never
>;

Source

recipe-normalize.ts

NormalizedLocalServiceRecipe

Signature

declare const NormalizedLocalServiceRecipe: NormalizedLocalServiceRecipe;

Source

NormalizedLocalServiceUnit

Signature

declare const NormalizedLocalServiceUnit: NormalizedLocalServiceUnit;

Source

normalizeLocalServiceRecipe

Normalize a recipe synchronously for existing callers.

Throws

TypeError when a recipe field or dependency is invalid.

Example

normalizeLocalServiceRecipe(recipe);

Signature

declare const normalizeLocalServiceRecipe: (
  recipe: LocalServiceRecipeInput,
) => NormalizedLocalServiceRecipe;

Source

normalizeLocalServiceRecipeEffect

Normalize a supported recipe in the Effect error channel.

Example

Effect.runSync(normalizeLocalServiceRecipeEffect(recipe));

Signature

declare const normalizeLocalServiceRecipeEffect: (recipe: LocalServiceRecipeInput) => Effect.Effect<
  | Readonly<{
      initialize?: (context: LocalServiceRecipeOutputContext) => Promise<void>;
      kind: "local-service-recipe";
      protocolVersion: 1;
      integrationId: string;
      recipeId: string;
      recipeVersion: 1;
      materializerId: "docker";
      units: ReadonlyArray<NormalizedLocalServiceUnit>;
      volumes: Readonly<{ data?: never } | { data: { mountPath: string } }>;
      generatedSecrets: Readonly<{ [x: string]: LocalServiceGeneratedSecret }>;
      environment: Readonly<{ [x: string]: LocalServiceSecretEnvironment }>;
      ownership: Readonly<{ scope: "binding"; retainVolumes: true }>;
      outputs: (context: LocalServiceRecipeOutputContext) => Readonly<Record<string, JsonValue>>;
    }>
  | Readonly<{
      initialize?: (context: LocalServiceRecipeOutputContext) => Promise<void>;
      ownership: Readonly<{ scope: "binding" | "project"; retainVolumes: boolean }>;
      outputs: (context: LocalServiceRecipeOutputContext) => Readonly<Record<string, JsonValue>>;
      network?: Readonly<{ readonly internal?: boolean }>;
      kind: "local-service-recipe";
      protocolVersion: 2;
      integrationId: string;
      recipeId: string;
      recipeVersion: 2;
      materializerId: "docker";
      units: ReadonlyArray<NormalizedLocalServiceUnit>;
      volumes: Readonly<{ [x: string]: CompositeLocalServiceVolume }>;
      generatedSecrets: Readonly<{ [x: string]: LocalServiceGeneratedSecret }>;
      environment: Readonly<{
        [x: string]: LocalServiceSecretEnvironment | LocalServiceLiteralEnvironment;
      }>;
    }>,
  LocalServiceValidationFailure,
  never
>;

Source

recipe-normalize.types.ts

NormalizedLocalServiceRecipe (interface)

Canonical recipe used by local materializers. Units are ordered by dependency and ID and the root collections are frozen.

Example

const normalized: NormalizedLocalServiceRecipe = normalizeLocalServiceRecipe(recipe);

Signature

export interface NormalizedLocalServiceRecipe {
  readonly kind: "local-service-recipe";
  readonly protocolVersion: 1 | typeof LOCAL_SERVICE_RECIPE_PROTOCOL_VERSION;
  readonly integrationId: string;
  readonly recipeId: string;
  readonly recipeVersion: number;
  readonly materializerId: "docker";
  readonly units: readonly NormalizedLocalServiceUnit[];
  readonly volumes: Readonly<Record<string, CompositeLocalServiceVolume>>;
  readonly generatedSecrets: Readonly<Record<string, LocalServiceGeneratedSecret>>;
  readonly environment: Readonly<
    Record<string, LocalServiceSecretEnvironment | LocalServiceLiteralEnvironment>
  >;
  readonly network?: Readonly<{ readonly internal?: boolean }>;
  readonly ownership: Readonly<{
    readonly scope: "project" | "binding";
    readonly retainVolumes: boolean;
  }>;
  readonly outputs: (
    context: LocalServiceRecipeOutputContext,
  ) => Readonly<Record<string, JsonValue>>;
  readonly initialize?: (context: LocalServiceRecipeOutputContext) => Promise<void>;
}

Source

NormalizedLocalServiceUnit (interface)

Validated unit with required frozen collections.

Example

const ids = recipe.units.map((unit: NormalizedLocalServiceUnit) => unit.id);

Signature

export interface NormalizedLocalServiceUnit extends CompositeLocalServiceUnit {
  readonly dependsOn: readonly string[];
  readonly ports: Readonly<Record<string, number>>;
  readonly volumes: readonly { readonly name: string; readonly mountPath: string }[];
  readonly health?: LocalServiceHealthCheck;
}

Source

recipe-runtime.types.ts

LocalServiceInstance (interface)

Observed materializer instance, possibly containing child units.

Example

const healthy = instance.health === "healthy";

Signature

export interface LocalServiceInstance {
  readonly id: string;
  readonly name: string;
  readonly labels: Readonly<Record<string, string>>;
  readonly state: string;
  readonly health?: "starting" | "healthy" | "unhealthy";
  readonly ports: Readonly<Record<string, number>>;
  readonly unitId?: string;
  readonly units?: readonly LocalServiceInstance[];
  readonly networkName?: string;
  readonly environment?: string;
  readonly serviceGeneration?: string;
}

Source

LocalServiceMaterializerRuntime (interface)

External materializer operations that own local containers and volumes. Implementations must release their acquired resources through stop, remove, and removeVolumes.

Example

const services = await materializer.list({ application: "demo" });

Signature

export interface LocalServiceMaterializerRuntime {
  readonly kind: "local-service-materializer-runtime";
  readonly protocolVersion: typeof LOCAL_SERVICE_PROTOCOL_VERSION;
  readonly integrationId: string;
  /** List matching services.
   * @param labels - Bounded identity labels used for lookup.
   * @param signal - Optional cancellation signal.
   * @returns Matching instances or a rejected provider promise.
   * @example await materializer.list({ application: "demo" });
   */
  readonly list: (
    labels: Readonly<Record<string, string>>,
    signal?: AbortSignal,
  ) => Promise<readonly LocalServiceInstance[]>;
  /** Start one requested service and return its live instance.
   * @param request - Recipe and runtime bindings.
   * @returns A live instance or a rejected provider promise.
   * @example await materializer.start(request);
   */
  readonly start: (request: LocalServiceStartRequest) => Promise<LocalServiceInstance>;
  /** Stop a live service without deleting it.
   * @param id - Materializer instance ID.
   * @param signal - Optional cancellation signal.
   * @returns Completion or a rejected provider promise.
   * @example await materializer.stop?.(instance.id);
   */
  readonly stop?: (id: string, signal?: AbortSignal) => Promise<void>;
  /** Remove a stopped service.
   * @param id - Materializer instance ID.
   * @param signal - Optional cancellation signal.
   * @returns Completion or a rejected provider promise.
   * @example await materializer.remove(instance.id);
   */
  readonly remove: (id: string, signal?: AbortSignal) => Promise<void>;
  /** Remove volumes owned by matching services.
   * @param labels - Ownership labels.
   * @param signal - Optional cancellation signal.
   * @returns Completion or a rejected provider promise.
   * @example await materializer.removeVolumes({ application: "demo" });
   */
  readonly removeVolumes: (
    labels: Readonly<Record<string, string>>,
    signal?: AbortSignal,
  ) => Promise<void>;
  /** List matching volumes when the materializer supports it.
   * @param labels - Ownership labels.
   * @param signal - Optional cancellation signal.
   * @returns Named volumes or a rejected provider promise.
   * @example await materializer.listVolumes?.({ application: "demo" });
   */
  readonly listVolumes?: (
    labels: Readonly<Record<string, string>>,
    signal?: AbortSignal,
  ) => Promise<
    readonly { readonly name: string; readonly labels: Readonly<Record<string, string>> }[]
  >;
  /** Remove networks owned by matching services.
   * @param labels - Ownership labels.
   * @param signal - Optional cancellation signal.
   * @returns Completion or a rejected provider promise.
   * @example await materializer.removeNetworks?.({ application: "demo" });
   */
  readonly removeNetworks?: (
    labels: Readonly<Record<string, string>>,
    signal?: AbortSignal,
  ) => Promise<void>;
}

Source

LocalServiceStartRequest (interface)

Parameters for starting one materialized local service. The caller owns cancellation through signal and materializer cleanup after start.

Example

await materializer.start(request);

Signature

export interface LocalServiceStartRequest {
  readonly name: string;
  readonly volumeName?: string;
  readonly labels: Readonly<Record<string, string>>;
  readonly recipe: LocalServiceRecipeInput;
  readonly environmentFile?: string;
  readonly environmentFiles?: Readonly<Record<string, string>>;
  readonly environmentVariables?: Readonly<Record<string, string>>;
  readonly volumeNames?: Readonly<Record<string, string>>;
  readonly networkName?: string;
  readonly serviceGeneration?: string;
  readonly workerArtifact?: LocalServiceWorkerArtifact;
  readonly bindMounts?: Readonly<Record<string, readonly LocalServiceBindMount[]>>;
  readonly environmentVariablesByUnit?: Readonly<Record<string, Readonly<Record<string, string>>>>;
  readonly portBindings?: Readonly<Record<string, Readonly<Record<string, number>>>>;
  readonly signal?: AbortSignal;
}

Source

recipe.ts

Version used by composite recipes; single-container recipes remain on v1.

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

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

Signature

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

Source