legacy-libs/walkdir/walkdir.d.ts

   1 import { EventEmitter } from "events";
   2 import { Stats } from "fs";
   3
   4
   5 /*~ This declaration specifies that the function
   6  *~ is the exported object from the file
   7  */
   8 export = walkdir;
   9
  10
  11 declare function walkdir(
  12     path:string,
  13     options:{sync:true,return_object:true}&walkdir.WalkOptions,
  14     eventListener?:walkdir.WalkEventListener)
  15     :{[path:string]:Stats};
  16
  17 declare function walkdir(
  18     path:string,
  19     options:{sync:true,return_object?:false}&walkdir.WalkOptions,
  20     eventListener?:walkdir.WalkEventListener)
  21     :string[];
  22
  23 declare function walkdir(
  24     path:string,
  25     options?:({sync?:false}&walkdir.WalkOptions)|walkdir.WalkEventListener,
  26     eventListener?:walkdir.WalkEventListener)
  27     :walkdir.WalkEmitter;
  28
  29 declare function walkdir(
  30     path:string,
  31     options?:walkdir.WalkOptions|walkdir.WalkEventListener,
  32     eventListener?:walkdir.WalkEventListener)
  33     :walkdir.WalkEmitter|string[]|{[path:string]:Stats};
  34
  35 /*~ If you want to expose types from your module as well, you can
  36  *~ place them in this block. Often you will want to describe the
  37  *~ shape of the return type of the function; that type should
  38  *~ be declared in here, as this example shows.
  39  */
  40 declare namespace walkdir {
  41     export type WalkOptions = {
  42         /**
  43          * follow symlinks. default FALSE
  44          */
  45         "follow_symlinks"?: boolean,
  46         /**
  47          * only go one level deep. convenience param.
  48          */
  49         "no_recurse"?: boolean,
  50         /**
  51          * only travel to max depth. emits an error if hit.
  52          */
  53         "max_depth"?: number,
  54         /**
  55          * on filesystems where inodes are not unique like windows (or perhaps hardlinks) some files may not be emitted due to inode collision.
  56          * turning off this behavior may be required but at the same time may lead to hitting max_depth via link loop.
  57          */
  58         "track_inodes"?: boolean;
  59         /**
  60          * make this syncronous. the same as calling walkdir.sync
  61          */
  62         "sync"?:boolean,
  63         /**
  64          * return an object of {path:stat} instead of just the resolved path names
  65          */
  66         "return_object"?: boolean, // if true the sync return will be in {path:stat} format instead of [path,path,...]
  67         /**
  68          * dont build up an internal list or object of all of the paths. this can be an important optimization for listing HUGE trees.
  69          */
  70         "no_return"?: boolean,
  71         /**
  72          * filter. filter an array of paths from readdir
  73          */
  74         "filter"?:(directory:string,files:string[])=>string[]|Promise<string[]>,
  75         /**
  76          * provide an alternate implementation of fs like graceful-fs
  77          */
  78         "fs"?:any,
  79         /***
  80          * default True. if false this will use stat insteqad of lstat and not find links at all.
  81          */
  82         "find_links"?:boolean,
  83     }
  84
  85   export type WalkEmitter = EventEmitter&{
  86         /**
  87          * cancel a walk in progress
  88          */
  89         end():void
  90         /**
  91          * pause the walk
  92          */
  93         pause():void;
  94         /**
  95          * resume the walk
  96          */
  97         resume():void;
  98         /**
  99          * pass paths to ignore for the remainder of the walk. directories ignored will not have events emitted for any of their children.
 100          * @param paths string|string[]
 101          */
 102         ignore(paths:string|string[]):void;
 103
 104         /**
 105          * emitted if there is an error from the file system reading the initial or target directory
 106          */
 107         on(event:"error",listener:(error:Error)=>void):WalkEmitter;
 108         /**
 109          *  emitted when there is an error from the filesystem reading as nested path.
 110          */
 111         on(event:"fail",listener:(path:string,error:Error)=>void):WalkEmitter;
 112         /**
 113          * the stat of the target directory. not emitted through any other event.
 114          */
 115         on(event:"targetdirectory",listener:(path:string,stat:Stats,depth:number)=>void):WalkEmitter;
 116         /**
 117          * helpful event that lets you know if a directory is empty
 118          */
 119         on(event:"empty",listener:(path:string,stat:Stats,depth:number)=>void):WalkEmitter;
 120         /**
 121          * found a path. this is the expected use case. every path for everything inside target directory is emitted here.
 122          */
 123         on(event:"path",listener:(this:WalkEmitter,path:string,stat:Stats,depth:number)=>void):WalkEmitter;
 124         /**
 125          * found a directory
 126          */
 127         on(event:"directory",listener:(path:string,stat:Stats,depth:number)=>void):WalkEmitter;
 128         /**
 129          * found a file
 130          */
 131         on(event:"file",listener:(path:string,stat:Stats,depth:number)=>void):WalkEmitter;
 132         /**
 133          * found a symlink
 134          */
 135         on(event:"link",listener:(path:string,stat:Stats,depth:number)=>void):WalkEmitter;
 136         /**
 137          * found a socket
 138          */
 139         on(event:"socket",listener:(path:string,stat:Stats,depth:number)=>void):WalkEmitter;
 140         /**
 141          * found a fifo
 142          */
 143         on(event:"fifo",listener:(path:string,stat:Stats,depth:number)=>void):WalkEmitter;
 144         /**
 145          * found a block device / disk
 146          */
 147         on(event:"blockdevice",listener:(path:string,stat:Stats,depth:number)=>void):WalkEmitter;
 148         /**
 149          * found a character device / tty / terminal
 150          */
 151         on(event:"characterdevice",listener:(path:string,stat:Stats,depth:number)=>void):WalkEmitter;
 152     };
 153
 154     export type WalkEventListener = (this:WalkEmitter,path:string,stat:Stats,ignore:(path:string|string[])=>void)=>void
 155
 156     // same a walkdir
 157     export function find(
 158         path:string,
 159         options:{sync:true,return_object:true}&walkdir.WalkOptions,
 160         eventListener?:walkdir.WalkEventListener)
 161         :{[path:string]:Stats};
 162
 163     export function find(
 164         path:string,
 165         options:{sync:true,return_object?:false}&walkdir.WalkOptions,
 166         eventListener?:walkdir.WalkEventListener)
 167         :string[];
 168
 169     export function find(
 170         path:string,
 171         options?:({sync?:false}&walkdir.WalkOptions)|walkdir.WalkEventListener,
 172         eventListener?:walkdir.WalkEventListener)
 173         :walkdir.WalkEmitter;
 174
 175
 176     //always sync:true but otherwise the same as walkdir
 177     export function sync(path:string,options:walkdir.WalkOptions&{return_object:true},eventListener?:walkdir.WalkEventListener):{[path:string]:Stats};
 178     export function sync(path:string,options?:walkdir.WalkOptions&{return_object?:false},eventListener?:walkdir.WalkEventListener):string[];
 179     export function sync(path:string,options?:walkdir.WalkOptions&{return_object?:boolean},eventListener?:walkdir.WalkEventListener):string[]|{[path:string]:Stats};
 180
 181     // always sync:false. a promise of whatever is the same as walkdir.
 182     export function async(path:string,options:walkdir.WalkOptions&{return_object:true},eventListener?:walkdir.WalkEventListener):Promise<{[path:string]:Stats}>;
 183     export function async(path:string,options?:walkdir.WalkOptions&{return_object?:false},eventListener?:walkdir.WalkEventListener):Promise<string[]>;
 184     export function async(path:string,options?:walkdir.WalkOptions&{return_object?:boolean},eventListener?:walkdir.WalkEventListener):Promise<string[]>|Promise<{[path:string]:Stats}>;
 185 }