path-treeify 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 isaaxite
+
+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,211 @@
+# path-treeify
+
+> 📖 [中文文档 (Chinese README)](https://github.com/isaaxite/path-treeify/blob/main/docs/README.zh-CN.md)
+
+<div align="left">
+  <!-- <h1>Path-Treeify</h1> -->
+  <p>Convert a path or an array of paths into a tree-structured JavaScript object, where each node holds a circular reference to its parent. </p>
+</div>
+
+<div align="left">
+  <a href="https://github.com/isaaxite/path-treeify">
+    <img alt="GitHub package.json dynamic" src="https://img.shields.io/github/package-json/version/isaaxite/path-treeify?logo=github">
+  </a>
+  <a href="https://nodejs.org">
+    <img alt="node" src="https://img.shields.io/node/v/path-treeify">
+  </a>
+  <a href="https://github.com/isaaxite/path-treeify/blob/main/LICENSE">
+    <img alt="license" src="https://img.shields.io/npm/l/path-treeify">
+  </a>
+  <a href="https://github.com/isaaxite/path-treeify">
+    <img alt="GitHub Created At" src="https://img.shields.io/github/created-at/isaaxite/path-treeify">
+  </a>
+  <a href="https://github.com/isaaxite/path-treeify">
+    <img alt="GitHub code size in bytes" src="https://img.shields.io/github/languages/code-size/isaaxite/path-treeify">
+  </a>
+  <a href="https://github.com/isaaxite/path-treeify/commits/main/">
+    <img alt="GitHub commit activity" src="https://img.shields.io/github/commit-activity/m/isaaxite/path-treeify">
+  </a>
+  <a href="https://github.com/isaaxite/path-treeify/commits/main/">
+    <img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/isaaxite/path-treeify">
+  </a>
+</div>
+
+---
+
+## Features
+
+- 🌲 Builds a recursive tree from one or more directory paths
+- 🔗 Each node carries a `parent` circular reference for upward traversal
+- 🔍 Optional `filter` callback to include/exclude directories during scanning
+- 📦 Ships as both ESM (`index.mjs`) and CJS (`index.cjs`) with full TypeScript types
+- 🚫 Zero runtime dependencies
+
+---
+
+## Requirements
+
+- Node.js `>= 18.0.0`
+
+---
+
+## Installation
+
+```bash
+npm install path-treeify
+```
+
+```bash
+yarn add path-treeify
+```
+
+---
+
+## Quick Start
+
+```ts
+import { PathTreeify } from 'path-treeify';
+
+const treeify = new PathTreeify({ base: '/your/project/root' });
+
+// Scan the whole base directory
+const tree = treeify.buildByDirPaths(['src', 'tests']);
+
+console.log(tree);
+// {
+//   parent: null,
+//   value: '',
+//   children: [
+//     { parent: [Circular], value: 'src',   children: [...] },
+//     { parent: [Circular], value: 'tests', children: [...] }
+//   ]
+// }
+```
+
+---
+
+## API
+
+### `new PathTreeify(options)`
+
+Creates a new instance.
+
+| Option   | Type                          | Required | Description                                       |
+|----------|-------------------------------|----------|---------------------------------------------------|
+| `base`   | `string`                      | ✅        | Absolute path to the root directory to scan from |
+| `filter` | `FilterFunction` (see below)  | ❌        | Called for every directory found during traversal |
+
+`base` must exist and be a directory, otherwise the constructor throws.
+
+---
+
+### `FilterFunction`
+
+```ts
+type FilterFunction = (params: {
+  name: string;    // directory name (leaf segment)
+  dirPath: string; // absolute path of the parent directory
+}) => boolean;
+```
+
+Return `true` to **include** the directory and recurse into it; `false` to **skip** it.
+
+**Example — skip hidden directories and `node_modules`:**
+
+```ts
+const treeify = new PathTreeify({
+  base: '/your/project',
+  filter: ({ name }) => !name.startsWith('.') && name !== 'node_modules',
+});
+```
+
+---
+
+### `buildByDirPaths(paths: string[]): PathTreeNode`
+
+Scans the given relative directory paths (resolved against `base`) and returns a synthetic root `PathTreeNode` whose `children` are the top-level nodes you requested.
+
+```ts
+const root = treeify.buildByDirPaths(['src', 'docs']);
+```
+
+- Each element of `paths` must be a valid, accessible directory relative to `base`.
+- Leading and trailing slashes are stripped automatically.
+- Throws if any path does not exist or is not a directory.
+
+---
+
+### `getPathBy(node: PathTreeNode): { relative: string; absolute: string }`
+
+Walks a node's `parent` chain to reconstruct its full path.
+
+```ts
+const srcNode = root.children[0];
+const { relative, absolute } = treeify.getPathBy(srcNode);
+// relative → 'src'
+// absolute → '/your/project/src'
+```
+
+---
+
+### `PathTreeNode`
+
+```ts
+interface PathTreeNode {
+  parent:   PathTreeNode | null; // null only on the synthetic root
+  value:    string;              // directory name for this node
+  children: PathTreeNode[];
+}
+```
+
+> ⚠️ **Circular references** — `parent` points back up the tree. Use `JSON.stringify` replacers or a library like `flatted` if you need to serialize the result.
+
+---
+
+## Examples
+
+### Scan an entire directory
+
+```ts
+import { PathTreeify } from 'path-treeify';
+import { readdirSync } from 'fs';
+
+const base = '/your/project';
+const treeify = new PathTreeify({ base });
+
+// Collect all top-level directories
+const topLevel = readdirSync(base, { withFileTypes: true })
+  .filter(d => d.isDirectory())
+  .map(d => d.name);
+
+const tree = treeify.buildByDirPaths(topLevel);
+```
+
+### Retrieve absolute paths while walking
+
+```ts
+function printPaths(node, treeify) {
+  for (const child of node.children) {
+    const { absolute } = treeify.getPathBy(child);
+    console.log(absolute);
+    printPaths(child, treeify);
+  }
+}
+
+printPaths(tree, treeify);
+```
+
+### CommonJS usage
+
+```js
+const { PathTreeify } = require('path-treeify');
+
+const treeify = new PathTreeify({ base: __dirname });
+const tree = treeify.buildByDirPaths(['src']);
+```
+
+---
+
+## License
+
+[MIT](https://github.com/isaaxite/path-treeify/blob/main//LICENSE) © [isaaxite](https://github.com/isaaxite)

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var t=require("fs"),r=require("path");class e{static isValid(r){try{return t.accessSync(r,t.constants.F_OK),!0}catch{return!1}}static isDirectory(r){try{return t.statSync(r).isDirectory()}catch{return!1}}}exports.PathTreeify=class{constructor({filter:t,base:r}){if(void 0!==t&&(this.validateFilter(t),this.filter=t),!r||!e.isValid(r))throw new Error(`${r} is not a valid path!`);if(!e.isDirectory(r))throw new Error(`${r} is not a dirPath!`);this.base=r}validateFilter(t){if("function"!=typeof t)throw new TypeError("filter must be a function");if(1!==t.length)throw new TypeError("filter must accept exactly one parameter");try{if("boolean"!=typeof t({name:"test",postPath:"/test"}))throw new TypeError("filter must return a boolean")}catch(t){throw new TypeError("filter function threw an error during test: "+t)}}initNode(t=null){return{parent:t,value:"",children:[]}}buildChildren(e,i){const o=t.readdirSync(e),s=[];for(const n of o){const o=r.join(e,n);if(!t.statSync(o).isDirectory())continue;if(this.filter&&!this.filter({dirPath:e,name:n}))continue;const a=this.initNode();a.value=n,a.parent=i,a.children=this.buildChildren(o,a),s.push(a)}return s}checkRelatePaths(t){if(!Array.isArray(t))throw new Error("Expected array, got "+typeof t);for(let i=0;i<t.length;i++){const o=t[i];if("string"!=typeof o)throw new Error(`Item at index ${i} is not a string, got ${typeof o}`);const s=r.resolve(this.base,o);if(!e.isValid(s))throw new Error(`Path does not exist or is not accessible: ${s} (from relative path: ${o})`);if(!e.isDirectory(s))throw new Error(`Path is not a directory: ${s} (from relative path: ${o})`)}}formatDirnames(t){return t.map(t=>t.replace(/^\/+|\/+$/g,"")).filter(t=>""!==t)}getPathBy(t){let e="",i=t;for(;i.parent;)e=e?`${i.value}${r.sep}${e}`:i.value,i=i.parent;return{relative:e,absolute:r.resolve(this.base,e)}}buildByDirPaths(t){const e=this.initNode();this.checkRelatePaths(t);const i=this.formatDirnames(t);for(const t of i){const i=this.initNode();i.value=t,i.parent=e,i.children=this.buildChildren(r.resolve(this.base,t),i),e.children.push(i)}return e}};

package/dist/index.mjs

@@ -0,0 +1 @@
+import{readdirSync as t,statSync as r,accessSync as e,constants as i}from"fs";import{join as o,resolve as n,sep as a}from"path";class s{static isValid(t){try{return e(t,i.F_OK),!0}catch{return!1}}static isDirectory(t){try{return r(t).isDirectory()}catch{return!1}}}class h{constructor({filter:t,base:r}){if(void 0!==t&&(this.validateFilter(t),this.filter=t),!r||!s.isValid(r))throw new Error(`${r} is not a valid path!`);if(!s.isDirectory(r))throw new Error(`${r} is not a dirPath!`);this.base=r}validateFilter(t){if("function"!=typeof t)throw new TypeError("filter must be a function");if(1!==t.length)throw new TypeError("filter must accept exactly one parameter");try{if("boolean"!=typeof t({name:"test",postPath:"/test"}))throw new TypeError("filter must return a boolean")}catch(t){throw new TypeError("filter function threw an error during test: "+t)}}initNode(t=null){return{parent:t,value:"",children:[]}}buildChildren(e,i){const n=t(e),a=[];for(const t of n){const n=o(e,t);if(!r(n).isDirectory())continue;if(this.filter&&!this.filter({dirPath:e,name:t}))continue;const s=this.initNode();s.value=t,s.parent=i,s.children=this.buildChildren(n,s),a.push(s)}return a}checkRelatePaths(t){if(!Array.isArray(t))throw new Error("Expected array, got "+typeof t);for(let r=0;r<t.length;r++){const e=t[r];if("string"!=typeof e)throw new Error(`Item at index ${r} is not a string, got ${typeof e}`);const i=n(this.base,e);if(!s.isValid(i))throw new Error(`Path does not exist or is not accessible: ${i} (from relative path: ${e})`);if(!s.isDirectory(i))throw new Error(`Path is not a directory: ${i} (from relative path: ${e})`)}}formatDirnames(t){return t.map(t=>t.replace(/^\/+|\/+$/g,"")).filter(t=>""!==t)}getPathBy(t){let r="",e=t;for(;e.parent;)r=r?`${e.value}${a}${r}`:e.value,e=e.parent;return{relative:r,absolute:n(this.base,r)}}buildByDirPaths(t){const r=this.initNode();this.checkRelatePaths(t);const e=this.formatDirnames(t);for(const t of e){const e=this.initNode();e.value=t,e.parent=r,e.children=this.buildChildren(n(this.base,t),e),r.children.push(e)}return r}}export{h as PathTreeify};

package/dist/types/index.d.ts

@@ -0,0 +1,29 @@
+type FilterFunction = (params: {
+    name: string;
+    dirPath: string;
+}) => boolean;
+interface PathTreeifyProps {
+    base: string;
+    filter?: FilterFunction;
+}
+interface PathTreeNode {
+    parent: PathTreeNode | null;
+    value: string;
+    children: PathTreeNode[];
+}
+export declare class PathTreeify {
+    private base;
+    private filter?;
+    constructor({ filter, base }: Partial<PathTreeifyProps>);
+    private validateFilter;
+    private initNode;
+    private buildChildren;
+    private checkRelatePaths;
+    private formatDirnames;
+    getPathBy(node: PathTreeNode): {
+        relative: string;
+        absolute: string;
+    };
+    buildByDirPaths(nameOfDirs: string[]): PathTreeNode;
+}
+export {};

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "path-treeify",
+  "version": "1.0.0",
+  "description": "Convert a path or an array of paths into a tree-structured JavaScript object, where each node has a `parent` property that holds a circular reference to its parent node.",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/index.mjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/index.cjs",
+    "dist/index.mjs",
+    "dist/**/*.d.ts",
+    "README.md",
+    "!README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "clean": "rimraf ./dist",
+    "build": "npm run clean && rollup -c",
+    "build:dev": "NODE_ENV=development npm run build",
+    "build:prod": "NODE_ENV=production npm run build",
+    "build:watch": "nodemon --watch src -e ts --exec \"npm run build:dev\"",
+    "check-publish": "npm pack --dry-run",
+    "publish": "npm publish"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/isaaxite/path-treeify.git"
+  },
+  "bugs": {
+    "url": "https://github.com/isaaxite/path-treeify/issues"
+  },
+  "keywords": [
+    "path",
+    "tree",
+    "treeify",
+    "hierarchy",
+    "filesystem",
+    "object",
+    "circular",
+    "reference"
+  ],
+  "author": {
+    "name": "isaaxite",
+    "url": "https://github.com/isaaxite"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/isaaxite/path-treeify#readme",
+  "sideEffects": false,
+  "devDependencies": {
+    "@rollup/plugin-terser": "^1.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^25.5.0",
+    "nodemon": "^3.1.14",
+    "rimraf": "^6.1.3",
+    "rollup": "^4.59.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  }
+}