globlin 1.0.0-beta.1

package/index.d.ts

@@ -0,0 +1,399 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/**
+ * Path data returned by glob with withFileTypes: true.
+ * This struct is converted to PathScurry Path objects in the JavaScript wrapper.
+ */
+export interface PathData {
+  /** The path relative to cwd (or absolute if absolute option is set) */
+  path: string
+  /** True if this is a directory */
+  isDirectory: boolean
+  /** True if this is a file */
+  isFile: boolean
+  /** True if this is a symbolic link */
+  isSymlink: boolean
+}
+export declare function globSync(pattern: string | Array<string>, options?: GlobOptions | undefined | null): Array<string>
+export declare function glob(pattern: string | Array<string>, options?: GlobOptions | undefined | null): Promise<Array<string>>
+/**
+ * Synchronous glob pattern matching with file type information.
+ * Returns PathData objects instead of strings.
+ */
+export declare function globSyncWithFileTypes(pattern: string | Array<string>, options?: GlobOptions | undefined | null): Array<PathData>
+/**
+ * Asynchronous glob pattern matching with file type information.
+ * Returns PathData objects instead of strings.
+ */
+export declare function globWithFileTypes(pattern: string | Array<string>, options?: GlobOptions | undefined | null): Promise<Array<PathData>>
+/**
+ * Streaming glob pattern matching.
+ * Streams results back to JavaScript via a callback function.
+ * This reduces peak memory usage for large result sets by not collecting all results before sending.
+ *
+ * @param pattern - Glob pattern or array of patterns
+ * @param options - Glob options
+ * @param callback - Function called with each result string
+ * @returns Promise that resolves when all results have been streamed
+ */
+export declare function globStream(pattern: string | Array<string>, options: GlobOptions | undefined | null, callback: (result: string) => void): void
+/**
+ * Streaming glob pattern matching with file type information.
+ * Streams PathData results back to JavaScript via a callback function.
+ *
+ * @param pattern - Glob pattern or array of patterns
+ * @param options - Glob options
+ * @param callback - Function called with each PathData result
+ * @returns Promise that resolves when all results have been streamed
+ */
+export declare function globStreamWithFileTypes(pattern: string | Array<string>, options: GlobOptions | undefined | null, callback: (result: { path: string, isDirectory: boolean, isFile: boolean, isSymlink: boolean }) => void): void
+/**
+ * Complete GlobOptions struct with all glob v13 options.
+ *
+ * All options are optional and false by default unless otherwise noted.
+ * This struct is designed to be 100% API-compatible with glob v13.0.0.
+ */
+export interface GlobOptions {
+  /**
+   * The current working directory in which to search.
+   * Defaults to `process.cwd()`.
+   *
+   * May be either a string path or a `file://` URL object or string.
+   * URL handling is done in the JavaScript wrapper.
+   */
+  cwd?: string
+  /**
+   * A string path resolved against the `cwd` option, which is used as the
+   * starting point for absolute patterns that start with `/`.
+   *
+   * Note that this doesn't necessarily limit the walk to the `root` directory,
+   * and doesn't affect the cwd starting point for non-absolute patterns.
+   * A pattern containing `..` will still be able to traverse out of the root
+   * directory, if it is not an actual root directory on the filesystem.
+   */
+  root?: string
+  /**
+   * Include `.dot` files in normal matches and `globstar` matches.
+   * Note that an explicit dot in a portion of the pattern will always match dot files.
+   */
+  dot?: boolean
+  /** Do not expand `{a,b}` and `{1..3}` brace sets. */
+  nobrace?: boolean
+  /**
+   * Do not match `**` against multiple filenames.
+   * (Ie, treat it as a normal `*` instead.)
+   *
+   * Conflicts with `matchBase`.
+   */
+  noglobstar?: boolean
+  /** Do not match "extglob" patterns such as `+(a|b)`. */
+  noext?: boolean
+  /**
+   * Perform a case-insensitive match.
+   *
+   * Defaults to `true` on macOS and Windows systems, and `false` on all others.
+   *
+   * **Note:** `nocase` should only be explicitly set when it is known that the
+   * filesystem's case sensitivity differs from the platform default.
+   */
+  nocase?: boolean
+  /**
+   * Treat brace expansion like `{a,b}` as a "magic" pattern.
+   * Has no effect if `nobrace` is set.
+   *
+   * Only affects the `hasMagic` function.
+   */
+  magicalBraces?: boolean
+  /**
+   * Follow symlinked directories when expanding `**` patterns.
+   * This can result in a lot of duplicate references in the presence of
+   * cyclic links, and make performance quite bad.
+   *
+   * By default, a `**` in a pattern will follow 1 symbolic link if it is not
+   * the first item in the pattern, or none if it is the first item in the
+   * pattern, following the same behavior as Bash.
+   */
+  follow?: boolean
+  /**
+   * Limit the directory traversal to a given depth below the cwd.
+   *
+   * - `undefined`/`None`: No limit (traverse all levels)
+   * - `0`: Only the starting directory itself
+   * - `1`: Starting directory and immediate children
+   * - `n`: Up to n levels deep from the starting directory
+   *
+   * Negative values result in empty results.
+   * Note that this does NOT prevent traversal to sibling folders, root patterns,
+   * and so on. It only limits the maximum folder depth that the walk will descend.
+   */
+  maxDepth?: number
+  /**
+   * Perform a basename-only match if the pattern does not contain any slash
+   * characters. That is, a pattern like "*.js" would be treated as equivalent
+   * to a recursive pattern matching all js files in all directories.
+   *
+   * Cannot be used with noglobstar: true.
+   */
+  matchBase?: boolean
+  /**
+   * Set to `true` to always receive absolute paths for matched files.
+   * Set to `false` to always return relative paths.
+   *
+   * When this option is not set, absolute paths are returned for patterns
+   * that are absolute, and otherwise paths are returned that are relative
+   * to the `cwd` setting.
+   *
+   * This does _not_ make an extra system call to get the realpath, it only
+   * does string path resolution.
+   *
+   * Conflicts with `withFileTypes`.
+   */
+  absolute?: boolean
+  /**
+   * Prepend all relative path strings with `./` (or `.\` on Windows).
+   *
+   * Without this option, returned relative paths are "bare", so instead of
+   * returning `'./foo/bar'`, they are returned as `'foo/bar'`.
+   *
+   * Relative patterns starting with `'../'` are not prepended with `./`,
+   * even if this option is set.
+   */
+  dotRelative?: boolean
+  /**
+   * Add a `/` character to directory matches.
+   * Note that this requires additional stat calls in some cases.
+   */
+  mark?: boolean
+  /**
+   * Do not match directories, only files.
+   * (Note: to match _only_ directories, put a `/` at the end of the pattern.)
+   */
+  nodir?: boolean
+  /**
+   * Return `/` delimited paths, even on Windows.
+   *
+   * On posix systems, this has no effect. But, on Windows, it means that
+   * paths will be `/` delimited, and absolute paths will be their full
+   * resolved UNC forms, eg instead of `'C:\oo\ar'`, it would return
+   * `'//?/C:/foo/bar'`
+   */
+  posix?: boolean
+  /**
+   * Return PathScurry `Path` objects instead of strings.
+   * These are similar to a NodeJS `Dirent` object, but with additional
+   * methods and properties.
+   *
+   * Conflicts with `absolute`.
+   *
+   * Note: In globlin, this is handled in the JavaScript wrapper which converts
+   * Rust results to PathScurry objects.
+   */
+  withFileTypes?: boolean
+  /**
+   * Call `lstat()` on all entries, whether required or not to determine
+   * if it's a valid match. When used with `withFileTypes`, this means
+   * that matches will include data such as modified time, permissions, etc.
+   *
+   * Note that this will incur a performance cost due to the added system calls.
+   */
+  stat?: boolean
+  /**
+   * Set to true to call `fs.realpath` on all of the results.
+   * In the case of an entry that cannot be resolved, the entry is omitted.
+   *
+   * This incurs a slight performance penalty due to the added system calls.
+   */
+  realpath?: boolean
+  /**
+   * Patterns to exclude from matching.
+   * Can be a single pattern string or an array of patterns.
+   *
+   * If an object with `ignored(path)` and/or `childrenIgnored(path)` methods
+   * is provided, those methods will be called to determine whether any Path
+   * is a match or if its children should be traversed.
+   *
+   * **Note:** `ignore` patterns are _always_ in `dot:true` mode, regardless
+   * of any other settings.
+   *
+   * Patterns ending in `/**` will ignore the directory and all its children.
+   */
+  ignore?: string | Array<string>
+  /**
+   * Do not match any children of any matches.
+   *
+   * For example, a recursive pattern would match "a/foo" but not "a/foo/b/foo"
+   * in this mode.
+   *
+   * This is especially useful for cases like "find all `node_modules` folders,
+   * but not the ones in `node_modules`".
+   *
+   * Defaults to `true`.
+   */
+  includeChildMatches?: boolean
+  /**
+   * Defaults to value of `process.platform` if available, or `'linux'` if not.
+   *
+   * Setting `platform:'win32'` on non-Windows systems may cause strange behavior.
+   */
+  platform?: string
+  /**
+   * Use `\\` as a path separator _only_, and _never_ as an escape character.
+   * If set, all `\\` characters are replaced with `/` in the pattern.
+   *
+   * Note that this makes it **impossible** to match against paths containing
+   * literal glob pattern characters, but allows matching with patterns
+   * constructed using `path.join()` and `path.resolve()` on Windows platforms.
+   */
+  windowsPathsNoEscape?: boolean
+  /**
+   * Set to false to enable `windowsPathsNoEscape`.
+   *
+   * @deprecated Use `windowsPathsNoEscape` instead.
+   */
+  allowWindowsEscape?: boolean
+  /**
+   * Enable parallel directory walking using multiple threads.
+   *
+   * When `true`, uses parallel traversal which can be faster on:
+   * - Spinning hard drives (HDDs)
+   * - Network filesystems (NFS, CIFS)
+   * - Very large directory trees
+   *
+   * When `false` (default), uses serial traversal which is:
+   * - Faster on SSDs for small to medium directories
+   * - Deterministic result ordering
+   * - Lower memory overhead
+   *
+   * **Note:** This is a globlin-specific option not present in the original glob package.
+   * Results may be returned in a different order when `parallel: true`.
+   */
+  parallel?: boolean
+  /**
+   * Enable directory caching for repeated glob operations.
+   *
+   * When `true`, caches directory listings in memory with a TTL-based invalidation
+   * strategy. This provides significant speedup when:
+   * - Running multiple glob operations on the same directories
+   * - Using the Glob class with cache reuse (passing Glob as options)
+   * - Patterns with overlapping directory prefixes
+   *
+   * When `false` (default), directories are read fresh each time, which is:
+   * - More accurate if the filesystem is changing
+   * - Lower memory usage (no cached directory listings)
+   * - Slightly slower for repeated operations
+   *
+   * The cache has a 5-second TTL to balance freshness with performance.
+   * Use `cache: false` when you expect filesystem changes during the operation.
+   *
+   * **Note:** This is a globlin-specific option not present in the original glob package.
+   */
+  cache?: boolean
+  /**
+   * Use optimized I/O operations on Linux (io_uring/getdents64).
+   *
+   * When `true` on Linux, uses platform-specific optimizations:
+   * - `getdents64` syscall for faster directory reading (bypasses libc overhead)
+   * - Batched I/O operations for reduced syscall overhead
+   * - Expected 1.3-2x speedup on directory-heavy workloads
+   *
+   * When `false` (default), uses the standard `walkdir` library which is:
+   * - Cross-platform compatible
+   * - Well-tested and stable
+   * - Sufficient for most use cases
+   *
+   * On non-Linux platforms, this option is ignored and the standard walker is used.
+   *
+   * **Note:** This is a globlin-specific option not present in the original glob package.
+   * Requires Linux kernel 5.1+ for full io_uring support.
+   */
+  useNativeIO?: boolean
+  /**
+   * Use Grand Central Dispatch (GCD) for parallel walking on macOS.
+   *
+   * When `true` on macOS, uses Apple's Grand Central Dispatch framework for
+   * parallel directory traversal. This provides:
+   * - Native macOS scheduler integration
+   * - Automatic handling of efficiency vs performance cores on Apple Silicon
+   * - Better power management than generic thread pools
+   * - Lower overhead than rayon for I/O-bound workloads
+   *
+   * When `false` (default), uses the standard walker which is often faster
+   * on modern SSDs due to reduced coordination overhead.
+   *
+   * **When to use:**
+   * - Large directory trees (100k+ files) on Macs with many cores
+   * - Network filesystems where I/O latency dominates
+   * - When power efficiency matters (GCD respects system power state)
+   *
+   * **When NOT to use:**
+   * - Small to medium directories on SSD
+   * - When deterministic ordering is required
+   * - On non-macOS platforms (option is ignored)
+   *
+   * **Note:** This is a globlin-specific option not present in the original glob package.
+   */
+  useGcd?: boolean
+}
+/**
+ * Escape magic glob characters in a pattern.
+ * After escaping, the pattern will match literally (no globbing).
+ *
+ * @param pattern - The glob pattern to escape
+ * @param windowsPathsNoEscape - If true, use `[x]` wrapping instead of backslash escapes
+ * @returns The escaped pattern
+ */
+export declare function escape(pattern: string, windowsPathsNoEscape?: boolean | undefined | null): string
+/**
+ * Unescape magic glob characters in a pattern.
+ * This reverses the effect of `escape()`.
+ *
+ * @param pattern - The escaped pattern to unescape
+ * @param windowsPathsNoEscape - If true, remove `[x]` wrapping instead of backslash escapes
+ * @returns The unescaped pattern
+ */
+export declare function unescape(pattern: string, windowsPathsNoEscape?: boolean | undefined | null): string
+/**
+ * Check if a pattern contains any magic glob characters.
+ * Takes into account escaped characters.
+ *
+ * @param pattern - The glob pattern to check
+ * @param options - Options affecting magic detection
+ * @returns True if the pattern has magic (unescaped) glob characters
+ */
+export declare function hasMagic(pattern: string, noext?: boolean | undefined | null, windowsPathsNoEscape?: boolean | undefined | null): boolean
+/**
+ * A pattern warning with message and optional suggestion.
+ * Used for providing helpful feedback about potential pattern issues.
+ */
+export interface PatternWarningInfo {
+  /** The type of warning (e.g., "escaped_wildcard", "performance", "empty") */
+  warningType: string
+  /** Human-readable warning message */
+  message: string
+  /** The original problematic pattern */
+  pattern?: string
+  /** Suggested fix (if applicable) */
+  suggestion?: string
+}
+/**
+ * Analyze a pattern for potential issues and return warnings.
+ * This is useful for providing helpful feedback about common mistakes.
+ *
+ * @param pattern - The glob pattern to analyze
+ * @param windowsPathsNoEscape - Whether backslashes are path separators (Windows mode)
+ * @param platform - The target platform ("win32", "darwin", "linux")
+ * @returns Array of warnings (empty if no issues detected)
+ */
+export declare function analyzePattern(pattern: string, windowsPathsNoEscape?: boolean | undefined | null, platform?: string | undefined | null): Array<PatternWarningInfo>
+/**
+ * Analyze multiple patterns for potential issues and return all warnings.
+ *
+ * @param patterns - Array of glob patterns to analyze
+ * @param windowsPathsNoEscape - Whether backslashes are path separators (Windows mode)
+ * @param platform - The target platform ("win32", "darwin", "linux")
+ * @returns Array of warnings for all patterns (empty if no issues detected)
+ */
+export declare function analyzePatterns(patterns: Array<string>, windowsPathsNoEscape?: boolean | undefined | null, platform?: string | undefined | null): Array<PatternWarningInfo>