A module’s body and an operation’s handler are Effects. A plugin can read the capability manager as an Effect
service, contribute layers of its own, and name the services an operation needs.
Inside a module, the capability manager is Capability.Service. Capability.get, getAll and waitFor read it
for you; yield the service itself when you need the manager.
Helper to define a capability module with explicit typing.
Wraps the default export function to provide better type inference and make the pattern explicit.
This helper provides explicit typing for the module activation function,
making it clear that the function should:
Access declared requires via yield* (or the ambient Capability.Service/Plugin.Service)
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.
When to use
Use when you want to write effectful code that looks and behaves like
synchronous code, while still handling asynchronous tasks, errors, and complex
control flow such as loops and conditions.
Generator functions work similarly to async/await but keep errors,
requirements, and interruption in the Effect type. You can yield* values
from effects and return the final result at the end.
await Effect.runPromise(program) // => "Final amount to charge: 96"
@stability ― stable
@category ― constructors
@since ― 2.0.0
gen(function* () {
9
const
const manager: CapabilityManager
manager = yield*
import Capability
Capability.
classService
Effect Context.Tag for accessing CapabilityManager via the Effect layer system.
This allows capability modules to access the capability manager without having it passed as an argument.
Returns a new array with all sub-array elements concatenated into it recursively up to the
specified depth.
@param ― depth The maximum recursion depth
flat();
11
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:
A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.
Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(newError('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(newError('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
A service an operation uses comes from a layer. Contribute a LayerSpec to Capabilities.LayerSpec: it says what
the layer provides, what it requires and how widely one instance is shared. With affinity: 'application' the app
builds the layer once and every operation shares it.
Use when you need to define a context service key for a dependency that must
be provided by the surrounding context.
Details
Call Context.Service("Key") for a function-style key, or use the two-stage
form Context.Service<Self, Shape>()("Key") for class-style service
declarations. The returned key can be yielded as an Effect and passed to
Context.make, Context.add, and the Context getter functions.
Gotchas
The string key is the runtime identity of the service. Reusing the same key
string for unrelated services makes them occupy the same slot in a
Context.
@see ― Reference for service keys with default values
@stability ― stable
@category ― services
@since ― 4.0.0
Service<
9
classLinkChecker
LinkChecker,
10
{ readonly
check: (url: string) => Effect.Effect<boolean>
check: (
url: string
url: string) =>
import Effect
Effect.
interfaceEffect<outA, outE = never, outR = never>
The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Returns true if the sequence of elements of searchString converted to a String is the
same as the corresponding elements of this object (converted to a String) starting at
position. Otherwise returns false.
startsWith('https://')),
15
});
16
17
// A layer spec says what the layer provides and how widely it is shared; the
18
// runtime builds it for any operation that declares the service.
Helper to define a capability module with explicit typing.
Wraps the default export function to provide better type inference and make the pattern explicit.
This helper provides explicit typing for the module activation function,
making it clear that the function should:
Access declared requires via yield* (or the ambient Capability.Service/Plugin.Service)
An operation lists the services it needs in services. When it is invoked, the runtime builds them from the layer
specs plugins contributed, and the handler yields them like any Effect service.
1
import*as
import Effect
Effectfrom'effect/Effect';
2
import*as
import Schema
Schemafrom'effect/Schema';
3
import*as
import Operation
Operationfrom'@dxos/compute/Operation';
4
import {
import DXN
DXN } from'@dxos/echo';
5
6
exportconst
const CheckLink: Operation.Definition<{
readonly url: string;
}, {
readonly ok: boolean;
}, LinkChecker>
CheckLink =
import Operation
Operation.
constmake: <{
readonly meta: {
readonly key: DXN.DXN;
readonly name: "Check link";
};
readonly input: Schema.Struct<{
readonly url: Schema.String;
}>;
readonly output: Schema.Struct<{
readonly ok: Schema.Boolean;
}>;
readonly services: readonly [typeof LinkChecker];
}>(props: {
readonly meta: {
readonly key: DXN.DXN;
readonly name: "Check link";
};
readonly input: Schema.Struct<{
readonly url: Schema.String;
}>;
readonly output: Schema.Struct<{
readonly ok: Schema.Boolean;
}>;
readonly services: readonly [typeof LinkChecker];
}) =>Operation.Definition<...>
Creates a new Operation definition.
Applies default executionMode of 'async' if not specified.
The returned type preserves the literal types of props (including services).
Defines a struct schema from a map of field schemas.
Details
Each field value is a schema. Use
optionalKey
or
optional
to
mark fields as optional, and
mutableKey
to mark them as mutable.
The resulting schema's Type is a readonly object type with the fields'
decoded types. The Encoded form mirrors the field schemas' encoded types.
Declared fields may be inherited and are copied to own properties in the
output. The __proto__ field is accepted only when it is an own property.
Parsing does not guarantee that output keys retain their input order.
Schema for string values. Validates that the input is typeof"string".
@stability ― stable
@category ― models
@since ― 4.0.0
@stability ― stable
@category ― schemas
@since ― 4.0.0
String }),
12
output: Schema.Struct<{
readonly ok: Schema.Boolean;
}>
output:
import Schema
Schema.
functionStruct<{
readonly ok: Schema.Boolean;
}>(fields: {
readonly ok: Schema.Boolean;
}): Schema.Struct<{
readonly ok: Schema.Boolean;
}>
Defines a struct schema from a map of field schemas.
Details
Each field value is a schema. Use
optionalKey
or
optional
to
mark fields as optional, and
mutableKey
to mark them as mutable.
The resulting schema's Type is a readonly object type with the fields'
decoded types. The Encoded form mirrors the field schemas' encoded types.
Declared fields may be inherited and are copied to own properties in the
output. The __proto__ field is accepted only when it is an own property.
Parsing does not guarantee that output keys retain their input order.
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.
When to use
Use when you want to write effectful code that looks and behaves like
synchronous code, while still handling asynchronous tasks, errors, and complex
control flow such as loops and conditions.
Generator functions work similarly to async/await but keep errors,
requirements, and interruption in the Effect type. You can yield* values
from effects and return the final result at the end.
