index.d.ts 3.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137
  1. import {Options as LocatePathOptions} from 'locate-path';
  2. declare const stop: unique symbol;
  3. declare namespace findUp {
  4. interface Options extends LocatePathOptions {}
  5. type StopSymbol = typeof stop;
  6. type Match = string | StopSymbol | undefined;
  7. }
  8. declare const findUp: {
  9. /**
  10. Find a file or directory by walking up parent directories.
  11. @param name - Name of the file or directory to find. Can be multiple.
  12. @returns The first path found (by respecting the order of `name`s) or `undefined` if none could be found.
  13. @example
  14. ```
  15. // /
  16. // └── Users
  17. // └── sindresorhus
  18. // ├── unicorn.png
  19. // └── foo
  20. // └── bar
  21. // ├── baz
  22. // └── example.js
  23. // example.js
  24. import findUp = require('find-up');
  25. (async () => {
  26. console.log(await findUp('unicorn.png'));
  27. //=> '/Users/sindresorhus/unicorn.png'
  28. console.log(await findUp(['rainbow.png', 'unicorn.png']));
  29. //=> '/Users/sindresorhus/unicorn.png'
  30. })();
  31. ```
  32. */
  33. (name: string | string[], options?: findUp.Options): Promise<string | undefined>;
  34. /**
  35. Find a file or directory by walking up parent directories.
  36. @param matcher - Called for each directory in the search. Return a path or `findUp.stop` to stop the search.
  37. @returns The first path found or `undefined` if none could be found.
  38. @example
  39. ```
  40. import path = require('path');
  41. import findUp = require('find-up');
  42. (async () => {
  43. console.log(await findUp(async directory => {
  44. const hasUnicorns = await findUp.exists(path.join(directory, 'unicorn.png'));
  45. return hasUnicorns && directory;
  46. }, {type: 'directory'}));
  47. //=> '/Users/sindresorhus'
  48. })();
  49. ```
  50. */
  51. (matcher: (directory: string) => (findUp.Match | Promise<findUp.Match>), options?: findUp.Options): Promise<string | undefined>;
  52. sync: {
  53. /**
  54. Synchronously find a file or directory by walking up parent directories.
  55. @param name - Name of the file or directory to find. Can be multiple.
  56. @returns The first path found (by respecting the order of `name`s) or `undefined` if none could be found.
  57. */
  58. (name: string | string[], options?: findUp.Options): string | undefined;
  59. /**
  60. Synchronously find a file or directory by walking up parent directories.
  61. @param matcher - Called for each directory in the search. Return a path or `findUp.stop` to stop the search.
  62. @returns The first path found or `undefined` if none could be found.
  63. @example
  64. ```
  65. import path = require('path');
  66. import findUp = require('find-up');
  67. console.log(findUp.sync(directory => {
  68. const hasUnicorns = findUp.sync.exists(path.join(directory, 'unicorn.png'));
  69. return hasUnicorns && directory;
  70. }, {type: 'directory'}));
  71. //=> '/Users/sindresorhus'
  72. ```
  73. */
  74. (matcher: (directory: string) => findUp.Match, options?: findUp.Options): string | undefined;
  75. /**
  76. Synchronously check if a path exists.
  77. @param path - Path to the file or directory.
  78. @returns Whether the path exists.
  79. @example
  80. ```
  81. import findUp = require('find-up');
  82. console.log(findUp.sync.exists('/Users/sindresorhus/unicorn.png'));
  83. //=> true
  84. ```
  85. */
  86. exists(path: string): boolean;
  87. }
  88. /**
  89. Check if a path exists.
  90. @param path - Path to a file or directory.
  91. @returns Whether the path exists.
  92. @example
  93. ```
  94. import findUp = require('find-up');
  95. (async () => {
  96. console.log(await findUp.exists('/Users/sindresorhus/unicorn.png'));
  97. //=> true
  98. })();
  99. ```
  100. */
  101. exists(path: string): Promise<boolean>;
  102. /**
  103. Return this in a `matcher` function to stop the search and force `findUp` to immediately return `undefined`.
  104. */
  105. readonly stop: findUp.StopSymbol;
  106. };
  107. export = findUp;