(impl: {
readonly randomBytes: (size: number) => Uint8Array
readonly digest: (
algorithm: DigestAlgorithm,
data: Uint8Array
) => Effect.Effect<Uint8Array, PlatformError.PlatformError>
}): CryptoCreates a Crypto service from the primitive implementation, deriving the
random generator helpers and UUID generation from those primitives.
When to use
Use to build a Crypto service for a platform integration, test layer, or custom runtime from primitive random-byte and digest operations.
Details
The constructor derives random numbers, booleans, integer ranges, shuffling,
and UUID generation from impl.randomBytes. Digest operations delegate to
impl.digest.
Gotchas
impl.randomBytes must return cryptographically secure bytes of the
requested length. UUID formatting mutates the byte array returned for UUID
generation, so the implementation should return a fresh array for each call.
Example (Creating a Crypto service)
import { Crypto, Effect, Layer } from "effect"
const TestCrypto = Layer.succeed(
Crypto.Crypto,
Crypto.make({
randomBytes: (size) => new Uint8Array(size),
digest: (_algorithm, data) => Effect.succeed(data)
})
)export const const make: (impl: {
readonly randomBytes: (
size: number
) => Uint8Array
readonly digest: (
algorithm: DigestAlgorithm,
data: Uint8Array
) => Effect.Effect<
Uint8Array,
PlatformError.PlatformError
>
}) => Crypto
Creates a Crypto service from the primitive implementation, deriving the
random generator helpers and UUID generation from those primitives.
When to use
Use to build a Crypto service for a platform integration, test layer, or
custom runtime from primitive random-byte and digest operations.
Details
The constructor derives random numbers, booleans, integer ranges, shuffling,
and UUID generation from impl.randomBytes. Digest operations delegate to
impl.digest.
Gotchas
impl.randomBytes must return cryptographically secure bytes of the
requested length. UUID formatting mutates the byte array returned for UUID
generation, so the implementation should return a fresh array for each call.
Example (Creating a Crypto service)
import { Crypto, Effect, Layer } from "effect"
const TestCrypto = Layer.succeed(
Crypto.Crypto,
Crypto.make({
randomBytes: (size) => new Uint8Array(size),
digest: (_algorithm, data) => Effect.succeed(data)
})
)
make = (
impl: {
readonly randomBytes: (
size: number
) => Uint8Array
readonly digest: (
algorithm: DigestAlgorithm,
data: Uint8Array
) => Effect.Effect<
Uint8Array,
PlatformError.PlatformError
>
}
randomBytes: (size: number) => Uint8ArrayrandomBytes: (size: numbersize: number) => interface Uint8Array<TArrayBuffer extends ArrayBufferLike = ArrayBufferLike>A typed array of 8-bit unsigned integer values. The contents are initialized to 0. If the
requested number of bytes could not be allocated an exception is raised.
Uint8Array
readonly digest: (
algorithm: DigestAlgorithm,
data: Uint8Array
) => Effect.Effect<
Uint8Array,
PlatformError.PlatformError
>
algorithm: DigestAlgorithmalgorithm: type DigestAlgorithm =
| "SHA-1"
| "SHA-256"
| "SHA-384"
| "SHA-512"
Digest algorithms supported by the platform Crypto service.
Gotchas
SHA-1 is included for interoperability with existing protocols. Do not use
SHA-1 for new security-sensitive designs.
Example (Using a digest algorithm)
import { Crypto } from "effect"
const algorithm: Crypto.DigestAlgorithm = "SHA-256"
DigestAlgorithm,
data: Uint8Array<ArrayBufferLike>data: interface Uint8Array<TArrayBuffer extends ArrayBufferLike = ArrayBufferLike>A typed array of 8-bit unsigned integer values. The contents are initialized to 0. If the
requested number of bytes could not be allocated an exception is raised.
Uint8Array
) => import EffectEffect.interface Effect<out A, out E = never, out R = 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.
Effect<interface Uint8Array<TArrayBuffer extends ArrayBufferLike = ArrayBufferLike>A typed array of 8-bit unsigned integer values. The contents are initialized to 0. If the
requested number of bytes could not be allocated an exception is raised.
Uint8Array, import PlatformErrorPlatformError.class PlatformErrorclass PlatformError {
message: string;
name: 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;
reason: PlatformError.BadArgument | PlatformError.SystemError;
}
Tagged error used by platform APIs to report either invalid arguments or
system-level failures.
When to use
Use as the shared error type for platform APIs that expose invalid arguments
and host or operating-system failures through a single Effect error
channel.
Details
The reason field contains the underlying BadArgument or SystemError.
When that reason has a cause, the cause is preserved on the wrapper.
PlatformError>
}
): Crypto => {
const const randomBytesUnsafe: (
size: number
) => Uint8Array
impl: {
readonly randomBytes: (
size: number
) => Uint8Array
readonly digest: (
algorithm: DigestAlgorithm,
data: Uint8Array
) => Effect.Effect<
Uint8Array,
PlatformError.PlatformError
>
}
randomBytes: (size: number) => Uint8ArrayrandomBytes
const const randomBytes: Crypto["randomBytes"]randomBytes: Crypto["randomBytes"] = (size: numbersize) => import EffectEffect.const map: {
<A, B>(f: (a: A) => B): <E, R>(
self: Effect<A, E, R>
) => Effect<B, E, R>
<A, E, R, B>(
self: Effect<A, E, R>,
f: (a: A) => B
): Effect<B, E, R>
}
const validateSize: (
method: string,
size: number
) => Effect.Effect<
number,
PlatformError.PlatformError
>
size: numbersize), const randomBytesUnsafe: (
size: number
) => Uint8Array
const nextDoubleUnsafe: () => numbernextDoubleUnsafe = (): number => {
const const bytes: Uint8Array<ArrayBufferLike>bytes = const randomBytesUnsafe: (
size: number
) => Uint8Array
const value: numbervalue = ((const bytes: Uint8Array<ArrayBufferLike>bytes[0] & 0x1f) * 2 ** 48) + (const bytes: Uint8Array<ArrayBufferLike>bytes[1] * 2 ** 40) + (const bytes: Uint8Array<ArrayBufferLike>bytes[2] * 2 ** 32) +
(const bytes: Uint8Array<ArrayBufferLike>bytes[3] * 2 ** 24) + (const bytes: Uint8Array<ArrayBufferLike>bytes[4] * 2 ** 16) + (const bytes: Uint8Array<ArrayBufferLike>bytes[5] * 2 ** 8) + const bytes: Uint8Array<ArrayBufferLike>bytes[6]
return const value: numbervalue / 2 ** 53
}
const const nextIntUnsafe: () => numbernextIntUnsafe = (): number =>
var Math: MathAn intrinsic object that provides basic mathematics functionality and constants.
Math.Math.floor(x: number): numberReturns the greatest integer less than or equal to its numeric argument.
floor(const nextDoubleUnsafe: () => numbernextDoubleUnsafe() * (var Number: NumberConstructorAn object that represents a number of any kind. All JavaScript numbers are 64-bit floating-point numbers.
Number.NumberConstructor.MAX_SAFE_INTEGER: numberThe value of the largest integer n such that n and n + 1 are both exactly representable as
a Number value.
The value of Number.MAX_SAFE_INTEGER is 9007199254740991 2^53 − 1.
MAX_SAFE_INTEGER - var Number: NumberConstructorAn object that represents a number of any kind. All JavaScript numbers are 64-bit floating-point numbers.
Number.NumberConstructor.MIN_SAFE_INTEGER: numberThe value of the smallest integer n such that n and n − 1 are both exactly representable as
a Number value.
The value of Number.MIN_SAFE_INTEGER is −9007199254740991 (−(2^53 − 1)).
MIN_SAFE_INTEGER + 1)) + var Number: NumberConstructorAn object that represents a number of any kind. All JavaScript numbers are 64-bit floating-point numbers.
Number.NumberConstructor.MIN_SAFE_INTEGER: numberThe value of the smallest integer n such that n and n − 1 are both exactly representable as
a Number value.
The value of Number.MIN_SAFE_INTEGER is −9007199254740991 (−(2^53 − 1)).
MIN_SAFE_INTEGER
return const Crypto: Context.Service<
Crypto,
Crypto
>
const Crypto: {
key: string;
Service: {
nextIntUnsafe: () => number;
nextDoubleUnsafe: () => number;
randomBytes: (size: number) => Effect.Effect<Uint8Array, PlatformError.PlatformError>;
digest: (algorithm: DigestAlgorithm, data: Uint8Array) => Effect.Effect<Uint8Array, PlatformError.PlatformError>;
random: Effect.Effect<number>;
randomBoolean: Effect.Effect<boolean>;
randomInt: Effect.Effect<number>;
randomBetween: (min: number, max: number) => Effect.Effect<number>;
randomIntBetween: (min: number, max: number, options?: { readonly halfOpen?: boolean | undefined }) => Effect.Effect<number>;
randomShuffle: <A>(elements: Iterable<A>) => Effect.Effect<Array<A>>;
randomUUIDv4: Effect.Effect<string, PlatformError.PlatformError>;
randomUUIDv7: Effect.Effect<string, PlatformError.PlatformError>;
};
of: (this: void, self: Crypto) => Crypto;
context: (self: Crypto) => Context.Context<Crypto>;
use: (f: (service: Crypto) => Effect.Effect<A, E, R>) => Effect.Effect<A, E, Crypto | R>;
useSync: (f: (service: Crypto) => A) => Effect.Effect<A, never, Crypto>;
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;
}
Platform-agnostic cryptographic operations.
Details
Crypto implementations must use cryptographically secure platform APIs.
The random generator helpers are derived by the make constructor from
the random methods on this service.
Example (Using cryptographic operations)
import { Crypto, Effect, Layer } from "effect"
const TestCrypto = Layer.succeed(
Crypto.Crypto,
Crypto.make({
randomBytes: (size) => new Uint8Array(size),
digest: (_algorithm, data) => Effect.succeed(data)
})
)
const program = Effect.gen(function*() {
const crypto = yield* Crypto.Crypto
const bytes = yield* crypto.randomBytes(16)
const uuidv4 = yield* crypto.randomUUIDv4
const uuidv7 = yield* crypto.randomUUIDv7
const hash = yield* crypto.digest("SHA-256", bytes)
return { uuidv4, uuidv7, hash }
})
Effect.runPromise(Effect.provide(program, TestCrypto))
Service tag for platform cryptography.
When to use
Use when you need to provide or retrieve the full platform cryptography
service from an effect's context.
Details
Providing this service supplies platform-agnostic cryptographic operations
such as hashing, UUID generation, and secure random values.
Crypto.of({
[const TypeId: "~effect/platform/Crypto"TypeId]: const TypeId: "~effect/platform/Crypto"TypeId,
randomBytes: (
size: number
) => Effect.Effect<
Uint8Array,
PlatformError.PlatformError
>
nextDoubleUnsafe: () => numbernextDoubleUnsafe,
nextIntUnsafe: () => numbernextIntUnsafe,
digest: (
algorithm: DigestAlgorithm,
data: Uint8Array
) => Effect.Effect<
Uint8Array,
PlatformError.PlatformError
>
impl: {
readonly randomBytes: (
size: number
) => Uint8Array
readonly digest: (
algorithm: DigestAlgorithm,
data: Uint8Array
) => Effect.Effect<
Uint8Array,
PlatformError.PlatformError
>
}
digest: (
algorithm: DigestAlgorithm,
data: Uint8Array
) => Effect.Effect<
Uint8Array,
PlatformError.PlatformError
>
random: Effect.Effect<number, never, never>(property) random: {
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;
}
import EffectEffect.const sync: <A>(
thunk: LazyArg<A>
) => Effect<A>
Creates an Effect that represents a synchronous side-effectful computation.
When to use
Use when you need to wrap a synchronous side-effectful operation that is not
expected to throw.
Details
The provided function is evaluated lazily when the effect runs.
Gotchas
The function must not throw. If it throws, the thrown value is treated as a
defect, not as a typed failure. Use try when throwing is expected.
Example (Capturing synchronous logging in an Effect)
import { Effect } from "effect"
const log = (message: string) =>
Effect.sync(() => {
console.log(message) // side effect
})
// ┌─── Effect<void, never, never>
// ▼
const program = log("Hello, World!")
sync(() => const nextDoubleUnsafe: () => numbernextDoubleUnsafe()),
randomBoolean: Effect.Effect<boolean, never, never>(property) randomBoolean: {
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;
}
import EffectEffect.const sync: <A>(
thunk: LazyArg<A>
) => Effect<A>
Creates an Effect that represents a synchronous side-effectful computation.
When to use
Use when you need to wrap a synchronous side-effectful operation that is not
expected to throw.
Details
The provided function is evaluated lazily when the effect runs.
Gotchas
The function must not throw. If it throws, the thrown value is treated as a
defect, not as a typed failure. Use try when throwing is expected.
Example (Capturing synchronous logging in an Effect)
import { Effect } from "effect"
const log = (message: string) =>
Effect.sync(() => {
console.log(message) // side effect
})
// ┌─── Effect<void, never, never>
// ▼
const program = log("Hello, World!")
sync(() => const nextDoubleUnsafe: () => numbernextDoubleUnsafe() > 0.5),
randomInt: Effect.Effect<number, never, never>(property) randomInt: {
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;
}
import EffectEffect.const sync: <A>(
thunk: LazyArg<A>
) => Effect<A>
Creates an Effect that represents a synchronous side-effectful computation.
When to use
Use when you need to wrap a synchronous side-effectful operation that is not
expected to throw.
Details
The provided function is evaluated lazily when the effect runs.
Gotchas
The function must not throw. If it throws, the thrown value is treated as a
defect, not as a typed failure. Use try when throwing is expected.
Example (Capturing synchronous logging in an Effect)
import { Effect } from "effect"
const log = (message: string) =>
Effect.sync(() => {
console.log(message) // side effect
})
// ┌─── Effect<void, never, never>
// ▼
const program = log("Hello, World!")
sync(() => const nextIntUnsafe: () => numbernextIntUnsafe()),
randomBetween: (
min: any,
max: any
) => Effect.Effect<any, never, never>
min: anymin, max: anymax) => import EffectEffect.const sync: <A>(
thunk: LazyArg<A>
) => Effect<A>
Creates an Effect that represents a synchronous side-effectful computation.
When to use
Use when you need to wrap a synchronous side-effectful operation that is not
expected to throw.
Details
The provided function is evaluated lazily when the effect runs.
Gotchas
The function must not throw. If it throws, the thrown value is treated as a
defect, not as a typed failure. Use try when throwing is expected.
Example (Capturing synchronous logging in an Effect)
import { Effect } from "effect"
const log = (message: string) =>
Effect.sync(() => {
console.log(message) // side effect
})
// ┌─── Effect<void, never, never>
// ▼
const program = log("Hello, World!")
sync(() => const nextDoubleUnsafe: () => numbernextDoubleUnsafe() * (max: anymax - min: anymin) + min: anymin),
function randomIntBetween(min: any, max: any, options: any): Effect.Effect<number, never, never>randomIntBetween(min: anymin, max: anymax, options: anyoptions) {
const const extra: 0 | 1extra = options: anyoptions?.halfOpen === true ? 0 : 1
return import EffectEffect.const sync: <A>(
thunk: LazyArg<A>
) => Effect<A>
Creates an Effect that represents a synchronous side-effectful computation.
When to use
Use when you need to wrap a synchronous side-effectful operation that is not
expected to throw.
Details
The provided function is evaluated lazily when the effect runs.
Gotchas
The function must not throw. If it throws, the thrown value is treated as a
defect, not as a typed failure. Use try when throwing is expected.
Example (Capturing synchronous logging in an Effect)
import { Effect } from "effect"
const log = (message: string) =>
Effect.sync(() => {
console.log(message) // side effect
})
// ┌─── Effect<void, never, never>
// ▼
const program = log("Hello, World!")
sync(() => {
const const minInt: numberminInt = var Math: MathAn intrinsic object that provides basic mathematics functionality and constants.
Math.Math.ceil(x: number): numberReturns the smallest integer greater than or equal to its numeric argument.
ceil(min: anymin)
const const maxInt: numbermaxInt = var Math: MathAn intrinsic object that provides basic mathematics functionality and constants.
Math.Math.floor(x: number): numberReturns the greatest integer less than or equal to its numeric argument.
floor(max: anymax)
return var Math: MathAn intrinsic object that provides basic mathematics functionality and constants.
Math.Math.floor(x: number): numberReturns the greatest integer less than or equal to its numeric argument.
floor(const nextDoubleUnsafe: () => numbernextDoubleUnsafe() * (const maxInt: numbermaxInt - const minInt: numberminInt + const extra: 0 | 1extra)) + const minInt: numberminInt
})
},
randomShuffle: (
elements: any
) => Effect.Effect<unknown[], never, never>
elements: anyelements) =>
import EffectEffect.const sync: <A>(
thunk: LazyArg<A>
) => Effect<A>
Creates an Effect that represents a synchronous side-effectful computation.
When to use
Use when you need to wrap a synchronous side-effectful operation that is not
expected to throw.
Details
The provided function is evaluated lazily when the effect runs.
Gotchas
The function must not throw. If it throws, the thrown value is treated as a
defect, not as a typed failure. Use try when throwing is expected.
Example (Capturing synchronous logging in an Effect)
import { Effect } from "effect"
const log = (message: string) =>
Effect.sync(() => {
console.log(message) // side effect
})
// ┌─── Effect<void, never, never>
// ▼
const program = log("Hello, World!")
sync(() => {
const const buffer: unknown[]buffer = var Array: ArrayConstructorArray.ArrayConstructor.from<unknown>(iterable: Iterable<unknown> | ArrayLike<unknown>): unknown[] (+3 overloads)Creates an array from an iterable object.
from(elements: anyelements)
for (let let i: numberi = const buffer: unknown[]buffer.Array<unknown>.length: numberGets or sets the length of the array. This is a number one higher than the highest index in the array.
length - 1; let i: numberi >= 1; let i: numberi = let i: numberi - 1) {
const const index: numberindex = var Math: MathAn intrinsic object that provides basic mathematics functionality and constants.
Math.Math.min(...values: number[]): numberReturns the smaller of a set of supplied numeric expressions.
min(let i: numberi, var Math: MathAn intrinsic object that provides basic mathematics functionality and constants.
Math.Math.floor(x: number): numberReturns the greatest integer less than or equal to its numeric argument.
floor(const nextDoubleUnsafe: () => numbernextDoubleUnsafe() * (let i: numberi + 1)))
const const value: {}value = const buffer: unknown[]buffer[let i: numberi]!
const buffer: unknown[]buffer[let i: numberi] = const buffer: unknown[]buffer[const index: numberindex]!
const buffer: unknown[]buffer[const index: numberindex] = const value: {}value
}
return const buffer: unknown[]buffer
}),
randomUUIDv4: Effect.Effect<string, never, never>(property) randomUUIDv4: {
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;
}
import EffectEffect.const sync: <A>(
thunk: LazyArg<A>
) => Effect<A>
Creates an Effect that represents a synchronous side-effectful computation.
When to use
Use when you need to wrap a synchronous side-effectful operation that is not
expected to throw.
Details
The provided function is evaluated lazily when the effect runs.
Gotchas
The function must not throw. If it throws, the thrown value is treated as a
defect, not as a typed failure. Use try when throwing is expected.
Example (Capturing synchronous logging in an Effect)
import { Effect } from "effect"
const log = (message: string) =>
Effect.sync(() => {
console.log(message) // side effect
})
// ┌─── Effect<void, never, never>
// ▼
const program = log("Hello, World!")
sync(() => const formatUUIDv4: (
bytes: Uint8Array
) => string
const randomBytesUnsafe: (
size: number
) => Uint8Array
randomUUIDv7: Effect.Effect<string, never, never>(property) randomUUIDv7: {
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;
}
import EffectEffect.const clockWith: <A, E, R>(
f: (clock: Clock) => Effect<A, E, R>
) => Effect<A, E, R>
Retrieves the Clock service from the context and provides it to the
specified effectful function.
Example (Accessing the Clock service)
import { Console, Effect } from "effect"
const program = Effect.clockWith((clock) =>
clock.currentTimeMillis.pipe(
Effect.map((currentTime) => `Current time is: ${currentTime}`),
Effect.tap(Console.log)
)
)
Effect.runFork(program)
// Example Output:
// Current time is: 1735484929744
clockWith((clock: Clock(parameter) clock: {
currentTimeMillisUnsafe: () => number;
currentTimeMillis: Effect<number>;
currentTimeNanosUnsafe: () => bigint;
currentTimeNanos: Effect<bigint>;
sleep: (duration: Duration.Duration) => Effect<void>;
}
import EffectEffect.const succeed: <A>(value: A) => Effect<A>Creates an Effect that always succeeds with a given value.
When to use
Use when an effect should complete successfully with a specific value without any errors
or external dependencies.
Example (Creating a successful effect)
import { Effect } from "effect"
// Creating an effect that represents a successful scenario
//
// ┌─── Effect<number, never, never>
// ▼
const success = Effect.succeed(42)
succeed(const formatUUIDv7: (
timestampMillis: number,
bytes: Uint8Array
) => string
clock: Clock(parameter) clock: {
currentTimeMillisUnsafe: () => number;
currentTimeMillis: Effect<number>;
currentTimeNanosUnsafe: () => bigint;
currentTimeNanos: Effect<bigint>;
sleep: (duration: Duration.Duration) => Effect<void>;
}
const randomBytesUnsafe: (
size: number
) => Uint8Array