[RFC]: add @stdlib/fs/resolve-parent-paths-by

lib/node_modules/@stdlib/fs/resolve-parent-paths-by.js/README.md

@@ -0,0 +1,120 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2024 The Stdlib Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-->
+
+# resolveParentPathsBy
+
+> Resolve paths from a set of paths by walking parent directories based on a predicate.
+
+## Overview
+
+The `resolveParentPathsBy` function resolves paths from a set of paths by walking parent directories according to a provided predicate. It supports both asynchronous and synchronous operations and allows specifying different modes of resolution.
+
+## Installation
+
+```bash
+npm install @stdlib/fs/resolve-parent-paths-by
+```
+
+## Usage
+
+```var resolveParentPathsBy = require('@stdlib/fs/resolve-parent-paths-by'); ```
+
+### Asynchronous API
+
+```resolveParentPathsBy(paths, options, callback);```
+
+### Example
+
+```
+var opts = {
+    dir: __dirname,
+    mode: 'first'
+};
+
+resolveParentPathsBy([ 'package.json', 'README.md' ], opts, function (error, paths) {
+    if (error) {
+        throw error;
+    }
+    console.log(paths);
+    // Output: ['...', '...']
+});
+```
+
+## Synchronous API
+```var paths = resolveParentPathsBy.sync(paths, options);```
+
+### Example
+
+```
+var opts = {
+    dir: __dirname,
+    mode: 'some'
+};
+
+var paths = resolveParentPathsBy.sync([ 'package.json', 'README.md' ], opts);
+console.log(paths);
+// Output: ['...', '...']
+```
+
+## Options 
+- dir: Base search directory. If not specified, the current working directory is used.
+- mode: Specifies how paths are resolved. Options include first, some, all, and each.
+
+## Notes
+
+- In some mode, the return order of resolved paths is not guaranteed.
+- This implementation performs a search by walking parent directories, which may involve filesystem access, unlike core path.resolve which performs string manipulation.
+
+## Examples
+
+```
+// Sync example
+var opts = {
+    dir: __dirname,
+    mode: 'first'
+};
+var paths = resolveParentPathsBy.sync([ 'package.json', 'README.md' ], opts);
+console.log(paths);
+// Output: ['...']
+
+// Async example
+resolveParentPathsBy([ 'package.json', 'README.md' ], opts, function (error, paths) {
+    if (error) {
+        throw error;
+    }
+    console.log(paths);
+});
+```
+
+## CLI
+### Usage
+
+``` resolve-parent-paths-by [options] <path> [<path>...]```
+
+### Options
+
+- `-h`, `--help`: Print help message.
+- `-V`, `--version`: Print the package version.
+- `--dir dir`: Base search directory.
+- `--mode mode`: Mode of operation.
+
+### Example
+
+```$ resolve-parent-paths-by package.json README.md```