@keystrokehq/snowflake 0.0.1

package/dist/rows.mjs

@@ -0,0 +1,223 @@
+import { executeSql } from "./sql.mjs";
+import { i as quoteIdentifier, t as buildFqn } from "./sql-safety-CywdR3EP.mjs";
+
+//#region src/rows.ts
+function isSqlBinding(value) {
+	return typeof value === "object" && value !== null && "type" in value && "value" in value && typeof value.type === "string";
+}
+/**
+* Map a JS value to its Snowflake typed binding. Callers who need full
+* control can pre-build a `{type, value}` object and pass it through.
+*/
+function inferBinding(value) {
+	if (isSqlBinding(value)) return value;
+	if (value === null || value === void 0) return {
+		type: "TEXT",
+		value: null
+	};
+	if (typeof value === "string") return {
+		type: "TEXT",
+		value
+	};
+	if (typeof value === "boolean") return {
+		type: "BOOLEAN",
+		value: value ? "true" : "false"
+	};
+	if (typeof value === "bigint") return {
+		type: "FIXED",
+		value: value.toString()
+	};
+	if (typeof value === "number") {
+		if (Number.isNaN(value) || !Number.isFinite(value)) throw new TypeError("Cannot bind NaN or Infinity as a Snowflake value");
+		return Number.isInteger(value) ? {
+			type: "FIXED",
+			value: value.toString()
+		} : {
+			type: "REAL",
+			value: value.toString()
+		};
+	}
+	if (value instanceof Date) return {
+		type: "TIMESTAMP_LTZ",
+		value: value.toISOString()
+	};
+	const unreachable = value;
+	throw new TypeError(`Unsupported binding type: ${typeof unreachable}`);
+}
+/**
+* Mutable binding builder. Internally indexes bindings starting at 1 and
+* returns the `?` placeholder for each append so callers can weave them into
+* their SQL composition.
+*/
+var BindingBuilder = class {
+	map = {};
+	counter = 0;
+	add(value) {
+		this.counter += 1;
+		this.map[String(this.counter)] = inferBinding(value);
+		return "?";
+	}
+	toRecord() {
+		return this.map;
+	}
+	size() {
+		return this.counter;
+	}
+};
+function composeWhere(where, bindings) {
+	const clauses = [];
+	for (const [column, value] of Object.entries(where)) {
+		if (value === null || value === void 0) {
+			clauses.push(`${quoteIdentifier(column)} IS NULL`);
+			continue;
+		}
+		clauses.push(`${quoteIdentifier(column)} = ${bindings.add(value)}`);
+	}
+	return clauses.length > 0 ? ` WHERE ${clauses.join(" AND ")}` : "";
+}
+function composeSet(set, bindings) {
+	const fragments = Object.entries(set).map(([column, value]) => `${quoteIdentifier(column)} = ${bindings.add(value)}`);
+	if (fragments.length === 0) throw new Error("updateRow requires at least one column in `set`");
+	return fragments.join(", ");
+}
+function executeRowStatement(client, sql, bindings, ctx) {
+	return executeSql(client, {
+		statement: sql,
+		warehouse: ctx.warehouse,
+		role: ctx.role,
+		database: ctx.database,
+		schema: ctx.schema,
+		bindings: bindings.size() > 0 ? bindings.toRecord() : void 0
+	});
+}
+/**
+* Read the first numeric value from the first row of a DML result.
+* Snowflake returns INSERT/UPDATE/DELETE stats as a single row with a
+* column like `"number of rows inserted"`.
+*/
+function readAffectedRows(result) {
+	if (result.rows.length === 0) return 0;
+	const firstRow = result.rows[0];
+	if (!firstRow) return 0;
+	const values = Array.isArray(firstRow) ? firstRow : Object.values(firstRow);
+	for (const value of values) {
+		if (typeof value === "number") return value;
+		if (typeof value === "bigint") return Number(value);
+		if (typeof value === "string") {
+			const parsed = Number(value);
+			if (!Number.isNaN(parsed)) return parsed;
+		}
+	}
+	return 0;
+}
+function composeColumnList(columns) {
+	if (!columns || columns.length === 0) return "*";
+	return columns.map((c) => quoteIdentifier(c)).join(", ");
+}
+function composeOrderBy(orderBy) {
+	if (!orderBy || orderBy.length === 0) return "";
+	return ` ORDER BY ${orderBy.map(({ column, direction }) => {
+		const dir = direction === "DESC" ? " DESC" : " ASC";
+		return `${quoteIdentifier(column)}${dir}`;
+	}).join(", ")}`;
+}
+function composeLimitOffset(limit, offset) {
+	let out = "";
+	if (typeof limit === "number" && limit >= 0) out += ` LIMIT ${Math.floor(limit)}`;
+	if (typeof offset === "number" && offset > 0) out += ` OFFSET ${Math.floor(offset)}`;
+	return out;
+}
+async function findRows(client, options) {
+	const bindings = new BindingBuilder();
+	return (await executeRowStatement(client, `SELECT ${composeColumnList(options.columns)} FROM ${buildFqn(options.database, options.schema, options.table)}` + composeWhere(options.where ?? {}, bindings) + composeOrderBy(options.orderBy) + composeLimitOffset(options.limit, options.offset), bindings, options)).rows;
+}
+async function findRow(client, options) {
+	return (await findRows(client, {
+		...options,
+		limit: 1
+	}))[0];
+}
+async function insertRow(client, options) {
+	const columns = Object.keys(options.row);
+	if (columns.length === 0) throw new Error("insertRow requires at least one column in `row`");
+	const bindings = new BindingBuilder();
+	const placeholders = columns.map((column) => bindings.add(options.row[column]));
+	return readAffectedRows(await executeRowStatement(client, `INSERT INTO ${buildFqn(options.database, options.schema, options.table)} (${columns.map((c) => quoteIdentifier(c)).join(", ")}) VALUES (${placeholders.join(", ")})`, bindings, options));
+}
+async function batchInsert(client, options) {
+	if (options.rows.length === 0) return 0;
+	const first = options.rows[0];
+	if (!first) return 0;
+	const columns = options.columns ?? Object.keys(first);
+	if (columns.length === 0) throw new Error("batchInsert requires at least one column");
+	const bindings = new BindingBuilder();
+	const valueTuples = options.rows.map((row) => {
+		return `(${columns.map((column) => bindings.add(row[column])).join(", ")})`;
+	});
+	return readAffectedRows(await executeRowStatement(client, `INSERT INTO ${buildFqn(options.database, options.schema, options.table)} (${columns.map((c) => quoteIdentifier(c)).join(", ")}) VALUES ${valueTuples.join(", ")}`, bindings, options));
+}
+async function updateRow(client, options) {
+	const bindings = new BindingBuilder();
+	const setClause = composeSet(options.set, bindings);
+	const whereClause = composeWhere(options.where, bindings);
+	return readAffectedRows(await executeRowStatement(client, `UPDATE ${buildFqn(options.database, options.schema, options.table)} SET ${setClause}${whereClause}`, bindings, options));
+}
+async function deleteRow(client, options) {
+	if (Object.keys(options.where).length === 0) throw new Error("deleteRow refuses an empty where filter; call executeSql to truncate intentionally");
+	const bindings = new BindingBuilder();
+	const whereClause = composeWhere(options.where, bindings);
+	return readAffectedRows(await executeRowStatement(client, `DELETE FROM ${buildFqn(options.database, options.schema, options.table)}${whereClause}`, bindings, options));
+}
+function readMergeStats(result) {
+	if (result.rows.length === 0) return {
+		inserted: 0,
+		updated: 0
+	};
+	const firstRow = result.rows[0];
+	if (!firstRow) return {
+		inserted: 0,
+		updated: 0
+	};
+	const entries = Array.isArray(firstRow) ? result.columns.map((col, idx) => [col.name, firstRow[idx]]) : Object.entries(firstRow);
+	let inserted = 0;
+	let updated = 0;
+	for (const [name, value] of entries) {
+		const numeric = typeof value === "number" ? value : Number(value);
+		if (!Number.isFinite(numeric)) continue;
+		const key = name.toLowerCase();
+		if (key.includes("insert")) inserted = numeric;
+		else if (key.includes("update")) updated = numeric;
+	}
+	return {
+		inserted,
+		updated
+	};
+}
+async function upsertRow(client, options) {
+	const rowColumns = Object.keys(options.row);
+	if (rowColumns.length === 0) throw new Error("upsertRow requires at least one column in `row`");
+	if (options.matchColumns.length === 0) throw new Error("upsertRow requires at least one match column");
+	for (const column of options.matchColumns) if (!rowColumns.includes(column)) throw new Error(`upsertRow match column "${column}" is missing from row`);
+	const bindings = new BindingBuilder();
+	const srcTuples = rowColumns.map((column) => bindings.add(options.row[column]));
+	const fqn = buildFqn(options.database, options.schema, options.table);
+	rowColumns.map((c) => quoteIdentifier(c)).join(", ");
+	const matchPredicate = options.matchColumns.map((column) => `t.${quoteIdentifier(column)} = s.${quoteIdentifier(column)}`).join(" AND ");
+	const updateSet = (options.updateColumns ?? rowColumns.filter((c) => !options.matchColumns.includes(c))).map((column) => `${quoteIdentifier(column)} = s.${quoteIdentifier(column)}`).join(", ");
+	const insertCols = rowColumns.map((c) => quoteIdentifier(c)).join(", ");
+	const insertVals = rowColumns.map((c) => `s.${quoteIdentifier(c)}`).join(", ");
+	return readMergeStats(await executeRowStatement(client, `MERGE INTO ${fqn} t USING (SELECT ${srcTuples.map((placeholder, idx) => `${placeholder} AS ${quoteIdentifier(rowColumns[idx] ?? "")}`).join(", ")}) s ON ${matchPredicate}` + (updateSet ? ` WHEN MATCHED THEN UPDATE SET ${updateSet}` : "") + ` WHEN NOT MATCHED THEN INSERT (${insertCols}) VALUES (${insertVals})`, bindings, options));
+}
+async function mergeRows(client, options) {
+	return readMergeStats(await executeSql(client, {
+		statement: options.statement,
+		warehouse: options.warehouse,
+		role: options.role,
+		database: options.database,
+		schema: options.schema,
+		bindings: options.bindings
+	}));
+}
+
+//#endregion
+export { BindingBuilder, batchInsert, deleteRow, findRow, findRows, inferBinding, insertRow, mergeRows, updateRow, upsertRow };

package/dist/schemas/index.d.mts

@@ -0,0 +1,2 @@
+import { C as resultSetMetaDataSchema, D as sqlBindingValueSchema, E as snowflakeObjectRowSchema, O as sqlBindingsSchema, S as partitionInfoSchema, T as snowflakeIdentifier, _ as SnowflakeObjectRow, a as SubmitStatementInput, b as StatementContext, c as statementStatus, d as HydratedRow, f as PartitionResponse, g as ResultSetMetaData, h as PartitionInfo, i as StatementTerminalStatus, k as statementContextSchema, l as statementStatusCodeSchema, m as ColumnMeta, n as StatementResponse, o as cancelStatementResponseSchema, p as partitionResponseSchema, r as StatementStatus, s as statementResponseSchema, t as CancelStatementResponse, u as submitStatementInputSchema, v as SqlBinding, w as snowflakeFqn, x as columnMetaSchema, y as SqlBindings } from "../statements-DJL0qVNA.mjs";
+export { CancelStatementResponse, ColumnMeta, HydratedRow, PartitionInfo, PartitionResponse, ResultSetMetaData, SnowflakeObjectRow, SqlBinding, SqlBindings, StatementContext, StatementResponse, StatementStatus, StatementTerminalStatus, SubmitStatementInput, cancelStatementResponseSchema, columnMetaSchema, partitionInfoSchema, partitionResponseSchema, resultSetMetaDataSchema, snowflakeFqn, snowflakeIdentifier, snowflakeObjectRowSchema, sqlBindingValueSchema, sqlBindingsSchema, statementContextSchema, statementResponseSchema, statementStatus, statementStatusCodeSchema, submitStatementInputSchema };

package/dist/schemas/index.mjs

@@ -0,0 +1,4 @@
+import { a as snowflakeIdentifier, c as sqlBindingsSchema, i as snowflakeFqn, l as statementContextSchema, n as partitionInfoSchema, o as snowflakeObjectRowSchema, r as resultSetMetaDataSchema, s as sqlBindingValueSchema, t as columnMetaSchema } from "../common-BnKTPQXc.mjs";
+import { a as submitStatementInputSchema, i as statementStatusCodeSchema, n as statementResponseSchema, o as partitionResponseSchema, r as statementStatus, t as cancelStatementResponseSchema } from "../statements-B2ThF_4b.mjs";
+
+export { cancelStatementResponseSchema, columnMetaSchema, partitionInfoSchema, partitionResponseSchema, resultSetMetaDataSchema, snowflakeFqn, snowflakeIdentifier, snowflakeObjectRowSchema, sqlBindingValueSchema, sqlBindingsSchema, statementContextSchema, statementResponseSchema, statementStatus, statementStatusCodeSchema, submitStatementInputSchema };

package/dist/schemas-catalog.d.mts

@@ -0,0 +1,2 @@
+import { CatalogResult, FindSchemasOptions, ShowSchemasOptions, findSchemas, showSchemas } from "./catalog.mjs";
+export { type CatalogResult, type FindSchemasOptions, type ShowSchemasOptions, findSchemas, showSchemas };

package/dist/schemas-catalog.mjs

@@ -0,0 +1,3 @@
+import { findSchemas, showSchemas } from "./catalog.mjs";
+
+export { findSchemas, showSchemas };

package/dist/shares.d.mts

@@ -0,0 +1,56 @@
+import { SnowflakeClient } from "./client.mjs";
+import { d as HydratedRow } from "./statements-DJL0qVNA.mjs";
+import { CatalogResult, ShowOptions, showShares } from "./catalog.mjs";
+
+//#region src/shares.d.ts
+interface ShareContext {
+  readonly warehouse?: string;
+  readonly role?: string;
+}
+interface CreateShareOptions extends ShareContext {
+  readonly name: string;
+  readonly orReplace?: boolean;
+  readonly ifNotExists?: boolean;
+  readonly comment?: string;
+}
+declare function createShare(client: SnowflakeClient, options: CreateShareOptions): Promise<void>;
+interface AlterShareOptions extends ShareContext {
+  readonly name: string;
+  readonly ifExists?: boolean;
+  /** Replace the full account list via `SET ACCOUNTS = (...)`. */
+  readonly setAccounts?: readonly string[];
+  /** `ADD ACCOUNTS = (...)`. */
+  readonly addAccounts?: readonly string[];
+  /** `REMOVE ACCOUNTS = (...)`. */
+  readonly removeAccounts?: readonly string[];
+  /** `SET COMMENT = '...'`. */
+  readonly comment?: string;
+  /** `UNSET COMMENT`. */
+  readonly unsetComment?: boolean;
+}
+declare function alterShare(client: SnowflakeClient, options: AlterShareOptions): Promise<void>;
+interface DropShareOptions extends ShareContext {
+  readonly name: string;
+  readonly ifExists?: boolean;
+}
+declare function dropShare(client: SnowflakeClient, options: DropShareOptions): Promise<void>;
+interface DescribeShareOptions extends ShareContext {
+  readonly name: string;
+}
+declare function describeShare(client: SnowflakeClient, options: DescribeShareOptions): Promise<readonly HydratedRow[]>;
+interface AddAccountsToShareOptions extends ShareContext {
+  readonly name: string;
+  readonly accounts: readonly string[];
+  readonly ifExists?: boolean;
+  /** Optional `SHARE_RESTRICTIONS = TRUE|FALSE` appended to ADD ACCOUNTS. */
+  readonly shareRestrictions?: boolean;
+}
+declare function addAccountsToShare(client: SnowflakeClient, options: AddAccountsToShareOptions): Promise<void>;
+interface RemoveAccountsFromShareOptions extends ShareContext {
+  readonly name: string;
+  readonly accounts: readonly string[];
+  readonly ifExists?: boolean;
+}
+declare function removeAccountsFromShare(client: SnowflakeClient, options: RemoveAccountsFromShareOptions): Promise<void>;
+//#endregion
+export { AddAccountsToShareOptions, AlterShareOptions, type CatalogResult, CreateShareOptions, DescribeShareOptions, DropShareOptions, RemoveAccountsFromShareOptions, ShareContext, type ShowOptions, addAccountsToShare, alterShare, createShare, describeShare, dropShare, removeAccountsFromShare, showShares };

package/dist/shares.mjs

@@ -0,0 +1,77 @@
+import { executeSql } from "./sql.mjs";
+import { a as quoteLiteral, i as quoteIdentifier } from "./sql-safety-CywdR3EP.mjs";
+import { showShares } from "./catalog.mjs";
+
+//#region src/shares.ts
+async function createShare(client, options) {
+	const prefix = `CREATE${options.orReplace ? " OR REPLACE" : ""} SHARE${options.ifNotExists ? " IF NOT EXISTS" : ""}`;
+	const comment = options.comment ? ` COMMENT = ${quoteLiteral(options.comment)}` : "";
+	await executeSql(client, {
+		statement: `${prefix} ${quoteIdentifier(options.name)}${comment}`,
+		warehouse: options.warehouse,
+		role: options.role
+	});
+}
+/**
+* Snowflake account identifiers for shares take the form
+* `<orgName>.<accountName>` (unquoted). We validate the shape lightly
+* and pass it through without quoting because Snowflake treats quoted
+* identifiers here as case-sensitive names which would not match the
+* real account.
+*/
+const ACCOUNT_ID_RE = /^[A-Za-z0-9_]+\.[A-Za-z0-9_]+$/u;
+function renderAccountList(accounts) {
+	if (accounts.length === 0) throw new Error("accounts must be a non-empty list");
+	for (const a of accounts) if (!ACCOUNT_ID_RE.test(a)) throw new Error(`Invalid account identifier "${a}" — expected "<orgName>.<accountName>" (letters, digits, underscore)`);
+	return accounts.join(", ");
+}
+async function alterShare(client, options) {
+	let tail;
+	if (options.addAccounts) tail = `ADD ACCOUNTS = (${renderAccountList(options.addAccounts)})`;
+	else if (options.removeAccounts) tail = `REMOVE ACCOUNTS = (${renderAccountList(options.removeAccounts)})`;
+	else if (options.setAccounts) tail = `SET ACCOUNTS = (${renderAccountList(options.setAccounts)})`;
+	else if (options.comment !== void 0) tail = `SET COMMENT = ${quoteLiteral(options.comment)}`;
+	else if (options.unsetComment) tail = "UNSET COMMENT";
+	else throw new Error("alterShare requires one of: setAccounts / addAccounts / removeAccounts / comment / unsetComment");
+	await executeSql(client, {
+		statement: `ALTER SHARE${options.ifExists ? " IF EXISTS" : ""} ${quoteIdentifier(options.name)} ${tail}`,
+		warehouse: options.warehouse,
+		role: options.role
+	});
+}
+async function dropShare(client, options) {
+	await executeSql(client, {
+		statement: `DROP SHARE${options.ifExists ? " IF EXISTS" : ""} ${quoteIdentifier(options.name)}`,
+		warehouse: options.warehouse,
+		role: options.role
+	});
+}
+async function describeShare(client, options) {
+	return (await executeSql(client, {
+		statement: `DESCRIBE SHARE ${quoteIdentifier(options.name)}`,
+		warehouse: options.warehouse,
+		role: options.role
+	})).rows;
+}
+async function addAccountsToShare(client, options) {
+	const ifExists = options.ifExists ? " IF EXISTS" : "";
+	const accounts = renderAccountList(options.accounts);
+	const restrictions = options.shareRestrictions !== void 0 ? ` SHARE_RESTRICTIONS = ${options.shareRestrictions ? "TRUE" : "FALSE"}` : "";
+	await executeSql(client, {
+		statement: `ALTER SHARE${ifExists} ${quoteIdentifier(options.name)} ADD ACCOUNTS = (${accounts})${restrictions}`,
+		warehouse: options.warehouse,
+		role: options.role
+	});
+}
+async function removeAccountsFromShare(client, options) {
+	const ifExists = options.ifExists ? " IF EXISTS" : "";
+	const accounts = renderAccountList(options.accounts);
+	await executeSql(client, {
+		statement: `ALTER SHARE${ifExists} ${quoteIdentifier(options.name)} REMOVE ACCOUNTS = (${accounts})`,
+		warehouse: options.warehouse,
+		role: options.role
+	});
+}
+
+//#endregion
+export { addAccountsToShare, alterShare, createShare, describeShare, dropShare, removeAccountsFromShare, showShares };

package/dist/sql-options-2k5xQ-oS.d.mts

@@ -0,0 +1,32 @@
+//#region src/sql-options.d.ts
+/**
+ * Option-list composition helpers for Snowflake DDL/DML.
+ *
+ * Most CREATE/ALTER statements (stages, file formats, pipes, tasks, COPY
+ * options, warehouses) accept option lists like:
+ *
+ *   FILE_FORMAT = (TYPE = 'CSV' FIELD_DELIMITER = '|' SKIP_HEADER = 1)
+ *   CREDENTIALS = (AWS_KEY_ID = 'abc' AWS_SECRET_KEY = 'xyz')
+ *   COPY_OPTIONS = (ON_ERROR = 'CONTINUE' PURGE = TRUE)
+ *
+ * These helpers compose those lists safely:
+ *  - String values are quoted with {@link quoteLiteral}.
+ *  - Numbers, booleans, and raw-marked values pass through verbatim.
+ *  - Nested option maps render as parenthesised sub-lists.
+ *  - Ordering is preserved in insertion order.
+ */
+/**
+ * A scalar that can appear on the RHS of an option. Pre-built raw SQL can
+ * be passed via {@link rawOption} when callers need to inject a keyword
+ * (e.g. `AUTO_REFRESH = TRUE`, `ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')`).
+ */
+type OptionScalar = string | number | bigint | boolean | null | undefined | RawSql | OptionMap | readonly OptionScalar[];
+interface OptionMap {
+  readonly [key: string]: OptionScalar;
+}
+/** Marker type for a pre-formatted SQL fragment. */
+interface RawSql {
+  readonly __rawSql: string;
+}
+//#endregion
+export { OptionMap as t };

package/dist/sql-options-DI-OmLU6.mjs

@@ -0,0 +1,79 @@
+import { a as quoteLiteral } from "./sql-safety-CywdR3EP.mjs";
+
+//#region src/sql-options.ts
+/**
+* Option-list composition helpers for Snowflake DDL/DML.
+*
+* Most CREATE/ALTER statements (stages, file formats, pipes, tasks, COPY
+* options, warehouses) accept option lists like:
+*
+*   FILE_FORMAT = (TYPE = 'CSV' FIELD_DELIMITER = '|' SKIP_HEADER = 1)
+*   CREDENTIALS = (AWS_KEY_ID = 'abc' AWS_SECRET_KEY = 'xyz')
+*   COPY_OPTIONS = (ON_ERROR = 'CONTINUE' PURGE = TRUE)
+*
+* These helpers compose those lists safely:
+*  - String values are quoted with {@link quoteLiteral}.
+*  - Numbers, booleans, and raw-marked values pass through verbatim.
+*  - Nested option maps render as parenthesised sub-lists.
+*  - Ordering is preserved in insertion order.
+*/
+function isRawSql(value) {
+	return typeof value === "object" && value !== null && typeof value.__rawSql === "string";
+}
+function isOptionMap(value) {
+	if (value === null || typeof value !== "object") return false;
+	if (Array.isArray(value)) return false;
+	if (isRawSql(value)) return false;
+	if (value instanceof Date) return false;
+	return true;
+}
+function formatScalar(value) {
+	if (value === void 0) return void 0;
+	if (value === null) return "NULL";
+	if (isRawSql(value)) return value.__rawSql;
+	if (typeof value === "string") return quoteLiteral(value);
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new TypeError("Cannot serialise NaN/Infinity as a Snowflake option value");
+		return value.toString();
+	}
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+	if (Array.isArray(value)) return `(${value.map((item) => formatScalar(item)).filter((item) => item !== void 0).join(", ")})`;
+	if (isOptionMap(value)) return formatOptionGroup(value);
+	throw new TypeError(`Unsupported Snowflake option value: ${typeof value}`);
+}
+/** Render a map like `(KEY = value KEY2 = 'literal')`. Empty maps render as `()`. */
+function formatOptionGroup(map) {
+	const parts = [];
+	for (const [key, value] of Object.entries(map)) {
+		const rendered = formatScalar(value);
+		if (rendered === void 0) continue;
+		parts.push(`${key.toUpperCase()} = ${rendered}`);
+	}
+	return `(${parts.join(" ")})`;
+}
+/**
+* Render a map as a space-separated option list (no wrapping parens). This
+* is the form used directly in `CREATE STAGE ... URL='...' CREDENTIALS=(..)`
+* where top-level options sit alongside the object name.
+*/
+function formatOptions(map) {
+	const parts = [];
+	for (const [key, value] of Object.entries(map)) {
+		const rendered = formatScalar(value);
+		if (rendered === void 0) continue;
+		parts.push(`${key.toUpperCase()} = ${rendered}`);
+	}
+	return parts.join(" ");
+}
+/**
+* Render a nested option group as ` KEY = (...)` — returns empty string when
+* the map is undefined so callers can compose optional clauses inline.
+*/
+function renderOptionGroup(key, map) {
+	if (!map) return "";
+	return ` ${key.toUpperCase()} = ${formatOptionGroup(map)}`;
+}
+
+//#endregion
+export { renderOptionGroup as n, formatOptions as t };

package/dist/sql-safety-CywdR3EP.mjs

@@ -0,0 +1,56 @@
+//#region src/sql-safety.ts
+/**
+* SQL identifier + literal escaping utilities.
+*
+* Snowflake follows ANSI rules:
+*  - Identifiers: wrap in `"..."`; internal `"` is escaped as `""`.
+*  - String literals: wrap in `'...'`; internal `'` is escaped as `''`.
+*  - Numeric, boolean, null literals are written raw.
+*
+* Every domain module that composes SQL goes through these helpers — they
+* are the package's sole defense against SQL injection from operation
+* inputs that name identifiers or match patterns.
+*/
+const UNQUOTED_IDENT = /^[A-Z_][A-Z0-9_$]*$/u;
+/**
+* Return a double-quoted form of the identifier, escaping embedded
+* double-quotes. When `allowUnquoted` is true and the input is already a
+* canonical unquoted identifier, return it verbatim so the resulting SQL
+* is more readable.
+*/
+function quoteIdentifier(name, options = {}) {
+	if (options.allowUnquoted && UNQUOTED_IDENT.test(name)) return name;
+	return `"${name.replaceAll("\"", "\"\"")}"`;
+}
+/**
+* Build a fully-qualified name from up to three segments. Each segment is
+* independently quoted. Missing leading segments are omitted.
+*/
+function buildFqn(...segments) {
+	return segments.filter((segment) => segment !== void 0 && segment.length > 0).map((segment) => quoteIdentifier(segment)).join(".");
+}
+/**
+* Quote a Snowflake string literal, doubling embedded single quotes.
+*/
+function quoteLiteral(value) {
+	return `'${value.replaceAll("'", "''")}'`;
+}
+/**
+* Compose `LIKE '<pattern>'` when `pattern` is provided, empty string
+* otherwise. Pattern is escaped as a SQL literal.
+*/
+function likeClause(pattern) {
+	return pattern ? ` LIKE ${quoteLiteral(pattern)}` : "";
+}
+/**
+* Compose `IN <scopeKeyword> <quoted identifier>` clause (e.g. "IN DATABASE
+* MYDB"). Caller supplies a pre-joined identifier (fqn already built).
+*/
+function inClause(scopeKeyword, target) {
+	if (!target) return "";
+	if (scopeKeyword === "ACCOUNT") return " IN ACCOUNT";
+	return ` IN ${scopeKeyword} ${target}`;
+}
+
+//#endregion
+export { quoteLiteral as a, quoteIdentifier as i, inClause as n, likeClause as r, buildFqn as t };

package/dist/sql.d.mts

@@ -0,0 +1,84 @@
+import { SnowflakeClient } from "./client.mjs";
+import { a as SubmitStatementInput, d as HydratedRow, f as PartitionResponse, m as ColumnMeta, n as StatementResponse } from "./statements-DJL0qVNA.mjs";
+//#region src/sql.d.ts
+interface SubmitOptions {
+  readonly async?: boolean;
+  readonly requestId?: string;
+}
+interface SubmitResult {
+  readonly response: StatementResponse;
+  readonly status: 'done' | 'failed' | 'pending' | 'cancelled';
+  readonly httpStatus: number;
+}
+/**
+ * Submit a statement. When `async: true` (or the server chooses async) we
+ * return the inflated response envelope along with the `pending` status so
+ * callers can poll via {@link getStatement} / {@link waitForStatement}.
+ *
+ * The SQL API itself keys idempotency on the `requestId` query param which
+ * {@link SnowflakeClient} auto-populates — callers can override it per
+ * request when they need deterministic retries.
+ */
+declare function submitStatement(client: SnowflakeClient, input: SubmitStatementInput, options?: SubmitOptions): Promise<SubmitResult>;
+/**
+ * Fetch the current status of a previously submitted async statement. Returns
+ * both the envelope and the derived `status` bucket.
+ */
+declare function getStatement(client: SnowflakeClient, handle: string, options?: {
+  readonly partition?: number;
+}): Promise<SubmitResult>;
+/**
+ * POST `/cancel`. Snowflake responds with `code: 333335` on success — we
+ * normalise anything else into a {@link SnowflakeApiError}.
+ */
+declare function cancelStatement(client: SnowflakeClient, handle: string): Promise<void>;
+interface ExecuteSqlOptions extends SubmitOptions {
+  readonly pollIntervalMs?: number;
+  readonly maxWaitMs?: number;
+  readonly hydrate?: boolean;
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => Promise<void>;
+}
+interface ExecuteSqlResult<TRow = HydratedRow> {
+  readonly handle: string;
+  readonly columns: readonly ColumnMeta[];
+  readonly rows: readonly TRow[];
+  readonly envelope: StatementResponse;
+  readonly partitions: number;
+}
+/**
+ * Submit + wait + fetch all partitions in one go. The returned rows are
+ * hydrated into objects keyed by column name by default; pass
+ * `hydrate: false` to get the raw tuple form.
+ */
+declare function executeSql(client: SnowflakeClient, input: SubmitStatementInput, options?: ExecuteSqlOptions): Promise<ExecuteSqlResult<HydratedRow | readonly unknown[]>>;
+/**
+ * Composio `SNOWFLAKE_BASIC_RUN_QUERY` parity — requires an explicit
+ * database + schema to match the published BASIC shape.
+ */
+declare function runQuery(client: SnowflakeClient, input: {
+  readonly statement: string;
+  readonly database: string;
+  readonly schema_name: string;
+  readonly warehouse?: string;
+  readonly role?: string;
+}, options?: ExecuteSqlOptions): Promise<ExecuteSqlResult<HydratedRow | readonly unknown[]>>;
+/**
+ * Fetch a single partition for a known handle.
+ */
+declare function getStatementResultPartition(client: SnowflakeClient, handle: string, partition: number): Promise<PartitionResponse>;
+/**
+ * Async iterator over every partition for a handle. Useful for streaming
+ * large result sets into downstream pipelines.
+ */
+declare function iterateStatementResult(client: SnowflakeClient, handle: string, options?: {
+  readonly maxPartitions?: number;
+}): AsyncGenerator<PartitionResponse, void, void>;
+/**
+ * Blocking helper: polls `getStatement` until the statement reaches a
+ * terminal status or the `maxWaitMs` budget elapses. Returns the terminal
+ * envelope (throws for `failed` / `cancelled`).
+ */
+declare function waitForStatement(client: SnowflakeClient, handle: string, options?: ExecuteSqlOptions): Promise<StatementResponse>;
+//#endregion
+export { ExecuteSqlOptions, ExecuteSqlResult, SubmitOptions, SubmitResult, cancelStatement, executeSql, getStatement, getStatementResultPartition, iterateStatementResult, runQuery, submitStatement, waitForStatement };