(node: AnyNode & { readonly path?: string }): Layer.Layer<
Services,
LookupUnaddressed
>export const const client: (
node: AnyNode & { readonly path?: string }
) => Layer.Layer<Services, LookupUnaddressed>
client = (
node: AnyNode & { readonly path?: string }node: type AnyNode = NodeKey<unknown> & {
readonly url: string | undefined;
readonly path: string | undefined;
readonly kind: ProtocolKind | undefined;
readonly endpoints?: Endpoints;
readonly onConflict?: OnConflict;
readonly [portSym]?: number;
}
A
Tag
erased — its transport endpoints set, plus the primary address
(url and/or Unix path) and
ProtocolKind
kind (the first-declared endpoint, kept for
single-protocol readers), so a tag's distributed set is self-describing about where AND how to
reach each one.
AnyNode & { readonly path?: string | undefinedpath?: string },
): 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<type Services =
| Identity
| Directory
| Advice
Services a Lookup client layer provides — identity, directory, and placement advice.
Services, class LookupUnaddressedclass LookupUnaddressed {
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;
node: string;
}
Lookup node has no dialable address — need { path } / url, or use
layer
/
layerOptions
. Layer error channel (not a sync throw).
LookupUnaddressed> => {
if (node: AnyNode & { readonly path?: string }node.path: string | undefinedpath === var undefinedundefined) {
return const lookupUnaddressedLayer: <A = never>(
node: string
) => Layer.Layer<A, LookupUnaddressed>
Fail a Layer build with
LookupUnaddressed
.
lookupUnaddressedLayer(
"key" in node: AnyNode & { readonly path?: string }node && typeof node: AnyNode & { readonly path?: string }node.Key<unknown, NodeProtocol>.key: stringkey === "string" ? node: AnyNode & { readonly path?: string }node.Key<unknown, NodeProtocol>.key: stringkey : "lookup",
);
}
const const path: stringpath = node: AnyNode & { readonly path?: string }node.path: stringpath;
// Path overload of connectIpc — no UnaddressedNode on the error channel.
// Opt out of default-on client verify: Lookup.client is often composed before (or
// beside) the Lookup listen, and bind-or-dial ({@link layerOptions}) builds the
// dial side without a guaranteed live peer at Layer.build. Connectivity fails on
// the first Identity/Directory call instead.
const const clients: anyclients: any = import LayerLayer.const mergeAll: <
Layers extends [
Layer<never, any, any>,
...Array<Layer<never, any, any>>
]
>(
...layers: Layers
) => Layer<
Success<Layers[number]>,
Error<Layers[number]>,
Services<Layers[number]>
>
Combines all the provided layers concurrently, creating a new layer with
merged input, error, and output types.
When to use
Use when you need to combine multiple independent layers.
Details
All layers are built concurrently, and their outputs are merged into a single layer.
If multiple merged layers depend on the same layer value, that dependency is
shared by default. Reuse a named layer value when you want services to share
the same resource, such as one database pool.
Example (Merging independent layers)
import { Context, Effect, Layer } from "effect"
class Database extends Context.Service<Database, {
readonly query: (sql: string) => Effect.Effect<string>
}>()("Database") {}
class Logger extends Context.Service<Logger, {
readonly log: (msg: string) => Effect.Effect<void>
}>()("Logger") {}
const dbLayer = Layer.succeed(Database, {
query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
})
const loggerLayer = Layer.succeed(Logger, {
log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(msg)))
})
const mergedLayer = Layer.mergeAll(dbLayer, loggerLayer)
mergeAll(
import HyperlinkHyperlink.client<Identity, {
claim: Hyperlink.Method<typeof ClaimRequest, typeof Endpoint, typeof DuplicateIdentity, false, Hyperlink.MethodAnnotations & {
description: string;
}, Hyperlink.Derive>;
resolve: Hyperlink.Method<typeof ResolveRequest, Schema.Option<typeof Endpoint>, Schema.Never, false, Hyperlink.MethodAnnotations & {
description: string;
}, Hyperlink.Derive>;
}, unknown>(tag: Hyperlink.HyperlinkTag<Identity, {
claim: Hyperlink.Method<typeof ClaimRequest, typeof Endpoint, typeof DuplicateIdentity, false, Hyperlink.MethodAnnotations & {
description: string;
}, Hyperlink.Derive>;
resolve: Hyperlink.Method<typeof ResolveRequest, Schema.Option<typeof Endpoint>, Schema.Never, false, Hyperlink.MethodAnnotations & {
description: string;
}, Hyperlink.Derive>;
}, {
...;
}>, node: NodeKey<...>): Layer.Layer<...> (+4 overloads)
export client
The client layer for a serviceKey: drive it over RPC as if it were local — the exact
same yield* Tag code as the local layer, only the provided layer differs, so it doesn't
matter where the HyperService actually runs.
Paths, by whether — and where — the tag names a
Node
:
- **node-bearing +
AddressedNode
** —
client(Hosted) when the tag's { node } is
dialable: auto-wires connect (R = never). Bare bound nodes still require the node service.
- **nodeless tag +
AddressedNode
** —
client(tag, Worker) same auto-connect gate.
- bare node —
client(tag, Bare) / bare-bound client(Hosted) still require the node;
provide
Node.connect
(Bare, protocol) (or lookup /
unix
(tag)) yourself.
- nodeless tag, ambient transport — ambient
RpcClient.Protocol.
client(class Identityclass Identity {
key: Identifier;
Service: {
claim: (payload: { key: string; kind: 'Http' | 'WebSocket' | 'IpcSocket'; nodeKey: string; url?: string | undefined; path?: string | undefined }) => Effect.Effect<Endpoint, DuplicateIdentity, never>;
resolve: (payload: { key: string }) => Effect.Effect<Option.Option<Endpoint>, never, never>;
};
description: string | undefined;
of: (this: void, self: { readonly claim: (payload: { key: string; kind: 'Http' | 'WebSocket' | 'IpcSocket'; nodeKey: string; url?: string | undefined; path?: string | undefined }) => Effect.Effect<Endpoint, DuplicateIdentity, never>; readonly …;
context: (self: { readonly claim: (payload: { key: string; kind: 'Http' | 'WebSocket' | 'IpcSocket'; nodeKey: string; url?: string | undefined; path?: string | undefined }) => Effect.Effect<Endpoint, DuplicateIdentity, never>; readonly resolve: (pa…;
use: (f: (service: { readonly claim: (payload: { key: string; kind: 'Http' | 'WebSocket' | 'IpcSocket'; nodeKey: string; url?: string | undefined; path?: string | undefined }) => Effect.Effect<Endpoint, DuplicateIdentity, never>; readonly resol…;
useSync: (f: (service: { readonly claim: (payload: { key: string; kind: 'Http' | 'WebSocket' | 'IpcSocket'; nodeKey: string; url?: string | undefined; path?: string | undefined }) => Effect.Effect<Endpoint, DuplicateIdentity, never>; readonly resol…;
Identifier: Identifier;
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;
}
Lookup identity service — claim HyperService keys (first wins; dead winners replaceable).
Identity, node: AnyNode & { readonly path?: string }node) as any,
import HyperlinkHyperlink.client<Directory, {
advertise: Hyperlink.Method<typeof AdvertiseRequest, typeof DirectoryEntry, typeof IncumbentAlive, false, Hyperlink.MethodAnnotations & {
description: string;
}, Hyperlink.Derive>;
unregister: Hyperlink.Method<typeof UnregisterRequest, Schema.Boolean, Schema.Never, false, Hyperlink.MethodAnnotations & {
description: string;
}, Hyperlink.Derive>;
nodesServing: Hyperlink.Method<typeof NodesServingRequest, ... 4 more ..., Hyperlink.Derive>;
}, unknown>(tag: Hyperlink.HyperlinkTag<...>, node: NodeKey<...>): Layer.Layer<...> (+4 overloads)
export client
The client layer for a serviceKey: drive it over RPC as if it were local — the exact
same yield* Tag code as the local layer, only the provided layer differs, so it doesn't
matter where the HyperService actually runs.
Paths, by whether — and where — the tag names a
Node
:
- **node-bearing +
AddressedNode
** —
client(Hosted) when the tag's { node } is
dialable: auto-wires connect (R = never). Bare bound nodes still require the node service.
- **nodeless tag +
AddressedNode
** —
client(tag, Worker) same auto-connect gate.
- bare node —
client(tag, Bare) / bare-bound client(Hosted) still require the node;
provide
Node.connect
(Bare, protocol) (or lookup /
unix
(tag)) yourself.
- nodeless tag, ambient transport — ambient
RpcClient.Protocol.
client(class Directoryclass Directory {
key: Identifier;
Service: {
advertise: (payload: { kind: 'Http' | 'WebSocket' | 'IpcSocket'; nodeKey: string; serves: ReadonlyArray<string>; url?: string | undefined; path?: string | undefined; onConflict?: 'livenessReplace' | 'askIncumbent' | 'reject' | 'inherit' | undefined }…;
unregister: (payload: { nodeKey: string; kind?: 'Http' | 'WebSocket' | 'IpcSocket' | undefined; url?: string | undefined; path?: string | undefined }) => Effect.Effect<boolean, never, never>;
nodesServing: (payload: { serviceKey: string }) => Effect.Effect<ReadonlyArray<DirectoryEntry>, never, never>;
};
description: string | undefined;
of: (this: void, self: { readonly advertise: (payload: { kind: 'Http' | 'WebSocket' | 'IpcSocket'; nodeKey: string; serves: ReadonlyArray<string>; url?: string | undefined; path?: string | undefined; onConflict?: 'livenessReplace' | 'askIncumb…;
context: (self: { readonly advertise: (payload: { kind: 'Http' | 'WebSocket' | 'IpcSocket'; nodeKey: string; serves: ReadonlyArray<string>; url?: string | undefined; path?: string | undefined; onConflict?: 'livenessReplace' | 'askIncumbent' | 'reje…;
use: (f: (service: { readonly advertise: (payload: { kind: 'Http' | 'WebSocket' | 'IpcSocket'; nodeKey: string; serves: ReadonlyArray<string>; url?: string | undefined; path?: string | undefined; onConflict?: 'livenessReplace' | 'askIncumbent' …;
useSync: (f: (service: { readonly advertise: (payload: { kind: 'Http' | 'WebSocket' | 'IpcSocket'; nodeKey: string; serves: ReadonlyArray<string>; url?: string | undefined; path?: string | undefined; onConflict?: 'livenessReplace' | 'askIncumbent' …;
Identifier: Identifier;
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;
}
Lookup node directory — advertise / unregister / list by served HyperService key.
Directory, node: AnyNode & { readonly path?: string }node) as any,
import HyperlinkHyperlink.client<Advice, {
advise: Hyperlink.Method<typeof AdviseRequest, Schema.String, Schema.Never, false, Hyperlink.MethodAnnotations & {
description: string;
}, Hyperlink.Derive>;
clear: Hyperlink.Method<typeof ClearAdviceRequest, Schema.Boolean, Schema.Never, false, Hyperlink.MethodAnnotations & {
description: string;
}, Hyperlink.Derive>;
preferred: Hyperlink.Method<typeof PreferredRequest, Schema.Option<Schema.String>, Schema.Never, false, Hyperlink.MethodAnnotations & {
...;
}, Hyperlink.Derive>;
}, unknown>(tag: Hyperlink.HyperlinkTag<...>, node: NodeKey<...>): Layer.Layer<...> (+4 overloads)
export client
The client layer for a serviceKey: drive it over RPC as if it were local — the exact
same yield* Tag code as the local layer, only the provided layer differs, so it doesn't
matter where the HyperService actually runs.
Paths, by whether — and where — the tag names a
Node
:
- **node-bearing +
AddressedNode
** —
client(Hosted) when the tag's { node } is
dialable: auto-wires connect (R = never). Bare bound nodes still require the node service.
- **nodeless tag +
AddressedNode
** —
client(tag, Worker) same auto-connect gate.
- bare node —
client(tag, Bare) / bare-bound client(Hosted) still require the node;
provide
Node.connect
(Bare, protocol) (or lookup /
unix
(tag)) yourself.
- nodeless tag, ambient transport — ambient
RpcClient.Protocol.
client(class Adviceclass Advice {
key: Identifier;
Service: {
advise: (payload: { serviceKey: string; prefer: string }) => Effect.Effect<string, never, never>;
clear: (payload: { serviceKey: string }) => Effect.Effect<boolean, never, never>;
preferred: (payload: { serviceKey: string }) => Effect.Effect<Option.Option<string>, never, never>;
};
description: string | undefined;
of: (this: void, self: { readonly advise: (payload: { serviceKey: string; prefer: string }) => Effect.Effect<string, never, never>; readonly clear: (payload: { serviceKey: string }) => Effect.Effect<boolean, never, never>; readonly preferred: …;
context: (self: { readonly advise: (payload: { serviceKey: string; prefer: string }) => Effect.Effect<string, never, never>; readonly clear: (payload: { serviceKey: string }) => Effect.Effect<boolean, never, never>; readonly preferred: (payload: { …;
use: (f: (service: { readonly advise: (payload: { serviceKey: string; prefer: string }) => Effect.Effect<string, never, never>; readonly clear: (payload: { serviceKey: string }) => Effect.Effect<boolean, never, never>; readonly preferred: (payl…;
useSync: (f: (service: { readonly advise: (payload: { serviceKey: string; prefer: string }) => Effect.Effect<string, never, never>; readonly clear: (payload: { serviceKey: string }) => Effect.Effect<boolean, never, never>; readonly preferred: (payl…;
Identifier: Identifier;
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;
}
Lookup placement board — coordinator advice for nodeless /
Hyperlink.lookupClient
dial.
v1: last-write-wins, in-memory, no advisor ACL. Algorithms stay app-owned (who calls
advise
); Lookup only stores and surfaces the preference.
Advice, node: AnyNode & { readonly path?: string }node) as any,
) as any;
return const clients: anyclients.pipe(
import LayerLayer.const provide: {
<RIn, E, ROut>(that: Layer<ROut, E, RIn>): <
RIn2,
E2,
ROut2
>(
self: Layer<ROut2, E2, RIn2>
) => Layer<
ROut2,
E | E2,
RIn | Exclude<RIn2, ROut>
>
<Layers extends [Any, ...Array<Any>]>(
that: Layers
): <A, E, R>(
self: Layer<A, E, R>
) => Layer<
A,
E | Error<Layers[number]>,
| Services<Layers[number]>
| Exclude<R, Success<Layers[number]>>
>
<RIn2, E2, ROut2, RIn, E, ROut>(
self: Layer<ROut2, E2, RIn2>,
that: Layer<ROut, E, RIn>
): Layer<
ROut2,
E | E2,
RIn | Exclude<RIn2, ROut>
>
<A, E, R, Layers extends [Any, ...Array<Any>]>(
self: Layer<A, E, R>,
that: Layers
): Layer<
A,
E | Error<Layers[number]>,
| Services<Layers[number]>
| Exclude<R, Success<Layers[number]>>
>
}
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(node: AnyNode & { readonly path?: string }node.Pipeable.pipe<NodeKey<unknown> & {
readonly url: string | undefined;
readonly path: string | undefined;
readonly kind: ProtocolKind | undefined;
readonly endpoints?: Endpoints;
readonly onConflict?: OnConflict;
readonly [portSym]?: number;
} & {
readonly path?: string;
}, Layer.Layer<unknown, never, never>>(this: NodeKey<...> & ... 1 more ... & {
readonly path?: string;
}, ab: (_: NodeKey<unknown> & {
readonly url: string | undefined;
readonly path: string | undefined;
readonly kind: ProtocolKind | undefined;
readonly endpoints?: Endpoints;
readonly onConflict?: OnConflict;
readonly [portSym]?: number;
} & {
readonly path?: string;
}) => Layer.Layer<...>): Layer.Layer<...> (+21 overloads)
pipe(function connectIpc(path: string): <Self>(node: NodeKey<Self>) => Layer.Layer<Self> (+1 overload)Wire a node over IpcSocket — Unix-domain socket RPC (
protocolIpc
),
connect
pinned to kind: "IpcSocket". Dual: MyNode.pipe(Hyperlink.connectIpc) uses the node's own path;
MyNode.pipe(Hyperlink.connectIpc(path)) overrides it.
connectIpc(const path: stringpath))),
import LayerLayer.const provide: {
<RIn, E, ROut>(that: Layer<ROut, E, RIn>): <
RIn2,
E2,
ROut2
>(
self: Layer<ROut2, E2, RIn2>
) => Layer<
ROut2,
E | E2,
RIn | Exclude<RIn2, ROut>
>
<Layers extends [Any, ...Array<Any>]>(
that: Layers
): <A, E, R>(
self: Layer<A, E, R>
) => Layer<
A,
E | Error<Layers[number]>,
| Services<Layers[number]>
| Exclude<R, Success<Layers[number]>>
>
<RIn2, E2, ROut2, RIn, E, ROut>(
self: Layer<ROut2, E2, RIn2>,
that: Layer<ROut, E, RIn>
): Layer<
ROut2,
E | E2,
RIn | Exclude<RIn2, ROut>
>
<A, E, R, Layers extends [Any, ...Array<Any>]>(
self: Layer<A, E, R>,
that: Layers
): Layer<
A,
E | Error<Layers[number]>,
| Services<Layers[number]>
| Exclude<R, Success<Layers[number]>>
>
}
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(import HyperlinkHyperlink.const clientVerify: (
mode: ClientVerifyMode
) => Layer.Layer<never>
Override
ClientVerify
for addressed client layers.
clientVerify(false)),
) as any;
};