Context.Reference<ReadonlyRecord<string, unknown>>Context reference for managing log annotations that are automatically added to all log entries. These annotations provide contextual metadata that appears in every log message.
When to use
Use to attach shared contextual metadata to every log entry emitted in the current context.
Example (Managing log annotations)
import { Console, Effect, References } from "effect"
const logAnnotationExample = Effect.gen(function*() {
// Get current annotations (empty by default)
const current = yield* References.CurrentLogAnnotations
console.log(current) // {}
// Run with custom log annotations
yield* Effect.provideService(
Effect.gen(function*() {
const annotations = yield* References.CurrentLogAnnotations
console.log(annotations) // { requestId: "req-123", userId: "user-456", version: "1.0.0" }
// All log entries will include these annotations
yield* Console.log("Starting operation")
yield* Console.info("Processing data")
}),
References.CurrentLogAnnotations,
{
requestId: "req-123",
userId: "user-456",
version: "1.0.0"
}
)
// Run with extended annotations
yield* Effect.provideService(
Effect.gen(function*() {
const extended = yield* References.CurrentLogAnnotations
console.log(extended) // { requestId: "req-123", userId: "user-456", version: "1.0.0", operation: "data-sync", timestamp: 1234567890 }
yield* Console.log("Operation completed with extended context")
}),
References.CurrentLogAnnotations,
{
requestId: "req-123",
userId: "user-456",
version: "1.0.0",
operation: "data-sync",
timestamp: 1234567890
}
)
})export const const CurrentLogAnnotations: Context.Reference<
ReadonlyRecord<string, unknown>
>
const CurrentLogAnnotations: {
defaultValue: () => Shape;
of: (this: void, self: ReadonlyRecord<string, unknown>) => ReadonlyRecord<string, unknown>;
context: (self: ReadonlyRecord<string, unknown>) => Context.Context<never>;
use: (f: (service: ReadonlyRecord<string, unknown>) => Effect<A, E, R>) => Effect<A, E, R>;
useSync: (f: (service: ReadonlyRecord<string, unknown>) => A) => Effect<A, never, never>;
Identifier: Identifier;
Service: Shape;
key: string;
stack: string | undefined;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
Context reference for managing log annotations that are automatically added to all log entries.
These annotations provide contextual metadata that appears in every log message.
When to use
Use to attach shared contextual metadata to every log entry emitted in the
current context.
Example (Managing log annotations)
import { Console, Effect, References } from "effect"
const logAnnotationExample = Effect.gen(function*() {
// Get current annotations (empty by default)
const current = yield* References.CurrentLogAnnotations
console.log(current) // {}
// Run with custom log annotations
yield* Effect.provideService(
Effect.gen(function*() {
const annotations = yield* References.CurrentLogAnnotations
console.log(annotations) // { requestId: "req-123", userId: "user-456", version: "1.0.0" }
// All log entries will include these annotations
yield* Console.log("Starting operation")
yield* Console.info("Processing data")
}),
References.CurrentLogAnnotations,
{
requestId: "req-123",
userId: "user-456",
version: "1.0.0"
}
)
// Run with extended annotations
yield* Effect.provideService(
Effect.gen(function*() {
const extended = yield* References.CurrentLogAnnotations
console.log(extended) // { requestId: "req-123", userId: "user-456", version: "1.0.0", operation: "data-sync", timestamp: 1234567890 }
yield* Console.log("Operation completed with extended context")
}),
References.CurrentLogAnnotations,
{
requestId: "req-123",
userId: "user-456",
version: "1.0.0",
operation: "data-sync",
timestamp: 1234567890
}
)
})
CurrentLogAnnotations: import ContextContext.interface Reference<in out Shape>Service key with a lazily computed default value.
Details
When a Reference is requested from a Context that does not contain an
override, Context getters that resolve references return the cached default
value instead of failing.
Example (Defining a reference with a default value)
import { Context } from "effect"
// Define a reference with a default value
const LoggerRef: Context.Reference<{ log: (msg: string) => void }> =
Context.Reference("Logger", {
defaultValue: () => ({ log: (msg: string) => console.log(msg) })
})
// The reference can be used without explicit provision
const context = Context.empty()
const logger = Context.get(context, LoggerRef) // Uses default value
Creates a context key with a default value.
When to use
Use when you need to define a context key with a lazily computed default
value.
Details
Context.Reference allows you to create a key that can hold a value. You
can provide a default value for the service, which will automatically be used
when the context is accessed, or override it with a custom implementation
when needed. The default value is computed lazily and cached on the
reference.
Example (Creating references with default values)
import { Context } from "effect"
// Create a reference with a default value
const LoggerRef = Context.Reference("Logger", {
defaultValue: () => ({ log: (msg: string) => console.log(msg) })
})
// The reference provides the default value when accessed from an empty context
const context = Context.empty()
const logger = Context.get(context, LoggerRef)
// You can also override the default value
const customContext = Context.make(LoggerRef, {
log: (msg: string) => `Custom: ${msg}`
})
const customLogger = Context.get(customContext, LoggerRef)
Reference<type ReadonlyRecord<in out K extends string | symbol, out A> = { readonly [P in K]: A; }Represents a readonly record with keys of type K and values of type A.
This is the foundational type for immutable key-value mappings in Effect.
Example (Defining a readonly record type)
import type { Record } from "effect"
// Creating a readonly record type
type UserRecord = Record.ReadonlyRecord<"name" | "age", string | number>
const user: UserRecord = {
name: "John",
age: 30
}
Namespace containing utility types for working with readonly records.
These types help with type-level operations on record keys and values.
Example (Using readonly record helper types)
import type { Record } from "effect"
// Using NonLiteralKey to convert literal keys to generic types
type GenericKey = Record.ReadonlyRecord.NonLiteralKey<"foo" | "bar"> // string
// Using IntersectKeys to find common keys between record types
type CommonKeys = Record.ReadonlyRecord.IntersectKeys<"a" | "b", "b" | "c"> // "b"
ReadonlyRecord<string, unknown>> =
import referencesreferences.const CurrentLogAnnotations: Context.Reference<
ReadonlyRecord<string, unknown>
>
const CurrentLogAnnotations: {
defaultValue: () => Shape;
of: (this: void, self: ReadonlyRecord<string, unknown>) => ReadonlyRecord<string, unknown>;
context: (self: ReadonlyRecord<string, unknown>) => Context.Context<never>;
use: (f: (service: ReadonlyRecord<string, unknown>) => Effect<A, E, R>) => Effect<A, E, R>;
useSync: (f: (service: ReadonlyRecord<string, unknown>) => A) => Effect<A, never, never>;
Identifier: Identifier;
Service: Shape;
key: string;
stack: string | undefined;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}