Skip to content
devsess
Esc
↑↓navigate↵open⌘Jpreview

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. write shallow-merges data into the existing JSON, so distinct slots (distinct schemas) coexist by key — but a key collision between two slots silently overwrites.
  • read resolves null, not Option — both when the file is missing and when decoding fails.
  • write creates 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, write fails with SessionStateError (_tag: 'SessionStateError') instead of merging into it — read is the one that degrades corrupt content to null, not write.

Was this page helpful?