poof 2.1.1 → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Hiroki Osame <hiroki.osame@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,305 +1,248 @@
-# Poof
-
-> Simple data processing with decorators
-
-[![Build Status](https://travis-ci.org/fatfisz/poof.svg?branch=master)](https://travis-ci.org/fatfisz/poof)
-[![Dependency Status](https://david-dm.org/fatfisz/poof.svg?path=packages/poof)](https://david-dm.org/fatfisz/poof?path=packages/poof)
-[![devDependency Status](https://david-dm.org/fatfisz/poof/dev-status.svg?path=packages/poof)](https://david-dm.org/fatfisz/poof?path=packages/poof#info=devDependencies)
-
-Poof is a tool for creating data processing functions in a declarative way by utilising an upcoming JS feature - decorators.
-
-It makes use of the awesome [validator](https://www.npmjs.com/package/validator) lib to provide assertion functions. Without it Poof probably wouldn't exist.
-
-## Contents
-
-- [Getting started](#getting-started)
-- [Why use Poof?](#why-use-poof)
-- [Example](#example)
-- [Example explained](#example-explained)
-- [The difference between poof and poof-cast](#the-difference-between-poof-and-poof-cast)
-- [API](#api)
-  - [createProcessor(config)](#createprocessorconfig)
-  - [decorators](#decorators)
-    - [decorators.assert.method and decorators.assert.not.method](#decoratorsassertmethod-and-decoratorsassertnotmethod)
-    - [decorators.assert.hasType and decorators.assert.not.hasType](#decoratorsasserthastype-and-decoratorsassertnothastype)
-    - [decorators.assert.isInstanceOf and decorators.assert.not.isInstanceOf](#decoratorsassertisinstanceof-and-decoratorsassertnotisinstanceof)
-    - [decorators.assign](#decoratorsassign)
-    - [decorators.filter(predicate)](#decoratorsfilterpredicate)
-    - [decorators.from(key)](#decoratorsfromkey)
-    - [decorators.ignoreIf(predicate)](#decoratorsignoreifpredicate)
-    - [decorators.ignoreIfUndefined](#decoratorsignoreifundefined)
-    - [decorators.map(mapper)](#decoratorsmapmapper)
-    - [decorators.set(value)](#decoratorssetvalue)
-    - [decorators.transform(transformer)](#decoratorstransformtransformer)
-- [Some questions you might have](#some-questions-you-might-have)
-  - [How can I use decorators in my code?](#how-can-i-use-decorators-in-my-code)
-  - [Why the explicit assignment decorator?](#why-the-explicit-assignment-decorator)
-  - [What about nested structures?](#what-about-nested-structures)
-  - [Why is the field error exception a separate package?](#why-is-the-field-error-exception-a-separate-package)
-- [Be careful with decorators!](#be-careful-with-decorators)
-- [Contributing](#contributing)
-- [License](#license)
-
-## Getting started
-
-Install the `poof` package with this command:
-```shell
-npm install poof field-validation-error --save
-```
-and/or install the `poof-cast` package with this command:
-```shell
-npm install poof-cast field-validation-error -save
-```
-
-`field-validation-error` is a peer dependency of both `poof` packages.
-
-### ES6 Data Structures
+<h2 align="center">
+    <img width="240" src=".github/logo.png">
+    <br><br>
+<a href="https://npm.im/poof"><img src="https://badgen.net/npm/v/poof"></a> <a href="https://npm.im/poof"><img src="https://badgen.net/npm/dm/poof"></a> <a href="https://packagephobia.now.sh/result?p=poof"><img src="https://packagephobia.now.sh/badge?p=poof"></a>
+</h2>
 
-Poof makes use of ES6 data structures, e.g. `WeakMap`, but doesn't include any polyfill.
-Make sure you add a polyfill yourself if you want to support older browsers.
+Ever `rm -rf`'d a large directory and sat there waiting for it to finish? With `poof` you no longer need to wait:
 
-## Why use Poof?
-
-- it lets you describe data processing in a straightforward, declarative way
-- it is especially useful for isomorphic websites - you can declare data validator once and use it both on the client-side and the on the server-side
-- Poof processors are composable - you can pass the result from one processor to another, e.g. when you want to separate validation and transforming
+```sh
+$ poof ./large-file ./large-directory "**/globs"
+```
 
-## Example
+### What's "poof"?
+`poof` is a fast, non-blocking CLI alternative to `rm -rf`, designed for deleting large files and directories without waiting for cleanup to complete.
 
-```js
-import FieldValidationError from 'field-validation-error';
-import { createProcessor, decorators } from 'poof-cast';
+It works by quickly moving files and directories out of the way, then deleting them in the background.
+This means large deletions finish instantly from your perspective, even when there's a lot of data to clean up.
 
-const processIdAndIndex = createProcessor({
-  @decorators.from('postId')
-  @decorators.assert.not.isNull('Missing post id')
-  @decorators.assert.isMongoId('Invalid id')
-  @decorators.transform(ObjectID)
-  @decorators.assign
-  _id() {},
+On a large filesystem (4.7 GB, 190k files), `poof` returns control in ~0.6s while `rm -rf` takes ~28s and `rimraf` ~12s. Full benchmarks below.
 
-  @decorators.assert.not.isNull('Missing index')
-  @decorators.assert.isInt('Invalid index', { min: 0 })
-  @decorators.transform(Number)
-  @decorators.assign
-  index() {},
-});
+### Features
+* ⚡ **Immediate return**: deletion doesn't block your shell
+* 🗂 **Move-then-delete**: fast, atomic rename before cleanup
+* 🛡 **Built-in safeguards**: root protection and directory scoping
+* 🖥 **Cross-platform**: macOS, Linux, and Windows
 
-try {
-  const result = processIdAndIndex(request.body);
+## Install
 
-  // Do something with the result...
-} catch(error) {
-  if (error instanceof FieldValidationError) {
-    // Do something with error messages contained in `error.fields`
-  }
-}
+```sh
+npm install -g poof
 ```
 
-## Example explained
-
-Poof library has two versions: [`poof`, and `poof-cast`](#the-difference-between-poof-and-poof-cast). Both of them have two exports: the [`createProcessor` function](#createprocessorconfig) and the [`decorators` object](#decorators).
+## CLI Usage
 
-```js
-// First import the FieldValidationError and also tools from Poof. The
-// `poof-cast` version additionaly casts data to String for assertions. More
-// about it later.
-import FieldValidationError from 'field-validation-error';
-import { createProcessor, decorators } from 'poof-cast';
+```sh
+# Delete files or directories
+poof node_modules dist
 
-// The `createProcessor` function returns a processor based on the passed
-// config object.
-const processIdAndIndex = createProcessor({
+# Use glob patterns
+poof "*.log" "temp-*"
 
-  // This decorator tells to pick the data from the `postId` property of
-  // a passed object.
-  @decorators.from('postId')
+# Recursive match with ** (searches all subdirectories)
+poof "**/node_modules" "**/dist"
 
-  // This decorator checks if the value is empty; if not, the error for this
-  // field is set to 'Missing post id' and this field's processing stops here.
-  @decorators.assert.not.isNull('Missing post id')
+# Verbose output
+poof --verbose ./large-directory
+```
 
-  // Similarly, check if the value is a MongoDB id.
-  @decorators.assert.isMongoId('Invalid id')
+### Options
 
-  // This decorator takes a function and uses it to transforms the value.
-  // In this case the ObjectID constructor is used.
-  @decorators.transform(ObjectID)
+| Flag          | Alias | Description                                    |
+| ------------- | ----- | ---------------------------------------------- |
+| `--dry`       | `-d`  | Preview files without deleting                 |
+| `--verbose`   | `-v`  | Log each file as it's deleted                  |
+| `--dangerous` |       | Allow deleting paths outside current directory |
+| `--version`   |       | Show version                                   |
+| `--help`      |       | Show help                                      |
 
-  // If you want to have the result of the processing contained in the result
-  // object, you have to do it explicitly with the `assign` decorator.
-  @decorators.assign
+## File matching
 
-  // This defines the output property which will have the processed value.
-  _id() {},
+`poof` accepts explicit paths or [glob patterns](https://en.wikipedia.org/wiki/Glob_%28programming%29) for flexible file matching.
 
+> [!TIP]
+> When using glob patterns, start with `--dry` to preview what will match before deleting.
 
-  // Assert that the value is not empty.
-  @decorators.assert.not.isNull('Missing index')
+### Quick refresher: shell quoting
 
-  // Assert that the value is an integer, with a value of at least 0.
-  @decorators.assert.isInt('Invalid index', { min: 0 })
+How unquoted glob patterns are expanded depends on your shell's settings (`dotglob`, `globstar`, etc.).  
+To get consistent behavior, quote the pattern so `poof` handles the matching itself.
 
-  // Cast to Number
-  @decorators.transform(Number)
+```sh
+# The shell expands the glob before poof runs
+$ poof **/node_modules
 
-  // Pass to the output
-  @decorators.assign
+# Recommended: poof expands the glob
+$ poof "**/node_modules"
+```
 
-  // The result will land in the `index` property.
-  // Note that here we initially get the value from the `index` property, so
-  // the `from` decorator is not needed.
-  index() {},
-});
+### Basic patterns
 
+```sh
+# Explicit paths
+$ poof node_modules
 
-try {
-  // Now the processor can be used with an object.
-  const result = processIdAndIndex(request.body);
+# Multiple paths
+$ poof dist coverage
 
-  // Do something with the result...
-} catch(error) {
-  if (error instanceof FieldValidationError) {
-    // Do something with error messages contained in `error.fields`
-  }
-}
+# Wildcards in current directory
+$ poof "*.log"
+$ poof "temp-*"
 ```
 
-So if `request.body` is:
-```js
-{
-  postId: '507f1f77bcf86cd799439011',
-  index: '12',
-}
-```
-then `result` would be:
-```js
-{
-  _id: ObjectID('507f1f77bcf86cd799439011'),
-  index: 12,
-}
-```
+### Recursive patterns
 
-If instead `request.body` is:
-```js
-{
-  index: '-1',
-}
-```
-then you'd get a `FieldValidationError` with the `fields` property equal to:
-```js
-{
-  _id: 'Missing post id',
-  index: 'Invalid index',
-}
-```
-
-## The difference between poof and poof-cast
+Use `**` to match across nested directories:
 
-While `poof` passes processed data for asserts without change, `poof-cast` casts it to string beforehand. The casting works the same as default JS string casting, with this exception: `null`, `undefined`, and `NaN` become `''` (empty string).
+```sh
+# All node_modules in a monorepo
+$ poof "**/node_modules"
 
-This is quite useful for parsing request bodies which usually consist of strings - missing fields assume the value of `''` when auto-casting is on. Because of this `decorators.assert.isNull` from `poof-cast` can be used to check both for field presence and whether the value is a non-empty string. This of course reduces otherwise necessary boilerplate code.
+# All .log files recursively
+$ poof "**/*.log"
 
-The [validator](https://www.npmjs.com/package/validator) library used to make the casting by itself before v. 5. Now it instead throws when the passed argument is not a string. Those exceptions can be thrown when using `poof` (without casting), so be careful when using that version.
-
-## API
+# Multiple patterns
+$ poof "**/dist" "**/coverage" "**/*.tmp"
+```
 
-Both `poof` and `poof-cast` export:
+### Dotfiles (hidden files)
 
-### createProcessor(config)
+By default, glob wildcards (`*`, `**`) don't match dotfiles (files starting with `.`). This helps avoid accidentally deleting `.git`, `.env`, or other hidden files.
 
-Use this function with a config object to get a simple data processor.
+To target dotfiles, explicitly include the `.` in your pattern:
 
-The processor either returns an output object or throws `FieldValidationError` if there was a validation error.
+```sh
+# Delete all dotfiles in current directory
+$ poof ".*"
 
-### decorators
+# Delete .cache directories (not inside hidden dirs)
+$ poof "**/.cache"
 
-#### decorators.assert.method and decorators.assert.not.method
+# Delete a specific dotfile
+$ poof .env.local
+```
 
-Those contain all validation functions from the validator lib: `contains`, `equals`, `isAfter`, `isAlpha`, `isAlphanumeric`, `isAscii`, `isBase64`, `isBefore`, `isBoolean`, `isByteLength`, `isCreditCard`, `isCurrency`, `isDataURI`, `isDate`, `isDecimal`, `isDivisibleBy`, `isEmail`, `isFloat`, `isFQDN`, `isFullWidth`, `isHalfWidth`, `isHexadecimal`, `isHexColor`, `isIn`, `isInt`, `isIP`, `isISBN`, `isISIN`, `isISO8601`, `isJSON`, `isLength`, `isLowercase`, `isMACAddress`, `isMobilePhone`, `isMongoId`, `isMultibyte`, `isNull`, `isNumeric`, `isSurrogatePair`, `isUppercase`, `isURL`, `isUUID`, `isVariableWidth`, `isWhitelisted`, and `matches`.
+#### Searching inside hidden directories
 
-*The validator methods will be updated if necessary, but the new ones should be auto-detected in most cases.*
+`**/.cache` finds `.cache` directories in regular directories, but does **not** scan inside other hidden directories like `.git`. This is intentional—scanning hidden directories is slow and rarely useful.
 
-The first argument is always a message that can be found in the thrown exception in case the validation failed.
+To search inside hidden directories, start your pattern with `.*`:
 
-That is followed by other arguments, which are passed to the validation function as the second, third, and so on arguments. The first argument passed is the currently processed value.
+```sh
+# Find .cache inside any hidden directory
+$ poof ".*/**/.cache"
+```
 
-So for example for `@decorators.assert.equals('Is different', 'expected')` the arguments passed to the `equals` validator will be the current value and `'expected'`, and if the currently processed value is different from `'expected'`, the error message for this field will be set to `'Is different'`.
+Or use brace expansion to target specific directories:
 
-`decorators.assert.not` works almost the same, only the validation fails if the function returns `true`.
+```sh
+# Search inside .config and src
+$ poof "{.config,src}/**/.cache"
+```
 
-#### decorators.assert.hasType and decorators.assert.not.hasType
+### Negation patterns
 
-An additional assertion function that performs the `typeof` check on the current value and the passed argument.
+Extglob negations like `!(pattern)` match everything *except* the specified pattern:
 
-#### decorators.assert.isInstanceOf and decorators.assert.not.isInstanceOf
+```sh
+# Delete everything except .gitkeep
+$ poof "!(.gitkeep)"
+```
 
-An additional assertion function that performs the `instanceof` check on the current value and the passed argument.
+> [!WARNING]
+> Negations match dotfiles. `!(important.txt)` will match `.env`, `.git`, and other hidden files. Always use `--dry` first.
 
-#### decorators.assign
+## Safety
 
-Used to assign the processed value to the output object. When using, it's best to put this decorator last, because any further processing results won't be saved.
+`poof` includes guards to help prevent common accidents:
 
-#### decorators.filter(predicate)
+- **Root protection**: refuses to delete the filesystem root
+- **Directory scoping**: won't delete paths outside `cwd` unless `--dangerous` is passed
+- **Typo protection**: explicit paths that don't exist are reported as errors, so `poof ndoe_modoules` won't silently succeed
+- **Script-friendly globs**: glob patterns with no matches exit silently, so `poof "*.log"` won't break your scripts
 
-Filters the current value using `predicate`. The current value is assumed to be an array.
+## How it works
 
-#### decorators.from(key)
+Traditional `rm -rf` blocks until every file is unlinked.
+For large directories, this means waiting on thousands of filesystem operations.
 
-The initial value for the processed field is taken from the input object using its key. If you want to use a value of a different field instead, use this decorator.
+`poof` uses a different strategy:
 
-#### decorators.ignoreIf(predicate)
+1. Resolve glob patterns and validate paths
+2. Spawn a detached cleanup process
+3. Rename files to a temp directory (constant-time, atomic)
+4. Stream renamed paths to the cleanup process as renames complete
+5. Exit process to return your shell while cleanup process continues in the background
 
-The predicate is called with the processed value. If the result is `true`, then the processing is stopped for that field and it is omitted from the output object.
+### Cross-device fallback
 
-#### decorators.ignoreIfUndefined
+If the target is on a different filesystem (`EXDEV`), `poof` falls back to renaming in place with a hidden prefix (e.g., `.poof-uuid-large-directory`) and streams it directly to the cleaner.
 
-Sometimes you might want to process some data only if it's present. Use this decorator to avoid validation and transforming in case the processed value is `undefined`. It's equivalent to `decorators.ignoreIf((value) => typeof value === 'undefined')`.
+## Benchmarks
 
-#### decorators.map(mapper)
+Deleting `**/node_modules` directories from a synthetic fixture:
 
-Maps the current value using `mapper`. The current value is assumed to be an array.
+| Tool     | Time    | vs poof    |
+| -------- | ------- | ---------- |
+| `poof`   | 0.59s   | —          |
+| `rimraf` | 12.32s  | 21x slower |
+| `rm -rf` | 27.82s  | 48x slower |
 
-#### decorators.set(value)
+Fixture: 4.7 GB, 190k files
 
-Simply sets the processed value to the one passed in the argument.
+Environment: macOS 15.2, Apple M2 Max, SSD
 
-#### decorators.transform(transformer)
+> [!NOTE]
+> These benchmarks measure how long it takes to return control of your terminal, not actual deletion time. Background deletion continues after `poof` exits. `rm -rf` and `rimraf` measure actual deletion time.
 
-Takes transformer, applies it to the processed value, and sets it as a new processed value. Useful for type casting or otherwise transforming the validated data.
+## JS API
 
-## Some questions you might have
+`poof` can also be used programmatically:
 
-### How can I use decorators in my code?
+```ts
+import poof from 'poof'
 
-You can use Babel 5 with an optional "es7.decorators" transformer, or use Babel 6 with [this legacy plugin](https://github.com/loganfsmyth/babel-plugin-transform-decorators-legacy). There are some differences though, you can read about them [here](https://github.com/loganfsmyth/babel-plugin-transform-decorators-legacy/blob/master/README.md).
+await poof('./large-directory')
+await poof(['**/dist', 'coverage'])
 
-### Why the explicit assignment decorator?
+const { deleted, errors } = await poof('./large-directory', { dry: true })
+```
 
-When I started creating what later became Poof I didn't always want to have all of the fields in the output object, and so I decided for the explicit assignment. Maybe in the future I'll add some options to enable auto-assignment for all fields in the object though.
+### Types
 
-### What about nested structures?
+```ts
+type Options = {
+    cwd?: string
+    dry?: boolean
+    dangerous?: boolean
+}
 
-This was supposed to be a simple lib, and I didn't have a need to support nested structures with it. I might do it someday and I'm open to suggestions/PRs.
+type Failure = {
+    path: string
+    error: Error
+}
 
-### Why is the field error exception a separate package?
+type Result = {
+    deleted: string[]
+    errors: Failure[]
+}
+```
 
-It makes sense to decouple the exception from the `poof` package because another package that handles this exception shouldn't be tied to `poof`. This problem is not contrived, it's an actual problem I had.
+## Alternatives
 
-## Be careful with decorators!
+Some tools provide fast, non-blocking removal by moving files to the system trash:
 
-The decorators feature is still at stage 1, a proposal.
-This means that the [current decorator spec](https://github.com/wycats/javascript-decorators) can change dramatically before it advances to the next stage.
+- [trash](https://formulae.brew.sh/formula/trash) (macOS)
+- [trash-cli](https://github.com/sindresorhus/trash-cli) (cross-platform)
 
-With this said, no changes should affect your use of this library much. You will be mostly using the exterior (decorator application) which now has a final form more or less, while the interior (how the decorating works in Poof) will be kept up-to-date with the spec.
+These are useful for recoverable deletes, but large directories can accumulate in the trash and consume disk space.
 
-While some things may be set in stone, there is still a room for improvement. So if you care about decorators, please can take part in discussions at [wycats/javascript-decorators](https://github.com/wycats/javascript-decorators) and [jeffmo/es-class-fields-and-static-properties](https://github.com/jeffmo/es-class-fields-and-static-properties).
+`poof` permanently deletes files, freeing space immediately.
 
-## Contributing
+## Requirements
 
-In lieu of a formal style guide, take care to maintain the existing coding style.
-Add unit tests for any new or changed functionality. Lint and test your code with `npm test`.
+Node.js >= 20.19.6
 
 ## License
 
-Copyright (c) 2016 Rafał Ruciński. Licensed under the MIT license.
+MIT