effect

Files (42)

• LICENSE
• README.md
• SKILL.md
• UPSTREAM.md
• build-explicit-services-and-layers.yaml · evals/cases/
• choose-native-runtime-primitives.yaml · evals/cases/
• ground-advice-in-the-project.yaml · evals/cases/
• keep-external-boundaries-truthful.yaml · evals/cases/
• load-guidance-by-concern.yaml · evals/cases/
• model-data-and-failures-with-schema.yaml · evals/cases/
• preserve-types-and-visible-dependencies.yaml · evals/cases/
• test-effect-code-deterministically.yaml · evals/cases/
• CONTRIBUTING.md · evals/fixtures/effect-app/
• package.json · evals/fixtures/effect-app/
• cache.ts · evals/fixtures/effect-app/src/
• consumer.ts · evals/fixtures/effect-app/src/
• event.ts · evals/fixtures/effect-app/src/
• handler.ts · evals/fixtures/effect-app/src/
• provider.ts · evals/fixtures/effect-app/src/
• retry.ts · evals/fixtures/effect-app/src/
• wiring.ts · evals/fixtures/effect-app/src/
• worker-test.ts · evals/fixtures/effect-app/src/
• effect-v4-api.md · evals/fixtures/effect-app/vendor/
• LICENSE · original/
• SKILL.md · original/
• CACHING.md · original/references/
• CONFIG.md · original/references/
• HTTP_CLIENTS.md · original/references/
• SCHEDULING.md · original/references/
• SCHEMA.md · original/references/
• SERVICES_LAYERS.md · original/references/
• STREAMS.md · original/references/
• TESTING.md · original/references/
• CACHING.md · references/
• CONFIG.md · references/
• HTTP_CLIENTS.md · references/
• SCHEDULING.md · references/
• SCHEMA.md · references/
• SERVICES_LAYERS.md · references/
• STREAMS.md · references/
• TESTING.md · references/
• spec.md

SKILL.md (first lines)

# Effect

Ground every recommendation in the target project. Inspect repository instructions, the pinned `effect` version, installed package source, and local conventions before choosing APIs. Prefer project evidence over remembered signatures.

## Choose the Relevant Guidance

Read only the references needed for the task, and combine them when concerns overlap:

- Schema, records, variants, brands, and typed errors: `references/SCHEMA.md`
- Services, layers, modules, scope ownership, and `Effect.fn`: `references/SERVICES_LAYERS.md`
- Configuration and providers: `references/CONFIG.md`
- Schedules, retry, repeat, polling, and pacing: `references/SCHEDULING.md`
- Cache, memoization, in-flight dedupe, and request batching: `references/CACHING.md`
- Streams, queues, PubSub, SubscriptionRef, and long-lived consumers: `references/STREAMS.md`
- HTTP clients, decoding, retries, and rate limits: `references/HTTP_CLIENTS.md`
- Effect-aware tests, TestClock, layers, and synchronization: `references/TESTING.md`

## Model Data and Failures

- Use `Schema.Struct(...)` for application records.
- Use brands for scalar IDs and constrained values.
- Use tagged Schema variants and unions for values that cross boundaries.
- Decode unknown boundary data with `Schema.decodeUnknownEffect(...)`.
- Model expected failures with `Schema.TaggedErrorClass`.
- Never use casts or throwing construction to skip validation at untrusted boundaries.

## Build Explicit Services and Layers

- Keep business rules in named workflows and services.
- Represent dependencies explicitly in the Effect environment.
- Build implementations with layers that own resource lifetime.
- Keep HTTP and transport handlers focused on decoding, context, invocation, and response mapping.
- Wrap public or non-trivial service methods with named `Effect.fn` calls.
- Do not hide required authority, credentials, persistence, or transports behind defaults.

## Choose Runtime Primitives by Meaning

- Use `Config` for runtime configuration and override it with providers in tests.
- Use `Schedule` for retry, repeat, polling, pacing, and backoff.
- Use `Cache` or Effect memoization when their ownership and eviction model fit.
- Use request batching only when the backend exposes a real batch operation.
- Use Queue, PubSub, SubscriptionRef, and Stream according to producer, consumer, broadcast, and backpressure needs.
- Keep long-lived fibers scoped to the layer or resource that owns them.

## Keep Boundaries Truthful

- Wrap HTTP clients, SDKs, CLIs, and external systems in named Effect boundaries.
- Decode persisted and external values before treating them as domain data.
- Preserve distinct transport, status, decode, and domain failures.
- Retry only proven transient failures on idempotent operations with a bounded policy.
- Keep exhausted failures visible unless the boundary has a real fallback.
- Keep provider and network calls outside authoritative database transactions.

## Test Deterministically

- Use Effect-aware tests and explicit test layers.
- Fork time-dependent work before advancing `TestClock`.
- Coordinate concurrent work with Deferred, Queue, Latch, Ref, fibers, or explicit hooks.
- Never add arbitrary real sleeps when deterministic synchronization can express the condition.

## Preserve Types and Dependencies

Solve missing requirements through explicit service and layer composition. Do not use `as any`, non-null assertions, broad cause recovery, `Layer.mergeAll`, `provideMerge`, or default authority merely to make code compile.

## Before Editing

1. Identify every Effect concern in the task.
2. Read the matching references and project-local source.
3. Choose APIs supported by the pinned version.
4. Make the smallest architecture-preserving change.
5. Run the project's typecheck and focused tests.

From getsentry/skillet, MIT.

More from getsentry/skillet