jsonbadger 0.5.0 → 0.6.0

package/src/utils/dirty-tracker/static.js

@@ -0,0 +1,343 @@
+import {deep_clone, is_function, is_not_object, is_object} from '#src/utils/value.js';
+
+// dirty-tracker: static
+
+/*
+ * MAIN API
+ */
+
+/**
+ * Wrap this object with dirty tracking and optional set interception.
+ *
+ * @param {object} target
+ * @param {object} [options]
+ * @param {object} [options.watch]
+ * @param {function} [options.intercept_set]
+ * @returns {Proxy}
+ */
+function track_changes(target, options = {}) {
+	const store = {
+		root_object: target,
+		base_state: deep_clone(target),
+		dirty_keys: new Set(),
+		watchers: []
+	};
+
+	let root_proxy;
+	const get_root = () => root_proxy;
+
+	// Build the intercepting proxy
+	root_proxy = build_proxy(target, target, store, get_root, options);
+
+	// Parse and bind Watchers
+	if(is_object(options.watch)) {
+		const watch_keys = Object.keys(options.watch);
+		let key_index = 0;
+
+		while(key_index < watch_keys.length) {
+			const watch_path = watch_keys[key_index];
+			add_watcher(root_proxy, watch_path, options.watch[watch_path]);
+			key_index += 1;
+		}
+	}
+
+	// Register the root proxy for static utility lookups
+	tracker_registry.set(root_proxy, store);
+
+	return root_proxy;
+}
+
+/*
+ * LAZY PROXY BUILDER
+ */
+
+function build_proxy(target_object, root_object, store, get_root, options = {}) {
+	const base_path = options.base_path || '';
+	let intercept_set = (path, next_value) => next_value;
+
+	if(is_function(options.intercept_set)) {
+		intercept_set = options.intercept_set;
+	}
+
+	return new Proxy(target_object, {
+		get(target, prop) {
+			// Do not proxy internal JS symbols
+			if(typeof prop === 'symbol') {
+				return target[prop];
+			}
+
+			// Root level: allow access to tracker methods
+			if(base_path === '') {
+				if(prop in target && is_function(target[prop])) {
+					return target[prop];
+				}
+			}
+
+			const value = target[prop];
+
+			// Lazy-proxy nested objects on access
+			if(is_object(value)) {
+				const next_path = base_path === '' ? prop : `${base_path}.${prop}`;
+				const next_options = {...options, base_path: next_path};
+				return build_proxy(value, root_object, store, get_root, next_options);
+			}
+
+			return value;
+		},
+
+		set(target, prop, value) {
+			if(typeof prop === 'symbol') {
+				target[prop] = value;
+				return true;
+			}
+
+			// Do not track mutations to functions/methods
+			if(base_path === '' && is_function(target[prop])) {
+				target[prop] = value;
+				return true;
+			}
+
+			const full_path = base_path === '' ? prop : `${base_path}.${prop}`;
+			const next_value = intercept_set(full_path, value);
+
+			const old_value = target[prop];
+			const original_value = read_path(store.base_state, full_path);
+
+			// Apply the mutation
+			target[prop] = next_value;
+
+			// Track Dirty State
+			if(original_value !== next_value) {
+				store.dirty_keys.add(full_path);
+			} else {
+				store.dirty_keys.delete(full_path);
+			}
+
+			// Trigger Watchers
+			if(old_value !== next_value) {
+				check_watchers(store, full_path, old_value, root_object, get_root());
+			}
+
+			return true;
+		}
+	});
+}
+
+/*
+ * STATE MANAGEMENT HELPERS
+ */
+
+const tracker_registry = new WeakMap();
+
+function has_dirty_fields(proxy) {
+	const store = tracker_registry.get(proxy);
+	return store ? store.dirty_keys.size > 0 : false;
+}
+
+function get_dirty_fields(proxy) {
+	const store = tracker_registry.get(proxy);
+	return store ? Array.from(store.dirty_keys) : [];
+}
+
+function reset_dirty_fields(proxy) {
+	const store = tracker_registry.get(proxy);
+
+	if(!store) {
+		return;
+	}
+
+	const original = store.base_state;
+	const original_keys = Object.keys(original);
+	let key_index = 0;
+
+	// Resetting through the proxy triggers setters naturally
+	while(key_index < original_keys.length) {
+		const key = original_keys[key_index];
+
+		if(!is_function(original[key])) {
+			proxy[key] = deep_clone(original[key]);
+		}
+
+		key_index += 1;
+	}
+
+	store.dirty_keys.clear();
+}
+
+function rebase_dirty_fields(proxy) {
+	const store = tracker_registry.get(proxy);
+
+	if(!store) {
+		return;
+	}
+
+	store.base_state = deep_clone(store.root_object);
+	store.dirty_keys.clear();
+}
+
+/*
+ * WATCHER HELPERS
+ */
+
+function add_watcher(proxy, path, options) {
+	const store = tracker_registry.get(proxy);
+
+	if(!store) {
+		throw new Error('Cannot add watcher: Object is not actively tracked.');
+	}
+
+	const handler = is_function(options) ? options : () => {};
+	const config = is_object(options) ? options : {handler};
+
+	const watcher = {
+		path,
+		handler: config.handler,
+		deep: config.deep === true,
+		once: config.once === true,
+		active: true
+	};
+
+	store.watchers.push(watcher);
+
+	if(config.immediate) {
+		const initial_value = read_path(store.root_object, path);
+		watcher.handler.call(proxy, initial_value, undefined);
+
+		if(watcher.once) {
+			watcher.active = false;
+		}
+	}
+
+	// Return the closure to unwatch
+	return () => {
+		watcher.active = false;
+		const index = store.watchers.indexOf(watcher);
+
+		if(index !== -1) {
+			store.watchers.splice(index, 1);
+		}
+	};
+}
+
+const pending_watchers = new Map();
+let is_flushing = false;
+
+function check_watchers(store, mutated_path, old_value, root_object, root_proxy) {
+	const watchers = store.watchers;
+	let watcher_index = 0;
+
+	while(watcher_index < watchers.length) {
+		const watcher = watchers[watcher_index];
+		if(!watcher.active) {
+			watcher_index += 1;
+			continue;
+		}
+
+		let should_trigger = false;
+		let handler_new_value = undefined;
+		let handler_old_value = old_value;
+
+		// Exact path match
+		if(watcher.path === mutated_path) {
+			should_trigger = true;
+			handler_new_value = read_path(root_object, mutated_path);
+		}
+		// Deep mutation (e.g., watching 'user', mutated 'user.name')
+		else if(watcher.deep && mutated_path.startsWith(watcher.path + '.')) {
+			should_trigger = true;
+			// In deep mutations, new and old values are identical references to the same parent object
+			handler_new_value = read_path(root_object, watcher.path);
+			handler_old_value = handler_new_value;
+		}
+		// Parent replacement (e.g., watching 'user.name', mutated 'user')
+		else if(watcher.path.startsWith(mutated_path + '.')) {
+			should_trigger = true;
+			handler_new_value = read_path(root_object, watcher.path);
+
+			// Attempt to extract the old nested value from the replaced parent object
+			const nested_path = watcher.path.substring(mutated_path.length + 1);
+			handler_old_value = read_path(old_value, nested_path);
+		}
+
+		if(should_trigger) {
+			queue_watcher(watcher, handler_new_value, handler_old_value, root_proxy);
+		}
+
+		watcher_index += 1;
+	}
+}
+
+function queue_watcher(watcher, new_value, old_value, context) {
+	// Deduplicate watchers in the same tick.
+	// If it exists, we update to the latest new_value, but keep the initial old_value of this tick.
+	if(pending_watchers.has(watcher)) {
+		pending_watchers.get(watcher).new_value = new_value;
+	} else {
+		pending_watchers.set(watcher, {new_value, old_value, context});
+	}
+
+	if(is_flushing) {
+		return;
+	}
+
+	is_flushing = true;
+
+	// Flush asynchronously on the next microtask (after synchronous code finishes)
+	Promise.resolve().then(() => {
+		const jobs = Array.from(pending_watchers.entries());
+		pending_watchers.clear();
+		is_flushing = false;
+
+		let job_index = 0;
+		while(job_index < jobs.length) {
+			const job_watcher = jobs[job_index][0];
+			const job_args = jobs[job_index][1];
+
+			if(job_watcher.active) {
+				job_watcher.handler.call(
+					job_args.context,
+					job_args.new_value,
+					job_args.old_value
+				);
+
+				if(job_watcher.once) {
+					job_watcher.active = false; // Mark inactive after first run
+				}
+			}
+			job_index += 1;
+		}
+	});
+}
+
+/*
+ * PATH HELPERS
+ */
+
+function read_path(root_object, dot_path) {
+	if(!dot_path) {
+		return root_object;
+	}
+
+	const segments = dot_path.split('.');
+	let current_value = root_object;
+	let segment_index = 0;
+
+	while(segment_index < segments.length) {
+		if(is_not_object(current_value)) {
+			return undefined;
+		}
+		current_value = current_value[segments[segment_index]];
+		segment_index += 1;
+	}
+
+	return current_value;
+}
+
+export {
+	track_changes,
+	has_dirty_fields,
+	get_dirty_fields,
+	reset_dirty_fields,
+	rebase_dirty_fields,
+	add_watcher
+};

package/src/utils/json-safe.js

@@ -1,9 +1,13 @@
-export function safe_json_stringify(value) {
-	try {
-		return JSON.stringify(value);
-	} catch(error) {
-		return '"[unserializable]"';
-	}
-}
-
-export default safe_json_stringify;
+function safe_json_stringify(value) {
+	try {
+		return JSON.stringify(value);
+	} catch(error) {
+		return '"[unserializable]"';
+	}
+}
+
+export default safe_json_stringify;
+
+export {
+	safe_json_stringify
+};

package/src/utils/object-path.js

@@ -1,33 +1,227 @@
-import {assert_path} from '#src/utils/assert.js';
-
-export function split_dot_path(path_value) {
-	assert_path(path_value, 'path');
-	return path_value.split('.');
-}
-
-export function build_path_literal(path_segments) {
-	return '{' + path_segments.join(',') + '}';
-}
-
-export function build_nested_object(path_value, leaf_value) {
-	const path_segments = split_dot_path(path_value);
-	const root_object = {};
-	let current_object = root_object;
-	let path_index = 0;
-
-	while(path_index < path_segments.length) {
-		const path_segment = path_segments[path_index];
-		const is_leaf = path_index === path_segments.length - 1;
-
-		if(is_leaf) {
-			current_object[path_segment] = leaf_value;
-			break;
-		}
-
-		current_object[path_segment] = {};
-		current_object = current_object[path_segment];
-		path_index += 1;
-	}
-
-	return root_object;
-}
+import {assert_path} from '#src/utils/assert.js';
+import {is_array} from '#src/utils/array.js';
+import {has_own} from '#src/utils/object.js';
+import {is_not_object, is_plain_object} from '#src/utils/value.js';
+
+// --- PUBLIC API ---
+
+/**
+ * Encodes an array of path segments into a PostgreSQL text array literal {a,b,c}.
+ *
+ * @param {string[]} path_segments
+ * @returns {string}
+ */
+function build_path_literal(path_segments) {
+	const escaped_segments = [];
+
+	for(const segment of path_segments) {
+		// Escape backslashes and double quotes with a backslash, then wrap in double quotes
+		escaped_segments.push('"' + String(segment).replace(/(["\\])/g, '\\$1') + '"');
+	}
+
+	return '{' + escaped_segments.join(',') + '}';
+}
+
+/**
+ * Recursively builds a nested object structure from a dot-path and a leaf value.
+ * Used for generating JSONB containment payloads.
+ *
+ * @param {string} path_value
+ * @param {*} leaf_value
+ * @returns {object}
+ * @throws {Error} If the path contains restricted prototype keys.
+ */
+function build_nested_object(path_value, leaf_value) {
+	const path_segments = split_dot_path(path_value);
+	const root_object = {};
+	let current_object = root_object;
+
+	const depth = path_segments.length - 1;
+	const leaf_segment = path_segments[depth];
+
+	for(let i = 0; i < depth; i++) {
+		const path_segment = path_segments[i];
+		current_object[path_segment] = {};
+		current_object = current_object[path_segment];
+	}
+
+	current_object[leaf_segment] = leaf_value;
+
+	return root_object;
+}
+
+/**
+ * Expands dotted object keys into nested object structures at the input boundary.
+ *
+ * @param {*} source_value
+ * @returns {*}
+ * @throws {Error} If any nested path contains restricted prototype keys.
+ */
+function expand_dot_paths(source_value) {
+	if(is_array(source_value)) {
+		const next_array = [];
+
+		for(const item of source_value) {
+			next_array.push(expand_dot_paths(item));
+		}
+
+		return next_array;
+	}
+
+	if(!is_plain_object(source_value)) {
+		return source_value;
+	}
+
+	const expanded_object = {};
+
+	for(const [path_name, next_value] of Object.entries(source_value)) {
+		const expanded_value = expand_dot_paths(next_value);
+
+		if(path_name.includes('.')) {
+			assign_nested_value(expanded_object, split_dot_path(path_name), expanded_value);
+		} else if(is_plain_object(expanded_value) && is_plain_object(expanded_object[path_name])) {
+			expanded_object[path_name] = merge_plain_objects(expanded_object[path_name], expanded_value);
+		} else {
+			expanded_object[path_name] = expanded_value;
+		}
+	}
+
+	return expanded_object;
+}
+
+/**
+ * Normalizes a dot-path by collapsing multiple consecutive dots and splitting into segments.
+ *
+ * @param {string} path_value
+ * @returns {string[]}
+ * @throws {Error} If the path contains restricted prototype keys.
+ */
+function split_dot_path(path_value) {
+	// Clean state: collapse multiple dots into one to prevent empty segment errors.
+	const clean_path = String(path_value).replace(/\.+/g, '.');
+
+	assert_path(clean_path, 'path');
+	const segments = clean_path.split('.');
+
+	for(const segment of segments) {
+		// Prevent Prototype Pollution by strictly blocking internal object keys
+		if(segment === '__proto__' || segment === 'constructor' || segment === 'prototype') {
+			throw new Error('Invalid path: restricted key name "' + segment + '"');
+		}
+	}
+
+	return segments;
+}
+
+/**
+ * Reads one nested value from an object path.
+ *
+ * @param {object} root_object
+ * @param {string[]} path_segments
+ * @returns {{exists: boolean, value: *}}
+ */
+function read_nested_path(root_object, path_segments) {
+	let current = root_object;
+
+	for(const segment of path_segments) {
+		if(is_not_object(current) || !has_own(current, segment)) {
+			return {
+				exists: false,
+				value: undefined
+			};
+		}
+
+		current = current[segment];
+	}
+
+	return {
+		exists: true,
+		value: current
+	};
+}
+
+/**
+ * Writes one normalized value into a nested object path.
+ *
+ * @param {object} root_object
+ * @param {string[]} path_segments
+ * @param {*} next_value
+ * @returns {void}
+ */
+function write_nested_path(root_object, path_segments, next_value) {
+	let current_object = root_object;
+	const depth = path_segments.length - 1;
+
+	for(let i = 0; i < depth; i++) {
+		const path_segment = path_segments[i];
+
+		if(is_not_object(current_object[path_segment])) {
+			current_object[path_segment] = {};
+		}
+
+		current_object = current_object[path_segment];
+	}
+
+	current_object[path_segments[depth]] = next_value;
+}
+
+// --- LOCAL HELPERS ---
+
+/**
+ * Writes one normalized value into a nested object path.
+ *
+ * @param {object} root_object
+ * @param {string[]} path_segments
+ * @param {*} next_value
+ * @returns {void}
+ */
+function assign_nested_value(root_object, path_segments, next_value) {
+	let current_object = root_object;
+	const depth = path_segments.length - 1;
+	const leaf_segment = path_segments[depth];
+
+	for(let i = 0; i < depth; i++) {
+		const path_segment = path_segments[i];
+		if(!is_plain_object(current_object[path_segment])) {
+			current_object[path_segment] = {};
+		}
+
+		current_object = current_object[path_segment];
+	}
+
+	if(is_plain_object(next_value) && is_plain_object(current_object[leaf_segment])) {
+		current_object[leaf_segment] = merge_plain_objects(current_object[leaf_segment], next_value);
+	} else {
+		current_object[leaf_segment] = next_value;
+	}
+}
+
+/**
+ * Deep-merges plain objects while letting later values win on scalar collisions.
+ *
+ * @param {object} base_object
+ * @param {object} patch_object
+ * @returns {object}
+ */
+function merge_plain_objects(base_object, patch_object) {
+	const merged_object = {...base_object};
+
+	for(const [key, value] of Object.entries(patch_object)) {
+		if(is_plain_object(value) && is_plain_object(merged_object[key])) {
+			merged_object[key] = merge_plain_objects(merged_object[key], value);
+		} else {
+			merged_object[key] = value;
+		}
+	}
+
+	return merged_object;
+}
+
+export {
+	split_dot_path,
+	read_nested_path,
+	write_nested_path,
+	build_path_literal,
+	build_nested_object,
+	expand_dot_paths
+};