@zthun/crumbtrail-fs 1.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+# MIT License
+
+Copyright © 2025 Anthony Bonta
+
+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

@@ -0,0 +1,11 @@
+# Description
+
+Crumbtrail is additional file system methods for node that are helpful and are
+better suited for unit testing.
+
+## Installation
+
+```sh
+npm install @zthun/crumbtrail-fs
+yarn add @zthun/crumbtrail-fs
+```

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

@@ -0,0 +1,44 @@
+/**
+ * Represents a type of a file system node.
+ */
+export declare enum ZFileSystemNodeType {
+    File = "file",
+    Folder = "folder"
+}
+export interface IZFileSystemNode {
+    /**
+     * The absolute path of the node.
+     */
+    path: string;
+    /**
+     * The type of the node (file or folder).
+     */
+    type: ZFileSystemNodeType;
+    /**
+     * The creation date of the node.
+     */
+    created?: string;
+    /**
+     * The modification date of the node.
+     */
+    updated?: string;
+    /**
+     * The size of the node in bytes.
+     */
+    size?: bigint;
+}
+/**
+ * Represents a builder for a file system node.
+ */
+export declare class ZFileSystemNodeBuilder {
+    private _node;
+    constructor();
+    created(at?: Date | string | undefined): this;
+    updated(at?: Date | string | undefined): this;
+    size(bytes: bigint | number | undefined): this;
+    path(path: string): this;
+    type(type: ZFileSystemNodeType): this;
+    file: () => this;
+    folder: () => this;
+    build(): IZFileSystemNode;
+}

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

@@ -0,0 +1,51 @@
+import { IZFileSystemNode } from './file-system-node.mjs';
+/**
+ * Represents options for searches.
+ */
+export interface IZFileSystemSearchOptions {
+    /**
+     * The directory to search in.
+     *
+     * If this is not set, then the cwd of the application is used.
+     */
+    cwd?: string;
+}
+/**
+ * Represents a service to enumerate the file system.
+ */
+export interface IZFileSystemService {
+    /**
+     * Gets information about a node.
+     *
+     * @param path -
+     *        The path to get information for.
+     *
+     * @returns
+     *        Information about the node.
+     */
+    info(path: string): Promise<IZFileSystemNode>;
+    /**
+     * Reads all nodes that match a pattern.
+     *
+     * @param pattern -
+     *        The pattern string to match against.
+     * @param options -
+     *        The options for the search.
+     *
+     * @returns
+     *        A list of path strings that match the given patterns.
+     */
+    search(pattern: string, options?: IZFileSystemSearchOptions): Promise<IZFileSystemNode[]>;
+}
+/**
+ * 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[]>;
+}

package/dist/index.cjs

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const lodashEs = require("lodash-es");
+const glob = require("glob");
+const promises = require("node:fs/promises");
+const node_path = require("node:path");
+const node_process = require("node:process");
+var ZFileSystemNodeType = /* @__PURE__ */ ((ZFileSystemNodeType2) => {
+  ZFileSystemNodeType2["File"] = "file";
+  ZFileSystemNodeType2["Folder"] = "folder";
+  return ZFileSystemNodeType2;
+})(ZFileSystemNodeType || {});
+class ZFileSystemNodeBuilder {
+  constructor() {
+    this.file = this.type.bind(
+      this,
+      "file"
+      /* File */
+    );
+    this.folder = this.type.bind(
+      this,
+      "folder"
+      /* Folder */
+    );
+    this._node = {
+      path: "/",
+      type: "folder"
+      /* Folder */
+    };
+  }
+  created(at) {
+    this._node.created = at instanceof Date ? at.toJSON() : at;
+    return this;
+  }
+  updated(at) {
+    this._node.updated = at instanceof Date ? at.toJSON() : at;
+    return this;
+  }
+  size(bytes) {
+    this._node.size = typeof bytes == "number" ? BigInt(bytes) : bytes;
+    return this;
+  }
+  path(path) {
+    this._node.path = path;
+    return this;
+  }
+  type(type) {
+    this._node.type = type;
+    return this;
+  }
+  build() {
+    const clone = structuredClone(this._node);
+    return lodashEs.omitBy(clone, lodashEs.isUndefined);
+  }
+}
+const ZFileSystemToken = Symbol("file-system");
+class ZFileSystemService {
+  async info(path) {
+    const [file] = await this.search(path);
+    return file;
+  }
+  async search(pattern, options) {
+    const paths = await glob.glob(pattern, {
+      ...options,
+      stat: true,
+      withFileTypes: true
+    });
+    return paths.map((path) => {
+      let info = new ZFileSystemNodeBuilder().path(path.fullpath()).created(path.birthtime).updated(path.atime).size(path.size);
+      info = path.isFile() ? info.file() : info.folder().size(void 0);
+      return info.build();
+    });
+  }
+}
+async function walk(search, options) {
+  const start = (options == null ? void 0 : options.start) || node_process.cwd();
+  const stop = (options == null ? void 0 : options.stop) || "/";
+  const mode = options == null ? void 0 : options.mode;
+  const _test = async (path) => {
+    try {
+      await promises.access(path, mode);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  if (node_path.isAbsolute(search)) {
+    return await _test(search) ? search : null;
+  }
+  let dir = start;
+  do {
+    const path = node_path.resolve(dir, search);
+    const exists = await _test(path);
+    if (exists) {
+      return path;
+    }
+    dir = dir === stop ? "" : node_path.dirname(dir);
+  } while (dir.length);
+  return null;
+}
+exports.ZFileSystemNodeBuilder = ZFileSystemNodeBuilder;
+exports.ZFileSystemNodeType = ZFileSystemNodeType;
+exports.ZFileSystemService = ZFileSystemService;
+exports.ZFileSystemToken = ZFileSystemToken;
+exports.walk = walk;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/file-system/file-system-node.mts","../src/file-system/file-system-service.mts","../src/walk/walk.mts"],"sourcesContent":["import { isUndefined, omitBy } from \"lodash-es\";\n\n/**\n * Represents a type of a file system node.\n */\nexport enum ZFileSystemNodeType {\n  File = \"file\",\n  Folder = \"folder\",\n}\n\nexport interface IZFileSystemNode {\n  /**\n   * The absolute path of the node.\n   */\n  path: string;\n\n  /**\n   * The type of the node (file or folder).\n   */\n  type: ZFileSystemNodeType;\n\n  /**\n   * The creation date of the node.\n   */\n  created?: string;\n\n  /**\n   * The modification date of the node.\n   */\n  updated?: string;\n\n  /**\n   * The size of the node in bytes.\n   */\n  size?: bigint;\n}\n\n/**\n * Represents a builder for a file system node.\n */\nexport class ZFileSystemNodeBuilder {\n  private _node: IZFileSystemNode;\n\n  public constructor() {\n    this._node = {\n      path: \"/\",\n      type: ZFileSystemNodeType.Folder,\n    };\n  }\n\n  public created(at?: Date | string | undefined) {\n    this._node.created = at instanceof Date ? at.toJSON() : at;\n    return this;\n  }\n\n  public updated(at?: Date | string | undefined) {\n    this._node.updated = at instanceof Date ? at.toJSON() : at;\n    return this;\n  }\n\n  public size(bytes: bigint | number | undefined) {\n    this._node.size = typeof bytes == \"number\" ? BigInt(bytes) : bytes;\n    return this;\n  }\n\n  public path(path: string) {\n    this._node.path = path;\n    return this;\n  }\n\n  public type(type: ZFileSystemNodeType) {\n    this._node.type = type;\n    return this;\n  }\n\n  public file = this.type.bind(this, ZFileSystemNodeType.File);\n  public folder = this.type.bind(this, ZFileSystemNodeType.Folder);\n\n  public build() {\n    const clone = structuredClone(this._node);\n    return omitBy<IZFileSystemNode>(clone, isUndefined) as IZFileSystemNode;\n  }\n}\n","import { glob } from \"glob\";\nimport {\n  IZFileSystemNode,\n  ZFileSystemNodeBuilder,\n} from \"./file-system-node.mjs\";\n\n/**\n * Represents options for searches.\n */\nexport interface IZFileSystemSearchOptions {\n  /**\n   * The directory to search in.\n   *\n   * If this is not set, then the cwd of the application is used.\n   */\n  cwd?: string;\n}\n\n/**\n * Represents a service to enumerate the file system.\n */\nexport interface IZFileSystemService {\n  /**\n   * Gets information about a node.\n   *\n   * @param path -\n   *        The path to get information for.\n   *\n   * @returns\n   *        Information about the node.\n   */\n  info(path: string): Promise<IZFileSystemNode>;\n\n  /**\n   * Reads all nodes that match a pattern.\n   *\n   * @param pattern -\n   *        The pattern string to match against.\n   * @param options -\n   *        The options for the search.\n   *\n   * @returns\n   *        A list of path strings that match the given patterns.\n   */\n  search(\n    pattern: string,\n    options?: IZFileSystemSearchOptions,\n  ): Promise<IZFileSystemNode[]>;\n}\n\n/**\n * A token that you can use with a framework like nest-js to describe\n * a file system service implementation.\n */\nexport const ZFileSystemToken = Symbol(\"file-system\");\n\n/**\n * Represents a node implementation of a file system service.\n */\nexport class ZFileSystemService implements IZFileSystemService {\n  public async info(path: string): Promise<IZFileSystemNode> {\n    const [file] = await this.search(path);\n    return file;\n  }\n\n  public async search(\n    pattern: string | string[],\n    options?: IZFileSystemSearchOptions,\n  ): Promise<IZFileSystemNode[]> {\n    const paths = await glob(pattern, {\n      ...options,\n      stat: true,\n      withFileTypes: true,\n    });\n\n    return paths.map((path) => {\n      let info = new ZFileSystemNodeBuilder()\n        .path(path.fullpath())\n        .created(path.birthtime)\n        .updated(path.atime)\n        .size(path.size);\n\n      // Note that for folders, node will return the size of the underlying OS metadata,\n      // hence, why we 0 out the size on a folder here.\n      info = path.isFile() ? info.file() : info.folder().size(undefined);\n\n      return info.build();\n    });\n  }\n}\n","import { access } from \"node:fs/promises\";\nimport { dirname, isAbsolute, resolve } from \"node:path\";\nimport { cwd } from \"node:process\";\n\n/**\n * Options for where a directory walk starts.\n */\nexport interface ZWalkOptions {\n  /**\n   * The starting directory.\n   *\n   * The default is the current working directory\n   *\n   * @see process.cwd for more information.\n   */\n  start?: string;\n\n  /**\n   * The directory to stop at.\n   *\n   * The default is the root of the file system.\n   */\n  stop?: string;\n\n  /**\n   * The type of mode that the path must support in order\n   * to be approved.\n   *\n   * The default is undefined and left up to the node api.\n   */\n  mode?: number;\n}\n\n/**\n * Walks up a directory tree to search for existence of a given path.\n *\n * @param search -\n *        The path to search for.  This is the candidate folder path that\n *        may or may not exist somewhere from the start directory all the\n *        way up the directory tree.\n * @param options -\n *        The given options for the search.\n *\n * @returns\n *        The fully qualified path to the first path that matches the search\n *        starting at the options start or the current working directory if not\n *        specified.  Returns null if no such directory exists.\n *\n * @example\n *\n * ```ts\n * import { resolve } from 'path'\n *\n * // Find any folder named .vscode from the current working directory all the way\n * // up the directory tree.  Returns null if no vscode directory can be found.\n * const vscode = walk('.vscode');\n *\n * // Walk the directory tree from the current script and find the .config folder.\n * const config = walk('.config', { start: __dirname });\n *\n * // Walk the directory tree from the current script and stop when we reach\n * // at most 2 directories up.\n * const start = __dirname;\n * const stop = resolve(__dirname, '../..');\n * const file = walk('path/to/file.json', { start, stop });\n * ```\n */\nexport async function walk(\n  search: string,\n  options?: ZWalkOptions,\n): Promise<string | null> {\n  const start = options?.start || cwd();\n  const stop = options?.stop || \"/\";\n  const mode = options?.mode;\n\n  const _test = async (path: string) => {\n    try {\n      await access(path, mode);\n      return true;\n    } catch {\n      return false;\n    }\n  };\n\n  if (isAbsolute(search)) {\n    return (await _test(search)) ? search : null;\n  }\n\n  let dir = start;\n  do {\n    const path = resolve(dir, search);\n    const exists = await _test(path);\n\n    if (exists) {\n      return path;\n    }\n\n    dir = dir === stop ? \"\" : dirname(dir);\n  } while (dir.length);\n\n  return null;\n}\n"],"names":["ZFileSystemNodeType","omitBy","isUndefined","glob","cwd","access","isAbsolute","resolve","dirname"],"mappings":";;;;;;;AAKY,IAAA,wCAAAA,yBAAL;AACLA,uBAAA,MAAO,IAAA;AACPA,uBAAA,QAAS,IAAA;AAFCA,SAAAA;AAAA,GAAA,uBAAA,CAAA,CAAA;AAmCL,MAAM,uBAAuB;AAAA,EAG3B,cAAc;AAgCrB,SAAO,OAAO,KAAK,KAAK;AAAA,MAAK;AAAA,MAAM;AAAA;AAAA,IAAwB;AAC3D,SAAO,SAAS,KAAK,KAAK;AAAA,MAAK;AAAA,MAAM;AAAA;AAAA,IAA0B;AAhC7D,SAAK,QAAQ;AAAA,MACX,MAAM;AAAA,MACN,MAAM;AAAA;AAAA,IACR;AAAA,EAAA;AAAA,EAGK,QAAQ,IAAgC;AAC7C,SAAK,MAAM,UAAU,cAAc,OAAO,GAAG,WAAW;AACjD,WAAA;AAAA,EAAA;AAAA,EAGF,QAAQ,IAAgC;AAC7C,SAAK,MAAM,UAAU,cAAc,OAAO,GAAG,WAAW;AACjD,WAAA;AAAA,EAAA;AAAA,EAGF,KAAK,OAAoC;AAC9C,SAAK,MAAM,OAAO,OAAO,SAAS,WAAW,OAAO,KAAK,IAAI;AACtD,WAAA;AAAA,EAAA;AAAA,EAGF,KAAK,MAAc;AACxB,SAAK,MAAM,OAAO;AACX,WAAA;AAAA,EAAA;AAAA,EAGF,KAAK,MAA2B;AACrC,SAAK,MAAM,OAAO;AACX,WAAA;AAAA,EAAA;AAAA,EAMF,QAAQ;AACP,UAAA,QAAQ,gBAAgB,KAAK,KAAK;AACjC,WAAAC,SAAA,OAAyB,OAAOC,oBAAW;AAAA,EAAA;AAEtD;AC5Ba,MAAA,mBAAmB,OAAO,aAAa;AAK7C,MAAM,mBAAkD;AAAA,EAC7D,MAAa,KAAK,MAAyC;AACzD,UAAM,CAAC,IAAI,IAAI,MAAM,KAAK,OAAO,IAAI;AAC9B,WAAA;AAAA,EAAA;AAAA,EAGT,MAAa,OACX,SACA,SAC6B;AACvB,UAAA,QAAQ,MAAMC,KAAA,KAAK,SAAS;AAAA,MAChC,GAAG;AAAA,MACH,MAAM;AAAA,MACN,eAAe;AAAA,IAAA,CAChB;AAEM,WAAA,MAAM,IAAI,CAAC,SAAS;AACzB,UAAI,OAAO,IAAI,yBACZ,KAAK,KAAK,SAAU,CAAA,EACpB,QAAQ,KAAK,SAAS,EACtB,QAAQ,KAAK,KAAK,EAClB,KAAK,KAAK,IAAI;AAIV,aAAA,KAAK,OAAO,IAAI,KAAK,SAAS,KAAK,OAAA,EAAS,KAAK,MAAS;AAEjE,aAAO,KAAK,MAAM;AAAA,IAAA,CACnB;AAAA,EAAA;AAEL;ACtBsB,eAAA,KACpB,QACA,SACwB;AAClB,QAAA,SAAQ,mCAAS,UAASC,iBAAI;AAC9B,QAAA,QAAO,mCAAS,SAAQ;AAC9B,QAAM,OAAO,mCAAS;AAEhB,QAAA,QAAQ,OAAO,SAAiB;AAChC,QAAA;AACI,YAAAC,SAAA,OAAO,MAAM,IAAI;AAChB,aAAA;AAAA,IAAA,QACD;AACC,aAAA;AAAA,IAAA;AAAA,EAEX;AAEI,MAAAC,UAAAA,WAAW,MAAM,GAAG;AACtB,WAAQ,MAAM,MAAM,MAAM,IAAK,SAAS;AAAA,EAAA;AAG1C,MAAI,MAAM;AACP,KAAA;AACK,UAAA,OAAOC,UAAAA,QAAQ,KAAK,MAAM;AAC1B,UAAA,SAAS,MAAM,MAAM,IAAI;AAE/B,QAAI,QAAQ;AACH,aAAA;AAAA,IAAA;AAGT,UAAM,QAAQ,OAAO,KAAKC,UAAAA,QAAQ,GAAG;AAAA,WAC9B,IAAI;AAEN,SAAA;AACT;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './file-system/file-system-node.mjs';
+export * from './file-system/file-system-service.mjs';
+export * from './walk/walk.mjs';

package/dist/index.js

@@ -0,0 +1,106 @@
+import { omitBy, isUndefined } from "lodash-es";
+import { glob } from "glob";
+import { access } from "node:fs/promises";
+import { isAbsolute, resolve, dirname } from "node:path";
+import { cwd } from "node:process";
+var ZFileSystemNodeType = /* @__PURE__ */ ((ZFileSystemNodeType2) => {
+  ZFileSystemNodeType2["File"] = "file";
+  ZFileSystemNodeType2["Folder"] = "folder";
+  return ZFileSystemNodeType2;
+})(ZFileSystemNodeType || {});
+class ZFileSystemNodeBuilder {
+  constructor() {
+    this.file = this.type.bind(
+      this,
+      "file"
+      /* File */
+    );
+    this.folder = this.type.bind(
+      this,
+      "folder"
+      /* Folder */
+    );
+    this._node = {
+      path: "/",
+      type: "folder"
+      /* Folder */
+    };
+  }
+  created(at) {
+    this._node.created = at instanceof Date ? at.toJSON() : at;
+    return this;
+  }
+  updated(at) {
+    this._node.updated = at instanceof Date ? at.toJSON() : at;
+    return this;
+  }
+  size(bytes) {
+    this._node.size = typeof bytes == "number" ? BigInt(bytes) : bytes;
+    return this;
+  }
+  path(path) {
+    this._node.path = path;
+    return this;
+  }
+  type(type) {
+    this._node.type = type;
+    return this;
+  }
+  build() {
+    const clone = structuredClone(this._node);
+    return omitBy(clone, isUndefined);
+  }
+}
+const ZFileSystemToken = Symbol("file-system");
+class ZFileSystemService {
+  async info(path) {
+    const [file] = await this.search(path);
+    return file;
+  }
+  async search(pattern, options) {
+    const paths = await glob(pattern, {
+      ...options,
+      stat: true,
+      withFileTypes: true
+    });
+    return paths.map((path) => {
+      let info = new ZFileSystemNodeBuilder().path(path.fullpath()).created(path.birthtime).updated(path.atime).size(path.size);
+      info = path.isFile() ? info.file() : info.folder().size(void 0);
+      return info.build();
+    });
+  }
+}
+async function walk(search, options) {
+  const start = (options == null ? void 0 : options.start) || cwd();
+  const stop = (options == null ? void 0 : options.stop) || "/";
+  const mode = options == null ? void 0 : options.mode;
+  const _test = async (path) => {
+    try {
+      await access(path, mode);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  if (isAbsolute(search)) {
+    return await _test(search) ? search : null;
+  }
+  let dir = start;
+  do {
+    const path = resolve(dir, search);
+    const exists = await _test(path);
+    if (exists) {
+      return path;
+    }
+    dir = dir === stop ? "" : dirname(dir);
+  } while (dir.length);
+  return null;
+}
+export {
+  ZFileSystemNodeBuilder,
+  ZFileSystemNodeType,
+  ZFileSystemService,
+  ZFileSystemToken,
+  walk
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/file-system/file-system-node.mts","../src/file-system/file-system-service.mts","../src/walk/walk.mts"],"sourcesContent":["import { isUndefined, omitBy } from \"lodash-es\";\n\n/**\n * Represents a type of a file system node.\n */\nexport enum ZFileSystemNodeType {\n  File = \"file\",\n  Folder = \"folder\",\n}\n\nexport interface IZFileSystemNode {\n  /**\n   * The absolute path of the node.\n   */\n  path: string;\n\n  /**\n   * The type of the node (file or folder).\n   */\n  type: ZFileSystemNodeType;\n\n  /**\n   * The creation date of the node.\n   */\n  created?: string;\n\n  /**\n   * The modification date of the node.\n   */\n  updated?: string;\n\n  /**\n   * The size of the node in bytes.\n   */\n  size?: bigint;\n}\n\n/**\n * Represents a builder for a file system node.\n */\nexport class ZFileSystemNodeBuilder {\n  private _node: IZFileSystemNode;\n\n  public constructor() {\n    this._node = {\n      path: \"/\",\n      type: ZFileSystemNodeType.Folder,\n    };\n  }\n\n  public created(at?: Date | string | undefined) {\n    this._node.created = at instanceof Date ? at.toJSON() : at;\n    return this;\n  }\n\n  public updated(at?: Date | string | undefined) {\n    this._node.updated = at instanceof Date ? at.toJSON() : at;\n    return this;\n  }\n\n  public size(bytes: bigint | number | undefined) {\n    this._node.size = typeof bytes == \"number\" ? BigInt(bytes) : bytes;\n    return this;\n  }\n\n  public path(path: string) {\n    this._node.path = path;\n    return this;\n  }\n\n  public type(type: ZFileSystemNodeType) {\n    this._node.type = type;\n    return this;\n  }\n\n  public file = this.type.bind(this, ZFileSystemNodeType.File);\n  public folder = this.type.bind(this, ZFileSystemNodeType.Folder);\n\n  public build() {\n    const clone = structuredClone(this._node);\n    return omitBy<IZFileSystemNode>(clone, isUndefined) as IZFileSystemNode;\n  }\n}\n","import { glob } from \"glob\";\nimport {\n  IZFileSystemNode,\n  ZFileSystemNodeBuilder,\n} from \"./file-system-node.mjs\";\n\n/**\n * Represents options for searches.\n */\nexport interface IZFileSystemSearchOptions {\n  /**\n   * The directory to search in.\n   *\n   * If this is not set, then the cwd of the application is used.\n   */\n  cwd?: string;\n}\n\n/**\n * Represents a service to enumerate the file system.\n */\nexport interface IZFileSystemService {\n  /**\n   * Gets information about a node.\n   *\n   * @param path -\n   *        The path to get information for.\n   *\n   * @returns\n   *        Information about the node.\n   */\n  info(path: string): Promise<IZFileSystemNode>;\n\n  /**\n   * Reads all nodes that match a pattern.\n   *\n   * @param pattern -\n   *        The pattern string to match against.\n   * @param options -\n   *        The options for the search.\n   *\n   * @returns\n   *        A list of path strings that match the given patterns.\n   */\n  search(\n    pattern: string,\n    options?: IZFileSystemSearchOptions,\n  ): Promise<IZFileSystemNode[]>;\n}\n\n/**\n * A token that you can use with a framework like nest-js to describe\n * a file system service implementation.\n */\nexport const ZFileSystemToken = Symbol(\"file-system\");\n\n/**\n * Represents a node implementation of a file system service.\n */\nexport class ZFileSystemService implements IZFileSystemService {\n  public async info(path: string): Promise<IZFileSystemNode> {\n    const [file] = await this.search(path);\n    return file;\n  }\n\n  public async search(\n    pattern: string | string[],\n    options?: IZFileSystemSearchOptions,\n  ): Promise<IZFileSystemNode[]> {\n    const paths = await glob(pattern, {\n      ...options,\n      stat: true,\n      withFileTypes: true,\n    });\n\n    return paths.map((path) => {\n      let info = new ZFileSystemNodeBuilder()\n        .path(path.fullpath())\n        .created(path.birthtime)\n        .updated(path.atime)\n        .size(path.size);\n\n      // Note that for folders, node will return the size of the underlying OS metadata,\n      // hence, why we 0 out the size on a folder here.\n      info = path.isFile() ? info.file() : info.folder().size(undefined);\n\n      return info.build();\n    });\n  }\n}\n","import { access } from \"node:fs/promises\";\nimport { dirname, isAbsolute, resolve } from \"node:path\";\nimport { cwd } from \"node:process\";\n\n/**\n * Options for where a directory walk starts.\n */\nexport interface ZWalkOptions {\n  /**\n   * The starting directory.\n   *\n   * The default is the current working directory\n   *\n   * @see process.cwd for more information.\n   */\n  start?: string;\n\n  /**\n   * The directory to stop at.\n   *\n   * The default is the root of the file system.\n   */\n  stop?: string;\n\n  /**\n   * The type of mode that the path must support in order\n   * to be approved.\n   *\n   * The default is undefined and left up to the node api.\n   */\n  mode?: number;\n}\n\n/**\n * Walks up a directory tree to search for existence of a given path.\n *\n * @param search -\n *        The path to search for.  This is the candidate folder path that\n *        may or may not exist somewhere from the start directory all the\n *        way up the directory tree.\n * @param options -\n *        The given options for the search.\n *\n * @returns\n *        The fully qualified path to the first path that matches the search\n *        starting at the options start or the current working directory if not\n *        specified.  Returns null if no such directory exists.\n *\n * @example\n *\n * ```ts\n * import { resolve } from 'path'\n *\n * // Find any folder named .vscode from the current working directory all the way\n * // up the directory tree.  Returns null if no vscode directory can be found.\n * const vscode = walk('.vscode');\n *\n * // Walk the directory tree from the current script and find the .config folder.\n * const config = walk('.config', { start: __dirname });\n *\n * // Walk the directory tree from the current script and stop when we reach\n * // at most 2 directories up.\n * const start = __dirname;\n * const stop = resolve(__dirname, '../..');\n * const file = walk('path/to/file.json', { start, stop });\n * ```\n */\nexport async function walk(\n  search: string,\n  options?: ZWalkOptions,\n): Promise<string | null> {\n  const start = options?.start || cwd();\n  const stop = options?.stop || \"/\";\n  const mode = options?.mode;\n\n  const _test = async (path: string) => {\n    try {\n      await access(path, mode);\n      return true;\n    } catch {\n      return false;\n    }\n  };\n\n  if (isAbsolute(search)) {\n    return (await _test(search)) ? search : null;\n  }\n\n  let dir = start;\n  do {\n    const path = resolve(dir, search);\n    const exists = await _test(path);\n\n    if (exists) {\n      return path;\n    }\n\n    dir = dir === stop ? \"\" : dirname(dir);\n  } while (dir.length);\n\n  return null;\n}\n"],"names":["ZFileSystemNodeType"],"mappings":";;;;;AAKY,IAAA,wCAAAA,yBAAL;AACLA,uBAAA,MAAO,IAAA;AACPA,uBAAA,QAAS,IAAA;AAFCA,SAAAA;AAAA,GAAA,uBAAA,CAAA,CAAA;AAmCL,MAAM,uBAAuB;AAAA,EAG3B,cAAc;AAgCrB,SAAO,OAAO,KAAK,KAAK;AAAA,MAAK;AAAA,MAAM;AAAA;AAAA,IAAwB;AAC3D,SAAO,SAAS,KAAK,KAAK;AAAA,MAAK;AAAA,MAAM;AAAA;AAAA,IAA0B;AAhC7D,SAAK,QAAQ;AAAA,MACX,MAAM;AAAA,MACN,MAAM;AAAA;AAAA,IACR;AAAA,EAAA;AAAA,EAGK,QAAQ,IAAgC;AAC7C,SAAK,MAAM,UAAU,cAAc,OAAO,GAAG,WAAW;AACjD,WAAA;AAAA,EAAA;AAAA,EAGF,QAAQ,IAAgC;AAC7C,SAAK,MAAM,UAAU,cAAc,OAAO,GAAG,WAAW;AACjD,WAAA;AAAA,EAAA;AAAA,EAGF,KAAK,OAAoC;AAC9C,SAAK,MAAM,OAAO,OAAO,SAAS,WAAW,OAAO,KAAK,IAAI;AACtD,WAAA;AAAA,EAAA;AAAA,EAGF,KAAK,MAAc;AACxB,SAAK,MAAM,OAAO;AACX,WAAA;AAAA,EAAA;AAAA,EAGF,KAAK,MAA2B;AACrC,SAAK,MAAM,OAAO;AACX,WAAA;AAAA,EAAA;AAAA,EAMF,QAAQ;AACP,UAAA,QAAQ,gBAAgB,KAAK,KAAK;AACjC,WAAA,OAAyB,OAAO,WAAW;AAAA,EAAA;AAEtD;AC5Ba,MAAA,mBAAmB,OAAO,aAAa;AAK7C,MAAM,mBAAkD;AAAA,EAC7D,MAAa,KAAK,MAAyC;AACzD,UAAM,CAAC,IAAI,IAAI,MAAM,KAAK,OAAO,IAAI;AAC9B,WAAA;AAAA,EAAA;AAAA,EAGT,MAAa,OACX,SACA,SAC6B;AACvB,UAAA,QAAQ,MAAM,KAAK,SAAS;AAAA,MAChC,GAAG;AAAA,MACH,MAAM;AAAA,MACN,eAAe;AAAA,IAAA,CAChB;AAEM,WAAA,MAAM,IAAI,CAAC,SAAS;AACzB,UAAI,OAAO,IAAI,yBACZ,KAAK,KAAK,SAAU,CAAA,EACpB,QAAQ,KAAK,SAAS,EACtB,QAAQ,KAAK,KAAK,EAClB,KAAK,KAAK,IAAI;AAIV,aAAA,KAAK,OAAO,IAAI,KAAK,SAAS,KAAK,OAAA,EAAS,KAAK,MAAS;AAEjE,aAAO,KAAK,MAAM;AAAA,IAAA,CACnB;AAAA,EAAA;AAEL;ACtBsB,eAAA,KACpB,QACA,SACwB;AAClB,QAAA,SAAQ,mCAAS,UAAS,IAAI;AAC9B,QAAA,QAAO,mCAAS,SAAQ;AAC9B,QAAM,OAAO,mCAAS;AAEhB,QAAA,QAAQ,OAAO,SAAiB;AAChC,QAAA;AACI,YAAA,OAAO,MAAM,IAAI;AAChB,aAAA;AAAA,IAAA,QACD;AACC,aAAA;AAAA,IAAA;AAAA,EAEX;AAEI,MAAA,WAAW,MAAM,GAAG;AACtB,WAAQ,MAAM,MAAM,MAAM,IAAK,SAAS;AAAA,EAAA;AAG1C,MAAI,MAAM;AACP,KAAA;AACK,UAAA,OAAO,QAAQ,KAAK,MAAM;AAC1B,UAAA,SAAS,MAAM,MAAM,IAAI;AAE/B,QAAI,QAAQ;AACH,aAAA;AAAA,IAAA;AAGT,UAAM,QAAQ,OAAO,KAAK,QAAQ,GAAG;AAAA,WAC9B,IAAI;AAEN,SAAA;AACT;"}

package/dist/walk/walk.d.mts

@@ -0,0 +1,61 @@
+/**
+ * Options for where a directory walk starts.
+ */
+export interface ZWalkOptions {
+    /**
+     * 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;
+}
+/**
+ * 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 vscode = walk('.vscode');
+ *
+ * // Walk the directory tree from the current script and find the .config folder.
+ * const config = 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 = walk('path/to/file.json', { start, stop });
+ * ```
+ */
+export declare function walk(search: string, options?: ZWalkOptions): Promise<string | null>;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@zthun/crumbtrail-fs",
+  "version": "1.1.0",
+  "description": "A better file system module for node",
+  "author": "Anthony Bonta",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zthun/crumbtrail",
+    "directory": "packages/crumbtrail-fs"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    "types": "./dist/index.d.ts",
+    "require": "./dist/index.cjs",
+    "import": "./dist/index.js"
+  },
+  "engines": {
+    "node": ">=22.16.0"
+  },
+  "scripts": {
+    "build": "vite build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "glob": "^11.0.2",
+    "lodash-es": "^4.17.21"
+  },
+  "devDependencies": {
+    "vite": "^6.3.5",
+    "vitest": "^3.1.4"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "gitHead": "3e311966e8d62306da2cf5427f4db2cf1a027bf5"
+}