JS: kw, kwid and inter-event helpers

kw, kwid and inter-event helpers¶

A kw is the JSON payload that travels with every event. These helpers read it, write it, filter it and clone it.

Source code: src/helpers.js

Most helpers take gobj as their first parameter, and they use it only to name the gobj in a log message. kw_has_key(), kw_pop() and kw_match_simple() are the exceptions, and they take no gobj.

kw_flag_t¶

The flags of the typed readers. Combine them with the bit-or operator.

Read and write¶

kw_has_key(kw, key)¶

Tells if kw has the key as its own property. It takes a key, not a path, and it takes no gobj. Returns a boolean.

kw_find_path(gobj, kw, path, verbose)¶

Gives the value at a back-tick path. Returns undefined when the path does not exist. With verbose set to true the function writes a log error first.

kw_delete(gobj, kw, path)¶

Deletes the key at a back-tick path. Returns 0.

kw_pop(kw1, kw2)¶

Deletes from kw1 every key that kw2 names. kw2 can be a string, an object or an array, and an array goes down into each of its elements. It takes no gobj, and it returns nothing.

kw_set_dict_value(gobj, kw, path, value)¶

Writes a value at a back-tick path, and creates the intermediate objects that the path needs.

kw_set_subdict_value(gobj, kw, path, key, value)¶

Writes key inside the object at path, and creates that object when it does not exist.

Typed readers¶

Every reader takes the same five parameters, and each one gives the type of its name. A value of a different type gives the default value back.

kw_get_bool      (gobj, kw, path, default_value, flag)
kw_get_int       (gobj, kw, path, default_value, flag)
kw_get_real      (gobj, kw, path, default_value, flag)
kw_get_str       (gobj, kw, path, default_value, flag)
kw_get_dict      (gobj, kw, path, default_value, flag)
kw_get_list      (gobj, kw, path, default_value, flag)
kw_get_dict_value(gobj, kw, path, default_value, flag)
kw_get_pointer   (gobj, kw, path, default_value, flag)

kw_get_bool()¶

Reads a boolean.

kw_get_int()¶

Reads an integer.

kw_get_real()¶

Reads a real number.

kw_get_str()¶

Reads a string. The function puts the result through String(), so the return value is always a string.

kw_get_dict()¶

Reads an object.

kw_get_dict_value()¶

Reads a value of any type from an object.

kw_get_list()¶

Reads an array.

kw_get_pointer()¶

Reads a value that is not JSON, such as a gobj or a DOM node.

Match and filter¶

kw_match_simple(kw, jn_filter)¶

Tells if kw matches a filter. It compares strings and numbers only. An empty filter matches everything. It takes no gobj.

kw_select(gobj, kw, jn_filter, match_fn)¶

Gives a new list with a deep copy of each row that matches the filter. Use it when the caller changes the rows. With match_fn empty the function uses kw_match_simple().

kw_collect(gobj, kw, jn_filter, match_fn)¶

Gives a new list with a reference to each row that matches the filter. It is kw_select() without the copy, so a change to a row changes the source.

kw_find_json_in_list(gobj, kw_list, item, flag)¶

Gives the index of a simple JSON item in a list. Returns -1 when the list does not hold it.

kw_clone_by_keys(gobj, kw, keys, verbose)¶

Gives a new object with the keys that keys names. keys can be a string, an array of strings or an object. It is not a deep copy. With empty keys the function gives kw back.

kw_clone_by_not_keys(gobj, kw, keys, verbose)¶

Gives a new object without the keys that keys names. It is the opposite of kw_clone_by_keys().

Local storage¶

These three helpers put a value in the local storage of the browser. The persistent attributes use them. See Persistence.

kw_get_local_storage_value(key, default_value, create)¶

Reads an attribute from the local storage. With create set to true the function writes the default value when the key does not exist.

kw_set_local_storage_value(key, value)¶

Writes an attribute to the local storage. Returns 0 on success, and -1 when the value did not reach the store. An older version returned nothing and only wrote to the console, so no caller saw the failure.

kw_remove_local_storage_value(key)¶

Deletes an attribute from the local storage.

kwid record helpers¶

A kwid is a collection of records. It can be a list of strings, a list of objects, or an object of objects with the identifier as its key. These helpers read the three forms in the same way.

kwid_match_id(ids, id)¶

Tells if id is in the collection ids. An empty ids matches every identifier, because no filter lets everything through.

kwid_collect(gobj, kw, ids, jn_filter, match_fn)¶

Gives a new list with the records that match both ids and the filter. With match_fn empty the function uses kw_match_simple().

kwid_find_one_record(gobj, kw, ids, jn_filter, match_fn)¶

Gives the first record that matches. It takes the parameters of kwid_collect().

kwid_new_dict(gobj, kw, path)¶

Builds an object of objects from a list of records, with the field id of each record as the key. With a path that is not empty the function reads the list at that path first. The function gives an unchanged result for a kw that is an object already.

kwid_get_ids(gobj, ids)¶

Gives the list of the identifiers of a collection. It accepts a string, a list of strings, a list of records or an object of records.

Inter-event metadata¶

The inter-event protocol carries its metadata inside the kw, in the key __md_iev__. Read and write it with these helpers and never by hand: the key name is an internal detail, and a message that goes to a remote yuno and comes back keeps only what these helpers wrote.

msg_iev_write_key(kw, key, value)¶

Writes a key in the metadata of the message, and creates the metadata object when it does not exist. It takes no gobj.

msg_iev_read_key(kw, key)¶

Reads a key of the metadata. Returns undefined when the message has no metadata. It takes no gobj.

msg_iev_push_stack(gobj, kw, stack, jn_data)¶

Puts jn_data on a stack with a name inside the metadata. The stack carries the data of one hop when a message goes through more than one yuno.

msg_iev_get_stack(gobj, kw, stack, verbose)¶

Reads the top of a stack with a name. It does not take the element out.

msg_iev_set_msg_type(gobj, kw, msg_type)¶

Writes the type of the message. An empty string deletes the key. Returns 0.

msg_iev_get_msg_type(gobj, kw)¶

Reads the type of the message. Returns an empty string when the message has none.

Metadata and private keys¶

is_metadata_key(key)¶

Tells if a key is a metadata key. A metadata key begins with two underscores.

is_private_key(key)¶

Tells if a key is a private key. A private key begins with one underscore.