jsonbadger 0.5.0 → 0.6.0

package/src/model/operations/delete-one.js

@@ -0,0 +1,39 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Execute the model-layer delete-one persistence path.
+ */
+import sql from '#src/sql/index.js';
+import where_compiler from '#src/sql/read/where/index.js';
+import {quote_identifier} from '#src/utils/assert.js';
+
+/**
+ * Execute Model.delete_one() for a model constructor.
+ *
+ * @param {Function} model Model constructor.
+ * @param {object|undefined} query_filter Query filter.
+ * @returns {Promise<object|null>}
+ */
+async function exec_delete_one(model, query_filter) {
+	const schema = model.schema;
+	const id_strategy = schema.id_strategy;
+
+	const model_options = model.options;
+	const data_column = model_options.data_column;
+	const table_name = model_options.table_name;
+
+	const table_identifier = quote_identifier(table_name);
+	const data_identifier = quote_identifier(data_column);
+	const where_result = where_compiler(query_filter, {schema, data_column, id_strategy});
+	const query_context = {table_identifier, data_identifier, where_result};
+
+	const delete_query = sql.build_delete_query(query_context);
+	const query_result = await sql.run(delete_query.sql_text, delete_query.sql_params, model.connection);
+	const rows = query_result.rows;
+	const row = rows.length ? rows[0] : null;
+
+	return row;
+}
+
+export {
+	exec_delete_one
+};

package/src/model/operations/insert-one.js

@@ -0,0 +1,35 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Execute the model-layer insert-one persistence path.
+ */
+import sql from '#src/sql/index.js';
+import {quote_identifier} from '#src/utils/assert.js';
+
+/**
+ * Execute one insert against prepared SQL-facing insert state.
+ *
+ * @param {Function} model Model constructor.
+ * @param {object} data Prepared insert state.
+ * @param {object} data.payload JSONB payload for the data column.
+ * @param {object} data.base_fields Row-level fields to persist outside the data column.
+ * @returns {Promise<object|null>}
+ */
+async function exec_insert_one(model, data) {
+	const model_options = model.options;
+	const table_name = model_options.table_name;
+	const data_column = model_options.data_column;
+	const table_identifier = quote_identifier(table_name);
+	const data_identifier = quote_identifier(data_column);
+	const payload = data.payload;
+	const base_fields = data.base_fields;
+
+	const insert_query = sql.build_insert_query({table_identifier, data_identifier, payload, base_fields});
+	const query_result = await sql.run(insert_query.sql_text, insert_query.sql_params, model.connection);
+	const saved_row = query_result.rows[0];
+
+	return saved_row;
+}
+
+export {
+	exec_insert_one
+};

package/src/model/operations/query-builder.js

@@ -0,0 +1,132 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Own model-facing query state, execution dispatch, and row hydration for read operations.
+ */
+import build_count_query from '#src/sql/read/build-count-query.js';
+import build_find_query from '#src/sql/read/build-find-query.js';
+import where_compiler from '#src/sql/read/where/index.js';
+
+import run from '#src/sql/run.js';
+
+import {assert_condition, quote_identifier} from '#src/utils/assert.js';
+import {is_object, to_iso_timestamp} from '#src/utils/value.js';
+
+function QueryBuilder(model, operation, query_filter) {
+	assert_condition(model, 'QueryBuilder requires model');
+	assert_condition(model.schema, 'QueryBuilder requires model.schema');
+	assert_condition(model.options, 'QueryBuilder requires model.options');
+
+	this.connection = model.connection || null;
+	this.model = model;
+	this.operation = operation;
+	this.base_filter = query_filter || {};
+	this.where_filter = {};
+	this.sort_filter = null;
+	this.limit_count = null;
+	this.skip_count = null;
+}
+
+QueryBuilder.prototype.where = function (extra_filter) {
+	this.where_filter = Object.assign({}, this.where_filter, extra_filter || {});
+	return this;
+};
+
+QueryBuilder.prototype.sort = function (sort_filter) {
+	this.sort_filter = sort_filter || null;
+	return this;
+};
+
+QueryBuilder.prototype.limit = function (limit_value) {
+	this.limit_count = limit_value;
+	return this;
+};
+
+QueryBuilder.prototype.skip = function (skip_value) {
+	this.skip_count = skip_value;
+	return this;
+};
+
+QueryBuilder.prototype.exec = async function () {
+	// Query execution is the queried/hydrated lifecycle boundary for read methods:
+	// rows become document instances through `model.hydrate(...)`.
+	const schema = this.model.schema;
+	const id_strategy = schema.id_strategy;
+	const model_options = this.model.options;
+
+	const table_name = model_options.table_name;
+	const data_column = model_options.data_column;
+
+	const table_identifier = quote_identifier(table_name);
+	const data_identifier = quote_identifier(data_column);
+	const limit_count = this.operation === 'find_one' ? 1 : this.limit_count;
+
+	const merged_filter = Object.assign({}, this.base_filter, this.where_filter);
+	const where_result = where_compiler(merged_filter, {schema, data_column, id_strategy});
+	const query_context = {
+		connection: this.connection,
+		table_identifier,
+		data_identifier,
+		data_column,
+		where_result,
+		sort: this.sort_filter,
+		limit_count,
+		skip_count: this.skip_count
+	};
+
+	const model = this.model;
+
+	switch(this.operation) {
+		case 'count_documents': {
+			return exec_count_documents(query_context);
+		}
+
+		case 'find_one': {
+			const rows = await exec_find_query(query_context);
+			return rows.length ? model.hydrate(row_to_document(rows[0])) : null;
+		}
+
+		case 'find': {
+			const rows = await exec_find_query(query_context);
+			const documents = [];
+
+			for(const row of rows) {
+				documents.push(model.hydrate(row_to_document(row)));
+			}
+
+			return documents;
+		}
+
+		default: {
+			throw new Error('Unsupported query operation: ' + this.operation);
+		}
+	}
+};
+
+function row_to_document(row) {
+	return {
+		id: row.id != null ? String(row.id) : null,
+		data: is_object(row.data) ? row.data : {},
+		created_at: to_iso_timestamp(row.created_at),
+		updated_at: to_iso_timestamp(row.updated_at)
+	};
+}
+
+async function exec_count_documents(query_context) {
+	const count_query = build_count_query(query_context);
+	const count_result = await run(count_query.sql_text, count_query.sql_params, query_context.connection);
+	const rows = count_result.rows;
+
+	if(rows.length === 0) {
+		return 0;
+	}
+
+	return Number(rows[0].total_count);
+}
+
+async function exec_find_query(query_context) {
+	const find_query = build_find_query(query_context);
+	const query_result = await run(find_query.sql_text, find_query.sql_params, query_context.connection);
+	return query_result.rows;
+}
+
+export default QueryBuilder;

package/src/model/operations/update-one.js

@@ -0,0 +1,333 @@
+/*
+ * MODULE RESPONSIBILITY
+ * Bridge model-layer update input into the SQL update context.
+ */
+import sql from '#src/sql/index.js';
+import where_compiler from '#src/sql/read/where/index.js';
+import {create_parameter_state} from '#src/sql/parameter-binder.js';
+
+import {JsonbOps} from '#src/sql/jsonb/ops.js';
+import {timestamp_fields} from '#src/model/factory/constants.js';
+import {is_array} from '#src/utils/array.js';
+import {quote_identifier} from '#src/utils/assert.js';
+import {expand_dot_paths} from '#src/utils/object-path.js';
+import {has_own} from '#src/utils/object.js';
+import {is_not_object, is_object, is_plain_object} from '#src/utils/value.js';
+
+// --- PUBLIC API ---
+
+/**
+ * Execute Model.update_one() by coordinating syntax parsing and SQL generation.
+ *
+ * @param {Function} model
+ * @param {object} query_filter
+ * @param {object} update_definition
+ * @returns {Promise<object|null>}
+ */
+async function exec_update_one(model, query_filter, update_definition) {
+	if(is_not_object(update_definition) || Object.keys(update_definition).length === 0) {
+		return null;
+	}
+
+	const model_options = model.options;
+	const data_column = model_options.data_column;
+
+	const gateway_definition = normalize_update_gateway(update_definition);
+	const {timestamp_set, payload} = normalize_update_definition(gateway_definition, data_column);
+
+	const data_identifier = quote_identifier(data_column);
+	const jsonb_ops = JsonbOps.from(payload, {
+		column_name: data_identifier,
+		coalesce: true
+	});
+
+	const where_result = where_compiler(query_filter, {
+		schema: model.schema,
+		data_column,
+		id_strategy: model.schema.id_strategy
+	});
+
+	const parameter_state = create_parameter_state(where_result.next_index);
+
+	const query_context = {
+		model,
+		table_identifier: quote_identifier(model_options.table_name),
+		data_identifier,
+		where_result,
+		parameter_state,
+		update_expression: {
+			jsonb_ops,
+			timestamp_set
+		}
+	};
+
+	const update_query = sql.build_update_query(query_context);
+	const query_result = await sql.run(update_query.sql_text, update_query.sql_params, model.connection);
+	const row = query_result.rows.length ? query_result.rows[0] : null;
+
+	return row;
+}
+
+// --- LOCAL HELPER FUNCTIONS ---
+
+/**
+ * Expand public dotted update input before the existing router consumes it.
+ *
+ * @param {object} update_definition
+ * @returns {object}
+ * @throws {Error} If update input includes invalid or restricted dotted paths.
+ */
+function normalize_update_gateway(update_definition) {
+	if(is_tracker_delta_update(update_definition)) {
+		return update_definition;
+	}
+
+	const implicit_definition = {};
+	const normalized_definition = {};
+
+	for(const [key, value] of Object.entries(update_definition)) {
+		if(key.startsWith('$')) {
+			normalized_definition[key] = normalize_update_operator_value(key, value);
+			continue;
+		}
+
+		implicit_definition[key] = value;
+	}
+
+	return Object.assign({}, normalized_definition, expand_dot_paths(implicit_definition));
+}
+
+/**
+ * Detect the internal tracker delta shape so public gateway expansion stays out of that path.
+ *
+ * @param {object} update_definition
+ * @returns {boolean}
+ */
+function is_tracker_delta_update(update_definition) {
+	return is_object(update_definition) && (
+		has_own(update_definition, 'set') ||
+		has_own(update_definition, 'unset') ||
+		has_own(update_definition, 'replace_roots')
+	);
+}
+
+/**
+ * Normalize one operator payload before the router turns it into SQL-oriented state.
+ *
+ * @param {string} operator_name
+ * @param {*} operator_value
+ * @returns {*}
+ * @throws {Error} If operator input includes invalid or restricted dotted paths.
+ */
+function normalize_update_operator_value(operator_name, operator_value) {
+	if((operator_name === '$set' || operator_name === '$replace_roots') && is_object(operator_value)) {
+		return expand_dot_paths(operator_value);
+	}
+
+	return operator_value;
+}
+
+/**
+ * Normalize one update definition into row timestamps plus operator-style JSONB payload.
+ *
+ * @param {object} update_definition
+ * @param {string} data_column
+ * @returns {{timestamp_set: object, payload: object}}
+ */
+function normalize_update_definition(update_definition, data_column) {
+	const timestamp_set = {};
+	const payload = pull_timestamp_fields(update_definition, timestamp_set);
+
+	merge_tracked_set(payload, data_column, timestamp_set);
+	merge_tracked_unset(payload, data_column);
+	merge_tracked_replace_roots(payload, data_column);
+	move_implicit_set_values(payload);
+
+	return {timestamp_set, payload};
+}
+
+/**
+ * Safely map tracker-emitted "set" objects to the explicit "$set" bucket.
+ *
+ * @param {object} payload
+ * @param {string} data_column
+ * @param {object} timestamp_set
+ * @returns {void}
+ */
+function merge_tracked_set(payload, data_column, timestamp_set) {
+	if(is_object(payload.$set)) {
+		payload.$set = flatten_update_paths(pull_timestamp_fields(payload.$set, timestamp_set));
+	}
+
+	if(!is_object(payload.set)) {
+		return;
+	}
+
+	const tracked_set = pull_timestamp_fields(payload.set, timestamp_set);
+	const set_payload = is_object(payload.$set) ? payload.$set : {};
+
+	delete payload.set;
+	payload.$set = set_payload;
+
+	for(const [path_name, value] of Object.entries(tracked_set)) {
+		const next_path = strip_tracked_root(path_name, data_column);
+
+		if(next_path !== '') {
+			set_payload[next_path] = value;
+		}
+	}
+}
+
+/**
+ * Safely map tracker-emitted "unset" arrays to the explicit "$unset" bucket.
+ *
+ * @param {object} payload
+ * @param {string} data_column
+ * @returns {void}
+ */
+function merge_tracked_unset(payload, data_column) {
+	if(!is_array(payload.unset)) {
+		return;
+	}
+
+	const tracked_unset = payload.unset;
+	const unset_payload = is_array(payload.$unset) ? payload.$unset : [];
+
+	delete payload.unset;
+	payload.$unset = unset_payload;
+
+	for(const path_name of tracked_unset) {
+		const next_path = strip_tracked_root(path_name, data_column);
+
+		if(next_path === '') {
+			payload.$replace_roots = {};
+		} else {
+			unset_payload.push(next_path);
+		}
+	}
+}
+
+/**
+ * Safely map tracker-emitted "replace_roots" objects to the explicit "$replace_roots" bucket.
+ *
+ * @param {object} payload
+ * @param {string} data_column
+ * @returns {void}
+ */
+function merge_tracked_replace_roots(payload, data_column) {
+	if(!is_object(payload.replace_roots)) {
+		return;
+	}
+
+	const next_root_payload = payload.replace_roots[data_column];
+	delete payload.replace_roots;
+
+	if(next_root_payload !== undefined) {
+		payload.$replace_roots = next_root_payload;
+	}
+}
+
+/**
+ * Extract supported row timestamp fields from one payload object.
+ *
+ * @param {object} source_object
+ * @param {object} timestamp_set
+ * @returns {object}
+ */
+function pull_timestamp_fields(source_object, timestamp_set) {
+	const next_object = {...source_object};
+
+	for(const key of timestamp_fields) {
+		if(has_own(next_object, key)) {
+			timestamp_set[key] = next_object[key];
+			delete next_object[key];
+		}
+	}
+
+	return next_object;
+}
+
+/**
+ * Move implicit object keys into the explicit `$set` bucket as leaf dot paths.
+ *
+ * @param {object} payload
+ * @returns {void}
+ */
+function move_implicit_set_values(payload) {
+	const implicit_source = {};
+
+	for(const [key, value] of Object.entries(payload)) {
+		if(key.startsWith('$')) {
+			continue;
+		}
+
+		implicit_source[key] = value;
+		delete payload[key];
+	}
+
+	if(Object.keys(implicit_source).length === 0) {
+		return;
+	}
+
+	const implicit_set = flatten_update_paths(implicit_source);
+	const set_payload = is_object(payload.$set) ? payload.$set : {};
+
+	payload.$set = set_payload;
+	Object.assign(set_payload, implicit_set);
+}
+
+/**
+ * Flatten nested object updates into leaf dot-path assignments for JSONB mutation.
+ *
+ * @param {object} source_object
+ * @param {string} [parent_path]
+ * @returns {object}
+ */
+function flatten_update_paths(source_object, parent_path = '') {
+	const path_map = {};
+
+	for(const [key, value] of Object.entries(source_object)) {
+		const next_path = parent_path ? `${parent_path}.${key}` : key;
+
+		if(is_plain_object(value)) {
+			const nested_keys = Object.keys(value);
+
+			if(nested_keys.length === 0) {
+				path_map[next_path] = {};
+				continue;
+			}
+
+			Object.assign(path_map, flatten_update_paths(value, next_path));
+			continue;
+		}
+
+		path_map[next_path] = value;
+	}
+
+	return path_map;
+}
+
+/**
+ * Strip the tracked root segment from one tracker-emitted path.
+ *
+ * @param {string} path_name
+ * @param {string} data_column
+ * @returns {string}
+ */
+function strip_tracked_root(path_name, data_column) {
+	if(path_name === data_column) {
+		return '';
+	}
+
+	const path_prefix = `${data_column}.`;
+
+	if(path_name.startsWith(path_prefix)) {
+		return path_name.substring(path_prefix.length);
+	}
+
+	return path_name;
+}
+
+export {
+	exec_update_one
+};

package/src/model/state.js

@@ -0,0 +1,34 @@
+const runtime_store = new WeakMap();
+
+/**
+ * Create and store one compiled-model runtime object by model constructor.
+ *
+ * @param {Function} key
+ * @param {object} init_data
+ * @returns {object}
+ */
+function create_runtime_store(key, init_data) {
+	const runtime_data = Object.assign({}, init_data);
+
+	runtime_store.set(key, runtime_data);
+	return runtime_data;
+}
+
+/**
+ * Read one compiled-model runtime object by model constructor.
+ *
+ * @param {Function} key
+ * @returns {object|null}
+ */
+function get_runtime_store(key) {
+	if(runtime_store.has(key)) {
+		return runtime_store.get(key);
+	}
+
+	return null;
+}
+
+export {
+	create_runtime_store,
+	get_runtime_store
+};