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

devsess/async

Promise-based facade over the same core as devsess, for dev scripts that would rather not import effect directly. Its shape doesn’t mirror devsess member-for-member anymore — the Effect API exports services and layers around a stock Command.make(...) (see Writing a dev CLI), while devsess/async keeps the config-object defineDevCli it always had, since it’s the one facade that legitimately owns main. This page documents this facade in full; it links to devsess wherever the underlying behavior — session picking, sticky ports, subprocess cleanup — is identical. See Without Effect.

Needs the same peer installed as devsess (effect) plus a platform package (@effect/platform-node or @effect/platform-bun), even though you don’t import effect yourself — see Getting Started.

defineDevCli

function defineDevCli(config: {
	name: string
	dir: string
	platform: DevPlatform
	options?: CommandConfig
	run: (ctx: AsyncRunContext, opts: Record<string, unknown>) => Promise<void> | void
}): (argv: string[]) => void

Unlike the Effect API — which stops wrapping effect/cli and hands you services and layers instead (see Writing a dev CLI) — devsess/async keeps this config-object shape on purpose: it’s the one facade that legitimately owns main for callers who’d rather not reach for effect at all. run returns Promise<void> | void instead of an Effect, and every ctx member returns a Promise. --version is hardcoded to 0.0.0 here (the Effect side’s Command.run/Command.runWith takes a real version string; this facade doesn’t expose an equivalent option).

Each ctx call runs against the single process-lifetime scope defineDevCli opens internally — not a fresh scope per call — so a subprocess started via ctx.runManagedSubprocess or a file written by ctx.publishRunning stays alive until the CLI process itself ends, not until that individual Promise settles.

DevPlatform, DevServices

type DevServices = ChildProcessSpawner | FileSystem | Path | Stdio | Terminal

type DevPlatform = {
	readonly services: Layer.Layer<DevServices>
	readonly runMain: RunMain // same shape as NodeRuntime.runMain / BunRuntime.runMain
}

devsess/async needs these core effect service tags and a way to run its main Effect, but depends on no platform package to supply them — you pass a DevPlatform to defineDevCli. Both @effect/platform-node’s { NodeServices.layer, NodeRuntime.runMain } and @effect/platform-bun’s { BunServices.layer, BunRuntime.runMain } satisfy it, since each platform’s service union is a superset of DevServices.

Exported only from devsess/async — the Effect API’s own layers only need FileSystem | Path (see devsess), so it has no equivalent type.

AsyncRunContext

The ctx object passed to run. Promise-returning mirror of the Effect core’s free functions (getStickyPort, runManagedSubprocess, publishRunning, awaitRunning — see devsess), bundled into one object.

Member Type
session() () => Promise<DevSession>
getStickyPort(options?) (options?: { name?: string }) => Promise<number>
runManagedSubprocess(cmd, args, opts?) (cmd: string, args: string[], opts?: { env?: Record<string, string> }) => Promise<ExitCode>
publishRunning(data) (data: unknown) => Promise<void>
awaitRunning<T>(pkg) (pkg: string) => Promise<T>

Differences from the Effect functions that bite:

  • session is a function, not a service tag — call await ctx.session() every time you need it. It’s still resolved at most once per run internally (Effect.cached), so repeated calls don’t repeat the session lookup.
  • getStickyPort(options?) is not cached, same as the Effect version — every call re-reads the stored port and re-asks get-port. Call it once per name per run and reuse the number. Omit options (or options.name) to resolve the port named default — see getStickyPort for how names are stored and excluded from each other.
  • runManagedSubprocess, publishRunning, and awaitRunning don’t take a session either — same as their Effect counterparts, they only need the scope defineDevCli opens internally (see above), or the project root for the latter two.

Otherwise identical: runManagedSubprocess merges env over process.env and inherits stdio; publishRunning writes atomically, deletes its file on process exit, and reports readiness to the CLI daemon when launched by devsess start; awaitRunning has no timeout.

DevSession

type DevSession = {
	readonly name: string
	readonly lastModifiedAt: Date | null
	path(relativePath: string): string
	toString(): string
}

Same fields as the Effect DevSession, except path(relativePath) is synchronous and returns string directly — no Effect, no Promise. Safe because the underlying Effect path is pure (Effect.succeed); it’s run with Effect.runSync internally. Still doesn’t create the directory.

This session isn’t interchangeable with the Effect one: prepareSessionPglite (devsess/pglite) expects a session whose path() returns an Effect, and the bridge back to that shape isn’t exported from this package. See devsess/pglite.

createDevSessions

function createDevSessions(
	rootDir: string,
	services: Layer.Layer<DevServices>,
): DevSessionManager

type DevSessionManager = {
	readonly dir: string
	getSessions(): Promise<Array<DevSession>>
	createSession(): Promise<DevSession>
	getLatestOrCreate(): Promise<DevSession>
}

Replaces the Effect API’s DevSessions for use outside defineDevCli. rootDir is your project root — same convention as DevSessions.layerAt(rootDir), so this facade and the Effect one agree on the on-disk layout (<rootDir>/.data/sessions) given the same root. services is the same platform layer defineDevCli takes as platform.services — e.g. NodeServices.layer or BunServices.layer. Each call builds its own layer from it — cheap, no I/O happens until a method runs — and runs each method with Effect.runPromise against it.

SessionState.slot

namespace SessionState {
	function slot<T extends Schema.Codec<unknown, unknown, never>>(
		schema: T,
		services: Layer.Layer<DevServices>,
	): {
		read: (session: DevSession) => Promise<T['Type'] | null>
		write: (session: DevSession, data: T['Type']) => Promise<void>
	}
}

Same behavior as the Effect version: one shared sess.json per session, shallow-merged writes, read resolves null on both a missing file and a decode failure, and write is not atomic — a corrupt file makes it reject with a SessionStateError instead of merging into it. services is the same platform layer as defineDevCli’s platform.services. Narrower schema constraint: Schema.Codec<unknown, unknown, never> instead of Schema.Top, because decoding runs with only DevServices | Scope available — a schema that needs extra decoding services doesn’t fit here.

devsess/async re-exports SessionStateError (the same class as the Effect version) so you can identify it without importing from devsess directly, e.g. error instanceof SessionStateError or error._tag === 'SessionStateError'.

cli, Schema

Re-exports of effect/cli and effect/Schema — so defineDevCli’s options and SessionState.slot’s schema can be declared without adding effect as a direct import. The core devsess entry point re-exports neither — Effect users build a Command straight from effect/cli and import Schema from effect directly.

Was this page helpful?