{"_id":"@antonthomzz/travex","name":"@antonthomzz/travex","dist-tags":{"alpha":"0.0.1-alpha.1","latest":"0.0.1-alpha.1"},"versions":{"0.0.1-alpha.1":{"name":"@antonthomzz/travex","version":"0.0.1-alpha.1","description":"Traversal and search utility using regular expressions for structured data","type":"module","main":"init.js","author":{"name":"Anton Thomzz","email":"antonthomzz@gmail.com","url":"https://github.com/Antonthomzz"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Antonthomzz/travex.git"},"bugs":{"url":"https://github.com/Antonthomzz/travex/issues"},"homepage":"https://github.com/Antonthomzz/travex#README.md","keywords":["traverse","traversal","regex","search","object-traversal","data-structure"],"engines":{"node":">=18"},"_id":"@antonthomzz/travex@0.0.1-alpha.1","_nodeVersion":"24.9.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-7OMocsSzfy1r+m/iREevmoMomyhr22Y6RJC9cvbIYpUdEvxEnbTgXJkjRGvMtNo+iIuwU7zqwdkn2IMp9V3Rew==","shasum":"c6c8bc19f9ff3db92e3b883da8cc8904a4dcfa19","tarball":"https://registry.npmjs.org/@antonthomzz/travex/-/travex-0.0.1-alpha.1.tgz","fileCount":12,"unpackedSize":134970,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD90Mxt2nDa6fVAv06rb7zsBU2GmhpVZ2X5st4ywTT0pQIhALDwvCC8/K2iYNVaTwetbxgTIflMgFy5GzfKn2N5+IPI"}]},"_npmUser":{"name":"antonthomzz","email":"antonthomzz@gmail.com"},"directories":{},"maintainers":[{"name":"antonthomzz","email":"antonthomzz@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/travex_0.0.1-alpha.1_1768223370081_0.1926577138850718"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-12T13:09:30.002Z","0.0.1-alpha.1":"2026-01-12T13:09:30.225Z","modified":"2026-01-12T13:09:30.487Z"},"maintainers":[{"name":"antonthomzz","email":"antonthomzz@gmail.com"}],"description":"Traversal and search utility using regular expressions for structured data","homepage":"https://github.com/Antonthomzz/travex#README.md","keywords":["traverse","traversal","regex","search","object-traversal","data-structure"],"repository":{"type":"git","url":"git+https://github.com/Antonthomzz/travex.git"},"author":{"name":"Anton Thomzz","email":"antonthomzz@gmail.com","url":"https://github.com/Antonthomzz"},"bugs":{"url":"https://github.com/Antonthomzz/travex/issues"},"license":"MIT","readme":"# Travex\n<div align=\"center\">\n\n[![NPM Version](https://img.shields.io/npm/v/@antonthomzz/travex?color=brightgreen&label=Version&style=for-the-badge)](https://www.npmjs.com/package/@antonthomzz/travex \"NPM Package\")\n[![NPM Downloads](https://img.shields.io/npm/dm/@antonthomzz/travex?label=Downloads&style=for-the-badge)](https://www.npmjs.com/package/@antonthomzz/travex \"Downloads\")\n[![Donate](https://img.shields.io/badge/-Donate-red.svg?logo=githubsponsors&labelColor=555555&style=for-the-badge)](https://github.com/sponsors/Antonthomzz \"Support Development\")\n\n</div>\n\n## Features\n\n- **Path-Based Traversal**: Navigate nested data using string paths (e.g., `\"user>name\"`) or arrays of paths.\n- **Configurable Options**:\n  - `default`: Specify a fallback value when no data is found.\n  - `fallback`: Define alternative paths to try if the primary path fails.\n  - `flatten`: Flatten nested arrays in the result for simpler output.\n  - `unique`: Remove duplicates from array results.\n  - `limit`: Restrict the number of items in array outputs.\n  - `debug`: Enable debug mode to log traversal details (integrates with external logging).\n  - `Find`: Search for data at a specified path.\n  - `Filter`: Apply a custom function to filter or transform results.\n  - `group`: Select or group results based on an index or logic.\n- **Error Handling**: Validates inputs and configurations, throwing clear errors for invalid JSON, paths, or options.\n- **Flexible Output**: Returns results with a `value` property and additional methods (`Find`, `Filter`, `group`) for further processing.\n\n## Installation\n\n1. Ensure Node.js is installed on your system.\n2. Clone or download the repository containing the traversal tool.\n3. Install dependencies (if any) by running:\n\n```bash\nnpm install @antonthomzz/travex\n```\n4. Include the traversal tool in your project:\n\n```javascript\nimport { (Traverse|Findall|Meta|Decode) } from '@antonthomzz/travex';\n```\n\n### Basic Setup\n\nSet up the tool by defining the input data and traversal path:\n\n```javascript\nimport { Traverse } from '@antonthomzz/travex';\n\nvar result = Traverse(\".value\", {\"data\":{\"name\":{\"value\":\"Anton\"}}})\nconsole.log(result); // Output: \"Anton\"\n```\n\n#### Available Options\n\n- `default`: Specifies a value to return if no data is found at the given path or fallback paths.\n  - Example:\n\n    ```javascript\n    import { Traverse } from '@antonthomzz/travex';\n\n    var result = Traverse('.anton', {}, { default: 'Not found' });\n    console.log(result); // Output: \"Not found\"\n    ```\n- `fallback`: Defines alternative paths (string or array of strings) to try if the primary path yields no result.\n  - Example:\n\n    ```javascript\n    import { Traverse } from '@antonthomzz/travex';\n\n    var result = Traverse('anton', {\"data\":{\"name\":\"Anton\"}}, { fallback: ['tes1', 'data>name'] });\n    console.log(result); // Output: \"Anton\"\n    ```\n- `flatten`: When `true`, flattens nested arrays in the result into a single array.\n  - Example:\n\n    ```javascript\n    import { Traverse } from '@antonthomzz/travex';\n\n    var result = Traverse('list', {\"list\":[[1,2],[3,4]]}, { flatten: true });\n    console.log(result); // Output: [1, 2, 3, 4]\n    ```\n- `unique`: When `true`, removes duplicates from array results using a `Set`.\n  - Example:\n\n    ```javascript\n    import { Traverse } from '@antonthomzz/travex';\n\n    var result = Traverse('items', {\"items\":[1,1,2,2,3]}, { unique: true });\n    console.log(result); // Output: [1, 2, 3]\n    ```\n- `limit`: Restricts the number of items in array results to the specified positive integer.\n  - Example:\n\n    ```javascript\n    import { Traverse } from '@antonthomzz/travex';\n\n    var result = Traverse('numbers', {\"numbers\":[1,2,3,4,5]}, { limit: 3 });\n    console.log(result); // Output: [1, 2, 3]\n    ```\n  - Throws `TypeError` if `limit` is not a positive integer.\n- `debug`: When `true`, enables debug mode to log traversal details (requires external logging setup, e.g., with `TestSuite`).\n  - Example:\n\n    ```javascript\n    import { Traverse } from '@antonthomzz/travex';\n\n    Traverse('data>value', {\"data\":{\"value\":42}}, {\n       debug: true\n    }); // Output: [DEBUG]: Key: \"data>value\" Got: 42\n    ```\n- `find`: search for metadata and then validate it with other data on the surface.\n  - Example:\n\n    ```javascript\n    import { Traverse } from '@antonthomzz/travex';\n\n    var result = Traverse(\"data\", {\"data\":[{\"name\":\"Anton\",\"age\":20},{\"name\":\"Tiara\",\"age\":17}]}, {\n       find: [\"name\", \"age:20\"]\n    });\n    console.log(result); // Output: Anton\n    ```\n- `filter`: Applies a custom function to filter or transform the result. If no function is provided, returns the original result.\n  - Example:\n\n    ```javascript\n    import { Traverse } from '@antonthomzz/travex';\n\n    var result = Traverse(\"num\", {\"num\": 10}, { filter: p => p * 10 });\n    console.log(result); // Output: 100\n    ```\n- `group`: Selects or groups results based on an index (`n`) or logic. If `n` is a positive number, selects the element at index `n-1`. If `n` is 0 or omitted, processes the entire result.\n  - Example:\n\n    ```javascript\n    import { Traverse } from '@antonthomzz/travex';\n\n    var result = Traverse(\"items\", {\"items\":[\"apple\",\"banana\",\"orange\"]}, { group: 2 });\n    console.log(result); // Output: banana\n    ```\n\n### Advanced Usage Examples\n\n- `search_regex`: search data based on `RegExp`\n  ```javascript\n  import { Findall } from '@antonthomzz/travex';\n\n  (async (input) => {\n     var result = await Findall(\"<title>(.*?)<title>\", input);\n     console.log(result); // Output: \"Follow github antonthomzz (https://github.com/Antonthomzz)\"\n  })('<title>Follow github antonthomzz (https://github.com/Antonthomzz)<title>');\n  ```\n\n### Error Handling\n\n- **Invalid Input**: Throws `TypeError` if `input` is not a valid object or JSON string (e.g., `traverse.isObject` or JSON parse errors).\n- **Invalid Path**: Returns `null` or the `default` value if no data is found, with fallback paths attempted if specified.\n- **Invalid Options**: Throws `TypeError` for invalid option values (e.g., non-boolean `flatten`, non-positive integer `limit`).\n- **Empty Data**: Throws `TypeError` (`traverse.data_not_found`) if the traversal path is invalid or empty without a `default` or `fallback`.\n\n## License (MIT)\n\nThis project is licensed under the MIT License. See the `LICENSE` file for details.","readmeFilename":"README.md","_rev":"1-c8461523b8e4b5c53385f281f9d8884d"}