npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

vscode-position-tracking

v0.1.0

Published

Give it a location in the document, and it gives back the updated location according to document changes.

Downloads

7

Readme

Description

If you have some location in the document of which you want to know what would be its new location according to document changes, this library aims to provide you with that updated location.

Important:

It is an experimental library. It requires further testing regarding its ability to effectively update the wanted location.

Here if you wish, is where you could help and provide situations in which the updated location is not correct. There are debug loggings which can aid you with this. You will see more details about this below.

Library's API

The API of this library consists in a single function that you will use.

This function is called getUpdatedRanges().

How to use

Install the library in your project

  • npm install vscode-position-tracking

Example

// Import it.
const { getUpdatedRanges } = require('vscode-position-tracking')

// To update your document locations according to each
// document change that occurs,
// the getUpdatedRanges() function has to be used 
// within an onDidChangeTextDocument event listener.
vscode.workspace.onDidChangeTextDocument((event) => {

   const updatedRanges = getUpdatedRanges(
      // The locations you want to update,
      // under the form of an array of ranges.
      // It is a required argument.
      someRanges,
      // Array of document changes.
      // It is a required argument.
      event.contentChanges,
      // An object with various options.
      // It is not a required argument,
      // nor any of its options.
      { 
         onDeletion: 'remove',
         onAddition: 'split',
         outputChannel: extensionOutputChannel
      }
   ) 
   // The function returns the updated locations
   // according to document changes,
   // under the form of a new array of ranges.
})

Options object

The options object is not a required argument, nor any of its options.

Available options:

  • onDeletion

    • It tells what happens if a document change that consists in deletion intersects with the range you want to update.

    • Values:

      • 'remove'

        Removes the range. In other words, the returned array will not contain that range or its update.

        onDeletion - remove

      • 'shrink'

        Shrinks the range.

        onDeletion - shrink

    • Default value: 'shrink'

  • onAddition

    • It tells what happens if a document change that consists in addition intersects with the range you want to update.

    • Values:

      • 'remove'

        Removes the range. In other words, the returned array will not contain that range or its update.

        onAddition - remove

      • 'extend'

        Extends the range.

        onDeletion - extend

      • 'split'

        Splits the range.

        onDeletion - split

    • Default value: 'extend'

  • outputChannel

    • It shows logs for debug purposes. For each onDidChangeTextDocument event it will log document change ranges, to update ranges, and updated ranges. The logs are shown on the terminal's output tab in the extension host window / end user window.

      Debug logs example

    • Note 1: The updated ranges are the ones that the library calculated.

    • Note 2: Try and not do logs on the debug console of the development window. From my testing, logging to the debug console creates a lag, the ranges wont be updated in real time.

    • Values:

      • vscode.outputChannel
    • Default value: undefined

Return value

  • The updated ranges from the returned array are in the same order as the ones from the array of ranges that you want to update.

  • In the case of having the onAddition option set to 'split', the new split ranges will be positioned in the returned array in the order they appear in document and from the position of the original range that was split.

    Example: toUpdateRanges = [A, B, C], if B was split into two ranges, the returned array will be [updatedA, D, E, updatedC].

Signature of getUpdatedRanges()

getUpdatedRanges(
   ranges: vscode.Range[],
   changes: vscode.TextDocumentContentChangeEvent[],
   options?: {
      onDeletion?: 'remove'|'shrink',
      onAddition?: 'remove'|'extend'|'split',
      outputChannel?: vscode.OutputChannel
   }
): vscode.Range[]

Feedback

You can use the Issues tab of the library's repository for any questions, suggestions and problems you have.

If the library calculates the wrong updated location:

Passing a vscode.OutputChannel object to the outputChannel option will help in gathering some of the data: document change ranges, to update ranges, and updated ranges.

In this case, the updated ranges from the logs will be the wrong ones. So what else should be provided in the opened issue will be the correct updated ranges.