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

scandal

v3.2.0

Published

Directory Search and Scan Utilities

Downloads

402

Readme

scandal - Scandalous directory scanning and searching

Build Status Deps

scandal provides two utilities:

  • Scanning a directory for paths matching a set of glob inclusions or exclusions. For example, you want to find a list of paths to search that match a certain pattern, but are not ignored by the .gitignore.

  • Searching a list of paths for a regex. For example, you have a list of paths, you want to find all instances of /text/gi.

Unsurprisingly, these two things can be combined to scan and search a directory.

Goals

It is written to be simple, flexible and efficient. Scandal does the minimum.

We want to provide modules to combine in any way you'd like. Want to scan in one process and search in another? You can do that.

To be clear, scandal is not a CLI. It can be used from the terminal, but in practice the CLI only used for benchmarking.

Objects

scandal provides two main modules: PathScanner and PathSearcher.

PathScanner

Usage is simple:

{PathScanner} = require 'scandal'
scanner = new PathScanner('/Users/me/myDopeProject', options)

scanner.on 'path-found', (path) ->
  console.log(path)

scanner.on 'finished-scanning', ->
  console.log('All done!')

scanner.scan()

PathScanner keeps no state. You must consume paths via the path-found event.

options

  • excludeVcsIgnores - bool; default false; true to exclude paths defined in a .gitignore. Uses git-utils to check ignored files.
  • inclusions - list of patterns to include. Uses minimatch with a couple additions: ['dirname'] and ['dirname/'] will match all paths in direcotry dirname
  • exclusions - list of patterns to exclude. Same matcher as inclusions.
  • includeHidden - bool; default false; true includes hidden files.

PathSearcher

{PathSearcher} = require 'scandal'
searcher = new PathSearcher()

# You can subscribe to a `results-found` event
searcher.on 'results-found', (result) ->
  # result will contain all the matches for a single path
  console.log("Single Path's Results", result)

# Search a list of paths
searcher.searchPaths /text/gi, ['/Some/path', ...], (results) ->
  console.log('Done Searching', results)

# Search a single path
searcher.searchPath /text/gi, '/Some/path', (result) ->
  console.log('Done Searching', result)

Results from line 10 (1 based) are in the following format.

{
  "path": "/Some/path",
  "matches": {
    "matchText": "Text",
    "lineText": "Text in this file!",
    "lineTextOffset": 0,
    "range": [[9, 0], [9, 4]]
  }
}

Like the PathScanner the searcher keeps no state. You need to consume results via the done callbacks or event.

File reading is fast and memory efficient. It reads in 10k chunks and writes over each previous chunk. Small object creation is kept to a minimum during the read to make light use of the GC.

PathFilter

A third object, PathFilter is available, but intended for use by the PathScanner.

Using the scanner and searcher together

If you dont want to think about combining the PathScanner and PathSearcher in your own way, a search function is provided.

{search, PathScanner, PathSearcher} = require 'scandal'

path = '/path/to/search'
scanner = new PathScanner(path, excludeVcsIgnores: true)
searcher = new PathSearcher()

searcher.on 'results-found' (result) ->
  # do something rad with the result!

name = "Search #{path}"
console.time name
console.log name
search /text/ig, scanner, searcher, ->
  console.timeEnd name