jsonbadger 0.5.0 → 0.6.0

package/src/sql/index.js

@@ -0,0 +1,17 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Expose the shared SQL builder and runner entry points.
+ */
+import build_update_query from '#src/sql/write/build-update-query.js';
+import build_insert_query from '#src/sql/write/build-insert-query.js';
+import build_delete_query from '#src/sql/write/build-delete-query.js';
+import run from '#src/sql/run.js';
+
+const sql = {
+	build_delete_query,
+	build_insert_query,
+	build_update_query,
+	run
+};
+
+export default sql;

package/src/sql/jsonb/ops.js

@@ -0,0 +1,153 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Parse operator-style JSONB mutations and compile one SQL RHS expression.
+ */
+import QueryError from '#src/errors/query-error.js';
+import {bind_parameter} from '#src/sql/parameter-binder.js';
+import {is_array} from '#src/utils/array.js';
+import {build_path_literal, split_dot_path} from '#src/utils/object-path.js';
+import {jsonb_stringify} from '#src/utils/json.js';
+import {is_not_object, is_plain_object} from '#src/utils/value.js';
+
+/**
+ * The canonical execution order for PostgreSQL JSONB mutations.
+ */
+const core_update_operators = ['$replace_roots', '$unset', '$set'];
+
+/**
+ * Utility for parsing JSONB mutations into a flat, ordered operation list.
+ * This acts as a Syntax Firewall: it knows HOW to write PG syntax, 
+ * but knows NOTHING about SQL parameters.
+ */
+function JsonbOps(target, operations) {
+	this.target = target;
+	this.operations = operations;
+}
+
+/**
+ * Compile one JsonbOps instance into a PostgreSQL JSONB RHS expression.
+ *
+ * @param {object} parameter_state
+ * @returns {string}
+ */
+JsonbOps.prototype.compile = function (parameter_state) {
+	let expression = this.target;
+
+	for(const step of this.operations) {
+		if(step.op === '$replace_roots') {
+			const placeholder = bind_parameter(parameter_state, step.value);
+			expression = `${placeholder}::jsonb`;
+		}
+		else if(step.op === '#-') {
+			expression = `${expression} #- '${step.path}'`;
+		}
+		else if(step.op === 'jsonb_set') {
+			const placeholder = bind_parameter(parameter_state, step.value);
+			expression = `jsonb_set(${expression}, '${step.path}', ${placeholder}::jsonb, true)`;
+		}
+	}
+
+	return expression;
+};
+
+/**
+ * Transforms one operator-style update definition into a JsonbOps instance.
+ *
+ * The input contract here is `$replace_roots`, `$unset`, `$set`, plus implicit
+ * top-level `$set` keys. If the caller starts from a tracker delta shape
+ * (`replace_roots`, `set`, `unset`), the orchestrator must map that delta into
+ * operator-style keys before calling `.from(...)`.
+ *
+ * @param {object} update_definition - Operator-style update input for one JSONB mutation.
+ * @param {object} options
+ * @param {string} options.column_name - The target column (e.g. '"data"').
+ * @param {boolean} [options.coalesce=true] - Wrap base in COALESCE.
+ * @returns {JsonbOps}
+ */
+JsonbOps.from = function (update_definition, options) {
+	if(is_not_object(update_definition)) {
+		throw new QueryError('JsonbOps requires an object definition');
+	}
+
+	const {column_name, coalesce = true} = options || {};
+
+	if(!column_name) {
+		throw new QueryError('JsonbOps requires options.column_name');
+	}
+
+	// Initialized with explicit types to avoid defensive assignment later
+	const buckets = {$replace_roots: {}, $unset: [], $set: {}};
+	let total_operations = 0;
+
+	// 1. Distribution & Auto-Wrapping
+	for(const [key, value] of Object.entries(update_definition)) {
+		if(key.startsWith('$')) {
+			if(!core_update_operators.includes(key)) {
+				throw new QueryError(`Unsupported JSONB operator: ${key}`);
+			}
+
+			if(key === '$unset') {
+				if(!is_array(value)) {
+					throw new QueryError('$unset expects array');
+				}
+
+				buckets.$unset.push(...value);
+				total_operations += value.length;
+
+			} else {
+				if(!is_plain_object(value)) {
+					throw new QueryError(`${key} expects plain object`);
+				}
+
+				Object.assign(buckets[key], value);
+				total_operations += Object.keys(value).length;
+			}
+
+		} else {
+			// Implicit wrapping of raw keys into $set
+			buckets.$set[key] = value;
+			total_operations += 1;
+		}
+	}
+
+	if(total_operations > 1024) {
+		throw new QueryError('JSONB mutation exceeds complexity limit (1024)');
+	}
+
+	// 2. Build the Linear Operation List
+	const operations = [];
+	let target = coalesce ? `COALESCE(${column_name}, '{}'::jsonb)` : column_name;
+
+	// A. Replace Roots (Redefines the starting target)
+	if(Object.keys(buckets.$replace_roots).length > 0) {
+		operations.push({
+			op: '$replace_roots',
+			value: jsonb_stringify(buckets.$replace_roots)
+		});
+	}
+
+	// B. Unsets
+	if(buckets.$unset.length > 0) {
+		for(const path of buckets.$unset) {
+			operations.push({
+				op: '#-',
+				path: build_path_literal(split_dot_path(path))
+			});
+		}
+	}
+
+	// C. Sets
+	if(Object.keys(buckets.$set).length > 0) {
+		for(const [path, value] of Object.entries(buckets.$set)) {
+			operations.push({
+				op: 'jsonb_set',
+				path: build_path_literal(split_dot_path(path)),
+				value: jsonb_stringify(value)
+			});
+		}
+	}
+
+	return new JsonbOps(target, operations);
+};
+
+export {JsonbOps};

package/src/{query → sql/jsonb}/path-parser.js

@@ -1,43 +1,54 @@
-import {assert_path} from '#src/utils/assert.js';
-import {build_path_literal, split_dot_path} from '#src/utils/object-path.js';
-
-export function build_text_expression(column_reference, path_value) {
-	const path_segments = split_dot_path(path_value);
-
-	if(path_segments.length === 1) {
-		return column_reference + " ->> '" + path_segments[0] + "'";
-	}
-
-	return column_reference + " #>> '" + build_path_literal(path_segments) + "'";
-}
-
-export function build_json_expression(column_reference, path_value) {
-	const path_segments = split_dot_path(path_value);
-
-	if(path_segments.length === 1) {
-		return column_reference + " -> '" + path_segments[0] + "'";
-	}
-
-	return column_reference + " #> '" + build_path_literal(path_segments) + "'";
-}
-
-export function build_elem_text_expression(elem_alias, path_segments) {
-	if(path_segments.length === 1) {
-		return elem_alias + "->>'" + path_segments[0] + "'";
-	}
-
-	return elem_alias + " #>> '" + build_path_literal(path_segments) + "'";
-}
-
-export function parse_path(path_value) {
-	assert_path(path_value, 'path');
-
-	const path_segments = split_dot_path(path_value);
-
-	return {
-		path_segments: path_segments,
-		root_path: path_segments[0],
-		child_segments: path_segments.slice(1),
-		is_nested: path_segments.length > 1
-	};
-}
+/*
+ * MODULE RESPONSIBILITY
+ * Parse JSONB paths and build SQL path expressions for JSONB query helpers.
+ */
+import {assert_path} from '#src/utils/assert.js';
+import {build_path_literal, split_dot_path} from '#src/utils/object-path.js';
+
+function build_text_expression(column_reference, path_value) {
+	const path_segments = split_dot_path(path_value);
+
+	if(path_segments.length === 1) {
+		return column_reference + " ->> '" + path_segments[0] + "'";
+	}
+
+	return column_reference + " #>> '" + build_path_literal(path_segments) + "'";
+}
+
+function build_json_expression(column_reference, path_value) {
+	const path_segments = split_dot_path(path_value);
+
+	if(path_segments.length === 1) {
+		return column_reference + " -> '" + path_segments[0] + "'";
+	}
+
+	return column_reference + " #> '" + build_path_literal(path_segments) + "'";
+}
+
+function build_elem_text_expression(elem_alias, path_segments) {
+	if(path_segments.length === 1) {
+		return elem_alias + "->>'" + path_segments[0] + "'";
+	}
+
+	return elem_alias + " #>> '" + build_path_literal(path_segments) + "'";
+}
+
+function parse_path(path_value) {
+	assert_path(path_value, 'path');
+
+	const path_segments = split_dot_path(path_value);
+
+	return {
+		path_segments: path_segments,
+		root_path: path_segments[0],
+		child_segments: path_segments.slice(1),
+		is_nested: path_segments.length > 1
+	};
+}
+
+export {
+	build_text_expression,
+	build_json_expression,
+	build_elem_text_expression,
+	parse_path
+};

package/src/sql/jsonb/read/elem-match.js

@@ -0,0 +1,133 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Compile JSONB nested-array and $elem_match predicates for read queries.
+ */
+import {build_elem_text_expression, build_json_expression} from '#src/sql/jsonb/path-parser.js';
+import elem_match_operator from '#src/sql/jsonb/read/operators/elem-match.js';
+import {eq_operator, regex_operator} from '#src/sql/read/where/operators/index.js';
+
+import {has_operator_entries} from '#src/sql/read/where/context.js';
+import {compile_operator_entry_clauses} from '#src/sql/read/where/operator-entries.js';
+import {compile_text_operator} from '#src/sql/read/where/text-operators.js';
+
+import {split_dot_path} from '#src/utils/object-path.js';
+import {is_object} from '#src/utils/value.js';
+import QueryError from '#src/errors/query-error.js';
+
+const unsupported_elem_match_operator_message = 'Unsupported operator inside $elem_match';
+
+function compile_nested_array_operator(operator_name, operator_value, regex_options, path_info, data_column_reference, parameter_state) {
+	const array_expression = build_json_expression(data_column_reference, path_info.root_path);
+	const elem_expression = build_elem_text_expression('elem', path_info.child_segments);
+	const predicate = compile_text_operator({
+		name: operator_name,
+		value: operator_value,
+		regex_options,
+		text_expression: elem_expression,
+		parameter_state,
+		error_message: unsupported_elem_match_operator_message
+	});
+
+	if(!predicate) {
+		throw new QueryError(unsupported_elem_match_operator_message + ': ' + operator_name, {
+			operator: operator_name
+		});
+	}
+
+	return elem_match_operator(array_expression, predicate);
+}
+
+function compile_elem_match_clause(path_value, elem_match_value, data_column_reference, parameter_state) {
+	const array_expression = build_json_expression(data_column_reference, path_value);
+	const predicate_list = [];
+
+	if(elem_match_value instanceof RegExp) {
+		predicate_list.push(regex_operator("elem #>> '{}'", elem_match_value.source, elem_match_value.flags, parameter_state));
+		return elem_match_operator(array_expression, predicate_list.join(' AND '));
+	}
+
+	if(!is_object(elem_match_value)) {
+		predicate_list.push(eq_operator("elem #>> '{}'", elem_match_value, parameter_state));
+		return elem_match_operator(array_expression, predicate_list.join(' AND '));
+	}
+
+	if(has_operator_entries(elem_match_value)) {
+		const option_value = elem_match_value.$options || '';
+		const compile_operator_predicate = (operator_name, operator_value) => {
+			const predicate = compile_text_operator({
+				name: operator_name,
+				value: operator_value,
+				regex_options: option_value,
+				text_expression: "elem #>> '{}'",
+				parameter_state,
+				error_message: unsupported_elem_match_operator_message
+			});
+
+			if(!predicate) {
+				throw new QueryError(unsupported_elem_match_operator_message + ': ' + operator_name, {
+					operator: operator_name
+				});
+			}
+
+			return predicate;
+		};
+		const operator_predicates = compile_operator_entry_clauses(elem_match_value, compile_operator_predicate);
+		predicate_list.push.apply(predicate_list, operator_predicates);
+
+		return elem_match_operator(array_expression, predicate_list.join(' AND '));
+	}
+
+	const elem_entries = Object.entries(elem_match_value);
+	let entry_index = 0;
+
+	while(entry_index < elem_entries.length) {
+		const entry_pair = elem_entries[entry_index];
+		const nested_path = entry_pair[0];
+		const nested_value = entry_pair[1];
+		const nested_segments = split_dot_path(nested_path);
+		const elem_expression = build_elem_text_expression('elem', nested_segments);
+
+		if(nested_value instanceof RegExp) {
+			predicate_list.push(regex_operator(elem_expression, nested_value.source, nested_value.flags, parameter_state));
+			entry_index += 1;
+			continue;
+		}
+
+		if(is_object(nested_value) && has_operator_entries(nested_value)) {
+			const option_value = nested_value.$options || '';
+			const compile_nested_predicate = (operator_name, operator_value) => {
+				const predicate = compile_text_operator({
+					name: operator_name,
+					value: operator_value,
+					regex_options: option_value,
+					text_expression: elem_expression,
+					parameter_state,
+					error_message: unsupported_elem_match_operator_message
+				});
+
+				if(!predicate) {
+					throw new QueryError(unsupported_elem_match_operator_message + ': ' + operator_name, {
+						operator: operator_name
+					});
+				}
+
+				return predicate;
+			};
+			const nested_predicates = compile_operator_entry_clauses(nested_value, compile_nested_predicate);
+			predicate_list.push.apply(predicate_list, nested_predicates);
+
+			entry_index += 1;
+			continue;
+		}
+
+		predicate_list.push(eq_operator(elem_expression, nested_value, parameter_state));
+		entry_index += 1;
+	}
+
+	return elem_match_operator(array_expression, predicate_list.join(' AND '));
+}
+
+export {
+	compile_elem_match_clause,
+	compile_nested_array_operator
+};

package/src/{query → sql/jsonb/read}/operators/contains.js

@@ -1,7 +1,13 @@
-import {bind_parameter} from '#src/sql/parameter-binder.js';
-import {jsonb_stringify} from '#src/utils/json.js';
-
-export default function contains_operator(jsonb_expression, comparison_value, parameter_state) {
-	const placeholder = bind_parameter(parameter_state, jsonb_stringify(comparison_value));
-	return jsonb_expression + ' @> ' + placeholder + '::jsonb';
-}
+/*
+ * MODULE RESPONSIBILITY
+ * Compile the SQL fragment for the $contains read-query operator.
+ */
+import {bind_parameter} from '#src/sql/parameter-binder.js';
+import {jsonb_stringify} from '#src/utils/json.js';
+
+function contains_operator(jsonb_expression, comparison_value, parameter_state) {
+	const placeholder = bind_parameter(parameter_state, jsonb_stringify(comparison_value));
+	return jsonb_expression + ' @> ' + placeholder + '::jsonb';
+}
+
+export default contains_operator;

package/src/sql/jsonb/read/operators/elem-match.js

@@ -0,0 +1,9 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Compile the SQL fragment for the $elem-match read-query operator.
+ */
+function elem_match_operator(array_expression, predicate_expression) {
+	return 'EXISTS (SELECT 1 FROM jsonb_array_elements(' + array_expression + ') AS elem WHERE ' + predicate_expression + ')';
+}
+
+export default elem_match_operator;

package/src/{query → sql/jsonb/read}/operators/has-all-keys.js

@@ -1,11 +1,17 @@
-import {bind_parameter} from '#src/sql/parameter-binder.js';
-import {to_array} from '#src/utils/array.js';
-
-export default function has_all_keys_operator(jsonb_expression, comparison_value, parameter_state) {
-	const key_list = to_array(comparison_value).map(function map_key(key_value) {
-		return String(key_value);
-	});
-
-	const placeholder = bind_parameter(parameter_state, key_list);
-	return jsonb_expression + ' ?& ' + placeholder + '::text[]';
-}
+/*
+ * MODULE RESPONSIBILITY
+ * Compile the SQL fragment for the $has-all-keys read-query operator.
+ */
+import {bind_parameter} from '#src/sql/parameter-binder.js';
+import {to_array} from '#src/utils/array.js';
+
+function has_all_keys_operator(jsonb_expression, comparison_value, parameter_state) {
+	const key_list = to_array(comparison_value).map(function map_key(key_value) {
+		return String(key_value);
+	});
+
+	const placeholder = bind_parameter(parameter_state, key_list);
+	return jsonb_expression + ' ?& ' + placeholder + '::text[]';
+}
+
+export default has_all_keys_operator;

package/src/{query → sql/jsonb/read}/operators/has-any-keys.js

@@ -1,11 +1,18 @@
-import {bind_parameter} from '#src/sql/parameter-binder.js';
-import {to_array} from '#src/utils/array.js';
-
-export default function has_any_keys_operator(jsonb_expression, comparison_value, parameter_state) {
-	const key_list = to_array(comparison_value).map(function map_key(key_value) {
-		return String(key_value);
-	});
-
-	const placeholder = bind_parameter(parameter_state, key_list);
-	return jsonb_expression + ' ?| ' + placeholder + '::text[]';
-}
+/*
+ * MODULE RESPONSIBILITY
+ * Compile the SQL fragment for the $has-any-keys read-query operator.
+ */
+import {bind_parameter} from '#src/sql/parameter-binder.js';
+import {to_array} from '#src/utils/array.js';
+
+function has_any_keys_operator(jsonb_expression, comparison_value, parameter_state) {
+	const key_list = to_array(comparison_value).map(function map_key(key_value) {
+		return String(key_value);
+	});
+
+	const placeholder = bind_parameter(parameter_state, key_list);
+
+	return jsonb_expression + ' ?| ' + placeholder + '::text[]';
+}
+
+export default has_any_keys_operator;

package/src/sql/jsonb/read/operators/has-key.js

@@ -0,0 +1,12 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Compile the SQL fragment for the $has-key read-query operator.
+ */
+import {bind_parameter} from '#src/sql/parameter-binder.js';
+
+function has_key_operator(jsonb_expression, comparison_value, parameter_state) {
+	const placeholder = bind_parameter(parameter_state, String(comparison_value));
+	return jsonb_expression + ' ? ' + placeholder;
+}
+
+export default has_key_operator;

package/src/{query → sql/jsonb/read}/operators/jsonpath-exists.js

@@ -1,15 +1,22 @@
-import QueryError from '#src/errors/query-error.js';
-import {bind_parameter} from '#src/sql/parameter-binder.js';
-import {is_string} from '#src/utils/value.js';
-
-export default function jsonpath_exists_operator(jsonb_expression, comparison_value, parameter_state) {
-	if(!is_string(comparison_value) || comparison_value.trim() === '') {
-		throw new QueryError('Invalid value for $json_path_exists operator', {
-			operator: '$json_path_exists',
-			value: comparison_value
-		});
-	}
-
-	const placeholder = bind_parameter(parameter_state, comparison_value);
-	return jsonb_expression + ' @? ' + placeholder + '::jsonpath';
-}
+/*
+ * MODULE RESPONSIBILITY
+ * Compile the SQL fragment for the $jsonpath-exists read-query operator.
+ */
+import QueryError from '#src/errors/query-error.js';
+import {bind_parameter} from '#src/sql/parameter-binder.js';
+import {is_string} from '#src/utils/value.js';
+
+function jsonpath_exists_operator(jsonb_expression, comparison_value, parameter_state) {
+	if(!is_string(comparison_value) || comparison_value.trim() === '') {
+		throw new QueryError('Invalid value for $json_path_exists operator', {
+			operator: '$json_path_exists',
+			value: comparison_value
+		});
+	}
+
+	const placeholder = bind_parameter(parameter_state, comparison_value);
+
+	return jsonb_expression + ' @? ' + placeholder + '::jsonpath';
+}
+
+export default jsonpath_exists_operator;

package/src/{query → sql/jsonb/read}/operators/jsonpath-match.js

@@ -1,15 +1,22 @@
-import QueryError from '#src/errors/query-error.js';
-import {bind_parameter} from '#src/sql/parameter-binder.js';
-import {is_string} from '#src/utils/value.js';
-
-export default function jsonpath_match_operator(jsonb_expression, comparison_value, parameter_state) {
-	if(!is_string(comparison_value) || comparison_value.trim() === '') {
-		throw new QueryError('Invalid value for $json_path_match operator', {
-			operator: '$json_path_match',
-			value: comparison_value
-		});
-	}
-
-	const placeholder = bind_parameter(parameter_state, comparison_value);
-	return jsonb_expression + ' @@ ' + placeholder + '::jsonpath';
-}
+/*
+ * MODULE RESPONSIBILITY
+ * Compile the SQL fragment for the $jsonpath-match read-query operator.
+ */
+import QueryError from '#src/errors/query-error.js';
+import {bind_parameter} from '#src/sql/parameter-binder.js';
+import {is_string} from '#src/utils/value.js';
+
+function jsonpath_match_operator(jsonb_expression, comparison_value, parameter_state) {
+	if(!is_string(comparison_value) || comparison_value.trim() === '') {
+		throw new QueryError('Invalid value for $json_path_match operator', {
+			operator: '$json_path_match',
+			value: comparison_value
+		});
+	}
+
+	const placeholder = bind_parameter(parameter_state, comparison_value);
+
+	return jsonb_expression + ' @@ ' + placeholder + '::jsonpath';
+}
+
+export default jsonpath_match_operator;

package/src/{query → sql/jsonb/read}/operators/size.js

@@ -1,16 +1,23 @@
-import QueryError from '#src/errors/query-error.js';
-import {bind_parameter} from '#src/sql/parameter-binder.js';
-import {is_nan} from '#src/utils/value.js';
-
-export default function size_operator(jsonb_expression, comparison_value, parameter_state) {
-	if(is_nan(comparison_value)) {
-		throw new QueryError('Invalid value for $size operator', {
-			operator: '$size',
-			value: comparison_value
-		});
-	}
-
-	const numeric_value = Number(comparison_value);
-	const placeholder = bind_parameter(parameter_state, numeric_value);
-	return 'jsonb_array_length(' + jsonb_expression + ') = ' + placeholder;
-}
+/*
+ * MODULE RESPONSIBILITY
+ * Compile the SQL fragment for the $size read-query operator.
+ */
+import QueryError from '#src/errors/query-error.js';
+import {bind_parameter} from '#src/sql/parameter-binder.js';
+import {is_nan} from '#src/utils/value.js';
+
+function size_operator(jsonb_expression, comparison_value, parameter_state) {
+	if(is_nan(comparison_value)) {
+		throw new QueryError('Invalid value for $size operator', {
+			operator: '$size',
+			value: comparison_value
+		});
+	}
+
+	const numeric_value = Number(comparison_value);
+	const placeholder = bind_parameter(parameter_state, numeric_value);
+
+	return 'jsonb_array_length(' + jsonb_expression + ') = ' + placeholder;
+}
+
+export default size_operator;

package/src/sql/parameter-binder.js

@@ -1,13 +1,18 @@
-export function create_parameter_state(start_index) {
-	return {
-		params: [],
-		current_index: start_index || 1
-	};
-}
-
-export function bind_parameter(parameter_state, value) {
-	const placeholder = '$' + parameter_state.current_index;
-	parameter_state.params.push(value);
-	parameter_state.current_index += 1;
-	return placeholder;
-}
+function create_parameter_state(start_index) {
+	return {
+		params: [],
+		current_index: start_index || 1
+	};
+}
+
+function bind_parameter(parameter_state, value) {
+	const placeholder = '$' + parameter_state.current_index;
+	parameter_state.params.push(value);
+	parameter_state.current_index += 1;
+	return placeholder;
+}
+
+export {
+	create_parameter_state,
+	bind_parameter
+};