feat(Predicate): updated doc comments for clarity and examples in the Predicate module #5094
+591
−200
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
… Predicate module The key improvements include: - **Enhanced Clarity:** All doc comments have been rewritten to be more intuitive and accessible. Complex logical combinators like `implies` now feature real-world analogies (e.g., the "if-then promise") to make them easier to understand. - **Comprehensive Examples:** Added or improved usage examples for nearly every function. These examples focus on demonstrating both the boolean logic and the powerful type-narrowing capabilities of `Refinement`s. - **Crucial Technical Details:** Added important notes for TypeScript developers, such as the logical equivalence of `implies` to `!p || q` and an explicit warning that it does not produce a `Refinement`, preventing common pitfalls. - **Improved Readability:** Standardized the format, added explanatory notes to examples, and ensured a consistent, helpful tone throughout the module's documentation. This change does not alter any runtime code but makes the module substantially easier to learn, use correctly, and integrate into projects.
|
The code fences were accidently removed, I added them back
gcanti
requested changes
Jun 24, 2025
Comment on lines
+2
to
+15
| * This module provides a collection of functions for working with predicates and refinements. | ||
| * | ||
| * A `Predicate<A>` is a function that takes a value of type `A` and returns a boolean. | ||
| * It is used to check if a value satisfies a certain condition. | ||
| * | ||
| * A `Refinement<A, B>` is a special type of predicate that not only checks a condition | ||
| * but also provides a type guard, allowing TypeScript to narrow the type of the input | ||
| * value from `A` to a more specific type `B` within a conditional block. | ||
| * | ||
| * The module includes: | ||
| * - Basic predicates and refinements for common types (e.g., `isString`, `isNumber`). | ||
| * - Combinators to create new predicates from existing ones (e.g., `and`, `or`, `not`). | ||
| * - Advanced combinators for working with data structures (e.g., `tuple`, `struct`). | ||
| * - Type-level utilities for inspecting predicate and refinement types. |
There was a problem hiding this comment.
This must be copied into the index.ts file. You can run pnpm codegen to do it automatically.
There was a problem hiding this comment.
Sorry, this may be a stupid question, but after I run pnpm docgen, where can I check the typescript issues?
PS C:\Users\Patrick\effect\packages\effect> pnpm docgen
[14:01:44.792] INFO (#12): Reading modules...
[14:01:44.903] INFO (#12): 173 module(s) found
[14:01:44.990] INFO (#12): Parsing modules...
[14:01:59.759] INFO (#12): Checking modules...
[14:01:59.852] INFO (#12): No examples found.
[14:01:59.861] INFO (#12): Creating markdown files...
[14:02:23.687] INFO (#12): Writing markdown files...
[14:02:24.468] INFO (#12): Docs generation succeeded!There was a problem hiding this comment.
after I run pnpm docgen, where can I check the typescript issues?
docs/examples folder, see https://github.com/Effect-TS/effect/actions/runs/15852817946/job/44692764087?pr=5094
| @@ -226,16 +334,20 @@ export const isMap = (input: unknown): input is Map<unknown, unknown> => input i | |||
| export const isString = (input: unknown): input is string => typeof input === "string" | |||
|
|
|||
| /** | |||
| * Tests if a value is a `number`. | |||
| * A refinement that checks if a value is a `number`. Note that this | |||
| * check returns `false` for `NaN`. | |||
There was a problem hiding this comment.
AFAIK this is not true
import { Predicate } from "effect"
console.log(Predicate.isNumber(NaN))
// true
github-project-automation
bot
moved this from Discussion Ongoing
to Waiting on Author
in PR Backlog
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
feat(Predicate): updated doc comments for clarity and examples in the Predicate module
The key improvements include:
Enhanced Clarity: All doc comments have been rewritten to be more intuitive and accessible. Complex logical combinators like
impliesnow feature real-world analogies (e.g., the "if-then promise") to make them easier to understand.Comprehensive Examples: Added or improved usage examples for nearly every function. These examples focus on demonstrating both the boolean logic and the powerful type-narrowing capabilities of
Refinements.Crucial Technical Details: Added important notes for TypeScript developers, such as the logical equivalence of
impliesto!p || qand an explicit warning that it does not produce aRefinement, preventing common pitfalls.Improved Readability: Standardized the format, added explanatory notes to examples, and ensured a consistent, helpful tone throughout the module's documentation.
This change does not alter any runtime code but makes the module substantially easier to learn, use correctly, and integrate into projects.
Type
Description
Enhanced Clarity: All doc comments have been rewritten to be more intuitive and accessible. Complex logical combinators like
impliesnow feature real-world analogies (e.g., the "if-then promise") to make them easier to understand.Comprehensive Examples: Added or improved usage examples for nearly every function. These examples focus on demonstrating both the boolean logic and the powerful type-narrowing capabilities of
Refinements.Crucial Technical Details: Added important notes for TypeScript developers, such as the logical equivalence of
impliesto!p || qand an explicit warning that it does not produce aRefinement, preventing common pitfalls.Improved Readability: Standardized the format, added explanatory notes to examples, and ensured a consistent, helpful tone throughout the module's documentation.
This change does not alter any runtime code but makes the module substantially easier to learn, use correctly, and integrate into projects.
Related