rrdir 14.2.2 → 14.2.4

package/README.md

@@ -8,13 +8,14 @@ This module is able to read any path including ones that contain invalid UTF-8 s
 | Benchmark | rrdir | fdir |
 |---|---|---|
 | async | 56ms | 56ms |
-| sync | 155ms | 174ms |
-| async + exclude | 43ms | — |
-| sync + exclude | 118ms | — |
-| async iterator | 77ms | — |
-| async iterator + exclude | 68ms | — |
-
-Results for 122K entries (111K files, 11K dirs), Node.js on macOS. rrdir returns richer entries (path + directory + symlink) while fdir returns only paths. Run with `make bench`.
+| sync | 150ms | 173ms |
+| async + glob | 64ms | 62ms |
+| sync + glob | 171ms | 194ms |
+| async + exclude | 49ms | 36ms |
+| sync + exclude | 118ms | 112ms |
+| async iterator | 78ms | — |
+
+Results for 122K entries (111K files, 11K dirs), Node.js on macOS. rrdir returns richer entries (path + directory + symlink) while fdir returns only paths. fdir uses [picomatch](https://github.com/micromatch/picomatch) for glob matching, rrdir has a built-in glob matcher. Run with `make bench`.
 
 ## Usage
 ```console

package/dist/index.d.ts

@@ -1,16 +1,20 @@
 import { Stats } from "node:fs";
 
 //#region index.d.ts
+/** The internal encoding used for path operations. */
 type Encoding = "utf8" | "buffer";
+/** A directory path, either as a string or a Buffer for raw byte paths. */
 type Dir = string | Buffer;
+/** Options for `rrdir`, `rrdirAsync`, and `rrdirSync`. */
 type RRDirOpts = {
-  strict?: boolean;
-  stats?: boolean;
-  followSymlinks?: boolean;
-  include?: Array<string>;
-  exclude?: Array<string>;
+  /** Whether to throw immediately when reading an entry fails. Default: `false`. */strict?: boolean; /** Whether to include `entry.stats`. Will reduce performance. Default: `false`. */
+  stats?: boolean; /** Whether to follow symlinks for both recursion and `stat` calls. Default: `false`. */
+  followSymlinks?: boolean; /** Path globs to include, e.g. `["**.map"]`. Default: `undefined`. */
+  include?: Array<string>; /** Path globs to exclude, e.g. `["**.js"]`. Default: `undefined`. */
+  exclude?: Array<string>; /** Whether `include` and `exclude` match case-insensitively. Default: `false`. */
   insensitive?: boolean;
 };
+/** A directory entry returned by `rrdir`, `rrdirAsync`, and `rrdirSync`. */
 type Entry<T = Dir> = {
   /** The path to the entry, will be relative if `dir` is given relative. If `dir` is a `Uint8Array`, this will be too. Always present. */path: T; /** Boolean indicating whether the entry is a directory. `undefined` on error. */
   directory?: boolean; /** Boolean indicating whether the entry is a symbolic link. `undefined` on error. */
@@ -18,8 +22,11 @@ type Entry<T = Dir> = {
   stats?: Stats; /** Any error encountered while reading this entry. `undefined` on success. */
   err?: Error;
 };
+/** Recursively read a directory via async iterator. Memory usage is `O(1)`. */
 declare function rrdir<T extends Dir>(dir: T, opts?: RRDirOpts): AsyncGenerator<Entry<T>>;
+/** Recursively read a directory, returning all entries as an array. Memory usage is `O(n)`. */
 declare function rrdirAsync<T extends Dir>(dir: T, opts?: RRDirOpts): Promise<Array<Entry<T>>>;
+/** Synchronously recursively read a directory, returning all entries as an array. Memory usage is `O(n)`. */
 declare function rrdirSync<T extends Dir>(dir: T, opts?: RRDirOpts): Array<Entry<T>>;
 //#endregion
 export { Dir, Encoding, Entry, RRDirOpts, rrdir, rrdirAsync, rrdirSync };

package/dist/index.js

@@ -1 +1 @@
-import{lstat as e,readdir as t,stat as n}from"node:fs/promises";import{lstatSync as r,readdirSync as i,statSync as a}from"node:fs";import{isAbsolute as o,resolve as s,sep as c}from"node:path";const l=new TextEncoder,u=l.encode.bind(l),d=new TextDecoder,f=d.decode.bind(d),p=u(c);function m({name:e},t,n){if(n===`buffer`){if(t===`.`)return e;let n=t,r=e,i=new Uint8Array(n.length+p.length+r.length);return i.set(n,0),i.set(p,n.length),i.set(r,n.length+p.length),i}else return t===`.`?e:String(t)+c+String(e)}function h(e,t,n,r,i){let a={path:e,directory:r?r.isDirectory():t,symlink:r?r.isSymbolicLink():n};return i&&(a.stats=r),a}function g(e,t){e=e.replace(/\\/g,`/`);let n=e.endsWith(`/**`),r=e.replace(/[.+?^${}()|[\]\\]/g,`\\$&`).replace(/\*\*/g,`__DOUBLESTAR__`).replace(/\*/g,`[^/]*`).replace(/__DOUBLESTAR__/g,`.*`);return n?(r=r.slice(0,-3),r=`^${r}(?:/.*)?$`):r=`^${r}$`,new RegExp(r,t?`i`:``)}function _(e,t){if(!e?.length)return null;let n=e.map(e=>g(e,t)),r=s(`.`)+c;return e=>{let t=o(e)?e:r+e,i=c===`\\`?t.replace(/\\/g,`/`):t;return n.some(e=>e.test(i))}}function v(e,t){typeof e==`string`&&/[/\\]$/.test(e)&&(e=e.substring(0,e.length-1));let n=e instanceof Uint8Array?`buffer`:`utf8`,r=t.insensitive||!1,i=_(t.include||[],r),a=_(t.exclude||[],r);return{dir:e,internalOpts:{includeMatcher:i,excludeMatcher:a,hasMatcher:!!(a||i),encoding:n,followSymlinks:!!t.followSymlinks,needStats:!!t.stats,strict:!!t.strict,readdirOpts:{encoding:n,withFileTypes:!0}}}}function y(e,t){return t===`buffer`?f(e):e}async function*b(r,i={}){let a=v(r,i),{includeMatcher:o,excludeMatcher:s,hasMatcher:c,encoding:l,followSymlinks:u,needStats:d,strict:f,readdirOpts:p}=a.internalOpts;r=a.dir;let g=[r];for(;g.length>0;){let r=await Promise.all(g.map(e=>t(e,p).then(t=>({dir:e,dirents:t,err:void 0}),t=>({dir:e,dirents:void 0,err:t})))),i=[];for(let{dir:t,dirents:a,err:p}of r){if(p){if(f)throw p;yield{path:t,err:p};continue}for(let r of a){let a=m(r,t,l),p=!0;if(c){let e=y(a,l);if(s?.(e))continue;p=!o||o(e)}let g=r.isDirectory(),_=r.isSymbolicLink(),v=u&&_,b;if(p){if(d||v)try{b=await(u?n:e)(a)}catch(e){if(f)throw e;yield{path:a,err:e}}yield h(a,g,_,b,d)}let x=g;if(v){if(!b)try{b=await n(a)}catch{}x=!!b?.isDirectory()}x&&i.push(a)}}g=i}}async function x(e,t={}){let n=v(e,t),r=[];return await S(n.dir,n.internalOpts,r),r}async function S(r,i,a){let{includeMatcher:o,excludeMatcher:s,hasMatcher:c,encoding:l,followSymlinks:u,needStats:d,strict:f,readdirOpts:p}=i,g=[];try{g=await t(r,p)}catch(e){if(f)throw e;a.push({path:r,err:e})}if(!g.length)return;let _=[];for(let t of g){let i=m(t,r,l),p=!0;if(c){let e=y(i,l);if(s?.(e))continue;p=!o||o(e)}let g=t.isDirectory(),v=t.isSymbolicLink(),b=u&&v,x;if(p){if(d||b)try{x=await(u?n:e)(i)}catch(e){if(f)throw e;a.push({path:i,err:e})}a.push(h(i,g,v,x,d))}let S=g;if(b){if(!x)try{x=await n(i)}catch{}S=!!x?.isDirectory()}S&&_.push(i)}_.length&&await Promise.all(_.map(e=>S(e,i,a)))}function C(e,t={}){let n=v(e,t),r=[];return w(n.dir,n.internalOpts,r),r}function w(e,t,n){let{includeMatcher:o,excludeMatcher:s,hasMatcher:c,encoding:l,followSymlinks:u,needStats:d,strict:f,readdirOpts:p}=t,g=[];try{g=i(e,p)}catch(t){if(f)throw t;n.push({path:e,err:t})}if(g.length)for(let i of g){let p=m(i,e,l),g=!0;if(c){let e=y(p,l);if(s?.(e))continue;g=!o||o(e)}let _=i.isDirectory(),v=i.isSymbolicLink(),b=u&&v,x;if(g){if(d||b)try{x=(u?a:r)(p)}catch(e){if(f)throw e;n.push({path:p,err:e})}n.push(h(p,_,v,x,d))}let S=_;if(b){if(!x)try{x=a(p)}catch{}S=!!x?.isDirectory()}S&&w(p,t,n)}}export{b as rrdir,x as rrdirAsync,C as rrdirSync};
+import{lstat as e,readdir as t,stat as n}from"node:fs/promises";import{lstatSync as r,readdirSync as i,statSync as a}from"node:fs";import{isAbsolute as o,resolve as s,sep as c}from"node:path";const l=new TextEncoder,u=l.encode.bind(l),d=new TextDecoder,f=d.decode.bind(d),p=u(c);function m({name:e},t,n){if(n===`buffer`){if(t===`.`)return e;let n=t,r=e,i=new Uint8Array(n.length+p.length+r.length);return i.set(n,0),i.set(p,n.length),i.set(r,n.length+p.length),i}else return t===`.`?e:t+c+e}function h(e,t,n,r,i){let a=r?r.isDirectory():t,o=r?r.isSymbolicLink():n;return i?{path:e,directory:a,symlink:o,stats:r}:{path:e,directory:a,symlink:o}}function g(e,t){e=e.replace(/\\/g,`/`);let n=e.endsWith(`/**`),r=e.replace(/[.+?^${}()|[\]\\]/g,`\\$&`).replace(/\*\*/g,`__DOUBLESTAR__`).replace(/\*/g,`[^/]*`).replace(/__DOUBLESTAR__/g,`.*`);return n?(r=r.slice(0,-3),r=`^${r}(?:/.*)?$`):r=`^${r}$`,new RegExp(r,t?`i`:``)}function _(e,t){if(!e?.length)return null;let n=e.map(e=>g(e,t)),r=s(`.`)+c;return e=>{let t=o(e)?e:r+e,i=c===`\\`?t.replace(/\\/g,`/`):t;return n.some(e=>e.test(i))}}function v(e,t){typeof e==`string`&&/[/\\]$/.test(e)&&(e=e.substring(0,e.length-1));let n=e instanceof Uint8Array?`buffer`:`utf8`,r=t.insensitive||!1,i=_(t.include||[],r),a=_(t.exclude||[],r);return{dir:e,internalOpts:{includeMatcher:i,excludeMatcher:a,hasMatcher:!!(a||i),encoding:n,followSymlinks:!!t.followSymlinks,needStats:!!t.stats,strict:!!t.strict,readdirOpts:{encoding:n,withFileTypes:!0}}}}function y(e,t){return t===`buffer`?f(e):e}async function*b(r,i={}){let a=v(r,i),{includeMatcher:o,excludeMatcher:s,hasMatcher:c,encoding:l,followSymlinks:u,needStats:d,strict:f,readdirOpts:p}=a.internalOpts;r=a.dir;let g=[r];for(;g.length>0;){let r=await Promise.all(g.map(e=>t(e,p).then(t=>({dir:e,dirents:t,err:void 0}),t=>({dir:e,dirents:void 0,err:t})))),i=[];for(let{dir:t,dirents:a,err:p}of r){if(p){if(f)throw p;yield{path:t,err:p};continue}for(let r of a){let a=m(r,t,l),p=!0;if(c){let e=y(a,l);if(s!==null&&s(e))continue;p=o===null||o(e)}let g=r.isDirectory(),_=r.isSymbolicLink(),v=u&&_,b;if(p){if(d||v)try{b=await(u?n:e)(a)}catch(e){if(f)throw e;yield{path:a,err:e}}yield h(a,g,_,b,d)}let x=g;if(v){if(!b)try{b=await n(a)}catch{}x=!!b?.isDirectory()}x&&i.push(a)}}g=i}}async function x(e,t={}){let n=v(e,t),r=[];return await S(n.dir,n.internalOpts,r),r}async function S(r,i,a){let{includeMatcher:o,excludeMatcher:s,hasMatcher:c,encoding:l,followSymlinks:u,needStats:d,strict:f,readdirOpts:p}=i,g=[];try{g=await t(r,p)}catch(e){if(f)throw e;a.push({path:r,err:e})}if(!g.length)return;let _=[];for(let t of g){let i=m(t,r,l),p=!0;if(c){let e=y(i,l);if(s!==null&&s(e))continue;p=o===null||o(e)}let g=t.isDirectory(),v=t.isSymbolicLink(),b=u&&v,x;if(p){if(d||b)try{x=await(u?n:e)(i)}catch(e){if(f)throw e;a.push({path:i,err:e})}a.push(h(i,g,v,x,d))}let S=g;if(b){if(!x)try{x=await n(i)}catch{}S=!!x?.isDirectory()}S&&_.push(i)}_.length&&await Promise.all(_.map(e=>S(e,i,a)))}function C(e,t={}){let n=v(e,t),r=[];return w(n.dir,n.internalOpts,r),r}function w(e,t,n){let{includeMatcher:o,excludeMatcher:s,hasMatcher:c,encoding:l,followSymlinks:u,needStats:d,strict:f,readdirOpts:p}=t,g=[e];for(;g.length>0;){let e=g.pop(),t=[];try{t=i(e,p)}catch(t){if(f)throw t;n.push({path:e,err:t});continue}if(t.length)for(let i of t){let t=m(i,e,l),p=!0;if(c){let e=y(t,l);if(s!==null&&s(e))continue;p=o===null||o(e)}let _=i.isDirectory(),v=i.isSymbolicLink(),b=u&&v,x;if(p){if(d||b)try{x=(u?a:r)(t)}catch(e){if(f)throw e;n.push({path:t,err:e})}n.push(h(t,_,v,x,d))}let S=_;if(b){if(!x)try{x=a(t)}catch{}S=!!x?.isDirectory()}S&&g.push(t)}}}export{b as rrdir,x as rrdirAsync,C as rrdirSync};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rrdir",
-  "version": "14.2.2",
+  "version": "14.2.4",
   "description": "Recursive directory reader with a delightful API",
   "author": "silverwind <me@silverwind.io>",
   "repository": "silverwind/rrdir",
@@ -17,20 +17,20 @@
     "node": ">=22"
   },
   "devDependencies": {
-    "@types/node": "25.4.0",
-    "@typescript/native-preview": "7.0.0-dev.20260312.1",
+    "@types/node": "25.5.0",
+    "@typescript/native-preview": "7.0.0-dev.20260317.1",
     "eslint": "9.39.4",
-    "eslint-config-silverwind": "124.0.7",
+    "eslint-config-silverwind": "125.0.3",
     "fdir": "6.5.0",
     "jest-extended": "7.0.0",
-    "tsdown": "0.21.2",
-    "tsdown-config-silverwind": "2.0.1",
+    "tsdown": "0.21.4",
+    "tsdown-config-silverwind": "2.0.2",
     "typescript": "5.9.3",
-    "typescript-config-silverwind": "15.0.0",
+    "typescript-config-silverwind": "16.0.0",
     "updates": "17.9.1",
-    "updates-config-silverwind": "1.0.3",
+    "updates-config-silverwind": "1.0.4",
     "versions": "14.2.1",
-    "vitest": "4.0.18",
-    "vitest-config-silverwind": "10.6.3"
+    "vitest": "4.1.0",
+    "vitest-config-silverwind": "10.6.5"
   }
 }