jsonbadger 0.5.0

package/src/query/where-compiler.js

@@ -0,0 +1,477 @@
+import {
+	all_operator,
+	contains_operator,
+	elem_match_operator,
+	eq_operator,
+	gt_operator,
+	gte_operator,
+	has_all_keys_operator,
+	has_any_keys_operator,
+	has_key_operator,
+	in_operator,
+	jsonpath_exists_operator,
+	jsonpath_match_operator,
+	lt_operator,
+	lte_operator,
+	ne_operator,
+	nin_operator,
+	regex_operator,
+	size_operator
+} from '#src/query/operators/index.js';
+
+import {build_elem_text_expression, build_json_expression, build_text_expression, parse_path} from '#src/query/path-parser.js';
+
+import {create_parameter_state} from '#src/sql/parameter-binder.js';
+
+import {quote_identifier} from '#src/utils/assert.js';
+import {build_nested_object, split_dot_path} from '#src/utils/object-path.js';
+import {is_object} from '#src/utils/value.js';
+
+// TODO: might as well split into multiple files within the same directory
+
+function where_compiler(query_filter, compile_options, start_index) {
+	const filter_object = query_filter ?? {};
+	const options = compile_options ?? {};
+	const parameter_state = create_parameter_state(start_index);
+	const clause_list = [];
+	const filter_entries = Object.entries(filter_object);
+	let entry_index = 0;
+
+	while(entry_index < filter_entries.length) {
+		const entry_pair = filter_entries[entry_index];
+		const path_value = entry_pair[0];
+		const comparison_value = entry_pair[1];
+		const clause = compile_field_clause(path_value, comparison_value, options, parameter_state);
+
+		if(clause) {
+			clause_list.push(clause);
+		}
+
+		entry_index += 1;
+	}
+
+	return {
+		sql: clause_list.length > 0 ? clause_list.join(' AND ') : 'TRUE',
+		params: parameter_state.params,
+		next_index: parameter_state.current_index
+	};
+}
+
+function compile_field_clause(path_value, comparison_value, compile_options, parameter_state) {
+	const data_column_name = compile_options?.data_column ?? 'data';
+	const data_column_reference = quote_identifier(data_column_name);
+	const schema_instance = compile_options?.schema ?? null;
+	const is_array_path = should_use_array_contains(path_value, comparison_value, schema_instance);
+
+	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, data_column_reference, schema_instance, 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, schema_instance);
+		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, schema_instance);
+	return eq_operator(text_expression, casted_comparison_value, parameter_state);
+}
+
+function compile_operator_object(path_value, operator_definition, data_column_reference, schema_instance, parameter_state) {
+	const clause_list = [];
+	const operator_entries = Object.entries(operator_definition);
+	const path_info = parse_path(path_value);
+	const regex_options = operator_definition.$options || '';
+	const has_array_root = is_array_root(schema_instance, path_info.root_path) && path_info.child_segments.length > 0;
+	let entry_index = 0;
+
+	while(entry_index < operator_entries.length) {
+		const operator_entry = operator_entries[entry_index];
+		const operator_name = operator_entry[0];
+		const operator_value = operator_entry[1];
+
+		if(operator_name === '$options') {
+			entry_index += 1;
+			continue;
+		}
+
+		if(has_array_root) {
+			clause_list.push(
+				compile_nested_array_operator(
+					operator_name,
+					operator_value,
+					regex_options,
+					path_info,
+					data_column_reference,
+					parameter_state
+				)
+			);
+			entry_index += 1;
+			continue;
+		}
+
+		clause_list.push(
+			compile_standard_operator(
+				operator_name,
+				operator_value,
+				regex_options,
+				path_value,
+				data_column_reference,
+				schema_instance,
+				parameter_state
+			)
+		);
+		entry_index += 1;
+	}
+
+	return clause_list.join(' AND ');
+}
+
+function compile_standard_operator(operator_name, operator_value, regex_options, path_value, data_column_reference, schema_instance, parameter_state) {
+	const text_expression = build_text_expression(data_column_reference, path_value);
+	const json_expression = build_json_expression(data_column_reference, path_value);
+	const casted_operator_value = cast_operator_value(path_value, operator_name, operator_value, schema_instance);
+
+	if(operator_name === '$eq') {
+		return eq_operator(text_expression, casted_operator_value, parameter_state);
+	}
+
+	if(operator_name === '$ne') {
+		return ne_operator(text_expression, casted_operator_value, parameter_state);
+	}
+
+	if(operator_name === '$gt') {
+		return gt_operator(text_expression, casted_operator_value, parameter_state);
+	}
+
+	if(operator_name === '$gte') {
+		return gte_operator(text_expression, casted_operator_value, parameter_state);
+	}
+
+	if(operator_name === '$lt') {
+		return lt_operator(text_expression, casted_operator_value, parameter_state);
+	}
+
+	if(operator_name === '$lte') {
+		return lte_operator(text_expression, casted_operator_value, parameter_state);
+	}
+
+	if(operator_name === '$in') {
+		return in_operator(text_expression, casted_operator_value, parameter_state);
+	}
+
+	if(operator_name === '$nin') {
+		return nin_operator(text_expression, casted_operator_value, parameter_state);
+	}
+
+	if(operator_name === '$regex') {
+		return regex_operator(text_expression, operator_value, regex_options, parameter_state);
+	}
+
+	if(operator_name === '$contains') {
+		const nested_object = build_nested_object(path_value, operator_value);
+		return contains_operator(data_column_reference, nested_object, parameter_state);
+	}
+
+	if(operator_name === '$has_key') {
+		return has_key_operator(json_expression, operator_value, parameter_state);
+	}
+
+	if(operator_name === '$has_any_keys') {
+		return has_any_keys_operator(json_expression, operator_value, parameter_state);
+	}
+
+	if(operator_name === '$has_all_keys') {
+		return has_all_keys_operator(json_expression, operator_value, parameter_state);
+	}
+
+	if(operator_name === '$json_path_exists') {
+		return jsonpath_exists_operator(json_expression, operator_value, parameter_state);
+	}
+
+	if(operator_name === '$json_path_match') {
+		return jsonpath_match_operator(json_expression, operator_value, parameter_state);
+	}
+
+	if(operator_name === '$all') {
+		return all_operator(json_expression, casted_operator_value, parameter_state);
+	}
+
+	if(operator_name === '$size') {
+		return size_operator(json_expression, operator_value, parameter_state);
+	}
+
+	throw new Error('Unsupported operator: ' + operator_name);
+}
+
+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_scalar_operator(operator_name, operator_value, regex_options, elem_expression, parameter_state);
+
+	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 operator_entries = Object.entries(elem_match_value);
+		const option_value = elem_match_value.$options || '';
+		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') {
+				operator_index += 1;
+				continue;
+			}
+
+			predicate_list.push(
+				compile_scalar_operator(operator_name, operator_value, option_value, "elem #>> '{}'", parameter_state)
+			);
+			operator_index += 1;
+		}
+
+		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 nested_operator_entries = Object.entries(nested_value);
+			const option_value = nested_value.$options || '';
+			let operator_index = 0;
+
+			while(operator_index < nested_operator_entries.length) {
+				const operator_entry = nested_operator_entries[operator_index];
+				const operator_name = operator_entry[0];
+				const operator_value = operator_entry[1];
+
+				if(operator_name === '$options') {
+					operator_index += 1;
+					continue;
+				}
+
+				predicate_list.push(
+					compile_scalar_operator(operator_name, operator_value, option_value, elem_expression, parameter_state)
+				);
+				operator_index += 1;
+			}
+
+			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 '));
+}
+
+function compile_scalar_operator(operator_name, operator_value, regex_options, elem_expression, parameter_state) {
+	if(operator_name === '$eq') {
+		return eq_operator(elem_expression, operator_value, parameter_state);
+	}
+
+	if(operator_name === '$ne') {
+		return ne_operator(elem_expression, operator_value, parameter_state);
+	}
+
+	if(operator_name === '$gt') {
+		return gt_operator(elem_expression, operator_value, parameter_state);
+	}
+
+	if(operator_name === '$gte') {
+		return gte_operator(elem_expression, operator_value, parameter_state);
+	}
+
+	if(operator_name === '$lt') {
+		return lt_operator(elem_expression, operator_value, parameter_state);
+	}
+
+	if(operator_name === '$lte') {
+		return lte_operator(elem_expression, operator_value, parameter_state);
+	}
+
+	if(operator_name === '$in') {
+		return in_operator(elem_expression, operator_value, parameter_state);
+	}
+
+	if(operator_name === '$nin') {
+		return nin_operator(elem_expression, operator_value, parameter_state);
+	}
+
+	if(operator_name === '$regex') {
+		return regex_operator(elem_expression, operator_value, regex_options, parameter_state);
+	}
+
+	throw new Error('Unsupported operator inside $elem_match: ' + operator_name);
+}
+
+function cast_operator_value(path_value, operator_name, operator_value, schema_instance) {
+	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, schema_instance);
+	}
+
+	if(operator_name === '$in' || operator_name === '$nin') {
+		if(!Array.isArray(operator_value)) {
+			return [cast_query_value(path_value, operator_value, schema_instance)];
+		}
+
+		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], schema_instance));
+			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], schema_instance));
+			value_index += 1;
+		}
+
+		return casted_values;
+	}
+
+	return operator_value;
+}
+
+function cast_query_value(path_value, comparison_value, schema_instance) {
+	if(comparison_value === undefined || comparison_value === null) {
+		return comparison_value;
+	}
+
+	const field_type = resolve_query_field_type(schema_instance, path_value);
+
+	if(!field_type || typeof field_type.cast !== 'function') {
+		return comparison_value;
+	}
+
+	return field_type.cast(comparison_value, {
+		path: path_value,
+		mode: 'query'
+	});
+}
+
+function cast_array_contains_value(path_value, comparison_value, schema_instance) {
+	const field_type = resolve_query_field_type(schema_instance, path_value);
+
+	if(!field_type || field_type.instance !== 'Array' || !field_type.of_field_type || typeof field_type.of_field_type.cast !== 'function') {
+		return comparison_value;
+	}
+
+	return field_type.of_field_type.cast(comparison_value, {
+		path: path_value,
+		mode: 'query'
+	});
+}
+
+function resolve_query_field_type(schema_instance, path_value) {
+	if(!schema_instance || typeof schema_instance.path !== 'function') {
+		return null;
+	}
+
+	return schema_instance.path(path_value);
+}
+
+function should_use_array_contains(path_value, comparison_value, schema_instance) {
+	if(!schema_instance || typeof schema_instance.is_array_root !== 'function') {
+		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(schema_instance, root_path) {
+	if(!schema_instance || typeof schema_instance.is_array_root !== 'function') {
+		return false;
+	}
+
+	return schema_instance.is_array_root(root_path);
+}
+
+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 default where_compiler;
+

package/src/schema/field-definition-parser.js

@@ -0,0 +1,218 @@
+/*
+Assumptions and trade-offs:
+- Type-key rules are strict: explicit declarations win when `type` is a supported type reference.
+- Plain-object `of` definitions for Array/Map are normalized to Mixed in this phase.
+*/
+import {default_field_type_registry} from '#src/field-types/registry.js';
+import {is_array, is_not_array} from '#src/utils/array.js';
+
+export default function field_definition_parser(schema_definition, registry_instance) {
+	const parse_state = {
+		field_types: Object.create(null),
+		object_paths: new Set()
+	};
+	const schema_root = schema_definition || {};
+	const field_registry = registry_instance || default_field_type_registry;
+
+	parse_schema_object(schema_root, '', field_registry, parse_state);
+
+	return {
+		field_types: parse_state.field_types,
+		object_paths: parse_state.object_paths
+	};
+}
+
+function parse_schema_object(schema_object, parent_path, field_registry, parse_state) {
+	if(!is_plain_object(schema_object)) {
+		throw new Error('Schema definition must be an object');
+	}
+
+	const schema_entries = Object.entries(schema_object);
+	let entry_index = 0;
+
+	while(entry_index < schema_entries.length) {
+		const schema_entry = schema_entries[entry_index];
+		const path_segment = schema_entry[0];
+		const field_definition = schema_entry[1];
+		const path_value = parent_path ? parent_path + '.' + path_segment : path_segment;
+		const parsed_field = parse_field_definition(path_value, field_definition, field_registry);
+
+		if(parsed_field.kind === 'field_type') {
+			parse_state.field_types[path_value] = parsed_field.field_type;
+			entry_index += 1;
+			continue;
+		}
+
+		parse_state.object_paths.add(path_value);
+		parse_schema_object(parsed_field.nested_schema, path_value, field_registry, parse_state);
+		entry_index += 1;
+	}
+}
+
+function parse_field_definition(path_value, field_definition, field_registry) {
+	if(is_array(field_definition)) {
+		return {
+			kind: 'field_type',
+			field_type: create_array_field_type(path_value, field_definition, {}, field_registry)
+		};
+	}
+
+	if(field_registry.has_field_type(field_definition)) {
+		return {
+			kind: 'field_type',
+			field_type: field_registry.create_field_type(path_value, field_definition, {})
+		};
+	}
+
+	if(is_plain_object(field_definition)) {
+		const definition_keys = Object.keys(field_definition);
+
+		if(definition_keys.length === 0) {
+			return {
+				kind: 'field_type',
+				field_type: field_registry.create_field_type(path_value, 'Mixed', {})
+			};
+		}
+
+		if(should_use_explicit_type(field_definition, field_registry)) {
+			return {
+				kind: 'field_type',
+				field_type: create_explicit_field_type(path_value, field_definition, field_registry)
+			};
+		}
+
+		return {
+			kind: 'nested',
+			nested_schema: field_definition
+		};
+	}
+
+	throw new Error('Invalid field definition at path "' + path_value + '"');
+}
+
+function should_use_explicit_type(field_definition, field_registry) {
+	if(!Object.prototype.hasOwnProperty.call(field_definition, 'type')) {
+		return false;
+	}
+
+	const type_key = field_definition.type;
+
+	if(is_array(type_key)) {
+		return true;
+	}
+
+	return field_registry.has_field_type(type_key);
+}
+
+function create_explicit_field_type(path_value, field_definition, field_registry) {
+	const type_key = field_definition.type;
+	const of_definition = field_definition.of;
+	const field_options = Object.assign({}, field_definition);
+
+	// Remove schema-definition syntax keys after extracting them.
+	// Runtime FieldType instances should receive internal option keys (for example, `of_field_type`),
+	// not parser syntax keys like `type` or `of`.
+	delete field_options.type;
+	delete field_options.of;
+
+	if(is_array(type_key)) {
+		return create_array_field_type(path_value, type_key, field_options, field_registry);
+	}
+
+	const type_name = field_registry.resolve_field_type_name(type_key);
+
+	if(!type_name) {
+		throw new Error('Unsupported field type at path "' + path_value + '"');
+	}
+
+	if(type_name === 'Array') {
+		const explicit_array_definition = of_definition !== undefined ? [of_definition] : [];
+		return create_array_field_type(path_value, explicit_array_definition, field_options, field_registry);
+	}
+
+	if(type_name === 'Map') {
+		field_options.of_field_type = create_of_field_type(path_value, of_definition, field_registry);
+		return field_registry.create_field_type(path_value, type_name, field_options);
+	}
+
+	if(type_name === 'Union') {
+		field_options.of_field_types = create_union_field_types(path_value, of_definition, field_registry);
+		return field_registry.create_field_type(path_value, type_name, field_options);
+	}
+
+	return field_registry.create_field_type(path_value, type_name, field_options);
+}
+
+function create_array_field_type(path_value, array_definition, field_options, field_registry) {
+	if(array_definition.length > 1) {
+		throw new Error('Array type definition at path "' + path_value + '" must contain at most one item type');
+	}
+
+	const array_options = Object.assign({}, field_options || {});
+	const item_definition = array_definition.length === 1 ? array_definition[0] : undefined;
+
+	array_options.of_field_type = create_of_field_type(path_value, item_definition, field_registry);
+	return field_registry.create_field_type(path_value, 'Array', array_options);
+}
+
+function create_union_field_types(path_value, union_of_definition, field_registry) {
+	if(is_not_array(union_of_definition) || union_of_definition.length === 0) {
+		throw new Error('Union type definition at path "' + path_value + '" must define a non-empty "of" array');
+	}
+
+	const union_field_types = [];
+	let type_index = 0;
+
+	while(type_index < union_of_definition.length) {
+		union_field_types.push(create_union_candidate_field_type(path_value, union_of_definition[type_index], field_registry));
+		type_index += 1;
+	}
+
+	return union_field_types;
+}
+
+function create_union_candidate_field_type(path_value, union_definition, field_registry) {
+	if(is_array(union_definition)) {
+		return create_array_field_type(path_value, union_definition, {}, field_registry);
+	}
+
+	if(field_registry.has_field_type(union_definition)) {
+		return field_registry.create_field_type(path_value, union_definition, {});
+	}
+
+	if(is_plain_object(union_definition) && should_use_explicit_type(union_definition, field_registry)) {
+		return create_explicit_field_type(path_value, union_definition, field_registry);
+	}
+
+	throw new Error('Unsupported union type at path "' + path_value + '"');
+}
+
+function create_of_field_type(path_value, of_definition, field_registry) {
+	const item_path = path_value + '.$';
+
+	if(of_definition === undefined) {
+		return field_registry.create_field_type(item_path, 'Mixed', {});
+	}
+
+	if(is_array(of_definition)) {
+		return create_array_field_type(item_path, of_definition, {}, field_registry);
+	}
+
+	if(field_registry.has_field_type(of_definition)) {
+		return field_registry.create_field_type(item_path, of_definition, {});
+	}
+
+	if(is_plain_object(of_definition)) {
+		if(should_use_explicit_type(of_definition, field_registry)) {
+			return create_explicit_field_type(item_path, of_definition, field_registry);
+		}
+
+		return field_registry.create_field_type(item_path, 'Mixed', {});
+	}
+
+	throw new Error('Unsupported "of" definition at path "' + path_value + '"');
+}
+
+function is_plain_object(value) {
+	return value !== null && typeof value === 'object' && is_not_array(value);
+}