turbine-orm 0.81.0 → 0.90.0

package/dist/cjs/query/sql-comment.js

@@ -0,0 +1,381 @@
+"use strict";
+/**
+ * turbine-orm: `sqlComment`, sqlcommenter-style key/values on each statement
+ * Turbine builds, so `pg_stat_activity`, the server log, `auto_explain` and
+ * database APM tools can attribute a statement to a service, a model, a feature
+ * or a trace.
+ *
+ *   SELECT ... LIMIT $2 /*action='findMany',application='billing',model='users'*\/
+ *
+ * FORMAT (the sqlcommenter spec): keys sorted, each value URL-encoded with
+ * `encodeURIComponent` and then `'` escaped as `\'`, each pair `key='value'`,
+ * pairs joined by commas, the whole comment appended after the statement with
+ * one space before it.
+ *
+ * WHY A VALUE CANNOT ESCAPE THE COMMENT. `encodeURIComponent` encodes `/`, so a
+ * value can hold neither `*\/` (the comment's end) nor `/*` (PostgreSQL and SQL
+ * Server nest block comments, so an opener would swallow the rest of the
+ * text). It also encodes every character a driver-side placeholder rewrite
+ * looks for (`$`, `?`, `:`, `@`) and `;`. Keys must match
+ * {@link SQL_COMMENT_KEY_PATTERN}, whose first-character rule also rules out
+ * MySQL's executable `/*!` and optimizer-hint `/*+` comments.
+ *
+ * WHERE IT IS APPENDED: at the execute seam, AFTER the SQL-template cache. The
+ * cache stores commentless text, so its keys, its hit rate and the lockstep
+ * checks are untouched by any comment, and a per-request value can never grow
+ * it. `$on('query')` events keep `sql` commentless and carry the comment in
+ * their own field.
+ *
+ * PREPARED-STATEMENT NAMES. node-postgres refuses to reuse a statement name for
+ * different text on one connection, and every name a connection prepares stays
+ * on the server until the connection closes. So:
+ *
+ *   - no comment: the template's own name, as before;
+ *   - static, model, action and tag only (constant per call site and label):
+ *     `c_<16 hex>`, a hash of the template name and the comment, claimed from
+ *     the same process-wide budget as every other name
+ *     (`PREPARED_STATEMENT_BUDGET`), so the server-side cost stays bounded
+ *     however many labels there are;
+ *   - any dynamic value (a trace id, unique per request): unnamed, parsed on
+ *     every execution and never kept. A per-request value under a name would
+ *     prepare a new statement on every pooled connection for every request.
+ *
+ * Leaf apart from errors.ts, logger.ts, query-events.ts (the `$tag` scope) and
+ * utils.ts (the name budget); nothing here is Node-only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlCommenter = exports.MAX_SQL_COMMENT_VALUE_LENGTH = exports.SQL_COMMENT_KEY_PATTERN = void 0;
+exports.resolveSqlComment = resolveSqlComment;
+exports.withoutTrailingComment = withoutTrailingComment;
+exports.commentDeferred = commentDeferred;
+const errors_js_1 = require("../errors.js");
+const logger_js_1 = require("../logger.js");
+const query_events_js_1 = require("../query-events.js");
+const utils_js_1 = require("./utils.js");
+const warn_registry_js_1 = require("./warn-registry.js");
+/** What a comment key must look like. Lower case, so it can never open `/*!` or `/*+`. */
+exports.SQL_COMMENT_KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
+/** Longest value accepted, in characters before encoding. */
+exports.MAX_SQL_COMMENT_VALUE_LENGTH = 256;
+/** The keys `model: true` and `tag: true` fill in. */
+const MODEL_KEYS = ['action', 'model'];
+const TAG_KEY = 'tag';
+const OPTION_KEYS = new Set(['static', 'model', 'tag', 'dynamic']);
+/** Once-only warning namespace for dropped dynamic values. */
+const DROPPED_WARN_NS = 'sqlCommentDropped';
+/**
+ * `value` URL-encoded with `'` escaped, or `undefined` when it cannot be encoded
+ * (a lone surrogate). `encodeURIComponent` leaves `'` as is and never emits a
+ * backslash; the escape covers both anyway, so it stays complete on its own.
+ */
+function encodeValue(value) {
+    try {
+        return encodeURIComponent(value).replace(/[\\']/g, '\\$&');
+    }
+    catch {
+        return undefined;
+    }
+}
+function render(pairs) {
+    let out = '/*';
+    for (let i = 0; i < pairs.length; i++) {
+        const [key, value] = pairs[i];
+        out += `${i === 0 ? '' : ','}${key}='${value}'`;
+    }
+    return `${out}*/`;
+}
+function byKey(a, b) {
+    return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0;
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** A short, printable rendering of a caller's key for a message. */
+function describeKey(key) {
+    return JSON.stringify(key.length > 64 ? `${key.slice(0, 64)}...` : key);
+}
+/**
+ * Builds the comment for each statement and the name it is sent under. One per
+ * client, shared by every table accessor and transaction of that client.
+ */
+class SqlCommenter {
+    logger;
+    /** Static pairs, encoded and sorted. */
+    staticPairs;
+    /** Keys a dynamic value may not take: the static ones and the ones model / tag fill in. */
+    reservedKeys;
+    withModel;
+    withTag;
+    dynamic;
+    /** The comment when it depends on nothing per statement (no model, no tag). */
+    constant;
+    /** Rendered model / action / tag comments. Bounded: tags may come from data. */
+    rendered = new utils_js_1.LRUCache(1000);
+    /** Claimed `c_` names by template name and comment. Holds only claimed names, so the budget bounds it. */
+    names = new Map();
+    /**
+     * Every statement gets a comment (a static key, or the model and action),
+     * so a template's own name is never sent and need not be claimed from the
+     * budget; the commented name is claimed instead.
+     */
+    alwaysComments;
+    constructor(staticPairs, withModel, withTag, dynamic, logger) {
+        this.logger = logger;
+        this.staticPairs = [...staticPairs].sort(byKey);
+        this.withModel = withModel;
+        this.withTag = withTag;
+        this.dynamic = dynamic;
+        const reserved = new Set(this.staticPairs.map(([k]) => k));
+        if (withModel)
+            for (const k of MODEL_KEYS)
+                reserved.add(k);
+        if (withTag)
+            reserved.add(TAG_KEY);
+        this.reservedKeys = reserved;
+        this.alwaysComments = this.staticPairs.length > 0 || withModel;
+        this.constant =
+            !withModel && !withTag && this.staticPairs.length > 0
+                ? { comment: render(this.staticPairs), dynamic: false }
+                : undefined;
+    }
+    /**
+     * The comment for one statement of operation `action` on `model`, or
+     * `undefined` when it carries none. Reads the `$tag` scope and calls
+     * `dynamic` in the caller's async context, so call it where the statement
+     * is sent.
+     */
+    commentFor(model, action) {
+        let pairs;
+        let base;
+        if (this.withModel || this.withTag) {
+            const tag = this.withTag ? (0, query_events_js_1.currentQueryTag)() : undefined;
+            const key = `${model}\u0000${action}\u0000${tag ?? ''}`;
+            let hit = this.rendered.get(key);
+            if (hit === undefined) {
+                const built = [...this.staticPairs];
+                if (this.withModel) {
+                    built.push(['action', encodeValue(action) ?? ''], ['model', encodeValue(model) ?? '']);
+                }
+                // A `$tag` label is 1 to 128 characters, checked when the scope opens.
+                const encodedTag = tag === undefined ? undefined : encodeValue(tag);
+                if (encodedTag !== undefined)
+                    built.push([TAG_KEY, encodedTag]);
+                built.sort(byKey);
+                hit = { pairs: built, comment: built.length > 0 ? render(built) : '' };
+                this.rendered.set(key, hit);
+            }
+            pairs = hit.pairs;
+            base = hit.comment === '' ? undefined : { comment: hit.comment, dynamic: false };
+        }
+        else {
+            pairs = this.staticPairs;
+            base = this.constant;
+        }
+        if (this.dynamic === undefined)
+            return base;
+        const extra = this.dynamicPairs();
+        if (extra === undefined)
+            return base;
+        return { comment: render([...pairs, ...extra].sort(byKey)), dynamic: true };
+    }
+    /**
+     * The name a statement with comment `c` is sent under, given its template's
+     * name. A template sent unnamed stays unnamed; a dynamic comment is unnamed;
+     * anything else gets a stable `c_` name from the process-wide budget, or
+     * goes unnamed once that is spent.
+     */
+    preparedName(templateName, c) {
+        if (!templateName)
+            return templateName;
+        if (c.dynamic)
+            return '';
+        const key = `${templateName}\u0000${c.comment}`;
+        const known = this.names.get(key);
+        if (known !== undefined)
+            return known;
+        const name = (0, utils_js_1.claimPreparedName)(`c_${(0, utils_js_1.fnv1a64Hex)(key)}`);
+        if (name !== '')
+            this.names.set(key, name);
+        return name;
+    }
+    /** The usable dynamic pairs, encoded, or `undefined` when there are none. */
+    dynamicPairs() {
+        let values;
+        try {
+            values = this.dynamic?.();
+        }
+        catch (err) {
+            this.dropped('threw', '', `sqlComment.dynamic threw (${err instanceof Error ? err.message : String(err)}), so ` +
+                'this statement carries no dynamic values. The statement itself ran as usual.');
+            return undefined;
+        }
+        if (values === undefined || values === null)
+            return undefined;
+        if (typeof values !== 'object' || Array.isArray(values)) {
+            this.dropped('shape', '', 'sqlComment.dynamic returned something other than an object of string values, so this statement carries ' +
+                'no dynamic values. Return an object such as { traceparent: "00-..." }, or undefined for none.');
+            return undefined;
+        }
+        let out;
+        for (const key of Object.keys(values)) {
+            const value = values[key];
+            if (value === undefined)
+                continue;
+            const reason = this.refusal(key, value);
+            if (reason !== undefined) {
+                this.dropped(reason[0], key, `sqlComment.dynamic key ${describeKey(key)} was left out of the comment: ${reason[1]}`);
+                continue;
+            }
+            const encoded = encodeValue(value);
+            if (encoded === undefined) {
+                this.dropped('encoding', key, `sqlComment.dynamic key ${describeKey(key)} was left out of the comment: its value is not well-formed ` +
+                    'Unicode (a lone surrogate), so it cannot be URL-encoded.');
+                continue;
+            }
+            if (out === undefined)
+                out = [];
+            out.push([key, encoded]);
+        }
+        return out;
+    }
+    /** Why a dynamic key or value cannot be used, as [warning key, sentence], or `undefined`. */
+    refusal(key, value) {
+        if (!exports.SQL_COMMENT_KEY_PATTERN.test(key)) {
+            return ['key', 'a key must be lower-case letters, digits and underscores, starting with a letter.'];
+        }
+        if (this.reservedKeys.has(key)) {
+            return ['reserved', 'that key is already set by sqlComment.static, model or tag, which take precedence.'];
+        }
+        if (typeof value !== 'string')
+            return ['type', `its value is ${typeof value}, not a string.`];
+        if (value.length > exports.MAX_SQL_COMMENT_VALUE_LENGTH) {
+            return ['length', `its value is ${value.length} characters, over the ${exports.MAX_SQL_COMMENT_VALUE_LENGTH} allowed.`];
+        }
+        return undefined;
+    }
+    /** One warning per reason and key, so a hook that misbehaves on every statement says it once. */
+    dropped(reason, key, message) {
+        if (!(0, warn_registry_js_1.shouldWarnOnce)(DROPPED_WARN_NS, `${reason}|${key.slice(0, 64)}`))
+            return;
+        (0, logger_js_1.logTo)(this.logger, 'warn', message, { code: 'sql-comment-dropped', reason });
+    }
+}
+exports.SqlCommenter = SqlCommenter;
+/**
+ * Validate `TurbineConfig.sqlComment` and build its commenter, or `undefined`
+ * when there is nothing to add. Throws `ValidationError` (E003) for a malformed
+ * option, and `UnsupportedFeatureError` (E017) where it cannot be honoured:
+ *
+ *   - a backend that builds no SQL (PowDB, which injects its own query
+ *     interface) has nothing to comment;
+ *   - `dynamic` on an engine that prepares every statement text
+ *     (`preparesEveryStatement`), which is MySQL: the MySQL engine sends each
+ *     parameterized statement through mysql2's `execute()`, which keeps one
+ *     SERVER-side prepared
+ *     statement per distinct text per connection (up to 16,000 each), and the
+ *     server caps the total across every client at `max_prepared_stmt_count`
+ *     (16,382 by default). A value unique per request makes every text
+ *     distinct, so a busy pool reaches that cap (error 1461) and every client
+ *     of the server then fails to prepare.
+ */
+function resolveSqlComment(value, logger, engine) {
+    if (value === undefined)
+        return undefined;
+    if (!isPlainObject(value)) {
+        throw new errors_js_1.ValidationError('Invalid sqlComment: expected an object with any of `static`, `model`, `tag` and `dynamic`, for example ' +
+            "{ static: { application: 'billing' }, model: true }.");
+    }
+    for (const key of Object.keys(value)) {
+        if (!OPTION_KEYS.has(key)) {
+            throw new errors_js_1.ValidationError(`Invalid sqlComment: unknown key ${describeKey(key)}. The keys are \`static\`, \`model\`, \`tag\` and \`dynamic\`.`);
+        }
+    }
+    const { static: staticValues, model, tag, dynamic } = value;
+    for (const [name, flag] of [
+        ['model', model],
+        ['tag', tag],
+    ]) {
+        if (flag !== undefined && typeof flag !== 'boolean') {
+            throw new errors_js_1.ValidationError(`Invalid sqlComment.${name}: expected true or false, got ${typeof flag}.`);
+        }
+    }
+    if (dynamic !== undefined && typeof dynamic !== 'function') {
+        throw new errors_js_1.ValidationError(`Invalid sqlComment.dynamic: expected a function returning an object of string values, got ${typeof dynamic}.`);
+    }
+    const pairs = [];
+    if (staticValues !== undefined) {
+        if (!isPlainObject(staticValues)) {
+            throw new errors_js_1.ValidationError("Invalid sqlComment.static: expected an object of string values, for example { application: 'billing' }.");
+        }
+        for (const key of Object.keys(staticValues)) {
+            const v = staticValues[key];
+            const where = `sqlComment.static key ${describeKey(key)}`;
+            if (!exports.SQL_COMMENT_KEY_PATTERN.test(key)) {
+                throw new errors_js_1.ValidationError(`Invalid ${where}: a key must be lower-case letters, digits and underscores, starting with a letter ` +
+                    '(the comment must never open a MySQL executable or hint comment, `/*!` or `/*+`).');
+            }
+            if ((model === true && MODEL_KEYS.includes(key)) || (tag === true && key === TAG_KEY)) {
+                throw new errors_js_1.ValidationError(`Invalid ${where}: \`${key}\` is filled in by sqlComment.${key === TAG_KEY ? 'tag' : 'model'}. ` +
+                    'Rename the static key or turn that option off.');
+            }
+            if (typeof v !== 'string') {
+                throw new errors_js_1.ValidationError(`Invalid ${where}: expected a string value, got ${typeof v}.`);
+            }
+            if (v.length > exports.MAX_SQL_COMMENT_VALUE_LENGTH) {
+                throw new errors_js_1.ValidationError(`Invalid ${where}: the value is ${v.length} characters, over the ${exports.MAX_SQL_COMMENT_VALUE_LENGTH} allowed.`);
+            }
+            const encoded = encodeValue(v);
+            if (encoded === undefined) {
+                throw new errors_js_1.ValidationError(`Invalid ${where}: the value is not well-formed Unicode (a lone surrogate), so it cannot be URL-encoded.`);
+            }
+            pairs.push([key, encoded]);
+        }
+    }
+    if (pairs.length === 0 && model !== true && tag !== true && dynamic === undefined)
+        return undefined;
+    if (!engine.buildsSql) {
+        throw new errors_js_1.UnsupportedFeatureError('sqlComment', engine.dialect, 'This engine does not run SQL, so there is no statement to carry a comment. Remove the option for this client.');
+    }
+    if (dynamic !== undefined && engine.preparesEveryStatement) {
+        throw new errors_js_1.UnsupportedFeatureError('sqlComment.dynamic', engine.dialect, 'The MySQL engine prepares each distinct statement text on the server (mysql2 execute(), up to 16,000 per ' +
+            'connection), and the server caps prepared statements across all clients at max_prepared_stmt_count ' +
+            '(16,382 by default). A per-statement value makes every text distinct, so a busy pool reaches that cap ' +
+            '(error 1461) and prepares start failing server-wide. Use `static`, `model` and `tag`, which are bounded.');
+    }
+    return new SqlCommenter(pairs, model === true, tag === true, dynamic, logger);
+}
+/**
+ * `sql` with a comment Turbine appended removed, for code that reads statement
+ * text to decide how to run it (an engine shim telling a row-returning
+ * statement from a change count). A value can never contain `/*` (it is
+ * URL-encoded), so the last ` /*` of a statement ending in `*\/` is the
+ * comment's own opener; text Turbine did not comment is returned unchanged
+ * unless it, too, ends in a block comment, which is equally not code.
+ */
+function withoutTrailingComment(sql) {
+    if (!sql.endsWith('*/'))
+        return sql;
+    const at = sql.lastIndexOf(' /*');
+    return at < 0 ? sql : sql.slice(0, at);
+}
+/**
+ * `q` as sent with `comment`: its statement, and every statement of its
+ * reselect plan (MySQL), carry the comment. Everything else on the query is
+ * kept. Used by the batch paths (`pipeline`, `$transaction([...])`), which run
+ * deferred queries without going through a query interface.
+ */
+function commentDeferred(q, comment) {
+    if (comment === undefined)
+        return q;
+    const reselect = q.reselect;
+    return {
+        ...q,
+        sql: `${q.sql} ${comment}`,
+        ...(reselect
+            ? { reselect: (exec) => reselect((sql, params, name) => exec(`${sql} ${comment}`, params, name)) }
+            : {}),
+    };
+}

package/dist/cjs/query/stream-idle.d.ts

@@ -0,0 +1,132 @@
+/**
+ * turbine-orm: the abandoned-stream idle guard.
+ *
+ * A cursor stream holds a checked-out connection between pulls (and, on
+ * PostgreSQL, an open transaction whose snapshot pins the xmin horizon for the
+ * whole database). A consumer that stops pulling without calling `return()`
+ * leaves the stream suspended at a `yield` forever, and a suspended generator
+ * runs no code, so nothing would ever release either. This guard is the code
+ * that runs instead: a timer that notices the consumer has asked for nothing for
+ * the configured time and closes the stream from outside.
+ *
+ * The consuming generator owns the {@link StreamIdleState}: it sets `suspended`
+ * around each yield and bumps `pulls` when the consumer resumes it. That is two
+ * writes per yield and no timer work, which is what keeps a per-row stream as
+ * cheap as before (a timer refreshed per row costs about 15% per row; a
+ * `setTimeout` per row more than doubles it).
+ *
+ * Leaf module: imports errors.ts only, so it stays in the serverless graph
+ * without pulling anything node-only.
+ */
+import { TimeoutError } from '../errors.js';
+/** The default for `streamIdleTimeoutMs` (client) and `idleTimeoutMs` (per call). */
+export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000;
+/**
+ * How much later than the idle timeout the PostgreSQL server-side limit fires.
+ * The client timer always expires a stream first (it ticks at most every
+ * {@link MAX_TICK_MS}, half this grace), so the server limit only acts when the
+ * process has stopped running timers: frozen between serverless invocations,
+ * or an event loop blocked for longer than the grace.
+ */
+export declare const STREAM_IDLE_BACKSTOP_GRACE_MS = 10000;
+/**
+ * The largest idle timeout accepted. PostgreSQL's
+ * `idle_in_transaction_session_timeout` is a 32-bit count of milliseconds, and
+ * the backstop adds the grace to it.
+ */
+export declare const MAX_STREAM_IDLE_TIMEOUT_MS: number;
+/**
+ * Validate an idle timeout: a whole number of milliseconds from 0 (disabled)
+ * to {@link MAX_STREAM_IDLE_TIMEOUT_MS}, else E003. `undefined` means "not
+ * set here", so the caller falls back to the next level.
+ */
+export declare function resolveStreamIdleTimeout(value: unknown, name: string): number | undefined;
+/**
+ * What the generator that yields to the consumer tells the guard. Written
+ * around every yield; read by the guard's timer.
+ */
+export interface StreamIdleState {
+    /** How many times the consumer has resumed the stream. */
+    pulls: number;
+    /** The stream is suspended at a yield, waiting for the consumer to ask for more. */
+    suspended: boolean;
+    /** Rows handed to the consumer so far, for the log line. */
+    rows: number;
+    /** Set when the guard closed the stream; the next pull throws it. */
+    expired: TimeoutError | undefined;
+}
+export declare function newStreamIdleState(): StreamIdleState;
+/** The E002 the next pull on an expired stream throws. */
+export declare function streamIdleExpiredError(action: string, table: string, timeoutMs: number, unit: string): TimeoutError;
+/**
+ * The PostgreSQL server-side limit for a stream's own transaction:
+ * `idle_in_transaction_session_timeout` set to the idle timeout plus the grace,
+ * TRANSACTION-LOCAL (`set_config(..., true)`), so it ends with the stream's
+ * COMMIT and cannot reach another client through a transaction pooler.
+ *
+ * A stricter limit already in force (a role or server setting below ours) is
+ * kept, so a stream never loosens what the operator configured. The value is a
+ * validated integer, never caller text: a GUC value cannot be a bind parameter.
+ * Reading `pg_settings` rather than calling `set_config` directly also means an
+ * engine without the setting gets no row and no error.
+ */
+export declare function streamBackstopStatement(timeoutMs: number): string;
+/**
+ * The timer half of the guard. One per open cursor stream, `unref()`ed so it
+ * never keeps a process alive.
+ *
+ * It ticks every `min(timeout / 4, 5 s)`. A tick that finds the stream
+ * suspended with no pull since the previous tick counts as idle; enough idle
+ * ticks in a row to cover the timeout expire the stream, so expiry lands
+ * between 1x the timeout and the timeout plus one tick. Time Turbine spends
+ * fetching never counts, because the stream is not suspended then.
+ *
+ * With `keepalive` set (PostgreSQL, where {@link streamBackstopStatement} is
+ * in force), a tick also sends a no-op statement when the connection has been
+ * quiet for half the timeout. A consumer that pulls rows of an already-fetched
+ * batch slowly is alive while the server sees an idle transaction; without the
+ * keepalive the server limit would end a stream the consumer is still reading.
+ * The server limit therefore only fires when this timer cannot run.
+ */
+export declare class StreamIdleGuard {
+    private readonly state;
+    private readonly timeoutMs;
+    private readonly expiredError;
+    private readonly onExpire;
+    private readonly keepalive?;
+    private readonly timer;
+    private readonly idleTicksToExpire;
+    private lastPulls;
+    private idleTicks;
+    private lastStatementAt;
+    private statementsInFlight;
+    private keepaliveInFlight;
+    /** Settles once an expired stream's cleanup has run (connection released). */
+    expiry: Promise<void> | undefined;
+    constructor(state: StreamIdleState, timeoutMs: number, expiredError: () => TimeoutError, onExpire: () => Promise<void>, keepalive?: (() => Promise<unknown>) | undefined);
+    /** Bracket a statement on the stream's connection, so the keepalive knows it is busy. */
+    statementStarted(): void;
+    statementSettled(): void;
+    stop(): void;
+    private tick;
+}
+/** The connection surface a stream drives; structurally `StreamableConnection` in dialect.ts. */
+interface StreamConnection {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+/**
+ * The stream's connection, as the dialect sees it, with two additions: every
+ * statement is reported to the guard (for the keepalive), and, when `backstop`
+ * is given, the dialect's own BEGIN carries {@link streamBackstopStatement} in
+ * the same simple-protocol round trip, so the limit is in force from the
+ * transaction's first statement at no extra cost. Matching the exact BEGIN text
+ * the dialect emits keeps the dialect itself unchanged; the live backstop test
+ * fails if that text ever stops matching.
+ */
+export declare function watchStreamConnection(base: StreamConnection, guard: () => StreamIdleGuard | undefined, backstop?: {
+    begin: string;
+    statement: string;
+}): StreamConnection;
+export {};