tiny-essentials 1.25.6 → 1.26.0

package/TinyFork.mjs

@@ -0,0 +1,608 @@
+#!/usr/bin/env node
+
+import fs from 'fs/promises';
+import { existsSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import parser from '@babel/parser';
+import _traverse from '@babel/traverse';
+import _generate from '@babel/generator';
+import * as t from '@babel/types';
+
+// Workaround for Babel ESM compatibility
+const traverse = _traverse.default || _traverse;
+const generate = _generate.default || _generate;
+
+const LATEST_VERSION = 1;
+
+/**
+ * Defines the current execution paths.
+ * @typedef {Object} AppPaths
+ * @property {string} cliRoot - The root directory of tiny-essentials.
+ * @property {string} userProjectRoot - The root directory of the user's project invoking the CLI.
+ */
+const PATHS = {
+  cliRoot: path.dirname(fileURLToPath(import.meta.url)),
+  userProjectRoot: process.cwd(),
+  /**
+   * Resolves the output directory.
+   * @param {string|null} customPath - Optional custom path provided by the user.
+   * @returns {string} The absolute path for the vendor directory.
+   */
+  getVendorDir(customPath) {
+    return customPath
+      ? path.resolve(this.userProjectRoot, customPath)
+      : path.join(this.userProjectRoot, 'vendor', 'tiny-essentials');
+  },
+};
+
+/**
+ * Parses a single user input target into resolving segments.
+ *
+ * @param {string} rawTarget - The raw string input from CLI.
+ * @returns {Object} Target descriptors.
+ * @property {number|null} targetVersion - The explicit version if provided.
+ * @property {string} basePath - The relative path requested.
+ * @property {string[]} functionsToExtract - The specific functions to pull via Babel.
+ */
+function parseTarget(rawTarget) {
+  let targetVersion = null;
+  let cleanTarget = rawTarget;
+
+  const versionMatch = rawTarget.match(/^v(\d+)\//);
+  if (versionMatch) {
+    targetVersion = parseInt(versionMatch[1], 10);
+    cleanTarget = rawTarget.replace(versionMatch[0], '');
+  }
+
+  const hasFunctions = cleanTarget.includes(',');
+  let functionsToExtract = [];
+  let basePath = cleanTarget;
+
+  if (hasFunctions) {
+    const parts = cleanTarget.split('/');
+    const lastPart = parts.pop();
+    if (lastPart) {
+      functionsToExtract = lastPart.split(',').map((f) => f.trim());
+      basePath = parts.join('/');
+    }
+  }
+
+  return { targetVersion, basePath, functionsToExtract };
+}
+
+/**
+ * Searches for the requested module file across versions.
+ *
+ * @param {number|null} targetVersion - The optional hardcoded version.
+ * @param {string} basePath - The module path.
+ * @returns {Promise<{ filePath: string, ext: string, versionDir: string, interceptedFunction?: string }>} Resolved file info.
+ */
+async function resolveSourceFile(targetVersion, basePath) {
+  if (basePath.includes('/build/')) {
+    throw new Error('Forbidden extraction: Cannot export files from the build directory.');
+  }
+
+  const extensions = ['.mjs', '.js'];
+  const startVersion = targetVersion || LATEST_VERSION;
+  const endVersion = targetVersion ? targetVersion : 1;
+
+  for (let v = startVersion; v >= endVersion; v--) {
+    const versionDir = path.join(PATHS.cliRoot, 'dist', `v${v}`);
+
+    // If it's a direct file path without functions (which means basePath might be the full path)
+    for (const ext of extensions) {
+      // First attempt: Treating basePath as the exact file (minus extension)
+      const exactPath = path.join(versionDir, `${basePath}${ext}`);
+      if (existsSync(exactPath)) return { filePath: exactPath, ext, versionDir };
+
+      // Second attempt: Checking if the last folder segment in basePath was meant to be functions,
+      // but didn't have commas. (e.g., folder/module/func1)
+      const parts = basePath.split('/');
+      if (parts.length > 1) {
+        const funcNameCandidate = parts.pop();
+        const modulePath = parts.join('/');
+        const nestedPath = path.join(versionDir, `${modulePath}${ext}`);
+
+        if (existsSync(nestedPath)) {
+          // Returns the path, but caller needs to know it intercepted a single function
+          return { filePath: nestedPath, ext, versionDir, interceptedFunction: funcNameCandidate };
+        }
+      }
+    }
+  }
+
+  throw new Error(`Module not found: ${basePath}`);
+}
+
+/**
+ * Advanced Multi-File Dependency Extractor.
+ * Parses files, traces dependencies, and extracts everything mirroring the original structure.
+ */
+class MultiFileExtractor {
+  /**
+   * @param {string} outDir - The base output directory.
+   */
+  constructor(outDir) {
+    this.outDir = outDir;
+    this.fileRequests = new Map();
+    this.processedFiles = new Map();
+  }
+
+  /**
+   * Registers a file and the specific functions needed from it into the extraction queue.
+   *
+   * @param {string} filePath - Absolute path to the file.
+   * @param {string[]} names - Specific exports to keep (empty array means full file).
+   * @param {string} versionDir - The base version directory for structural mirroring.
+   */
+  requestExtraction(filePath, names, versionDir) {
+    if (!this.fileRequests.has(filePath)) {
+      this.fileRequests.set(filePath, { names: new Set(), versionDir, full: false });
+    }
+    const req = this.fileRequests.get(filePath);
+
+    if (names.length === 0) {
+      req.full = true;
+    } else {
+      names.forEach((n) => req.names.add(n));
+    }
+  }
+
+  /**
+   * Resolves local imports relative to the current file.
+   *
+   * @param {string} currentFilePath - The file importing the module.
+   * @param {string} importStr - The import string.
+   * @returns {string|null} Resolved absolute path or null if it's an external package.
+   */
+  resolveImportPath(currentFilePath, importStr) {
+    if (!importStr.startsWith('.')) return null; // Ignore external/node_modules
+
+    const dir = path.dirname(currentFilePath);
+    let resolved = path.resolve(dir, importStr);
+
+    if (!path.extname(resolved)) {
+      for (const ext of ['.mjs', '.js']) {
+        if (existsSync(resolved + ext)) return resolved + ext;
+      }
+    }
+    return resolved;
+  }
+
+  async processQueue() {
+    let processedCount = 0;
+
+    // Use a while loop because tracing dependencies will dynamically add new files to the Map
+    while (processedCount < this.fileRequests.size) {
+      const entries = Array.from(this.fileRequests.entries());
+
+      for (const [filePath, req] of entries) {
+        if (this.processedFiles.has(filePath)) continue;
+
+        const finalCode = await this.parseAndPrune(filePath, req);
+        this.processedFiles.set(filePath, { code: finalCode, versionDir: req.versionDir });
+        processedCount++;
+      }
+    }
+
+    await this.writeFiles();
+  }
+
+  /**
+   * Core AST manipulation: traces required imports and removes unused code.
+   *
+   * @param {string} filePath - Target file path.
+   * @param {Object} req - Request object containing required export names.
+   * @returns {Promise<string>} The minified and formatted generated source code.
+   */
+  async parseAndPrune(filePath, req) {
+    const sourceCode = await fs.readFile(filePath, 'utf-8');
+    const ast = parser.parse(sourceCode, { sourceType: 'module', plugins: ['classProperties'] });
+
+    const localKeepNames = new Set();
+    const requiredImports = new Map();
+
+    // Phase 1: Deep traceability
+    traverse(ast, {
+      Program: (astPath) => {
+        const bindings = astPath.scope.bindings;
+
+        if (req.full) {
+          Object.keys(bindings).forEach((name) => localKeepNames.add(name));
+        }
+
+        const queue = [];
+        const addToKeep = (name) => {
+          if (!localKeepNames.has(name)) {
+            localKeepNames.add(name);
+            queue.push(name);
+          }
+        };
+
+        astPath.traverse({
+          // Tracing Static Methods on any Class
+          ClassDeclaration(classPath) {
+            if (req.full) return;
+            classPath.node.body.body.forEach((item) => {
+              const keyName = t.isIdentifier(item.key) ? item.key.name : null;
+              if (
+                keyName &&
+                item.static &&
+                (t.isClassMethod(item) || t.isClassProperty(item)) &&
+                req.names.has(keyName)
+              ) {
+                traverse(
+                  item,
+                  {
+                    Identifier(idPath) {
+                      if (idPath.isReferencedIdentifier() && bindings[idPath.node.name]) {
+                        addToKeep(idPath.node.name);
+                      }
+                    },
+                  },
+                  astPath.scope,
+                  astPath,
+                );
+              }
+            });
+          },
+          CallExpression(callPath) {
+            if (callPath.node.callee.type === 'Import') {
+              const arg = callPath.node.arguments[0];
+              if (t.isStringLiteral(arg)) {
+                const source = arg.value;
+                if (!requiredImports.has(source)) requiredImports.set(source, new Set());
+                requiredImports.get(source).add({ local: '*', imported: '*' });
+              }
+            }
+          },
+          ImportDeclaration(expPath) {
+            const source = expPath.node.source.value;
+            if (!requiredImports.has(source)) requiredImports.set(source, new Set());
+
+            if (req.full) {
+              if (expPath.node.specifiers.length === 0) {
+                requiredImports.get(source).add({ local: null, imported: null });
+              } else {
+                expPath.node.specifiers.forEach((spec) => {
+                  const importedName = t.isImportDefaultSpecifier(spec)
+                    ? 'default'
+                    : t.isImportNamespaceSpecifier(spec)
+                      ? '*'
+                      : spec.imported.name;
+                  requiredImports
+                    .get(source)
+                    .add({ local: spec.local.name, imported: importedName });
+                });
+              }
+            }
+          },
+          // Catch re-exports (export * from './module')
+          ExportAllDeclaration(expPath) {
+            if (expPath.node.source) {
+              const source = expPath.node.source.value;
+              if (!requiredImports.has(source)) requiredImports.set(source, new Set());
+              // Always request '*' to trace export everything if needed
+              requiredImports.get(source).add({ local: '*', imported: '*', isExportAll: true });
+            }
+          },
+          ExportNamedDeclaration(expPath) {
+            if (expPath.node.source) {
+              // Tracing specific re-exports: export { target } from './module'
+              const source = expPath.node.source.value;
+              if (!requiredImports.has(source)) requiredImports.set(source, new Set());
+
+              expPath.node.specifiers.forEach((spec) => {
+                const exportedName = spec.exported.name;
+                if (req.full || req.names.has(exportedName)) {
+                  const importedName = spec.local ? spec.local.name : exportedName;
+                  requiredImports
+                    .get(source)
+                    .add({ local: null, imported: importedName, isReExport: true, exportedName });
+                }
+              });
+            } else {
+              const dec = expPath.node.declaration;
+              if (dec) {
+                if (t.isFunctionDeclaration(dec) && (req.full || req.names.has(dec.id.name))) {
+                  addToKeep(dec.id.name);
+                } else if (t.isVariableDeclaration(dec)) {
+                  dec.declarations.forEach((d) => {
+                    if (t.isIdentifier(d.id) && (req.full || req.names.has(d.id.name)))
+                      addToKeep(d.id.name);
+                  });
+                }
+              } else if (expPath.node.specifiers) {
+                expPath.node.specifiers.forEach((spec) => {
+                  if (req.full || req.names.has(spec.exported.name)) addToKeep(spec.local.name);
+                });
+              }
+            }
+          },
+          ExportDefaultDeclaration(expPath) {
+            const dec = expPath.node.declaration;
+            if (req.full || req.names.has('default')) {
+              if (t.isIdentifier(dec)) addToKeep(dec.name);
+              else if (dec.id) addToKeep(dec.id.name);
+            }
+          },
+        });
+
+        // Trace local variables and imports inside the queue
+        let i = 0;
+        while (i < queue.length) {
+          const currentName = queue[i++];
+          const binding = bindings[currentName];
+
+          if (binding) {
+            // Namespace Specifier Fix Included!
+            if (
+              binding.path.isImportSpecifier() ||
+              binding.path.isImportDefaultSpecifier() ||
+              binding.path.isImportNamespaceSpecifier()
+            ) {
+              const importDecl = binding.path.parentPath.node;
+              const source = importDecl.source.value;
+              if (!requiredImports.has(source)) requiredImports.set(source, new Set());
+
+              const importedName = binding.path.isImportDefaultSpecifier()
+                ? 'default'
+                : binding.path.isImportNamespaceSpecifier()
+                  ? '*'
+                  : binding.path.node.imported.name;
+              requiredImports.get(source).add({ local: currentName, imported: importedName });
+            } else {
+              binding.path.traverse({
+                Identifier(idPath) {
+                  if (idPath.isReferencedIdentifier() && bindings[idPath.node.name]) {
+                    addToKeep(idPath.node.name);
+                  }
+                },
+              });
+            }
+          }
+        }
+      },
+    });
+
+    // Trigger extraction of all found deep dependencies
+    for (const [source, specs] of requiredImports.entries()) {
+      const resolvedPath = this.resolveImportPath(filePath, source);
+      if (resolvedPath) {
+        // If it's a full export dependency (like side-effect imports or export *), request full extraction
+        const isFullDependency = Array.from(specs).some(
+          (s) => s.imported === null || s.imported === '*',
+        );
+        const importedNamesToRequest = isFullDependency
+          ? []
+          : Array.from(specs).map((s) => s.imported);
+
+        this.requestExtraction(resolvedPath, importedNamesToRequest, req.versionDir);
+      }
+    }
+
+    // Phase 2: Surgical Pruning
+    if (!req.full) {
+      // Helper function to extract Class Methods AND Class Properties natively
+      const extractStaticMethods = (classNode) => {
+        const newNodes = [];
+        classNode.body.body.forEach((item) => {
+          const keyName = t.isIdentifier(item.key) ? item.key.name : null;
+          if (
+            keyName &&
+            item.static &&
+            (t.isClassMethod(item) || t.isClassProperty(item)) &&
+            req.names.has(keyName)
+          ) {
+            if (t.isClassMethod(item)) {
+              const func = t.functionDeclaration(
+                t.identifier(keyName),
+                item.params,
+                item.body,
+                item.generator,
+                item.async,
+              );
+              if (item.leadingComments) func.leadingComments = item.leadingComments;
+              newNodes.push(t.exportNamedDeclaration(func));
+            } else if (t.isClassProperty(item)) {
+              const variableDec = t.variableDeclaration('const', [
+                t.variableDeclarator(t.identifier(keyName), item.value),
+              ]);
+              if (item.leadingComments) variableDec.leadingComments = item.leadingComments;
+              newNodes.push(t.exportNamedDeclaration(variableDec));
+            }
+          }
+        });
+        return newNodes;
+      };
+
+      traverse(ast, {
+        Program(astPath) {
+          const body = astPath.get('body');
+          for (const statement of body) {
+            let keep = false;
+
+            if (statement.isImportDeclaration()) {
+              const source = statement.node.source.value;
+              if (requiredImports.has(source)) {
+                const neededSpecs = requiredImports.get(source);
+                const neededLocalNames = new Set(
+                  Array.from(neededSpecs)
+                    .map((s) => s.local)
+                    .filter(Boolean),
+                );
+
+                if (statement.node.specifiers.length > 0) {
+                  statement.node.specifiers = statement.node.specifiers.filter((spec) =>
+                    neededLocalNames.has(spec.local.name),
+                  );
+                  if (statement.node.specifiers.length > 0) keep = true;
+                }
+              }
+            } else if (statement.isExportNamedDeclaration()) {
+              if (statement.node.source) {
+                const source = statement.node.source.value;
+                if (requiredImports.has(source)) {
+                  const neededSpecs = requiredImports.get(source);
+                  const neededExportedNames = new Set(
+                    Array.from(neededSpecs)
+                      .filter((s) => s.isReExport)
+                      .map((s) => s.exportedName),
+                  );
+
+                  statement.node.specifiers = statement.node.specifiers.filter((spec) =>
+                    neededExportedNames.has(spec.exported.name),
+                  );
+                  if (statement.node.specifiers.length > 0) keep = true;
+                }
+              } else {
+                const dec = statement.get('declaration');
+                if (
+                  dec &&
+                  dec.isFunctionDeclaration() &&
+                  (req.names.has(dec.node.id.name) || localKeepNames.has(dec.node.id.name))
+                ) {
+                  keep = true;
+                } else if (dec && dec.isVariableDeclaration()) {
+                  const keepers = dec.node.declarations.filter(
+                    (d) =>
+                      t.isIdentifier(d.id) &&
+                      (req.names.has(d.id.name) || localKeepNames.has(d.id.name)),
+                  );
+                  if (keepers.length > 0) {
+                    dec.node.declarations = keepers;
+                    keep = true;
+                  }
+                } else if (dec && dec.isClassDeclaration()) {
+                  if (req.names.has(dec.node.id.name) || localKeepNames.has(dec.node.id.name)) {
+                    keep = true;
+                  } else {
+                    const extractedNodes = extractStaticMethods(dec.node);
+                    if (extractedNodes.length > 0) {
+                      statement.replaceWithMultiple(extractedNodes);
+                      keep = true;
+                      continue;
+                    }
+                  }
+                } else if (statement.node.specifiers && statement.node.specifiers.length > 0) {
+                  statement.node.specifiers = statement.node.specifiers.filter(
+                    (spec) =>
+                      req.names.has(spec.exported.name) || localKeepNames.has(spec.local.name),
+                  );
+                  if (statement.node.specifiers.length > 0) keep = true;
+                }
+              }
+            } else if (statement.isExportAllDeclaration()) {
+              const source = statement.node.source.value;
+              if (requiredImports.has(source)) {
+                const neededSpecs = requiredImports.get(source);
+                if (Array.from(neededSpecs).some((s) => s.isExportAll)) keep = true;
+              }
+            } else if (statement.isExportDefaultDeclaration()) {
+              if (req.names.has('default')) {
+                keep = true;
+              } else if (t.isClassDeclaration(statement.node.declaration)) {
+                const extractedNodes = extractStaticMethods(statement.node.declaration);
+                if (extractedNodes.length > 0) {
+                  statement.replaceWithMultiple(extractedNodes);
+                  keep = true;
+                  continue;
+                }
+              }
+            } else if (statement.isClassDeclaration()) {
+              if (localKeepNames.has(statement.node.id.name)) {
+                keep = true;
+              } else {
+                const extractedNodes = extractStaticMethods(statement.node);
+                if (extractedNodes.length > 0) {
+                  statement.replaceWithMultiple(extractedNodes);
+                  keep = true;
+                  continue;
+                }
+              }
+            } else if (
+              statement.isFunctionDeclaration() &&
+              localKeepNames.has(statement.node.id.name)
+            ) {
+              keep = true;
+            } else if (statement.isVariableDeclaration()) {
+              const keepers = statement.node.declarations.filter(
+                (d) => t.isIdentifier(d.id) && localKeepNames.has(d.id.name),
+              );
+              if (keepers.length > 0) {
+                statement.node.declarations = keepers;
+                keep = true;
+              }
+            }
+
+            if (!keep) statement.remove();
+          }
+        },
+      });
+    }
+
+    return generate(ast).code;
+  }
+
+  /**
+   * Flushes processed files mapping onto the filesystem maintaining origin structure.
+   */
+  async writeFiles() {
+    let filesSaved = 0;
+    for (const [filePath, data] of this.processedFiles.entries()) {
+      const relativeToVersion = path.relative(data.versionDir, filePath);
+      const destPath = path.join(this.outDir, relativeToVersion);
+
+      await fs.mkdir(path.dirname(destPath), { recursive: true });
+      await fs.writeFile(destPath, data.code, 'utf-8');
+      console.log(`> Created: ${relativeToVersion}`);
+      filesSaved++;
+    }
+    console.log(`\nSuccessfully orchestrated and bundled ${filesSaved} isolated files!`);
+  }
+}
+
+/**
+ * Main execution function for the CLI tool.
+ */
+async function runCLI() {
+  const args = process.argv.slice(2);
+
+  const outDirArg = args.find((a) => a.startsWith('--out-dir='));
+  const customOutDir = outDirArg ? outDirArg.split('=')[1] : null;
+
+  // Filter out flags to get the raw target strings
+  const rawTargets = args.filter((a) => !a.startsWith('--'));
+
+  if (rawTargets.length === 0) {
+    console.error('Usage: npx tiny-essentials-fork [--out-dir=custom/path] <target1> [target2] ...');
+    console.error('Example: npx tiny-essentials-fork v1/basics/example/func1 v1/lib/TinyHtml');
+    process.exit(1);
+  }
+
+  try {
+    const finalVendorDir = PATHS.getVendorDir(customOutDir);
+    const extractor = new MultiFileExtractor(finalVendorDir);
+
+    for (const rawTarget of rawTargets) {
+      let { targetVersion, basePath, functionsToExtract } = parseTarget(rawTarget);
+      const resolved = await resolveSourceFile(targetVersion, basePath);
+
+      if (resolved.interceptedFunction && functionsToExtract.length === 0) {
+        functionsToExtract.push(resolved.interceptedFunction);
+      }
+
+      extractor.requestExtraction(resolved.filePath, functionsToExtract, resolved.versionDir);
+    }
+
+    console.log(`Starting extraction to: ${finalVendorDir}\n`);
+    await extractor.processQueue();
+  } catch (error) {
+    console.error('\nError extracting modules:');
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+runCLI();

package/changelog/1/26/0.md

@@ -0,0 +1,5 @@
+# 🚀 Introducing TinyFork CLI: The Smart Extractor for Tiny-Essentials! 🍴✨
+
+If you've ever wanted to use just a single function or class from `tiny-essentials` without bringing the entire library into your bundle, this release is for you! TinyFork is a custom, AST-powered tool that deeply scans our JavaScript modules and extracts *exactly* what you ask for. 
+
+It automatically traces and pulls in any required local dependencies, maintains the original `jsDoc` comments, and perfectly mirrors the original folder structure in your project.

package/docs/TinyFork.md

@@ -0,0 +1,89 @@
+# 🍴 TinyFork CLI (BETA)
+
+**The smart, AST-powered tree-shaking extractor for `tiny-essentials`.**
+
+Welcome to TinyFork! This is a friendly command-line interface (CLI) designed to extract specific functions, classes, and modules from the `tiny-essentials` library. Instead of forcing you to bundle the entire library into your project, TinyFork performs a deep Abstract Syntax Tree (AST) analysis to cherry-pick exactly what you need. It automatically resolves and extracts all necessary local dependencies, imports, and jsDocs without bringing in any dead code.
+
+### 📦 Prerequisites
+
+Before running TinyFork, make sure you have the required Babel core packages installed in your project so the AST parsing can work its magic:
+```bash
+npm install @babel/core @babel/parser @babel/traverse @babel/generator @babel/types
+```
+
+## ✨ Key Features
+
+* 🌳 **Deep Tree-Shaking:** Uses `@babel/parser` to deeply trace your code. If you extract one function, TinyFork automatically finds and includes its dependencies (variables, other functions, dynamic imports) while leaving the rest behind.
+* 📁 **Structure Mirroring:** Extracted files are automatically saved maintaining their original folder structure inside your project, preventing naming conflicts and keeping imports clean.
+* 🧩 **Smart Class Extraction:** Can extract static methods from default exported classes and convert them into clean, standalone functions.
+* 🔄 **Version Fallback:** Automatically scans for the requested files starting from the latest version down to `v1`. You can also explicitly request a specific version.
+
+---
+
+## 🚀 Usage
+
+You can run TinyFork directly using `npx` from any project that has `tiny-essentials` installed.
+
+**Basic Syntax:**
+```bash
+npx tiny-essentials-fork [--out-dir=custom/path] <target1> [target2] ...
+```
+
+By default, all files are extracted to: `./vendor/tiny-essentials/` at the root of your project.
+
+---
+
+## 📖 Examples & Capabilities
+
+### 1. Extracting a Full File
+If you want to extract an entire JavaScript module, simply provide the path to the file (without the extension). TinyFork will extract it and automatically trace all of its internal imports!
+
+```bash
+npx tiny-essentials-fork basics/array
+```
+*Result:* Creates `vendor/tiny-essentials/basics/array.mjs` and includes any other internal modules that `array.mjs` depends on.
+
+### 2. Extracting Specific Functions
+To extract only specific exports from a file, append them to the path separated by commas. 
+
+```bash
+npx tiny-essentials-fork basics/array/multiplyArrayBlocks,diffArrayList
+```
+*Result:* Extracts **only** `multiplyArrayBlocks` and `diffArrayList` (and their specific local dependencies) from the `basics/array.mjs` file, discarding all other unused functions.
+
+### 3. Extracting Static Methods from a Class
+If a module exports a default class filled with static methods, you can extract those methods just like regular functions. TinyFork will intelligently detach them from the class and export them as standalone functions!
+
+```bash
+npx tiny-essentials-fork libs/TinyArrayComparator/generateHash
+```
+
+### 4. Extracting Multiple Targets at Once
+You can queue as many targets as you want in a single command. TinyFork will orchestrate the entire extraction, mapping all dependencies together.
+
+```bash
+npx tiny-essentials-fork libs/TinyHtml basics/array/multiplyArrayBlocks libs/TinyArrayComparator/generateHash
+```
+
+### 5. Specifying a Library Version
+If you need a file from a specific version of `tiny-essentials` (e.g., `v1`), prepend the version number to the path. If no version is specified, TinyFork starts searching from the latest version downwards.
+
+```bash
+npx tiny-essentials-fork v1/basics/array/multiplyArrayBlocks
+```
+
+### 6. Using a Custom Output Directory
+Don't want to use the default `vendor/tiny-essentials` folder? Use the `--out-dir` flag to specify your own path.
+
+```bash
+npx tiny-essentials-fork --out-dir=src/assets/tiny-modules basics/array
+```
+
+---
+
+## ⚙️ How it Works Under the Hood
+
+1. **Target Parsing:** TinyFork reads your CLI arguments and resolves the correct file path and version inside the `tiny-essentials/dist` folder.
+2. **Dependency Tracing (Bottom-Up):** Using Babel, it builds an AST of the requested file. It traces all identifiers used by your target functions, finding exactly which local variables and internal imports are required to make them work.
+3. **Surgical Pruning:** It removes all AST nodes (dead code) that are not part of the required trace.
+4. **Formatting & Output:** The optimized AST is generated back into standard JavaScript (preserving your original `jsDoc` comments) and written to your project's file system, perfectly mirroring the original directory structure.

package/docs/v1/README.md

@@ -86,6 +86,14 @@ To get started, navigate to the appropriate directory and explore the files list
 
 ---
 
+## 🍴 TinyFork CLI
+
+Want to extract only specific modules, classes, or functions into your project without carrying the whole library? We built a powerful AST-based CLI specifically for this!
+
+👉 Discover how to use our smart tree-shaking tool by visiting the [**TinyFork CLI Documentation**](../TinyFork.md) for important usage information and commands.
+
+---
+
 ## 📖 More Regex Goodies
 
 Looking for practical regex examples and migration helpers?

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "tiny-essentials",
-  "version": "1.25.6",
+  "version": "1.26.0",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
+  "bin": {
+    "tiny-essentials-fork": "./TinyFork.mjs"
+  },
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",
     "test:js": "npx babel-node test/index.js",
@@ -15,11 +18,12 @@
     "test:mjs:levelup": "node test/index.mjs levelUp",
     "test:mjs:filemanager": "node test/index.mjs fileManager",
     "test:mjs:i18": "node test/index.mjs i18",
-    "fix:prettier": "npm run fix:prettier:src && npm run fix:prettier:test && npm run fix:prettier:rollup.config && npm run fix:prettier:webpack.config",
+    "fix:prettier": "npm run fix:prettier:src && npm run fix:prettier:test && npm run fix:prettier:rollup.config && npm run fix:prettier:webpack.config && npm run fix:prettier:tiny_fork",
     "fix:prettier:src": "prettier --write ./src/*",
     "fix:prettier:test": "prettier --write ./test/*",
     "fix:prettier:rollup.config": "prettier --write ./rollup.config.mjs",
     "fix:prettier:webpack.config": "prettier --write ./webpack.config.mjs",
+    "fix:prettier:tiny_fork": "prettier --write ./TinyFork.mjs",
     "auto-build": "npm run build",
     "build": "npm run build:js && npm run build:css",
     "build:js": "tsc -p tsconfig.json && rollup -c && webpack --mode production",
@@ -493,10 +497,14 @@
   },
   "homepage": "https://github.com/Tiny-Essentials/Tiny-Essentials#readme",
   "devDependencies": {
-    "@babel/cli": "^7.27.0",
-    "@babel/core": "^7.26.10",
-    "@babel/node": "^7.26.0",
-    "@babel/preset-env": "^7.26.9",
+    "@babel/cli": "^7.28.6",
+    "@babel/core": "^7.29.0",
+    "@babel/generator": "^7.29.1",
+    "@babel/node": "^7.29.0",
+    "@babel/parser": "^7.29.2",
+    "@babel/preset-env": "^7.29.2",
+    "@babel/traverse": "^7.29.0",
+    "@babel/types": "^7.29.0",
     "@rollup/plugin-commonjs": "^28.0.3",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.1",