@zthun/crumbtrail-fs 1.1.0 → 2.0.1

package/dist/file-system/file-system-node.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/file-system/file-system-service.d.mts

@@ -10,6 +10,32 @@ export interface IZFileSystemSearchOptions {
      */
     cwd?: string;
 }
+/**
+ * Represents options for directory walking.
+ */
+export interface IZFileSystemWalkOptions {
+    /**
+     * The starting directory.
+     *
+     * The default is the current working directory
+     *
+     * @see process.cwd for more information.
+     */
+    start?: string;
+    /**
+     * The directory to stop at.
+     *
+     * The default is the root of the file system.
+     */
+    stop?: string;
+    /**
+     * The type of mode that the path must support in order
+     * to be approved.
+     *
+     * The default is undefined and left up to the node api.
+     */
+    mode?: number;
+}
 /**
  * Represents a service to enumerate the file system.
  */
@@ -36,16 +62,48 @@ export interface IZFileSystemService {
      *        A list of path strings that match the given patterns.
      */
     search(pattern: string, options?: IZFileSystemSearchOptions): Promise<IZFileSystemNode[]>;
+    /**
+     * Walks up a directory tree to search for existence of a given path.
+     *
+     * @param search -
+     *        The path to search for.  This is the candidate folder path that
+     *        may or may not exist somewhere from the start directory all the
+     *        way up the directory tree.
+     * @param options -
+     *        The given options for the search.
+     *
+     * @returns
+     *        The fully qualified path to the first path that matches the search
+     *        starting at the options start or the current working directory if not
+     *        specified.  Returns null if no such directory exists.
+     *
+     * @example
+     *
+     * ```ts
+     * import { resolve } from 'path'
+     *
+     * // Find any folder named .vscode from the current working directory all the way
+     * // up the directory tree.  Returns null if no vscode directory can be found.
+     * const service = new ZFileSystemService();
+     * const vscode = service.walk('.vscode');
+     *
+     * // Walk the directory tree from the current script and find the .config folder.
+     * const config = service.walk('.config', { start: __dirname });
+     *
+     * // Walk the directory tree from the current script and stop when we reach
+     * // at most 2 directories up.
+     * const start = __dirname;
+     * const stop = resolve(__dirname, '../..');
+     * const file = service.walk('path/to/file.json', { start, stop });
+     * ```
+     */
+    walk(search: string, options?: IZFileSystemWalkOptions): Promise<string | null>;
 }
-/**
- * A token that you can use with a framework like nest-js to describe
- * a file system service implementation.
- */
-export declare const ZFileSystemToken: unique symbol;
 /**
  * Represents a node implementation of a file system service.
  */
 export declare class ZFileSystemService implements IZFileSystemService {
     info(path: string): Promise<IZFileSystemNode>;
     search(pattern: string | string[], options?: IZFileSystemSearchOptions): Promise<IZFileSystemNode[]>;
+    walk(search: string, options?: IZFileSystemWalkOptions): Promise<string | null>;
 }

package/dist/file-system/file-system-service.spec.d.ts

@@ -0,0 +1 @@
+export {};