@yuneta/gobj-js 7.16.6 → 7.21.0

package/dist/gobj-js.cjs.js

@@ -4021,10 +4021,18 @@ Being `kw` a:
 - list of strings [s,...]
 - list of dicts [{},...]
 - dict of dicts {id:{},...}
-return a **NEW** list of incref (clone) kw filtering the rows by `jn_filter` (where),
-and matching the ids.
-If match_fn is 0 then kw_match_simple is used.
-NOTE Using JSON_INCREF/JSON_DECREF HACK
+return a NEW list holding the rows that match `ids` and the
+`jn_filter` (where). If match_fn is 0 then kw_match_simple is used.
+
+WARNING the LIST is new; its elements are THE SAME objects, not
+copies. The C twin increfs each one and says "clone", which this
+comment repeated for years: javascript has no refcount, so a write
+through a collected row writes into `kw`. Copy what you mean to
+modify.
+
+Returns null -- not an empty list -- for a `kw` that is neither a
+list nor a dict, so a caller that reads `.length` off the answer
+must check it first (kwid_find_one_record does).
 *************************************************************/
 function kwid_collect(gobj, kw, ids, jn_filter, match_fn) {
 	if (gobj && !is_gobj(gobj)) log_error(`GObj bad instanceof`);
@@ -4053,12 +4061,17 @@ function kwid_collect(gobj, kw, ids, jn_filter, match_fn) {
 }
 /*************************************************************
 Utility for databases.
-Return a new dict from a "dict of records" or "list of records"
-WARNING the "id" of a dict's record is hardcorded to their key.
+Return a dict from a "dict of records" or "list of records".
+WARNING the "id" of a dict's record is hardcoded to its key.
 Convention:
-- all arrays are list of records (dicts) with "id" field as primary key
+- all arrays are lists of records (dicts) with "id" as primary key
 - delimiter is '`' and '.'
 If path is empty then use kw
+
+WARNING "new" is the C twin's word, where it means a new REFERENCE:
+handed a dict, both return THAT dict and not a copy of it. Only the
+list case builds something new, and even then the records inside it
+are the same objects.
 *************************************************************/
 function kwid_new_dict(gobj, kw, path) {
 	if (gobj && !is_gobj(gobj)) log_error(`GObj bad instanceof`);
@@ -4067,20 +4080,59 @@ function kwid_new_dict(gobj, kw, path) {
 	if (is_object(kw)) new_dict = kw;
 	else if (is_array(kw)) for (let i = 0; i < kw.length; i++) {
 		let kv = kw[i];
-		let id = kw_get_str(gobj, kv, "id", "", 0);
+		let id = kw_get_str(gobj, kv, "id", "", kw_flag_t.KW_REQUIRED);
 		if (!empty_string(id)) new_dict[id] = kv;
 	}
 	else log_error(`${gobj_short_name(gobj)} kwid_new_dict: data type unknown`);
 	return new_dict;
 }
 /*************************************************************
+Utility for databases.
+Return a list from a "dict of records" or "list of records".
+The NORMALIZING function of this family: whatever shape the data
+arrives in, what comes back is the shape a table indexed and
+sorted by `id` wants.
+Convention:
+- all arrays are lists of records (dicts) with "id" as primary key
+- delimiter is '`' and '.'
+If path is empty then use kw
+
+WARNING handed a DICT it writes each record's key into the record
+as its `id`, OVERWRITING one that differs -- in the source records,
+which it does not copy. That is the C twin's behaviour
+(`json_object_set_new(v, "id", ...)` in kwid.c) and it is the point:
+a dict keyed by id whose records disagree with their own key is
+exactly what this is for. Handed a LIST it returns that same list,
+untouched, as C returns a new reference to it.
+*************************************************************/
+function kwid_new_list(gobj, kw, path) {
+	if (gobj && !is_gobj(gobj)) log_error(`GObj bad instanceof`);
+	if (!empty_string(path)) kw = kw_find_path(gobj, kw, path);
+	if (is_array(kw)) return kw;
+	if (is_object(kw)) {
+		let new_list = [];
+		for (let id of Object.keys(kw)) {
+			let record = kw[id];
+			if (!is_object(record)) {
+				log_error(`${gobj_short_name(gobj)} kwid_new_list: not a record: '${id}'`);
+				continue;
+			}
+			record["id"] = id;
+			new_list.push(record);
+		}
+		return new_list;
+	}
+	log_error(`${gobj_short_name(gobj)} kwid_new_list: wrong type for list`);
+	return [];
+}
+/*************************************************************
 *  Utility for databases. See kwid_collect parameters
 *************************************************************/
 function kwid_find_one_record(gobj, kw, ids, jn_filter, match_fn) {
 	if (gobj && !is_gobj(gobj)) log_error(`GObj bad instanceof`);
 	let list = kwid_collect(gobj, kw, ids, jn_filter, match_fn);
-	if (list.length > 0) return list[0];
-	else return null;
+	if (!list || list.length === 0) return null;
+	return list[0];
 }
 /*************************************************************
 Utility for databases.
@@ -7128,6 +7180,7 @@ exports.kwid_find_one_record = kwid_find_one_record;
 exports.kwid_get_ids = kwid_get_ids;
 exports.kwid_match_id = kwid_match_id;
 exports.kwid_new_dict = kwid_new_dict;
+exports.kwid_new_list = kwid_new_list;
 exports.list2options = list2options;
 exports.load_json_file = load_json_file;
 exports.log_debug = log_debug;