Return undefined not null when resolving fails

[Etiquette] / model.js

// 📧🏷️ Étiquette ∷ model.js
// ====================================================================
//
// Copyright © 2023 Lady [@ Lady’s Computer].
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at <https://mozilla.org/MPL/2.0/>.

import { identity } from "./deps.js";
import { Storage } from "./memory.js";
import { taggingDiscoveryContext } from "./names.js";
import schema from "./schema.js";

/**
 * A tag.
 *
 * `Tag`s are not assigned identifiers and do not have side·effects on
 * other tags in the `TagSystem` until they are persisted with
 * `::persist`, at which point changes to their relationships are
 * applied.
 *
 * `Tag`s are also not kept up‐to‐date, but persisting an outdated
 * `Tag` will *not* undo subsequent changes.
 *
 * ※ This class is not itself directly exposed, although bound
 * versions of it are via `TagSystem::Tag`.
 */
class Tag {
  /** The `TagSystem` this `Tag` belongs to. */
  #system;

  /** The `Storage` managed by this `Tag`’s `TagSystem`. */
  #storage;

  /** The schema in use for this `Tag`. */
  #schema;

  /**
   * The 30‐bit W·R·M·G base32 identifier with leading checksum which
   * has been assigned to this `Tag`.
   *
   * Will be `null` if this `Tag` has not been persisted. Otherwise,
   * the format is `cxx-xxxx` (`c` = checksum; `x` = digit).
   */
  #identifier = null;

  /** The kind of this `Tag`. */
  #kind = "Tag";

  /**
   * The data which was attached to this `Tag` the last time it was
   * persisted or retrieved from storage.
   *
   * Diffing with this will reveal changes.
   */
  #persistedData = null;

  /** The current (modified) data associated with this `Tag`. */
  #data = tagData();

  /**
   * Adds the provided label(s) to this `Tag` as the provided
   * predicate, then returns this `Tag`.
   */
  #addLabel(predicate, ...labels) {
    const values = this.#data[predicate];
    for (const $ of labels) {
      // Iterate over each provided label and attempt to add it.
      const literal = langString($);
      values.add(literal);
    }
    return this;
  }

  /**
   * Adds the provided tags to the list of tags that this `Tag` is
   * related to by the provided predicate, then returns this `Tag`.
   *
   * Arguments may be string identifiers or objects with an
   * `.identifier` property.
   */
  #addTag(predicate, ...tags) {
    const storage = this.#storage;
    const values = this.#data[predicate];
    for (const $ of tags) {
      // Iterate over each tag and attempt to state the predicate.
      const identifier = toIdentifier($);
      if (identifier == null) {
        // ☡ The current tag has no identifier.
        throw new TypeError(
          `Cannot state ${predicate} of Tag: Identifier must not be nullish.`,
        );
      } else if (values.has(identifier)) {
        // Short‐circuit: The identifier has already been stated with
        // this predicate.
        /* do nothing */
      } else {
        // The current tag has an identifier, but it hasn’t been stated
        // with this predicate yet.
        const tag = storage.get(identifier);
        if (tag == null) {
          // ☡ The current tag has not been persisted to this `Tag`’s
          // storage.
          throw new RangeError(
            `Cannot state ${predicate} of Tag: Identifier is not persisted: ${identifier}.`,
          );
        } else if (!this.#isTagInStorage(tag)) {
          // ☡ The current tag is not a tag in the correct tag system.
          throw new TypeError(
            `Cannot state ${predicate} of Tag: Tags must be from the same Tag System, but got: ${identifier}.`,
          );
        } else if (
          !isObjectPredicateOK(
            this.#schema,
            this.#kind,
            predicate,
            tag.#kind,
          )
        ) {
          // ☡ This tag and the current tag form an invalid pair for
          // this predicate.
          throw new TypeError(
            `Cannot state ${predicate} of Tag: Not valid for domain and range: ${this.#kind}, ${tag.#kind}.`,
          );
        } else {
          // The current tag is a tag in the correct tag system; add
          // its identifier.
          values.add(identifier);
        }
      }
    }
    return this;
  }

  /**
   * Removes the provided string label(s) from this `Tag` as the
   * provided predicate, then returns this `Tag`.
   */
  #deleteLabel(predicate, ...labels) {
    const values = this.#data[predicate];
    for (const $ of labels) {
      // Iterate over each provided label and attempt to remove it.
      const literal = langString($);
      values.delete(literal);
    }
    return this;
  }

  /**
   * Removes the provided tags from the list of tags that this `Tag` is
   * related to by the provided predicate, then returns this `Tag`.
   *
   * Arguments may be string identifiers or objects with an
   * `.identifier` property.
   */
  #deleteTag(predicate, ...tags) {
    const values = this.#data[predicate];
    for (const $ of tags) {
      // Iterate over the provided tags and delete them.
      values.delete(toIdentifier($));
    }
    return this;
  }

  /**
   * Returns whether or not the provided value is a tag which shares a
   * storage with this tag.
   *
   * Sharing a storage also implies sharing a `TagSystem`.
   */
  #isTagInStorage($) {
    try {
      // Try to compare the provided value’s internal store with
      // the provided storage.
      return $.#storage == this.#storage;
    } catch {
      // The provided value was not a `Tag`.
      return false;
    }
  }

  /**
   * Yields the labels of this `Tag` according to the provided
   * predicate.
   */
  *#yieldLabels(predicate) {
    yield* this.#data[predicate];
  }

  /**
   * Yields the tags that this `Tag` is related to by the provided
   * predicate.
   */
  *#yieldTags(predicate) {
    const storage = this.#storage;
    for (const identifier of this.#data[predicate]) {
      // Iterate over the tags in this predicate and yield them if
      // possible.
      const tag = storage.get(identifier);
      if (
        !this.#isTagInStorage(tag) || !isObjectPredicateOK(
          this.#schema,
          this.#kind,
          predicate,
          tag.#kind,
        )
      ) {
        // The tag no longer appears in storage or is not compatible;
        // perhaps it was deleted.
        /* do nothing */
      } else {
        // The tag exists and is constructable from storage.
        yield tag;
      }
    }
  }

  /**
   * Yields the tags that this `Tag` is related to by the provided
   * predicate, figured transitively.
   */
  *#yieldTransitiveTags(transitivePredicate, basePredicate) {
    const storage = this.#storage;
    const encountered = new Set();
    let pending = new Set(this.#data[basePredicate]);
    while (pending.size > 0) {
      // Loop until all tags of the predicate have been encountered.
      const processing = pending;
      pending = new Set();
      for (const identifier of processing) {
        // Iterate over the tags and yield them if possible.
        if (!encountered.has(identifier)) {
          // The tag has not been encountered before.
          encountered.add(identifier);
          const tag = storage.get(identifier);
          if (
            !this.#isTagInStorage(tag) || !isObjectPredicateOK(
              this.#schema,
              this.#kind,
              transitivePredicate,
              tag.#kind,
            )
          ) {
            // The tag no longer appears in storage or is not
            // compatible; perhaps it was deleted.
            /* do nothing */
          } else {
            // The tag exists and is constructable from storage.
            yield tag;
            for (const transitive of tag.#data[basePredicate]) {
              // Iterate over the nested tags of the current tag and
              // add them to pending as needed.
              if (!encountered.has(transitive)) {
                // The nested tag has not been encountered yet.
                pending.add(transitive);
              } else {
                // The nested tag has already been encountered.
                /* do nothing */
              }
            }
          }
        } else {
          // The tag has already been encountered.
          /* do nothing */
        }
      }
    }
  }

  /**
   * Constructs a new `Tag` of the provided kind and with the provided
   * preferred label.
   *
   * ※ The first two arguments of this constructor are bound when
   * generating the value of `TagSystem::Tag`. It isn’t possible to
   * access this constructor in its unbound form from outside this
   * module.
   *
   * ☡ This constructor throws if the provided kind is not supported.
   */
  constructor(system, storage, schema, kind = "Tag", prefLabel = "") {
    this.#system = system;
    this.#storage = storage;
    this.#schema = schema;
    const kindString = `${kind}`;
    if (!(kindString in schema.classes)) {
      // The provided kind is not supported.
      throw new RangeError(
        `Cannot construct Tag: Unrecognized kind: ${kind}.`,
      );
    } else {
      // The provided kind is one of the recognized tag kinds.
      this.#kind = kindString;
      this.#data.prefLabel = prefLabel;
    }
  }

  /**
   * Returns a new `Tag` constructor for the provided system, storage,
   * schema, created with an appropriate prototype for the properties
   * so defined.
   *
   * ※ This function is not exposed.
   */
  static For(system, storage, schema) {
    const {
      objectProperties,
      transitiveProperties,
      dataProperties,
    } = schema;
    const constructor = function (...$s) {
      return Reflect.construct(
        Tag,
        [system, storage, schema, ...$s],
        new.target,
      );
    };
    Object.defineProperties(constructor, {
      name: { value: "TagSystem::Tag" },
      prototype: {
        configurable: false,
        enumerable: false,
        value: Object.create(
          Tag.prototype,
          Object.fromEntries(Array.from(
            function* () {
              for (const key in objectProperties) {
                // Iterate over each object property and yield any
                // necessary method definitions.
                const {
                  inverseOf,
                  subPropertyOf,
                } = objectProperties[key];
                if (key in transitiveProperties) {
                  // The current key indicates a transitive property.
                  //
                  // Transitive property methods are added by their
                  // nontransitive subproperties.
                  /* do nothing */
                } else {
                  // The current key does not indicate a transitive
                  // property.
                  yield [`${key}Tags`, function* () {
                    yield* this.#yieldTags(key);
                  }];
                  if (inverseOf == null) {
                    // The current key does not indicate an inverse
                    // property, so add and delete methods are also
                    // added.
                    const cased = key[0].toUpperCase() +
                      key.substring(1);
                    yield [`add${cased}Tag`, function (...tags) {
                      return this.#addTag(key, ...tags);
                    }];
                    yield [`delete${cased}Tag`, function (...tags) {
                      return this.#deleteTag(key, ...tags);
                    }];
                  } else {
                    // The current key indicates an inverse property,
                    // so no add and delete methods are necessary.
                    /* do nothing */
                  }
                  if (
                    subPropertyOf != null &&
                    subPropertyOf in transitiveProperties
                  ) {
                    // The current key indicates a subproperty of a
                    // transitive property; its method is also added.
                    yield [`${subPropertyOf}Tags`, function* () {
                      yield* this.#yieldTransitiveTags(
                        subPropertyOf,
                        key,
                      );
                    }];
                  } else {
                    // The current key does not indicate a subproperty
                    // of a transitive property.
                    /* do nothing */
                  }
                }
              }
              for (const key in dataProperties) {
                // Iterate over each data property and yield any
                // necessary method definitions.
                if (key != "prefLabel") {
                  // The current key is not `"prefLabel"`.
                  const cased = key[0].toUpperCase() +
                    key.substring(1);
                  yield [`${key}s`, function* () {
                    yield* this.#yieldLabels(key);
                  }];
                  yield [`add${cased}`, function (...labels) {
                    return this.#addLabel(key, ...labels);
                  }];
                  yield [`delete${cased}`, function (...labels) {
                    return this.#deleteLabel(key, ...labels);
                  }];
                } else {
                  // The current key is `"prefLabel"`. This is a
                  // special case which is not handled by the schema.
                  /* do nothing */
                }
              }
            }(),
            ([key, value]) => [key, {
              configurable: true,
              enumerable: false,
              value: Object.defineProperty(value, "name", {
                value: key,
              }),
              writable: true,
            }],
          )),
        ),
        writable: false,
      },
    });
    return new TagConstructor(constructor, system, storage, schema);
  }

  /**
   * Assigns the provided data and identifier to the provided tag.
   *
   * ☡ This function throws if the provided tag is not a `Tag`.
   *
   * ※ This function is not exposed.
   */
  static assignData(tag, data, identifier) {
    tag.#identifier = `${identifier}`;
    tag.#persistedData = tagData(data);
    tag.#data = tagData(data);
    return tag;
  }

  /**
   * Returns the `TagSystem` that the provided value belongs to.
   *
   * ※ This function can be used to check if the provided value has
   * private tag features.
   *
   * ※ This function is not exposed.
   */
  static getSystem($) {
    return !(#system in Object($)) ? null : $.#system;
  }

  static {
    // Overwrite the default `::constructor` method to instead give the
    // actual (bound) constructor which was used to generate a given
    // `Tag`.
    Object.defineProperties(this.prototype, {
      constructor: {
        configurable: true,
        enumerable: false,
        get() {
          // All `Tag`s are constructed via the `.Tag` constructor
          // available in their `TagSystem`; return it.
          return this.#system.Tag;
        },
        set: undefined,
      },
    });
  }

  /** Returns the authority (domain) name for this `Tag`. */
  get authorityName() {
    return this.#system.authorityName;
  }

  /** Returns the identifier of this `Tag`. */
  get identifier() {
    return this.#identifier;
  }

  /** Returns the I·R·I for this `Tag`. */
  get iri() {
    const { identifier, iriSpace } = this;
    return identifier == null ? null : `${iriSpace}${identifier}`;
  }

  /** Returns the I·R·I space for this `Tag`. */
  get iriSpace() {
    return this.#system.iriSpace;
  }

  /** Returns the kind of this `Tag`. */
  get kind() {
    return this.#kind;
  }

  /**
   * Persist this `Tag` to storage and return an ActivityStreams
   * 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
   * marked as narrower.
   *
   * ※ Inverse object properties will never appear in the predicates
   * of generated activities.
   */
  persist(silent = false) {
    const system = this.#system;
    const storage = this.#storage;
    const {
      objectProperties,
      transitiveProperties,
      dataProperties,
    } = this.#schema;
    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 (
        objectProperties[key]?.inverseOf != null ||
        silent && key in dataProperties
      ) {
        // 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.
        const persisted = persistedData?.[key] ?? null;
        if (persisted == null) {
          // There is no persisted data for the current property yet.
          diffs[key] = {
            old: new Set(),
            new: value instanceof Set
              ? new Set(value)
              : new Set([value]),
          };
        } else if (value instanceof Set) {
          // The current property is set‐valued.
          const oldValues = new Set(persisted);
          const newValues = new Set(value);
          for (const existing of persisted) {
            // Iterate over each persisted property and either remove
            // it from the list of new values or add it to the list of
            // removed ones.
            if (value.has(existing)) {
              // The value is in both the old and new version of the
              // data.
              oldValues.delete(existing);
              newValues.delete(existing);
            } else {
              // The value is not shared.
              /* do nothing */
            }
          }
          diffs[key] = { old: oldValues, new: newValues };
        } else if (
          `${value}` != `${persisted}` ||
          value.language != persisted.language
        ) {
          // The current property is (optionally language‐tagged)
          // string‐valued and the value changed.
          diffs[key] = {
            old: new Set([persisted]),
            new: new Set([value]),
          };
        } else {
          // The current property did not change.
          diffs[key] = { old: new Set(), new: new Set() };
        }
      }
    }
    const identifier = this.#identifier;
    if (identifier != null) {
      // This `Tag` has already been persisted; use its existing
      // identifier and persist.
      storage.set(identifier, this);
    } else {
      // This `Tag` has not been persisted yet; save the new
      // identifier after persisting.
      this.#identifier = storage.add(this);
    }
    const persistedIdentifier = this.#identifier;
    this.#persistedData = tagData(data); // cloning here is necessary
    for (const inverse in objectProperties) {
      // Iterate over each non‐transitive inverse property and update
      // it based on its inverse on the corresponding tags if possible.
      const term = objectProperties[inverse].inverseOf;
      if (term == null || term in transitiveProperties) {
        // The current property is not the inverse of an non‐transitive
        // property.
        /* do nothing */
      } else {
        // The current property is the inverse of a non‐transitive
        // property.
        for (const referencedIdentifier of diffs[term].old) {
          // Iterate over the removed tags and remove this `Tag` from
          // their inverse property.
          const referenced = storage.get(referencedIdentifier);
          try {
            // Try removing this `Tag`.
            referenced.#data[inverse].delete(persistedIdentifier);
            storage.set(referencedIdentifier, referenced);
          } catch {
            // Removal failed, possibly because the other tag was
            // deleted.
            /* do nothing */
          }
        }
        for (const referencedIdentifier of diffs[term].new) {
          const referenced = storage.get(referencedIdentifier);
          try {
            // Try adding this `Tag`.
            referenced.#data[inverse].add(persistedIdentifier);
            storage.set(referencedIdentifier, referenced);
          } catch {
            // Adding failed, possibly because the other tag was deleted.
            /* do nothing */
          }
        }
      }
    }
    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 (term in dataProperties) {
                // This is a literal term; push it.
                unstates.push({
                  predicate: term,
                  object: { ...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 */
                }
              }
            }
            for (const newValue of newValues) {
              // Iterate over additions and state them.
              if (term in dataProperties) {
                // This is a literal term; push it.
                states.push({
                  predicate: term,
                  object: { ...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 */
                }
              }
            }
          }
          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;
      }
    }
  }

  /** Returns the preferred label for this `Tag`. */
  get prefLabel() {
    return this.#data.prefLabel;
  }

  /** Sets the preferred label of this `Tag` to the provided label. */
  set prefLabel($) {
    this.#data.prefLabel = langString($);
  }

  /** Returns the Tag U·R·I for this `Tag`. */
  get tagURI() {
    const { identifier } = this;
    return identifier == null
      ? null
      : `tag:${this.taggingEntity}:${identifier}`;
  }

  /** Returns the tagging entity (domain and date) for this `Tag`. */
  get taggingEntity() {
    return this.#system.taggingEntity;
  }

  /** Returns the string form of the preferred label of this `Tag`. */
  toString() {
    return `${this.#data.prefLabel}`;
  }

  /**
   * Returns a new object whose enumerable own properties contain the
   * data from this object needed for storage.
   *
   * ※ This method is not really intended for public usage.
   */
  [Storage.toObject]() {
    const data = this.#data;
    return Object.assign(Object.create(null), {
      ...data,
      kind: this.#kind,
    });
  }
}

const {
  /**
   * A `Tag` constructor function.
   *
   * This class extends the identity function, meaning that the object
   * provided as the constructor is used verbatim (with new private
   * fields added).
   *
   * ※ The instance methods of this class are provided as static
   * methods on the superclass which all `Tag` constructors inherit
   * from.
   *
   * ※ This class is not exposed.
   */
  TagConstructor,

  /**
   * The exposed constructor function from which all `Tag` constructors
   * inherit.
   *
   * ☡ This constructor always throws.
   */
  TagSuper,
} = (() => {
  const tagConstructorBehaviours = Object.create(null);
  return {
    TagConstructor: class extends identity {
      /**
       * The `TagSystem` used for `Tag`s constructed by this
       * constructor.
       */
      #system;

      /** The `Storage` managed by this constructor’s `TagSystem`. */
      #storage;

      /** The schema in use for this constructor. */
      #schema;

      /**
       * Constructs a new `Tag` constructor by adding the appropriate
       * private fields to the provided constructor, setting its
       * prototype, and then returning it.
       *
       * ※ This constructor does not modify the `name` or `prototype`
       * properties of the provided constructor.
       *
       * ※ See `Tag.For`, where this constructor is used.
       */
      constructor(constructor, system, storage, schema) {
        super(constructor);
        Object.setPrototypeOf(this, TagSuper);
        this.#system = system;
        this.#storage = storage;
        this.#schema = schema;
      }

      static {
        // Define the superclass constructor which all `Tag`
        // constructors will inherit from.
        const superclass = tagConstructorBehaviours.TagSuper =
          function Tag() {
            throw new TypeError("Tags must belong to a System.");
          };
        const { prototype: methods } = this;
        delete methods.constructor;
        Object.defineProperty(superclass, "prototype", {
          configurable: false,
          enumerable: false,
          value: Tag.prototype,
          writable: false,
        });
        Object.defineProperties(
          superclass,
          Object.getOwnPropertyDescriptors(methods),
        );
      }

      /**
       * Yields the tags in the `TagSystem` associated with this
       * constructor.
       */
      *all() {
        const system = this.#system;
        const storage = this.#storage;
        for (const instance of storage.values()) {
          // Iterate over the entries and yield the ones which are
          // `Tag`s in this `TagSystem`.
          if (Tag.getSystem(instance) == system) {
            // The current instance is a `Tag` in this `TagSystem`.
            yield instance;
          } else {
            // The current instance is not a `Tag` in this
            // `TagSystem`.
            /* do nothing */
          }
        }
      }

      /**
       * Returns a new `Tag` resolved from the provided I·R·I.
       *
       * ☡ This function throws if the I·R·I is not in the `.iriSpace`
       * of the `TagSystem` associated with this constructor.
       *
       * ※ If the I·R·I is not recognized, this function returns
       * `undefined`.
       */
      fromIRI(iri) {
        const system = this.#system;
        const storage = this.#storage;
        const name = `${iri}`;
        const prefix = `${system.iriSpace}`;
        if (!name.startsWith(prefix)) {
          // The I·R·I does not begin with the expected prefix.
          throw new RangeError(
            `I·R·I did not begin with the expected prefix: ${iri}`,
          );
        } else {
          // The I·R·I begins with the expected prefix.
          const identifier = name.substring(prefix.length);
          try {
            // Attempt to resolve the identifier.
            const instance = storage.get(identifier);
            return Tag.getSystem(instance) == system
              ? instance
              : undefined;
          } catch {
            // Do not throw for bad identifiers.
            return undefined;
          }
        }
      }

      /**
       * Returns a new `Tag` resolved from the provided identifier.
       *
       * ☡ This function throws if the identifier is invalid.
       *
       * ※ If the identifier is valid but not recognized, this
       * function returns `undefined`.
       */
      fromIdentifier(identifier) {
        const system = this.#system;
        const storage = this.#storage;
        const instance = storage.get(identifier);
        return Tag.getSystem(instance) == system
          ? instance
          : undefined;
      }

      /**
       * Returns a new `Tag` resolved from the provided Tag U·R·I.
       *
       * ☡ This function throws if the provided Tag U·R·I does not
       * match the tagging entity of this constructor’s `TagSystem`.
       *
       * ※ If the specific component of the Tag U·R·I is not
       * recognized, this function returns `undefined`.
       */
      fromTagURI(tagURI) {
        const system = this.#system;
        const storage = this.#storage;
        const tagName = `${tagURI}`;
        const tagPrefix = `tag:${system.taggingEntity}:`;
        if (!tagName.startsWith(tagPrefix)) {
          // The Tag U·R·I does not begin with the expected prefix.
          throw new RangeError(
            `Tag U·R·I did not begin with the expected prefix: ${tagURI}`,
          );
        } else {
          // The I·R·I begins with the expected prefix.
          const identifier = tagName.substring(tagPrefix.length);
          try {
            // Attempt to resolve the identifier.
            const instance = storage.get(identifier);
            return Tag.getSystem(instance) == system
              ? instance
              : undefined;
          } catch {
            // Do not throw for bad identifiers.
            return undefined;
          }
        }
      }

      /**
       * Yields the tag identifiers in the `TagSystem` associated with
       * this constructor.
       */
      *identifiers() {
        const system = this.#system;
        const storage = this.#storage;
        for (const [identifier, instance] of storage.entries()) {
          // Iterate over the entries and yield the ones which are
          // `Tag`s in this `TagSystem`.
          if (Tag.getSystem(instance) == system) {
            // The current instance is a `Tag` in this `TagSystem`.
            yield identifier;
          } else {
            // The current instance is not a `Tag` in this `TagSystem`.
            /* do nothing */
          }
        }
      }

      /**
       * Returns a new `Tag` constructed from the provided data and
       * with the provided identifier.
       *
       * ※ This function is not really intended for public usage.
       */
      [Storage.toInstance](data, identifier) {
        const tag = new this(data.kind);
        return Tag.assignData(tag, data, identifier);
      }
    },
    TagSuper: tagConstructorBehaviours.TagSuper,
  };
})();

const {
  /**
   * Returns whether the provided schema, subject class, object
   * property, and object class are consistent.
   *
   * This is hardly a full reasoner; it is tuned to the abilites and
   * needs of this module.
   */
  isObjectPredicateOK,
} = (() => {
  const cachedClassAndSuperclasses = new WeakMap();
  const cachedClassRestrictions = new WeakMap();
  const cachedPredicateRestrictions = new WeakMap();

  const classAndSuperclasses = function* (
    classes,
    baseClass,
    touched = new Set(),
  ) {
    if (baseClass == "Thing" || touched.has(baseClass)) {
      /* do nothing */
    } else {
      yield baseClass;
      touched.add(baseClass);
      const subClassOf = classes[baseClass]?.subClassOf ?? "Thing";
      for (
        const superclass of (
          typeof subClassOf == "string"
            ? [subClassOf]
            : Array.from(subClassOf)
        ).filter(($) => typeof $ == "string")
      ) {
        yield* classAndSuperclasses(classes, superclass, touched);
      }
    }
  };

  const getClassAndSuperclasses = (schema, baseClass) => {
    const schemaCache = cachedClassAndSuperclasses.get(schema);
    const cached = schemaCache?.[baseClass];
    if (cached != null) {
      return cached;
    } else {
      const { classes } = schema;
      const result = [...classAndSuperclasses(classes, baseClass)];
      if (schemaCache) {
        schemaCache[baseClass] = result;
      } else {
        cachedClassRestrictions.set(
          schema,
          Object.assign(Object.create(null), { [baseClass]: result }),
        );
      }
      return result;
    }
  };

  const getClassRestrictions = (schema, domain) => {
    const schemaCache = cachedClassRestrictions.get(schema);
    const cached = schemaCache?.[domain];
    if (cached != null) {
      return cached;
    } else {
      const { classes } = schema;
      const restrictions = Object.create(null);
      const subClassOf = classes[domain]?.subClassOf ?? "Thing";
      for (
        const superclass of (
          typeof subClassOf == "string"
            ? [subClassOf]
            : Array.from(subClassOf)
        ).filter(($) => Object($) === $)
      ) {
        const { onProperty, allValuesFrom } = superclass;
        restrictions[onProperty] = processSpace(allValuesFrom);
      }
      if (schemaCache) {
        schemaCache[domain] = restrictions;
      } else {
        cachedClassRestrictions.set(
          schema,
          Object.assign(Object.create(null), {
            [domain]: restrictions,
          }),
        );
      }
      return restrictions;
    }
  };

  const getPredicateRestrictions = (schema, predicate) => {
    const schemaCache = cachedPredicateRestrictions.get(schema);
    const cached = schemaCache?.[predicate];
    if (cached != null) {
      return cached;
    } else {
      const { objectProperties } = schema;
      const restrictions = [
        ...predicateRestrictions(objectProperties, predicate),
      ].reduce(
        (result, { domainIntersection, rangeIntersection }) => {
          result.domainIntersection.push(...domainIntersection);
          result.rangeIntersection.push(...rangeIntersection);
          return result;
        },
        Object.assign(Object.create(null), {
          domainIntersection: [],
          rangeIntersection: [],
        }),
      );
      if (schemaCache) {
        schemaCache[predicate] = restrictions;
      } else {
        cachedPredicateRestrictions.set(
          schema,
          Object.assign(Object.create(null), {
            [predicate]: restrictions,
          }),
        );
      }
      return restrictions;
    }
  };

  const processSpace = (space) =>
    Object(space) === space
      ? "length" in space
        ? Array.from(
          space,
          (subspace) =>
            Object(subspace) === subspace
              ? Array.from(subspace.unionOf)
              : [subspace],
        )
        : [Array.from(space.unionOf)]
      : [[space]];

  const predicateRestrictions = function* (
    objectProperties,
    predicate,
    touched = new Set(),
  ) {
    if (predicate == "Property" || touched.has(predicate)) {
      /* do nothing */
    } else {
      const { domain, range, subPropertyOf } =
        objectProperties[predicate];
      yield Object.assign(Object.create(null), {
        domainIntersection: processSpace(domain ?? "Thing"),
        rangeIntersection: processSpace(range ?? "Thing"),
      });
      touched.add(predicate);
      for (
        const superproperty of (
          subPropertyOf == null
            ? ["Property"]
            : typeof subPropertyOf == "string"
            ? [subPropertyOf]
            : Array.from(subPropertyOf)
        )
      ) {
        yield* predicateRestrictions(
          objectProperties,
          superproperty,
          touched,
        );
      }
    }
  };

  return {
    isObjectPredicateOK: (
      schema,
      subjectClass,
      predicate,
      objectClass,
    ) => {
      const { objectProperties } = schema;
      const predicateDefinition = objectProperties[predicate];
      const isInverse = "inverseOf" in predicateDefinition;
      const usedPredicate = isInverse
        ? predicateDefinition.inverseOf
        : predicate;
      const domain = isInverse ? objectClass : subjectClass;
      const domains = new Set(getClassAndSuperclasses(schema, domain));
      const ranges = new Set(getClassAndSuperclasses(
        schema,
        isInverse ? subjectClass : objectClass,
      ));
      const predicateRestrictions = getPredicateRestrictions(
        schema,
        usedPredicate,
      );
      const { domainIntersection } = predicateRestrictions;
      const rangeIntersection = [
        ...predicateRestrictions.rangeIntersection,
        ...function* () {
          for (const domain of domains) {
            const classRestrictionOnPredicate =
              getClassRestrictions(schema, domain)[usedPredicate];
            if (classRestrictionOnPredicate != null) {
              yield* classRestrictionOnPredicate;
            } else {
              /* do nothing */
            }
          }
        }(),
      ];
      return domainIntersection.every((domainUnion) =>
        domainUnion.some((domain) =>
          domain == "Thing" || domains.has(domain)
        )
      ) &&
        rangeIntersection.every((rangeUnion) =>
          rangeUnion.some((range) =>
            range == "Thing" || ranges.has(range)
          )
        );
    },
  };
})();

const {
  /**
   * Returns the provided value converted into a `String` object with
   * `.["@value"]` and `.["@language"]` properties.
   *
   * The same object will be returned for every call with an equivalent
   * value.
   *
   * TODO: Ideally this would be extracted more fully into an R·D·F
   * library.
   *
   * ※ This function is not exposed.
   */
  langString,
} = (() => {
  /**
   * Returns the language string object corresponding to the provided
   * value and language.
   */
  const getLangString = (value, language = "") => {
    const valueMap = languageMap[language] ??= Object.create(null);
    const literal = valueMap[value]?.deref();
    if (literal != null) {
      // There is already an object corresponding to the provided value
      // and language.
      return literal;
    } else {
      // No object already exists corresponding to the provided value
      // and language; create one.
      const result = Object.preventExtensions(
        Object.create(String.prototype, {
          "@value": {
            enumerable: true,
            value,
          },
          "@language": {
            enumerable: !!language,
            value: language || null,
          },
          language: { enumerable: false, get: getLanguage },
          toString: { enumerable: false, value: toString },
          valueOf: { enumerable: false, value: valueOf },
        }),
      );
      const ref = new WeakRef(result);
      langStringRegistry.register(result, { ref, language, value });
      valueMap[value] = ref;
      return result;
    }
  };

  /** Returns the `.["@language"]` of this object. */
  const getLanguage = Object.defineProperty(
    function () {
      return this["@language"] || null;
    },
    "name",
    { value: "get language" },
  );

  /**
   * A `FinalizationRegistry` for language string objects.
   *
   * This simply cleans up the corresponding `WeakRef` in the language
   * map.
   */
  const langStringRegistry = new FinalizationRegistry(
    ({ ref, language, value }) => {
      const valueMap = languageMap[language];
      if (valueMap?.[value] === ref) {
        delete valueMap[value];
      } else {
        /* do nothing */
      }
    },
  );

  /**
   * An object whose own values are an object mapping values to
   * language string objects for the language specified by the key.
   */
  const languageMap = Object.create(null);

  /** Returns the `.["@value"]` of this object. */
  const toString = function () {
    return this["@value"];
  };

  /**
   * Returns this object if it has a `.["@language"]`; otherwise, its
   * `.["@value"]`.
   */
  const valueOf = function () {
    return this["@language"] ? this : this["@value"];
  };

  return {
    langString: ($) =>
      Object($) === $
        ? "@value" in $
          ? "@language" in $
            ? getLangString(
              `${$["@value"]}`,
              `${$["@language"] ?? ""}`,
            )
            : getLangString(`${$["@value"]}`)
          : "language" in $
          ? getLangString(`${$}`, `${$.language ?? ""}`)
          : getLangString(`${$}`)
        : getLangString(`${$ ?? ""}`),
  };
})();

/**
 * Returns a normalized tag data object derived from the provided
 * object.
 *
 * ※ The properties of this function need to match the term names used
 * in the ActivityStreams serialization.
 *
 * ※ This function is not exposed.
 */
const tagData = ($) => {
  const data = Object($);
  const {
    // prefLabel intentionally not set here
    altLabel,
    hiddenLabel,
    broader,
    narrower,
    inCanon,
    hasInCanon,
    involves,
    involvedIn,
  } = data;
  let prefLabel = langString(data.prefLabel);
  return Object.preventExtensions(Object.create(null, {
    prefLabel: {
      enumerable: true,
      get: () => prefLabel,
      set: ($) => {
        prefLabel = langString($);
      },
    },
    altLabel: {
      enumerable: true,
      value: new Set(
        altLabel != null
          ? Array.from(altLabel, langString)
          : undefined,
      ),
    },
    hiddenLabel: {
      enumerable: true,
      value: new Set(
        hiddenLabel != null
          ? Array.from(hiddenLabel, langString)
          : undefined,
      ),
    },
    broader: {
      enumerable: true,
      value: new Set(
        broader != null
          ? Array.from(broader, toIdentifier)
          : undefined,
      ),
    },
    narrower: {
      enumerable: true,
      value: new Set(
        narrower != null
          ? Array.from(narrower, toIdentifier)
          : undefined,
      ),
    },
    inCanon: {
      enumerable: true,
      value: new Set(
        inCanon != null
          ? Array.from(inCanon, toIdentifier)
          : undefined,
      ),
    },
    hasInCanon: {
      enumerable: true,
      value: new Set(
        hasInCanon != null
          ? Array.from(hasInCanon, toIdentifier)
          : undefined,
      ),
    },
    involves: {
      enumerable: true,
      value: new Set(
        involves != null
          ? Array.from(involves, toIdentifier)
          : undefined,
      ),
    },
    involvedIn: {
      enumerable: true,
      value: new Set(
        involvedIn != null
          ? Array.from(involvedIn, toIdentifier)
          : undefined,
      ),
    },
  }));
};

/**
 * Returns an identifier corresponding to the provided object.
 *
 * This is either the value of its `.identifier` or its string value.
 *
 * ※ This function is not exposed.
 */
const toIdentifier = ($) =>
  $ == null
    ? null
    : Object($) === $ && "identifier" in $
    ? $.identifier
    : `${$}`;

/**
 * A tag system, with storage.
 *
 * The `::Tag` constructor available on any `TagSystem` instance can be
 * used to create new `Tag`s within the system.
 */
export class TagSystem {
  /** The cached bound `Tag` constructor for this `TagSystem`. */
  #Tag = null;

  /** The domain of this `TagSystem`. */
  #domain;

  /** The date of this `TagSystem`. */
  #date;

  /** The identifier of this `TagSystem`. */
  #identifier;

  /** The internal `Storage` of this `TagSystem`. */
  #storage = new Storage();

  /**
   * Constructs a new `TagSystem` with the provided domain and date.
   *
   * Only actual, lowercased domain names are allowed for the domain,
   * and the date must be “full” (include month and day components).
   * This is for alignment with general best practices for Tag URI’s.
   *
   * ☡ This constructor throws if provided with an invalid date.
   */
  constructor(domain, date, identifier = "") {
    const domainString = `${domain}`;
    const dateString = `${date}`;
    this.#identifier = `${identifier}`;
    try {
      // If the identifier is a valid storage I·D, reserve it.
      this.#storage.delete(this.#identifier);
    } catch {
      // The identifier is not a valid storage I·D, so no worries.
      /* do nothing */
    }
    if (
      !/^[a-z](?:[\da-z-]*[\da-z])?(?:\.[a-z](?:[\da-z-]*[\da-z])?)*$/u
        .test(domainString)
    ) {
      // ☡ The domain is invalid.
      throw new RangeError(`Invalid domain: ${domain}.`);
    } else if (
      !/^\d{4}-\d{2}-\d{2}$/u.test(dateString) ||
      dateString != new Date(dateString).toISOString().split("T")[0]
    ) {
      // ☡ The date is invalid.
      throw new RangeError(`Invalid date: ${date}.`);
    } else {
      // The domain and date are 🆗.
      this.#domain = domainString;
      this.#date = dateString;
    }
  }

  /**
   * Returns a bound constructor for constructing `Tags` in this
   * `TagSystem`.
   */
  get Tag() {
    if (this.#Tag != null) {
      // A bound constructor has already been generated; return it.
      return this.#Tag;
    } else {
      // No bound constructor has been created yet.
      const storage = this.#storage;
      return this.#Tag = Tag.For(this, storage, schema);
    }
  }

  /** Returns the authority name (domain) for this `TagSystem`. */
  get authorityName() {
    return this.#domain;
  }

  /** Returns the date of this `TagSystem`, as a string. */
  get date() {
    return this.#date;
  }

  /**
   * Yields the entities in this `TagSystem`.
   *
   * ※ Entities can hypothetically be anything. If you specifically
   * want the `Tag`s, use `::Tag.all` instead.
   */
  *entities() {
    yield* this.#storage.values();
  }

  /**
   * Returns the identifier of this `TagSystem`.
   *
   * ※ Often this is just the empty string.
   */
  get identifier() {
    return this.#identifier;
  }

  /** Yields the identifiers in use in this `TagSystem`. */
  *identifiers() {
    yield* this.#storage.keys();
  }

  /** Returns the I·R·I for this `TagSystem`. */
  get iri() {
    return `${this.iriSpace}${this.identifier}`;
  }

  /**
   * Returns the prefix used for I·R·I’s of `Tag`s in this `TagSystem`.
   */
  get iriSpace() {
    return `https://${this.authorityName}/tag:${this.taggingEntity}:`;
  }

  /** Returns the Tag U·R·I for this `TagSystem`. */
  get tagURI() {
    return `tag:${this.taggingEntity}:${this.identifier}`;
  }

  /**
   * Returns the tagging entity (domain and date) for this `TagSystem`.
   */
  get taggingEntity() {
    return `${this.authorityName},${this.date}`;
  }
}