Effect service standards

Use this page when a contribution adds service contracts, layers, parameter providers, calculator execution or expected error handling.

Service boundaries

Use Effect services and layers for tax behaviour:

  • facts are provided through Context.Service
  • parameter tables are services
  • rules are Layers
  • calculators are Effect programs that require facts and return reports
  • expected domain failures stay in the typed error channel

@taxkit/calculators owns reusable calculator service policy. HTTP handlers and SDK helpers must not hide tax business logic or duplicate calculator lookup, fact decoding, rule execution, graph assembly or expected error shaping.

Effect-native primitives

Use Effect-native primitives when they fit:

  • Data, Schema, Schema.TaggedClass and Schema.TaggedError
  • Array, Chunk, HashSet, HashMap, Record, Option, Result, Exit and Match
  • Context, Layer, Config, ManagedRuntime and Command

Do not create ad hoc tagged objects, mutable Map or Set indexes, manual env parsing or per-request runtime wrappers when an Effect primitive owns the pattern.

Error handling

Keep one-off Effect.mapError, Effect.catchTag, Effect.catch and Effect.catchDefect transformations inline at the callsite. Extract a helper only when it owns reusable policy or removes meaningful duplication.

For the full rule set, read Effect services.

Read this page as Markdown