search

Find objects whose key matches a glob (default), regex, substring, or exact pattern. Streams matches as an async iterable, walking every page like listAll, with a glob's literal prefix pushed down automatically.

files.search(pattern, options?)

Find objects whose key matches pattern, walking every page like listAll. It’s a streaming async iterable of StoredFile, so it stays memory-bounded on large buckets and you can break to stop early.

// Glob is the default: `*` stays within a path segment, `?` matches one char.
for await (const file of files.search("avatars/*.png")) {
  console.log(file.key, file.size);
}

// Collect into an array when you want them all at once:
const pdfs = await Array.fromAsync(files.search("invoices/2024/*.pdf"));

Matching is against the caller-facing key, so a client prefix on the instance is already stripped before the pattern is tested.

Glob syntax

"glob" mode uses standard glob semantics, powered by picomatch:

* — any run of characters within a path segment (does not cross /).
** — a globstar segment that spans path segments. Write it as its own segment: photos/**/*.jpg matches at any depth, including zero subfolders.
? — a single non-/ character.
[a-z], {a,b} — character classes and brace alternation.
!pattern — negation (matches everything except).

The pattern is anchored to the whole key, and dotfiles are matched (object keys are opaque, not hidden files). A glob with no wildcards is an exact match, not a substring — files.search("report.pdf") matches the key report.pdf and nothing else. Use match: "substring" for “contains”.

// Every JPEG at any depth under photos/:
for await (const file of files.search("photos/**/*.jpg")) {
  // photos/cover.jpg, photos/2024/spain/beach.jpg, ...
}

Match modes

Pass a match mode to change how a string pattern is interpreted, or pass a RegExp directly (which always matches by regex and ignores match):

// Regular expression (string form):
files.search("\\.(png|jpe?g)$", { match: "regex" });

// ...or a RegExp instance:
files.search(/\.(png|jpe?g)$/);

// Substring — key contains the text anywhere:
files.search("report", { match: "substring" });

// Exact — key equals the text:
files.search("invoices/2024/q1.pdf", { match: "exact" });

// Case-insensitive (any mode):
files.search("*.PNG", { caseInsensitive: true });

An invalid regex pattern throws a FilesError before the walk begins.

Scoping the walk with `prefix`

search reads every page under a prefix, following the cursor. For a glob, the literal head of the pattern is pushed down automatically as that prefix, so files.search("uploads/2024/*.pdf") scopes the walk to the uploads/2024 prefix rather than the whole bucket.

Other modes carry no inferable prefix, so for a regex, substring, or caseInsensitive search over a large bucket, pass prefix yourself to bound the walk:

// Only walk logs/ — then regex-match within it:
files.search("error|panic", { match: "regex", prefix: "logs/" });

A glob’s auto push-down is disabled when caseInsensitive is set (a provider’s prefix filter is case-sensitive), so combine caseInsensitive with an explicit prefix to scope it.

Stopping early

maxResults caps the number of matches yielded; because the walk is lazy, it also stops paging once the cap is hit. Equivalently, break out of the loop.

// First 10 matches, then stop fetching pages:
const recent = await Array.fromAsync(
  files.search("**/*.log", { maxResults: 10 })
);

Provider support

search runs on every adapter, since it’s built on listAll — there’s no per-provider search capability and nothing to gate. The two listAll caveats carry over: on Netlify Blobs omit limit to walk everything, and the non-recursive Box / OneDrive / SharePoint adapters only see the immediate children of the root folder. An unbounded search with no prefix walks the whole bucket by design.

Options

PropType

prefix?string

Restrict the underlying walk to keys starting with this prefix. For a glob pattern a literal prefix is inferred automatically (`uploads/2024/*.pdf` walks only the `uploads/2024` prefix); set this explicitly to bound a `regex`, `substring`, or `caseInsensitive` search — which have no inferable prefix — to part of a large bucket. Composes with the {@link Files} instance `prefix` exactly like {@link ListOptions.prefix}.

Typestring

limit?number

Page size for each underlying `list()` call — the walk's batch size, not a cap on results. See {@link ListOptions.limit}.

Typenumber

maxResults?number

Stop after yielding this many matches. Omit to yield every match (the walk still pages lazily, so memory stays bounded).

Typenumber

match?SearchMatch

How to interpret a string `pattern`. Defaults to `"glob"`. Ignored when `pattern` is a `RegExp`.

TypeSearchMatch

caseInsensitive?boolean

Match case-insensitively. Adds the `i` flag for `glob` and `regex` and lowercases both sides for `substring` and `exact`. A `RegExp` that already sets its own `i` flag is honored regardless. When set, the automatic glob prefix push-down is disabled (a provider prefix filter is case-sensitive), so pass an explicit `prefix` to bound a case-insensitive search. Defaults to `false`.

Typeboolean

signal?AbortSignal

Abort the operation when this signal is aborted. When both constructor and per-call signals are provided, either one can abort the call.

TypeAbortSignal

timeout?number

Overall timeout in milliseconds, applied to each attempt. A timeout aborts the operation and is not retried. `0` or a negative value disables timeout handling.

Typenumber

retries?RetryOptions

Retry provider failures. A number is treated as `{ max: number }`.

TypeRetryOptions

The match mode is one of:

PropType

toString() => string

Returns a string representation of a string.

Type() => string

charAt(pos: number) => string

Returns the character at the specified index.

Type(pos: number) => string

charCodeAt(index: number) => number

Returns the Unicode value of the character at the specified location.

Type(index: number) => number

concat(...strings: string[]) => string

Returns a string that contains the concatenation of two or more strings.

Type(...strings: string[]) => string

indexOf(searchString: string, position?: number | undefined) => number

Returns the position of the first occurrence of a substring, or -1 if it is not present.

Type(searchString: string, position?: number | undefined) => number

lastIndexOf(searchString: string, position?: number | undefined) => number

Returns the last occurrence of a substring in the string, or -1 if it is not present.

Type(searchString: string, position?: number | undefined) => number

localeCompare

{ (that: string): number; (that: string, locales?: string | string[] | undefined, options?: CollatorOptions | undefined): number; (that: string, locales?: LocalesArgument, options?: CollatorOptions | undefined): number; }

Determines whether two strings are equivalent in the current locale. Determines whether two strings are equivalent in the current or specified locale.

Type

{ (that: string): number; (that: string, locales?: string | string[] | undefined, options?: CollatorOptions | undefined): number; (that: string, locales?: LocalesArgument, options?: CollatorOptions | undefined): number; }

match

{ (regexp: string | RegExp): RegExpMatchArray | null; (matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null; }

Matches a string with a regular expression, and returns an array containing the results of that search. Matches a string or an object that supports being matched against, and returns an array containing the results of that search, or null if no matches are found.

Type

{ (regexp: string | RegExp): RegExpMatchArray | null; (matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null; }

replace

{ (searchValue: string | RegExp, replaceValue: string): string; (searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string; (searchValue: { ...; }, replaceValue: string): string; (searchValue: { ...; }, replacer: (substring: string, ...args: any[]) => string): string; }

Replaces text in a string, using a regular expression or search string. Passes a string and {@linkcode replaceValue} to the `[Symbol.replace]` method on {@linkcode searchValue}. This method is expected to implement its own replacement algorithm. Replaces text in a string, using an object that supports replacement within a string.

Type

{ (searchValue: string | RegExp, replaceValue: string): string; (searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string; (searchValue: { ...; }, replaceValue: string): string; (searchValue: { ...; }, replacer: (substring: string, ...args: any[]) => string): string; }

search{ (regexp: string | RegExp): number; (searcher: { [Symbol.search](string: string): number; }): number; }

Finds the first substring match in a regular expression search.

Type{ (regexp: string | RegExp): number; (searcher: { [Symbol.search](string: string): number; }): number; }

slice(start?: number | undefined, end?: number | undefined) => string

Returns a section of a string.

Type(start?: number | undefined, end?: number | undefined) => string

split

{ (separator: string | RegExp, limit?: number | undefined): string[]; (splitter: { [Symbol.split](string: string, limit?: number | undefined): string[]; }, limit?: number | undefined): string[]; }

Split a string into substrings using the specified separator and return them as an array.

Type

{ (separator: string | RegExp, limit?: number | undefined): string[]; (splitter: { [Symbol.split](string: string, limit?: number | undefined): string[]; }, limit?: number | undefined): string[]; }

substring(start: number, end?: number | undefined) => string

Returns the substring at the specified location within a String object.

Type(start: number, end?: number | undefined) => string

toLowerCase() => string

Converts all the alphabetic characters in a string to lowercase.

Type() => string

toLocaleLowerCase{ (locales?: string | string[] | undefined): string; (locales?: LocalesArgument): string; }

Converts all alphabetic characters to lowercase, taking into account the host environment's current locale.

Type{ (locales?: string | string[] | undefined): string; (locales?: LocalesArgument): string; }

toUpperCase() => string

Converts all the alphabetic characters in a string to uppercase.

Type() => string

toLocaleUpperCase{ (locales?: string | string[] | undefined): string; (locales?: LocalesArgument): string; }

Returns a string where all alphabetic characters have been converted to uppercase, taking into account the host environment's current locale.

Type{ (locales?: string | string[] | undefined): string; (locales?: LocalesArgument): string; }

trim() => string

Removes the leading and trailing white space and line terminator characters from a string.

Type() => string

lengthpping t

Returns the length of a String object.

Typepping t

substr(from: number, length?: number | undefined) => string

Gets a substring beginning at the specified location and having the specified length.

Type(from: number, length?: number | undefined) => string

valueOf() => string

Returns the primitive value of the specified object.

Type() => string

codePointAt(pos: number) => number | undefined

Returns a nonnegative integer Number less than 1114112 (0x110000) that is the code point value of the UTF-16 encoded code point starting at the string element at position pos in the String resulting from converting this object to a String. If there is no element at that position, the result is undefined. If a valid UTF-16 surrogate pair does not begin at pos, the result is the code unit at pos.

Type(pos: number) => number | undefined

includes(searchString: string, position?: number | undefined) => boolean

Returns true if searchString appears as a substring of the result of converting this object to a String, at one or more positions that are greater than or equal to position; otherwise, returns false.

Type(searchString: string, position?: number | undefined) => boolean

endsWith(searchString: string, endPosition?: number | undefined) => boolean

Returns true if the sequence of elements of searchString converted to a String is the same as the corresponding elements of this object (converted to a String) starting at endPosition – length(this). Otherwise returns false.

Type(searchString: string, endPosition?: number | undefined) => boolean

normalize{ (form: "NFC" | "NFD" | "NFKC" | "NFKD"): string; (form?: string | undefined): string; }

Returns the String value result of normalizing the string into the normalization form named by form as specified in Unicode Standard Annex #15, Unicode Normalization Forms.

Type{ (form: "NFC" | "NFD" | "NFKC" | "NFKD"): string; (form?: string | undefined): string; }

repeat(count: number) => string

Returns a String value that is made from count copies appended together. If count is 0, the empty string is returned.

Type(count: number) => string

startsWith(searchString: string, position?: number | undefined) => boolean

Returns true if the sequence of elements of searchString converted to a String is the same as the corresponding elements of this object (converted to a String) starting at position. Otherwise returns false.

Type(searchString: string, position?: number | undefined) => boolean

anchor(name: string) => string

Returns an `<a>` HTML anchor element and sets the name attribute to the text value

Type(name: string) => string

big() => string

Returns a `<big>` HTML element

Type() => string

blink() => string

Returns a `<blink>` HTML element

Type() => string

bold() => string

Returns a `` HTML element

Type() => string

fixed() => string

Returns a `<tt>` HTML element

Type() => string

fontcolor(color: string) => string

Returns a `` HTML element and sets the color attribute value

Type(color: string) => string

fontsize{ (size: number): string; (size: string): string; }

Returns a `` HTML element and sets the size attribute value

Type{ (size: number): string; (size: string): string; }

italics() => string

Returns an `` HTML element

Type() => string

link(url: string) => string

Returns an `<a>` HTML element and sets the href attribute value

Type(url: string) => string

small() => string

Returns a `` HTML element

Type() => string

strike() => string

Returns a `<strike>` HTML element

Type() => string

sub() => string

Returns a `` HTML element

Type() => string

sup() => string

Returns a `` HTML element

Type() => string

padStart(maxLength: number, fillString?: string | undefined) => string

Pads the current string with a given string (possibly repeated) so that the resulting string reaches a given length. The padding is applied from the start (left) of the current string.

Type(maxLength: number, fillString?: string | undefined) => string

padEnd(maxLength: number, fillString?: string | undefined) => string

Pads the current string with a given string (possibly repeated) so that the resulting string reaches a given length. The padding is applied from the end (right) of the current string.

Type(maxLength: number, fillString?: string | undefined) => string

trimEnd() => string

Removes the trailing white space and line terminator characters from a string.

Type() => string

trimStart() => string

Removes the leading white space and line terminator characters from a string.

Type() => string

trimLeft() => string

Removes the leading white space and line terminator characters from a string.

Type() => string

trimRight() => string

Removes the trailing white space and line terminator characters from a string.

Type() => string

matchAll(regexp: RegExp) => RegExpStringIterator<RegExpExecArray>

Matches a string with a regular expression, and returns an iterable of matches containing the results of that search.

Type(regexp: RegExp) => RegExpStringIterator<RegExpExecArray>

replaceAll

{ (searchValue: string | RegExp, replaceValue: string): string; (searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string; }

Replace all instances of a substring in a string, using a regular expression or search string.

Type

{ (searchValue: string | RegExp, replaceValue: string): string; (searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string; }

at(index: number) => string | undefined

Returns a new String consisting of the single UTF-16 code unit located at the specified index.

Type(index: number) => string | undefined

isWellFormed() => boolean

Returns true if all leading surrogates and trailing surrogates appear paired and in order.

Type() => boolean

toWellFormed() => string

Returns a string where all lone or out-of-order surrogates have been replaced by the Unicode replacement character (U+FFFD).

Type() => string

__@iterator@1034() => StringIterator<string>

Iterator

Type() => StringIterator<string>

search

Glob syntax

Match modes

Scoping the walk with prefix

Stopping early

Provider support

Options

Scoping the walk with `prefix`