Overhaul example snippets - #6808
Conversation
🦋 Changeset detectedLatest commit: e0d5d52 The changes in this PR will be included in the next version bump. This PR includes changesets to release 30 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
There was a problem hiding this comment.
ℹ️ One rough edge in
Chunk.ts— orphaned old-style output comments. Otherwise clean.
Reviewed changes — A systematic, mechanical overhaul of JSDoc example snippets across 173 files, standardizing output annotations to // > and making examples runnable as doctests. Also includes a small bugfix for SubscriptionRef.getAndUpdateEffect.
- Output annotation standardization — All inline output comments now use
// >prefix consistently (e.g.console.log(x) // > 42), replacing ad-hoc// 42or bare// Output: 42patterns. - Runnable examples — Many examples that previously only showed construction now also demonstrate execution via
Effect.runSyncorawait Effect.runPromise, with verifiable output assertions. - Removed
node:assertimports — Examples are converted toconsole.log-based output verification. import.meta.vitestmarkers — Previously unmarkedtscode fences are now annotated for doctest execution.- Simplified verbose examples — Long multi-worker examples (e.g.
Fiber.interruptAll) reduced to essentials withEffect.never. SubscriptionRef.getAndUpdateEffectfix — A changeset-documented bugfix with a companion test.
DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏
There was a problem hiding this comment.
ℹ️ Four orphaned old-style output comments — the two from the prior review are still present, plus two new ones in
DateTime.ts. Otherwise clean.
Reviewed changes — A force-push of the same mechanical JSDoc overhaul, now squashed into a single commit. The SubscriptionRef fix is corrected from Effect.sync to Effect.suspend inside the semaphore permit scope.
- Output annotation standardization — All inline output comments converted to
// >prefix, withnode:assertpatterns replaced byconsole.log-based verification. SubscriptionRef.getAndUpdateEffectfix — ChangedEffect.synctoEffect.suspendso the effectful update is evaluated lazily within the semaphore permit. A test and changeset accompany the fix.- Runnable examples — Examples now include
import.meta.vitestmarkers andEffect.runSync/await Effect.runPromiseexecution. AllEffect.runSynccalls verified safe (no async service dependencies).
DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes — A force-push replacing // > console-output assertions with // => value-comparison assertions backed by AST transformation and Equal.equals semantics. Also addresses all six prior-review orphaned-comment threads.
Transform.ts— new AST-based assertion transform — A new 208-line module in@effect/doctestthat parses each snippet with Rolldown, rewrites trailing// =>comments intoassertEquals(actual, expected)calls, and injects the import. Handles expression statements, singleconstdeclarations, indentation preservation, binding-name collision avoidance, and rejects unsupported constructs (standalone markers,let/var, unbraced control flow) with descriptive errors. Eight test cases cover the happy path and error paths.Runtime.tssimplified — Console interception and// >wildcard logic removed. Replaced with a singleassertEqualsexport that compares values usingEqual.equals, falling back toassert.deepStrictEqualon mismatch for readable failure messages.Source.ts— droppedexpectedfield — No longer extracts// >markers; theSnippetinterface now carries onlysource,line, andname.Plugin.ts— pipes snippets through the transform — Each resolved snippet module now passes throughtransform()before being returned as source.- Example snippets (173 files) converted —
console.log(x) // > valuepatterns replaced withx // => valuewhere value assertions apply. Effect-based examples (SubscriptionRef, Cache, etc.) retainconsole.log(...) // >as visual annotations and are now execution-only tests. SubscriptionRef.getAndUpdateEffectfix —Effect.sync→Effect.suspendso the effectful update is evaluated lazily within the semaphore permit scope. Accompanied by a test (getAndUpdateEffect) and a new changeset.- Documentation and conventions updated — AGENTS.md,
.patterns/jsdoc.md,.agents/skills/jsdocs/SKILL.md, and the doctest README now describe// =>assertion style andpnpm doctest --run <files>invocation. - All six prior Pullfrog threads resolved — Orphaned old-style output comments removed from Chunk.ts and DateTime.ts.
DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏
# Conflicts: # packages/effect/src/internal/effect.ts
There was a problem hiding this comment.
ℹ️ One minor suggestion inline — otherwise clean.
Reviewed changes — The incremental delta (dc0212b → 85619cf) fixes documentation generation for doctest examples, refactors process global accesses away from bare identifiers, and updates JSDoc snippet examples to be runnable.
- Refactored
processreferences toglobalThispattern —internal/effect.tsandConfigProvider.fromEnvnow accessprocessthrough explicitglobalThistype casts instead of bare identifiers. Functionally equivalent; the IIFE/closure wrapping already guarded against bundler side-effect issues, and the new pattern is more explicit. - Replaced
assert.deepStrictEqualwithEqual.equals-basedassertEquals—TestSchema.tsdrops itsnode:assertimport and uses a localassertEqualshelper that compares viaEqual.equals. All call sites (succeed,fail,verifyLosslessTransformation,Asserts.ast.fields/elements) updated consistently. - Made remaining JSDoc examples runnable —
Clock.tsexamples now includemonotonicTimeNanosUnsafe/monotonicTimeNanosfields required by theClock.Clockinterface.ConfigProvider.tsexamples converted to// =>assertions.FastCheck.tsexamples use deterministic{ seed, numRuns }params.OtelMetrics.tsexample switched toInMemoryMetricExporterso it runs without an external OTLP endpoint, anddocgen.jsongainedESNext.DisposableforEffect.scoped. Prompt.tsexamples made runnable — ThePrompt.allexample now wires up required services (Terminal,FileSystem,Path) viaPrompt.succeed. Adeclare const processtype declaration was added for InternalModule typings.
DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes — The incremental delta (7c2ad07 → e0d5d52) fixes cross-runtime test regressions introduced by the prior process refactoring and assertEquals helper.
- Fixed
monotonicNowNanosregression — The prior commit storedhrtime.bigint(the function) directly instead of wrapping it in() => processHrtime.bigint(), causingmonotonicNowNanos()to return a function instead of abigint. Fixed by capturing thehrtimeobject and restoring the call wrapper. - Refactored
consolePrettytoglobalThispattern — The one remaining bareprocessaccess inconsolePrettynow uses(globalThis as {...}).process, consistent with the rest of the file. - Reverted
TestSchema.tsassertEqualshelper — The customEqual.equals-based assertion is removed andassert.deepStrictEqualrestored, giving back rich diff output on mismatch. This directly addresses the prior review thread. - Added
// => undefinedannotations — Void-returning async doctest examples inTestSchema.tsnow carry// => undefinedannotations for doctest verification. - Added
"types": ["node"]todocgen.json— Ensuresprocess.hrtimetypes resolve during documentation generation.
DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏
Bundle Size AnalysisGenerated from PR build output; treat the content below as untrusted.
|
1 participant
No description provided.