8000 feat(useLens): new function by YomoABH · Pull Request #4657 · vueuse/vueuse · GitHub
[go: up one dir, main page]
Skip to content

feat(useLens): new function #4657

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

feat(useLens): new function #4657

wants to merge 9 commits into from

Conversation

YomoABH
Copy link
@YomoABH YomoABH commented Mar 11, 2025 •
edited
Loading

Before submitting the PR, please make sure you do the following

  • Read the Contributing Guidelines.
  • Read the Pull Request Guidelines.
  • Check that there isn't already a PR that solves the problem the same way to avoid creating a duplicate.
  • Provide a description in this PR that addresses what the PR is solving, or reference the issue that it solves (e.g. fixes #123).
  • Ideally, include relevant tests that fail without this PR but pass with it.
⚠️ Slowing down new functions

Warning: Slowing down new functions

As the VueUse audience continues to grow, we have been inundated with an overwhelming number of feature requests and pull requests. As a result, maintaining the project has become increasingly challenging and has stretched our capacity to its limits. As such, in the near future, we may need to slow down our acceptance of new features and prioritize the stability and quality of existing functions. Please note that new features for VueUse may not be accepted at this time. If you have any new ideas, we suggest that you first incorporate them into your own codebase, iterate on them to suit your needs, and assess their generalizability. If you strongly believe that your ideas are beneficial to the community, you may submit a pull request along with your use cases, and we would be happy to review and discuss them. Thank you for your understanding.

Description

This PR introduces useLens, a new composable that provides a reactive, type-safe way to access and modify nested properties in Ref or reactive objects. It solves the problem of verbose and error-prone nested property management by offering a single WritableComputedRef with support for fallbacks and transformations.

  • What it solves: Simplifies reading and updating deeply nested reactive data (e.g., obj.a.b.c) without manual path handling or reactivity boilerplate.
  • Key Features: Reactive access, TypeScript support, optional fallback, transform, onGet, and onSet for customization.
  • Example: 
    const user = reactive({ profile: { name: 'Alice' } })
const name = useLens(user, (u) => u.profile.name)
name.value = 'Bob' // Updates user.profile.name

Changes: Adds useLens implementation, tests, and documentation in packages/core/useLens/.

Additional context

Motivation: Nested property access in Vue often requires repetitive code. useLens offers a reusable, reactive solution tailored for Vue’s ecosystem.

Implementation: Uses Proxy to parse selectors, computed for reactivity, and overloads for type flexibility.

Tests: Covers basic usage, fallbacks, transformations, arrays, and errors using Vitest.

Fit for VueUse: Enhances the Reactivity category with a lightweight, type-safe utility.

Reviewer Focus: Please check type overloads, test coverage, and documentation clarity. Given the "Slowing down new functions" note, I’d value input on its community value.

@dosubot dosubot bot added size:L This PR changes 100-499 lines, ignoring generated files. enhancement New feature or request new function labels Mar 11, 2025
@YomoABH
Copy link
Author
YomoABH commented Mar 11, 2025

Hi maintainers! 👋

I noticed that the Netlify deploy preview is failing (e.g., "netlify/vueuse/deploy-preview" and related checks). After investigating, it seems this issue is not related to my changes in useLens. The error appears to stem from another composable in the version I forked (VueUse v13). Specifically, I believe the problem lies in an existing composable that affects the documentation build process, as my changes are isolated to packages/core/useLens/ and follow VueUse conventions.

Could you please take a look at the Netlify logs to confirm? I’d be happy to assist if there’s anything on my side that needs adjustment, but I suspect this might be a pre-existing issue in the base branch. Thanks for your time and support! 🙏

@ilyaliao ilyaliao changed the title feature(useLens): First release feat(useLens): new function Mar 11, 2025
@ferferga
Copy link
Member

Hello, thank you very much for your PR!

I don't understand the purpose of this function: what's the difference with a writable computed property?

@YomoABH
Copy link
Author
YomoABH commented Mar 13, 2025 •
edited
Loading

Hello, thank you very much for your PR!

I don't understand the purpose of this function: what's the difference with a writable computed property?

Hello! Thanks for your feedback and for reviewing my PR. I’ll clarify how useLens differs from a writable computed property.
useLens is a reusable, type-safe composable for accessing and updating nested properties in reactive objects (Ref or reactive) via a selector (e.g., (s) => s.a.b.c). Unlike a writable computed, it simplifies deep property access, reduces boilerplate, and adds features like type inference, fallbacks, and transformations (transform, onGet, onSet). It also supports arrays and error handling, making it more versatile.
For example:

const source = reactive({ profile: { name: 'Alice' } });
const name = useLens(source, (s) => s.profile.name, { fallback: 'Guest' }); // Concise and flexible

useLens fits VueUse’s goal of providing reusable reactive utilities, addressing nested reactivity challenges with a robust API. I’d be happy to adjust based on your feedback. Looking forward to your thoughts!
Best,
Yomo))

OrbisK
OrbisK reviewed Mar 15, 2025
View reviewed changes
OrbisK
OrbisK requested changes Mar 15, 2025
View reviewed changes
@YomoABH YomoABH requested a review from OrbisK March 15, 2025 20:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@OrbisK OrbisK Awaiting requested review from OrbisK

Requested changes must be addressed to merge this pull request.

Assignees
No one assigned
Labels
enhancement New feature or request new function size:L This PR changes 100-499 lines, ignoring generated files.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@YomoABH @ferferga @OrbisK
0