Return this on Tag add/delete methods

[Etiquette] / model.js

diff --git a/model.js b/model.js
index 9f7962dce8df217f77239f1ecbb730159bc34f7c..6963a16778601567b5d56bef31763af503eeeba1 100644 (file)
--- a/model.js
+++ b/model.js
@@ -385,7 +385,10 @@ class Tag {
     });
   }
 
     });
   }
 

-  /** Adds the provided label(s) to this `Tag` as alternate labels. */
+  /**
+   * Adds the provided label(s) to this `Tag` as alternate labels, then
+   * returns this `Tag`.
+   */

   addAltLabel(...labels) {
     const altLabels = this.#data.altLabel;
     let objectLabels = null; // initialized on first use
   addAltLabel(...labels) {
     const altLabels = this.#data.altLabel;
     let objectLabels = null; // initialized on first use


@@ -428,11 +431,12 @@ class Tag {
         altLabels.add(literal);
       }
     }
         altLabels.add(literal);
       }
     }

+    return this;

   }
 
   /**
    * Adds the provided tags to the list of tags that this `Tag` is
   }
 
   /**
    * Adds the provided tags to the list of tags that this `Tag` is

-   * narrower than.
+   * narrower than, then returns this `Tag`.

    *
    * Arguments may be string identifiers or objects with an
    * `.identifier` property.
    *
    * Arguments may be string identifiers or objects with an
    * `.identifier` property.


@@ -474,9 +478,13 @@ class Tag {
         }
       }
     }
         }
       }
     }

+    return this;

   }
 
   }
 

-  /** Adds the provided label(s) to this `Tag` as hidden labels. */
+  /**
+   * Adds the provided label(s) to this `Tag` as hidden labels, then
+   * returns this `Tag`.
+   */

   addHiddenLabel(...labels) {
     const hiddenLabels = this.#data.hiddenLabel;
     let objectLabels = null; // initialized on first use
   addHiddenLabel(...labels) {
     const hiddenLabels = this.#data.hiddenLabel;
     let objectLabels = null; // initialized on first use


@@ -519,11 +527,12 @@ class Tag {
         hiddenLabels.add(literal);
       }
     }
         hiddenLabels.add(literal);
       }
     }

+    return this;

   }
 
   /**
    * Adds the provided tags to the list of tags that this `Tag` is in
   }
 
   /**
    * Adds the provided tags to the list of tags that this `Tag` is in

-   * canon with.
+   * canon with, then returns this `Tag`.

    *
    * Arguments may be string identifiers or objects with an
    * `.identifier` property.
    *
    * Arguments may be string identifiers or objects with an
    * `.identifier` property.


@@ -584,11 +593,12 @@ class Tag {
         }
       }
     }
         }
       }
     }

+    return this;

   }
 
   /**
    * Adds the provided tags to the list of tags that this `Tag`
   }
 
   /**
    * Adds the provided tags to the list of tags that this `Tag`

-   * involves.
+   * involves, then returns this `Tag`.

    *
    * Arguments may be string identifiers or objects with an
    * `.identifier` property.
    *
    * Arguments may be string identifiers or objects with an
    * `.identifier` property.


@@ -650,6 +660,7 @@ class Tag {
         }
       }
     }
         }
       }
     }

+    return this;

   }
 
   /** Yields the alternative labels of this `Tag`. */
   }
 
   /** Yields the alternative labels of this `Tag`. */


@@ -726,7 +737,7 @@ class Tag {
 
   /**
    * Removes the provided string label(s) from this `Tag` as alternate
 
   /**
    * Removes the provided string label(s) from this `Tag` as alternate

-   * labels.
+   * labels, then returns this `Tag`.

    */
   deleteAltLabel(...labels) {
     const altLabels = this.#data.altLabel;
    */
   deleteAltLabel(...labels) {
     const altLabels = this.#data.altLabel;


@@ -761,11 +772,12 @@ class Tag {
         altLabels.delete(literal);
       }
     }
         altLabels.delete(literal);
       }
     }

+    return this;

   }
 
   /**
    * Removes the provided tags from the list of tags that this `Tag` is
   }
 
   /**
    * Removes the provided tags from the list of tags that this `Tag` is

-   * narrower than.
+   * narrower than, then returns this `Tag`.

    *
    * Arguments may be string identifiers or objects with an
    * `.identifier` property.
    *
    * Arguments may be string identifiers or objects with an
    * `.identifier` property.


@@ -776,11 +788,12 @@ class Tag {
       // Iterate over the provided tags and delete them.
       broader.delete(toIdentifier($));
     }
       // Iterate over the provided tags and delete them.
       broader.delete(toIdentifier($));
     }

+    return this;

   }
 
   /**
    * Removes the provided string label(s) from this `Tag` as hidden
   }
 
   /**
    * Removes the provided string label(s) from this `Tag` as hidden

-   * labels.
+   * labels, then returns this `Tag`.

    */
   deleteHiddenLabel(...labels) {
     const hiddenLabels = this.#data.hiddenLabel;
    */
   deleteHiddenLabel(...labels) {
     const hiddenLabels = this.#data.hiddenLabel;


@@ -815,11 +828,12 @@ class Tag {
         hiddenLabels.delete(literal);
       }
     }
         hiddenLabels.delete(literal);
       }
     }

+    return this;

   }
 
   /**
    * Removes the provided tags from the list of tags that this `Tag` is
   }
 
   /**
    * Removes the provided tags from the list of tags that this `Tag` is

-   * in canon with.
+   * in canon with, then returns this `Tag`.

    *
    * Arguments may be string identifiers or objects with an
    * `.identifier` property.
    *
    * Arguments may be string identifiers or objects with an
    * `.identifier` property.


@@ -830,11 +844,12 @@ class Tag {
       // Iterate over the provided tags and delete them.
       inCanon.delete(toIdentifier($));
     }
       // Iterate over the provided tags and delete them.
       inCanon.delete(toIdentifier($));
     }

+    return this;

   }
 
   /**
    * Removes the provided tags from the list of tags that this `Tag`
   }
 
   /**
    * Removes the provided tags from the list of tags that this `Tag`

-   * involves.
+   * involves, then returns this `Tag`.

    *
    * Arguments may be string identifiers or objects with an
    * `.identifier` property.
    *
    * Arguments may be string identifiers or objects with an
    * `.identifier` property.


@@ -845,6 +860,7 @@ class Tag {
       // Iterate over the provided tags and delete them.
       involves.delete(toIdentifier($));
     }
       // Iterate over the provided tags and delete them.
       involves.delete(toIdentifier($));
     }

+    return this;

   }
 
   /** Yields `Tag`s that are in canon of this `Tag`. */
   }
 
   /** Yields `Tag`s that are in canon of this `Tag`. */


@@ -1036,6 +1052,9 @@ class Tag {
    * serialization of a Tag Activity representing any changes, or
    * `null` if no changes were made.
    *
    * serialization of a Tag Activity representing any changes, or
    * `null` if no changes were made.
    *

+   * If the second argument is `true`, the `Tag` will be persisted but
+   * no serialization will be made. This is somewhat more efficient.
+   *

    * ※ Persistence can imply side‐effects on other objects, which are
    * not noted explicitly in the activity. For example, marking a tag
    * as broader than another causes the other tag to reciprocally be
    * ※ Persistence can imply side‐effects on other objects, which are
    * not noted explicitly in the activity. For example, marking a tag
    * as broader than another causes the other tag to reciprocally be


@@ -1044,17 +1063,19 @@ class Tag {
    * ※ The inverse terms `hasInCanon`, `isIncludedIn`, and `narrower`
    * will never appear in the predicates of generated activities.
    */
    * ※ The inverse terms `hasInCanon`, `isIncludedIn`, and `narrower`
    * will never appear in the predicates of generated activities.
    */

-  persist() {
+  persist(silent = false) {

     const system = this.#system;
     const storage = this.#storage;
     const persistedData = this.#persistedData;
     const data = this.#data;
     const diffs = {};
     for (const [key, value] of Object.entries(data)) {
     const system = this.#system;
     const storage = this.#storage;
     const persistedData = this.#persistedData;
     const data = this.#data;
     const diffs = {};
     for (const [key, value] of Object.entries(data)) {

-      // Iterate over each entry of the tag data and create a diff with
-      // the last persisted information.
-      if (SKIP_IN_DIFF.has(key)) {
+      // Iterate over each entry of the tag data and create a diff
+      // with the last persisted information.
+      if (SKIP_IN_DIFF.has(key) || silent && LITERAL_TERMS.has(key)) {

         // The current property is one which is skipped in diffs.
         // The current property is one which is skipped in diffs.

+        //
+        // In a silent persist, this includes any literal terms.

         /* do nothing */
       } else {
         // The current property should be diffed.
         /* do nothing */
       } else {
         // The current property should be diffed.


@@ -1130,7 +1151,7 @@ class Tag {
       this.#identifier = storage.add(this);
     }
     const persistedIdentifier = this.#identifier;
       this.#identifier = storage.add(this);
     }
     const persistedIdentifier = this.#identifier;

-    this.#persistedData = tagData(data); // need to clone here
+    this.#persistedData = tagData(data); // cloning here is necessary

     for (
       const [term, inverse] of [
         ["broader", "narrower"],
     for (
       const [term, inverse] of [
         ["broader", "narrower"],


@@ -1166,131 +1187,138 @@ class Tag {
         }
       }
     }
         }
       }
     }

-    const activity = {
-      "@context": taggingDiscoveryContext,
-      "@type": [
-        "TagActivity",
-        identifier == null ? "Create" : "Update",
-      ],
-      context: `${system.iri}`,
-      object: `${this.iri}`,
-      endTime: new Date().toISOString(),
-      ...(() => {
-        const statements = {
-          unstates: [],
-          states: [],
-        };
-        const { unstates, states } = statements;
-        if (identifier == null) {
-          // This is a Create activity.
-          states.push({ predicate: "a", object: `${this.kind}` });
-        } else {
-          // This is an Update activity.
-          /* do nothing */
-        }
-        for (
-          const [term, {
-            old: oldValues,
-            new: newValues,
-          }] of Object.entries(diffs)
-        ) {
-          // Iterate over the diffs of each term and state/unstate
-          // things as needed.
-          for (const oldValue of oldValues) {
-            // Iterate over removals and unstate them.
-            if (LITERAL_TERMS.has(term)) {
-              // This is a literal term; push the change wrapped in an
-              // object.
-              unstates.push({
-                predicate: term,
-                object: Object(oldValue) === oldValue
-                  ? { ...langString(oldValue) }
-                  : { "@value": `${oldValue}` },
-              });
-            } else {
-              // This is a named term; attempt to get its I·R·I and
-              // push it.
-              try {
-                // Attempt to resolve the value and push the change.
-                const tag = storage.get(oldValue);
-                if (!this.#isTagInStorage(tag)) {
-                  // The value did not resolve to a tag in storage.
+    if (silent) {
+      // This is a silent persist.
+      return undefined;
+    } else {
+      // This is not a silent persist; an activity needs to be
+      // generated if a change was made.
+      const activity = {
+        "@context": taggingDiscoveryContext,
+        "@type": [
+          "TagActivity",
+          identifier == null ? "Create" : "Update",
+        ],
+        context: `${system.iri}`,
+        object: `${this.iri}`,
+        endTime: new Date().toISOString(),
+        ...(() => {
+          const statements = {
+            unstates: [],
+            states: [],
+          };
+          const { unstates, states } = statements;
+          if (identifier == null) {
+            // This is a Create activity.
+            states.push({ predicate: "a", object: `${this.kind}` });
+          } else {
+            // This is an Update activity.
+            /* do nothing */
+          }
+          for (
+            const [term, {
+              old: oldValues,
+              new: newValues,
+            }] of Object.entries(diffs)
+          ) {
+            // Iterate over the diffs of each term and state/unstate
+            // things as needed.
+            for (const oldValue of oldValues) {
+              // Iterate over removals and unstate them.
+              if (LITERAL_TERMS.has(term)) {
+                // This is a literal term; push the change wrapped in an
+                // object.
+                unstates.push({
+                  predicate: term,
+                  object: Object(oldValue) === oldValue
+                    ? { ...langString(oldValue) }
+                    : { "@value": `${oldValue}` },
+                });
+              } else {
+                // This is a named term; attempt to get its I·R·I and
+                // push it.
+                try {
+                  // Attempt to resolve the value and push the change.
+                  const tag = storage.get(oldValue);
+                  if (!this.#isTagInStorage(tag)) {
+                    // The value did not resolve to a tag in storage.
+                    /* do nothing */
+                  } else {
+                    // The value resolved; push its I·R·I.
+                    unstates.push({
+                      predicate: term,
+                      object: tag.iri,
+                    });
+                  }
+                } catch {
+                  // Value resolution failed for some reason; perhaps the
+                  // tag was deleted.

                   /* do nothing */
                   /* do nothing */

-                } else {
-                  // The value resolved; push its I·R·I.
-                  unstates.push({
-                    predicate: term,
-                    object: tag.iri,
-                  });

                 }
                 }

-              } catch {
-                // Value resolution failed for some reason; perhaps the
-                // tag was deleted.
-                /* do nothing */

               }
             }
               }
             }

-          }
-          for (const newValue of newValues) {
-            // Iterate over additions and state them.
-            if (LITERAL_TERMS.has(term)) {
-              // This is a literal term; push the change wrapped in an
-              // object.
-              states.push({
-                predicate: term,
-                object: Object(newValue) === newValue
-                  ? { ...langString(newValue) }
-                  : { "@value": `${newValue}` },
-              });
-            } else {
-              // This is a named term; attempt to get its I·R·I and
-              // push it.
-              try {
-                // Attempt to resolve the value and push the change.
-                const tag = storage.get(newValue);
-                if (!this.#isTagInStorage(tag)) {
-                  // The value did not resolve to a tag in storage.
+            for (const newValue of newValues) {
+              // Iterate over additions and state them.
+              if (LITERAL_TERMS.has(term)) {
+                // This is a literal term; push the change wrapped in an
+                // object.
+                states.push({
+                  predicate: term,
+                  object: Object(newValue) === newValue
+                    ? { ...langString(newValue) }
+                    : { "@value": `${newValue}` },
+                });
+              } else {
+                // This is a named term; attempt to get its I·R·I and
+                // push it.
+                try {
+                  // Attempt to resolve the value and push the change.
+                  const tag = storage.get(newValue);
+                  if (!this.#isTagInStorage(tag)) {
+                    // The value did not resolve to a tag in storage.
+                    /* do nothing */
+                  } else {
+                    // The value resolved; push its I·R·I.
+                    states.push({
+                      predicate: term,
+                      object: tag.iri,
+                    });
+                  }
+                } catch {
+                  // Value resolution failed for some reason; perhaps the
+                  // tag was deleted.

                   /* do nothing */
                   /* do nothing */

-                } else {
-                  // The value resolved; push its I·R·I.
-                  states.push({
-                    predicate: term,
-                    object: tag.iri,
-                  });

                 }
                 }

-              } catch {
-                // Value resolution failed for some reason; perhaps the
-                // tag was deleted.
-                /* do nothing */

               }
             }
           }
               }
             }
           }

-        }
-        if (unstates.length == 0) {
-          // Nothing was unstated.
-          delete statements.unstates;
-        } else {
-          // Things were stated.
-          /* do nothing */
-        }
-        if (states.length == 0) {
-          // Nothing was stated.
-          delete statements.states;
-        } else {
-          // Things were stated.
-          /* do nothing */
-        }
-        return statements;
-      })(),
-    };
-    if (
-      !Object.hasOwn(activity, "states") &&
-      !Object.hasOwn(activity, "unstates")
-    ) {
-      // No meaningful changes were actually persisted.
-      return null;
-    } else {
-      // There were meaningful changes persisted regarding this `Tag`.
-      return activity;
+          if (unstates.length == 0) {
+            // Nothing was unstated.
+            delete statements.unstates;
+          } else {
+            // Things were stated.
+            /* do nothing */
+          }
+          if (states.length == 0) {
+            // Nothing was stated.
+            delete statements.states;
+          } else {
+            // Things were stated.
+            /* do nothing */
+          }
+          return statements;
+        })(),
+      };
+      if (
+        !Object.hasOwn(activity, "states") &&
+        !Object.hasOwn(activity, "unstates")
+      ) {
+        // No meaningful changes were actually persisted.
+        return null;
+      } else {
+        // There were meaningful changes persisted regarding this `Tag`.
+        return activity;
+      }

     }
   }
 
     }
   }