neon 3.0.0 → 3.1.0

package/dist/utils/flags.js

@@ -1,52 +1,40 @@
+//#region src/utils/flags.ts
 /**
- * Strict readers for flags whose value decides how much a credential can reach.
- *
- * These live apart from any one command because both `api-keys` and `profile create` mint
- * keys, and a lenient reading of a scope flag has the same consequence in either: the flag
- * reads as falsy, the scope check falls through, and an **account** key is minted instead of
- * the narrow one that was asked for. Two copies of that check is one copy too many.
- */
+* Strict readers for flags whose value decides how much a credential can reach.
+*
+* These live apart from any one command because both `api-keys` and `profile create` mint
+* keys, and a lenient reading of a scope flag has the same consequence in either: the flag
+* reads as falsy, the scope check falls through, and an **account** key is minted instead of
+* the narrow one that was asked for. Two copies of that check is one copy too many.
+*/
 /**
- * A flag is either absent, or exactly one non-empty string. Anything else is an error.
- *
- * - `--org-id ""` — an unset shell variable; empty string, which is falsy.
- * - `--no-org-id` — yargs boolean negation; `false`, which is falsy.
- * - `--org-id a --org-id b` — an array, which would reach the API as `a,b`.
- *
- * A misspelled flag never binds and cannot be seen here; `.strict()` rejects it. Anything
- * after a `--` terminator is handled by {@link noPassthrough}.
- */
-export const single = (name, { required = false } = {}) => (value) => {
-    if (value === undefined)
-        return undefined;
-    if (Array.isArray(value)) {
-        throw new Error(`--${name} was given more than once. Pass it at most once.`);
-    }
-    // `--no-x` is the negation form and yields `false`, so name it rather than telling
-    // the user their value was empty when they never gave one.
-    if (value === false) {
-        throw new Error(required
-            ? `--no-${name} is not valid: --${name} is required.`
-            : `--no-${name} is not a valid way to skip --${name}. Omit the flag entirely.`);
-    }
-    if (typeof value !== "string" || value.trim() === "") {
-        throw new Error(required
-            ? `--${name} needs a value.`
-            : `--${name} needs a value. Pass one, or omit the flag entirely.`);
-    }
-    return value;
+* A flag is either absent, or exactly one non-empty string. Anything else is an error.
+*
+* - `--org-id ""` — an unset shell variable; empty string, which is falsy.
+* - `--no-org-id` — yargs boolean negation; `false`, which is falsy.
+* - `--org-id a --org-id b` — an array, which would reach the API as `a,b`.
+*
+* A misspelled flag never binds and cannot be seen here; `.strict()` rejects it. Anything
+* after a `--` terminator is handled by {@link noPassthrough}.
+*/
+const single = (name, { required = false } = {}) => (value) => {
+	if (value === void 0) return void 0;
+	if (Array.isArray(value)) throw new Error(`--${name} was given more than once. Pass it at most once.`);
+	if (value === false) throw new Error(required ? `--no-${name} is not valid: --${name} is required.` : `--no-${name} is not a valid way to skip --${name}. Omit the flag entirely.`);
+	if (typeof value !== "string" || value.trim() === "") throw new Error(required ? `--${name} needs a value.` : `--${name} needs a value. Pass one, or omit the flag entirely.`);
+	return value;
 };
 /**
- * Refuse arguments after a `--` terminator.
- *
- * The CLI sets `populate--`, so everything past `--` lands in `argv["--"]` where `.strict()`
- * never looks — `create --name x -- --project-id p` would parse cleanly and mint an account
- * key from a line that names the scope flag.
- */
-export const noPassthrough = (command) => (argv) => {
-    const rest = argv["--"];
-    if (Array.isArray(rest) && rest.length > 0) {
-        throw new Error(`${command} takes no arguments after \`--\`, and options placed there are ignored rather than applied. Remove the \`--\`.`);
-    }
-    return true;
+* Refuse arguments after a `--` terminator.
+*
+* The CLI sets `populate--`, so everything past `--` lands in `argv["--"]` where `.strict()`
+* never looks — `create --name x -- --project-id p` would parse cleanly and mint an account
+* key from a line that names the scope flag.
+*/
+const noPassthrough = (command) => (argv) => {
+	const rest = argv["--"];
+	if (Array.isArray(rest) && rest.length > 0) throw new Error(`${command} takes no arguments after \`--\`, and options placed there are ignored rather than applied. Remove the \`--\`.`);
+	return true;
 };
+//#endregion
+export { noPassthrough, single };

package/dist/utils/formats.js

@@ -1,18 +1,11 @@
+//#region src/utils/formats.ts
 const HAIKU_REGEX = /^[a-z0-9]+-[a-z0-9]+-[a-z0-9]+$/;
-export const looksLikeBranchId = (branch) => branch.startsWith("br-") && HAIKU_REGEX.test(branch.substring(3));
+const looksLikeBranchId = (branch) => branch.startsWith("br-") && HAIKU_REGEX.test(branch.substring(3));
 const LSN_REGEX = /^[a-fA-F0-9]{1,8}\/[a-fA-F0-9]{1,8}$/;
-export const looksLikeLSN = (lsn) => LSN_REGEX.test(lsn);
-export const looksLikeTimestamp = (timestamp) => {
-    if (isNaN(Date.parse(timestamp)))
-        return false;
-    /**
-     * @info
-     * Check for ISO 8601/RFC 3339 format patterns
-     * Must contain 'T' separator and end with 'Z' or timezone offset
-     *
-     * `Date.parse` aggressive parsing will attempt a date out of any string.
-     * so if a branch name has a number, `Date.parse` will return a valid timestamp.
-     */
-    const iso8601Regex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?([+-]\d{2}:\d{2}|Z)$/;
-    return iso8601Regex.test(timestamp);
+const looksLikeLSN = (lsn) => LSN_REGEX.test(lsn);
+const looksLikeTimestamp = (timestamp) => {
+	if (isNaN(Date.parse(timestamp))) return false;
+	return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?([+-]\d{2}:\d{2}|Z)$/.test(timestamp);
 };
+//#endregion
+export { looksLikeBranchId, looksLikeLSN, looksLikeTimestamp };

package/dist/utils/git_diff.js

@@ -1,90 +1,79 @@
 import chalk from "chalk";
 import { structuredPatch } from "diff";
+//#region src/utils/git_diff.ts
 /**
- * Color palette for the rendered diff. When `color` is false every entry is the
- * identity function, so the exact same layout is emitted without ANSI codes
- * (for `--no-color`, non-TTY pipes, and stable test snapshots).
- */
+* Color palette for the rendered diff. When `color` is false every entry is the
+* identity function, so the exact same layout is emitted without ANSI codes
+* (for `--no-color`, non-TTY pipes, and stable test snapshots).
+*/
 const palette = (color) => {
-    const id = (s) => s;
-    if (!color) {
-        return {
-            header: id,
-            removedFile: id,
-            addedFile: id,
-            hunk: id,
-            added: id,
-            removed: id,
-            noNewline: id,
-        };
-    }
-    return {
-        header: (s) => chalk.bold(s),
-        removedFile: (s) => chalk.bold.red(s),
-        addedFile: (s) => chalk.bold.green(s),
-        hunk: (s) => chalk.cyan(s),
-        added: (s) => chalk.green(s),
-        removed: (s) => chalk.red(s),
-        noNewline: (s) => chalk.dim(s),
-    };
+	const id = (s) => s;
+	if (!color) return {
+		header: id,
+		removedFile: id,
+		addedFile: id,
+		hunk: id,
+		added: id,
+		removed: id,
+		noNewline: id
+	};
+	return {
+		header: (s) => chalk.bold(s),
+		removedFile: (s) => chalk.bold.red(s),
+		addedFile: (s) => chalk.bold.green(s),
+		hunk: (s) => chalk.cyan(s),
+		added: (s) => chalk.green(s),
+		removed: (s) => chalk.red(s),
+		noNewline: (s) => chalk.dim(s)
+	};
 };
 const branchLabel = (schema) => `${schema.branchName} (${schema.branchId})`;
 /**
- * Render a single database's schema comparison as a git-style unified diff.
- *
- * Pure: given the two schemas it computes hunks with `diff`'s `structuredPatch`
- * and lays them out like `git diff` — a bold header, red `---` / green `+++`
- * branch lines, cyan `@@` hunk headers, and green/red line bodies. Returns
- * `hasChanges: false` with empty text when the two schemas are identical.
- */
-export const renderDatabaseSchemaDiff = (diff, opts) => {
-    const patch = structuredPatch(diff.database, diff.database, diff.before.sql, diff.after.sql, "", "", { context: 3 });
-    if (patch.hunks.length === 0) {
-        return { database: diff.database, hasChanges: false, text: "" };
-    }
-    const paint = palette(opts.color);
-    const lines = [
-        paint.header(`diff --neon database ${diff.database}`),
-        paint.removedFile(`--- ${branchLabel(diff.before)}`),
-        paint.addedFile(`+++ ${branchLabel(diff.after)}`),
-    ];
-    for (const hunk of patch.hunks) {
-        lines.push(paint.hunk(`@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`));
-        for (const line of hunk.lines) {
-            // `structuredPatch` prefixes every line: '+' added, '-' removed,
-            // ' ' unchanged context, and '\' for the "No newline at end of file"
-            // marker. Color the first three; dim the marker; leave context plain.
-            if (line.startsWith("+")) {
-                lines.push(paint.added(line));
-            }
-            else if (line.startsWith("-")) {
-                lines.push(paint.removed(line));
-            }
-            else if (line.startsWith("\\")) {
-                lines.push(paint.noNewline(line));
-            }
-            else {
-                lines.push(line);
-            }
-        }
-    }
-    return {
-        database: diff.database,
-        hasChanges: true,
-        text: lines.join("\n"),
-    };
+* Render a single database's schema comparison as a git-style unified diff.
+*
+* Pure: given the two schemas it computes hunks with `diff`'s `structuredPatch`
+* and lays them out like `git diff` — a bold header, red `---` / green `+++`
+* branch lines, cyan `@@` hunk headers, and green/red line bodies. Returns
+* `hasChanges: false` with empty text when the two schemas are identical.
+*/
+const renderDatabaseSchemaDiff = (diff, opts) => {
+	const patch = structuredPatch(diff.database, diff.database, diff.before.sql, diff.after.sql, "", "", { context: 3 });
+	if (patch.hunks.length === 0) return {
+		database: diff.database,
+		hasChanges: false,
+		text: ""
+	};
+	const paint = palette(opts.color);
+	const lines = [
+		paint.header(`diff --neon database ${diff.database}`),
+		paint.removedFile(`--- ${branchLabel(diff.before)}`),
+		paint.addedFile(`+++ ${branchLabel(diff.after)}`)
+	];
+	for (const hunk of patch.hunks) {
+		lines.push(paint.hunk(`@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`));
+		for (const line of hunk.lines) if (line.startsWith("+")) lines.push(paint.added(line));
+		else if (line.startsWith("-")) lines.push(paint.removed(line));
+		else if (line.startsWith("\\")) lines.push(paint.noNewline(line));
+		else lines.push(line);
+	}
+	return {
+		database: diff.database,
+		hasChanges: true,
+		text: lines.join("\n")
+	};
 };
 /**
- * Render every database's diff into one report, keeping only databases whose
- * schema actually changed. `hasChanges` is false when nothing changed across
- * all databases, letting the caller print a single "no differences" note.
- */
-export const renderSchemaDiffReport = (diffs, opts) => {
-    const rendered = diffs.map((diff) => renderDatabaseSchemaDiff(diff, opts));
-    const changed = rendered.filter((r) => r.hasChanges);
-    return {
-        hasChanges: changed.length > 0,
-        text: changed.map((r) => r.text).join("\n\n"),
-        changedDatabases: changed.map((r) => r.database),
-    };
+* Render every database's diff into one report, keeping only databases whose
+* schema actually changed. `hasChanges` is false when nothing changed across
+* all databases, letting the caller print a single "no differences" note.
+*/
+const renderSchemaDiffReport = (diffs, opts) => {
+	const changed = diffs.map((diff) => renderDatabaseSchemaDiff(diff, opts)).filter((r) => r.hasChanges);
+	return {
+		hasChanges: changed.length > 0,
+		text: changed.map((r) => r.text).join("\n\n"),
+		changedDatabases: changed.map((r) => r.database)
+	};
 };
+//#endregion
+export { renderDatabaseSchemaDiff, renderSchemaDiffReport };

package/dist/utils/inspect_db.js

@@ -1,153 +1,111 @@
-import { parseConnectionUri } from "../psql/index.js";
-import { PgConnection } from "../psql/wire/connection.js";
 import { EndpointType } from "./api_enums.js";
 import { branchIdFromProps } from "./enrichers.js";
 import { parsePITBranch } from "./point_in_time.js";
-export const SSL_MODES = [
-    "require",
-    "verify-ca",
-    "verify-full",
-    "omit",
+import { PgConnection } from "../psql/wire/connection.js";
+import { parseConnectionUri } from "../psql/index.js";
+//#region src/utils/inspect_db.ts
+const SSL_MODES = [
+	"require",
+	"verify-ca",
+	"verify-full",
+	"omit"
 ];
 /**
- * Resolve a branch's live Postgres connection details via the Neon API
- * (endpoint → role → password → database → URL, honoring point-in-time,
- * pooling, prisma tuning, and SSL mode). Mirrors how `connection-string`
- * resolves a branch so `inspect db` connects the same way.
- */
-export const resolveConnectionUri = async (props) => {
-    const projectId = props.projectId;
-    const parsedPIT = props.branch
-        ? parsePITBranch(props.branch)
-        : { tag: "head", branch: "" };
-    if (props.branch) {
-        props.branch = parsedPIT.branch;
-    }
-    const branchId = await branchIdFromProps(props);
-    const { data: { endpoints }, } = await props.apiClient.listProjectBranchEndpoints(projectId, branchId);
-    const matchEndpointType = props.endpointType ?? EndpointType.ReadWrite;
-    let endpoint = endpoints.find((e) => e.type === matchEndpointType);
-    if (!endpoint && props.endpointType == null) {
-        endpoint = endpoints[0];
-    }
-    if (!endpoint) {
-        throw new Error(`No ${props.endpointType ?? ""} endpoint found for the branch: ${branchId}`);
-    }
-    const role = props.roleName ||
-        (await props.apiClient
-            .listProjectBranchRoles(projectId, branchId)
-            .then(({ data }) => {
-            if (data.roles.length === 0) {
-                throw new Error(`No roles found for the branch: ${branchId}`);
-            }
-            if (data.roles.length === 1) {
-                return data.roles[0].name;
-            }
-            throw new Error(`Multiple roles found for the branch, please provide one with the --role-name option: ${data.roles
-                .map((r) => r.name)
-                .join(", ")}`);
-        }));
-    const { data: { databases: branchDatabases }, } = await props.apiClient.listProjectBranchDatabases(projectId, branchId);
-    const database = props.databaseName ||
-        (() => {
-            if (branchDatabases.length === 0) {
-                throw new Error(`No databases found for the branch: ${branchId}`);
-            }
-            if (branchDatabases.length === 1) {
-                return branchDatabases[0].name;
-            }
-            throw new Error(`Multiple databases found for the branch, please provide one with the --database-name option: ${branchDatabases
-                .map((d) => d.name)
-                .join(", ")}`);
-        })();
-    if (!branchDatabases.find((d) => d.name === database)) {
-        throw new Error(`Database not found: ${database}`);
-    }
-    const { data: { password }, } = await props.apiClient.getProjectBranchRolePassword(props.projectId, endpoint.branch_id, role);
-    let host = props.pooled
-        ? endpoint.host.replace(endpoint.id, `${endpoint.id}-pooler`)
-        : endpoint.host;
-    if (parsedPIT.tag !== "head") {
-        host = endpoint.host.replace(endpoint.id, endpoint.branch_id);
-    }
-    const connectionString = new URL(`postgresql://${host}`);
-    connectionString.pathname = database;
-    connectionString.username = role;
-    connectionString.password = password;
-    if (props.prisma) {
-        connectionString.searchParams.set("connect_timeout", "30");
-        if (props.pooled) {
-            connectionString.searchParams.set("pool_timeout", "30");
-            connectionString.searchParams.set("pgbouncer", "true");
-        }
-    }
-    const ssl = props.ssl ?? "require";
-    if (ssl !== "omit") {
-        connectionString.searchParams.set("sslmode", ssl);
-        connectionString.searchParams.set("channel_binding", "require");
-    }
-    if (parsedPIT.tag === "lsn") {
-        connectionString.searchParams.set("options", `neon_lsn:${parsedPIT.lsn}`);
-    }
-    else if (parsedPIT.tag === "timestamp") {
-        connectionString.searchParams.set("options", `neon_timestamp:${parsedPIT.timestamp}`);
-    }
-    return {
-        connectionUri: connectionString.toString(),
-        host,
-        role,
-        password,
-        database,
-        options: connectionString.searchParams.toString(),
-    };
+* Resolve a branch's live Postgres connection details via the Neon API
+* (endpoint → role → password → database → URL, honoring point-in-time,
+* pooling, prisma tuning, and SSL mode). Mirrors how `connection-string`
+* resolves a branch so `inspect db` connects the same way.
+*/
+const resolveConnectionUri = async (props) => {
+	const projectId = props.projectId;
+	const parsedPIT = props.branch ? parsePITBranch(props.branch) : {
+		tag: "head",
+		branch: ""
+	};
+	if (props.branch) props.branch = parsedPIT.branch;
+	const branchId = await branchIdFromProps(props);
+	const { data: { endpoints } } = await props.apiClient.listProjectBranchEndpoints(projectId, branchId);
+	const matchEndpointType = props.endpointType ?? EndpointType.ReadWrite;
+	let endpoint = endpoints.find((e) => e.type === matchEndpointType);
+	if (!endpoint && props.endpointType == null) endpoint = endpoints[0];
+	if (!endpoint) throw new Error(`No ${props.endpointType ?? ""} endpoint found for the branch: ${branchId}`);
+	const role = props.roleName || await props.apiClient.listProjectBranchRoles(projectId, branchId).then(({ data }) => {
+		if (data.roles.length === 0) throw new Error(`No roles found for the branch: ${branchId}`);
+		if (data.roles.length === 1) return data.roles[0].name;
+		throw new Error(`Multiple roles found for the branch, please provide one with the --role-name option: ${data.roles.map((r) => r.name).join(", ")}`);
+	});
+	const { data: { databases: branchDatabases } } = await props.apiClient.listProjectBranchDatabases(projectId, branchId);
+	const database = props.databaseName || (() => {
+		if (branchDatabases.length === 0) throw new Error(`No databases found for the branch: ${branchId}`);
+		if (branchDatabases.length === 1) return branchDatabases[0].name;
+		throw new Error(`Multiple databases found for the branch, please provide one with the --database-name option: ${branchDatabases.map((d) => d.name).join(", ")}`);
+	})();
+	if (!branchDatabases.find((d) => d.name === database)) throw new Error(`Database not found: ${database}`);
+	const { data: { password } } = await props.apiClient.getProjectBranchRolePassword(props.projectId, endpoint.branch_id, role);
+	let host = props.pooled ? endpoint.host.replace(endpoint.id, `${endpoint.id}-pooler`) : endpoint.host;
+	if (parsedPIT.tag !== "head") host = endpoint.host.replace(endpoint.id, endpoint.branch_id);
+	const connectionString = new URL(`postgresql://${host}`);
+	connectionString.pathname = database;
+	connectionString.username = role;
+	connectionString.password = password;
+	if (props.prisma) {
+		connectionString.searchParams.set("connect_timeout", "30");
+		if (props.pooled) {
+			connectionString.searchParams.set("pool_timeout", "30");
+			connectionString.searchParams.set("pgbouncer", "true");
+		}
+	}
+	const ssl = props.ssl ?? "require";
+	if (ssl !== "omit") {
+		connectionString.searchParams.set("sslmode", ssl);
+		connectionString.searchParams.set("channel_binding", "require");
+	}
+	if (parsedPIT.tag === "lsn") connectionString.searchParams.set("options", `neon_lsn:${parsedPIT.lsn}`);
+	else if (parsedPIT.tag === "timestamp") connectionString.searchParams.set("options", `neon_timestamp:${parsedPIT.timestamp}`);
+	return {
+		connectionUri: connectionString.toString(),
+		host,
+		role,
+		password,
+		database,
+		options: connectionString.searchParams.toString()
+	};
 };
 const rowsFrom = (result) => {
-    const names = result.fields.map((f) => f.name);
-    return result.rows.map((row) => {
-        const obj = {};
-        names.forEach((name, i) => {
-            obj[name] = row[i];
-        });
-        return obj;
-    });
+	const names = result.fields.map((f) => f.name);
+	return result.rows.map((row) => {
+		const obj = {};
+		names.forEach((name, i) => {
+			obj[name] = row[i];
+		});
+		return obj;
+	});
 };
 /**
- * Connect to `connectionUri` with the embedded wire client, run a single
- * read-only `sql`, and return the rows as objects keyed by column name (so the
- * shared `writer` can render them by field). The connection is always closed,
- * even on error.
- */
-export const runInspectQuery = async (connectionUri, sql, options = {}) => {
-    const opts = parseConnectionUri(connectionUri);
-    let connection;
-    try {
-        connection = await PgConnection.connect(opts);
-    }
-    catch (err) {
-        // Give the failure a Postgres-specific message. The raw socket error
-        // (e.g. ECONNREFUSED) would otherwise be mislabeled by the top-level
-        // `isNetworkError` handler as a "Could not reach the Neon API" hint —
-        // misleading for `inspect db`, which talks to Postgres, not the API.
-        // We intentionally do not chain `cause` so that classifier can't match
-        // the socket `code`; the underlying reason is preserved in the message.
-        const reason = err instanceof Error ? err.message : String(err);
-        throw new Error(`Could not connect to Postgres at ${opts.host}:${opts.port}: ${reason}`);
-    }
-    try {
-        const ext = options.requiresExtension;
-        if (ext) {
-            // `ext` is an internal constant from INSPECT_QUERIES, never user input,
-            // so interpolating it into the literal is safe.
-            const check = await connection.query(`SELECT 1 FROM pg_extension WHERE extname = '${ext}';`);
-            if (check.rows.length === 0) {
-                throw new Error(`This query needs the "${ext}" extension, which is not installed. ` +
-                    `Enable it with: CREATE EXTENSION ${ext};`);
-            }
-        }
-        const result = await connection.query(sql);
-        return rowsFrom(result);
-    }
-    finally {
-        await connection.close();
-    }
+* Connect to `connectionUri` with the embedded wire client, run a single
+* read-only `sql`, and return the rows as objects keyed by column name (so the
+* shared `writer` can render them by field). The connection is always closed,
+* even on error.
+*/
+const runInspectQuery = async (connectionUri, sql, options = {}) => {
+	const opts = parseConnectionUri(connectionUri);
+	let connection;
+	try {
+		connection = await PgConnection.connect(opts);
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		throw new Error(`Could not connect to Postgres at ${opts.host}:${opts.port}: ${reason}`);
+	}
+	try {
+		const ext = options.requiresExtension;
+		if (ext) {
+			if ((await connection.query(`SELECT 1 FROM pg_extension WHERE extname = '${ext}';`)).rows.length === 0) throw new Error(`This query needs the "${ext}" extension, which is not installed. Enable it with: CREATE EXTENSION ${ext};`);
+		}
+		const result = await connection.query(sql);
+		return rowsFrom(result);
+	} finally {
+		await connection.close();
+	}
 };
+//#endregion
+export { SSL_MODES, resolveConnectionUri, runInspectQuery };