Search.ts overview

Bounded filename and content search over an explicit immutable snapshot.

Search grants the snapshot's authority, without caller permission filtering. Paths are exact UTF-8 strings relative to the selected directory root. Hidden names are included, discovered symlinks are not followed, and hard-link names are searched independently. Glob never reads or copies file contents.

Since v0.8.0

defaults

defaultLimits

Finite default work policy. Byte limits use exact ByteSize values.

Defaults are 100,000 entries, depth 256, 4 KiB paths, 100 rows, 64 KiB result payload, 4 KiB per pattern, 128 pattern sources, 64 KiB aggregate sources, 1,024 expanded alternatives, 65,536 compiled tokens, and 10 million matching operations. Content defaults are 64 MiB scanned bytes, 1 MiB per file, 100,000 line evaluations and 1 KiB excerpts. Glob performs no content work. These bounds do not promise a deadline or measure JavaScript heap or serialized JSON size.

Signature

declare const defaultLimits: {
  readonly maxEntries: number
  readonly maxDepth: number
  readonly maxPathBytes: ByteSize.ByteSize
  readonly maxResults: number
  readonly maxResultBytes: ByteSize.ByteSize
  readonly maxPatternBytes: ByteSize.ByteSize
  readonly maxPatterns: number
  readonly maxPatternListBytes: ByteSize.ByteSize
  readonly maxExpansions: number
  readonly maxTokens: number
  readonly maxMatchingWork: number
  readonly maxScannedBytes: ByteSize.ByteSize
  readonly maxFileBytes: ByteSize.ByteSize
  readonly maxLineEvaluations: number
  readonly maxExcerptBytes: ByteSize.ByteSize
}

Source

Since v0.8.0

errors

BudgetExceeded (class)

Typed runtime budget exhaustion.

Signature

declare class BudgetExceeded

Source

Since v0.8.0

ContentFailure (type alias)

Typed query, pattern-compilation and snapshot failures for content collectors.

Signature

type ContentFailure = QueryFailure | FsFailure | ImageFailure

Source

Since v0.8.0

GlobFailure (type alias)

Query and snapshot failures preserved by collectors.

Signature

type GlobFailure = QueryFailure | FsFailure | ImageFailure

Source

Since v0.8.0

QueryFailure (class)

Invalid query, pattern syntax or aggregate compilation limit.

Signature

declare class QueryFailure

Source

Since v0.8.0

ScanContentFailure (type alias)

Content Stream failures, including budget exhaustion after earlier rows.

Signature

type ScanContentFailure = ContentFailure | BudgetExceeded

Source

Since v0.8.0

ScanGlobFailure (type alias)

Stream failures, including exhaustion after earlier rows.

Signature

type ScanGlobFailure = GlobFailure | BudgetExceeded

Source

Since v0.8.0

models

Completion (type alias)

Query completion with an actual stopping bound.

Signature

export type Completion =
  | { readonly _tag: "Complete" }
  | {
      readonly _tag: "Stopped"
      readonly limit:
        | "maxEntries"
        | "maxDepth"
        | "maxPathBytes"
        | "maxResults"
        | "maxResultBytes"
        | "maxPatternBytes"
        | "maxPatterns"
        | "maxPatternListBytes"
        | "maxExpansions"
        | "maxTokens"
        | "maxMatchingWork"
        | "maxScannedBytes"
        | "maxFileBytes"
        | "maxLineEvaluations"
        | "maxExcerptBytes"
      readonly path?: string
    }

Source

Since v0.8.0

ContentQuery (type alias)

Validated snapshot content query.

Signature

export type ContentQuery = {
  readonly root: string | BytePath
  readonly include: readonly [string, ...string[]]
  readonly pattern:
    | { readonly _tag: "Literal"; readonly pattern: string }
    | { readonly _tag: "Regex"; readonly pattern: string }
  readonly exclude?: readonly string[]
  readonly limits?: {
    readonly maxEntries?: number
    readonly maxDepth?: number
    readonly maxPathBytes?: ByteSize.ByteSize
    readonly maxResults?: number
    readonly maxResultBytes?: ByteSize.ByteSize
    readonly maxPatternBytes?: ByteSize.ByteSize
    readonly maxPatterns?: number
    readonly maxPatternListBytes?: ByteSize.ByteSize
    readonly maxExpansions?: number
    readonly maxTokens?: number
    readonly maxMatchingWork?: number
    readonly maxScannedBytes?: ByteSize.ByteSize
    readonly maxFileBytes?: ByteSize.ByteSize
    readonly maxLineEvaluations?: number
    readonly maxExcerptBytes?: ByteSize.ByteSize
  }
  readonly ignoreCase?: boolean
}

Source

Since v0.8.0

CountLinesReport (type alias)

Bounded snapshot content report.

Signature

export type CountLinesReport = {
  readonly root: string | BytePath
  readonly results: readonly { readonly path: string; readonly count: number }[]
  readonly work: {
    readonly entries: number
    readonly matchingWork: number
    readonly resultBytes: ByteSize.ByteSize
    readonly scannedBytes: ByteSize.ByteSize
    readonly lineEvaluations: number
  }
  readonly skips: {
    readonly invalidNames: number
    readonly invalidNameSubtrees: number
    readonly oversizedFiles: number
    readonly invalidUtf8Files: number
    readonly binaryFiles: number
  }
  readonly completion:
    | { readonly _tag: "Complete" }
    | {
        readonly _tag: "Stopped"
        readonly limit:
          | "maxEntries"
          | "maxDepth"
          | "maxPathBytes"
          | "maxResults"
          | "maxResultBytes"
          | "maxPatternBytes"
          | "maxPatterns"
          | "maxPatternListBytes"
          | "maxExpansions"
          | "maxTokens"
          | "maxMatchingWork"
          | "maxScannedBytes"
          | "maxFileBytes"
          | "maxLineEvaluations"
          | "maxExcerptBytes"
        readonly path?: string
      }
}

Source

Since v0.8.0

CountResult (type alias)

One completed file matching-line count.

Signature

export type CountResult = { readonly path: string; readonly count: number }

Source

Since v0.8.0

Excerpt (type alias)

Bounded excerpt of one matching line.

Signature

export type Excerpt = { readonly text: string; readonly start: number; readonly truncated: boolean }

Source

Since v0.8.0

FilesReport (type alias)

Bounded snapshot content report.

Signature

export type FilesReport = {
  readonly root: string | BytePath
  readonly results: readonly string[]
  readonly work: {
    readonly entries: number
    readonly matchingWork: number
    readonly resultBytes: ByteSize.ByteSize
    readonly scannedBytes: ByteSize.ByteSize
    readonly lineEvaluations: number
  }
  readonly skips: {
    readonly invalidNames: number
    readonly invalidNameSubtrees: number
    readonly oversizedFiles: number
    readonly invalidUtf8Files: number
    readonly binaryFiles: number
  }
  readonly completion:
    | { readonly _tag: "Complete" }
    | {
        readonly _tag: "Stopped"
        readonly limit:
          | "maxEntries"
          | "maxDepth"
          | "maxPathBytes"
          | "maxResults"
          | "maxResultBytes"
          | "maxPatternBytes"
          | "maxPatterns"
          | "maxPatternListBytes"
          | "maxExpansions"
          | "maxTokens"
          | "maxMatchingWork"
          | "maxScannedBytes"
          | "maxFileBytes"
          | "maxLineEvaluations"
          | "maxExcerptBytes"
        readonly path?: string
      }
}

Source

Since v0.8.0

GlobQuery (type alias)

Filename query decoded by GlobQuery.

Signature

export type GlobQuery = {
  readonly root: string | BytePath
  readonly include: readonly [string, ...string[]]
  readonly exclude?: readonly string[]
  readonly kinds?: readonly ("file" | "directory" | "symlink")[]
  readonly limits?: {
    readonly maxEntries?: number
    readonly maxDepth?: number
    readonly maxPathBytes?: ByteSize.ByteSize
    readonly maxResults?: number
    readonly maxResultBytes?: ByteSize.ByteSize
    readonly maxPatternBytes?: ByteSize.ByteSize
    readonly maxPatterns?: number
    readonly maxPatternListBytes?: ByteSize.ByteSize
    readonly maxExpansions?: number
    readonly maxTokens?: number
    readonly maxMatchingWork?: number
    readonly maxScannedBytes?: ByteSize.ByteSize
    readonly maxFileBytes?: ByteSize.ByteSize
    readonly maxLineEvaluations?: number
    readonly maxExcerptBytes?: ByteSize.ByteSize
  }
}

Source

Since v0.8.0

GlobReport (type alias)

A selected root, preceding results, counters and completion.

Signature

export type GlobReport = {
  readonly root: string | BytePath
  readonly results: readonly string[]
  readonly work: {
    readonly entries: number
    readonly matchingWork: number
    readonly resultBytes: ByteSize.ByteSize
    readonly scannedBytes: ByteSize.ByteSize
    readonly lineEvaluations: number
  }
  readonly skips: {
    readonly invalidNames: number
    readonly invalidNameSubtrees: number
    readonly oversizedFiles: number
    readonly invalidUtf8Files: number
    readonly binaryFiles: number
  }
  readonly completion:
    | { readonly _tag: "Complete" }
    | {
        readonly _tag: "Stopped"
        readonly limit:
          | "maxEntries"
          | "maxDepth"
          | "maxPathBytes"
          | "maxResults"
          | "maxResultBytes"
          | "maxPatternBytes"
          | "maxPatterns"
          | "maxPatternListBytes"
          | "maxExpansions"
          | "maxTokens"
          | "maxMatchingWork"
          | "maxScannedBytes"
          | "maxFileBytes"
          | "maxLineEvaluations"
          | "maxExcerptBytes"
        readonly path?: string
      }
}

Source

Since v0.8.0

Kind (type alias)

Entry kinds selected by filename queries.

Signature

export type Kind = "file" | "directory" | "symlink"

Source

Since v0.8.0

Limit (type alias)

Names of compiler, traversal, output and content bounds.

Signature

export type Limit =
  | "maxEntries"
  | "maxDepth"
  | "maxPathBytes"
  | "maxResults"
  | "maxResultBytes"
  | "maxPatternBytes"
  | "maxPatterns"
  | "maxPatternListBytes"
  | "maxExpansions"
  | "maxTokens"
  | "maxMatchingWork"
  | "maxScannedBytes"
  | "maxFileBytes"
  | "maxLineEvaluations"
  | "maxExcerptBytes"

Source

Since v0.8.0

LimitOverrides (type alias)

Optional overrides applied to default limits.

Signature

export type LimitOverrides = {
  readonly maxEntries?: number
  readonly maxDepth?: number
  readonly maxPathBytes?: ByteSize.ByteSize
  readonly maxResults?: number
  readonly maxResultBytes?: ByteSize.ByteSize
  readonly maxPatternBytes?: ByteSize.ByteSize
  readonly maxPatterns?: number
  readonly maxPatternListBytes?: ByteSize.ByteSize
  readonly maxExpansions?: number
  readonly maxTokens?: number
  readonly maxMatchingWork?: number
  readonly maxScannedBytes?: ByteSize.ByteSize
  readonly maxFileBytes?: ByteSize.ByteSize
  readonly maxLineEvaluations?: number
  readonly maxExcerptBytes?: ByteSize.ByteSize
}

Source

Since v0.8.0

Limits (type alias)

Complete finite search limits.

Signature

export type Limits = {
  readonly maxEntries: number
  readonly maxDepth: number
  readonly maxPathBytes: ByteSize.ByteSize
  readonly maxResults: number
  readonly maxResultBytes: ByteSize.ByteSize
  readonly maxPatternBytes: ByteSize.ByteSize
  readonly maxPatterns: number
  readonly maxPatternListBytes: ByteSize.ByteSize
  readonly maxExpansions: number
  readonly maxTokens: number
  readonly maxMatchingWork: number
  readonly maxScannedBytes: ByteSize.ByteSize
  readonly maxFileBytes: ByteSize.ByteSize
  readonly maxLineEvaluations: number
  readonly maxExcerptBytes: ByteSize.ByteSize
}

Source

Since v0.8.0

LineResult (type alias)

One matching line result.

Signature

export type LineResult = {
  readonly path: string
  readonly lineNumber: number
  readonly range: { readonly start: number; readonly end: number }
  readonly excerpt: { readonly text: string; readonly start: number; readonly truncated: boolean }
}

Source

Since v0.8.0

LinesReport (type alias)

Bounded snapshot content report.

Signature

export type LinesReport = {
  readonly root: string | BytePath
  readonly results: readonly {
    readonly path: string
    readonly lineNumber: number
    readonly range: { readonly start: number; readonly end: number }
    readonly excerpt: { readonly text: string; readonly start: number; readonly truncated: boolean }
  }[]
  readonly work: {
    readonly entries: number
    readonly matchingWork: number
    readonly resultBytes: ByteSize.ByteSize
    readonly scannedBytes: ByteSize.ByteSize
    readonly lineEvaluations: number
  }
  readonly skips: {
    readonly invalidNames: number
    readonly invalidNameSubtrees: number
    readonly oversizedFiles: number
    readonly invalidUtf8Files: number
    readonly binaryFiles: number
  }
  readonly completion:
    | { readonly _tag: "Complete" }
    | {
        readonly _tag: "Stopped"
        readonly limit:
          | "maxEntries"
          | "maxDepth"
          | "maxPathBytes"
          | "maxResults"
          | "maxResultBytes"
          | "maxPatternBytes"
          | "maxPatterns"
          | "maxPatternListBytes"
          | "maxExpansions"
          | "maxTokens"
          | "maxMatchingWork"
          | "maxScannedBytes"
          | "maxFileBytes"
          | "maxLineEvaluations"
          | "maxExcerptBytes"
        readonly path?: string
      }
}

Source

Since v0.8.0

MatchRange (type alias)

First whole-match byte range.

Signature

export type MatchRange = { readonly start: number; readonly end: number }

Source

Since v0.8.0

Pattern (type alias)

Explicit literal or native regex content pattern.

Signature

export type Pattern =
  | { readonly _tag: "Literal"; readonly pattern: string }
  | { readonly _tag: "Regex"; readonly pattern: string }

Source

Since v0.8.0

Skips (type alias)

Counted policy skips.

Signature

export type Skips = {
  readonly invalidNames: number
  readonly invalidNameSubtrees: number
  readonly oversizedFiles: number
  readonly invalidUtf8Files: number
  readonly binaryFiles: number
}

Source

Since v0.8.0

Work (type alias)

Work counts, with exact raw UTF-8 result bytes.

Signature

export type Work = {
  readonly entries: number
  readonly matchingWork: number
  readonly resultBytes: ByteSize.ByteSize
  readonly scannedBytes: ByteSize.ByteSize
  readonly lineEvaluations: number
}

Source

Since v0.8.0

operations

countLines

Collect exact per-file matching-line counts with work, skips and completion. A stopped or skipped query's summed counts are lower bounds for its original scope. Raw result accounting is UTF-8 path bytes plus 8 bytes per count; scalar metadata is excluded, as in the other content modes.

Signature

declare const countLines: {
  (query: ContentQuery): (snapshot: Snapshot) => Effect.Effect<CountLinesReport, ContentFailure>
  (snapshot: Snapshot, query: ContentQuery): Effect.Effect<CountLinesReport, ContentFailure>
}

Source

Since v0.8.0

files

Collect matching filenames with preceding rows, work, skips and completion. Shares text classification and matching with lines, but evaluates only as far as the first hit in each classified file. Raw result bytes count paths only; scanned bytes still charge the full selected file before classification.

Signature

declare const files: {
  (query: ContentQuery): (snapshot: Snapshot) => Effect.Effect<FilesReport, ContentFailure>
  (snapshot: Snapshot, query: ContentQuery): Effect.Effect<FilesReport, ContentFailure>
}

Source

Since v0.8.0

glob

Collect bounded matches and preserve preceding rows when a work or output budget stops the query. Invalid queries, malformed patterns and snapshot failures remain typed failures; interruption remains interruption.

Reaching the row cap always reports Stopped, even for the last possible result. Invalid UTF-8 names are counted skips, and invalid-name directories count one skipped subtree without examining its descendants.

Example

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { Search, VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
const program = Effect.gen(function* () {
  const volume = yield* Vfs.fromFixture({
    entries: [
      { kind: "file", path: "/a.ts", bytes: new Uint8Array() },
      { kind: "file", path: "/b.ts", bytes: new Uint8Array() }
    ]
  })
  return yield* Search.glob(yield* volume.snapshot, {
    root: "/",
    include: ["*.ts"],
    limits: { maxResults: 1 }
  })
})
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then((report) => {
  console.log(report.results, report.completion._tag)
})
// [ "a.ts" ] Stopped

Signature

declare const glob: {
  (query: GlobQuery): (snapshot: Snapshot) => Effect.Effect<GlobReport, GlobFailure>
  (snapshot: Snapshot, query: GlobQuery): Effect.Effect<GlobReport, GlobFailure>
}

Source

Since v0.8.0

lines

Collect matching lines, preceding rows, skips, work and completion. Catch only budget exhaustion; query, pattern and snapshot failures remain typed failures, and interruption propagates. Reaching the result cap reports Stopped with no lookahead, even for the last possible result.

Raw row bytes are UTF-8 path and excerpt bytes plus 16 bytes for the range. Scalar metadata is excluded; this is not heap or serialized JSON accounting. Complete classification charges full eligible file bytes, including skips and repeated hard-link scans. Empty files have no lines.

Signature

declare const lines: {
  (query: ContentQuery): (snapshot: Snapshot) => Effect.Effect<LinesReport, ContentFailure>
  (snapshot: Snapshot, query: ContentQuery): Effect.Effect<LinesReport, ContentFailure>
}

Source

Since v0.8.0

scanCountLines

Stream exact matching-line counts for completely scanned matching files. Multiple occurrences on one line count once. A stopped file emits no partial count; earlier completed rows can precede a budget failure. Builds no line ranges or excerpts. Use countLines when coverage information matters.

Signature

declare const scanCountLines: {
  (query: ContentQuery): (snapshot: Snapshot) => Stream.Stream<CountResult, ScanContentFailure>
  (snapshot: Snapshot, query: ContentQuery): Stream.Stream<CountResult, ScanContentFailure>
}

Source

Since v0.8.0

scanFiles

Stream one root-relative filename per matching regular-file path. Classify the complete file before testing lines and stop matching after the first hit. Build no line-result ranges or excerpts. Budget exhaustion fails the Stream; use files for coverage and skip counters.

Signature

declare const scanFiles: {
  (query: ContentQuery): (snapshot: Snapshot) => Stream.Stream<string, ScanContentFailure>
  (snapshot: Snapshot, query: ContentQuery): Stream.Stream<string, ScanContentFailure>
}

Source

Since v0.8.0

scanGlob

Stream ordinary root-relative strings in depth-first preorder, with each directory sorted by raw name bytes. Resolve the root through directory symlinks; never follow discovered symlinks or emit the root itself.

A budget failure may follow earlier rows. Taking a prefix establishes no completion. Use glob when skip counts or coverage matter. Each evaluation owns fresh traversal and counters, including repeated or concurrent runs.

Example

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { Search, VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect, Stream } from "effect"
 
const program = Effect.gen(function* () {
  const volume = yield* Vfs.fromFixture({ entries: [{ kind: "file", path: "/😀.ts", bytes: new Uint8Array() }] })
  const snapshot = yield* volume.snapshot
  return yield* Stream.runCollect(Search.scanGlob(snapshot, { root: "/", include: ["?.ts"] }))
})
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ '😀.ts' ]

Signature

declare const scanGlob: {
  (query: GlobQuery): (snapshot: Snapshot) => Stream.Stream<string, ScanGlobFailure>
  (snapshot: Snapshot, query: GlobQuery): Stream.Stream<string, ScanGlobFailure>
}

Source

Since v0.8.0

scanLines

Stream one result per matching line after classifying the complete file for strict UTF-8 and NUL. Each row contains the first whole-match byte range and a UTF-8-bounded excerpt beginning at the match. Files and hard-link names are selected independently; invalid, binary and oversized files are skipped.

A budget failure can follow earlier rows. A prefix establishes no completion; use lines for coverage and skip counters. Each evaluation owns fresh state. Native regex can block within one call; Effect timeouts cannot preempt it.

Example

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { Search, VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect, Stream } from "effect"
 
const program = Effect.gen(function* () {
  const volume = yield* Vfs.fromFixture({
    entries: [{ kind: "file", path: "/note", bytes: new TextEncoder().encode("😀TODO\n") }]
  })
  return yield* Stream.runCollect(
    Search.scanLines(yield* volume.snapshot, {
      root: "/",
      include: ["**"],
      pattern: Search.Pattern.cases.Literal.make({ pattern: "TODO" })
    })
  )
})
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then((rows) => {
  console.log(rows[0]?.range)
})
// { start: 4, end: 8 }

Signature

declare const scanLines: {
  (query: ContentQuery): (snapshot: Snapshot) => Stream.Stream<LineResult, ScanContentFailure>
  (snapshot: Snapshot, query: ContentQuery): Stream.Stream<LineResult, ScanContentFailure>
}

Source

Since v0.8.0

schemas

Completion

Complete exhausts the eligible namespace, possibly with skips. Stopped names the exhausted bound and a root-relative path when representable. The empty string identifies the selected root. Stopping does not assert that another matching entry exists.

Signature

declare const Completion: Schema.Union<
  readonly [
    Schema.TaggedStruct<"Complete", {}>,
    Schema.TaggedStruct<
      "Stopped",
      {
        readonly limit: Schema.Literals<
          readonly [
            "maxEntries",
            "maxDepth",
            "maxPathBytes",
            "maxResults",
            "maxResultBytes",
            "maxPatternBytes",
            "maxPatterns",
            "maxPatternListBytes",
            "maxExpansions",
            "maxTokens",
            "maxMatchingWork",
            "maxScannedBytes",
            "maxFileBytes",
            "maxLineEvaluations",
            "maxExcerptBytes"
          ]
        >
        readonly path: Schema.optionalKey<Schema.String>
      }
    >
  ]
>

Source

Since v0.8.0

ContentQuery

Regular-file content selection using the same case-sensitive filename globs as GlobQuery. Content ignoreCase defaults to false and never affects filenames.

Signature

declare const ContentQuery: Schema.Struct<{
  readonly root: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>
  readonly include: Schema.NonEmptyArray<Schema.String>
  readonly exclude: Schema.optionalKey<Schema.$Array<Schema.String>>
  readonly pattern: Schema.TaggedUnion<{
    readonly Literal: Schema.TaggedStruct<"Literal", { readonly pattern: Schema.NonEmptyString }>
    readonly Regex: Schema.TaggedStruct<"Regex", { readonly pattern: Schema.String }>
  }>
  readonly ignoreCase: Schema.optionalKey<Schema.Boolean>
  readonly limits: Schema.optionalKey<
    Schema.Struct<{
      readonly maxEntries: Schema.optionalKey<Schema.Natural>
      readonly maxDepth: Schema.optionalKey<Schema.Natural>
      readonly maxPathBytes: Schema.optionalKey<Schema.ByteSize>
      readonly maxResults: Schema.optionalKey<Schema.Natural>
      readonly maxResultBytes: Schema.optionalKey<Schema.ByteSize>
      readonly maxPatternBytes: Schema.optionalKey<Schema.ByteSize>
      readonly maxPatterns: Schema.optionalKey<Schema.Natural>
      readonly maxPatternListBytes: Schema.optionalKey<Schema.ByteSize>
      readonly maxExpansions: Schema.optionalKey<Schema.Natural>
      readonly maxTokens: Schema.optionalKey<Schema.Natural>
      readonly maxMatchingWork: Schema.optionalKey<Schema.Natural>
      readonly maxScannedBytes: Schema.optionalKey<Schema.ByteSize>
      readonly maxFileBytes: Schema.optionalKey<Schema.ByteSize>
      readonly maxLineEvaluations: Schema.optionalKey<Schema.Natural>
      readonly maxExcerptBytes: Schema.optionalKey<Schema.ByteSize>
    }>
  >
}>

Source

Since v0.8.0

CountLinesReport

Preceding completed-file counts with coverage, work and skips. Complete covers eligible content and can still contain skips. Stopped or skipped query totals are lower bounds for the original scope.

Signature

declare const CountLinesReport: Schema.Struct<{
  readonly root: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>
  readonly results: Schema.$Array<Schema.Struct<{ readonly path: Schema.String; readonly count: Schema.Int }>>
  readonly work: Schema.Struct<{
    readonly entries: Schema.Natural
    readonly matchingWork: Schema.Natural
    readonly resultBytes: Schema.ByteSize
    readonly scannedBytes: Schema.ByteSize
    readonly lineEvaluations: Schema.Natural
  }>
  readonly skips: Schema.Struct<{
    readonly invalidNames: Schema.Natural
    readonly invalidNameSubtrees: Schema.Natural
    readonly oversizedFiles: Schema.Natural
    readonly invalidUtf8Files: Schema.Natural
    readonly binaryFiles: Schema.Natural
  }>
  readonly completion: Schema.Union<
    readonly [
      Schema.TaggedStruct<"Complete", {}>,
      Schema.TaggedStruct<
        "Stopped",
        {
          readonly limit: Schema.Literals<
            readonly [
              "maxEntries",
              "maxDepth",
              "maxPathBytes",
              "maxResults",
              "maxResultBytes",
              "maxPatternBytes",
              "maxPatterns",
              "maxPatternListBytes",
              "maxExpansions",
              "maxTokens",
              "maxMatchingWork",
              "maxScannedBytes",
              "maxFileBytes",
              "maxLineEvaluations",
              "maxExcerptBytes"
            ]
          >
          readonly path: Schema.optionalKey<Schema.String>
        }
      >
    ]
  >
}>

Source

Since v0.8.0

CountResult

Exact matching-line count for one completely scanned matching file. This counts lines, not occurrences. Incomplete files never produce a count row.

Signature

declare const CountResult: Schema.Struct<{ readonly path: Schema.String; readonly count: Schema.Int }>

Source

Since v0.8.0

Excerpt

UTF-8-bounded text beginning at the match, with its original file-byte start. truncated is true when any line prefix or suffix is omitted. The full match range can extend beyond this text. A zero-width end match can have empty text.

Signature

declare const Excerpt: Schema.Struct<{
  readonly text: Schema.String
  readonly start: Schema.Natural
  readonly truncated: Schema.Boolean
}>

Source

Since v0.8.0

FilesReport

Preceding matching filenames with coverage, work and skips. Complete covers eligible content and can still contain skips. Stopped or skipped query totals are lower bounds for the original scope.

Signature

declare const FilesReport: Schema.Struct<{
  readonly root: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>
  readonly results: Schema.$Array<Schema.String>
  readonly work: Schema.Struct<{
    readonly entries: Schema.Natural
    readonly matchingWork: Schema.Natural
    readonly resultBytes: Schema.ByteSize
    readonly scannedBytes: Schema.ByteSize
    readonly lineEvaluations: Schema.Natural
  }>
  readonly skips: Schema.Struct<{
    readonly invalidNames: Schema.Natural
    readonly invalidNameSubtrees: Schema.Natural
    readonly oversizedFiles: Schema.Natural
    readonly invalidUtf8Files: Schema.Natural
    readonly binaryFiles: Schema.Natural
  }>
  readonly completion: Schema.Union<
    readonly [
      Schema.TaggedStruct<"Complete", {}>,
      Schema.TaggedStruct<
        "Stopped",
        {
          readonly limit: Schema.Literals<
            readonly [
              "maxEntries",
              "maxDepth",
              "maxPathBytes",
              "maxResults",
              "maxResultBytes",
              "maxPatternBytes",
              "maxPatterns",
              "maxPatternListBytes",
              "maxExpansions",
              "maxTokens",
              "maxMatchingWork",
              "maxScannedBytes",
              "maxFileBytes",
              "maxLineEvaluations",
              "maxExcerptBytes"
            ]
          >
          readonly path: Schema.optionalKey<Schema.String>
        }
      >
    ]
  >
}>

Source

Since v0.8.0

GlobQuery

An explicit directory root, nonempty include list and optional exclusions, kinds and limits. All patterns are root-relative and case-sensitive.

Wildcards and classes match Unicode code points without normalization. Supports *, ?, classes, comma brace alternatives, whole-segment **, backslash escapes, and a directory-only trailing slash. Excluded directories prune traversal. Include selectors and kind filters do not prune directories.

Signature

declare const GlobQuery: Schema.Struct<{
  readonly root: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>
  readonly include: Schema.NonEmptyArray<Schema.String>
  readonly exclude: Schema.optionalKey<Schema.$Array<Schema.String>>
  readonly kinds: Schema.optionalKey<Schema.$Array<Schema.Literals<readonly ["file", "directory", "symlink"]>>>
  readonly limits: Schema.optionalKey<
    Schema.Struct<{
      readonly maxEntries: Schema.optionalKey<Schema.Natural>
      readonly maxDepth: Schema.optionalKey<Schema.Natural>
      readonly maxPathBytes: Schema.optionalKey<Schema.ByteSize>
      readonly maxResults: Schema.optionalKey<Schema.Natural>
      readonly maxResultBytes: Schema.optionalKey<Schema.ByteSize>
      readonly maxPatternBytes: Schema.optionalKey<Schema.ByteSize>
      readonly maxPatterns: Schema.optionalKey<Schema.Natural>
      readonly maxPatternListBytes: Schema.optionalKey<Schema.ByteSize>
      readonly maxExpansions: Schema.optionalKey<Schema.Natural>
      readonly maxTokens: Schema.optionalKey<Schema.Natural>
      readonly maxMatchingWork: Schema.optionalKey<Schema.Natural>
      readonly maxScannedBytes: Schema.optionalKey<Schema.ByteSize>
      readonly maxFileBytes: Schema.optionalKey<Schema.ByteSize>
      readonly maxLineEvaluations: Schema.optionalKey<Schema.Natural>
      readonly maxExcerptBytes: Schema.optionalKey<Schema.ByteSize>
    }>
  >
}>

Source

Since v0.8.0

GlobReport

A selected root, preceding results, counters and completion.

Signature

declare const GlobReport: Schema.Struct<{
  readonly root: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>
  readonly results: Schema.$Array<Schema.String>
  readonly work: Schema.Struct<{
    readonly entries: Schema.Natural
    readonly matchingWork: Schema.Natural
    readonly resultBytes: Schema.ByteSize
    readonly scannedBytes: Schema.ByteSize
    readonly lineEvaluations: Schema.Natural
  }>
  readonly skips: Schema.Struct<{
    readonly invalidNames: Schema.Natural
    readonly invalidNameSubtrees: Schema.Natural
    readonly oversizedFiles: Schema.Natural
    readonly invalidUtf8Files: Schema.Natural
    readonly binaryFiles: Schema.Natural
  }>
  readonly completion: Schema.Union<
    readonly [
      Schema.TaggedStruct<"Complete", {}>,
      Schema.TaggedStruct<
        "Stopped",
        {
          readonly limit: Schema.Literals<
            readonly [
              "maxEntries",
              "maxDepth",
              "maxPathBytes",
              "maxResults",
              "maxResultBytes",
              "maxPatternBytes",
              "maxPatterns",
              "maxPatternListBytes",
              "maxExpansions",
              "maxTokens",
              "maxMatchingWork",
              "maxScannedBytes",
              "maxFileBytes",
              "maxLineEvaluations",
              "maxExcerptBytes"
            ]
          >
          readonly path: Schema.optionalKey<Schema.String>
        }
      >
    ]
  >
}>

Source

Since v0.8.0

Kind

Entry kinds selected by filename queries.

Signature

declare const Kind: Schema.Literals<readonly ["file", "directory", "symlink"]>

Source

Since v0.8.0

Limit

Names of compiler, traversal, output and content bounds.

Signature

declare const Limit: Schema.Literals<
  readonly [
    "maxEntries",
    "maxDepth",
    "maxPathBytes",
    "maxResults",
    "maxResultBytes",
    "maxPatternBytes",
    "maxPatterns",
    "maxPatternListBytes",
    "maxExpansions",
    "maxTokens",
    "maxMatchingWork",
    "maxScannedBytes",
    "maxFileBytes",
    "maxLineEvaluations",
    "maxExcerptBytes"
  ]
>

Source

Since v0.8.0

LimitOverrides

Optional overrides applied to default limits.

Signature

declare const LimitOverrides: Schema.Struct<{
  readonly maxEntries: Schema.optionalKey<Schema.Natural>
  readonly maxDepth: Schema.optionalKey<Schema.Natural>
  readonly maxPathBytes: Schema.optionalKey<Schema.ByteSize>
  readonly maxResults: Schema.optionalKey<Schema.Natural>
  readonly maxResultBytes: Schema.optionalKey<Schema.ByteSize>
  readonly maxPatternBytes: Schema.optionalKey<Schema.ByteSize>
  readonly maxPatterns: Schema.optionalKey<Schema.Natural>
  readonly maxPatternListBytes: Schema.optionalKey<Schema.ByteSize>
  readonly maxExpansions: Schema.optionalKey<Schema.Natural>
  readonly maxTokens: Schema.optionalKey<Schema.Natural>
  readonly maxMatchingWork: Schema.optionalKey<Schema.Natural>
  readonly maxScannedBytes: Schema.optionalKey<Schema.ByteSize>
  readonly maxFileBytes: Schema.optionalKey<Schema.ByteSize>
  readonly maxLineEvaluations: Schema.optionalKey<Schema.Natural>
  readonly maxExcerptBytes: Schema.optionalKey<Schema.ByteSize>
}>

Source

Since v0.8.0

Limits

Complete finite namespace, matching, content and output limits.

Signature

declare const Limits: Schema.Struct<{
  maxEntries: Schema.Natural
  maxDepth: Schema.Natural
  maxPathBytes: Schema.ByteSize
  maxResults: Schema.Natural
  maxResultBytes: Schema.ByteSize
  maxPatternBytes: Schema.ByteSize
  maxPatterns: Schema.Natural
  maxPatternListBytes: Schema.ByteSize
  maxExpansions: Schema.Natural
  maxTokens: Schema.Natural
  maxMatchingWork: Schema.Natural
  maxScannedBytes: Schema.ByteSize
  maxFileBytes: Schema.ByteSize
  maxLineEvaluations: Schema.Natural
  maxExcerptBytes: Schema.ByteSize
}>

Source

Since v0.8.0

LineResult

One matching line, its first whole match and bounded excerpt. Line numbers are 1-based; paths are root-relative. LF separates lines, CR is stripped only before LF, BOM and lone CR are preserved, and a final LF adds no synthetic empty line.

Signature

declare const LineResult: Schema.Struct<{
  readonly path: Schema.String
  readonly lineNumber: Schema.Int
  readonly range: Schema.Struct<{ readonly start: Schema.Natural; readonly end: Schema.Natural }>
  readonly excerpt: Schema.Struct<{
    readonly text: Schema.String
    readonly start: Schema.Natural
    readonly truncated: Schema.Boolean
  }>
}>

Source

Since v0.8.0

LinesReport

Preceding line matches with coverage, work and skips. Complete covers eligible content and can still contain skips. Stopped or skipped query totals are lower bounds for the original scope.

Signature

declare const LinesReport: Schema.Struct<{
  readonly root: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>
  readonly results: Schema.$Array<
    Schema.Struct<{
      readonly path: Schema.String
      readonly lineNumber: Schema.Int
      readonly range: Schema.Struct<{ readonly start: Schema.Natural; readonly end: Schema.Natural }>
      readonly excerpt: Schema.Struct<{
        readonly text: Schema.String
        readonly start: Schema.Natural
        readonly truncated: Schema.Boolean
      }>
    }>
  >
  readonly work: Schema.Struct<{
    readonly entries: Schema.Natural
    readonly matchingWork: Schema.Natural
    readonly resultBytes: Schema.ByteSize
    readonly scannedBytes: Schema.ByteSize
    readonly lineEvaluations: Schema.Natural
  }>
  readonly skips: Schema.Struct<{
    readonly invalidNames: Schema.Natural
    readonly invalidNameSubtrees: Schema.Natural
    readonly oversizedFiles: Schema.Natural
    readonly invalidUtf8Files: Schema.Natural
    readonly binaryFiles: Schema.Natural
  }>
  readonly completion: Schema.Union<
    readonly [
      Schema.TaggedStruct<"Complete", {}>,
      Schema.TaggedStruct<
        "Stopped",
        {
          readonly limit: Schema.Literals<
            readonly [
              "maxEntries",
              "maxDepth",
              "maxPathBytes",
              "maxResults",
              "maxResultBytes",
              "maxPatternBytes",
              "maxPatterns",
              "maxPatternListBytes",
              "maxExpansions",
              "maxTokens",
              "maxMatchingWork",
              "maxScannedBytes",
              "maxFileBytes",
              "maxLineEvaluations",
              "maxExcerptBytes"
            ]
          >
          readonly path: Schema.optionalKey<Schema.String>
        }
      >
    ]
  >
}>

Source

Since v0.8.0

MatchRange

Half-open, file-absolute UTF-8 byte offsets. These are safe integers, not UTF-16 indices or character columns.

Signature

declare const MatchRange: Schema.Struct<{ readonly start: Schema.Natural; readonly end: Schema.Natural }>

Source

Since v0.8.0

Pattern

Explicit content interpretation. Literal strings never become regex implicitly.

Signature

declare const Pattern: Schema.TaggedUnion<{
  readonly Literal: Schema.TaggedStruct<"Literal", { readonly pattern: Schema.NonEmptyString }>
  readonly Regex: Schema.TaggedStruct<"Regex", { readonly pattern: Schema.String }>
}>

Source

Since v0.8.0

Skips

Counted policy skips. Descendants of skipped directories are not estimated.

Signature

declare const Skips: Schema.Struct<{
  readonly invalidNames: Schema.Natural
  readonly invalidNameSubtrees: Schema.Natural
  readonly oversizedFiles: Schema.Natural
  readonly invalidUtf8Files: Schema.Natural
  readonly binaryFiles: Schema.Natural
}>

Source

Since v0.8.0

Work

Work counts, with exact raw UTF-8 result bytes.

Signature

declare const Work: Schema.Struct<{
  readonly entries: Schema.Natural
  readonly matchingWork: Schema.Natural
  readonly resultBytes: Schema.ByteSize
  readonly scannedBytes: Schema.ByteSize
  readonly lineEvaluations: Schema.Natural
}>

Source

Since v0.8.0

Related documentation