@socprime/logtotal-sanitizer 0.0.1-beta.0

package/index-CutSH_48.d.ts

@@ -0,0 +1,409 @@
+/**
+ * Identifiers of the rules shipped with this package.
+ */
+type BuiltinRuleId = 'secrets' | 'sessionCookies' | 'paymentInfo' | 'govIds' | 'healthInfo' | 'phoneNumbers' | 'ips' | 'hosts' | 'users' | 'geoLocation' | 'paths';
+/**
+ * A rule identifier. Built-in identifiers are suggested by editors; any other string is accepted
+ * so custom rules can use their own namespace, for example `acme:ticketId`.
+ *
+ * A rule identifier must be a valid ASCII identifier because it is used as a named capture group
+ * in the combined pattern. Namespacing with `:` is not allowed — use `_` instead.
+ */
+type RuleId = BuiltinRuleId | (string & {});
+/**
+ * How a matched value is replaced.
+ *
+ * - `pseudo` replaces the value with a token carrying the rule's own prefix, for example
+ *   `<IP:4f2a1c9d5b3e7a08>`. The same input always maps to the same token for a given key, so
+ *   occurrences stay correlatable across a run and across files sanitized with the same key.
+ * - `mask` produces the same stable token but always uses the neutral `R` prefix, so the kind of
+ *   secret that was found is not disclosed by the output.
+ */
+type RedactionMode = 'pseudo' | 'mask';
+/**
+ * How a key string is turned into bytes. Keys produced by {@link generateKey} are `hex`;
+ * user-supplied passphrases are usually `utf8`.
+ */
+type KeyEncoding = 'hex' | 'utf8';
+/**
+ * A detection rule: a set of patterns plus the policy for replacing what they match.
+ *
+ * Create rules with {@link defineRule} rather than as plain objects — it validates the shape and
+ * fails early with an actionable message.
+ */
+interface SanitizeRule {
+    /**
+     * Unique identifier, also used as the named capture group in the combined pattern.
+     * Must match `/^[A-Za-z_$][A-Za-z0-9_$]*$/`.
+     */
+    id: RuleId;
+    /** Short human-readable name, suitable for a checkbox label or a report heading. */
+    label: string;
+    /** One sentence describing what the rule detects. */
+    description: string;
+    /** Replacement policy for values this rule matches. */
+    mode: RedactionMode;
+    /**
+     * Token prefix used in `pseudo` mode, for example `IP` produces `<IP:…>`. Must match
+     * `/^[A-Z][A-Z0-9]*$/`. Ignored in `mask` mode. Defaults to the uppercased identifier.
+     */
+    token?: string;
+    /**
+     * Regular expression source fragments, combined into one alternation. Each fragment is compiled
+     * with the `u` flag and must not contain capture groups other than non-capturing `(?:…)` —
+     * numbered groups shift the combined pattern's group indices.
+     */
+    patterns: string[];
+    /**
+     * Additional, deliberately broader fragments applied only when `aggressive` is enabled. They
+     * belong to the same rule, so counts and tokens still use this rule's identifier.
+     */
+    aggressivePatterns?: string[];
+    /**
+     * Final decision for a candidate the patterns matched. Return `false` to leave the value
+     * untouched — used to filter out well-known non-sensitive values and to apply checksums such as
+     * Luhn or IBAN mod-97. Must be side-effect free and fast: it runs once per candidate match.
+     */
+    validate?: (match: string) => boolean;
+    /**
+     * JSON field names whose value is redacted by name alone, regardless of its shape, when the
+     * input line is a JSON object. Matching ignores case, hyphens and underscores, so `x-api-key`,
+     * `x_api_key` and `xApiKey` are the same key.
+     */
+    jsonKeys?: string[];
+}
+/**
+ * Public description of a rule taking part in a run, without its patterns.
+ */
+interface RuleInfo {
+    id: RuleId;
+    label: string;
+    description: string;
+    mode: RedactionMode;
+}
+/** Match counts per rule identifier. */
+type RuleCounts = Partial<Record<RuleId, number>>;
+/**
+ * A slice of a before/after preview. `changed` marks the parts a rule replaced.
+ */
+interface SanitizeSegment {
+    text: string;
+    changed: boolean;
+}
+/**
+ * One distinct value that was replaced, with the number of times it occurred.
+ */
+interface SanitizeReplacement {
+    ruleId: RuleId;
+    original: string;
+    replacement: string;
+    count: number;
+    /** Text immediately before the first occurrence. Present only when `report.contextChars > 0`. */
+    contextBefore?: string;
+    /** Text immediately after the first occurrence. Present only when `report.contextChars > 0`. */
+    contextAfter?: string;
+}
+/**
+ * Summary of a sanitization run.
+ */
+interface SanitizeReport {
+    /** Number of replacements per rule, for the whole input. */
+    counts: RuleCounts;
+    /** Sum of every entry in {@link SanitizeReport.counts}. */
+    totalMatches: number;
+    /** Number of lines processed. */
+    lineCount: number;
+    /**
+     * Distinct replaced values for the whole input, deduplicated by rule and original value.
+     * Empty when `report.replacements` is disabled.
+     *
+     * These entries contain the original, unredacted values. Treat the report as sensitive: it is
+     * meant for local review, not for shipping alongside the sanitized output.
+     */
+    replacements: SanitizeReplacement[];
+    /**
+     * Before/after segments for the first `report.previewBytes` of output, so a UI can render a
+     * diff without holding the whole input in memory. Empty when `report.previewBytes` is `0`.
+     */
+    preview: {
+        before: SanitizeSegment[];
+        after: SanitizeSegment[];
+    };
+}
+/**
+ * Values and patterns that must be redacted regardless of which rules are active.
+ *
+ * Entries here take priority over every rule, so a value that would otherwise be missed is still
+ * replaced. Values allowlisted through {@link NeverRedactOptions} still win.
+ */
+interface AlwaysRedactOptions {
+    /** Exact substrings to redact. Matched literally; longer values win on overlap. */
+    values?: readonly string[];
+    /**
+     * Patterns to redact. A string is treated as a regular expression source, not as a literal.
+     * Flags on a `RegExp` are ignored; the combined pattern is always compiled with `gu`.
+     */
+    patterns?: readonly (string | RegExp)[];
+    /**
+     * Rule identifier reported for these matches.
+     * @default 'custom'
+     */
+    ruleId?: RuleId;
+    /**
+     * Replacement policy for these matches.
+     * @default 'pseudo'
+     */
+    mode?: RedactionMode;
+    /**
+     * Token prefix for these matches in `pseudo` mode.
+     * @default 'CUSTOM'
+     */
+    token?: string;
+}
+/** A per-rule allowlist entry. */
+interface NeverRedactRuleEntry {
+    ruleId: RuleId;
+    values: readonly string[];
+}
+/**
+ * Values that must never be redacted, even when a rule matches them.
+ *
+ * Checked against the matched value itself, not the surrounding line, and applied before any
+ * replacement is built.
+ */
+interface NeverRedactOptions {
+    /** Exact values to keep, whichever rule matched them. */
+    values?: readonly string[];
+    /**
+     * Patterns that keep a matched value when they match it in full. A string is treated as a
+     * regular expression source. Flags are ignored; matching is always anchored and Unicode-aware.
+     */
+    patterns?: readonly (string | RegExp)[];
+    /** Exact values to keep only for a specific rule. */
+    byRule?: readonly NeverRedactRuleEntry[];
+}
+/**
+ * Report detail level. Tightening these bounds lowers memory use on large inputs.
+ */
+interface ReportOptions {
+    /**
+     * Size of the before/after preview window, in output characters. `0` disables the preview.
+     * @default 262144
+     */
+    previewBytes?: number;
+    /**
+     * Whether to collect the list of distinct replaced values. Disable it when the report is only
+     * used for counts — the list grows with the number of distinct sensitive values in the input.
+     * @default true
+     */
+    replacements?: boolean;
+    /**
+     * How many characters of surrounding text to record next to each distinct replacement, to help
+     * a reviewer judge a match. `0` omits {@link SanitizeReplacement.contextBefore} and
+     * {@link SanitizeReplacement.contextAfter} entirely.
+     * @default 0
+     */
+    contextChars?: number;
+}
+/**
+ * Line splitting bounds, relevant for inputs that contain very long lines.
+ */
+interface LineOptions {
+    /**
+     * A run of characters longer than this without a line terminator is processed in bounded
+     * segments instead of being buffered whole.
+     * @default 1048576
+     */
+    maxLineChars?: number;
+    /**
+     * Characters carried from one bounded segment into the next, so a value straddling the cut is
+     * still matched. Must be smaller than `maxLineChars`.
+     * @default 1024
+     */
+    overlapChars?: number;
+}
+/** A rule to run: either a built-in identifier or a rule object. */
+type RuleSelector = RuleId | SanitizeRule;
+/**
+ * Configuration for {@link createSanitizer}.
+ */
+interface SanitizerOptions {
+    /**
+     * Rules to run, in priority order: when two rules can match at the same position, the one
+     * listed first wins. Identifiers are resolved against the built-in rules. Passing a rule object
+     * whose identifier is already present replaces that rule while keeping its position.
+     * @default every built-in rule, in the order documented in the README
+     */
+    rules?: readonly RuleSelector[];
+    /** Rules appended after {@link SanitizerOptions.rules}, so they run at the lowest priority. */
+    extraRules?: readonly SanitizeRule[];
+    /**
+     * Whether to also apply each rule's broader `aggressivePatterns`. Catches more, at the cost of
+     * more false positives.
+     * @default false
+     */
+    aggressive?: boolean;
+    /**
+     * Key used to derive replacement tokens. Reuse it to keep tokens comparable across files or
+     * runs; change it to make them uncorrelatable.
+     * @default a fresh random 32-byte key from {@link generateKey}
+     */
+    key?: string;
+    /**
+     * How {@link SanitizerOptions.key} is decoded.
+     * @default 'hex'
+     */
+    keyEncoding?: KeyEncoding;
+    /** Values and patterns to redact regardless of the active rules. */
+    alwaysRedact?: AlwaysRedactOptions;
+    /** Values and patterns to keep even when a rule matches them. */
+    neverRedact?: NeverRedactOptions;
+    /**
+     * How to treat lines that parse as a JSON object or array.
+     *
+     * - `'auto'` redacts values of fields named in a rule's `jsonKeys` and re-serializes the
+     *   record, falling back to plain-text scanning when the line is not valid JSON.
+     * - `false` always scans as plain text.
+     * @default 'auto'
+     */
+    json?: 'auto' | false;
+    /** Report detail level. */
+    report?: ReportOptions;
+    /** Line splitting bounds. */
+    lines?: LineOptions;
+}
+/** Result of sanitizing an in-memory string. */
+interface SanitizeTextResult {
+    /** The sanitized text. */
+    output: string;
+    /** Summary of what was replaced. */
+    report: SanitizeReport;
+}
+/** Progress of a streaming run. */
+interface SanitizeProgress {
+    /** Characters consumed from the source so far. */
+    charsRead: number;
+    /**
+     * Snapshot of the report so far. Counts grow throughout the run; the distinct-replacement list
+     * is omitted from snapshots and only present in the final report.
+     */
+    report: SanitizeReport;
+}
+/**
+ * The subset of `AbortSignal` this package relies on, so passing a signal does not require DOM or
+ * Node type definitions to be in scope.
+ */
+interface AbortSignalLike {
+    readonly aborted: boolean;
+}
+/** Per-run options for {@link Sanitizer.sanitizeStream}. */
+interface SanitizeStreamOptions {
+    /** Called after each source chunk with a live snapshot of progress. */
+    onProgress?: (progress: SanitizeProgress) => void;
+    /**
+     * Aborts the run between lines. The sink is not closed and a
+     * {@link SanitizationAbortedError} is thrown.
+     */
+    signal?: AbortSignalLike;
+}
+/** A source of text chunks. Chunk boundaries do not need to align with line boundaries. */
+type TextSource = AsyncIterable<string> | Iterable<string>;
+/** A destination for sanitized text. */
+interface TextSink {
+    write(chunk: string): void | Promise<void>;
+    /** Called once after the last chunk of a successful run. */
+    close?(): void | Promise<void>;
+}
+/**
+ * The minimal shape of a `Blob` or `File` this package reads, so browser and Node values are both
+ * accepted without depending on DOM type definitions.
+ */
+interface BlobLike {
+    readonly size: number;
+    slice(start?: number, end?: number): BlobLike;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * The minimal shape of a `ReadableStream` this package reads.
+ */
+interface ReadableStreamLike<T> {
+    getReader(): {
+        read(): Promise<{
+            done: boolean;
+            value?: T;
+        }>;
+        releaseLock(): void;
+    };
+}
+/**
+ * A configured, reusable sanitizer. Rules are compiled once when it is created, so sanitizing many
+ * inputs with the same configuration does not recompile patterns.
+ */
+interface Sanitizer {
+    /**
+     * The key in use, hex-encoded when it was generated. Persist it to keep tokens comparable in a
+     * later run; treat it as a secret, since it is what makes the tokens unguessable.
+     */
+    readonly key: string;
+    /** The rules taking part in a run, in priority order. */
+    readonly rules: readonly RuleInfo[];
+    /**
+     * Sanitizes an in-memory string.
+     *
+     * Holds both the input and the output in memory. For anything large, prefer
+     * {@link Sanitizer.sanitizeStream}.
+     */
+    sanitizeText(text: string): SanitizeTextResult;
+    /**
+     * Streams text from `source` through the rules and writes the result to `sink`, holding no more
+     * than one chunk plus one line in memory.
+     *
+     * @returns The report for the whole run.
+     * @throws {SanitizationAbortedError} When `options.signal` is aborted.
+     */
+    sanitizeStream(source: TextSource, sink: TextSink, options?: SanitizeStreamOptions): Promise<SanitizeReport>;
+}
+
+/**
+ * Validates a rule and returns it unchanged.
+ *
+ * Use it instead of a plain object literal: the shape is checked once, at module load, so a typo in
+ * a pattern surfaces immediately rather than as a silent miss during a run.
+ *
+ * @throws {InvalidRuleError} When the rule is malformed.
+ *
+ * @example
+ * ```ts
+ * const ticketRule = defineRule({
+ *   id: 'acme_ticket',
+ *   label: 'Support ticket IDs',
+ *   description: 'Internal ticket references such as ACME-123456.',
+ *   mode: 'pseudo',
+ *   token: 'TICKET',
+ *   patterns: ['(?:\\bACME-\\d{6}\\b)'],
+ *   jsonKeys: ['ticketId'],
+ * });
+ *
+ * const sanitizer = createSanitizer({ extraRules: [ticketRule] });
+ * ```
+ */
+declare function defineRule(rule: SanitizeRule): SanitizeRule;
+
+/**
+ * Every rule shipped with this package, in default priority order.
+ *
+ * Order matters: when two rules could match at the same position, the one listed first wins.
+ * Credential-shaped rules come first so a token is not partially consumed by a broader
+ * identifier rule.
+ */
+declare const builtinRules: readonly SanitizeRule[];
+/** Identifiers of {@link builtinRules}, in the same order. */
+declare const builtinRuleIds: readonly BuiltinRuleId[];
+/**
+ * Looks up a built-in rule by identifier.
+ *
+ * @returns The rule, or `undefined` when the identifier is not built in.
+ */
+declare function getBuiltinRule(id: string): SanitizeRule | undefined;
+
+export { type AbortSignalLike as A, type BlobLike as B, type KeyEncoding as K, type LineOptions as L, type NeverRedactOptions as N, type ReadableStreamLike as R, type SanitizerOptions as S, type TextSource as T, type SanitizeProgress as a, type SanitizeReport as b, type TextSink as c, type AlwaysRedactOptions as d, type BuiltinRuleId as e, type NeverRedactRuleEntry as f, type RedactionMode as g, type ReportOptions as h, type RuleCounts as i, type RuleId as j, type RuleInfo as k, type RuleSelector as l, type SanitizeReplacement as m, type SanitizeRule as n, type SanitizeSegment as o, type SanitizeStreamOptions as p, type SanitizeTextResult as q, type Sanitizer as r, builtinRuleIds as s, builtinRules as t, defineRule as u, getBuiltinRule as v };

package/index.cjs

@@ -0,0 +1,93 @@
+'use strict';
+
+var chunkWISLDJT3_cjs = require('./chunk-WISLDJT3.cjs');
+var chunkVW3VVW6L_cjs = require('./chunk-VW3VVW6L.cjs');
+
+
+
+Object.defineProperty(exports, "createSanitizer", {
+  enumerable: true,
+  get: function () { return chunkWISLDJT3_cjs.createSanitizer; }
+});
+Object.defineProperty(exports, "fromBlob", {
+  enumerable: true,
+  get: function () { return chunkWISLDJT3_cjs.fromBlob; }
+});
+Object.defineProperty(exports, "fromString", {
+  enumerable: true,
+  get: function () { return chunkWISLDJT3_cjs.fromString; }
+});
+Object.defineProperty(exports, "fromWebStream", {
+  enumerable: true,
+  get: function () { return chunkWISLDJT3_cjs.fromWebStream; }
+});
+Object.defineProperty(exports, "generateKey", {
+  enumerable: true,
+  get: function () { return chunkWISLDJT3_cjs.generateKey; }
+});
+Object.defineProperty(exports, "sanitizeStream", {
+  enumerable: true,
+  get: function () { return chunkWISLDJT3_cjs.sanitizeStream; }
+});
+Object.defineProperty(exports, "sanitizeText", {
+  enumerable: true,
+  get: function () { return chunkWISLDJT3_cjs.sanitizeText; }
+});
+Object.defineProperty(exports, "toCallbackSink", {
+  enumerable: true,
+  get: function () { return chunkWISLDJT3_cjs.toCallbackSink; }
+});
+Object.defineProperty(exports, "toNullSink", {
+  enumerable: true,
+  get: function () { return chunkWISLDJT3_cjs.toNullSink; }
+});
+Object.defineProperty(exports, "toStringSink", {
+  enumerable: true,
+  get: function () { return chunkWISLDJT3_cjs.toStringSink; }
+});
+Object.defineProperty(exports, "InvalidKeyError", {
+  enumerable: true,
+  get: function () { return chunkVW3VVW6L_cjs.InvalidKeyError; }
+});
+Object.defineProperty(exports, "InvalidOptionError", {
+  enumerable: true,
+  get: function () { return chunkVW3VVW6L_cjs.InvalidOptionError; }
+});
+Object.defineProperty(exports, "InvalidRuleError", {
+  enumerable: true,
+  get: function () { return chunkVW3VVW6L_cjs.InvalidRuleError; }
+});
+Object.defineProperty(exports, "SanitizationAbortedError", {
+  enumerable: true,
+  get: function () { return chunkVW3VVW6L_cjs.SanitizationAbortedError; }
+});
+Object.defineProperty(exports, "SanitizerError", {
+  enumerable: true,
+  get: function () { return chunkVW3VVW6L_cjs.SanitizerError; }
+});
+Object.defineProperty(exports, "UnknownRuleError", {
+  enumerable: true,
+  get: function () { return chunkVW3VVW6L_cjs.UnknownRuleError; }
+});
+Object.defineProperty(exports, "builtinRuleIds", {
+  enumerable: true,
+  get: function () { return chunkVW3VVW6L_cjs.builtinRuleIds; }
+});
+Object.defineProperty(exports, "builtinRules", {
+  enumerable: true,
+  get: function () { return chunkVW3VVW6L_cjs.builtinRules; }
+});
+Object.defineProperty(exports, "defineRule", {
+  enumerable: true,
+  get: function () { return chunkVW3VVW6L_cjs.defineRule; }
+});
+Object.defineProperty(exports, "getBuiltinRule", {
+  enumerable: true,
+  get: function () { return chunkVW3VVW6L_cjs.getBuiltinRule; }
+});
+Object.defineProperty(exports, "isSanitizerError", {
+  enumerable: true,
+  get: function () { return chunkVW3VVW6L_cjs.isSanitizerError; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/index.d.cts

@@ -0,0 +1,157 @@
+import { S as SanitizerOptions, r as Sanitizer, T as TextSource, c as TextSink, p as SanitizeStreamOptions, b as SanitizeReport, q as SanitizeTextResult, B as BlobLike, R as ReadableStreamLike } from './index-CutSH_48.cjs';
+export { A as AbortSignalLike, d as AlwaysRedactOptions, e as BuiltinRuleId, K as KeyEncoding, L as LineOptions, N as NeverRedactOptions, f as NeverRedactRuleEntry, g as RedactionMode, h as ReportOptions, i as RuleCounts, j as RuleId, k as RuleInfo, l as RuleSelector, a as SanitizeProgress, m as SanitizeReplacement, n as SanitizeRule, o as SanitizeSegment, s as builtinRuleIds, t as builtinRules, u as defineRule, v as getBuiltinRule } from './index-CutSH_48.cjs';
+
+/**
+ * Machine-readable cause of a {@link SanitizerError}.
+ */
+type SanitizerErrorCode = 'INVALID_RULE' | 'UNKNOWN_RULE' | 'INVALID_KEY' | 'INVALID_OPTION' | 'ABORTED';
+/**
+ * Base class for every error this package throws.
+ */
+declare class SanitizerError extends Error {
+    /** Machine-readable cause, stable across releases. */
+    readonly code: SanitizerErrorCode;
+    constructor(code: SanitizerErrorCode, message: string);
+}
+/** A rule object is malformed. */
+declare class InvalidRuleError extends SanitizerError {
+    constructor(message: string);
+}
+/** A rule identifier does not match any built-in rule. */
+declare class UnknownRuleError extends SanitizerError {
+    constructor(message: string);
+}
+/** A key is malformed, or no secure random source is available to generate one. */
+declare class InvalidKeyError extends SanitizerError {
+    constructor(message: string);
+}
+/** An option value is outside its allowed range. */
+declare class InvalidOptionError extends SanitizerError {
+    constructor(message: string);
+}
+/** A streaming run was stopped through its `AbortSignal`. */
+declare class SanitizationAbortedError extends SanitizerError {
+    constructor(message?: string);
+}
+/**
+ * Whether a caught value is an error thrown by this package.
+ *
+ * Prefer this over `instanceof` when the value may have crossed a bundle, worker or realm
+ * boundary, where class identity is not preserved.
+ */
+declare function isSanitizerError(value: unknown): value is SanitizerError;
+
+/**
+ * Generates a random hex-encoded key for token derivation.
+ *
+ * Persist the returned value if tokens have to stay comparable across runs or files; discard it if
+ * they should not. There is no way to recover the original values from the tokens, with or without
+ * the key — the key only determines which token a given value maps to.
+ *
+ * @param byteLength Key length in bytes, at least 16.
+ * @throws {InvalidKeyError} When `byteLength` is too small or no secure random source is available.
+ *
+ * @example
+ * ```ts
+ * const key = generateKey();
+ * const sanitizer = createSanitizer({ key });
+ * ```
+ */
+declare function generateKey(byteLength?: number): string;
+
+/**
+ * Creates a reusable sanitizer.
+ *
+ * Rules are resolved, validated and compiled into a single pattern once, here — so sanitizing many
+ * inputs with one sanitizer is much cheaper than calling the one-shot helpers repeatedly.
+ *
+ * @throws {UnknownRuleError} When `rules` names a rule that is not built in.
+ * @throws {InvalidRuleError} When a custom rule is malformed.
+ * @throws {InvalidKeyError} When `key` is malformed, or none could be generated.
+ * @throws {InvalidOptionError} When an option value is out of range.
+ *
+ * @example
+ * ```ts
+ * const sanitizer = createSanitizer({
+ *   rules: ['secrets', 'ips', 'users'],
+ *   alwaysRedact: { values: ['acme-internal'] },
+ *   neverRedact: { values: ['127.0.0.1'] },
+ * });
+ *
+ * const { output, report } = sanitizer.sanitizeText('login from 10.0.0.7 failed');
+ * ```
+ */
+declare function createSanitizer(options?: SanitizerOptions): Sanitizer;
+/**
+ * Sanitizes a string with a one-off configuration.
+ *
+ * Convenient for scripts and tests. Each call builds a new sanitizer, so unless `options.key` is
+ * supplied the tokens are not comparable between calls. For repeated use, create a sanitizer with
+ * {@link createSanitizer} instead.
+ */
+declare function sanitizeText(text: string, options?: SanitizerOptions): SanitizeTextResult;
+/**
+ * Streams text through a one-off sanitizer.
+ *
+ * See {@link sanitizeText} for the trade-off of creating a sanitizer per call.
+ */
+declare function sanitizeStream(source: TextSource, sink: TextSink, options?: SanitizerOptions & SanitizeStreamOptions): Promise<SanitizeReport>;
+
+/**
+ * Wraps a string as a source, split into fixed-size chunks.
+ *
+ * Useful for exercising the streaming path in tests and for feeding text that is already in memory
+ * without copying it in one piece.
+ */
+declare function fromString(text: string, chunkChars?: number): TextSource;
+/**
+ * Reads a `Blob` or `File` as UTF-8 text, one chunk at a time.
+ *
+ * Multi-byte characters split across a chunk boundary are decoded correctly. Accepts any object
+ * with `size`, `slice` and `arrayBuffer`, so browser `File`, browser `Blob` and Node's `Blob` all
+ * work.
+ *
+ * @example
+ * ```ts
+ * const report = await sanitizer.sanitizeStream(fromBlob(file), toStringSink());
+ * ```
+ */
+declare function fromBlob(blob: BlobLike, chunkBytes?: number): TextSource;
+/**
+ * Reads a `ReadableStream` of text or bytes.
+ *
+ * Byte chunks are decoded as UTF-8 across chunk boundaries. Accepts web streams from `fetch`,
+ * `Blob.stream()` and `node:stream/web`.
+ */
+declare function fromWebStream(stream: ReadableStreamLike<string | Uint8Array>): TextSource;
+
+/** A sink that accumulates everything in memory. */
+interface StringSink extends TextSink {
+    /** Everything written so far, joined. */
+    readonly text: string;
+}
+/**
+ * Collects sanitized output into a string.
+ *
+ * Only appropriate when the output is known to fit in memory — the point of the streaming API is
+ * usually to avoid that.
+ *
+ * @example
+ * ```ts
+ * const sink = toStringSink();
+ * const report = await sanitizer.sanitizeStream(fromString(input), sink);
+ * console.log(sink.text, report.totalMatches);
+ * ```
+ */
+declare function toStringSink(): StringSink;
+/**
+ * Sends sanitized output to a callback, one line at a time.
+ *
+ * The callback may return a promise; it is awaited before the next line is written, so
+ * backpressure propagates to the source.
+ */
+declare function toCallbackSink(onChunk: (chunk: string) => void | Promise<void>, onClose?: () => void | Promise<void>): TextSink;
+/** A sink that discards everything, for report-only runs. */
+declare function toNullSink(): TextSink;
+
+export { BlobLike, InvalidKeyError, InvalidOptionError, InvalidRuleError, ReadableStreamLike, SanitizationAbortedError, SanitizeReport, SanitizeStreamOptions, SanitizeTextResult, Sanitizer, SanitizerError, type SanitizerErrorCode, SanitizerOptions, type StringSink, TextSink, TextSource, UnknownRuleError, createSanitizer, fromBlob, fromString, fromWebStream, generateKey, isSanitizerError, sanitizeStream, sanitizeText, toCallbackSink, toNullSink, toStringSink };