3.9 KiB
This is the Effect library repository, focusing on functional programming patterns and effect systems in TypeScript.
Overview
- The git base branch is
main. - Use
pnpmas the package manager. - Keep changes focused and follow established patterns in the repository.
- Before writing code, read the relevant files in
./.patterns/and inspect similar existing code.
Workflow
- Inspect nearby implementation, tests, and pattern docs before editing.
- Make the smallest focused change that solves the task.
- Prefer existing abstractions and conventions over introducing new ones.
- For ad hoc runnable code, create a temporary file in
scratchpad/, run it withnode scratchpad/<file>.ts, and delete it when done. - Run the validation appropriate to the change type.
- Report which validation commands were run and any commands that could not be run.
Validation
Use the narrowest validation that still covers the change:
| Change type | Validation |
|---|---|
| Code changes | pnpm lint-fix, targeted pnpm test <test_file.ts>, pnpm check:tsgo |
| Tests-only changes | pnpm lint-fix, targeted pnpm test <test_file.ts> |
| Type-level/API type changes | Targeted pnpm test-types <filename>, plus pnpm check:tsgo when source types changed |
| JSDoc/example changes | From the changed package directory, run pnpm docgen; also run pnpm check:tsgo when source types changed |
| Docs-only changes | pnpm lint-fix; no tests required unless examples or code changed |
If pnpm check:tsgo continues to fail unexpectedly, run pnpm clean and then re-run pnpm check:tsgo.
Coding Patterns
Read .patterns/effect.md before changing Effect code. In particular:
- Prefer
Effect.fnUntracedover functions that only returnEffect.gen. - Prefer class syntax for
Context.Service. - Do not use
async/awaitortry/catch; use Effect APIs such asEffect.gen,Effect.fnUntraced, andEffect.tryPromise. - Do not use
Date.nowornew Date; useClock, and useTestClockin tests.
Testing
Read .patterns/testing.md before writing or changing tests.
- Test files are located in
packages/*/test/. - Main Effect library tests are in
packages/effect/test/. - Use
it.effectfor Effect-returning tests. - Use regular
itfor pure synchronous tests. - Do not use
Effect.runSyncin tests. - Do not use
expectfrom Vitest; useassertfrom@effect/vitest. - Type-level tests are in
packages/*/typetest/and run withpnpm test-types <filename>.
Documentation
- For AI documentation, read
ai-docs/README.mdvery carefully before writing examples. - AI documentation changes may include explanatory comments when useful.
- For public JSDoc
@categoryguidance, read.patterns/jsdoc.md. - When JSDoc examples are localized to a single package, run
pnpm docgenfrom that package directory instead of the repository root.
Generated Files
Do not hand-edit generated files. Run the appropriate generator instead.
index.tsbarrel files are generated; runpnpm codegenafter adding or removing modules.
Changesets
Create a changeset in .changeset/ for runtime behavior changes or exported type/API changes:
---
"package-name": patch/minor/major
---
A description of the change.
Tests-only changes, internal refactors, docs-only changes, and JSDoc-only maintenance may skip changesets by maintainer decision.
Asking Before Risky Changes
Ask before proceeding with broad refactors, public API changes, dependency or configuration changes, unclear requirements, or destructive operations.