Effect Service Authoring

Overview

This skill covers the three canonical patterns for defining Effect-TS services in TMNL:

Effect.Service<>() — Auto-layered services with effectful construction (RECOMMENDED DEFAULT)
Context.Tag — Strategy Pattern for swappable implementations
Context.Tag + Config — Parameterized services with configuration injection

Master these patterns to build composable, testable, type-safe service architectures.

Canonical Sources

Effect-TS Core

Submodule: ../../submodules/effect/packages/effect/src/
- Context.ts:507-585 — Context.Tag and Context.Reference
- Layer.ts:289-292 — Layer.effect (effectful construction)
- Layer.ts:772-775 — Layer.succeed (synchronous construction)
- Layer.ts:727-735 — Layer.scoped (resource management)
- Layer.ts:583-589 — Layer.mergeAll (composition)

Effect Website Documentation

Submodule: ../../submodules/website/content/src/content/docs/docs/
- requirements-management/services.mdx — Service patterns
- requirements-management/layers.mdx — Layer composition
- requirements-management/default-services.mdx — Default layers

TMNL Battle-tested Implementations

SliderBehavior — src/lib/slider/v1/services/SliderBehavior.ts:15 (Strategy Pattern, 5 variants)
DataManager — src/lib/data-manager/v1/DataManager.ts:73 (Effect.Service with dependencies)
SearchKernel — src/lib/data-manager/v1/kernels/SearchKernel.ts:308 (Effect.Service)
IdGenerator — src/lib/layers/v1/services/IdGenerator.ts:34 (Config + Service)

Patterns

Decision Tree: Which Service Pattern?

Need a service?
│
├─ Multiple swappable implementations (Strategy Pattern)?
│  └─ Use: class extends Context.Tag
│     Example: SliderBehavior (linear, log, decibel, exponential, stepped)
│
├─ Effectful construction or service dependencies?
│  └─ Use: class extends Effect.Service<>()
│     Example: DataManager (depends on SearchKernel)
│
└─ Simple configuration tag?
   └─ Use: class extends Context.Tag
      with Static Default + Custom factories
      Example: IdGeneratorConfig

Pattern 1: Effect.Service<>() — RECOMMENDED DEFAULT

When to use:

Service has dependencies on other services
Construction is effectful (async, fallible, requires resources)
You want auto-generated .Default layer
Default choice for most new services

Signature:

typescript

class ServiceName extends Effect.Service<ServiceName>()(
  "app/namespace/ServiceName",
  {
    effect: Effect.Effect<Interface>,
    dependencies?: Layer.Layer<Deps>[]
  }
) {}

Full Example:

typescript

import { Effect, Context, Layer } from 'effect'

// Define interface
interface DatabaseService {
  readonly query: (sql: string) => Effect.Effect<unknown[]>
  readonly execute: (sql: string) => Effect.Effect<void>
}

// Define service with effectful construction
class Database extends Effect.Service<Database>()(
  "app/Database",
  {
    effect: Effect.gen(function* () {
      // Yield dependencies
      const config = yield* DatabaseConfig

      // Effectful construction
      const pool = yield* Effect.tryPromise(() =>
        createPool(config.connectionString)
      )

      // Define interface methods
      const query = (sql: string) =>
        Effect.tryPromise(() => pool.query(sql))

      const execute = (sql: string) =>
        Effect.tryPromise(() => pool.execute(sql))

      return { query, execute } as const
    }),
    dependencies: [DatabaseConfig.Default]
  }
) {}

// Auto-generated layer available at:
Database.Default

// Usage in other services:
const userService = Effect.gen(function* () {
  const db = yield* Database
  const users = yield* db.query('SELECT * FROM users')
  return users
})

Key Features:

Double ()() syntax: First () parameterizes generic type, second () provides config
dependencies: [...]: Auto-provides required layers (optional but recommended)
as const: Ensures readonly interface, prevents accidental mutations
Auto-generated .Default: Layer is automatically created

TMNL Example (src/lib/data-manager/v1/DataManager.ts:73):

typescript

class DataManager extends Effect.Service<DataManager>()(
  "tmnl/data-manager/DataManager",
  {
    effect: Effect.gen(function* () {
      const kernel = yield* SearchKernel

      const search = (query: string, limit: number) =>
        Effect.gen(function* () {
          const results = yield* kernel.search(query, limit)
          return results
        })

      return { search } as const
    }),
    dependencies: [SearchKernel.Default]
  }
) {}

Pattern 2: Context.Tag — STRATEGY PATTERN

When to use:

Multiple implementations of same interface (Strategy Pattern)
Runtime behavior swapping
Need to export both .Default (Layer) AND .shape (direct access)

Signature:

typescript

class TagName extends Context.Tag("namespace/TagName")<
  TagName,
  InterfaceShape
>() {}

Full Example:

typescript

import { Context, Layer } from 'effect'

// 1. Define interface shape
interface TransformBehavior {
  readonly id: string
  readonly transform: (value: number) => number
  readonly inverse: (value: number) => number
}

// 2. Define tag
class ValueTransform extends Context.Tag("app/ValueTransform")<
  ValueTransform,
  TransformBehavior
>() {}

// 3. Create implementations
const linearImpl: TransformBehavior = {
  id: 'linear',
  transform: (v) => v,
  inverse: (v) => v,
}

const logarithmicImpl: TransformBehavior = {
  id: 'logarithmic',
  transform: (v) => Math.log(v),
  inverse: (v) => Math.exp(v),
}

// 4. Export BOTH .Default AND .shape
export const LinearTransform = {
  Default: Layer.succeed(ValueTransform, linearImpl),
  shape: linearImpl,  // Direct access without Layer
}

export const LogarithmicTransform = {
  Default: Layer.succeed(ValueTransform, logarithmicImpl),
  shape: logarithmicImpl,
}

// 5. Runtime swapping
const withLinear = program.pipe(Effect.provide(LinearTransform.Default))
const withLog = program.pipe(Effect.provide(LogarithmicTransform.Default))

Key Features:

Export .shape: Allows direct access without Effect runtime
Export .Default: Layer for Effect programs
Layer.succeed: Creates layer from synchronous value
Swappable: Change behavior via Effect.provide

TMNL Example (src/lib/slider/v1/services/SliderBehavior.ts):

typescript

// Interface
interface SliderBehaviorShape {
  readonly id: string
  readonly normalize: (value: number, min: number, max: number) => number
  readonly denormalize: (normalized: number, min: number, max: number) => number
  readonly format: (value: number, precision: number, unit: string) => string
}

// Tag
class SliderBehavior extends Context.Tag('tmnl/slider/SliderBehavior')<
  SliderBehavior,
  SliderBehaviorShape
>() {}

// Linear implementation
const linearBehavior: SliderBehaviorShape = {
  id: 'linear',
  normalize(value, min, max) {
    return (value - min) / (max - min)
  },
  denormalize(normalized, min, max) {
    return min + normalized * (max - min)
  },
  format(value, precision, unit) {
    return `${value.toFixed(precision)}${unit}`
  },
}

export const LinearBehavior = {
  Default: Layer.succeed(SliderBehavior, linearBehavior),
  shape: linearBehavior,
}

// 4 more behaviors: Logarithmic, Decibel, Exponential, Stepped
// Each follows same pattern: implementation + { Default, shape }

Pattern 3: Context.Tag + Config — PARAMETERIZED SERVICE

When to use:

Service needs configuration injection
Configuration should be overridable at composition time
Want to separate config from service logic

Critical Rule: Define Config tag BEFORE Service (avoids circular dependencies)

Full Example:

typescript

import { Context, Effect, Layer } from 'effect'

// 1. Config tag FIRST
class ApiConfig extends Context.Tag("app/ApiConfig")<
  ApiConfig,
  { readonly baseUrl: string; readonly timeout: number }
>() {
  static Default = Layer.succeed(this, {
    baseUrl: 'https://api.example.com',
    timeout: 5000
  })

  static Custom = (config: { baseUrl: string; timeout: number }) =>
    Layer.succeed(this, config)
}

// 2. Service depends on config
class ApiClient extends Effect.Service<ApiClient>()(
  "app/ApiClient",
  {
    effect: Effect.gen(function* () {
      const config = yield* ApiConfig  // Dependency on config

      const fetch = (path: string) =>
        Effect.tryPromise(() =>
          window.fetch(`${config.baseUrl}${path}`, {
            signal: AbortSignal.timeout(config.timeout)
          })
        )

      return { fetch } as const
    }),
    dependencies: [ApiConfig.Default]
  }
) {}

// 3. Override config at composition
const productionLayer = ApiClient.Default.pipe(
  Layer.provide(ApiConfig.Custom({
    baseUrl: 'https://prod.example.com',
    timeout: 10000
  }))
)

const testLayer = ApiClient.Default.pipe(
  Layer.provide(ApiConfig.Custom({
    baseUrl: 'http://localhost:3000',
    timeout: 1000
  }))
)

Key Features:

Static .Default: Default configuration
Static .Custom: Factory for custom configuration
Order matters: Config tag MUST be defined before service
Layer.provide: Override dependencies at composition

TMNL Example (src/lib/layers/v1/services/IdGenerator.ts):

typescript

// Config FIRST
class IdGeneratorConfig extends Context.Tag('app/layers/IdGeneratorConfig')<
  IdGeneratorConfig,
  { strategy: 'nanoid' | 'uuid' | 'custom'; customFn?: () => string }
>() {
  static Default = Layer.succeed(this, { strategy: 'nanoid' })
  static Custom = (config: { strategy: 'nanoid' | 'uuid' | 'custom'; customFn?: () => string }) =>
    Layer.succeed(this, config)
}

// Service SECOND
class IdGenerator extends Effect.Service<IdGenerator>()(
  "app/layers/IdGenerator",
  {
    effect: Effect.gen(function* () {
      const config = yield* IdGeneratorConfig

      const generate = () => {
        switch (config.strategy) {
          case 'nanoid': return nanoid()
          case 'uuid': return uuidv4()
          case 'custom': return config.customFn?.() ?? nanoid()
        }
      }

      return { generate } as const
    }),
    dependencies: [IdGeneratorConfig.Default]
  }
) {}

Pattern 4: Layer Composition

Layer.mergeAll — Combine multiple service layers:

typescript

import { Layer } from 'effect'

// Individual service layers
const configLayer = ConfigService.Default
const loggerLayer = LoggerService.Default
const dbLayer = DatabaseService.Default

// Merge into single runtime layer
const AppLayer = Layer.mergeAll(
  configLayer,
  loggerLayer,
  dbLayer
)

// Use with effect-atom
const appRuntime = Atom.runtime(AppLayer)

Layer.provide — Inject dependencies:

typescript

// Service depends on Database
const UserServiceLive = Layer.effect(
  UserService,
  Effect.gen(function* () {
    const db = yield* Database
    return { findUser: (id) => db.query(`SELECT * FROM users WHERE id = ${id}`) }
  })
).pipe(
  Layer.provide(Database.Default)  // Inject dependency
)

Layer chains — Complex dependency graphs:

typescript

// A → B → C (A depends on B, B depends on C)
const CLayer = ConfigService.Default
const BLayer = DatabaseService.Default.pipe(Layer.provide(CLayer))
const ALayer = UserService.Default.pipe(Layer.provide(BLayer))

// All dependencies satisfied
const program = Effect.gen(function* () {
  const users = yield* UserService
  return users
}).pipe(Effect.provide(ALayer))

Pattern 5: Resource Management with Layer.scoped

When to use:

Service acquires resources (connections, file handles, subscriptions)
Resources need cleanup on shutdown
Want automatic resource disposal

Example:

typescript

import { Effect, Layer } from 'effect'

class ConnectionPool extends Context.Tag("app/ConnectionPool")<
  ConnectionPool,
  { query: (sql: string) => Effect.Effect<unknown[]> }
>() {}

const ConnectionPoolLive = Layer.scoped(
  ConnectionPool,
  Effect.acquireRelease(
    // Acquire
    Effect.gen(function* () {
      const pool = yield* Effect.tryPromise(() => createPool())
      yield* Effect.log("Pool created")
      return { query: (sql) => Effect.tryPromise(() => pool.query(sql)) }
    }),
    // Release (called on layer disposal)
    (pool) => Effect.gen(function* () {
      yield* Effect.log("Closing pool")
      yield* Effect.tryPromise(() => pool.close())
    })
  )
)

Examples

Example 1: Simple Service with No Dependencies

typescript

import { Effect } from 'effect'

class RandomService extends Effect.Service<RandomService>()(
  "app/RandomService",
  {
    effect: Effect.gen(function* () {
      const randomInt = (max: number) =>
        Effect.sync(() => Math.floor(Math.random() * max))

      const randomString = (length: number) =>
        Effect.sync(() =>
          Array.from({ length }, () =>
            String.fromCharCode(97 + Math.floor(Math.random() * 26))
          ).join('')
        )

      return { randomInt, randomString } as const
    })
  }
) {}

// Usage
const program = Effect.gen(function* () {
  const random = yield* RandomService
  const n = yield* random.randomInt(100)
  const s = yield* random.randomString(10)
  console.log({ n, s })
})

Example 2: Service with Multiple Dependencies

typescript

import { Effect, Layer } from 'effect'

// Service A
class Logger extends Effect.Service<Logger>()(
  "app/Logger",
  {
    effect: Effect.succeed({
      log: (msg: string) => Effect.sync(() => console.log(msg))
    })
  }
) {}

// Service B
class Config extends Effect.Service<Config>()(
  "app/Config",
  {
    effect: Effect.succeed({
      apiKey: "secret-key",
      baseUrl: "https://api.example.com"
    })
  }
) {}

// Service C depends on A and B
class ApiClient extends Effect.Service<ApiClient>()(
  "app/ApiClient",
  {
    effect: Effect.gen(function* () {
      const logger = yield* Logger
      const config = yield* Config

      const fetch = (path: string) =>
        Effect.gen(function* () {
          yield* logger.log(`Fetching: ${config.baseUrl}${path}`)
          const response = yield* Effect.tryPromise(() =>
            window.fetch(`${config.baseUrl}${path}`)
          )
          return response
        })

      return { fetch } as const
    }),
    dependencies: [Logger.Default, Config.Default]
  }
) {}

// All dependencies auto-satisfied
const program = Effect.gen(function* () {
  const api = yield* ApiClient
  yield* api.fetch('/users')
})

Example 3: Swappable Behaviors (Strategy Pattern)

typescript

import { Context, Effect, Layer } from 'effect'

interface CacheStrategy {
  readonly name: string
  readonly get: <A>(key: string) => Effect.Effect<A | null>
  readonly set: <A>(key: string, value: A) => Effect.Effect<void>
}

class Cache extends Context.Tag("app/Cache")<Cache, CacheStrategy>() {}

// In-memory implementation
const memoryCache: CacheStrategy = {
  name: 'memory',
  get: (key) => Effect.sync(() => memoryStore.get(key) ?? null),
  set: (key, value) => Effect.sync(() => memoryStore.set(key, value)),
}

// Redis implementation
const redisCache: CacheStrategy = {
  name: 'redis',
  get: (key) => Effect.tryPromise(() => redis.get(key)),
  set: (key, value) => Effect.tryPromise(() => redis.set(key, value)),
}

export const MemoryCache = {
  Default: Layer.succeed(Cache, memoryCache),
  shape: memoryCache,
}

export const RedisCache = {
  Default: Layer.succeed(Cache, redisCache),
  shape: redisCache,
}

// Swap implementations
const dev = program.pipe(Effect.provide(MemoryCache.Default))
const prod = program.pipe(Effect.provide(RedisCache.Default))

Anti-Patterns

1. Missing Double `()()` Syntax

typescript

// WRONG
class MyService extends Effect.Service<MyService>("id", { effect: ... }) {}

// CORRECT
class MyService extends Effect.Service<MyService>()("id", { effect: ... }) {}

2. Config AFTER Service (Circular Dependency)

typescript

// WRONG — Circular dependency!
class MyService extends Effect.Service<MyService>()("id", {
  effect: Effect.gen(function* () {
    const config = yield* MyConfig  // MyConfig not defined yet!
  }),
}) {}
class MyConfig extends Context.Tag("config")<...>() {}

// CORRECT — Config first
class MyConfig extends Context.Tag("config")<...>() {}
class MyService extends Effect.Service<MyService>()("id", { ... }) {}

3. Forgetting `as const`

typescript

// WRONG — Mutable interface
return { doThing }

// CORRECT — Readonly interface
return { doThing } as const

4. Not Exporting `.shape` for Strategy Pattern

typescript

// WRONG — Missing direct access
export const LinearBehavior = {
  Default: Layer.succeed(Behavior, linearImpl),
}

// CORRECT — Export both Layer and shape
export const LinearBehavior = {
  Default: Layer.succeed(Behavior, linearImpl),
  shape: linearImpl,  // Direct access without Layer
}

5. Using Effect.Ref in React-consumed Services

typescript

// WRONG — Ref + Atom bridging complexity
const service = Effect.gen(function* () {
  const stateRef = yield* Ref.make(initial)
  // Now need: polling, SubscriptionRef, streams-to-consume-streams
})

// CORRECT — Atom-as-State pattern
const stateAtom = Atom.make(initial)
const service = {
  update: (value) => Effect.sync(() => Atom.set(stateAtom, value))
}

Pattern Comparison

Feature	`Effect.Service<>()`	`Context.Tag` (Strategy)	`Context.Tag + Config`
Auto-generates `.Default`	✅ Yes	❌ Manual `Layer.succeed`	⚠️ Config: manual, Service: auto
Effectful construction	✅ `Effect.gen`	⚠️ Needs `Layer.effect`	✅ Service uses `Effect.gen`
Dependencies array	✅ `dependencies: [...]`	❌ Manual `Layer.provide`	✅ Service has dependencies
Multiple implementations	⚠️ Possible but awkward	✅ Idiomatic	❌ Not applicable
Configuration injection	⚠️ Needs separate Config tag	❌ Not applicable	✅ Built for this
Recommended for	Default choice	Strategy Pattern only	Configurable services

Quick Reference

I need to...	Use this pattern
Create a new service with dependencies	`Effect.Service<>()` with `dependencies: [...]`
Swap implementations at runtime	`Context.Tag` with multiple `{ Default, shape }` exports
Inject configuration into a service	`Context.Tag` for config + `Effect.Service<>()` for service
Manage resources (connections, files)	`Layer.scoped` with `Effect.acquireRelease`
Compose multiple services	`Layer.mergeAll([...layers])`
Override a dependency	`Layer.provide(dependencyLayer)`
Access service in Effect program	`yield* ServiceName`

Related Skills

effect-schema-mastery — Schema validation for service inputs/outputs
effect-atom-integration — Integrating services with React via effect-atom
effect-testing-patterns — Testing services in isolation

Search AI Tools

effect-service-authoring

Install this agent skill to your Project

SKILL.md

Effect Service Authoring

Overview

Canonical Sources

Effect-TS Core

Effect Website Documentation

TMNL Battle-tested Implementations

Patterns

Decision Tree: Which Service Pattern?

Pattern 1: Effect.Service<>() — RECOMMENDED DEFAULT

Pattern 2: Context.Tag — STRATEGY PATTERN

Pattern 3: Context.Tag + Config — PARAMETERIZED SERVICE

Pattern 4: Layer Composition

Pattern 5: Resource Management with Layer.scoped

Examples

Example 1: Simple Service with No Dependencies

Example 2: Service with Multiple Dependencies

Example 3: Swappable Behaviors (Strategy Pattern)

Anti-Patterns

1. Missing Double `()()` Syntax

2. Config AFTER Service (Circular Dependency)

3. Forgetting `as const`

4. Not Exporting `.shape` for Strategy Pattern

5. Using Effect.Ref in React-consumed Services

Pattern Comparison

Quick Reference

Related Skills

Search AI Tools

Install this agent skill to your Project

SKILL.md

Effect Service Authoring

Overview

Canonical Sources

Effect-TS Core

Effect Website Documentation

TMNL Battle-tested Implementations

Patterns

Decision Tree: Which Service Pattern?

Pattern 1: Effect.Service<>() — RECOMMENDED DEFAULT

Pattern 2: Context.Tag — STRATEGY PATTERN

Pattern 3: Context.Tag + Config — PARAMETERIZED SERVICE

Pattern 4: Layer Composition

Pattern 5: Resource Management with Layer.scoped

Examples

Example 1: Simple Service with No Dependencies

Example 2: Service with Multiple Dependencies

Example 3: Swappable Behaviors (Strategy Pattern)

Anti-Patterns

1. Missing Double ()() Syntax

2. Config AFTER Service (Circular Dependency)

3. Forgetting as const

4. Not Exporting .shape for Strategy Pattern

5. Using Effect.Ref in React-consumed Services

Pattern Comparison

Quick Reference

Related Skills

1. Missing Double `()()` Syntax

3. Forgetting `as const`

4. Not Exporting `.shape` for Strategy Pattern