(options?: {
readonly path?: string | undefined
readonly expandVariables?: boolean | undefined
readonly preserveEmptyStrings?: boolean | undefined
}): Effect.Effect<ConfigProvider, PlatformError, FileSystem.FileSystem>Creates a ConfigProvider by reading and parsing a .env file from the
file system.
When to use
Use to load environment config from a .env file at application startup.
Details
Requires FileSystem in the Effect context. Defaults to reading ".env" in
the current directory; override with { path: "/custom/.env" }.
Variable expansion (for example, ${VAR}) is disabled by default; enable
with { expandVariables: true }.
Literal empty strings are treated as missing values when loaded as values by
default. Pass { preserveEmptyStrings: true } to keep empty strings as
explicit values. Child discovery still reflects the keys present in the
parsed .env source.
Returns an Effect that resolves to a ConfigProvider. Fails with a
PlatformError if the file cannot be read.
Example (Loading a .env file)
import { ConfigProvider, Effect } from "effect"
const program = Effect.gen(function*() {
const provider = yield* ConfigProvider.fromDotEnv()
return provider
})Source effect/ConfigProvider.ts:111011 lines
export const const fromDotEnv: (options?: {
readonly path?: string | undefined
readonly expandVariables?: boolean | undefined
readonly preserveEmptyStrings?:
| boolean
| undefined
}) => Effect.Effect<
ConfigProvider,
PlatformError,
FileSystem.FileSystem
>
Creates a ConfigProvider by reading and parsing a .env file from the
file system.
When to use
Use to load environment config from a .env file at application startup.
Details
Requires FileSystem in the Effect context. Defaults to reading ".env" in
the current directory; override with { path: "/custom/.env" }.
Variable expansion (for example, ${VAR}) is disabled by default; enable
with { expandVariables: true }.
Literal empty strings are treated as missing values when loaded as values by
default. Pass { preserveEmptyStrings: true } to keep empty strings as
explicit values. Child discovery still reflects the keys present in the
parsed .env source.
Returns an Effect that resolves to a ConfigProvider. Fails with a
PlatformError if the file cannot be read.
Example (Loading a .env file)
import { ConfigProvider, Effect } from "effect"
const program = Effect.gen(function*() {
const provider = yield* ConfigProvider.fromDotEnv()
return provider
})
fromDotEnv: (options: | {
readonly path?: string | undefined
readonly expandVariables?:
| boolean
| undefined
readonly preserveEmptyStrings?:
| boolean
| undefined
}
| undefined
path?: string | undefinedpath?: string | undefined
readonly expandVariables?: boolean | undefinedexpandVariables?: boolean | undefined
readonly preserveEmptyStrings?: boolean | undefinedpreserveEmptyStrings?: boolean | undefined
}) => 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<ConfigProvider, 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: BadArgument | 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, import FileSystemFileSystem.FileSystem> = import EffectEffect.const fnUntraced: <Effect.Effect<FileSystem.FileSystem, never, FileSystem.FileSystem> | Effect.Effect<string, PlatformError, never>, ConfigProvider, [options: {
readonly path?: string | undefined;
readonly expandVariables?: boolean | undefined;
readonly preserveEmptyStrings?: boolean | undefined;
} | undefined]>(body: (this: unassigned, options: {
readonly path?: string | undefined;
readonly expandVariables?: boolean | undefined;
readonly preserveEmptyStrings?: boolean | undefined;
} | undefined) => Generator<...>) => (options: {
readonly path?: string | undefined;
readonly expandVariables?: boolean | undefined;
readonly preserveEmptyStrings?: boolean | undefined;
} | undefined) => Effect.Effect<...> (+41 overloads)
options: | {
readonly path?: string | undefined
readonly expandVariables?:
| boolean
| undefined
readonly preserveEmptyStrings?:
| boolean
| undefined
}
| undefined
const fs: FileSystem.FileSystemconst fs: {
access: (path: string, options?: { readonly ok?: boolean | undefined; readonly readable?: boolean | undefined; readonly writable?: boolean | undefined }) => Effect.Effect<void, PlatformError>;
copy: (fromPath: string, toPath: string, options?: { readonly overwrite?: boolean | undefined; readonly preserveTimestamps?: boolean | undefined }) => Effect.Effect<void, PlatformError>;
copyFile: (fromPath: string, toPath: string) => Effect.Effect<void, PlatformError>;
chmod: (path: string, mode: number) => Effect.Effect<void, PlatformError>;
chown: (path: string, uid: number, gid: number) => Effect.Effect<void, PlatformError>;
glob: (pattern: string, options?: { readonly root?: string | undefined; readonly exclude?: ReadonlyArray<string> | undefined }) => Effect.Effect<Array<string>, PlatformError>;
exists: (path: string) => Effect.Effect<boolean, PlatformError>;
link: (fromPath: string, toPath: string) => Effect.Effect<void, PlatformError>;
makeDirectory: (path: string, options?: { readonly recursive?: boolean | undefined; readonly mode?: number | undefined }) => Effect.Effect<void, PlatformError>;
makeTempDirectory: (options?: { readonly directory?: string | undefined; readonly prefix?: string | undefined }) => Effect.Effect<string, PlatformError>;
makeTempDirectoryScoped: (options?: { readonly directory?: string | undefined; readonly prefix?: string | undefined }) => Effect.Effect<string, PlatformError, Scope>;
makeTempFile: (options?: { readonly directory?: string | undefined; readonly prefix?: string | undefined; readonly suffix?: string | undefined }) => Effect.Effect<string, PlatformError>;
makeTempFileScoped: (options?: { readonly directory?: string | undefined; readonly prefix?: string | undefined; readonly suffix?: string | undefined }) => Effect.Effect<string, PlatformError, Scope>;
open: (path: string, options?: { readonly flag?: OpenFlag | undefined; readonly mode?: number | undefined }) => Effect.Effect<File, PlatformError, Scope>;
readDirectory: (path: string, options?: { readonly recursive?: boolean | undefined }) => Effect.Effect<Array<string>, PlatformError>;
readFile: (path: string) => Effect.Effect<Uint8Array, PlatformError>;
readFileString: (path: string, encoding?: string) => Effect.Effect<string, PlatformError>;
readLink: (path: string) => Effect.Effect<string, PlatformError>;
realPath: (path: string) => Effect.Effect<string, PlatformError>;
remove: (path: string, options?: { readonly recursive?: boolean | undefined; readonly force?: boolean | undefined }) => Effect.Effect<void, PlatformError>;
rename: (oldPath: string, newPath: string) => Effect.Effect<void, PlatformError>;
sink: (path: string, options?: { readonly flag?: OpenFlag | undefined; readonly mode?: number | undefined }) => Sink.Sink<void, Uint8Array, never, PlatformError>;
stat: (path: string) => Effect.Effect<File.Info, PlatformError>;
stream: (path: string, options?: { readonly bytesToRead?: SizeInput | undefined; readonly chunkSize?: SizeInput | undefined; readonly offset?: SizeInput | undefined }) => Stream.Stream<Uint8Array, PlatformError>;
symlink: (fromPath: string, toPath: string) => Effect.Effect<void, PlatformError>;
truncate: (path: string, length?: SizeInput) => Effect.Effect<void, PlatformError>;
utimes: (path: string, atime: Date | number, mtime: Date | number) => Effect.Effect<void, PlatformError>;
watch: (path: string) => Stream.Stream<WatchEvent, PlatformError>;
writeFile: (path: string, data: Uint8Array, options?: { readonly flag?: OpenFlag | undefined; readonly mode?: number | undefined }) => Effect.Effect<void, PlatformError>;
writeFileString: (path: string, data: string, options?: { readonly flag?: OpenFlag | undefined; readonly mode?: number | undefined }) => Effect.Effect<void, PlatformError>;
}
import FileSystemFileSystem.const FileSystem: Context.Service<
FileSystem,
FileSystem
>
const FileSystem: {
key: string;
Service: {
access: (path: string, options?: { readonly ok?: boolean | undefined; readonly readable?: boolean | undefined; readonly writable?: boolean | undefined }) => Effect.Effect<void, PlatformError>;
copy: (fromPath: string, toPath: string, options?: { readonly overwrite?: boolean | undefined; readonly preserveTimestamps?: boolean | undefined }) => Effect.Effect<void, PlatformError>;
copyFile: (fromPath: string, toPath: string) => Effect.Effect<void, PlatformError>;
chmod: (path: string, mode: number) => Effect.Effect<void, PlatformError>;
chown: (path: string, uid: number, gid: number) => Effect.Effect<void, PlatformError>;
glob: (pattern: string, options?: { readonly root?: string | undefined; readonly exclude?: ReadonlyArray<string> | undefined }) => Effect.Effect<Array<string>, PlatformError>;
exists: (path: string) => Effect.Effect<boolean, PlatformError>;
link: (fromPath: string, toPath: string) => Effect.Effect<void, PlatformError>;
makeDirectory: (path: string, options?: { readonly recursive?: boolean | undefined; readonly mode?: number | undefined }) => Effect.Effect<void, PlatformError>;
makeTempDirectory: (options?: { readonly directory?: string | undefined; readonly prefix?: string | undefined }) => Effect.Effect<string, PlatformError>;
makeTempDirectoryScoped: (options?: { readonly directory?: string | undefined; readonly prefix?: string | undefined }) => Effect.Effect<string, PlatformError, Scope>;
makeTempFile: (options?: { readonly directory?: string | undefined; readonly prefix?: string | undefined; readonly suffix?: string | undefined }) => Effect.Effect<string, PlatformError>;
makeTempFileScoped: (options?: { readonly directory?: string | undefined; readonly prefix?: string | undefined; readonly suffix?: string | undefined }) => Effect.Effect<string, PlatformError, Scope>;
open: (path: string, options?: { readonly flag?: OpenFlag | undefined; readonly mode?: number | undefined }) => Effect.Effect<File, PlatformError, Scope>;
readDirectory: (path: string, options?: { readonly recursive?: boolean | undefined }) => Effect.Effect<Array<string>, PlatformError>;
readFile: (path: string) => Effect.Effect<Uint8Array, PlatformError>;
readFileString: (path: string, encoding?: string) => Effect.Effect<string, PlatformError>;
readLink: (path: string) => Effect.Effect<string, PlatformError>;
realPath: (path: string) => Effect.Effect<string, PlatformError>;
remove: (path: string, options?: { readonly recursive?: boolean | undefined; readonly force?: boolean | undefined }) => Effect.Effect<void, PlatformError>;
rename: (oldPath: string, newPath: string) => Effect.Effect<void, PlatformError>;
sink: (path: string, options?: { readonly flag?: OpenFlag | undefined; readonly mode?: number | undefined }) => Sink.Sink<void, Uint8Array, never, PlatformError>;
stat: (path: string) => Effect.Effect<File.Info, PlatformError>;
stream: (path: string, options?: { readonly bytesToRead?: SizeInput | undefined; readonly chunkSize?: SizeInput | undefined; readonly offset?: SizeInput | undefined }) => Stream.Stream<Uint8Array, PlatformError>;
symlink: (fromPath: string, toPath: string) => Effect.Effect<void, PlatformError>;
truncate: (path: string, length?: SizeInput) => Effect.Effect<void, PlatformError>;
utimes: (path: string, atime: Date | number, mtime: Date | number) => Effect.Effect<void, PlatformError>;
watch: (path: string) => Stream.Stream<WatchEvent, PlatformError>;
writeFile: (path: string, data: Uint8Array, options?: { readonly flag?: OpenFlag | undefined; readonly mode?: number | undefined }) => Effect.Effect<void, PlatformError>;
writeFileString: (path: string, data: string, options?: { readonly flag?: OpenFlag | undefined; readonly mode?: number | undefined }) => Effect.Effect<void, PlatformError>;
};
of: (this: void, self: FileSystem.FileSystem) => FileSystem.FileSystem;
context: (self: FileSystem.FileSystem) => Context.Context<FileSystem.FileSystem>;
use: (f: (service: FileSystem.FileSystem) => Effect.Effect<A, E, R>) => Effect.Effect<A, E, FileSystem.FileSystem | R>;
useSync: (f: (service: FileSystem.FileSystem) => A) => Effect.Effect<A, never, FileSystem.FileSystem>;
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;
}
Core interface for file system operations in Effect.
Details
The FileSystem interface provides a comprehensive set of file and directory operations
that work cross-platform. All operations return Effect values that can be composed,
transformed, and executed safely with proper error handling.
Example (Accessing file system operations)
import { Console, Effect, FileSystem } from "effect"
const program = Effect.gen(function*() {
const fs = yield* FileSystem.FileSystem
// Basic file operations
const exists = yield* fs.exists("./config.json")
if (!exists) {
yield* fs.writeFileString("./config.json", "{\"env\": \"development\"}")
}
// Directory operations
yield* fs.makeDirectory("./logs", { recursive: true })
// File information
const stats = yield* fs.stat("./config.json")
yield* Console.log(`File size: ${stats.size} bytes`)
// Streaming operations
const content = yield* fs.readFileString("./config.json")
yield* Console.log("Config:", content)
})
Service tag for platform file-system operations.
When to use
Use to access or provide operations for files, directories, permissions,
streams, and sinks through the Effect context.
Details
This key is used to provide and access the FileSystem service in the Effect context.
Example (Accessing and providing FileSystem)
import { Effect, FileSystem } from "effect"
// Access the FileSystem service
const program = Effect.gen(function*() {
const fs = yield* FileSystem.FileSystem
const exists = yield* fs.exists("./data.txt")
if (exists) {
const content = yield* fs.readFileString("./data.txt")
yield* Effect.log("File content:", content)
}
})
// Provide a custom FileSystem implementation
declare const platformImpl: Omit<
FileSystem.FileSystem,
"exists" | "readFileString" | "stream" | "sink" | "writeFileString"
>
const customFs = FileSystem.make(platformImpl)
const withCustomFs = Effect.provideService(
program,
FileSystem.FileSystem,
customFs
)
FileSystem
const const content: stringcontent = yield* const fs: FileSystem.FileSystemconst fs: {
access: (path: string, options?: { readonly ok?: boolean | undefined; readonly readable?: boolean | undefined; readonly writable?: boolean | undefined }) => Effect.Effect<void, PlatformError>;
copy: (fromPath: string, toPath: string, options?: { readonly overwrite?: boolean | undefined; readonly preserveTimestamps?: boolean | undefined }) => Effect.Effect<void, PlatformError>;
copyFile: (fromPath: string, toPath: string) => Effect.Effect<void, PlatformError>;
chmod: (path: string, mode: number) => Effect.Effect<void, PlatformError>;
chown: (path: string, uid: number, gid: number) => Effect.Effect<void, PlatformError>;
glob: (pattern: string, options?: { readonly root?: string | undefined; readonly exclude?: ReadonlyArray<string> | undefined }) => Effect.Effect<Array<string>, PlatformError>;
exists: (path: string) => Effect.Effect<boolean, PlatformError>;
link: (fromPath: string, toPath: string) => Effect.Effect<void, PlatformError>;
makeDirectory: (path: string, options?: { readonly recursive?: boolean | undefined; readonly mode?: number | undefined }) => Effect.Effect<void, PlatformError>;
makeTempDirectory: (options?: { readonly directory?: string | undefined; readonly prefix?: string | undefined }) => Effect.Effect<string, PlatformError>;
makeTempDirectoryScoped: (options?: { readonly directory?: string | undefined; readonly prefix?: string | undefined }) => Effect.Effect<string, PlatformError, Scope>;
makeTempFile: (options?: { readonly directory?: string | undefined; readonly prefix?: string | undefined; readonly suffix?: string | undefined }) => Effect.Effect<string, PlatformError>;
makeTempFileScoped: (options?: { readonly directory?: string | undefined; readonly prefix?: string | undefined; readonly suffix?: string | undefined }) => Effect.Effect<string, PlatformError, Scope>;
open: (path: string, options?: { readonly flag?: OpenFlag | undefined; readonly mode?: number | undefined }) => Effect.Effect<File, PlatformError, Scope>;
readDirectory: (path: string, options?: { readonly recursive?: boolean | undefined }) => Effect.Effect<Array<string>, PlatformError>;
readFile: (path: string) => Effect.Effect<Uint8Array, PlatformError>;
readFileString: (path: string, encoding?: string) => Effect.Effect<string, PlatformError>;
readLink: (path: string) => Effect.Effect<string, PlatformError>;
realPath: (path: string) => Effect.Effect<string, PlatformError>;
remove: (path: string, options?: { readonly recursive?: boolean | undefined; readonly force?: boolean | undefined }) => Effect.Effect<void, PlatformError>;
rename: (oldPath: string, newPath: string) => Effect.Effect<void, PlatformError>;
sink: (path: string, options?: { readonly flag?: OpenFlag | undefined; readonly mode?: number | undefined }) => Sink.Sink<void, Uint8Array, never, PlatformError>;
stat: (path: string) => Effect.Effect<File.Info, PlatformError>;
stream: (path: string, options?: { readonly bytesToRead?: SizeInput | undefined; readonly chunkSize?: SizeInput | undefined; readonly offset?: SizeInput | undefined }) => Stream.Stream<Uint8Array, PlatformError>;
symlink: (fromPath: string, toPath: string) => Effect.Effect<void, PlatformError>;
truncate: (path: string, length?: SizeInput) => Effect.Effect<void, PlatformError>;
utimes: (path: string, atime: Date | number, mtime: Date | number) => Effect.Effect<void, PlatformError>;
watch: (path: string) => Stream.Stream<WatchEvent, PlatformError>;
writeFile: (path: string, data: Uint8Array, options?: { readonly flag?: OpenFlag | undefined; readonly mode?: number | undefined }) => Effect.Effect<void, PlatformError>;
writeFileString: (path: string, data: string, options?: { readonly flag?: OpenFlag | undefined; readonly mode?: number | undefined }) => Effect.Effect<void, PlatformError>;
}
FileSystem.readFileString: (path: string, encoding?: string) => Effect.Effect<string, PlatformError>Read the contents of a file.
readFileString(options: | {
readonly path?: string | undefined
readonly expandVariables?:
| boolean
| undefined
readonly preserveEmptyStrings?:
| boolean
| undefined
}
| undefined
path?: string | undefinedpath ?? ".env")
return function fromDotEnvContents(
lines: string,
options?: {
readonly expandVariables?: boolean | undefined
readonly preserveEmptyStrings?:
| boolean
| undefined
}
): ConfigProvider
Creates a ConfigProvider by parsing the string contents of a .env file.
When to use
Use when you already have the .env contents as a string, such as contents
fetched from a remote store or embedded in a test.
Details
Supports export prefixes, single/double/backtick quoting, inline comments,
and escaped newlines. Variable expansion (for example, ${VAR}) is disabled
by default; enable with { expandVariables: true }.
Literal empty strings are treated as missing values when loaded as values by
default. Pass { preserveEmptyStrings: true } to keep empty strings as
explicit values. Child discovery still reflects the keys present in the
parsed .env source.
Parsing is based on the dotenv / dotenv-expand algorithm.
Internally delegates to
fromEnv
with the parsed key-value pairs.
Example (Parsing .env contents)
import { ConfigProvider } from "effect"
const contents = `
HOST=localhost
PORT=3000
# this is a comment
`
const provider = ConfigProvider.fromDotEnvContents(contents)
fromDotEnvContents(const content: stringcontent, options: | {
readonly path?: string | undefined
readonly expandVariables?:
| boolean
| undefined
readonly preserveEmptyStrings?:
| boolean
| undefined
}
| undefined