devsess
The Effect-based core: DevSessions and CurrentSession (services + layers), and free functions for sticky ports, managed subprocesses, and cross-package running signals. See Writing a dev CLI for how these fit around a stock Command.make(...), and Running your dev server for subprocess lifetime.
Peer: effect (^4.0.0). No platform package is a peer — devsess depends on neither; provide something satisfying FileSystem | Path yourself (both @effect/platform-node’s NodeServices.layer and @effect/platform-bun’s BunServices.layer do, since each is a superset).
bun add devsess effect @effect/platform-node
bun add devsess effect @effect/platform-bun
DevSessions
Context.Service tag for the session store.
class DevSessions extends Context.Service<
DevSessions,
{
readonly dir: string
readonly path: (relativePath: string) => string
readonly getSessions: Effect.Effect<Array<DevSession>, PlatformError>
readonly createSession: Effect.Effect<DevSession, PlatformError>
readonly getLatestOrCreate: Effect.Effect<DevSession, PlatformError>
readonly getOrCreate: (name: string) => Effect.Effect<DevSession, PlatformError>
}
>()('devsess/DevSessions') {
static readonly layerAt: (rootDir: string) => Layer.Layer<DevSessions, never, FileSystem | Path>
static readonly layer: Layer.Layer<DevSessions, PlatformError | ProjectRootNotFoundError, FileSystem | Path>
}
| Member | Type | Description |
|---|---|---|
dir |
string |
The root this instance was built with — rootDir verbatim, not the sessions subdirectory |
path(relativePath) |
(relativePath: string) => string |
Joins relativePath onto dir — a project file, not a session file |
getSessions |
Effect.Effect<Array<DevSession>, PlatformError> |
Lists session subdirectories with their mtimes. [] if the root doesn’t exist yet — not an error |
createSession |
Effect.Effect<DevSession, PlatformError> |
Creates a new session directory with a fresh slug |
getLatestOrCreate |
Effect.Effect<DevSession, PlatformError> |
Ensures the root exists, then returns the session with the newest directory mtime — or creates one if none exist |
getOrCreate(name) |
Effect.Effect<DevSession, PlatformError> |
Returns the named session, creating its directory if needed; use a single directory name |
getSessions, createSession, and getLatestOrCreate are Effects already bound to the resolved service instance, not functions — read them off the service, e.g. (yield* DevSessions).getLatestOrCreate.
DevSessions.layerAt(rootDir) — rooted at rootDir explicitly: dir/path resolve against rootDir itself (e.g. sessions.path('drizzle') reaches a project’s real drizzle/ folder), while session directories are namespaced under <rootDir>/.data/sessions. No directory I/O happens when the layer is built, only when its methods run.
DevSessions.layer — layerAt rooted at the auto-detected project root: the nearest ancestor of process.cwd() containing a package.json, found by walking up one directory at a time. Fails with ProjectRootNotFoundError if no ancestor has one, instead of silently falling back to process.cwd().
Deliberately does not also provide CurrentSession — see CurrentSession below for why.
ProjectRootNotFoundError
class ProjectRootNotFoundError extends Data.TaggedError('ProjectRootNotFoundError')<{
readonly searchedFrom: string
}> {}
Raised by DevSessions.layer when no ancestor of searchedFrom (process.cwd() at the start of the search) contains a package.json.
CurrentSession
Context.Service tag holding the session resolved for a single command run.
class CurrentSession extends Context.Service<CurrentSession, DevSession>()('devsess/CurrentSession') {
static readonly layer: Layer.Layer<CurrentSession, PlatformError, DevSessions>
static readonly layerOf: (session: DevSession) => Layer.Layer<CurrentSession, never, never>
}
yield* CurrentSession always gives a plain DevSession — never a wrapper effect to unwrap.
CurrentSession.layer — resolves the session via DevSessions#getLatestOrCreate, cached for the run via layer memoization (two yield* CurrentSession in the same provided scope resolve the identical session, one lookup). Provide this around a command’s own handler effect, not the whole CLI program: a Layer’s build effect runs the moment it’s provided, so wrapping Command.run itself would create a session for --help, --version, or a bad flag too, none of which ever reach a handler.
CurrentSession.layerOf(session) — pins an explicit session instead of resolving one via DevSessions. For tests.
DevSession
type DevSession = {
rootDir: string
name: string
lastModifiedAt: Date | null
path: (relativePath: string) => Effect.Effect<string, never, never>
toString: () => string
}
| Member | Description |
|---|---|
name |
Session slug — a single noun, e.g. walrus |
lastModifiedAt |
Directory mtime as of the last listing; null for a session just created in this call |
rootDir |
Project directory carried by every session; shared services use it for root discovery |
path(relativePath) |
Joins relativePath onto the session directory. Pure path math — does not create the directory or touch the filesystem |
toString() |
Returns name |
getStickyPort
function getStickyPort(
session: DevSession,
options?: { name?: string },
): Effect.Effect<number, PlatformError | SessionStateError, FileSystem | Path>
Reads the port already stored under options?.name ?? 'default' in session’s sess.json ({ ports: Record<string, number> }), passes it to get-port as a preference, and writes back whichever port that call actually returns, keyed by that same name. The ports remembered under every other name are passed to get-port as exclude, so resolving one name can never return a port another name is holding. A sess.json written before named ports existed has a top-level port instead of ports — still read once, as the seed for default, but never written again once the new shape lands. Not cached — every call re-reads and re-asks; call it once per name per run and reuse the returned number. Built on SessionState.slot internally, so a sess.json corrupted by something outside devsess surfaces here as SessionStateError too.
runManagedSubprocess
function runManagedSubprocess(
cmd: string,
args: string[],
opts?: { env?: Record<string, string> },
): Effect.Effect<ExitCode, PlatformError, ChildProcessSpawner | Scope.Scope>
Takes no DevSession — it only needs a scope to register cleanup against and something to spawn a process with. ExitCode (effect/process) is a branded number.
| Parameter | Type | |
|---|---|---|
cmd |
string |
The executable to run |
args |
string[] |
Arguments passed to it |
opts.env |
Record<string, string> |
Extra environment variables, merged over process.env — they add and override, they don’t replace it |
Resolves to the child’s exit code, once the child exits. stdio is inherit for stdin/stdout/stderr, so child output goes straight to your terminal. The child is registered against the ambient Scope — killed when it closes (script exit, throw, or Ctrl-C); a failed kill is logged, not thrown.
publishRunning, awaitRunning
function publishRunning(
data: unknown,
): Effect.Effect<void, PlatformError, DevSessions | FileSystem | Path | Scope.Scope>
function awaitRunning<T>(
pkg: string,
): Effect.Effect<T, PlatformError, DevSessions | FileSystem | Path>
Neither takes a session — both pull the project root from DevSessions in context.
publishRunning(data) — writes data as JSON to <DevSessions#dir>/.data/running.json, atomically (temp file, then rename, so readers never see a partial write). Deletes that file when its scope closes, so a crashed or exited publisher leaves no stale signal behind. When the process was launched as a devsess CLI service, it also publishes the same value to the daemon using the injected DEVSESS_SOCKET, DEVSESS_RUN_ID, and DEVSESS_SERVICE environment variables. The daemon stores it with a timestamp, shows it as ready in devsess status, and clears it on release or service exit. A URL can be published as { url: 'http://localhost:5173' }, or multiple named URLs as { urls: { app: 'http://localhost:5173', api: 'http://localhost:3000' } }; other JSON values are shown compactly. If the daemon cannot accept the publication, the dev script warns once on stderr and continues using the file signal.
awaitRunning<T>(pkg) — reads another package’s running-signal file, not this project’s own. pkg starting with . or / resolves as a path relative to DevSessions#dir; anything else is resolved as a package name via require.resolve('<pkg>/package.json'). Creates the sibling’s .data directory if it doesn’t exist yet (fs.watch would otherwise throw synchronously on a missing directory), then waits using fs.watch on it (no polling), plus one immediate read to catch the already-published case. No timeout — waits indefinitely.
Running signals are not session-scoped — they coordinate across sibling packages in a monorepo, keyed by project directory. See Wiring services together.
SessionState.slot
namespace SessionState {
function slot<T extends Schema.Top>(schema: T): {
read: (session: DevSession) => Effect.Effect<T['Type'] | null, PlatformError, FileSystem | T['DecodingServices']>
write: (session: DevSession, data: T['Type']) => Effect.Effect<void, PlatformError | SessionStateError, FileSystem | Path>
}
}
class SessionStateError extends Data.TaggedError('SessionStateError')<{
message: string
cause?: unknown
}> {}
devsess doesn’t re-export Schema — build schema from effect directly (import { Schema } from 'effect').
- All slots for a session share one file,
<session>/sess.json.writeshallow-mergesdatainto the existing JSON, so distinct slots (distinct schemas) coexist by key — but a key collision between two slots silently overwrites. readresolvesnull, notOption— both when the file is missing and when decoding fails.writecreates the parent directory before writing, but the write itself is not atomic (no temp-file-then-rename, unlike the running-signal file). If the on-disk JSON is corrupt,writefails withSessionStateError(_tag: 'SessionStateError') instead of merging into it —readis the one that degrades corrupt content tonull, notwrite.