UserDirectories unstable

Well-known directories for an application's persisted data.

UserDirectories resolves where an application should keep its configuration, data, cache and state, following the conventions of the host platform. The resolved directories are what KeyValueStore.layerFileSystem expects.

Example Backing a key-value store with the config directory

import { Effect, Layer } from "effect"
import { KeyValueStore, UserDirectories } from "effect/persistence"

const StoreLive = Layer.unwrap(
  Effect.gen(function*() {
    const dirs = yield* UserDirectories.UserDirectories
    return KeyValueStore.layerFileSystem(yield* dirs.config("myapp"))
  })
).pipe(Layer.provide(UserDirectories.layer))

7 exports Since v4.0.0 Source

Constructors

make

unstable

Since v4.0.0

Creates a resolver that reads the environment from the current ConfigProvider on every call, using the conventions of platform, which defaults to the host platform.

Signature

declare function make(options?: {
  readonly platform?: string;
}): UserDirectories

Example Resolving for another platform

import { ConfigProvider, Effect } from "effect"
import { UserDirectories } from "effect/persistence"

const dirs = UserDirectories.make({ platform: "darwin" })

const program = dirs.cache("myapp").pipe(
  Effect.provideService(
    ConfigProvider.ConfigProvider,
    ConfigProvider.fromEnv({ env: { HOME: "/Users/ada" } })
  )
)

await Effect.runPromise(program) // => "/Users/ada/Library/Caches/myapp"

Layers

layer

unstable

Since v4.0.0

Layer that resolves directories for the host platform.

Signature

declare const layer: Layer.Layer<UserDirectories>

layerPlatform

unstable

Since v4.0.0

Layer that resolves directories for the given platform, such as "win32", "darwin" or "linux".

Signature

declare function layerPlatform(platform: string): Layer<UserDirectories>

Models

UserDirectories

interface unstable

Since v4.0.0

Resolves the directories where an application keeps its files.

Details

An absolute XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_CACHE_HOME or XDG_STATE_HOME is used on every platform, with the application name appended. A relative one is ignored. Otherwise the native location is used:

kind	Windows	macOS	other
config	`%APPDATA%`	`~/Library/Application Support`	`~/.config`
data	`%APPDATA%`	`~/Library/Application Support`	`~/.local/share`
cache	`%LOCALAPPDATA%`, then `\Cache` suffix	`~/Library/Caches`	`~/.cache`
state	`%LOCALAPPDATA%`	`~/Library/Application Support`	`~/.local/state`

APPDATA and LOCALAPPDATA are used when absolute and otherwise replaced by %USERPROFILE%\AppData\Roaming and %USERPROFILE%\AppData\Local.

Gotchas

config and data resolve to the same directory on Windows and macOS, and state joins them on macOS. That is the native convention. Keep each kind in its own subdirectory when the same application uses more than one, since KeyValueStore.layerFileSystem clears a directory recursively.

Signature

interface UserDirectories {
  readonly "~effect/persistence/UserDirectories": "~effect/persistence/UserDirectories";
  readonly cache: (appName: string) => Effect<string, PlatformError>;
  readonly config: (appName: string) => Effect<string, PlatformError>;
  readonly data: (appName: string) => Effect<string, PlatformError>;
  readonly home: Effect<string, PlatformError>;
  readonly state: (appName: string) => Effect<string, PlatformError>;
}

Services

UserDirectories

unstable

Since v4.0.0

Service tag for the user directory resolver.

Signature

declare const UserDirectories: Service<UserDirectories, UserDirectories>

Type Ids

TypeId

unstable

Since v4.0.0

Identifies a UserDirectories service.

Signature

declare const TypeId: TypeId

TypeId

type unstable

Since v4.0.0

Type of the UserDirectories type id.

Signature

type TypeId = "~effect/persistence/UserDirectories"