Local providers API
Generated public TypeScript reference for @relkit/providers-local.
For configuration and examples, read local providers.
Public imports
@relkit/providers-local— 217 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.
provider.ts
Composes filesystem-backed agent-state operations and their Promise compatibility boundary.
LocalAgentStateProviderOptions
Signature
declare const LocalAgentStateProviderOptions: LocalAgentStateProviderOptions;LocalAgentStateService (class)
Local agent state operations with substitutable transactional storage.
Signature
declare class LocalAgentStateServiceagentStateLayer
Builds the live agent-state layer without starting background work.
Example
import { Effect } from "effect";
import { LocalAgentStateService, agentStateLayer } from "./provider.js";
const program = Effect.gen(function* () {
const agents = yield* LocalAgentStateService;
return yield* agents.getEpoch();
});
await Effect.runPromise(program.pipe(Effect.provide(agentStateLayer("/tmp/example-agents"))));Signature
declare const agentStateLayer: (
root: string,
pollingMs?: number,
) => Layer.Layer<LocalAgentStateService, LocalOperationError, never>;createAgentStateProviderFromStore
Substitutes storage while preserving the same public agent-state operations.
Signature
declare const createAgentStateProviderFromStore: (
store: ReturnType<typeof createAgentStateStore>,
pollingMs?: number,
) => AgentStateProvider;createLocalAgentStateProvider
Creates the filesystem-backed agent-state compatibility provider.
Signature
declare const createLocalAgentStateProvider: (
root: string,
options?: LocalAgentStateProviderOptions,
) => AgentStateProvider;makeAgentStateService
Composes agent operations over a replaceable state store.
Signature
declare const makeAgentStateService: (
store: AgentStateStoreEffects,
pollingMs?: number,
) => AgentStateEffects;provider.types.ts
Defines the Effect operation contract and bounded polling options for local agent state.
AgentStateEffects (type alias)
Effect counterpart of the established public agent-state provider methods.
Signature
type AgentStateEffects = {
readonly [K in keyof AgentStateProvider]: AgentStateProvider[K] extends (
...args: infer A
) => infer R
? (...args: A) => Effect.Effect<Awaited<R>, LocalOperationError>
: AgentStateProvider[K];
};LocalAgentStateProviderOptions (interface)
Polling policy for observing updates from other agent-state processes.
Signature
export interface LocalAgentStateProviderOptions {
readonly pollingMs?: number;
}state.ts
LOCAL_AGENT_STATE_VERSION
Signature
declare const LOCAL_AGENT_STATE_VERSION: 1;LocalAgentState
Signature
declare const LocalAgentState: {
readonly version: 1;
readonly providerEpoch: string;
readonly revision: number;
readonly threads: {
readonly [x: string]: {
readonly thread: {
readonly threadId: string;
readonly agentId: string;
readonly ownerScope: string;
readonly status:
| "idle"
| "running"
| "waiting"
| "approval-interrupted"
| "stopping"
| "worker-interrupted";
readonly revision: string;
readonly createdAt: string;
readonly updatedAt: string;
};
readonly runs: {
readonly [x: string]: {
readonly status:
| "running"
| "waiting"
| "approval-interrupted"
| "stopping"
| "worker-interrupted"
| "accepted"
| "succeeded"
| "failed"
| "cancelled";
readonly threadId: string;
readonly runId: string;
readonly owner: {
readonly generationId: string;
readonly publicFingerprint: string;
readonly protocolVersion: number;
readonly schemaVersion: number;
readonly providerScope: string;
};
readonly operationId: OperationId;
readonly inputDigest: string;
readonly acceptedAt: string;
readonly maxJournalBytes: number;
readonly maxJournalRecordBytes: number;
readonly terminalReserveBytes: number;
readonly settledAt?: string;
readonly outcome?: "worker-interrupted" | "succeeded" | "failed" | "cancelled";
};
};
readonly messages: ReadonlyArray<{
readonly createdAt: string;
readonly role: "user" | "assistant" | "tool";
readonly parts: ReadonlyArray<
| {
readonly kind: "text";
readonly text: string;
readonly partId: string;
readonly state?: "streaming" | "complete";
}
| {
readonly kind: "tool";
readonly state:
| "running"
| "succeeded"
| "failed"
| "started"
| "input-streaming"
| "input-ready"
| "approval-required"
| "denied";
readonly partId: string;
readonly toolCallId: string;
readonly toolId: string;
readonly inputText?: string;
readonly input?: unknown;
readonly output?: unknown;
readonly value?: unknown;
}
| {
readonly partId: string;
readonly kind: "progress";
readonly value: unknown;
readonly scope: "run";
}
| {
readonly partId: string;
readonly kind: "progress";
readonly value: unknown;
readonly scope: "tool";
readonly toolCallId: string;
readonly toolId: string;
}
>;
readonly messageId: string;
readonly runId?: string;
}>;
readonly approvals: ReadonlyArray<{
readonly status: "cancelled" | "denied" | "open" | "approved";
readonly runId: string;
readonly approvalId: string;
readonly interruptSetDigest: string;
readonly publicRequest: unknown;
readonly interruptSetSize?: number;
}>;
readonly journal: ReadonlyArray<{
readonly recordId: string;
readonly runId: string;
readonly kind:
"progress" | "message" | "approval" | "control" | "terminal" | "interruption" | "event";
readonly publicValue: unknown;
readonly checkpoint: {
readonly applicationId: string;
readonly environment: string;
readonly profile: string;
readonly providerEpoch: string;
readonly threadId: string;
readonly sequence: string;
};
readonly encodedBytes: number;
readonly createdAt: string;
}>;
readonly sequence: number;
readonly controls: {
readonly [x: string]: {
readonly sequence: number;
readonly record: {
readonly status: "accepted" | "cancelled" | "processing" | "applied" | "rejected";
readonly runId: string;
readonly acceptedAt: string;
readonly kind: "steer" | "follow-up" | "stop" | "approve";
readonly controlId: OperationId;
readonly semanticDigest: string;
readonly effect: "not-started" | "confirmed" | "unknown";
readonly settledAt?: string;
readonly publicPayload?: unknown;
};
readonly publicPayload: unknown;
readonly semanticDigest: string;
readonly receipt: {
readonly operationId: OperationId;
readonly threadId: string;
readonly runId: string;
readonly status: "accepted" | "cancelled" | "processing" | "applied" | "rejected";
readonly effect: "not-started" | "confirmed" | "unknown";
readonly duplicate: boolean;
};
readonly expiresAt: string;
readonly downstreamOperationId?: string;
};
};
readonly runClaims: {
readonly [x: string]: {
readonly runId: string;
readonly claimId: string;
readonly workerId: string;
readonly generationId: string;
readonly fence: number;
readonly expiresAt: string;
};
};
readonly controlClaims: {
readonly [x: string]: {
readonly controlId: OperationId;
readonly claimId: string;
readonly workerId: string;
readonly generationId: string;
readonly fence: number;
readonly expiresAt: string;
};
};
readonly scopeKey: string;
readonly controlSequence: number;
readonly nextFence: number;
readonly waiting?: {
readonly revision: string;
readonly runId: string;
readonly response: Json;
readonly requests: ReadonlyArray<{
readonly node: string;
readonly response: Json;
readonly value?: unknown;
}>;
};
readonly activeRunId?: string;
readonly snapshots?: {
readonly [x: string]: {
readonly createdAt: string;
readonly messages: ReadonlyArray<{
readonly createdAt: string;
readonly role: "user" | "assistant" | "tool";
readonly parts: ReadonlyArray<
| {
readonly kind: "text";
readonly text: string;
readonly partId: string;
readonly state?: "streaming" | "complete";
}
| {
readonly kind: "tool";
readonly state:
| "running"
| "succeeded"
| "failed"
| "started"
| "input-streaming"
| "input-ready"
| "approval-required"
| "denied";
readonly partId: string;
readonly toolCallId: string;
readonly toolId: string;
readonly inputText?: string;
readonly input?: unknown;
readonly output?: unknown;
readonly value?: unknown;
}
| {
readonly partId: string;
readonly kind: "progress";
readonly value: unknown;
readonly scope: "run";
}
| {
readonly partId: string;
readonly kind: "progress";
readonly value: unknown;
readonly scope: "tool";
readonly toolCallId: string;
readonly toolId: string;
}
>;
readonly messageId: string;
readonly runId?: string;
}>;
};
};
};
};
readonly createReceipts: {
readonly [x: string]: { readonly digest: string; readonly threadId: string };
};
readonly runReceipts: {
readonly [x: string]: {
readonly semanticDigest: string;
readonly expiresAt: string;
readonly value:
| {
readonly operationId: OperationId;
readonly threadId: string;
readonly runId: string;
readonly status: "accepted";
readonly duplicate: boolean;
}
| {
readonly operationId: OperationId;
readonly threadId: string;
readonly runId: string;
readonly status: "succeeded" | "failed" | "cancelled";
readonly checkpoint: {
readonly applicationId: string;
readonly environment: string;
readonly profile: string;
readonly providerEpoch: string;
readonly threadId: string;
readonly sequence: string;
};
readonly duplicate: boolean;
};
};
};
readonly controlReceipts: {
readonly [x: string]: {
readonly semanticDigest: string;
readonly expiresAt: string;
readonly value: {
readonly operationId: OperationId;
readonly threadId: string;
readonly runId: string;
readonly status: "accepted" | "cancelled" | "processing" | "applied" | "rejected";
readonly effect: "not-started" | "confirmed" | "unknown";
readonly duplicate: boolean;
};
};
};
readonly continuationReceipts: {
readonly [x: string]: {
readonly semanticDigest: string;
readonly expiresAt: string;
readonly value: {
readonly threadId: string;
readonly runId: string;
readonly operationId: OperationId;
readonly interruptSetDigest: string;
readonly duplicate: boolean;
readonly interruptedRunId: string;
readonly waitingRevision?: string;
};
};
};
};LocalAgentThread
Signature
declare const LocalAgentThread: {
readonly thread: {
readonly threadId: string;
readonly agentId: string;
readonly ownerScope: string;
readonly status:
"idle" | "running" | "waiting" | "approval-interrupted" | "stopping" | "worker-interrupted";
readonly revision: string;
readonly createdAt: string;
readonly updatedAt: string;
};
readonly runs: {
readonly [x: string]: {
readonly status:
| "running"
| "waiting"
| "approval-interrupted"
| "stopping"
| "worker-interrupted"
| "accepted"
| "succeeded"
| "failed"
| "cancelled";
readonly threadId: string;
readonly runId: string;
readonly owner: {
readonly generationId: string;
readonly publicFingerprint: string;
readonly protocolVersion: number;
readonly schemaVersion: number;
readonly providerScope: string;
};
readonly operationId: OperationId;
readonly inputDigest: string;
readonly acceptedAt: string;
readonly maxJournalBytes: number;
readonly maxJournalRecordBytes: number;
readonly terminalReserveBytes: number;
readonly settledAt?: string;
readonly outcome?: "worker-interrupted" | "succeeded" | "failed" | "cancelled";
};
};
readonly messages: ReadonlyArray<{
readonly createdAt: string;
readonly role: "user" | "assistant" | "tool";
readonly parts: ReadonlyArray<
| {
readonly kind: "text";
readonly text: string;
readonly partId: string;
readonly state?: "streaming" | "complete";
}
| {
readonly kind: "tool";
readonly state:
| "running"
| "succeeded"
| "failed"
| "started"
| "input-streaming"
| "input-ready"
| "approval-required"
| "denied";
readonly partId: string;
readonly toolCallId: string;
readonly toolId: string;
readonly inputText?: string;
readonly input?: unknown;
readonly output?: unknown;
readonly value?: unknown;
}
| {
readonly partId: string;
readonly kind: "progress";
readonly value: unknown;
readonly scope: "run";
}
| {
readonly partId: string;
readonly kind: "progress";
readonly value: unknown;
readonly scope: "tool";
readonly toolCallId: string;
readonly toolId: string;
}
>;
readonly messageId: string;
readonly runId?: string;
}>;
readonly approvals: ReadonlyArray<{
readonly status: "cancelled" | "denied" | "open" | "approved";
readonly runId: string;
readonly approvalId: string;
readonly interruptSetDigest: string;
readonly publicRequest: unknown;
readonly interruptSetSize?: number;
}>;
readonly journal: ReadonlyArray<{
readonly recordId: string;
readonly runId: string;
readonly kind:
"progress" | "message" | "approval" | "control" | "terminal" | "interruption" | "event";
readonly publicValue: unknown;
readonly checkpoint: {
readonly applicationId: string;
readonly environment: string;
readonly profile: string;
readonly providerEpoch: string;
readonly threadId: string;
readonly sequence: string;
};
readonly encodedBytes: number;
readonly createdAt: string;
}>;
readonly sequence: number;
readonly controls: {
readonly [x: string]: {
readonly sequence: number;
readonly record: {
readonly status: "accepted" | "cancelled" | "processing" | "applied" | "rejected";
readonly runId: string;
readonly acceptedAt: string;
readonly kind: "steer" | "follow-up" | "stop" | "approve";
readonly controlId: OperationId;
readonly semanticDigest: string;
readonly effect: "not-started" | "confirmed" | "unknown";
readonly settledAt?: string;
readonly publicPayload?: unknown;
};
readonly publicPayload: unknown;
readonly semanticDigest: string;
readonly receipt: {
readonly operationId: OperationId;
readonly threadId: string;
readonly runId: string;
readonly status: "accepted" | "cancelled" | "processing" | "applied" | "rejected";
readonly effect: "not-started" | "confirmed" | "unknown";
readonly duplicate: boolean;
};
readonly expiresAt: string;
readonly downstreamOperationId?: string;
};
};
readonly runClaims: {
readonly [x: string]: {
readonly runId: string;
readonly claimId: string;
readonly workerId: string;
readonly generationId: string;
readonly fence: number;
readonly expiresAt: string;
};
};
readonly controlClaims: {
readonly [x: string]: {
readonly controlId: OperationId;
readonly claimId: string;
readonly workerId: string;
readonly generationId: string;
readonly fence: number;
readonly expiresAt: string;
};
};
readonly scopeKey: string;
readonly controlSequence: number;
readonly nextFence: number;
readonly waiting?: {
readonly revision: string;
readonly runId: string;
readonly response: Json;
readonly requests: ReadonlyArray<{
readonly node: string;
readonly response: Json;
readonly value?: unknown;
}>;
};
readonly activeRunId?: string;
readonly snapshots?: {
readonly [x: string]: {
readonly createdAt: string;
readonly messages: ReadonlyArray<{
readonly createdAt: string;
readonly role: "user" | "assistant" | "tool";
readonly parts: ReadonlyArray<
| {
readonly kind: "text";
readonly text: string;
readonly partId: string;
readonly state?: "streaming" | "complete";
}
| {
readonly kind: "tool";
readonly state:
| "running"
| "succeeded"
| "failed"
| "started"
| "input-streaming"
| "input-ready"
| "approval-required"
| "denied";
readonly partId: string;
readonly toolCallId: string;
readonly toolId: string;
readonly inputText?: string;
readonly input?: unknown;
readonly output?: unknown;
readonly value?: unknown;
}
| {
readonly partId: string;
readonly kind: "progress";
readonly value: unknown;
readonly scope: "run";
}
| {
readonly partId: string;
readonly kind: "progress";
readonly value: unknown;
readonly scope: "tool";
readonly toolCallId: string;
readonly toolId: string;
}
>;
readonly messageId: string;
readonly runId?: string;
}>;
};
};
};LocalControl
Signature
declare const LocalControl: {
readonly sequence: number;
readonly record: {
readonly status: "accepted" | "cancelled" | "processing" | "applied" | "rejected";
readonly runId: string;
readonly acceptedAt: string;
readonly kind: "steer" | "follow-up" | "stop" | "approve";
readonly controlId: OperationId;
readonly semanticDigest: string;
readonly effect: "not-started" | "confirmed" | "unknown";
readonly settledAt?: string;
readonly publicPayload?: unknown;
};
readonly publicPayload: unknown;
readonly semanticDigest: string;
readonly receipt: {
readonly operationId: OperationId;
readonly threadId: string;
readonly runId: string;
readonly status: "accepted" | "cancelled" | "processing" | "applied" | "rejected";
readonly effect: "not-started" | "confirmed" | "unknown";
readonly duplicate: boolean;
};
readonly expiresAt: string;
readonly downstreamOperationId?: string;
};LocalPinnedSnapshot
Signature
declare const LocalPinnedSnapshot: {
readonly createdAt: string;
readonly messages: ReadonlyArray<{
readonly createdAt: string;
readonly role: "user" | "assistant" | "tool";
readonly parts: ReadonlyArray<
| {
readonly kind: "text";
readonly text: string;
readonly partId: string;
readonly state?: "streaming" | "complete";
}
| {
readonly kind: "tool";
readonly state:
| "running"
| "succeeded"
| "failed"
| "started"
| "input-streaming"
| "input-ready"
| "approval-required"
| "denied";
readonly partId: string;
readonly toolCallId: string;
readonly toolId: string;
readonly inputText?: string;
readonly input?: unknown;
readonly output?: unknown;
readonly value?: unknown;
}
| {
readonly partId: string;
readonly kind: "progress";
readonly value: unknown;
readonly scope: "run";
}
| {
readonly partId: string;
readonly kind: "progress";
readonly value: unknown;
readonly scope: "tool";
readonly toolCallId: string;
readonly toolId: string;
}
>;
readonly messageId: string;
readonly runId?: string;
}>;
};LocalStoredRun
Signature
declare const LocalStoredRun: {
readonly status:
| "running"
| "waiting"
| "approval-interrupted"
| "stopping"
| "worker-interrupted"
| "accepted"
| "succeeded"
| "failed"
| "cancelled";
readonly threadId: string;
readonly runId: string;
readonly owner: {
readonly generationId: string;
readonly publicFingerprint: string;
readonly protocolVersion: number;
readonly schemaVersion: number;
readonly providerScope: string;
};
readonly operationId: OperationId;
readonly inputDigest: string;
readonly acceptedAt: string;
readonly maxJournalBytes: number;
readonly maxJournalRecordBytes: number;
readonly terminalReserveBytes: number;
readonly settledAt?: string;
readonly outcome?: "worker-interrupted" | "succeeded" | "failed" | "cancelled";
};StoredReceipt
Signature
declare const StoredReceipt: StoredReceipt<Value>;emptyAgentState
Creates format-v1 state with a fresh provider epoch and empty domain indexes.
Signature
declare const emptyAgentState: () => LocalAgentState;state.types.ts
LocalAgentState (type alias)
Complete validated version-one agent-state snapshot.
Signature
type LocalAgentState = typeof AgentState.Type;LocalAgentThread (type alias)
Thread, runs, controls and retained content decoded before transitions.
Signature
type LocalAgentThread = typeof AgentThread.Type;LocalControl (type alias)
Control record with its receipt and downstream identity.
Signature
type LocalControl = typeof AgentControl.Type;LocalPinnedSnapshot (type alias)
Immutable pinned message view retained for paginated history.
Signature
type LocalPinnedSnapshot = typeof PinnedSnapshot.Type;LocalStoredRun (type alias)
Run metadata and journal limits decoded together.
Signature
type LocalStoredRun = typeof AgentRun.Type;StoredReceipt (interface)
Generic idempotency envelope used when selecting retained receipts.
Signature
export interface StoredReceipt<Value> {
readonly semanticDigest: string;
readonly expiresAt: string;
readonly value: Value;
}storage.types.ts
AgentStateStore (interface)
Promise storage seam retained for existing provider adapters and fault injection.
Signature
export interface AgentStateStore {
read(): Promise<LocalAgentState>;
update<Value>(
change: (state: LocalAgentState) => readonly [LocalAgentState, Value],
): Promise<Value>;
}AgentStateStoreEffects (type alias)
Effect storage contract used by agent-state operations.
Signature
type AgentStateStoreEffects = LocalStateStore<LocalAgentState>;buckets.types.ts
LocalBucketListOptions (interface)
Optional cursor and bounded page size for lexical key listing.
Signature
export interface LocalBucketListOptions {
readonly cursor?: string;
readonly limit?: number;
}LocalBucketListPage (interface)
Immutable bucket key page with continuation metadata.
Signature
export interface LocalBucketListPage {
readonly items: readonly string[];
readonly nextCursor?: string;
}LocalBucketObjectMetadata (interface)
Verified content identity, size and optional application metadata.
Signature
export interface LocalBucketObjectMetadata extends BucketObjectMetadata {
readonly contentHash: string;
}LocalBucketPolicy (interface)
Size, content-type and metadata limits enforced before bucket writes.
Signature
export interface LocalBucketPolicy {
readonly maxObjectBytes?: number;
readonly allowedContentTypes?: readonly string[];
}LocalBucketProvider (type alias)
Public Promise bucket contract plus local inspection and lifecycle operations.
Signature
type LocalBucketProvider = Omit<BucketProvider, "list"> & {
readonly capabilities: Readonly<BucketCapabilities>;
readonly root: string;
readonly policy: Readonly<LocalBucketPolicy>;
readonly list: {
(prefix?: string): Promise<readonly string[]>;
(prefix: string | undefined, options: LocalBucketListOptions): Promise<LocalBucketListPage>;
};
readonly listPage: (
prefix?: string,
options?: LocalBucketListOptions,
) => Promise<LocalBucketListPage>;
readonly ready: () => Promise<void>;
readonly close: () => Promise<void>;
readonly inspector: {
readonly list: (request: {
readonly prefix?: string;
readonly cursor?: string;
readonly limit: number;
readonly signal: AbortSignal;
}) => Promise<{
readonly items: readonly { readonly key: string; readonly metadata?: BucketObjectMetadata }[];
readonly nextCursor?: string;
}>;
readonly preview: (request: {
readonly key: string;
readonly offset: number;
readonly limit: number;
readonly signal: AbortSignal;
}) => Promise<
| {
readonly bytes: Uint8Array;
readonly metadata: BucketObjectMetadata;
readonly totalBytes: number;
}
| undefined
>;
};
};LocalBucketProviderOptions (interface)
Owned root, object policy and default pagination settings for a local bucket.
Signature
export interface LocalBucketProviderOptions extends LocalBucketPolicy {
readonly root?: string;
readonly stateRoot?: string;
readonly policy?: LocalBucketPolicy;
readonly pageSize?: number;
}LocalBucketUnsupportedCapability (type alias)
Bucket capability that the filesystem implementation explicitly does not provide.
Signature
type LocalBucketUnsupportedCapability = {
readonly capability: BucketCapability;
readonly operation: BucketOperation;
};StoredLocalBucketObject (type alias)
Versioned object envelope storing verified bytes as base64.
Signature
type StoredLocalBucketObject = typeof StoredBucketObject.Type;keys.ts
assertContainedPath
Rejects a resolved path that escapes the owned root.
Signature
declare const assertContainedPath: (root: string, candidate: string) => void;encodeBucketKey
Encodes a normalized key into a filesystem-safe object identity.
Signature
declare const encodeBucketKey: (key: string) => string;normalizeBucketKey
Validates an object key without normalizing away an attempted escape.
Signature
declare const normalizeBucketKey: (value: unknown) => string;normalizeBucketPrefix
Validates a list prefix while allowing the conventional trailing slash.
Signature
declare const normalizeBucketPrefix: (value: unknown) => string;pagination.ts
DEFAULT_BUCKET_PAGE_SIZE
Signature
declare const DEFAULT_BUCKET_PAGE_SIZE: 100;MAX_BUCKET_PAGE_SIZE
Signature
declare const MAX_BUCKET_PAGE_SIZE: 1000;paginateKeys
Returns a stable page of sorted keys using a prefix-bound cursor.
Signature
declare const paginateKeys: (
keys: readonly string[],
prefix: string,
options: LocalBucketListOptions | undefined,
) => LocalBucketListPage;provider.ts
LocalBucketService (class)
Owns bucket admission, object IO and ordered inspection.
Signature
declare class LocalBucketServicecreateLocalBucketProvider
Creates a filesystem bucket with the established Promise and overload contracts.
Signature
declare const createLocalBucketProvider: (
optionsOrRoot: LocalBucketProviderOptions | string,
policy?: LocalBucketPolicy,
) => LocalBucketProvider;createLocalBucketProviderForTest
The same constructor is deterministic when supplied an isolated temporary root.
Signature
declare const createLocalBucketProviderForTest: (
optionsOrRoot: LocalBucketProviderOptions | string,
policy?: LocalBucketPolicy,
) => LocalBucketProvider;localBucketLayer
Provides a bucket service and closes its admission gate with the scope.
Example
import { Effect } from "effect";
import { LocalBucketService, localBucketLayer } from "./provider.js";
const program = Effect.gen(function* () {
const bucket = yield* LocalBucketService;
yield* bucket.put("hello.txt", new TextEncoder().encode("hello"));
return yield* bucket.head("hello.txt");
});
await Effect.runPromise(
program.pipe(Effect.provide(localBucketLayer({ root: "/tmp/example-bucket" }))),
);Signature
declare const localBucketLayer: (
options: LocalBucketProviderOptions,
) => Layer.Layer<LocalBucketService, LocalOperationError, never>;makeLocalBucketService
Validates construction and creates one bucket lifecycle owner.
Signature
declare const makeLocalBucketService: (
optionsOrRoot: string | LocalBucketProviderOptions,
policy?: LocalBucketPolicy | undefined,
) => Effect.Effect<LocalBucketEffects, LocalOperationError, never>;types.ts
LOCAL_BUCKET_CAPABILITIES
Signature
declare const LOCAL_BUCKET_CAPABILITIES: Readonly<BucketCapabilities>;LOCAL_BUCKET_RESERVED_PREFIXES
Signature
declare const LOCAL_BUCKET_RESERVED_PREFIXES: ReadonlyArray<string>;LocalBucketKeyError (class)
Preserves the public local bucket key error identity and stable error code.
Signature
declare class LocalBucketKeyError {
constructor();
}code (property)
Signature
readonly code: "RELKIT_BUCKET_KEY_INVALID"LocalBucketListOptions
Signature
declare const LocalBucketListOptions: LocalBucketListOptions;LocalBucketListPage
Signature
declare const LocalBucketListPage: LocalBucketListPage;LocalBucketObjectMetadata
Signature
declare const LocalBucketObjectMetadata: LocalBucketObjectMetadata;LocalBucketPaginationError (class)
Preserves the public local bucket pagination error identity and stable error code.
Signature
declare class LocalBucketPaginationError {
constructor();
}code (property)
Signature
readonly code: "RELKIT_BUCKET_CURSOR_INVALID"LocalBucketPolicy
Signature
declare const LocalBucketPolicy: LocalBucketPolicy;LocalBucketPolicyError (class)
Preserves the public local bucket policy error identity and stable error code.
Signature
declare class LocalBucketPolicyError {
constructor(message: string);
}code (property)
Signature
readonly code: "RELKIT_BUCKET_POLICY_INVALID"LocalBucketProvider
Signature
declare const LocalBucketProvider: LocalBucketProvider;LocalBucketProviderOptions
Signature
declare const LocalBucketProviderOptions: LocalBucketProviderOptions;LocalBucketStateError (class)
Preserves the public local bucket state error identity and stable error code.
Signature
declare class LocalBucketStateError {
constructor(message = "Bucket state is invalid");
}code (property)
Signature
readonly code: "RELKIT_BUCKET_STATE_INVALID"LocalBucketUnsupportedCapability
Signature
declare const LocalBucketUnsupportedCapability: LocalBucketUnsupportedCapability;StoredLocalBucketObject
Signature
declare const StoredLocalBucketObject: {
readonly version: 1;
readonly metadata: { readonly [x: string]: string };
readonly key: string;
readonly size: number;
readonly contentHash: string;
readonly etag: string;
readonly data: string;
readonly contentType?: string;
};cache.types.ts
LocalCacheCapabilities (interface)
Truthful persistence, atomicity and capacity guarantees for the local cache.
Signature
export interface LocalCacheCapabilities extends CacheCapabilities {
readonly persistence: "memory-only" | "restart-recovery";
readonly singleFlight: "generation-local";
}LocalCacheEvictionPolicy (type alias)
Eviction policy supported by the bounded in-memory cache.
Signature
type LocalCacheEvictionPolicy = "lru";LocalCachePolicy (interface)
Normalized TTL, encoded-value and total-cache limits.
Signature
export interface LocalCachePolicy {
readonly defaultTtlMs?: number;
readonly maxTtlMs?: number;
readonly maxEntries: number;
readonly maxBytes: number;
readonly evictionPolicy: LocalCacheEvictionPolicy;
}LocalCacheProvider (type alias)
Public cache operations and local lifecycle/inspection surface.
Signature
type LocalCacheProvider = Omit<CacheProvider, "capabilities"> & {
readonly capabilities: Readonly<LocalCacheCapabilities>;
readonly cacheId: string;
readonly schemaVersion: string | number;
readonly policy: Readonly<LocalCachePolicy>;
readonly snapshot: () => LocalCacheSnapshot;
readonly stateRoot?: string;
readonly ready: () => Promise<void>;
readonly close: () => Promise<void>;
readonly get: (key: unknown, context?: CacheOperationContext) => Promise<unknown | undefined>;
readonly set: (
key: unknown,
value: unknown,
options?: CacheOperationOptions,
context?: CacheOperationContext,
) => Promise<void>;
readonly delete: (key: unknown, context?: CacheOperationContext) => Promise<void>;
readonly has: (key: unknown, context?: CacheOperationContext) => Promise<boolean>;
readonly getOrSet: (
key: unknown,
produce: () => unknown | Promise<unknown>,
options?: CacheOperationOptions,
context?: CacheOperationContext,
) => Promise<unknown>;
readonly increment: (
key: unknown,
delta: number,
options?: CacheOperationOptions,
context?: CacheOperationContext,
) => Promise<number>;
readonly inspector: {
readonly scan: (request: {
readonly search?: string;
readonly cursor?: string;
readonly limit: number;
readonly signal: AbortSignal;
}) => Promise<{ readonly items: readonly unknown[]; readonly nextCursor?: string }>;
readonly value: (request: {
readonly key: string;
readonly limit: number;
readonly signal: AbortSignal;
}) => Promise<unknown | undefined>;
};
};LocalCacheProviderOptions (interface)
Cache bounds, persistence, clock and safe observation hooks.
Signature
export interface LocalCacheProviderOptions {
/** Provider-owned profile directory; enables atomic restart snapshots. */
readonly stateRoot?: string;
readonly cacheId?: string;
readonly schemaVersion?: string | number;
readonly defaultTtlMs?: number;
readonly maxTtlMs?: number;
readonly maxEntries?: number;
readonly maxBytes?: number;
readonly evictionPolicy?: LocalCacheEvictionPolicy;
/** Injectable clock used for TTL and deadline checks. */
readonly clock?: () => number;
/** Alias for clock, kept for small deterministic test seams. */
readonly now?: () => number;
/** Receives safe counters only; keys and values are never included. */
readonly onSnapshot?: (snapshot: LocalCacheSnapshot) => void;
}LocalCacheSnapshot (interface)
Safe cache counters and effective policy without keys or values.
Signature
export interface LocalCacheSnapshot {
readonly version: 1;
readonly cacheId: string;
readonly schemaVersion: string | number;
readonly entries: number;
readonly bytes: number;
readonly evictions: number;
readonly hits: number;
readonly misses: number;
readonly inFlight: number;
}inspector.ts
createLocalCacheInspector
Projects bounded cache metadata and previews from the same byte-LRU store.
Signature
declare const createLocalCacheInspector: (
store: LocalCacheStore,
clock: () => number,
) => LocalCacheProvider["inspector"];keys.ts
createLocalCacheKey
Builds a deterministic namespace key without exposing the raw key to logs.
Signature
declare const createLocalCacheKey: (
cacheId: string,
schemaVersion: string | number,
key: unknown,
) => string;normalizeCacheId
Validates the namespace used to isolate canonical cache keys.
Signature
declare const normalizeCacheId: (value: unknown) => string;normalizeSchemaVersion
Validates the cache schema namespace without changing its public representation.
Signature
declare const normalizeSchemaVersion: (value: unknown) => string | number;serializeLocalCacheValue
Serializes supported JSON values for byte accounting and cloning.
Signature
declare const serializeLocalCacheValue: (value: unknown) => string;policy.ts
assertActive
Rejects an aborted or expired operation before cache or bucket IO.
Signature
declare const assertActive: (
context: CacheOperationContext | undefined,
clock: () => number,
) => number;byteLength
Measures UTF-8 bytes for cache key and value capacity accounting.
Signature
declare const byteLength: (value: string) => number;clone
Copies cache values through their supported JSON representation.
Signature
declare const clone: (value: unknown) => unknown;normalizePolicy
Validates provider limits and normalizes effective policy defaults.
Signature
declare const normalizePolicy: (options: LocalCacheProviderOptions) => LocalCachePolicy;normalizeTtl
Resolves entry TTL against defaults and the maximum allowed lifetime.
Signature
declare const normalizeTtl: (value: unknown, policy: LocalCachePolicy) => number | undefined;readClock
Checks that the injected clock returns a usable finite timestamp.
Signature
declare const readClock: (clock: () => number) => number;provider.ts
LocalCacheService (class)
Cache state, producer admission and durable writes share one owner.
Signature
declare class LocalCacheServicecreateLocalCacheProvider
Creates the existing Promise cache API over an Effect service.
Signature
declare const createLocalCacheProvider: (options?: LocalCacheProviderOptions) => LocalCacheProvider;localCacheLayer
Provides a cache and commits its final snapshot at scope exit.
Example
import { Effect } from "effect";
import { LocalCacheService, localCacheLayer } from "./provider.js";
const program = Effect.gen(function* () {
const cache = yield* LocalCacheService;
yield* cache.set("answer", 42);
return yield* cache.get("answer");
});
await Effect.runPromise(program.pipe(Effect.provide(localCacheLayer())));Signature
declare const localCacheLayer: (
options?: LocalCacheProviderOptions,
) => Layer.Layer<LocalCacheService, LocalOperationError, never>;makeLocalCacheService
Acquires the cache’s indexes, serialization permit and producer coordination.
Signature
declare const makeLocalCacheService: (
options?: LocalCacheProviderOptions,
) => Effect.Effect<LocalCacheEffects, LocalOperationError>;store.ts
LocalCacheRead
Signature
declare const LocalCacheRead: LocalCacheRead;LocalCacheStore (class)
Pure byte-bounded LRU state owned by LocalCacheService; callers supply clock values.
Signature
declare class LocalCacheStore { constructor(private readonly policy: LocalCachePolicy) }read (method)
Reads an entry, expires stale values, and updates recency and hit/miss counters.
Signature
declare const read: (key: string, now: number) => LocalCacheRead;write (method)
Replaces an entry and evicts least-recently-used values until both bounds hold.
Signature
declare const write: (
key: string,
value: unknown,
bytes: number,
expiresAt: number | undefined,
) => void;remove (method)
Removes one entry and adjusts encoded byte accounting; reports whether it existed.
Signature
declare const remove: (key: string) => boolean;purgeExpired (method)
Removes every expired entry without changing hit/miss counters.
Signature
declare const purgeExpired: (now: number) => void;snapshot (method)
Copies safe counters without exposing cached values or keys.
Signature
declare const snapshot: () => LocalCacheStoreSnapshot;exportState (method)
Copies all entries and recency counters for the owning service’s durable snapshot.
Signature
declare const exportState: () => LocalCacheStoreState;restore (method)
Validates snapshot entries, rebuilds accounting, and reapplies current policy limits.
Signature
declare const restore: (state: LocalCacheStoreState) => void;clear (method)
Releases all cached entries while preserving historical counters.
Signature
declare const clear: () => void;evict (method)
Evicts by recency using a bounded linear scan of the in-memory entries.
Signature
declare const evict: () => void;LocalCacheStoreEntry
Signature
declare const LocalCacheStoreEntry: LocalCacheStoreEntry;LocalCacheStoreSnapshot
Signature
declare const LocalCacheStoreSnapshot: LocalCacheStoreSnapshot;LocalCacheStoreState
Signature
declare const LocalCacheStoreState: LocalCacheStoreState;MISSING
Signature
declare const MISSING: unique symbol;store.types.ts
Entry (interface)
Mutable LRU entry with encoded-byte accounting and recency sequence.
Signature
export interface Entry {
readonly key: string;
readonly value: unknown;
readonly bytes: number;
readonly expiresAt?: number;
lastUsed: number;
}LocalCacheRead (interface)
Cache read result distinguishing absence from an expired value.
Signature
export interface LocalCacheRead {
readonly value: unknown | typeof MISSING;
readonly expired: boolean;
}LocalCacheStoreEntry (interface)
Serializable cache entry including expiration and recency metadata.
Signature
export interface LocalCacheStoreEntry {
readonly key: string;
readonly value: unknown;
readonly bytes: number;
readonly expiresAt?: number;
readonly lastUsed: number;
}LocalCacheStoreSnapshot (interface)
Safe counters maintained by the pure LRU state.
Signature
export interface LocalCacheStoreSnapshot {
readonly entries: number;
readonly bytes: number;
readonly evictions: number;
readonly hits: number;
readonly misses: number;
}LocalCacheStoreState (interface)
Complete cache snapshot used to restore counters and LRU ordering.
Signature
export interface LocalCacheStoreState extends Omit<LocalCacheStoreSnapshot, "entries"> {
readonly sequence: number;
readonly entries: readonly LocalCacheStoreEntry[];
}types.ts
LOCAL_CACHE_CAPABILITIES
Signature
declare const LOCAL_CACHE_CAPABILITIES: Readonly<{
readonly increment: true;
readonly persistence: "memory-only";
readonly singleFlight: "generation-local";
}>;LOCAL_CACHE_DURABLE_CAPABILITIES
Signature
declare const LOCAL_CACHE_DURABLE_CAPABILITIES: Readonly<{
readonly increment: true;
readonly persistence: "restart-recovery";
readonly singleFlight: "generation-local";
}>;LocalCacheCapabilities
Signature
declare const LocalCacheCapabilities: LocalCacheCapabilities;LocalCacheEvictionPolicy
Signature
declare const LocalCacheEvictionPolicy: "lru";LocalCacheKeyError (class)
Preserves the public local cache key error identity and stable error code.
Signature
declare class LocalCacheKeyError {
constructor();
}code (property)
Signature
readonly code: "RELKIT_CACHE_KEY_INVALID"LocalCachePolicy
Signature
declare const LocalCachePolicy: LocalCachePolicy;LocalCachePolicyError (class)
Preserves the public local cache policy error identity and stable error code.
Signature
declare class LocalCachePolicyError {
constructor(message: string);
}code (property)
Signature
readonly code: "RELKIT_CACHE_POLICY_INVALID"LocalCacheProvider
Signature
declare const LocalCacheProvider: LocalCacheProvider;LocalCacheProviderOptions
Signature
declare const LocalCacheProviderOptions: LocalCacheProviderOptions;LocalCacheSnapshot
Signature
declare const LocalCacheSnapshot: LocalCacheSnapshot;LocalCacheStateError (class)
Preserves the public local cache state error identity and stable error code.
Signature
declare class LocalCacheStateError {
constructor(message = "Cache provider state is invalid");
}code (property)
Signature
readonly code: "RELKIT_CACHE_STATE_INVALID"LocalCacheValueError (class)
Preserves the public local cache value error identity and stable error code.
Signature
declare class LocalCacheValueError {
constructor();
}code (property)
Signature
readonly code: "RELKIT_CACHE_VALUE_INVALID"admin-contracts.ts
EVENT_ADMIN_PROTOCOL
Signature
declare const EVENT_ADMIN_PROTOCOL: "relkit.events.admin";EVENT_ADMIN_VERSION
Signature
declare const EVENT_ADMIN_VERSION: 1;EventAdminAction
Signature
declare const EventAdminAction: "retry";EventAdminActionContract
Signature
declare const EventAdminActionContract: EventAdminActionContract;EventAdminActionOutcome
Signature
declare const EventAdminActionOutcome: EventAdminActionOutcome;EventAdminActionRecord
Signature
declare const EventAdminActionRecord: EventAdminActionRecord;EventAdminActionRequest
Signature
declare const EventAdminActionRequest: EventAdminActionRequest;EventAdminActionSink
Signature
declare const EventAdminActionSink: EventAdminActionSink;EventAdminMode
Signature
declare const EventAdminMode: EventAdminMode;EventAdminVersion
Signature
declare const EventAdminVersion: EventAdminVersion;EventContract
Signature
declare const EventContract: EventContract;EventContractInput
Signature
declare const EventContractInput: EventContractInput;EventDeadLetterContract
Signature
declare const EventDeadLetterContract: EventDeadLetterContract;EventDeliveryContract
Signature
declare const EventDeliveryContract: EventDeliveryContract;EventPublicationContract
Signature
declare const EventPublicationContract: EventPublicationContract;EventQueryContract
Signature
declare const EventQueryContract: EventQueryContract;EventQueryRequest
Signature
declare const EventQueryRequest: EventQueryRequest;EventRetryRequest
Signature
declare const EventRetryRequest: EventAdminActionRequest;EventTriggerCapabilityContract
Signature
declare const EventTriggerCapabilityContract: EventTriggerCapabilityContract;EventTriggerContract
Signature
declare const EventTriggerContract: EventTriggerContract;EventVersioned
Signature
declare const EventVersioned: EventVersioned;admin-contracts.types.ts
EventAdminAction (type alias)
Supported audited event administration action.
Signature
type EventAdminAction = "retry";EventAdminActionContract (interface)
Versioned mutation response containing status and audit record.
Signature
export interface EventAdminActionContract extends EventAdminVersion {
readonly action: EventAdminAction;
readonly status: EventDeliveryContract;
readonly record: EventAdminActionRecord;
}EventAdminActionOutcome (type alias)
Whether an event administration action was applied or rejected.
Signature
type EventAdminActionOutcome = "applied" | "rejected";EventAdminActionRecord (interface)
Immutable audit record for an applied or rejected event mutation.
Signature
export interface EventAdminActionRecord extends EventAdminVersion {
readonly actionId: string;
readonly action: EventAdminAction;
readonly deliveryId: string;
readonly eventInstanceId?: string;
readonly triggerId?: string;
readonly mode: EventAdminMode;
readonly outcome: EventAdminActionOutcome;
readonly requestedAt: number;
readonly fromState?: Exclude<JobQueueState, "accepted">;
readonly toState?: Exclude<JobQueueState, "accepted">;
readonly errorCode?: string;
readonly reason?: string;
}EventAdminActionRequest (interface)
Event mutation request carrying delivery identity and optional audit reason.
Signature
export interface EventAdminActionRequest {
readonly protocol?: typeof EVENT_ADMIN_PROTOCOL;
readonly version?: typeof EVENT_ADMIN_VERSION;
readonly deliveryId: string;
readonly reason?: string;
}EventAdminActionSink (type alias)
Optional audit sink isolated from the event action outcome.
Signature
type EventAdminActionSink = (record: EventAdminActionRecord) => MaybePromise<void>;EventAdminMode (type alias)
Environment mode controlling event administration mutations.
Signature
type EventAdminMode = "development" | "test" | "production";EventAdminVersion (interface)
Protocol identity carried by event administration contracts.
Signature
export interface EventAdminVersion {
readonly protocol: typeof EVENT_ADMIN_PROTOCOL;
readonly version: typeof EVENT_ADMIN_VERSION;
}EventContract (interface)
Versioned declared event identity and schema metadata for inspection.
Signature
export interface EventContract extends EventVersioned, EventContractInput {}EventContractInput (interface)
The serializable event contract registered by the active graph.
Signature
export interface EventContractInput {
readonly id: string;
readonly version: number;
readonly input: JsonValue;
readonly sensitiveFields?: readonly string[];
readonly source?: JsonValue;
}EventDeadLetterContract (interface)
Versioned dead-letter status with safe retry/failure metadata.
Signature
export interface EventDeadLetterContract extends EventDeliveryContract {
readonly state: "dead-lettered";
readonly failure: JobFailureMetadata;
}EventDeliveryContract (interface)
Safe delivery state shared by current and dead-lettered attempts.
Signature
export interface EventDeliveryContract extends EventVersioned {
readonly cursor: number;
readonly sequence: number;
readonly deliveryId: string;
readonly eventInstanceId: string;
readonly eventId: string;
readonly version: number;
readonly triggerId: string;
readonly state: Exclude<JobQueueState, "accepted">;
readonly attempt: number;
readonly duplicate: boolean;
readonly timestamp: number;
readonly leaseExpiresAt?: number;
readonly failure?: JobFailureMetadata;
}EventPublicationContract (interface)
Safe publication metadata; payload data is intentionally not projected.
Signature
export interface EventPublicationContract extends EventVersioned {
readonly sequence: number;
readonly timestamp: number;
readonly accepted: true;
readonly instanceId: string;
readonly eventId: string;
readonly version: number;
readonly occurredAt: string;
readonly publishedAt: string;
readonly key?: string;
readonly correlationId?: string;
readonly originRequestId?: string;
readonly producerTraceId?: string;
readonly attributes: Readonly<Record<string, string | number | boolean>>;
}EventQueryContract (interface)
Versioned bounded event, publication and delivery inspection response.
Signature
export interface EventQueryContract extends EventAdminVersion {
readonly events: readonly EventContract[];
readonly triggers: readonly EventTriggerContract[];
readonly capabilities: readonly EventTriggerCapabilityContract[];
readonly publications: readonly EventPublicationContract[];
readonly items: readonly EventDeliveryContract[];
readonly deliveries: readonly EventDeliveryContract[];
readonly deadLetters: readonly EventDeadLetterContract[];
readonly nextCursor?: string;
}EventQueryRequest (interface)
Event, trigger, state and pagination filters for local inspection.
Signature
export interface EventQueryRequest {
readonly protocol?: typeof EVENT_ADMIN_PROTOCOL;
readonly version?: typeof EVENT_ADMIN_VERSION;
readonly eventId?: string;
readonly eventVersion?: number;
readonly triggerId?: string;
readonly state?: Exclude<JobQueueState, "accepted">;
readonly states?: readonly Exclude<JobQueueState, "accepted">[];
readonly cursor?: string;
readonly limit?: number;
}EventRetryRequest (type alias)
Dead-letter retry request preserving event admin protocol identity.
Signature
type EventRetryRequest = EventAdminActionRequest;EventTriggerCapabilityContract (interface)
Versioned truthful delivery capabilities for a registered trigger.
Signature
export interface EventTriggerCapabilityContract extends EventAdminVersion {
readonly triggerId: string;
readonly delivery: "ephemeral" | "durable";
readonly persistence: "none" | "restart-recovery";
readonly restartRecovery: boolean;
readonly atLeastOnce: boolean;
readonly exactlyOnce: false;
readonly ordering: "unsupported";
readonly orderedByKey: false;
}EventTriggerContract (interface)
Exact event and delivery metadata for one generated event trigger.
Signature
export interface EventTriggerContract extends EventAdminVersion {
readonly id: string;
readonly targetFunctionId?: string;
readonly eventId: string;
readonly eventVersion: number;
readonly delivery: "ephemeral" | "durable";
readonly profile?: string;
readonly retry?: RetryPolicy;
readonly concurrency?: number;
readonly timeoutMs?: number;
}EventVersioned (interface)
Protocol identity carried by public event inspection contracts.
Signature
export interface EventVersioned {
readonly protocol: typeof EVENT_ADMIN_PROTOCOL;
readonly protocolVersion: typeof EVENT_ADMIN_VERSION;
}admin-errors.ts
Preserves the public event admin error identity and stable error code.
EventAdminError (class)
Preserves the public event admin error identity and stable error code.
Signature
declare class EventAdminError { constructor(
readonly code: string,
message: string,
) }admin.ts
“./admin-contracts.js” (namespace export)
Re-exports all named exports from the “./admin-contracts.js” module.
Signature
export * from "./admin-contracts.js";EventAdmin
Signature
declare const EventAdmin: EventAdmin;EventAdminError
Signature
declare const EventAdminError: typeof EventAdminError;EventAdminOptions
Signature
declare const EventAdminOptions: EventAdminOptions;createEventAdmin
Exposes versioned event inspection and an audited local dead-letter retry.
Signature
declare const createEventAdmin: (router: EventRouter, options?: EventAdminOptions) => EventAdmin;admin.types.ts
EventAdmin (interface)
Versioned event inspection and audited dead-letter retry interface.
Signature
export interface EventAdmin {
readonly protocol: typeof EVENT_ADMIN_PROTOCOL;
readonly version: typeof EVENT_ADMIN_VERSION;
readonly query: (request?: EventQueryRequest) => EventQueryContract;
readonly retry: (request: string | EventAdminActionRequest) => Promise<EventAdminActionContract>;
readonly actions: () => readonly EventAdminActionRecord[];
}EventAdminOptions (interface)
Event administration mode plus isolated audit and clock hooks.
Signature
export interface EventAdminOptions {
readonly mode?: EventAdminMode;
readonly environment?: EventAdminMode;
readonly enabled?: boolean;
readonly now?: () => number;
readonly createActionId?: () => string;
readonly onAction?: EventAdminActionSink;
}delivery-types.ts
EVENT_DELIVERY_CAPABILITIES
Signature
declare const EVENT_DELIVERY_CAPABILITIES: Readonly<{
readonly persistence: "restart-recovery";
readonly restartRecovery: true;
readonly atLeastOnce: true;
readonly exactlyOnce: false;
readonly ordering: "unsupported";
readonly orderedByKey: false;
}>;EventDelivery
Signature
declare const EventDelivery: EventDelivery;EventDeliveryBinding
Signature
declare const EventDeliveryBinding: EventDeliveryBinding;EventDeliveryBoundary
Signature
declare const EventDeliveryBoundary: EventDeliveryBoundary;EventDeliveryCapabilities
Signature
declare const EventDeliveryCapabilities: Readonly<{
readonly persistence: "restart-recovery";
readonly restartRecovery: true;
readonly atLeastOnce: true;
readonly exactlyOnce: false;
readonly ordering: "unsupported";
readonly orderedByKey: false;
}>;EventDeliveryInvocationOptions
Signature
declare const EventDeliveryInvocationOptions: EventDeliveryInvocationOptions;EventDeliveryLedgerRecord
Signature
declare const EventDeliveryLedgerRecord: EventDeliveryLedgerRecord;EventDeliveryOptions
Signature
declare const EventDeliveryOptions: EventDeliveryOptions;EventDeliveryResult
Signature
declare const EventDeliveryResult: EventDeliveryResult;EventDeliverySnapshot
Signature
declare const EventDeliverySnapshot: EventDeliverySnapshot;delivery.ts
EVENT_DELIVERY_CAPABILITIES
Signature
declare const EVENT_DELIVERY_CAPABILITIES: Readonly<{
readonly persistence: "restart-recovery";
readonly restartRecovery: true;
readonly atLeastOnce: true;
readonly exactlyOnce: false;
readonly ordering: "unsupported";
readonly orderedByKey: false;
}>;EventDelivery
Signature
declare const EventDelivery: EventDelivery;EventDeliveryBinding
Signature
declare const EventDeliveryBinding: EventDeliveryBinding;EventDeliveryBoundary
Signature
declare const EventDeliveryBoundary: EventDeliveryBoundary;EventDeliveryLedgerRecord
Signature
declare const EventDeliveryLedgerRecord: EventDeliveryLedgerRecord;EventDeliveryOptions
Signature
declare const EventDeliveryOptions: EventDeliveryOptions;EventDeliveryResult
Signature
declare const EventDeliveryResult: EventDeliveryResult;EventDeliverySnapshot
Signature
declare const EventDeliverySnapshot: EventDeliverySnapshot;LocalEventDeliveryService (class)
One trigger owns durable admission, retry transitions and handler concurrency.
Signature
declare class LocalEventDeliveryServicecreateEventDelivery
Opens durable at-least-once delivery behind its existing Promise API.
Signature
declare const createEventDelivery: (
root: string,
binding: EventDeliveryBinding,
options?: EventDeliveryOptions,
) => Promise<EventDelivery>;eventDeliveryLayer
Provides one trigger’s delivery service with scope-owned shutdown.
Signature
declare const eventDeliveryLayer: (
root: string,
binding: EventDeliveryBinding,
options?: EventDeliveryOptions,
) => Layer.Layer<LocalEventDeliveryService, LocalOperationError, never>;makeEventDelivery
Recovers a trigger and composes its serialized admission and bounded execution.
Signature
declare const makeEventDelivery: (
root: string,
binding: EventDeliveryBinding,
options?: EventDeliveryOptions | undefined,
) => Effect.Effect<EventDeliveryEffects, LocalOperationError, never>;delivery.types.ts
EventDelivery (interface)
Compatibility interface for accepting, executing and inspecting durable deliveries.
Signature
export interface EventDelivery {
readonly triggerId: string;
readonly capabilities: EventDeliveryCapabilities;
readonly accept: (envelope: UnknownEventEnvelope) => Promise<EventDeliveryResult>;
readonly deliver: (envelope: UnknownEventEnvelope) => Promise<EventDeliveryResult>;
readonly runNext: (deliveryId?: string) => Promise<EventDeliveryResult | undefined>;
readonly retry: (deliveryId: string) => Promise<EventDeliveryResult>;
readonly drain: () => Promise<readonly EventDeliveryResult[]>;
readonly recover: (now?: number) => Promise<readonly EventDeliveryLedgerRecord[]>;
readonly snapshot: () => EventDeliverySnapshot;
readonly close: () => Promise<void>;
}EventDeliveryBinding (interface)
Trigger identity and executable target for a durable delivery owner.
Signature
export interface EventDeliveryBinding {
readonly id: string;
readonly invoke: (
envelope: UnknownEventEnvelope,
options?: EventDeliveryInvocationOptions,
) => Promise<unknown>;
readonly profile?: string;
readonly retry?: RetryPolicy;
readonly concurrency?: number;
readonly timeoutMs?: number;
}EventDeliveryBoundary (type alias)
Durable delivery commit milestones exposed to hooks.
Signature
type EventDeliveryBoundary = JobStoreBoundary | "handler-success-before-ack";EventDeliveryCapabilities (type alias)
Actual durability, restart, overflow and cancellation guarantees.
Signature
type EventDeliveryCapabilities = typeof EVENT_DELIVERY_CAPABILITIES;EventDeliveryInvocationOptions (interface)
Attempt metadata and cancellation supplied to a delivery target.
Signature
export interface EventDeliveryInvocationOptions {
readonly attempt: number;
readonly replayed: boolean;
readonly timeoutMs?: number;
}EventDeliveryLedgerRecord (interface)
Persisted delivery envelope joined with its latest queue state.
Signature
export interface EventDeliveryLedgerRecord extends EventDeliveryRecord {
readonly cursor: number;
readonly state: EventDeliveryResult["state"];
readonly attempt: number;
readonly duplicate: boolean;
readonly leaseOwner?: string;
readonly leaseExpiresAt?: number;
readonly failure?: JobFailureMetadata;
}EventDeliveryOptions (interface)
Backlog, concurrency, retry and durable-boundary configuration.
Signature
export interface EventDeliveryOptions {
readonly now?: () => number;
readonly random?: () => number;
readonly ownerToken?: string;
readonly leaseDurationMs?: number;
readonly retry?: RetryPolicy;
readonly concurrency?: number;
readonly onBoundary?: (boundary: EventDeliveryBoundary) => void | Promise<void>;
}EventDeliveryResult (interface)
Delivery outcome including acceptance and actual persistence guarantees.
Signature
export interface EventDeliveryResult {
readonly deliveryId: string;
readonly triggerId: string;
readonly eventInstanceId: string;
readonly accepted: boolean;
readonly persisted: boolean;
readonly status: "queued" | "completed" | "failed";
readonly state: "available" | "leased" | "delayed" | "completed" | "dead-lettered";
readonly attempt: number;
readonly duplicate: boolean;
readonly value?: unknown;
readonly error?: unknown;
readonly failure?: JobFailureMetadata;
}EventDeliverySnapshot (interface)
Safe delivery counters and durable ledger inspection.
Signature
export interface EventDeliverySnapshot {
readonly cursor: number;
readonly records: readonly EventDeliveryRecord[];
readonly ledger: readonly EventDeliveryLedgerRecord[];
readonly counts: JobQueueCounts;
readonly capabilities: typeof EVENT_DELIVERY_CAPABILITIES;
}ephemeral.ts
DEFAULT_EPHEMERAL_CAPACITY
Signature
declare const DEFAULT_EPHEMERAL_CAPACITY: 100;EPHEMERAL_DELIVERY_CAPABILITIES
Signature
declare const EPHEMERAL_DELIVERY_CAPABILITIES: Readonly<{
readonly persistence: "none";
readonly restartRecovery: false;
readonly dropPolicy: "drop-newest";
}>;EphemeralDelivery
Signature
declare const EphemeralDelivery: EphemeralDelivery;EphemeralDeliveryEffects
Signature
declare const EphemeralDeliveryEffects: EphemeralDeliveryEffects;EphemeralDeliveryResult
Signature
declare const EphemeralDeliveryResult: EphemeralDeliveryResult;EphemeralDeliverySnapshot
Signature
declare const EphemeralDeliverySnapshot: EphemeralDeliverySnapshot;LocalEphemeralService (class)
Capacity, counters and native handler completion share one service owner.
Signature
declare class LocalEphemeralServicecreateEphemeralDelivery
Constructs a transient delivery service behind the Promise boundary.
Signature
declare const createEphemeralDelivery: (
invoke: (envelope: UnknownEventEnvelope) => Promise<unknown>,
requestedCapacity?: number,
) => EphemeralDelivery;ephemeralDeliveryLayer
Supplies transient delivery and drains admitted handlers at scope exit.
Signature
declare const ephemeralDeliveryLayer: (
invoke: (envelope: UnknownEventEnvelope) => Promise<unknown>,
capacity?: number,
) => Layer.Layer<LocalEphemeralService, LocalOperationError, never>;makeEphemeralDelivery
Owns bounded admission and safe counters using Ref and Semaphore.
Signature
declare const makeEphemeralDelivery: (
invoke: (envelope: UnknownEventEnvelope) => Promise<unknown>,
capacity?: any,
) => Effect.Effect<EphemeralDeliveryEffects, LocalOperationError, never>;ephemeral.types.ts
EphemeralDelivery (interface)
Public transient delivery interface with explicit drain and synchronous counters.
Signature
export interface EphemeralDelivery {
readonly deliver: (envelope: UnknownEventEnvelope) => Promise<EphemeralDeliveryResult>;
readonly drain: () => Promise<void>;
readonly snapshot: () => EphemeralDeliverySnapshot;
}EphemeralDeliveryEffects (interface)
Effect contract for bounded transient delivery without a hidden backlog.
Signature
export interface EphemeralDeliveryEffects {
readonly deliver: (envelope: UnknownEventEnvelope) => Effect.Effect<EphemeralDeliveryResult>;
readonly drain: () => Effect.Effect<void>;
readonly snapshot: () => Effect.Effect<EphemeralDeliverySnapshot>;
}EphemeralDeliveryResult (interface)
Transient handler outcome with explicit nonpersistent capacity guarantees.
Signature
export interface EphemeralDeliveryResult {
readonly accepted: boolean;
readonly persisted: false;
readonly status: "completed" | "failed" | "dropped";
readonly capacity: number;
readonly dropPolicy: "drop-newest";
readonly restartRecovery: false;
readonly value?: unknown;
readonly error?: unknown;
readonly dropReason?: "capacity";
}EphemeralDeliverySnapshot (interface)
Safe admission, completion, failure and overflow counters.
Signature
export interface EphemeralDeliverySnapshot {
readonly capacity: number;
readonly inFlight: number;
readonly admitted: number;
readonly completed: number;
readonly failed: number;
readonly dropped: number;
readonly persistence: "none";
readonly restartRecovery: false;
readonly dropPolicy: "drop-newest";
}log.ts
EVENT_LOG_VERSION
Signature
declare const EVENT_LOG_VERSION: 1;EventLog
Signature
declare const EventLog: EventLog;EventLogBoundary
Signature
declare const EventLogBoundary: JobStoreBoundary;EventLogInput
Signature
declare const EventLogInput: EventLogInput;EventLogOptions
Signature
declare const EventLogOptions: EventLogOptions;EventLogPaths
Signature
declare const EventLogPaths: JobStorePaths;EventLogRecord
Signature
declare const EventLogRecord: EventLogRecord;EventLogSnapshot
Signature
declare const EventLogSnapshot: EventLogSnapshot;EventLogStateError (class)
Preserves the public event log state error identity and stable error code.
Signature
declare class EventLogStateError {
constructor(message: string);
}code (property)
Signature
readonly code: "RELKIT_EVENT_LOG_STATE_INVALID"createEventLog
Opens the durable accepted-event log and repairs invalid records on startup.
Signature
declare const createEventLog: (
requestedRoot: string,
options?: EventLogOptions,
) => Promise<EventLog>;createEventLogPaths
Builds the stable event journal and metadata paths below the owned root.
Signature
declare const createEventLogPaths: (root: string) => EventLogPaths;log.types.ts
EventLog (interface)
Promise event log operations and synchronous recovered snapshot.
Signature
export interface EventLog {
readonly root: string;
readonly paths: EventLogPaths;
readonly append: (envelope: EventLogInput) => Promise<EventLogRecord>;
readonly snapshot: () => EventLogSnapshot;
readonly close: () => Promise<void>;
}EventLogBoundary (type alias)
Durable event-log commit milestones exposed to hooks.
Signature
type EventLogBoundary = JobStoreBoundary;EventLogInput (type alias)
Event envelope input before journal sequence assignment.
Signature
type EventLogInput = UnknownEventEnvelope | EventPublishResult<string, number, unknown>;EventLogOptions (interface)
Event-log validation and durable commit hook configuration.
Signature
export interface EventLogOptions extends Pick<JobStoreOptions, "now" | "onBoundary"> {}EventLogPaths (type alias)
Owned paths for durable event records and derived metadata.
Signature
type EventLogPaths = ReturnType<typeof createJobStorePaths>;EventLogRecord (interface)
Accepted event envelope with its durable journal identity.
Signature
export interface EventLogRecord {
readonly version: typeof EVENT_LOG_VERSION;
readonly sequence: number;
readonly kind: "accepted";
readonly accepted: true;
readonly timestamp: number;
readonly envelope: UnknownEventEnvelope;
}EventLogSnapshot (interface)
Immutable persisted event records and recovery metadata.
Signature
export interface EventLogSnapshot {
readonly records: readonly EventLogRecord[];
readonly index: JobStoreIndex;
readonly checkpoint: JobStoreCheckpoint;
}provider.ts
LocalEventEffects
Signature
declare const LocalEventEffects: LocalEventEffects;LocalEventProvider
Signature
declare const LocalEventProvider: LocalEventProvider;LocalEventService (class)
Publication and delivery orchestration for one local event provider.
Signature
declare class LocalEventServicecreateLocalEventProvider
Acquires a scoped event provider behind its established Promise surface.
Signature
declare const createLocalEventProvider: (root: string) => Promise<LocalEventProvider>;localEventLayer
Supplies publication and its supervised delivery workers as one layer.
Example
import { Effect } from "effect";
import { LocalEventService, localEventLayer } from "./provider.js";
const program = Effect.gen(function* () {
const events = yield* LocalEventService;
yield* events.health();
});
await Effect.runPromise(program.pipe(Effect.provide(localEventLayer("/tmp/example-events"))));Signature
declare const localEventLayer: (
root: string,
) => Layer.Layer<LocalEventService, LocalOperationError, never>;makeLocalEventService
Owns log, router, worker fibers and background failure state.
Signature
declare const makeLocalEventService: (
root: string,
) => Effect.Effect<LocalEventEffects, LocalOperationError, Scope.Scope>;provider.types.ts
LocalEventEffects (interface)
Effect event methods owned by the provider scope.
Signature
export interface LocalEventEffects {
readonly query: (
request?: EventQueryRequest,
) => Effect.Effect<EventQueryContract, LocalOperationError>;
readonly registerContract: (contract: unknown) => Effect.Effect<void, LocalOperationError>;
readonly registerTrigger: (
binding: EventRouterTrigger,
) => Effect.Effect<void, LocalOperationError>;
readonly publish: (
payload: unknown,
options: EventPublishOptions,
context: EventOperationContext,
) => Effect.Effect<EventProviderResult, LocalOperationError>;
readonly health: () => Effect.Effect<void, LocalOperationError>;
}LocalEventProvider (interface)
Public event registration, publication and explicit close operations.
Signature
export interface LocalEventProvider extends EventProvider {
readonly registerContract: EventRouter["registerContract"];
readonly registerTrigger: EventRouter["registerTrigger"];
readonly query: (request?: EventQueryRequest) => Promise<EventQueryContract>;
readonly close: () => Promise<void>;
}router-model.types.ts
EventDeliveryResult (interface)
Delivery outcome including acceptance and actual persistence guarantees.
Signature
export interface EventDeliveryResult {
readonly triggerId: string;
readonly delivery: "ephemeral" | "durable";
readonly deliveryId?: string;
readonly eventInstanceId?: string;
readonly accepted: boolean;
readonly persisted: boolean;
readonly status: "queued" | "completed" | "failed" | "dropped";
readonly state?: "available" | "leased" | "delayed" | "completed" | "dead-lettered";
readonly attempt?: number;
readonly duplicate?: boolean;
readonly capacity?: number;
readonly dropPolicy?: "drop-newest";
readonly restartRecovery?: false;
readonly dropReason?: "capacity";
readonly value?: unknown;
readonly error?: unknown;
readonly failure?: unknown;
}EventFanoutResult (interface)
Publication result containing each matching trigger delivery outcome.
Signature
export interface EventFanoutResult {
readonly event: UnknownEventEnvelope;
readonly matchedTriggerIds: readonly string[];
readonly deliveries: readonly EventDeliveryResult[];
}EventRouter (interface)
Compatibility router interface for registration, fanout, inspection and lifecycle.
Signature
export interface EventRouter {
readonly root: string;
readonly registerContract: (contract: unknown) => Promise<void>;
readonly registerTrigger: (binding: EventRouterTrigger) => Promise<void>;
readonly route: (
event: EventRouterInput,
options?: EventRouterRouteOptions,
) => Promise<EventFanoutResult>;
readonly runNext: (triggerId?: string) => Promise<EventDeliveryResult | undefined>;
readonly drain: () => Promise<readonly EventDeliveryResult[]>;
readonly retry: (deliveryId: string) => Promise<EventDeliveryResult>;
readonly snapshot: () => EventRouterSnapshot;
readonly close: () => Promise<void>;
}EventRouterInput (type alias)
Publication input accepted as a log record or event envelope.
Signature
type EventRouterInput = EventLogRecord | EventLogInput;EventRouterOptions (interface)
Storage and delivery construction settings for the local router.
Signature
export interface EventRouterOptions {
readonly onBoundary?: (
boundary: EventDeliveryBoundary,
triggerId: string,
) => void | Promise<void>;
readonly now?: () => number;
readonly random?: () => number;
readonly ownerToken?: string;
readonly leaseDurationMs?: number;
readonly ephemeralCapacity?: number;
}EventRouterRouteOptions (interface)
Fanout options controlling immediate worker execution.
Signature
export interface EventRouterRouteOptions {
readonly run?: boolean;
}EventRouterSnapshot (interface)
Immutable contracts, triggers, publications and delivery status inspection.
Signature
export interface EventRouterSnapshot {
readonly records: readonly EventDeliveryRecord[];
readonly contracts: readonly EventContractInput[];
readonly triggers: readonly EventTriggerSnapshot[];
readonly publications: readonly EventLogRecord[];
readonly deliveries: readonly EventDeliveryLedgerRecord[];
}EventRouterTrigger (interface)
Declared trigger identity, event match and executable target binding.
Signature
export interface EventRouterTrigger {
readonly id: string;
readonly targetFunctionId?: string;
readonly eventId: string;
readonly eventVersion: number;
readonly delivery: "ephemeral" | "durable";
readonly profile?: string;
readonly retry?: RetryPolicy;
readonly concurrency?: number;
readonly timeoutMs?: number;
readonly invoke: (
envelope: UnknownEventEnvelope,
options?: EventDeliveryInvocationOptions,
) => Promise<unknown>;
}EventTriggerSnapshot (interface)
Safe trigger configuration and runtime delivery counters.
Signature
export interface EventTriggerSnapshot {
readonly ephemeral?: import("./ephemeral.js").EphemeralDeliverySnapshot;
readonly id: string;
readonly targetFunctionId?: string;
readonly eventId: string;
readonly eventVersion: number;
readonly delivery: "ephemeral" | "durable";
readonly profile?: string;
readonly retry?: RetryPolicy;
readonly concurrency?: number;
readonly timeoutMs?: number;
}router-records.ts
EVENT_DELIVERY_VERSION
Signature
declare const EVENT_DELIVERY_VERSION: 1;EventDeliveryRecord
Signature
declare const EventDeliveryRecord: EventDeliveryRecord;EventRouterStateError (class)
Preserves the public event router state error identity and stable error code.
Signature
declare class EventRouterStateError {
constructor(message: string);
}code (property)
Signature
readonly code: "RELKIT_EVENT_ROUTER_STATE_INVALID"appendDeliveryAcceptance
Appends delivery acceptance before acknowledging durable fanout.
Signature
declare const appendDeliveryAcceptance: (
store: JobStore,
envelope: UnknownEventEnvelope,
triggerId: string,
) => Promise<void>;makeDeliveryId
Derives a stable identity from the publication and target trigger.
Signature
declare const makeDeliveryId: (eventInstanceId: string, triggerId: string) => string;normalizeDelivery
Validates the durable or ephemeral delivery mode.
Signature
declare const normalizeDelivery: (value: unknown) => "ephemeral" | "durable";normalizeEnvelope
Validates the envelope and copies its JSON payload and safe attributes.
Signature
declare const normalizeEnvelope: (input: unknown) => UnknownEventEnvelope;toDeliveryRecord
Projects a durable journal record into its delivery identity and envelope.
Signature
declare const toDeliveryRecord: (record: JobRecord) => EventDeliveryRecord;toJson
Copies an unknown value into canonical JSON for stable durable encoding.
Signature
declare const toJson: (value: DeliveryData) => JsonValue;validateDeliveryData
Rejects malformed delivery identities or envelopes during record replay.
Signature
declare const validateDeliveryData: (value: JsonValue) => void;router-records.types.ts
DeliveryData (interface)
Versioned persisted delivery identity and canonical envelope payload.
Signature
export interface DeliveryData {
readonly version: typeof EVENT_DELIVERY_VERSION;
readonly deliveryId: string;
readonly eventInstanceId: string;
readonly triggerId: string;
readonly envelope: UnknownEventEnvelope;
}EventDeliveryRecord (interface)
Durable acceptance record connecting one publication and trigger.
Signature
export interface EventDeliveryRecord {
readonly version: typeof EVENT_DELIVERY_VERSION;
readonly sequence: number;
readonly timestamp: number;
readonly deliveryId: string;
readonly eventInstanceId: string;
readonly triggerId: string;
readonly envelope: UnknownEventEnvelope;
}router.ts
EVENT_DELIVERY_VERSION
Signature
declare const EVENT_DELIVERY_VERSION: 1;EventDeliveryRecord
Signature
declare const EventDeliveryRecord: EventDeliveryRecord;EventDeliveryResult
Signature
declare const EventDeliveryResult: EventDeliveryResult;EventFanoutResult
Signature
declare const EventFanoutResult: EventFanoutResult;EventRouter
Signature
declare const EventRouter: EventRouter;EventRouterInput
Signature
declare const EventRouterInput: EventRouterInput;EventRouterOptions
Signature
declare const EventRouterOptions: EventRouterOptions;EventRouterRouteOptions
Signature
declare const EventRouterRouteOptions: EventRouterRouteOptions;EventRouterSnapshot
Signature
declare const EventRouterSnapshot: EventRouterSnapshot;EventRouterStateError
Signature
declare const EventRouterStateError: typeof EventRouterStateError;EventRouterTrigger
Signature
declare const EventRouterTrigger: EventRouterTrigger;EventTriggerSnapshot
Signature
declare const EventTriggerSnapshot: EventTriggerSnapshot;createEventRouter
Routes accepted envelopes to independently delivered exact-event triggers.
Signature
declare const createEventRouter: (
requestedRoot: string,
options?: EventRouterOptions,
) => Promise<EventRouter>;index.ts
“./agent-state/index.js” (namespace export)
Re-exports all named exports from the “./agent-state/index.js” module.
Signature
export * from "./agent-state/index.js";“./buckets/index.js” (namespace export)
Re-exports all named exports from the “./buckets/index.js” module.
Signature
export * from "./buckets/index.js";“./cache/index.js” (namespace export)
Re-exports all named exports from the “./cache/index.js” module.
Signature
export * from "./cache/index.js";“./events/admin.js” (namespace export)
Re-exports all named exports from the “./events/admin.js” module.
Signature
export * from "./events/admin.js";“./events/log.js” (namespace export)
Re-exports all named exports from the “./events/log.js” module.
Signature
export * from "./events/log.js";“./events/router.js” (namespace export)
Re-exports all named exports from the “./events/router.js” module.
Signature
export * from "./events/router.js";“./jobs/admin.js” (namespace export)
Re-exports all named exports from the “./jobs/admin.js” module.
Signature
export * from "./jobs/admin.js";“./jobs/queue-utils.js” (namespace export)
Re-exports all named exports from the “./jobs/queue-utils.js” module.
Signature
export * from "./jobs/queue-utils.js";“./jobs/queue.js” (namespace export)
Re-exports all named exports from the “./jobs/queue.js” module.
Signature
export * from "./jobs/queue.js";“./jobs/retry.js” (namespace export)
Re-exports all named exports from the “./jobs/retry.js” module.
Signature
export * from "./jobs/retry.js";“./realtime/index.js” (namespace export)
Re-exports all named exports from the “./realtime/index.js” module.
Signature
export * from "./realtime/index.js";“./runtime-capabilities.js” (namespace export)
Re-exports all named exports from the “./runtime-capabilities.js” module.
Signature
export * from "./runtime-capabilities.js";CompiledSchedule
Signature
declare const CompiledSchedule: CompiledSchedule;DEFAULT_EPHEMERAL_CAPACITY
Signature
declare const DEFAULT_EPHEMERAL_CAPACITY: 100;DurableEventDeliveryResult
Signature
declare const DurableEventDeliveryResult: EventDeliveryResult;EPHEMERAL_DELIVERY_CAPABILITIES
Signature
declare const EPHEMERAL_DELIVERY_CAPABILITIES: Readonly<{
readonly persistence: "none";
readonly restartRecovery: false;
readonly dropPolicy: "drop-newest";
}>;EVENT_DELIVERY_CAPABILITIES
Signature
declare const EVENT_DELIVERY_CAPABILITIES: Readonly<{
readonly persistence: "restart-recovery";
readonly restartRecovery: true;
readonly atLeastOnce: true;
readonly exactlyOnce: false;
readonly ordering: "unsupported";
readonly orderedByKey: false;
}>;EphemeralDelivery
Signature
declare const EphemeralDelivery: EphemeralDelivery;EphemeralDeliveryResult
Signature
declare const EphemeralDeliveryResult: EphemeralDeliveryResult;EphemeralDeliverySnapshot
Signature
declare const EphemeralDeliverySnapshot: EphemeralDeliverySnapshot;EventDelivery
Signature
declare const EventDelivery: EventDelivery;EventDeliveryBinding
Signature
declare const EventDeliveryBinding: EventDeliveryBinding;EventDeliveryBoundary
Signature
declare const EventDeliveryBoundary: EventDeliveryBoundary;EventDeliveryLedgerRecord
Signature
declare const EventDeliveryLedgerRecord: EventDeliveryLedgerRecord;EventDeliveryOptions
Signature
declare const EventDeliveryOptions: EventDeliveryOptions;EventDeliverySnapshot
Signature
declare const EventDeliverySnapshot: EventDeliverySnapshot;JobRecord
Signature
declare const JobRecord: {
readonly version: 1;
readonly sequence: number;
readonly instanceId: string;
readonly kind: string;
readonly timestamp: number;
readonly data: Json;
};JobRecordInput
Signature
declare const JobRecordInput: JobRecordInput;JobStore
Signature
declare const JobStore: JobStore;JobStoreBoundary
Signature
declare const JobStoreBoundary: JobStoreBoundary;JobStoreCheckpoint
Signature
declare const JobStoreCheckpoint: {
readonly version: 1;
readonly commit: number;
readonly sequence: number;
readonly offset: number;
readonly recordCount: number;
};JobStoreIndex
Signature
declare const JobStoreIndex: {
readonly version: 1;
readonly commit: number;
readonly entries: {
readonly [x: string]: { readonly sequence: number; readonly offset: number };
};
};JobStoreOptions
Signature
declare const JobStoreOptions: JobStoreOptions;JobStoreSnapshot
Signature
declare const JobStoreSnapshot: JobStoreSnapshot;LocalEventProvider
Signature
declare const LocalEventProvider: LocalEventProvider;ScheduleEnqueue
Signature
declare const ScheduleEnqueue: ScheduleEnqueue;ScheduleEnqueueContext
Signature
declare const ScheduleEnqueueContext: ScheduleEnqueueContext;ScheduleRun
Signature
declare const ScheduleRun: ScheduleRun;ScheduleValidationError
Signature
declare const ScheduleValidationError: typeof ScheduleValidationError;Scheduler
Signature
declare const Scheduler: Scheduler;SchedulerClock
Signature
declare const SchedulerClock: SchedulerClock;SchedulerOptions
Signature
declare const SchedulerOptions: SchedulerOptions;SchedulerRegistration
Signature
declare const SchedulerRegistration: SchedulerRegistration;compileSchedule
Signature
declare const compileSchedule: (
schedule: ScheduleDefinition,
options?: { readonly currentDate?: Date },
) => CompiledSchedule;createEphemeralDelivery
Signature
declare const createEphemeralDelivery: (
invoke: (envelope: UnknownEventEnvelope) => Promise<unknown>,
requestedCapacity?: number,
) => EphemeralDelivery;createEventDelivery
Signature
declare const createEventDelivery: (
root: string,
binding: EventDeliveryBinding,
options?: EventDeliveryOptions,
) => Promise<EventDelivery>;createJobStore
Signature
declare const createJobStore: (
requestedRoot: string,
options?: JobStoreOptions,
) => Promise<JobStore>;createLocalEventProvider
Signature
declare const createLocalEventProvider: (root: string) => Promise<LocalEventProvider>;createScheduler
Signature
declare const createScheduler: (options?: SchedulerOptions) => Scheduler;admin-contracts.ts
JOB_ADMIN_PROTOCOL
Signature
declare const JOB_ADMIN_PROTOCOL: "relkit.jobs.admin";JOB_ADMIN_VERSION
Signature
declare const JOB_ADMIN_VERSION: 1;JobActionContract
Signature
declare const JobActionContract: JobActionContract;JobActionRequest
Signature
declare const JobActionRequest: JobActionRequest;JobAdminAction
Signature
declare const JobAdminAction: JobAdminAction;JobAdminActionOutcome
Signature
declare const JobAdminActionOutcome: JobAdminActionOutcome;JobAdminActionRecord
Signature
declare const JobAdminActionRecord: JobAdminActionRecord;JobAdminActionSink
Signature
declare const JobAdminActionSink: JobAdminActionSink;JobAdminMode
Signature
declare const JobAdminMode: JobAdminMode;JobAdminVersion
Signature
declare const JobAdminVersion: JobAdminVersion;JobCancelRequest
Signature
declare const JobCancelRequest: JobActionRequest;JobDeadLetterRequest
Signature
declare const JobDeadLetterRequest: JobActionRequest;JobQueryContract
Signature
declare const JobQueryContract: JobQueryContract;JobQueryRequest
Signature
declare const JobQueryRequest: JobQueryRequest;JobRetryRequest
Signature
declare const JobRetryRequest: JobActionRequest;JobStatusContract
Signature
declare const JobStatusContract: JobStatusContract;admin-contracts.types.ts
JobActionContract (interface)
Versioned job mutation result including status and audit record.
Signature
export interface JobActionContract extends JobAdminVersion {
readonly action: JobAdminAction;
readonly status: JobStatusContract;
readonly record: JobAdminActionRecord;
}JobActionRequest (interface)
Base job administration request with target identity and audit reason.
Signature
export interface JobActionRequest {
readonly protocol?: typeof JOB_ADMIN_PROTOCOL;
readonly version?: typeof JOB_ADMIN_VERSION;
readonly instanceId: string;
readonly reason?: string;
}JobAdminAction (type alias)
Supported audited queue administration action.
Signature
type JobAdminAction = "retry" | "cancel" | "dead-letter";JobAdminActionOutcome (type alias)
Whether an administration action was applied or rejected.
Signature
type JobAdminActionOutcome = "applied" | "rejected";JobAdminActionRecord (interface)
Immutable audit record retained for each applied or rejected job action.
Signature
export interface JobAdminActionRecord extends JobAdminVersion {
readonly actionId: string;
readonly action: JobAdminAction;
readonly instanceId: string;
readonly mode: JobAdminMode;
readonly outcome: JobAdminActionOutcome;
readonly requestedAt: number;
readonly fromState?: JobQueueState;
readonly toState?: JobQueueState;
readonly errorCode?: string;
readonly reason?: string;
}JobAdminActionSink (type alias)
Optional notification sink whose rejection cannot change the action outcome.
Signature
type JobAdminActionSink = (record: JobAdminActionRecord) => MaybePromise<void>;JobAdminMode (type alias)
Environment mode controlling local administration mutations.
Signature
type JobAdminMode = "development" | "test" | "production";JobAdminVersion (interface)
Protocol identity carried by job administration contracts.
Signature
export interface JobAdminVersion {
readonly protocol: typeof JOB_ADMIN_PROTOCOL;
readonly version: typeof JOB_ADMIN_VERSION;
}JobCancelRequest (type alias)
Job cancellation request with optional audit reason.
Signature
type JobCancelRequest = JobActionRequest;JobDeadLetterRequest (type alias)
Job dead-letter request with optional audit reason.
Signature
type JobDeadLetterRequest = JobActionRequest;JobQueryContract (interface)
Versioned bounded page of safe job status records.
Signature
export interface JobQueryContract extends JobAdminVersion {
readonly items: readonly JobStatusContract[];
readonly counts: JobQueueCounts;
readonly nextCursor?: string;
}JobQueryRequest (interface)
Optional identity, state and pagination filters for job inspection.
Signature
export interface JobQueryRequest {
readonly protocol?: typeof JOB_ADMIN_PROTOCOL;
readonly version?: typeof JOB_ADMIN_VERSION;
readonly instanceId?: string;
readonly state?: JobQueueState;
readonly states?: readonly JobQueueState[];
readonly cursor?: string;
readonly limit?: number;
}JobRetryRequest (type alias)
Job retry request with optional policy override.
Signature
type JobRetryRequest = JobActionRequest;JobStatusContract (interface)
Safe, versioned state returned to inspector consumers.
Signature
export interface JobStatusContract extends JobAdminVersion {
readonly instanceId: string;
readonly state: JobQueueState;
readonly profile: string;
readonly attempt: number;
readonly acceptedAt: number;
readonly order: number;
readonly availableAt?: number;
readonly leaseExpiresAt?: number;
readonly idempotencyExpiresAt?: number;
readonly failure?: JobFailureMetadata;
}admin-errors.ts
Preserves the public job admin error identity and stable error code.
JobAdminError (class)
Preserves the public job admin error identity and stable error code.
Signature
declare class JobAdminError { constructor(
readonly code: string,
message: string,
) }admin.ts
“./admin-contracts.js” (namespace export)
Re-exports all named exports from the “./admin-contracts.js” module.
Signature
export * from "./admin-contracts.js";JobAdmin
Signature
declare const JobAdmin: JobAdmin;JobAdminError
Signature
declare const JobAdminError: typeof JobAdminError;JobAdminOptions
Signature
declare const JobAdminOptions: JobAdminOptions;createJobAdmin
Exposes versioned local job inspection and explicitly audited mutations.
Signature
declare const createJobAdmin: (queue: JobQueue, options?: JobAdminOptions) => JobAdmin;admin.types.ts
JobAdmin (interface)
Versioned job inspection and audited development mutation interface.
Signature
export interface JobAdmin {
readonly protocol: typeof JOB_ADMIN_PROTOCOL;
readonly version: typeof JOB_ADMIN_VERSION;
readonly status: (instanceId: string) => JobStatusContract | undefined;
readonly query: (request?: JobQueryRequest) => JobQueryContract;
readonly retry: (request: string | JobActionRequest) => Promise<JobActionContract>;
readonly cancel: (request: string | JobActionRequest) => Promise<JobActionContract>;
readonly deadLetter: (request: string | JobActionRequest) => Promise<JobActionContract>;
readonly actions: () => readonly JobAdminActionRecord[];
}JobAdminOptions (interface)
Local administration mode and isolated audit/clock hooks.
Signature
export interface JobAdminOptions {
readonly mode?: JobAdminMode;
readonly environment?: JobAdminMode;
readonly enabled?: boolean;
readonly now?: () => number;
readonly createActionId?: () => string;
readonly onAction?: JobAdminActionSink;
}queue-utils.ts
JOB_QUEUE_STATES
Signature
declare const JOB_QUEUE_STATES: readonly [
"accepted",
"available",
"leased",
"delayed",
"completed",
"dead-lettered",
];JobFailureKind
Signature
declare const JobFailureKind: JobFailureKind;JobFailureMetadata
Signature
declare const JobFailureMetadata: JobFailureMetadata;JobFailureOutcome
Signature
declare const JobFailureOutcome: JobFailureOutcome;JobFailureRetry
Signature
declare const JobFailureRetry: JobFailureRetry;JobIdempotencyDefinition
Signature
declare const JobIdempotencyDefinition: JobIdempotencyDefinition;JobIdempotencyRecord
Signature
declare const JobIdempotencyRecord: JobIdempotencyRecord;JobQueue
Signature
declare const JobQueue: JobQueue;JobQueueAcceptance
Signature
declare const JobQueueAcceptance: JobQueueAcceptance;JobQueueAdminRetryOptions
Signature
declare const JobQueueAdminRetryOptions: JobQueueAdminRetryOptions;JobQueueCounts
Signature
declare const JobQueueCounts: Readonly<
Record<"accepted" | "completed" | "available" | "leased" | "delayed" | "dead-lettered", number>
>;JobQueueEnqueue
Signature
declare const JobQueueEnqueue: JobQueueEnqueue;JobQueueEntry
Signature
declare const JobQueueEntry: JobQueueEntry;JobQueueLeaseOptions
Signature
declare const JobQueueLeaseOptions: JobQueueLeaseOptions;JobQueueOptions
Signature
declare const JobQueueOptions: JobQueueOptions;JobQueueState
Signature
declare const JobQueueState:
"accepted" | "completed" | "available" | "leased" | "delayed" | "dead-lettered";JobQueueStateError (class)
Preserves the public job queue state error identity and stable error code.
Signature
declare class JobQueueStateError {
constructor(message: string);
}code (property)
Signature
readonly code: "RELKIT_JOB_QUEUE_STATE_INVALID"JobQueueTransitionOptions
Signature
declare const JobQueueTransitionOptions: JobQueueTransitionOptions;JobState
Signature
declare const JobState:
"accepted" | "completed" | "available" | "leased" | "delayed" | "dead-lettered";MutableQueueState
Signature
declare const MutableQueueState: MutableQueueState;assertTime
Rejects times outside the nonnegative safe millisecond range.
Signature
declare const assertTime: (value: number, label: string) => void;transitions
Signature
declare const transitions: Readonly<
Record<
"accepted" | "completed" | "available" | "leased" | "delayed" | "dead-lettered",
ReadonlyArray<"accepted" | "completed" | "available" | "leased" | "delayed" | "dead-lettered">
>
>;queue-utils.types.ts
JobFailureKind (type alias)
Public classification of a failed queue attempt.
Signature
type JobFailureKind = "application" | "provider" | "cancellation" | "timeout" | "defect";JobFailureMetadata (interface)
Public, JSON-safe failure data retained with a delayed or dead-lettered job.
Signature
export interface JobFailureMetadata {
readonly kind: JobFailureKind;
readonly outcome: JobFailureOutcome;
readonly code: string;
readonly message: string;
readonly data?: JsonValue;
readonly status?: number;
readonly retry?: JobFailureRetry;
readonly afterMs?: number;
}JobFailureOutcome (type alias)
Public terminal or retry outcome of a failed queue attempt.
Signature
type JobFailureOutcome = "declared-error" | "provider-failure" | "cancelled" | "timeout" | "defect";JobFailureRetry (type alias)
Retry hint retained in safe failure metadata.
Signature
type JobFailureRetry = "never" | "later";JobIdempotencyDefinition (interface)
Caller deduplication identity and retention policy for a queue acceptance.
Signature
export interface JobIdempotencyDefinition {
readonly key: string;
readonly retentionMs: number;
}JobIdempotencyRecord (interface)
Persisted acceptance identity and expiry used for deduplication.
Signature
export interface JobIdempotencyRecord {
readonly key: string;
readonly expiresAt: number;
}JobQueue (interface)
Promise mutation and synchronous inspection contract for one durable queue.
Signature
export interface JobQueue {
readonly ownerToken: string;
readonly ready: () => Promise<void>;
readonly enqueue: (input: JobQueueEnqueue) => Promise<JobQueueAcceptance>;
readonly acquire: (
instanceId?: string,
options?: JobQueueLeaseOptions,
) => Promise<JobQueueEntry | undefined>;
readonly renew: (instanceId: string, options?: JobQueueLeaseOptions) => Promise<JobQueueEntry>;
readonly transition: (
instanceId: string,
state: JobQueueState,
options?: JobQueueTransitionOptions,
) => Promise<JobQueueEntry>;
/** Requeues one dead letter as a fresh attempt without widening normal transitions. */
readonly adminRetry: (
instanceId: string,
options?: JobQueueAdminRetryOptions,
) => Promise<JobQueueEntry>;
/** Moves one eligible nonterminal entry to a dead letter with safe metadata. */
readonly adminDeadLetter: (
instanceId: string,
failure: JobFailureMetadata,
) => Promise<JobQueueEntry>;
readonly recover: (now?: number) => Promise<readonly JobQueueEntry[]>;
readonly expire: (now?: number) => Promise<readonly JobQueueEntry[]>;
readonly selectAvailable: (limit?: number, now?: number) => readonly JobQueueEntry[];
readonly get: (instanceId: string) => JobQueueEntry | undefined;
readonly counts: () => JobQueueCounts;
readonly snapshot: () => readonly JobQueueEntry[];
}JobQueueAcceptance (interface)
Durable acceptance information returned by queue admission.
Signature
export interface JobQueueAcceptance extends JobQueueEntry {
readonly accepted: true;
readonly duplicate: boolean;
readonly idempotencyKey?: string;
readonly idempotencyExpiresAt?: number;
}JobQueueAdminRetryOptions (interface)
Administrative retry preconditions and next-availability settings.
Signature
export interface JobQueueAdminRetryOptions {
readonly availableAt?: number;
}JobQueueCounts (type alias)
Entry counts grouped by durable queue lifecycle state.
Signature
type JobQueueCounts = Readonly<Record<JobQueueState, number>>;JobQueueEnqueue (interface)
Input required to accept a job into the local durable queue.
Signature
export interface JobQueueEnqueue {
readonly input: JsonValue;
readonly profile?: string;
readonly instanceId?: string;
readonly acceptedAt?: number;
readonly idempotency?: JobIdempotencyDefinition;
readonly propagation?: TracePropagation;
}JobQueueEntry (interface)
Durable queue state including acceptance, lease, retry and failure metadata.
Signature
export interface JobQueueEntry {
readonly instanceId: string;
readonly state: JobQueueState;
readonly input: JsonValue;
readonly profile: string;
readonly attempt: number;
readonly acceptedAt: number;
readonly order: number;
readonly availableAt?: number;
readonly leaseOwner?: string;
readonly leaseExpiresAt?: number;
readonly idempotency?: JobIdempotencyRecord;
readonly failure?: JobFailureMetadata;
readonly propagation?: TracePropagation;
}JobQueueLeaseOptions (interface)
Caller ownership and duration settings for acquiring a lease.
Signature
export interface JobQueueLeaseOptions {
readonly leaseDurationMs?: number;
readonly leaseExpiresAt?: number;
}JobQueueOptions (interface)
Clock, persistence and policy options for a local queue.
Signature
export interface JobQueueOptions {
readonly now?: () => number;
readonly createInstanceId?: () => string;
readonly ownerToken?: string;
readonly leaseDurationMs?: number;
readonly idempotency?: JobIdempotencyDefinition;
}JobQueueState (type alias)
Persisted lifecycle states supported by the local durable queue.
Signature
type JobQueueState = (typeof JOB_QUEUE_STATES)[number];JobQueueTransitionOptions (interface)
Expected state, ownership and metadata for a durable transition.
Signature
export interface JobQueueTransitionOptions extends JobQueueLeaseOptions {
readonly expectedState?: JobQueueState;
readonly attempt?: number;
readonly availableAt?: number;
readonly leaseOwner?: string;
readonly failure?: JobFailureMetadata;
}JobState (type alias)
Compatibility alias for the durable queue lifecycle state.
Signature
type JobState = JobQueueState;MutableQueueState (interface)
In-memory queue index and next acceptance order owned by serialized mutations.
Signature
export interface MutableQueueState {
readonly entries: Map<string, JobQueueEntry>;
nextOrder: number;
}queue.ts
“./queue-utils.js” (namespace export)
Re-exports all named exports from the “./queue-utils.js” module.
Signature
export * from "./queue-utils.js";JOB_QUEUE_STATES
Signature
declare const JOB_QUEUE_STATES: readonly [
"accepted",
"available",
"leased",
"delayed",
"completed",
"dead-lettered",
];JobQueueStateError
Signature
declare const JobQueueStateError: typeof JobQueueStateError;createJobQueue
Provides durable queue state plus process-owned leases.
Signature
declare const createJobQueue: (store: JobStore, options?: JobQueueOptions) => JobQueue;retry.ts
RandomSource
Signature
declare const RandomSource: RandomSource;RetryClassification
Signature
declare const RetryClassification: RetryClassification;RetryOptions
Signature
declare const RetryOptions: RetryOptions;RetryPlan
Signature
declare const RetryPlan: RetryPlan;RetryState
Signature
declare const RetryState: RetryState;applyRetry
Applies one leased attempt’s retry/dead-letter outcome durably.
Signature
declare const applyRetry: (
queue: Pick<JobQueue, "get" | "transition">,
instanceId: string,
policy: RetryPolicy,
failure: unknown,
options?: RetryOptions,
) => Promise<JobQueueEntry>;calculateRetryDelay
Calculates a bounded, integer delay for a one-based completed attempt.
Signature
declare const calculateRetryDelay: (
policy: RetryPolicy,
attempt: number,
random?: RandomSource,
) => number;classifyFailure
Uses the declared error policy; non-declared failures are not retried.
Signature
declare const classifyFailure: (value: unknown) => RetryClassification;planRetry
Combines normalized failure classification, attempt limits and retry jitter into a retry plan.
Signature
declare const planRetry: (
policy: RetryPolicy,
attempt: number,
failure: unknown,
options?: Pick<RetryOptions, "random">,
) => RetryPlan;safeFailureMetadata
Copies the public failure envelope so persisted metadata cannot retain arbitrary error objects.
Signature
declare const safeFailureMetadata: (value: unknown) => JobFailureMetadata;retry.types.ts
RandomSource (type alias)
Replaceable source of values in [0, 1) for deterministic jitter.
Signature
type RandomSource = () => number;RetryClassification (type alias)
Whether the normalized failure permits another attempt.
Signature
type RetryClassification = "retryable" | "non-retryable";RetryOptions (interface)
Clock, jitter and transition options for applying retry policy.
Signature
export interface RetryOptions {
readonly now?: () => number;
readonly random?: RandomSource;
}RetryPlan (interface)
Validated retry classification, delay and safe failure metadata.
Signature
export interface RetryPlan {
readonly classification: RetryClassification;
readonly state: RetryState;
readonly attempt: number;
readonly delayMs: number;
readonly failure: JobFailureMetadata;
}RetryState (type alias)
Durable queue outcome selected by retry policy.
Signature
type RetryState = "delayed" | "dead-lettered";schedule-definition.ts
ScheduleValidationError (class)
Preserves the public schedule validation error identity and stable error code.
Signature
declare class ScheduleValidationError {
constructor(message: string);
}code (property)
Signature
readonly code: "RELKIT_SCHEDULE_INVALID"compileSchedule
Validates a static schedule and hides the cron parser behind native dates.
Signature
declare const compileSchedule: (
schedule: ScheduleDefinition,
options?: { readonly currentDate?: Date },
) => CompiledSchedule;isRecord
Checks for a non-null, non-array object before inspecting unknown fields.
Signature
declare const isRecord: (value: unknown) => value is Record<string, any>;parseNext
Computes the next cron occurrence within the configured timezone.
Signature
declare const parseNext: (cron: string, timezone: string, currentDate: Date) => Date;requiredText
Rejects missing or blank schedule identifiers.
Signature
declare const requiredText: (value: unknown, name: string) => string;validDate
Rejects invalid clock dates before scheduling work.
Signature
declare const validDate: (value: Date, name: string) => Date;scheduler.ts
CompiledSchedule
Signature
declare const CompiledSchedule: CompiledSchedule;LocalSchedulerService (class)
Owns schedule registrations, next-fire positions and active overlap counters.
Signature
declare class LocalSchedulerServiceScheduleEnqueue
Signature
declare const ScheduleEnqueue: ScheduleEnqueue;ScheduleEnqueueContext
Signature
declare const ScheduleEnqueueContext: ScheduleEnqueueContext;ScheduleRun
Signature
declare const ScheduleRun: ScheduleRun;ScheduleValidationError
Signature
declare const ScheduleValidationError: typeof ScheduleValidationError;Scheduler
Signature
declare const Scheduler: Scheduler;SchedulerClock
Signature
declare const SchedulerClock: SchedulerClock;SchedulerOptions
Signature
declare const SchedulerOptions: SchedulerOptions;SchedulerRegistration
Signature
declare const SchedulerRegistration: SchedulerRegistration;compileSchedule
Signature
declare const compileSchedule: (
schedule: ScheduleDefinition,
options?: { readonly currentDate?: Date },
) => CompiledSchedule;createScheduler
Runs due schedules against an injected clock without owning or calling handlers.
Signature
declare const createScheduler: (options?: SchedulerOptions) => Scheduler;makeSchedulerService
Creates lazy registration, inspection and due-work operations over one owned state.
Signature
declare const makeSchedulerService: (
options?: SchedulerOptions | undefined,
) => Effect.Effect<SchedulerEffects, LocalOperationError, never>;schedulerLayer
Provides an explicitly driven scheduler without starting an automatic timer.
Example
import { Effect } from "effect";
import { LocalSchedulerService, schedulerLayer } from "./scheduler.js";
const program = Effect.gen(function* () {
const scheduler = yield* LocalSchedulerService;
return yield* scheduler.runDue();
});
await Effect.runPromise(program.pipe(Effect.provide(schedulerLayer())));Signature
declare const schedulerLayer: (
options?: SchedulerOptions,
) => Layer.Layer<LocalSchedulerService, LocalOperationError, never>;scheduler.types.ts
CompiledSchedule (interface)
Validated cron schedule with its normalized timezone and identity.
Signature
export interface CompiledSchedule {
readonly id: string;
readonly cron: string;
readonly timezone: string;
readonly input: JsonValue;
readonly overlap: ScheduleOverlap;
readonly nextFireAt: Date;
readonly nextFire: (currentDate: Date) => Date;
}ScheduleEnqueue (type alias)
The scheduler only emits work through the common job enqueue/invocation seam.
Signature
type ScheduleEnqueue = (input: JsonValue, context: ScheduleEnqueueContext) => MaybePromise<unknown>;ScheduleEnqueueContext (interface)
Occurrence identity and time supplied when enqueueing scheduled work.
Signature
export interface ScheduleEnqueueContext {
readonly scheduleId: string;
readonly fireAt: Date;
}ScheduleRun (interface)
Result of processing one due schedule occurrence.
Signature
export interface ScheduleRun {
readonly scheduleId: string;
readonly fireAt: Date;
readonly status: "enqueued" | "skipped";
readonly result?: unknown;
}ScheduleState (interface)
Registered schedule and its current next-fire/overlap bookkeeping.
Signature
export interface ScheduleState {
readonly compiled: CompiledSchedule;
readonly enqueue: ScheduleEnqueue;
nextFireAt: number;
active: number;
}Scheduler (interface)
Explicitly driven scheduler with registration, due-work execution and inspection.
Signature
export interface Scheduler {
readonly register: (schedule: ScheduleDefinition, enqueue: ScheduleEnqueue) => CompiledSchedule;
readonly nextFire: (scheduleId: string) => Date | undefined;
readonly runDue: (currentDate?: Date | number) => Promise<readonly ScheduleRun[]>;
readonly tick: (currentDate?: Date | number) => Promise<readonly ScheduleRun[]>;
}SchedulerClock (interface)
Replaceable clock used by scheduler calculations.
Signature
export interface SchedulerClock {
readonly now: () => Date | number;
}SchedulerEffects (type alias)
Lazy scheduler operations shared by live composition and deterministic test substitutes.
Signature
type SchedulerEffects = {
readonly [K in keyof Scheduler]: Scheduler[K] extends (...args: infer A) => infer R
? (...args: A) => Effect.Effect<Awaited<R>, LocalOperationError>
: never;
};SchedulerOptions (interface)
Clock and scheduling behavior supplied by the local scheduler owner.
Signature
export interface SchedulerOptions {
readonly clock?: SchedulerClock;
readonly now?: () => Date | number;
readonly schedules?: readonly SchedulerRegistration[];
}SchedulerRegistration (interface)
Schedule declaration paired with its enqueue callback.
Signature
export interface SchedulerRegistration {
readonly schedule: ScheduleDefinition;
readonly enqueue: ScheduleEnqueue;
}store.ts
JobIndexEntry
Signature
declare const JobIndexEntry: { readonly sequence: number; readonly offset: number };JobRecord
Signature
declare const JobRecord: {
readonly version: 1;
readonly sequence: number;
readonly instanceId: string;
readonly kind: string;
readonly timestamp: number;
readonly data: Json;
};JobRecordInput
Signature
declare const JobRecordInput: JobRecordInput;JobStore
Signature
declare const JobStore: JobStore;JobStoreBoundary
Signature
declare const JobStoreBoundary: JobStoreBoundary;JobStoreCheckpoint
Signature
declare const JobStoreCheckpoint: {
readonly version: 1;
readonly commit: number;
readonly sequence: number;
readonly offset: number;
readonly recordCount: number;
};JobStoreEffects
Signature
declare const JobStoreEffects: JobStoreEffects;JobStoreIndex
Signature
declare const JobStoreIndex: {
readonly version: 1;
readonly commit: number;
readonly entries: {
readonly [x: string]: { readonly sequence: number; readonly offset: number };
};
};JobStoreOptions
Signature
declare const JobStoreOptions: JobStoreOptions;JobStoreSnapshot
Signature
declare const JobStoreSnapshot: JobStoreSnapshot;JobStoreStateError (class)
Preserves the public job store state error identity and stable error code.
Signature
declare class JobStoreStateError {
constructor(message: string);
}code (property)
Signature
readonly code: "RELKIT_JOB_STORE_STATE_INVALID"LocalJobStoreService (class)
A durable journal whose serialization and lifecycle have one owner.
Signature
declare class LocalJobStoreServiceSTORE_VERSION
Signature
declare const STORE_VERSION: 1;createJobStore
Opens the journal through the established Promise interface.
Signature
declare const createJobStore: (
requestedRoot: string,
options?: JobStoreOptions,
) => Promise<JobStore>;jobStoreLayer
Supplies and closes a durable journal through a scope-owned layer.
Example
import { Effect } from "effect";
import { LocalJobStoreService, jobStoreLayer } from "./store.js";
const program = Effect.gen(function* () {
const journal = yield* LocalJobStoreService;
return yield* journal.snapshot();
});
await Effect.runPromise(program.pipe(Effect.provide(jobStoreLayer("/tmp/example-journal"))));Signature
declare const jobStoreLayer: (
root: string,
options?: JobStoreOptions,
) => Layer.Layer<LocalJobStoreService, LocalOperationError, never>;makeJobStore
Recovers a journal before exposing serialized append operations.
Signature
declare const makeJobStore: (
requestedRoot: string,
options?: JobStoreOptions | undefined,
) => Effect.Effect<JobStoreEffects, LocalOperationError, never>;store.types.ts
JobIndexEntry (type alias)
Latest record sequence and byte offset for one job instance.
Signature
type JobIndexEntry = typeof JobIndexEntrySchema.Type;JobRecord (type alias)
Versioned durable journal record with ordered sequence and timestamp.
Signature
type JobRecord = typeof JobRecordSchema.Type;JobRecordInput (interface)
Canonical JSON record input before sequence and timestamp assignment.
Signature
export interface JobRecordInput {
readonly instanceId: string;
readonly kind: string;
readonly data: JsonValue;
readonly timestamp?: number;
}JobStore (interface)
Compatibility journal interface with durable append and explicit close.
Signature
export interface JobStore {
readonly root: string;
readonly paths: Readonly<ReturnType<typeof createJobStorePaths>>;
readonly append: (input: JobRecordInput) => Promise<JobRecord>;
readonly snapshot: () => JobStoreSnapshot;
readonly close: () => Promise<void>;
}JobStoreBoundary (type alias)
Durable commit milestones available to fault-injection and observation hooks.
Signature
type JobStoreBoundary = "record-fsynced" | "index-committed" | "checkpoint-committed";JobStoreCheckpoint (type alias)
Committed sequence, record count and byte offset used for recovery.
Signature
type JobStoreCheckpoint = typeof JobCheckpointSchema.Type;JobStoreEffects (interface)
Effect operations for a durable journal and its committed snapshot.
Signature
export interface JobStoreEffects {
readonly root: string;
readonly paths: JobStore["paths"];
readonly append: (input: JobRecordInput) => Effect.Effect<JobRecord, LocalOperationError>;
readonly snapshot: () => Effect.Effect<JobStoreSnapshot>;
readonly close: () => Effect.Effect<void>;
}JobStoreIndex (type alias)
Versioned index rebuilt from the durable journal.
Signature
type JobStoreIndex = typeof JobIndexSchema.Type;JobStoreOptions (interface)
Clock, record validation and durable-boundary hooks for journal ownership.
Signature
export interface JobStoreOptions {
readonly now?: () => number;
/** Test-only failure seam; an error rejects append before acknowledgement. */
readonly onBoundary?: (boundary: JobStoreBoundary) => void | Promise<void>;
/** Optional semantic guard used by durable stores layered on this record format. */
readonly validateData?: (data: JsonValue) => void;
}JobStoreSnapshot (interface)
Immutable recovered records, index and checkpoint.
Signature
export interface JobStoreSnapshot {
readonly records: readonly JobRecord[];
readonly index: JobStoreIndex;
readonly checkpoint: JobStoreCheckpoint;
}common.ts
LocalRealtimeError (class)
Preserves the public local realtime error identity and stable error code.
Signature
declare class LocalRealtimeError { constructor(
readonly code: string,
message: string,
) }checkpoint
Builds the current journal checkpoint from the persisted sequence.
Signature
declare const checkpoint: (
scope: RealtimeScope,
state: LocalRealtimeState,
sequence: number,
historyStart: number,
expiresAt: string,
) => ChannelCheckpoint;emptyPartition
Creates an empty retained event and presence partition.
Signature
declare const emptyPartition: (sequence: number) => StoredRealtimePartition;encodedBytes
Measures canonical JSON bytes for admission limits.
Signature
declare const encodedBytes: (value: unknown) => number;partitionKey
Encodes the channel and scope into a stable realtime partition key.
Signature
declare const partitionKey: (scope: RealtimeScope) => string;prunePartition
Removes expired events and enforces retention bounds without renumbering sequences.
Signature
declare const prunePartition: (
partition: StoredRealtimePartition,
now: number,
) => StoredRealtimePartition;scopeGap
Constructs a replay gap describing the requested checkpoint and current scope.
Signature
declare const scopeGap: (
expected: RealtimeScope,
actual: ChannelCheckpoint,
providerEpoch: string,
) => "foreign" | "policy" | "session" | "provider-reset" | undefined;provider.ts
LocalRealtimeProviderOptions
Signature
declare const LocalRealtimeProviderOptions: LocalRealtimeProviderOptions;LocalRealtimeService (class)
Realtime operations sharing one persisted-state transaction owner.
Signature
declare class LocalRealtimeServicecreateLocalRealtimeProvider
Provides realtime operations using filesystem-shared state.
Signature
declare const createLocalRealtimeProvider: (
root: string,
options?: LocalRealtimeProviderOptions,
) => RealtimeProvider;createRealtimeProviderFromStore
Substitutes an existing Promise storage adapter at the compatibility edge.
Signature
declare const createRealtimeProviderFromStore: (
store: RealtimeStateStore,
pollingMs?: number,
) => RealtimeProvider;makeRealtimeService
Composes realtime behavior over an Effect transaction interface.
Signature
declare const makeRealtimeService: (
store: RealtimeStateStoreEffects,
pollingMs?: number,
) => RealtimeEffects;realtimeLayer
Builds one live realtime service through a substitutable layer.
Example
import { Effect } from "effect";
import { LocalRealtimeService, realtimeLayer } from "./provider.js";
const program = Effect.gen(function* () {
const realtime = yield* LocalRealtimeService;
return yield* realtime.getEpoch();
});
await Effect.runPromise(program.pipe(Effect.provide(realtimeLayer("/tmp/example-realtime"))));Signature
declare const realtimeLayer: (
root: string,
pollingMs?: number,
) => Layer.Layer<LocalRealtimeService, LocalOperationError, never>;provider.types.ts
LocalRealtimeProviderOptions (interface)
Polling configuration for filesystem-shared realtime observations.
Signature
export interface LocalRealtimeProviderOptions {
readonly pollingMs?: number;
}RealtimeEffects (type alias)
Effect methods corresponding to the established realtime provider surface.
Signature
type RealtimeEffects = {
readonly [K in Exclude<keyof RealtimeProvider, "capabilities">]: RealtimeProvider[K] extends (
...args: infer A
) => infer R
? (...args: A) => Effect.Effect<Awaited<R>, LocalOperationError>
: never;
};state.ts
LOCAL_REALTIME_STATE_VERSION
Signature
declare const LOCAL_REALTIME_STATE_VERSION: 2;LocalRealtimeState
Signature
declare const LocalRealtimeState: {
readonly version: 2;
readonly providerEpoch: string;
readonly sequence: number;
readonly revision: number;
readonly retainedBytes: number;
readonly partitions: {
readonly [x: string]: {
readonly historyStart: number;
readonly events: ReadonlyArray<{
readonly sequence: number;
readonly eventId: string;
readonly event: string;
readonly payload: unknown;
readonly encodedBytes: number;
readonly createdAt: string;
readonly expiresAt: string;
}>;
readonly presence: ReadonlyArray<{
readonly expiresAt: string;
readonly leaseId: string;
readonly connectionId: string;
readonly opaqueMemberId?: string;
readonly memberInfo?: unknown;
}>;
};
};
readonly receipts: {
readonly [x: string]: {
readonly semanticDigest: string;
readonly expiresAt: string;
readonly receipt: {
readonly accepted: true;
readonly profile: string;
readonly providerEpoch: string;
readonly checkpoint: {
readonly applicationId: string;
readonly environment: string;
readonly profile: string;
readonly providerEpoch: string;
readonly sequence: string;
readonly expiresAt: string;
readonly historyStart: string;
readonly channelId: string;
readonly partition: string;
readonly policyEpoch: string;
readonly identityScope: string;
readonly sessionEpoch: string;
readonly tenantScope?: string;
};
readonly duplicate: boolean;
readonly eventId: string;
readonly operationId?: OperationId;
};
};
};
};StoredAppendReceipt
Signature
declare const StoredAppendReceipt: {
readonly semanticDigest: string;
readonly expiresAt: string;
readonly receipt: {
readonly accepted: true;
readonly profile: string;
readonly providerEpoch: string;
readonly checkpoint: {
readonly applicationId: string;
readonly environment: string;
readonly profile: string;
readonly providerEpoch: string;
readonly sequence: string;
readonly expiresAt: string;
readonly historyStart: string;
readonly channelId: string;
readonly partition: string;
readonly policyEpoch: string;
readonly identityScope: string;
readonly sessionEpoch: string;
readonly tenantScope?: string;
};
readonly duplicate: boolean;
readonly eventId: string;
readonly operationId?: OperationId;
};
};StoredPresenceLease
Signature
declare const StoredPresenceLease: {
readonly expiresAt: string;
readonly leaseId: string;
readonly connectionId: string;
readonly opaqueMemberId?: string;
readonly memberInfo?: unknown;
};StoredRealtimeEvent
Signature
declare const StoredRealtimeEvent: {
readonly sequence: number;
readonly eventId: string;
readonly event: string;
readonly payload: unknown;
readonly encodedBytes: number;
readonly createdAt: string;
readonly expiresAt: string;
};StoredRealtimePartition
Signature
declare const StoredRealtimePartition: {
readonly historyStart: number;
readonly events: ReadonlyArray<{
readonly sequence: number;
readonly eventId: string;
readonly event: string;
readonly payload: unknown;
readonly encodedBytes: number;
readonly createdAt: string;
readonly expiresAt: string;
}>;
readonly presence: ReadonlyArray<{
readonly expiresAt: string;
readonly leaseId: string;
readonly connectionId: string;
readonly opaqueMemberId?: string;
readonly memberInfo?: unknown;
}>;
};emptyRealtimeState
Creates format-v1 realtime state with an epoch and empty partition/receipt indexes.
Signature
declare const emptyRealtimeState: (epoch?: string) => LocalRealtimeState;state.types.ts
LocalRealtimeState (type alias)
Complete validated version-two realtime snapshot.
Signature
type LocalRealtimeState = typeof RealtimeState.Type;StoredAppendReceipt (type alias)
Idempotent append acknowledgement with semantic digest and expiry.
Signature
type StoredAppendReceipt = typeof AppendReceipt.Type;StoredPresenceLease (type alias)
Connection lease decoded before expiry and capacity decisions.
Signature
type StoredPresenceLease = typeof PresenceLease.Type;StoredRealtimeEvent (type alias)
Stored ordered event whose application payload remains opaque.
Signature
type StoredRealtimeEvent = typeof RealtimeEvent.Type;StoredRealtimePartition (type alias)
Atomic partition history and presence representation.
Signature
type StoredRealtimePartition = typeof RealtimePartition.Type;storage.types.ts
RealtimeStateStore (interface)
Existing Promise transaction seam for third-party storage adapters.
Signature
export interface RealtimeStateStore {
readonly read: () => Promise<LocalRealtimeState>;
readonly update: <Value>(
change: (state: LocalRealtimeState) => {
readonly state: LocalRealtimeState;
readonly value: Value;
},
) => Promise<Value>;
}RealtimeStateStoreEffects (interface)
Effect operations sharing one transactional initialization and lock owner.
Signature
export interface RealtimeStateStoreEffects {
readonly read: () => Effect.Effect<LocalRealtimeState, LocalOperationError>;
readonly update: <Value>(
change: (state: LocalRealtimeState) => {
readonly state: LocalRealtimeState;
readonly value: Value;
},
) => Effect.Effect<Value, LocalOperationError>;
}runtime-capabilities.ts
LocalJobProvider
Signature
declare const LocalJobProvider: LocalJobProvider;createLocalJobProvider
Creates a profile-owned durable queue provider through its established synchronous constructor.
Signature
declare const createLocalJobProvider: {
(root: string, profile: string): LocalJobProvider;
(root: string, profile: string, executionModel: "task"): JobsAdapterRuntime;
};createLocalObservabilityProvider
Creates an isolated synchronous JSON collector without recursively observing sink writes.
Signature
declare const createLocalObservabilityProvider: () => Readonly<{
collect: (record: JsonValue) => void;
emit: (record: JsonValue) => void;
read: () => readonly JsonValue[];
}>;runtime-capabilities.types.ts
LocalJobProvider (interface)
Public local native-job adapter with worker and lifecycle capabilities.
Signature
export interface LocalJobProvider {
readonly createQueue: (context: {
readonly jobId: string;
readonly idempotency?: JobIdempotencyDefinition;
}) => Promise<JobQueue>;
readonly close: () => Promise<void>;
}