Tinyglobby

https://github.com/superchupudev/tinyglobby
Admin
A fast and minimal alternative to globby and fast-glob for file pattern matching with only two...
Tokens:10,069
Snippets:64
Trust Score:8.8
License:MIT
Update:6 days ago
Show doc for...
Tokens:
Raw
### convertPathToPattern no glob symbols example (JavaScript)

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/convertPathToPattern.md

Example showing that when the path has no glob symbols, the pattern is the same as the input path.

```javascript
import { convertPathToPattern } from 'tinyglobby';
convertPathToPattern('src/index.ts'); // 'src/index.ts' — nothing to escape
```

--------------------------------

### Importing tinyglobby modules

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/index.md

Examples of importing the library using both ESM and CommonJS syntax.

```js
// ESM
import { glob, globSync, convertPathToPattern, escapePath, isDynamicPattern } from 'tinyglobby';
import type { GlobOptions, FileSystemAdapter } from 'tinyglobby';

// CommonJS
const { glob, globSync } = require('tinyglobby');
```

--------------------------------

### convertPathToPattern Windows example (JavaScript)

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/convertPathToPattern.md

Example of converting a Windows path with backslashes and a glob symbol. The backslashes are converted to forward slashes, and the `*` is escaped.

```javascript
// windows: 'src/a\\*b/c.ts' → also works when the path contains backslashes
import { convertPathToPattern } from 'tinyglobby';
const winPattern = convertPathToPattern('C:\\src\\a*b\\c.ts');
// C:/src/a\\*b/c.ts  (backslashes became forward slashes)
```

--------------------------------

### Basic glob usage with negation

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/glob.md

Example showing basic usage of `glob` with multiple patterns, including a negated pattern to exclude declaration files. The result is logged to console.

```javascript
import { glob } from 'tinyglobby';

// basic usage — all TypeScript files under src, skipping declarations
const files = await glob(['src/**/*.ts', '!**/*.d.ts'], { cwd: '.' });
console.log(files); // e.g. ['src/index.ts', 'src/crawler.ts', ...]
```

--------------------------------

### convertPathToPattern POSIX example (JavaScript)

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/convertPathToPattern.md

Example of converting a POSIX path with a glob symbol (`*`) to a pattern. The `*` is escaped with a backslash, and the result is shown in a comment.

```javascript
import { convertPathToPattern } from 'tinyglobby';

// POSIX: 'src/a\\*b/c.ts'  →  '/foo/a\\*b/c.ts'
const pattern = convertPathToPattern('/foo/src/a*b/c.ts');
```

--------------------------------

### Glob with absolute paths and timeout

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/glob.md

Example using `glob` with `absolute: true`, `ignore` patterns, and an `AbortSignal.timeout` to cancel after 5 seconds. It demonstrates error handling for abort errors.

```javascript
import { glob } from 'tinyglobby';

// absolute paths with a custom file system adapter
const runner = glob('**/*.json', {
  absolute: true,
  ignore: ['**/node_modules/**'],
  signal: AbortSignal.timeout(5_000)
});

try {
  const results = await runner;
  // results are absolute and start with the resolved cwd
} catch (err) {
  if (isAbortError(err)) {
    console.error('glob timed out');
  }
}
```

--------------------------------

### Basic usage of glob and globSync

Source: https://github.com/superchupudev/tinyglobby/blob/main/README.md

Shows how to import and use the glob and globSync functions from tinyglobby. The glob function is async and accepts an array of patterns with options like cwd, while globSync is synchronous and accepts a single pattern with an ignore option.

```javascript
import { glob, globSync } from 'tinyglobby';

await glob(['files/*.ts', '!**/*.d.ts'], { cwd: 'src' });
globSync('src/**/*.ts', { ignore: '**/*.d.ts' });
```

--------------------------------

### glob(patterns, options?)

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/glob.md

Asynchronously match files following a glob pattern. Accepts a single pattern string or an array of pattern strings, with optional tuning options.

```APIDOC
## glob(patterns, options?)

### Description
Asynchronously match files following a glob pattern. Accepts a single pattern string or an array of pattern strings, with optional tuning options.

### Method
Function

### Signature
```ts
export function glob(patterns: string | readonly string[], options?: Omit<GlobOptions, 'patterns'>): Promise<string[]>;
```

### Parameters
#### patterns (string | readonly string[])
- Required: yes
- Description: Glob pattern(s) to match. Can be a single pattern string (e.g., `'src/**/*.ts'`) or an array of pattern strings (e.g., `['src/**/*.ts', '!**/*.d.ts']`). Negated patterns (`!pattern`) act as ignore patterns, except when `!` is immediately followed by `(` (extglob).

#### options (Omit<GlobOptions, 'patterns'>)
- Required: no
- Description: Tuning options. See configuration.md for defaults. Common options include `cwd`, `absolute`, `ignore`, and `signal`.

### Returns
`Promise<string[]>` resolving to matched paths. By default paths are relative to `options.cwd` with Web-style `/` separators. Set `options.absolute: true` for absolute paths.

### Throws
- `Error: Cannot pass patterns as both an argument and an option` if patterns are provided both as an argument and in `options.patterns`.
- `AbortError` if `options.signal` is aborted while crawling.
- Native `node:fs` errors (e.g., `ENOENT`, `EACCES`) for missing `cwd` or permission issues.

### Example
```js
import { glob } from 'tinyglobby';

// basic usage — all TypeScript files under src, skipping declarations
const files = await glob(['src/**/*.ts', '!**/*.d.ts'], { cwd: '.' });
console.log(files); // e.g. ['src/index.ts', 'src/crawler.ts', ...]
```
```

--------------------------------

### globSync(patterns, options?)

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/globSync.md

Synchronously match files following a glob pattern. Returns an array of matched paths relative to the current working directory unless options.absolute is set. This function does not accept an AbortSignal and never rejects; errors are thrown synchronously.

```APIDOC
## globSync(patterns, options?)

### Description
Synchronously match files following a glob pattern. Returns an array of matched paths relative to the current working directory unless options.absolute is set. This function does not accept an AbortSignal and never rejects; errors are thrown synchronously.

### Method
Function

### Signature
```ts
export function globSync(patterns: string | readonly string[], options?: Omit<GlobOptions, 'patterns'>): string[];
```

### Parameters
#### patterns (string | readonly string[])
- Required: yes
- Description: Glob pattern(s) to match; pass `!pattern` to ignore.

#### options (Omit<GlobOptions, 'patterns'>)
- Required: no
- Description: Tuning options. See configuration for full defaults and semantics.

### Return Value
`string[]` — matched paths, relative to `options.cwd` unless `options.absolute` is set. Empty array (`[]`) if no patterns are provided or nothing matches.

### Throws
| Error | Condition |
|-------|-----------|
| `Error: Cannot pass patterns as both an argument and an option` | both argument + `options.patterns` |
| native `node:fs` errors (`ENOENT`, `EACCES`, …) from crawling | missing `cwd`, permissions, concurrent deletion |
| errors from `options.fs` custom functions | if the adapter's `stat` / `statSync` etc. throw |

### Example
```js
import { globSync } from 'tinyglobby';

const files = globSync(['**/*.ts', '!**/*.d.ts'], { cwd: 'src' });
console.log(files);
// e.g. ['.', './index.ts', './glob.ts', ...] — paths relative to `./src`
```

### Notes
- `deep`, `dot`, `debug`, `absolute`, `onlyFiles`, `caseSensitiveMatch`, `followSymbolicLinks`, `expandDirectories`, `signal`, `fs` → see configuration for full defaults & semantics.
- Result paths use forward slashes regardless of platform (`pathSeparator: '/'`).
- On Windows, returned paths may contain drive-relative prefixes that are normalized by `ensureNonDriveRelativePath`.
- Same deprecation & error behavior as `glob`; the deprecated `GlobOptions.patterns` option throws an error only if combined with a patterns argument.
```

--------------------------------

### convertPathToPattern signatures (TypeScript)

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/convertPathToPattern.md

Shows the type signatures and implementation of `convertPosixPathToPattern`, `convertWin32PathToPattern`, and `convertPathToPattern`. The `convertPathToPattern` is platform-dependent, using the win32 version on Windows and the POSIX version otherwise.

```typescript
// #region convertPathToPattern
const ESCAPED_WIN32_BACKSLASHES = /\\(?![()[\]{}!+@])/g;

export function convertPosixPathToPattern(path: string): string {
  return escapePosixPath(path);
}

export function convertWin32PathToPattern(path: string): string {
  return escapeWin32Path(path).replace(ESCAPED_WIN32_BACKSLASHES, '/');
}

/**
 * Converts a path to a pattern depending on the platform.
 * Identical to {@link escapePath} on POSIX systems.
 * @see {@link https://superchupu.dev/tinyglobby/documentation#convertPathToPattern}
 */
/* node:coverage ignore next 3 */
export const convertPathToPattern: (path: string) => string = isWin
  ? convertWin32PathToPattern
  : convertPosixPathToPattern;
// #endregion
```

```typescript
export const convertPosixPathToPattern = (path: string): string => path.replace(POSIX_UNESCAPED_GLOB_SYMBOLS, '\\$&');
export const convertWin32PathToPattern = (path: string): string =>
  path.replace(WIN32_UNESCAPED_GLOB_SYMBOLS, '\\$&').replace(ESCAPED_WIN32_BACKSLASHES, '/');
```

--------------------------------

### Module dependency graph

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/index.md

Visual representation of the module relationships within the project.

```text
index.ts ──buildCrawler──▶ crawler.ts ──processPatterns──▶ patterns.ts
   │                          │
   ├──◀── utils.ts (BACKSLASHES, ensureStringArray, isReadonlyArray, log)
   │
   └──▶ index.ts re-exports convertPathToPattern, escapePath, isDynamicPattern from utils.ts
```

--------------------------------

### globSync(options) (deprecated)

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/globSync.md

Deprecated signature that accepts an options object containing patterns. This is provided for backward compatibility; use the patterns-first signature instead.

```APIDOC
## globSync(options) (deprecated)

### Description
Deprecated signature that accepts an options object containing patterns. This is provided for backward compatibility; use the patterns-first signature instead.

### Method
Function

### Signature
```ts
/**
 * @deprecated Provide patterns as the first argument instead.
 */
export function globSync(options: GlobOptions): string[];
```

### Parameters
#### options (GlobOptions)
- Required: yes
- Description: Options object carrying `patterns`. The deprecated `GlobOptions.patterns` option is what this signature reads. Passing `patterns` both as an argument and as an option throws.

### Return Value
`string[]` — matched paths, relative to `options.cwd` unless `options.absolute` is set. Empty array (`[]`) if no patterns are provided or nothing matches.

### Throws
| Error | Condition |
|-------|-----------|
| `Error: Cannot pass patterns as both an argument and an option` | both argument + `options.patterns` |
| native `node:fs` errors (`ENOENT`, `EACCES`, …) from crawling | missing `cwd`, permissions, concurrent deletion |
| errors from `options.fs` custom functions | if the adapter's `stat` / `statSync` etc. throw |

### Example
```js
import { globSync } from 'tinyglobby';

const files = globSync({ patterns: ['**/*.ts'], cwd: 'src' });
console.log(files);
```

### Notes
- This signature is deprecated; use the patterns-first signature instead.
- The `signal` option is silently ignored in sync mode; `AbortError` cannot happen.
```

--------------------------------

### Basic globSync usage

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/globSync.md

Matches all TypeScript files in the `src` directory, excluding declaration files. Returns paths relative to `cwd`.

```javascript
import { globSync } from 'tinyglobby';

const files = globSync(['**/*.ts', '!**/*.d.ts'], { cwd: 'src' });
console.log(files);
// e.g. ['.', './index.ts', './glob.ts', ...] — paths relative to `./src`
```

--------------------------------

### glob(options) [deprecated]

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/glob.md

Deprecated overload that accepts a single GlobOptions object. Patterns are read from `options.patterns` and default to `['**/*']` if not provided.

```APIDOC
## glob(options) [deprecated]

### Description
Deprecated overload that accepts a single GlobOptions object. Patterns are read from `options.patterns` and default to `['**/*']` if not provided. Passing `options.patterns` is deprecated; provide patterns as the first argument instead.

### Method
Function

### Signature
```ts
/**
 * @deprecated Provide patterns as the first argument instead.
 */
export function glob(options: GlobOptions): Promise<string[]>;
```

### Parameters
#### options (GlobOptions)
- Required: yes
- Description: An options object that includes `patterns` and other tuning options.

##### options.patterns (string | readonly string[])
- Required: no (defaults to `['**/*']`)
- Description: Glob patterns to match. Passing this property is deprecated.

### Returns
`Promise<string[]>` resolving to matched paths. By default paths are relative to `options.cwd` with Web-style `/` separators. Set `options.absolute: true` for absolute paths.

### Throws
- `Error: Cannot pass patterns as both an argument and an option` if patterns are provided both as an argument and in `options.patterns`.
- `AbortError` if `options.signal` is aborted while crawling.
- Native `node:fs` errors (e.g., `ENOENT`, `EACCES`) for missing `cwd` or permission issues.

### Example
```js
import { glob } from 'tinyglobby';

// deprecated usage — patterns in options
const files = await glob({ patterns: ['src/**/*.ts'], cwd: '.' });
console.log(files);
```
```

--------------------------------

### Error handling with globSync

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/globSync.md

Wraps `globSync` in a try/catch to handle a non-existent `cwd`, checking for `ENOENT` and rethrowing other errors.

```javascript
import { globSync } from 'tinyglobby';

try {
  globSync('**/*', { cwd: '/does/not/exist' });
} catch (err) {
  if (err.code === 'ENOENT') {
    console.error('working directory does not exist:', err.path);
  } else {
    throw err;
  }
}
```

--------------------------------

### Exporting internal utilities and types

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/index.md

Re-exports from the internal utils and types modules as defined in src/index.ts.

```ts
export { convertPathToPattern, escapePath, isDynamicPattern } from './utils.ts';
export type { FileSystemAdapter, GlobOptions } from './types.ts';
```

--------------------------------

### convertPathToPattern

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/index.md

Converts a path to a glob pattern. Re-exported from the utils module.

```APIDOC
## convertPathToPattern

### Description
Converts a path to a glob pattern. Re-exported from the utils module.

### Signature
```ts
export function convertPathToPattern(value: string): string;
```

### Parameters
- **value** (string) - Required - The path to convert.

### Returns
- **string** - The converted glob pattern.

### Example
```js
import { convertPathToPattern } from 'tinyglobby';
const pattern = convertPathToPattern('src/**/*.ts');
```
```

--------------------------------

### Asynchronous glob matching

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/index.md

The glob function signature for asynchronous file matching. The second overload is deprecated.

```ts
export function glob(patterns: string | readonly string[], options?: Omit<GlobOptions, 'patterns'>): Promise<string[]>;
/** @deprecated Provide patterns as the first argument instead. */
export function glob(options: GlobOptions): Promise<string[]>;
export async function glob(globInput: GlobInput, options?: GlobOptions): Promise<string[]> {
  const [crawler, relative] = getCrawler(globInput, options);
  return crawler ? formatPaths(await crawler.withPromise(), relative) : [];
}
```

--------------------------------

### globSync with absolute paths

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/globSync.md

Returns absolute paths for TypeScript files, without following symbolic links and only files (not directories).

```javascript
import { globSync } from 'tinyglobby';

const files = globSync('src/**/*.ts', {
  absolute: true,
  followSymbolicLinks: false,
  onlyDirectories: false
});
// -> ['/abs/path/to/src/index.ts', ...]
```

--------------------------------

### escapePath

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/index.md

Escapes a path for use in a glob pattern. Re-exported from the utils module.

```APIDOC
## escapePath

### Description
Escapes a path for use in a glob pattern. Re-exported from the utils module.

### Signature
```ts
export function escapePath(value: string): string;
```

### Parameters
- **value** (string) - Required - The path to escape.

### Returns
- **string** - The escaped path.

### Example
```js
import { escapePath } from 'tinyglobby';
const escaped = escapePath('path with spaces');
```
```

--------------------------------

### convertPathToPattern(path)

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/convertPathToPattern.md

Converts a path to a glob pattern depending on the current platform, escaping special characters. On POSIX, it is identical to escapePath; on Windows, backslashes are converted to forward slashes.

```APIDOC
## convertPathToPattern(path)

### Description
Converts a filesystem path to a glob pattern, escaping special characters so the path is matched literally. On Windows, backslashes are converted to forward slashes.

### Signature
```ts
export const convertPathToPattern: (path: string) => string;
```

### Parameters
- **path** (string) - Required - A filesystem path. Slashes which already begin the pattern (e.g. `C:\`) are preserved; backslashes on win32 are converted to forward slashes.

### Returns
- **string** - A glob pattern with the same structure as the path, but with glob special characters (`*`, `?`, `[`, `]`, `{`, `}`, `(`, `)`, and `!` at the start, `+`/`@` before `(`) escaped with a backslash.

### Platform-specific behavior
- **POSIX**: result is identical to `escapePath(path)`.
- **win32**: additionally, backslashes left by escaping are converted to forward slashes.

### Examples
```js
import { convertPathToPattern } from 'tinyglobby';

// POSIX: '/foo/src/a*b/c.ts' → '/foo/src/a\*b/c.ts'
const pattern = convertPathToPattern('/foo/src/a*b/c.ts');
```

```js
// Windows: 'C:\src\a*b\c.ts' → 'C:/src/a\*b/c.ts'
import { convertPathToPattern } from 'tinyglobby';
const winPattern = convertPathToPattern('C:\\src\\a*b\\c.ts');
```

```js
// No glob symbols: 'src/index.ts' → 'src/index.ts'
import { convertPathToPattern } from 'tinyglobby';
convertPathToPattern('src/index.ts');
```

### Related
- [`escapePath`](./escapePath.md) — same operation without the win32 slash swap
- [`isDynamicPattern`](./isDynamicPattern.md) — test if a pattern has dynamic parts
- [configuration.md](../configuration.md) — glob matching options
```

--------------------------------

### Synchronous glob matching

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/index.md

The globSync function signature for synchronous file matching. The second overload is deprecated.

```ts
export function globSync(patterns: string | readonly string[], options?: Omit<GlobOptions, 'patterns'>): string[];
/** @deprecated Provide patterns as the first argument instead. */
export function globSync(options: GlobOptions): string[];
export function globSync(globInput: GlobInput, options?: GlobOptions): string[] {
  const [crawler, relative] = getCrawler(globInput, options);
  return crawler ? formatPaths(crawler.sync(), relative) : [];
}
```

--------------------------------

### glob function signature and implementation

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/glob.md

The TypeScript signature and implementation of the `glob` function. It accepts a `GlobInput` (string, array, or deprecated options object) and returns a Promise of string array. The implementation uses `getCrawler` and `formatPaths`.

```typescript
/**
 * Asynchronously match files following a glob pattern.
 * @see {@link https://superchupu.dev/tinyglobby/documentation#glob}
 */
export function glob(patterns: string | readonly string[], options?: Omit<GlobOptions, 'patterns'>): Promise<string[]>;
/**
 * @deprecated Provide patterns as the first argument instead.
 */
export function glob(options: GlobOptions): Promise<string[]>;
export async function glob(globInput: GlobInput, options?: GlobOptions): Promise<string[]> {
  const [crawler, relative] = getCrawler(globInput, options);
  return crawler ? formatPaths(await crawler.withPromise(), relative) : [];
}
```

--------------------------------

### isDynamicPattern

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/index.md

Checks if a pattern is dynamic (contains glob special characters). Re-exported from the utils module.

```APIDOC
## isDynamicPattern

### Description
Checks if a pattern is dynamic (contains glob special characters). Re-exported from the utils module.

### Signature
```ts
export function isDynamicPattern(pattern: string): boolean;
```

### Parameters
- **pattern** (string) - Required - The pattern to check.

### Returns
- **boolean** - True if the pattern is dynamic, false otherwise.

### Example
```js
import { isDynamicPattern } from 'tinyglobby';
const isDynamic = isDynamicPattern('**/*.js');
```
```

--------------------------------

### globSync function signature

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/globSync.md

The TypeScript signature for `globSync`, including the deprecated overload that accepts options with `patterns`. The implementation uses `getCrawler` and `formatPaths`.

```typescript
/**
 * Synchronously match files following a glob pattern.
 * @see {@link https://superchupu.dev/tinyglobby/documentation#globSync}
 */
export function globSync(patterns: string | readonly string[], options?: Omit<GlobOptions, 'patterns'>): string[];
/**
 * @deprecated Provide patterns as the first argument instead.
 */
export function globSync(options: GlobOptions): string[];
export function globSync(globInput: GlobInput, options?: GlobOptions): string[] {
  const [crawler, relative] = getCrawler(globInput, options);
  return crawler ? formatPaths(crawler.sync(), relative) : [];
}
```

--------------------------------

### GlobInput type definition

Source: https://github.com/superchupudev/tinyglobby/blob/main/_autodocs/api-reference/glob.md

The `GlobInput` type is a union of string, readonly string array, or `GlobOptions`. It is used as the first argument to `glob`.

```typescript
export type GlobInput = string | readonly string[] | GlobOptions;
```
Tokens:
Raw