jsonbadger 0.5.0 → 0.6.0

package/src/sql/read/build-count-query.js

@@ -0,0 +1,12 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Build SQL text and parameters for count read queries.
+ */
+function build_count_query(query_context) {
+	return {
+		sql_text: `SELECT COUNT(*)::int AS total_count FROM ${query_context.table_identifier} WHERE ${query_context.where_result.sql}`,
+		sql_params: query_context.where_result.params
+	};
+}
+
+export default build_count_query;

package/src/sql/read/build-find-query.js

@@ -0,0 +1,25 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Build SQL text and parameters for row-returning read queries.
+ */
+import limit_skip_compiler from '#src/sql/read/limit-skip.js';
+import sort_compiler from '#src/sql/read/sort.js';
+
+function build_find_query(query_context) {
+	let sql_text =
+		`SELECT id::text AS id, ${query_context.data_identifier} AS data, ` +
+		`created_at AS created_at, ` +
+		`updated_at AS updated_at ` +
+		`FROM ${query_context.table_identifier} ` +
+		`WHERE ${query_context.where_result.sql}`;
+
+	sql_text += sort_compiler(query_context.sort, {data_column: query_context.data_column});
+	sql_text += limit_skip_compiler(query_context.limit_count, query_context.skip_count);
+
+	return {
+		sql_text,
+		sql_params: query_context.where_result.params
+	};
+}
+
+export default build_find_query;

package/src/sql/read/limit-skip.js

@@ -0,0 +1,21 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Compile LIMIT and OFFSET clauses for read queries.
+ */
+import {is_nan, to_int} from '#src/utils/value.js';
+
+function limit_skip_compiler(limit_value, skip_value) {
+	let sql_fragment = '';
+
+	if(!is_nan(limit_value)) {
+		sql_fragment += ' LIMIT ' + to_int(limit_value);
+	}
+
+	if(!is_nan(skip_value)) {
+		sql_fragment += ' OFFSET ' + to_int(skip_value);
+	}
+
+	return sql_fragment;
+}
+
+export default limit_skip_compiler;

package/src/sql/read/sort.js

@@ -0,0 +1,85 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Compile ORDER BY clauses for read queries.
+ */
+import QueryError from '#src/errors/query-error.js';
+import {quote_identifier} from '#src/utils/assert.js';
+import {has_own} from '#src/utils/object.js';
+import {build_text_expression} from '#src/sql/jsonb/path-parser.js';
+import {split_dot_path} from '#src/utils/object-path.js';
+
+const base_field_sort_columns = Object.freeze({
+	id: '"id"',
+	created_at: '"created_at"',
+	updated_at: '"updated_at"'
+});
+
+/**
+ * Compiles a sort object into a SQL ORDER BY clause.
+ *
+ * Supported shape:
+ * - keys: field paths (e.g. `name`, `profile.last_name`, `created_at`)
+ * - values: order hints (`-1` => DESC, any other value => ASC)
+ *
+ * Returns an empty string for missing/invalid sort definitions so callers can
+ * safely append the result to a larger SQL fragment.
+ */
+function sort_compiler(sort_definition, compile_options) {
+	if(!sort_definition || typeof sort_definition !== 'object') {
+		return '';
+	}
+
+	const data_column_name = compile_options?.data_column ?? 'data';
+	const data_column_reference = quote_identifier(data_column_name);
+	const sort_entries = Object.entries(sort_definition);
+	const sort_clauses = [];
+	let entry_index = 0;
+
+	while(entry_index < sort_entries.length) {
+		const sort_entry = sort_entries[entry_index];
+		const path_value = sort_entry[0];
+		// Keep sort order normalization permissive: only exact -1 maps to DESC.
+		const order_value = Number(sort_entry[1]) === -1 ? 'DESC' : 'ASC';
+		const text_expression = resolve_sort_expression(path_value, data_column_reference);
+
+		sort_clauses.push(text_expression + ' ' + order_value);
+		entry_index += 1;
+	}
+
+	if(sort_clauses.length === 0) {
+		return '';
+	}
+
+	return ' ORDER BY ' + sort_clauses.join(', ');
+}
+
+/**
+ * Resolves a sort path to the SQL expression used in ORDER BY.
+ *
+ * Base fields (`id`, `created_at`, `updated_at`) are mapped to
+ * dedicated table columns instead of JSON path lookups. These fields are
+ * intentionally restricted to top-level usage only: `created_at` is valid,
+ * but `created_at.anything` is rejected.
+ *
+ * Non-base-field paths are treated as JSON data paths and may be dotted.
+ */
+function resolve_sort_expression(path_value, data_column_reference) {
+	const path_segments = split_dot_path(path_value);
+	const root_path = path_segments[0];
+
+	if(has_own(base_field_sort_columns, root_path)) {
+		// Prevent ambiguity: base-field columns do not support dotted access.
+		if(path_segments.length > 1) {
+			throw new QueryError('Base fields only support top-level sort paths', {
+				path: path_value,
+				field: root_path
+			});
+		}
+
+		return base_field_sort_columns[root_path];
+	}
+
+	return build_text_expression(data_column_reference, path_value);
+}
+
+export default sort_compiler;

package/src/sql/read/where/base-fields.js

@@ -0,0 +1,310 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Compile top-level base-field predicates for read queries.
+ */
+import QueryError from '#src/errors/query-error.js';
+import ID_STRATEGY from '#src/constants/id-strategy.js';
+import {bind_parameter} from '#src/sql/parameter-binder.js';
+import {parse_path} from '#src/sql/jsonb/path-parser.js';
+import {is_plain_object, is_uuid_v7} from '#src/utils/value.js';
+
+// Base fields are top-level only. Each one owns its SQL expression and allowed operators.
+const base_field_rules = Object.freeze({
+	id: {
+		expression: '"id"',
+		operator_allowlist: new Set(['$eq', '$ne', '$in', '$nin']),
+		value_kind: 'id'
+	},
+	created_at: {
+		expression: '"created_at"',
+		operator_allowlist: new Set(['$eq', '$ne', '$gt', '$gte', '$lt', '$lte', '$in', '$nin']),
+		value_kind: 'timestamp'
+	},
+	updated_at: {
+		expression: '"updated_at"',
+		operator_allowlist: new Set(['$eq', '$ne', '$gt', '$gte', '$lt', '$lte', '$in', '$nin']),
+		value_kind: 'timestamp'
+	}
+});
+
+/**
+ * Resolve the base-field name for a query path.
+ *
+ * @param {string} path_value Query path.
+ * @returns {string|null}
+ * @throws {QueryError} When a base field is used with a nested path.
+ */
+function resolve_base_field_name(path_value) {
+	const path_info = parse_path(path_value);
+	const root_path = path_info.root_path;
+
+	if(!base_field_rules[root_path]) {
+		return null;
+	}
+
+	if(path_info.is_nested) {
+		throw new QueryError('Base fields only support top-level paths', {
+			path: path_value,
+			field: root_path
+		});
+	}
+
+	return root_path;
+}
+
+/**
+ * Compile one base-field clause.
+ *
+ * @param {string} field_name Base-field name.
+ * @param {*} comparison_value Query value or operator object.
+ * @param {object} compile_context Normalized where-compiler context.
+ * @param {object} parameter_state SQL parameter state.
+ * @returns {string}
+ * @throws {QueryError} When the value or operator is invalid for the base field.
+ */
+function compile_base_field_clause(field_name, comparison_value, compile_context, parameter_state) {
+	if(comparison_value instanceof RegExp) {
+		throw new QueryError('Base field does not support regular expression matching', {
+			field: field_name
+		});
+	}
+
+	if(is_plain_object(comparison_value)) {
+		if(comparison_value.$elem_match !== undefined) {
+			throw new QueryError('Base field does not support $elem_match', {
+				field: field_name
+			});
+		}
+
+		if(!has_operator_entries(comparison_value)) {
+			throw new QueryError('Base field only supports scalar values or operator objects', {
+				field: field_name
+			});
+		}
+
+		const clause_list = [];
+		const operator_entries = Object.entries(comparison_value);
+		let operator_index = 0;
+
+		while(operator_index < operator_entries.length) {
+			const operator_entry = operator_entries[operator_index];
+			const operator_name = operator_entry[0];
+			const operator_value = operator_entry[1];
+
+			if(operator_name === '$options') {
+				throw new QueryError('Base field does not support $options', {
+					field: field_name
+				});
+			}
+
+			assert_base_field_operator_supported(field_name, operator_name);
+			clause_list.push(
+				compile_base_field_operator(field_name, operator_name, operator_value, compile_context, parameter_state)
+			);
+			operator_index += 1;
+		}
+
+		return clause_list.join(' AND ');
+	}
+
+	const normalized_value = normalize_base_field_scalar(field_name, comparison_value, '$eq', compile_context);
+	return build_base_field_comparison(field_name, '$eq', normalized_value, compile_context, parameter_state);
+}
+
+function compile_base_field_operator(field_name, operator_name, operator_value, compile_context, parameter_state) {
+	if(operator_name === '$in' || operator_name === '$nin') {
+		const normalized_values = normalize_base_field_list(field_name, operator_value, operator_name, compile_context);
+		return build_base_field_comparison(field_name, operator_name, normalized_values, compile_context, parameter_state);
+	}
+
+	const normalized_value = normalize_base_field_scalar(field_name, operator_value, operator_name, compile_context);
+	return build_base_field_comparison(field_name, operator_name, normalized_value, compile_context, parameter_state);
+}
+
+function build_base_field_comparison(field_name, operator_name, normalized_value, compile_context, parameter_state) {
+	const field_rule = base_field_rules[field_name];
+	const placeholder = bind_parameter(parameter_state, normalized_value);
+	const field_expression = field_rule.expression;
+	const id_parameter_cast = resolve_id_parameter_cast(compile_context.id_strategy);
+
+	if(operator_name === '$eq') {
+		if(field_rule.value_kind === 'id') {
+			return field_expression + ' = ' + placeholder + id_parameter_cast;
+		}
+
+		return field_expression + ' = ' + placeholder + '::timestamptz';
+	}
+
+	if(operator_name === '$ne') {
+		if(field_rule.value_kind === 'id') {
+			return field_expression + ' != ' + placeholder + id_parameter_cast;
+		}
+
+		return field_expression + ' != ' + placeholder + '::timestamptz';
+	}
+
+	if(operator_name === '$gt') {
+		return field_expression + ' > ' + placeholder + '::timestamptz';
+	}
+
+	if(operator_name === '$gte') {
+		return field_expression + ' >= ' + placeholder + '::timestamptz';
+	}
+
+	if(operator_name === '$lt') {
+		return field_expression + ' < ' + placeholder + '::timestamptz';
+	}
+
+	if(operator_name === '$lte') {
+		return field_expression + ' <= ' + placeholder + '::timestamptz';
+	}
+
+	if(operator_name === '$in') {
+		if(field_rule.value_kind === 'id') {
+			const id_array_cast = id_parameter_cast === '::uuid' ? '::uuid[]' : '::bigint[]';
+			return field_expression + ' = ANY(' + placeholder + id_array_cast + ')';
+		}
+
+		return field_expression + ' = ANY(' + placeholder + '::timestamptz[])';
+	}
+
+	if(operator_name === '$nin') {
+		if(field_rule.value_kind === 'id') {
+			const id_array_cast = id_parameter_cast === '::uuid' ? '::uuid[]' : '::bigint[]';
+			return 'NOT (' + field_expression + ' = ANY(' + placeholder + id_array_cast + '))';
+		}
+
+		return 'NOT (' + field_expression + ' = ANY(' + placeholder + '::timestamptz[]))';
+	}
+}
+
+function normalize_base_field_list(field_name, operator_value, operator_name, compile_context) {
+	const input_values = Array.isArray(operator_value) ? operator_value : [operator_value];
+	const normalized_values = [];
+	let value_index = 0;
+
+	while(value_index < input_values.length) {
+		const next_value = normalize_base_field_scalar(field_name, input_values[value_index], operator_name, compile_context);
+		normalized_values.push(next_value);
+		value_index += 1;
+	}
+
+	return normalized_values;
+}
+
+function normalize_base_field_scalar(field_name, operator_value, operator_name, compile_context) {
+	const field_rule = base_field_rules[field_name];
+
+	if(operator_value === undefined || operator_value === null || Array.isArray(operator_value) || is_plain_object(operator_value)) {
+		throw new QueryError('Invalid value for base field', {
+			field: field_name,
+			operator: operator_name,
+			value: operator_value
+		});
+	}
+
+	if(field_rule.value_kind === 'id') {
+		return normalize_id_value(operator_value, operator_name, compile_context.id_strategy);
+	}
+
+	return normalize_timestamp_value(field_name, operator_name, operator_value);
+}
+
+function normalize_timestamp_value(field_name, operator_name, operator_value) {
+	const parsed_timestamp = operator_value instanceof Date ? operator_value : new Date(operator_value);
+
+	if(Number.isNaN(parsed_timestamp.getTime())) {
+		throw new QueryError('Invalid timestamp value for base field', {
+			field: field_name,
+			operator: operator_name,
+			value: operator_value
+		});
+	}
+
+	return parsed_timestamp.toISOString();
+}
+
+function normalize_id_value(operator_value, operator_name, id_strategy) {
+	if(id_strategy === ID_STRATEGY.uuidv7) {
+		const uuid_value = String(operator_value);
+
+		if(!is_uuid_v7(uuid_value)) {
+			throw new QueryError('Invalid id value for uuid id_strategy', {
+				field: 'id',
+				operator: operator_name,
+				value: operator_value
+			});
+		}
+
+		return uuid_value;
+	}
+
+	if(typeof operator_value === 'bigint') {
+		return operator_value.toString();
+	}
+
+	if(typeof operator_value === 'number') {
+		if(Number.isInteger(operator_value) === false) {
+			throw new QueryError('Invalid id value for bigserial id_strategy', {
+				field: 'id',
+				operator: operator_name,
+				value: operator_value
+			});
+		}
+
+		return String(operator_value);
+	}
+
+	const numeric_value = String(operator_value);
+
+	if(/^[0-9]+$/.test(numeric_value) === false) {
+		throw new QueryError('Invalid id value for bigserial id_strategy', {
+			field: 'id',
+			operator: operator_name,
+			value: operator_value
+		});
+	}
+
+	return numeric_value;
+}
+
+function resolve_id_parameter_cast(id_strategy) {
+	if(id_strategy === ID_STRATEGY.uuidv7) {
+		return '::uuid';
+	}
+
+	return '::bigint';
+}
+
+function assert_base_field_operator_supported(field_name, operator_name) {
+	const field_rule = base_field_rules[field_name];
+
+	if(field_rule.operator_allowlist.has(operator_name)) {
+		return;
+	}
+
+	throw new QueryError('Operator is not supported for base field', {
+		field: field_name,
+		operator: operator_name
+	});
+}
+
+function has_operator_entries(object_value) {
+	const keys = Object.keys(object_value);
+	let key_index = 0;
+
+	while(key_index < keys.length) {
+		if(keys[key_index][0] === '$') {
+			return true;
+		}
+
+		key_index += 1;
+	}
+
+	return false;
+}
+
+export {
+	compile_base_field_clause,
+	resolve_base_field_name
+};

package/src/sql/read/where/casting.js

@@ -0,0 +1,90 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Cast read-query operator values with schema-aware rules.
+ */
+import {is_function} from '#src/utils/value.js';
+
+import {resolve_query_field_type} from '#src/sql/read/where/context.js';
+
+function cast_query_value(path_value, comparison_value, compile_context) {
+	if(comparison_value === undefined || comparison_value === null) {
+		return comparison_value;
+	}
+
+	const field_type = resolve_query_field_type(compile_context, path_value);
+
+	if(!field_type || !is_function(field_type.cast)) {
+		return comparison_value;
+	}
+
+	return field_type.cast(comparison_value, {
+		path: path_value,
+		mode: 'query'
+	});
+}
+
+function cast_array_contains_value(path_value, comparison_value, compile_context) {
+	const field_type = resolve_query_field_type(compile_context, path_value);
+
+	if(!field_type || field_type.instance !== 'Array' || !field_type.of_field_type || !is_function(field_type.of_field_type.cast)) {
+		return comparison_value;
+	}
+
+	return field_type.of_field_type.cast(comparison_value, {
+		path: path_value,
+		mode: 'query'
+	});
+}
+
+function cast_operator_value(path_value, operator_name, operator_value, compile_context) {
+	if(
+		operator_name === '$eq' ||
+		operator_name === '$ne' ||
+		operator_name === '$gt' ||
+		operator_name === '$gte' ||
+		operator_name === '$lt' ||
+		operator_name === '$lte'
+	) {
+		return cast_query_value(path_value, operator_value, compile_context);
+	}
+
+	if(operator_name === '$in' || operator_name === '$nin') {
+		if(!Array.isArray(operator_value)) {
+			return [cast_query_value(path_value, operator_value, compile_context)];
+		}
+
+		const casted_values = [];
+		let value_index = 0;
+
+		while(value_index < operator_value.length) {
+			casted_values.push(cast_query_value(path_value, operator_value[value_index], compile_context));
+			value_index += 1;
+		}
+
+		return casted_values;
+	}
+
+	if(operator_name === '$all') {
+		if(!Array.isArray(operator_value)) {
+			return operator_value;
+		}
+
+		const casted_values = [];
+		let value_index = 0;
+
+		while(value_index < operator_value.length) {
+			casted_values.push(cast_array_contains_value(path_value, operator_value[value_index], compile_context));
+			value_index += 1;
+		}
+
+		return casted_values;
+	}
+
+	return operator_value;
+}
+
+export {
+	cast_array_contains_value,
+	cast_operator_value,
+	cast_query_value
+};

package/src/sql/read/where/context.js

@@ -0,0 +1,79 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Create shared compile context helpers for read-query WHERE compilation.
+ */
+import ID_STRATEGY from '#src/constants/id-strategy.js';
+
+import {quote_identifier} from '#src/utils/assert.js';
+import {is_function, is_object} from '#src/utils/value.js';
+
+function resolve_query_field_type(compile_context, path_value) {
+	const schema_instance = compile_context.schema_instance;
+
+	if(!schema_instance || !is_function(schema_instance.get_path)) {
+		return null;
+	}
+
+	return schema_instance.get_path(path_value);
+}
+
+function should_use_array_contains(path_value, comparison_value, compile_context) {
+	const schema_instance = compile_context.schema_instance;
+
+	if(!schema_instance || !is_function(schema_instance.is_array_root)) {
+		return false;
+	}
+
+	if(is_object(comparison_value) || comparison_value instanceof RegExp) {
+		return false;
+	}
+
+	return schema_instance.is_array_root(path_value);
+}
+
+function is_array_root(compile_context, root_path) {
+	const schema_instance = compile_context.schema_instance;
+
+	if(!schema_instance || !is_function(schema_instance.is_array_root)) {
+		return false;
+	}
+
+	return schema_instance.is_array_root(root_path);
+}
+
+function create_compile_context(compile_options) {
+	const options = compile_options ?? {};
+	const data_column_name = options.data_column ?? 'data';
+	const data_column_reference = quote_identifier(data_column_name);
+	const schema_instance = options.schema ?? null;
+	const id_strategy = options.id_strategy === ID_STRATEGY.uuidv7 ? ID_STRATEGY.uuidv7 : ID_STRATEGY.bigserial;
+
+	return {
+		data_column_reference,
+		schema_instance,
+		id_strategy
+	};
+}
+
+function has_operator_entries(object_value) {
+	const keys = Object.keys(object_value);
+	let key_index = 0;
+
+	while(key_index < keys.length) {
+		if(keys[key_index][0] === '$') {
+			return true;
+		}
+
+		key_index += 1;
+	}
+
+	return false;
+}
+
+export {
+	create_compile_context,
+	has_operator_entries,
+	is_array_root,
+	resolve_query_field_type,
+	should_use_array_contains
+};

package/src/sql/read/where/field-clause.js

@@ -0,0 +1,58 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Compile one read-query field clause into SQL.
+ */
+import {build_text_expression} from '#src/sql/jsonb/path-parser.js';
+import contains_operator from '#src/sql/jsonb/read/operators/contains.js';
+import {eq_operator, regex_operator} from '#src/sql/read/where/operators/index.js';
+import {compile_base_field_clause, resolve_base_field_name} from '#src/sql/read/where/base-fields.js';
+
+import {cast_array_contains_value, cast_query_value} from '#src/sql/read/where/casting.js';
+import {has_operator_entries, should_use_array_contains} from '#src/sql/read/where/context.js';
+import {compile_elem_match_clause} from '#src/sql/jsonb/read/elem-match.js';
+import {compile_operator_object} from '#src/sql/read/where/operators.js';
+
+import {build_nested_object} from '#src/utils/object-path.js';
+import {is_object} from '#src/utils/value.js';
+
+function compile_field_clause(path_value, comparison_value, compile_context, parameter_state) {
+	const data_column_reference = compile_context.data_column_reference;
+	const is_array_path = should_use_array_contains(path_value, comparison_value, compile_context);
+	const base_field_name = resolve_base_field_name(path_value);
+
+	if(base_field_name) {
+		return compile_base_field_clause(base_field_name, comparison_value, compile_context, parameter_state);
+	}
+
+	if(comparison_value instanceof RegExp) {
+		const text_expression = build_text_expression(data_column_reference, path_value);
+		return regex_operator(text_expression, comparison_value.source, comparison_value.flags, parameter_state);
+	}
+
+	if(is_object(comparison_value)) {
+		if(comparison_value.$elem_match !== undefined) {
+			return compile_elem_match_clause(path_value, comparison_value.$elem_match, data_column_reference, parameter_state);
+		}
+
+		if(has_operator_entries(comparison_value)) {
+			return compile_operator_object(path_value, comparison_value, compile_context, parameter_state);
+		}
+
+		const nested_object = build_nested_object(path_value, comparison_value);
+		return contains_operator(data_column_reference, nested_object, parameter_state);
+	}
+
+	if(is_array_path) {
+		const casted_array_value = cast_array_contains_value(path_value, comparison_value, compile_context);
+		const nested_object = build_nested_object(path_value, [casted_array_value]);
+		return contains_operator(data_column_reference, nested_object, parameter_state);
+	}
+
+	const text_expression = build_text_expression(data_column_reference, path_value);
+	const casted_comparison_value = cast_query_value(path_value, comparison_value, compile_context);
+	return eq_operator(text_expression, casted_comparison_value, parameter_state);
+}
+
+export {
+	compile_field_clause
+};