@happyvertical/sql 0.89.1 → 0.89.3

package/README.md

@@ -83,6 +83,20 @@ cached adapter. Combine it with `cache: false` to evict first and return an
 uncached replacement. A concurrent initializer caught by eviction is closed
 and cannot repopulate the cache.
 
+With automatic file registration enabled (the default), cached JSON adapters
+also detect external changes to JSON data and companion `.schema.sql` files when
+a later `getDatabase()` call acquires the same cache identity. A changed, added,
+or removed source file causes the old DuckDB adapter to close before one fresh
+shared adapter is created. Existing references point to the closed adapter
+after replacement; acquire the database again before continuing work after an
+external file change. Writes made through the adapter refresh its snapshot and
+do not invalidate the adapter itself when the tracked sources are otherwise
+unchanged. If an external change is already visible before an adapter export,
+the export fails closed so the caller can reacquire the database and retry.
+Freshness checks are not a cross-process file lock: an external process writing
+the same table's JSON or companion schema file at the same instant as an adapter
+export remains last-writer-wins and must be coordinated by the application.
+
 The JSON adapter's exported `clearConnectionCache()` helper is asynchronous:
 always `await clearConnectionCache()` before opening a replacement connection.
 
@@ -248,6 +262,13 @@ object with a `toString` — is rejected outright rather than coerced, so the va
 validated is always the value interpolated. Values are always parameterized and
 are unaffected.
 
+PostgreSQL `upsert()` additionally lowercases each validated column name before
+double-quoting it. PostgreSQL has always folded the adapter's unquoted column
+names to lowercase, so this preserves existing behavior (`mixedCase` still
+addresses `mixedcase`) while allowing reserved words such as `end` in insert,
+conflict and update positions. Delimited, case-sensitive physical names such as
+`"MixedCase"` remain outside the CRUD identifier contract.
+
 `buildWhere` separates a supported operator suffix (`'price >'`,
 `'name contains'`) from the field and then validates the field as an identifier.
 Unsupported suffixes remain part of the field and fail validation rather than

package/dist/chunks/{connection-cache-WEH2ulk5.js → connection-cache-Da5UcY5u.js}

@@ -911,11 +911,12 @@ function validateColumnName(columnName) {
 * Validates every identifier in a column list to prevent SQL injection
 *
 * Column names reaching the CRUD methods come from `Object.keys(data)` and the
-* caller's `conflictColumns`, both of which are interpolated into SQL. They are
-* checked rather than quoted deliberately: the accepted shape has no character
-* that can end an identifier, so quoting adds nothing to safety, and quoting a
-* name on PostgreSQL makes it case-sensitive, which would silently change which
-* column an existing caller addresses.
+* caller's `conflictColumns`, both of which are interpolated into SQL. The
+* accepted shape has no character that can end an identifier. Adapters may
+* render a validated name bare, or quote it under an adapter-specific contract.
+* PostgreSQL upsert uses {@link quotePostgresColumnName}, which canonicalizes
+* the name before quoting so its established unquoted case-folding semantics
+* do not change.
 *
 * @param columnNames - Column names to validate
 * @throws Error if any column name contains invalid characters
@@ -924,6 +925,24 @@ function validateColumnNames(columnNames) {
 	for (const columnName of columnNames) validateColumnName(columnName);
 }
 /**
+* Quotes a validated column name using PostgreSQL's historic case semantics.
+*
+* PostgreSQL folds every unquoted identifier to lowercase. The CRUD API has
+* always accepted mixed-case inputs while rendering them unquoted, so quoting
+* the caller's spelling directly would silently change which physical column
+* is addressed. Validate the existing plain-identifier contract first, then
+* lowercase before quoting: `mixedCase` still addresses `mixedcase`, while a
+* reserved word such as `end` is no longer parsed as SQL syntax.
+*
+* @param columnName - Plain column name to render for PostgreSQL
+* @returns A lowercase, double-quoted PostgreSQL identifier
+* @throws Error if the column name is outside the CRUD identifier contract
+*/
+function quotePostgresColumnName(columnName) {
+	validateColumnName(columnName);
+	return `"${columnName.toLowerCase()}"`;
+}
+/**
 * Escapes an identifier for interpolation inside double quotes
 *
 * For the positions that already quote the identifier — the DuckDB and JSON
@@ -976,15 +995,17 @@ function validateIndexName(indexName) {
 }
 //#endregion
 //#region src/shared/connection-cache.ts
+var CACHED_VALIDATION_CAPABILITY = Symbol.for("@happyvertical/sql/connection-cache-cached-validation/v1");
 /** Race-safe async resource cache used by database adapters. */
 var ConnectionCache = class {
+	[CACHED_VALIDATION_CAPABILITY] = true;
 	#connections = /* @__PURE__ */ new Map();
 	#pending = /* @__PURE__ */ new Map();
 	#evictions = /* @__PURE__ */ new Map();
 	#requests = /* @__PURE__ */ new Map();
 	#clearing = /* @__PURE__ */ new Map();
 	#failedClosures = /* @__PURE__ */ new Map();
-	async getOrCreate(key, options, create, close) {
+	async getOrCreate(key, options, create, close, validateCached) {
 		validateDatabaseCacheOptions(options);
 		const request = key && options.cache !== false ? this.#registerRequest(key) : void 0;
 		try {
@@ -1002,7 +1023,17 @@ var ConnectionCache = class {
 				}
 				this.#throwIfFailedClosure(key);
 				const cached = this.#connections.get(key);
-				if (cached) return cached;
+				if (cached !== void 0) {
+					if (!validateCached) return cached;
+					const isValid = await validateCached(cached);
+					this.#throwIfCancelled(request);
+					if (isValid && this.#connections.get(key) === cached && !this.#evictions.has(key)) return cached;
+					if (!isValid && this.#connections.get(key) === cached && !this.#evictions.has(key)) {
+						await this.evict(key, close);
+						this.#throwIfCancelled(request);
+					}
+					continue;
+				}
 				let pending = this.#pending.get(key);
 				if (!pending) {
 					this.#throwIfCancelled(request);
@@ -1165,10 +1196,110 @@ var ConnectionCache = class {
 		}
 	}
 };
+/**
+* Adds cached-resource validation to a shared cache created by an older module.
+*
+* JSON connection caches live on `globalThis`, so a compatible older SDK copy
+* can create the shared object before this module loads. Mutating that object
+* preserves one cache for both module copies while upgrading its four-argument
+* `getOrCreate` method to the current validation contract.
+*/
+function enableCachedValidation(cache) {
+	if (cache[CACHED_VALIDATION_CAPABILITY]) return cache;
+	const legacyGetOrCreate = cache.getOrCreate.bind(cache);
+	const legacyClear = cache.clear.bind(cache);
+	const locks = /* @__PURE__ */ new Map();
+	let clearGeneration = 0;
+	let activeClear;
+	const runLocked = async (key, work) => {
+		const previous = locks.get(key) ?? Promise.resolve();
+		let release;
+		const current = new Promise((resolve) => {
+			release = resolve;
+		});
+		const chain = previous.then(() => current, () => current);
+		locks.set(key, chain);
+		await previous.catch(() => {});
+		try {
+			return await work();
+		} finally {
+			release();
+			if (locks.get(key) === chain) locks.delete(key);
+		}
+	};
+	Object.defineProperty(cache, "getOrCreate", {
+		configurable: true,
+		value: async (key, options, create, close, validateCached) => {
+			if (!key || options.cache === false) return legacyGetOrCreate(key, options, create, close);
+			const requestGeneration = clearGeneration;
+			const throwIfCleared = () => {
+				if (activeClear || requestGeneration !== clearGeneration) throw new Error("Database connection initialization was cancelled by cache clear");
+			};
+			return runLocked(key, async () => {
+				throwIfCleared();
+				let requestOptions = options;
+				while (true) {
+					throwIfCleared();
+					const candidate = await legacyGetOrCreate(key, requestOptions, create, close);
+					throwIfCleared();
+					if (!validateCached) return candidate;
+					const isValid = await validateCached(candidate);
+					throwIfCleared();
+					if (isValid) {
+						const confirmed = await legacyGetOrCreate(key, {
+							...requestOptions,
+							clearCache: false
+						}, create, close);
+						throwIfCleared();
+						if (confirmed === candidate) return candidate;
+					} else await cache.evict(key, close);
+					requestOptions = {
+						...options,
+						clearCache: false
+					};
+				}
+			});
+		},
+		writable: true
+	});
+	Object.defineProperty(cache, "clear", {
+		configurable: true,
+		value: async (close) => {
+			if (activeClear) return activeClear;
+			clearGeneration += 1;
+			const clearing = (async () => {
+				let clearError;
+				let clearFailed = false;
+				try {
+					await legacyClear(close);
+				} catch (error) {
+					clearFailed = true;
+					clearError = error;
+				}
+				while (locks.size > 0) await Promise.allSettled([...locks.values()]);
+				if (clearFailed) throw clearError;
+			})();
+			activeClear = clearing;
+			try {
+				await clearing;
+			} finally {
+				if (activeClear === clearing) activeClear = void 0;
+			}
+		},
+		writable: true
+	});
+	Object.defineProperty(cache, CACHED_VALIDATION_CAPABILITY, {
+		configurable: false,
+		enumerable: false,
+		value: true,
+		writable: false
+	});
+	return cache;
+}
 function validateDatabaseCacheOptions(options) {
 	if (options.dbid === "") throw new Error("Database cache dbid must be a non-empty string");
 }
 //#endregion
-export { unwrapRawKey as _, generateAddColumnStatement as a, validateColumnNames as c, DatabaseSchemaManager as d, buildWhere as f, resolveInsertColumns as g, raw as h, escapeStringLiteral as i, validateIndexName as l, parseConditionKey as m, validateDatabaseCacheOptions as n, generateCreateIndexStatement as o, formatDbError as p, escapeQuotedIdentifier as r, validateColumnName as s, ConnectionCache as t, validateTableName as u, wrapDatabaseError as v };
+export { raw as _, escapeStringLiteral as a, wrapDatabaseError as b, quotePostgresColumnName as c, validateIndexName as d, validateTableName as f, parseConditionKey as g, formatDbError as h, escapeQuotedIdentifier as i, validateColumnName as l, buildWhere as m, enableCachedValidation as n, generateAddColumnStatement as o, DatabaseSchemaManager as p, validateDatabaseCacheOptions as r, generateCreateIndexStatement as s, ConnectionCache as t, validateColumnNames as u, resolveInsertColumns as v, unwrapRawKey as y };
 
-//# sourceMappingURL=connection-cache-WEH2ulk5.js.map
+//# sourceMappingURL=connection-cache-Da5UcY5u.js.map