Return undefined not null when resolving fails

If an identifier is not in use, its resolved value should be
`undefined`.

diff --git a/model.js b/model.js
index d64f6c4218889f7cab3c60dbc215fec884fe6ead..cfd228d88f12e7e7625a1f2374f3775d57021683 100644 (file)
--- a/model.js
+++ b/model.js
@@ -901,7 +901,7 @@ const {
        * of the `TagSystem` associated with this constructor.
        *
        * ※ If the I·R·I is not recognized, this function returns
-       * `null`.
+       * `undefined`.
        */
       fromIRI(iri) {
         const system = this.#system;
@@ -919,10 +919,12 @@ const {
           try {
             // Attempt to resolve the identifier.
             const instance = storage.get(identifier);
-            return Tag.getSystem(instance) == system ? instance : null;
+            return Tag.getSystem(instance) == system
+              ? instance
+              : undefined;
           } catch {
             // Do not throw for bad identifiers.
-            return null;
+            return undefined;
           }
         }
       }
@@ -933,13 +935,15 @@ const {
        * ☡ This function throws if the identifier is invalid.
        *
        * ※ If the identifier is valid but not recognized, this
-       * function returns `null`.
+       * function returns `undefined`.
        */
       fromIdentifier(identifier) {
         const system = this.#system;
         const storage = this.#storage;
         const instance = storage.get(identifier);
-        return Tag.getSystem(instance) == system ? instance : null;
+        return Tag.getSystem(instance) == system
+          ? instance
+          : undefined;
       }
 
       /**
@@ -949,7 +953,7 @@ const {
        * 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 `null`.
+       * recognized, this function returns `undefined`.
        */
       fromTagURI(tagURI) {
         const system = this.#system;
@@ -967,10 +971,12 @@ const {
           try {
             // Attempt to resolve the identifier.
             const instance = storage.get(identifier);
-            return Tag.getSystem(instance) == system ? instance : null;
+            return Tag.getSystem(instance) == system
+              ? instance
+              : undefined;
           } catch {
             // Do not throw for bad identifiers.
-            return null;
+            return undefined;
           }
         }
       }

diff --git a/model.test.js b/model.test.js
index a92671c52d2a4a033ab575172ff6abe7e00f2117..ed1430e8a49246c1a97190eb3e64ca9e443bbad3 100644 (file)
--- a/model.test.js
+++ b/model.test.js
@@ -183,12 +183,12 @@ describe("TagSystem", () => {
         assertStrictEquals(retrieved.identifier, identifier);
       });
 
-      it("[[Call]] returns null if no tag with the given I·R·I has been persisted", () => {
+      it("[[Call]] returns undefined if no tag with the given I·R·I has been persisted", () => {
         assertStrictEquals(
           Tag.fromIRI(
             `https://${system.authorityName}/tag:${system.taggingEntity}:000-0000`,
           ),
-          null,
+          undefined,
         );
       });
 
@@ -212,8 +212,8 @@ describe("TagSystem", () => {
         assertStrictEquals(retrieved.identifier, identifier);
       });
 
-      it("[[Call]] returns null if no tag with the given identifier has been persisted", () => {
-        assertStrictEquals(Tag.fromIdentifier("000-0000"), null);
+      it("[[Call]] returns undefined if no tag with the given identifier has been persisted", () => {
+        assertStrictEquals(Tag.fromIdentifier("000-0000"), undefined);
       });
 
       it("[[Call]] throws if passed an invalid identifier", () => {
@@ -239,14 +239,14 @@ describe("TagSystem", () => {
         assertStrictEquals(retrieved.identifier, identifier);
       });
 
-      it("[[Call]] returns null if no tag with the given Tag U·R·I has been persisted", () => {
+      it("[[Call]] returns undefined if no tag with the given Tag U·R·I has been persisted", () => {
         assertStrictEquals(
           Tag.fromTagURI(`tag:${system.taggingEntity}:`),
-          null,
+          undefined,
         );
         assertStrictEquals(
           Tag.fromTagURI(`tag:${system.taggingEntity}:000-0000`),
-          null,
+          undefined,
         );
       });