<Self, S extends Spec>(
tag: HyperlinkTag<Self, S>,
options?: DiscoverClientOptions
): Layer.Layer<Self, LookupClientError>Sugar: lookupClient + Lookup.layer / Lookup.layerOptions —
discover an endpoint for tag via Lookup (identity, then directory) and dial it.
Not Effect “local” vs remote; name is discover.
Hyperlink.discoverClient(Jobs, { lookupPath })export const const discoverClient: <
Self,
S extends Spec
>(
tag: HyperlinkTag<Self, S>,
options?: DiscoverClientOptions
) => Layer.Layer<Self, LookupClientError>
Sugar:
lookupClient
+
Lookup.layer
/
Lookup.layerOptions
—
discover an endpoint for tag via Lookup (identity, then directory) and dial it.
Not Effect “local” vs remote; name is discover.
Hyperlink.discoverClient(Jobs, { lookupPath })
discoverClient = <function (type parameter) Self in <Self, S extends Spec>(tag: HyperlinkTag<Self, S>, options?: DiscoverClientOptions): Layer.Layer<Self, LookupClientError>Self, function (type parameter) S in <Self, S extends Spec>(tag: HyperlinkTag<Self, S>, options?: DiscoverClientOptions): Layer.Layer<Self, LookupClientError>S extends Spec>(
tag: HyperlinkTag<Self, S>(parameter) tag: {
groupId: string;
description: string | undefined;
key: Identifier;
of: (this: void, self: Simplify<{ readonly [K in keyof S]: S[K] extends FromLocalMethod<infer M> ? InjectLocal<M, Self> : S[K] extends LocalMethod<infer T> ? LocalEffect<T, never, Self> : S[K] extends { readonly _tag: 'constant'; } ? SuccessOf…;
context: (self: Simplify<{ readonly [K in keyof S]: S[K] extends FromLocalMethod<infer M> ? InjectLocal<M, Self> : S[K] extends LocalMethod<infer T> ? LocalEffect<T, never, Self> : S[K] extends { readonly _tag: 'constant'; } ? SuccessOf<AsMethod<S[…;
use: (f: (service: Simplify<{ readonly [K in keyof S]: S[K] extends FromLocalMethod<infer M> ? InjectLocal<M, Self> : S[K] extends LocalMethod<infer T> ? LocalEffect<T, never, Self> : S[K] extends { readonly _tag: 'constant'; } ? SuccessOf<AsMe…;
useSync: (f: (service: Simplify<{ readonly [K in keyof S]: S[K] extends FromLocalMethod<infer M> ? InjectLocal<M, Self> : S[K] extends LocalMethod<infer T> ? LocalEffect<T, never, Self> : S[K] extends { readonly _tag: 'constant'; } ? SuccessOf<AsMe…;
Identifier: Identifier;
Service: Shape;
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;
}
interface HyperlinkTag<Self, S extends Spec, Svc = Simplify<{ readonly [K in keyof S]: S[K] extends FromLocalMethod<infer M> ? InjectLocal<M, Self> : S[K] extends LocalMethod<infer T> ? LocalEffect<...> : S[K] extends { ...; } ? SuccessOf<...> : S[K] extends { ...; } ? Subscribable<...> : S[K] extends { ...; } ? ClientMethod<...> : S[K] extends Spec ? Simplify<...> : never; }>>The type of a resource tag carrying spec S — what
Hyperlink.Tag
/ a
Hyperlink.tagFor
factory produce (and what you extend). Lets a consumer write
<S extends Spec>(tag: HyperlinkTag<Self, S>) and read the spec through named types
(
specOf
/
groupOf
) instead of a Parameters<typeof specOf> workaround.
HyperlinkTag<function (type parameter) Self in <Self, S extends Spec>(tag: HyperlinkTag<Self, S>, options?: DiscoverClientOptions): Layer.Layer<Self, LookupClientError>Self, function (type parameter) S in <Self, S extends Spec>(tag: HyperlinkTag<Self, S>, options?: DiscoverClientOptions): Layer.Layer<Self, LookupClientError>S>,
options: DiscoverClientOptionsoptions?: type DiscoverClientOptions =
LookupClientOptions & {
readonly lookupPath?: string
readonly unlink?: boolean
}
Options for
discoverClient
/
discoverClients
— Lookup soft-pick
plus default-lookup bootstrap knobs.
DiscoverClientOptions,
): import LayerLayer.interface Layer<in ROut, out E = never, out RIn = never>A Layer describes how to build one or more services for dependency injection.
When to use
Use to model construction of application services for dependency injection,
especially when services have dependencies, can fail during construction, or
need scoped setup and release.
Details
A Layer<ROut, E, RIn> represents ROut as the services this layer
provides, E as the possible errors during layer construction, and RIn as
the services this layer requires as dependencies.
Layer<function (type parameter) Self in <Self, S extends Spec>(tag: HyperlinkTag<Self, S>, options?: DiscoverClientOptions): Layer.Layer<Self, LookupClientError>Self, class LookupClientErrorclass LookupClientError {
name: string;
message: string;
stack: string;
cause: unknown;
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;
_tag: Tag;
tag: string;
reason: 'missing' | 'ambiguous';
count: number;
}
lookupClient
could not resolve exactly one dial target for the Tag
(missing = none; ambiguous = more than one directory row and no
LookupClientOptions.pick
).
LookupClientError> => {
const { const lookupPath: string | undefinedlookupPath, const unlink: boolean | undefinedunlink, ...const clientOptions: {
pick?: LookupClientPick
}
options: DiscoverClientOptionsoptions ?? {};
return import LayerLayer.const unwrap: <
Self,
unknown,
unknown,
never,
never
>(
self: Effect.Effect<
Layer.Layer<Self, unknown, unknown>,
never,
never
>
) => Layer.Layer<Self, unknown, unknown>
Unwraps a Layer from an Effect, flattening the nested structure.
When to use
Use when you have an Effect that produces a Layer and you want to
use that layer directly.
Details
The resulting Layer will have the combined error and dependency types from
both the outer Effect and the inner Layer.
Example (Unwrapping an effectful layer)
import { Context, Effect, Layer } from "effect"
class Database extends Context.Service<Database, {
readonly query: (sql: string) => Effect.Effect<string>
}>()("Database") {}
const layerEffect = Effect.succeed(
Layer.succeed(Database, { query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result")) })
)
const unwrappedLayer = Layer.unwrap(layerEffect)
unwrap(
import EffectEffect.const promise: <any>(
evaluate: (
signal: AbortSignal
) => PromiseLike<any>
) => Effect.Effect<any, never, never>
Creates an Effect that represents an asynchronous computation guaranteed to
succeed.
When to use
Use to convert a Promise into an Effect when the async operation is
guaranteed to succeed and will not reject.
Details
An optional AbortSignal can be provided to allow for interruption of the
wrapped Promise API.
Gotchas
The Promise must not reject. If it rejects, the rejection is treated as a
defect, not as a typed failure. Use tryPromise when rejection is expected.
Interruption aborts the provided AbortSignal, but the underlying
asynchronous operation only stops if it observes that signal.
Example (Wrapping a non-rejecting Promise)
import { Effect } from "effect"
const delay = (message: string) =>
Effect.promise<string>(
() =>
new Promise((resolve) => {
setTimeout(() => {
resolve(message)
}, 2000)
})
)
// ┌─── Effect<string, never, never>
// ▼
const program = delay("Async operation completed successfully!")
promise(() => import("./Lookup")).Pipeable.pipe<Effect.Effect<any, never, never>, Effect.Effect<Layer.Layer<Self, unknown, unknown>, never, never>>(this: Effect.Effect<any, never, never>, ab: (_: Effect.Effect<any, never, never>) => Effect.Effect<Layer.Layer<Self, unknown, unknown>, never, never>): Effect.Effect<Layer.Layer<Self, unknown, unknown>, never, never> (+21 overloads)pipe(
import EffectEffect.const map: <any, Layer.Layer<Self, unknown, unknown>>(f: (a: any) => Layer.Layer<Self, unknown, unknown>) => <E, R>(self: Effect.Effect<any, E, R>) => Effect.Effect<Layer.Layer<Self, unknown, unknown>, E, R> (+1 overload)Transforms the value inside an effect by applying a function to it.
When to use
Use to transform an effect's success value with a function that returns a
plain value, producing a new effect without changing the original effect's
typed error or context requirements.
Details
map takes a function and applies it to the value contained within an
effect, creating a new effect with the transformed value.
It's important to note that effects are immutable, meaning that the original
effect is not modified. Instead, a new effect is returned with the updated
value.
Example (Choosing map syntax variants)
import { Effect, pipe } from "effect"
const myEffect = Effect.succeed(1)
const transformation = (n: number) => n + 1
const mappedWithPipe = pipe(myEffect, Effect.map(transformation))
const mappedWithDataFirst = Effect.map(myEffect, transformation)
const mappedWithMethod = myEffect.pipe(Effect.map(transformation))
Example (Adding a service charge)
import { Effect, pipe } from "effect"
const addServiceCharge = (amount: number) => amount + 1
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))
const finalAmount = pipe(
fetchTransactionAmount,
Effect.map(addServiceCharge)
)
Effect.runPromise(finalAmount).then(console.log)
// Output: 101
map((type Lookup: anyLookup) =>
const lookupClient: <
Self,
S extends Spec
>(
tag: HyperlinkTag<Self, S>,
options?: LookupClientOptions
) => Layer.Layer<
Self,
LookupClientError,
LookupIdentity | LookupDirectory | LookupAdvice
>
Lookup-resolved nodeless client (D7/D4) — you do not pass a
Node
; Lookup
chooses the dial target. Contrast
client
(Tag, node), where you name the Node.
Resolution order:
Lookup.Identity
resolve(tag.key), else
Lookup.Directory
nodesServing(tag.key).
Fail-closed by default: missing or more than one directory row →
LookupClientError
. When N>1, a live
Lookup.Advice
prefer that
matches a directory row wins before D4 { pick }. Opt into soft pick with
{ pick: "first" } or a sync (rows) => DirectoryEntry. Identity resolve
ignores advice / pick (unique by key).
Bake name sketch was unsafeLookupClient (“trust Lookup or die”); bare
lookupClient(Tag) keeps that fail-closed contract when advice is absent/stale.
// Sole endpoint (identity winner or one directory row):
Hyperlink.lookupClient(Mail).pipe(Layer.provide(Lookup.layer))
// Coordinator published advice — bare client honors prefer:
yield* Lookup.advise({ resourceKey: Mail.key, prefer: "fleet/Mail#w2" })
Hyperlink.lookupClient(Mail)
// N>1 replicas — opt-in pick when no advice (still fail on 0):
Hyperlink.lookupClient(Mail, { pick: "first" })
// You already know an addressed Node — client auto-connects:
Hyperlink.client(Mail, East)
lookupClient(tag: HyperlinkTag<Self, S>(parameter) tag: {
groupId: string;
description: string | undefined;
key: Identifier;
of: (this: void, self: Simplify<{ readonly [K in keyof S]: S[K] extends FromLocalMethod<infer M> ? InjectLocal<M, Self> : S[K] extends LocalMethod<infer T> ? LocalEffect<T, never, Self> : S[K] extends { readonly _tag: 'constant'; } ? SuccessOf…;
context: (self: Simplify<{ readonly [K in keyof S]: S[K] extends FromLocalMethod<infer M> ? InjectLocal<M, Self> : S[K] extends LocalMethod<infer T> ? LocalEffect<T, never, Self> : S[K] extends { readonly _tag: 'constant'; } ? SuccessOf<AsMethod<S[…;
use: (f: (service: Simplify<{ readonly [K in keyof S]: S[K] extends FromLocalMethod<infer M> ? InjectLocal<M, Self> : S[K] extends LocalMethod<infer T> ? LocalEffect<T, never, Self> : S[K] extends { readonly _tag: 'constant'; } ? SuccessOf<AsMe…;
useSync: (f: (service: Simplify<{ readonly [K in keyof S]: S[K] extends FromLocalMethod<infer M> ? InjectLocal<M, Self> : S[K] extends LocalMethod<infer T> ? LocalEffect<T, never, Self> : S[K] extends { readonly _tag: 'constant'; } ? SuccessOf<AsMe…;
Identifier: Identifier;
Service: Shape;
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;
}
const clientOptions: {
pick?: LookupClientPick
}
Pipeable.pipe<Layer.Layer<Self, LookupClientError, any>, Layer.Layer<Self, unknown, unknown>>(this: Layer.Layer<Self, LookupClientError, any>, ab: (_: Layer.Layer<Self, LookupClientError, any>) => Layer.Layer<Self, unknown, unknown>): Layer.Layer<Self, unknown, unknown> (+21 overloads)pipe(
import LayerLayer.const provide: <any>(that: any) => <A, E, R>(self: Layer.Layer<A, E, R>) => Layer.Layer<A, unknown, unknown> (+3 overloads)Feeds the output services of the dependency layer into the requirements of
this layer, returning a layer that only provides the services from this layer.
When to use
Use when you need to hide an implementation dependency layer from callers.
Details
In serviceLayer.pipe(Layer.provide(dependencyLayer)), the dependency layer is
built first and is used to satisfy the requirements of serviceLayer.
Example (Providing layer dependencies)
import { Context, Effect, Layer } from "effect"
class Database extends Context.Service<Database, {
readonly query: (sql: string) => Effect.Effect<string>
}>()("Database") {}
class UserService extends Context.Service<UserService, {
readonly getUser: (id: string) => Effect.Effect<{
id: string
name: string
}>
}>()("UserService") {}
class Logger extends Context.Service<Logger, {
readonly log: (msg: string) => Effect.Effect<void>
}>()("Logger") {}
// Create dependency layers
const databaseLayer = Layer.succeed(Database, {
query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
})
const loggerLayer = Layer.succeed(Logger, {
log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
})
// UserService depends on Database and Logger
const userServiceLayer = Layer.effect(UserService, Effect.gen(function*() {
const database = yield* Database
const logger = yield* Logger
return {
getUser: Effect.fn("UserService.getUser")(function*(id: string) {
yield* logger.log(`Looking up user ${id}`)
const result = yield* database.query(
`SELECT * FROM users WHERE id = ${id}`
)
return { id, name: result }
})
}
}))
// Provide dependencies to UserService layer
const userServiceWithDependencies = userServiceLayer.pipe(
Layer.provide(Layer.mergeAll(databaseLayer, loggerLayer))
)
// Now UserService layer has no dependencies
const program = Effect.gen(function*() {
const userService = yield* UserService
return yield* userService.getUser("123")
}).pipe(
Effect.provide(userServiceWithDependencies)
)
provide(
const lookupPath: string | undefinedlookupPath === var undefinedundefined && const unlink: boolean | undefinedunlink === var undefinedundefined
? type Lookup: anyLookup.layer
: type Lookup: anyLookup.layerOptions({
...(const lookupPath: string | undefinedlookupPath !== var undefinedundefined ? { path: stringpath: const lookupPath: stringlookupPath } : {}),
...(const unlink: boolean | undefinedunlink !== var undefinedundefined ? { unlink: booleanunlink } : {}),
}),
),
),
),
),
) as import LayerLayer.interface Layer<in ROut, out E = never, out RIn = never>A Layer describes how to build one or more services for dependency injection.
When to use
Use to model construction of application services for dependency injection,
especially when services have dependencies, can fail during construction, or
need scoped setup and release.
Details
A Layer<ROut, E, RIn> represents ROut as the services this layer
provides, E as the possible errors during layer construction, and RIn as
the services this layer requires as dependencies.
Layer<function (type parameter) Self in <Self, S extends Spec>(tag: HyperlinkTag<Self, S>, options?: DiscoverClientOptions): Layer.Layer<Self, LookupClientError>Self, class LookupClientErrorclass LookupClientError {
name: string;
message: string;
stack: string;
cause: unknown;
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;
_tag: Tag;
tag: string;
reason: 'missing' | 'ambiguous';
count: number;
}
lookupClient
could not resolve exactly one dial target for the Tag
(missing = none; ambiguous = more than one directory row and no
LookupClientOptions.pick
).
LookupClientError>;
};