@arpproject/recrate 0.1.2

package/src/crate-builder/CrateManager/lib.spec.ts

@@ -0,0 +1,133 @@
+import { describe, expect, test } from "vitest";
+import { isURL, normaliseEntityType, normalise } from "./lib";
+
+describe("Test urls are correctly identified", () => {
+    test(`expect fail- ''`, () => {
+        let url = undefined;
+        expect(isURL(url)).toBeFalsy;
+    });
+
+    test(`expect fail - 3`, () => {
+        expect(isURL(3)).toBeFalsy;
+    });
+    test(`expect fail - true`, () => {
+        expect(isURL(true)).toBeFalsy;
+    });
+    test(`expect fail - data://server.name`, () => {
+        expect(isURL("data://server.name")).toBeFalsy;
+    });
+    test(`expect pass - http://schema.org/person`, () => {
+        expect(isURL("http://schema.org/person")).toBeTruthy;
+    });
+    test(`expect pass - https://schema.org/person`, () => {
+        expect(isURL("https://schema.org/person")).toBeTruthy;
+    });
+    test(`expect pass - ftp://server.name`, () => {
+        expect(isURL("ftp://server.name")).toBeTruthy;
+    });
+    test(`expect pass - ftps://server.name`, () => {
+        expect(isURL("ftps://server.name")).toBeTruthy;
+    });
+    test(`arcp://uuid,32a423d6-52ab-47e3-a9cd-54f418a48571/doc.html`, () => {
+        expect(isURL("arcp://uuid,32a423d6-52ab-47e3-a9cd-54f418a48571/doc.html")).toBeTruthy;
+    });
+    test(`arcp://uuid,b7749d0b-0e47-5fc4-999d-f154abe68065/pics/`, () => {
+        expect(isURL("arcp://uuid,b7749d0b-0e47-5fc4-999d-f154abe68065/pics/")).toBeTruthy;
+    });
+    test(`arcp://ni,sha-256;F-34D4TUeOfG0selz7REKRDo4XePkewPeQYtjL3vQs0/`, () => {
+        expect(isURL("arcp://ni,sha-256;F-34D4TUeOfG0selz7REKRDo4XePkewPeQYtjL3vQs0/")).toBeTruthy;
+    });
+    test(`arcp://name,gallery.example.org/`, () => {
+        expect(isURL("arcp://name,gallery.example.org/")).toBeTruthy;
+    });
+});
+
+describe("Test normalising an entity type", () => {
+    test(`no type defined - @id = ./`, () => {
+        let entity = { "@id": "./" };
+        expect(normaliseEntityType({ entity })).toMatchObject(["Thing"]);
+    });
+    test(`no type defined - @id = http://schema.org/person`, () => {
+        let entity = { "@id": "http://schema.org/person" };
+        expect(normaliseEntityType({ entity })).toMatchObject(["URL"]);
+    });
+    test(`type is boolean`, () => {
+        let entity = { "@id": "http://schema.org/person", "@type": true };
+        expect(normaliseEntityType({ entity })).toMatchObject(["true"]);
+    });
+    test(`type is number`, () => {
+        let entity = { "@id": "http://schema.org/person", "@type": 3 };
+        expect(normaliseEntityType({ entity })).toMatchObject(["3"]);
+    });
+    test(`type is string - 'Dataset'`, () => {
+        let entity = { "@id": "http://schema.org/person", "@type": "Dataset" };
+        expect(normaliseEntityType({ entity })).toMatchObject(["Dataset"]);
+    });
+    test(`type is string - 'Dataset, Collection'`, () => {
+        let entity = { "@id": "http://schema.org/person", "@type": "Dataset,Collection" };
+        expect(normaliseEntityType({ entity })).toMatchObject(["Dataset", "Collection"]);
+    });
+});
+
+describe("Test normalising an entity", () => {
+    test(`reject bad @type`, () => {
+        try {
+            // @ts-expect-error: Intentionally passing incorrect type for testing
+            normalise({ "@type": {} }, 1);
+        } catch (error) {
+            expect((error as Error).message).toEqual(
+                `'@type' property must be a string or an array or not defined at all`
+            );
+        }
+    });
+    test(`reject bad @id`, () => {
+        try {
+            // @ts-expect-error: Intentionally passing incorrect type for testing
+            normalise({ "@id": {} }, 1);
+        } catch (error) {
+            expect((error as Error).message).toEqual(
+                `'@id' property must be a string or not defined at all`
+            );
+        }
+
+        try {
+            // @ts-expect-error: Intentionally passing incorrect type for testing
+            normalise({ "@id": 3 }, 1);
+        } catch (error) {
+            expect((error as Error).message).toEqual(
+                `'@id' property must be a string or not defined at all`
+            );
+        }
+    });
+    test(`reject if @type not defined`, () => {
+        let entity = { "@id": "./" };
+        expect(normalise(entity, 1)).toBeFalsy;
+    });
+
+    test(`no @id set`, () => {
+        let entity = { "@type": "Dataset" };
+        // console.log(normalise(entity, 1));
+        expect(normalise(entity, 1)).toEqual({ "@type": ["Dataset"], "@id": "#e1/", name: "e1/" });
+    });
+
+    test(`Dataset entity`, () => {
+        let entity = { "@id": "somewhere", "@type": "Dataset" };
+        // console.log(normalise(entity, 1));
+        expect(normalise(entity, 1)).toEqual({
+            "@type": ["Dataset"],
+            "@id": "somewhere/",
+            name: "somewhere/",
+        });
+    });
+
+    test(`Entity with properties containing numbers`, () => {
+        let entity = { "@id": "somewhere", "@type": "Dataset", name: "something", pid: 3 };
+        // console.log(normalise(entity, 1));
+        expect(normalise(entity, 1)).toEqual({
+            "@type": ["Dataset"],
+            "@id": "somewhere/",
+            name: "something",
+            pid: [3],
+        });
+    });
+});

package/src/crate-builder/CrateManager/lib.ts

@@ -0,0 +1,170 @@
+import isArray from "lodash/isArray.js";
+import isNumber from "lodash/isNumber.js";
+import isBoolean from "lodash/isBoolean.js";
+import isString from "lodash/isString.js";
+import isUndefined from "lodash/isUndefined.js";
+import isNull from "lodash/isNull.js";
+import { isURL as validatorIsURL } from "validator";
+import { validateId } from "./validate-identifier";
+import type { UnverifiedEntityDefinition, NormalisedEntityDefinition } from "../types.js";
+import { isEmpty, isObject } from "lodash";
+
+export const urlProtocols = ["http", "https", "ftp", "ftps"];
+
+/**
+ *
+ * @param {string} value - string to check as a URL: checks 'http','https','ftp', 'arcp'
+ */
+export function isURL(value: string | number | boolean | undefined | null): boolean {
+    if (!value) return false;
+    if (isNumber(value)) return false;
+    if (isBoolean(value)) return false;
+    if (isArray(value)) return false;
+    if (value.match(/arcp:\/\/name,.*/)) return true;
+    if (value.match(/arcp:\/\/uuid,.*/)) return true;
+    if (value.match(/arcp:\/\/ni,sha-256;,.*/)) return true;
+    return validatorIsURL(value, {
+        require_protocol: true,
+        protocols: urlProtocols,
+    });
+}
+
+/**
+ *  This method normalises an entity. It checks that the '@type' is sensible, '@id' is valid and sets the name to the '@id' if not set
+ *
+ * @param {Object} entity - an entity to normalise
+ * @param {string} i - if an id is not defined, then it will be set to #e${i}
+ *
+ * @returns the entity ready for use
+ */
+export function normalise(
+    entity: UnverifiedEntityDefinition,
+    i: number
+): NormalisedEntityDefinition {
+    if (!isString(entity["@type"]) && !isArray(entity["@type"]) && !isUndefined(entity["@type"])) {
+        throw new Error(`'@type' property must be a string or an array or not defined at all`);
+    }
+    if (!isString(entity["@id"]) && !isUndefined(entity["@id"] && !isNull(entity["@id"]))) {
+        throw new Error(`'@id' property must be a string or not defined at all`);
+    }
+
+    const normalisedEntity = {
+        "@id": "",
+        "@type": "",
+        name: "",
+    } as any as NormalisedEntityDefinition;
+
+    if (isUndefined(entity["@id"]) || isNull(entity["@id"])) {
+        // set it to the generated id
+        normalisedEntity["@id"] = `#e${i}`;
+    } else {
+        normalisedEntity["@id"] = isEncoded(entity["@id"])
+            ? entity["@id"]
+            : encodeURI(entity["@id"]);
+    }
+
+    //  normalise the entity['@type']
+    normalisedEntity["@type"] = normaliseEntityType({ entity });
+
+    // if it's a dataset, ensure the @id ends with /
+    if (
+        normalisedEntity["@type"].includes("Dataset") &&
+        normalisedEntity["@id"].slice(-1) !== "/"
+    ) {
+        normalisedEntity["@id"] = `${normalisedEntity["@id"]}/`;
+    }
+
+    // there is an @id - is it valid?
+    let { isValid, message } = validateId({
+        id: normalisedEntity["@id"],
+        type: normalisedEntity["@type"],
+    });
+    if (
+        !isValid &&
+        message ===
+            "The identifier is not valid according to the RO Crate spec nor is it a valid IRI."
+    ) {
+        // set the id to an internal reference
+        normalisedEntity["@id"] = `#${normalisedEntity["@id"]}`;
+    }
+
+    // is there a name?
+    normalisedEntity.name = entity.name ? entity.name : normalisedEntity["@id"].replace(/^#/, "");
+
+    // if the name is an array join it back into a string
+    if (isArray(normalisedEntity.name)) normalisedEntity.name = normalisedEntity.name.join(" ");
+
+    // set all properties other than core prop's to array
+    //  and remove any rubbish: undefined, null and empty
+    for (let property of Object.keys(entity)) {
+        if (["@id", "@type", "name", "@reverse"].includes(property)) continue;
+
+        // set property data as array
+        let propertyData = Array.isArray(entity[property]) ? entity[property] : [entity[property]];
+
+        // iterate over the property data
+        (normalisedEntity as any)[property] = propertyData.filter((entry) => {
+            // remove rubbish
+            return (
+                !isUndefined(entry) &&
+                !isNull(entry) &&
+                !(isObject(entry) && isEmpty(entry)) &&
+                !(isString(entry) && isEmpty(entry))
+            );
+        });
+        if (!normalisedEntity[property].length) delete normalisedEntity[property];
+    }
+
+    return normalisedEntity;
+}
+
+export function normaliseEntityType({ entity }: { entity: UnverifiedEntityDefinition }): string[] {
+    let type: string[];
+
+    if (!entity["@type"]) {
+        type = isURL(entity["@id"]) ? ["URL"] : ["Thing"];
+    } else if (isArray(entity["@type"])) {
+        type = entity["@type"].map((t) => "" + t);
+    } else if (isBoolean(entity["@type"]) || isNumber(entity["@type"])) {
+        type = ["" + entity["@type"]];
+    } else if (isString(entity["@type"])) {
+        type = entity["@type"].split(",").map((t) => t.trim());
+    } else {
+        // Handle any other unexpected cases
+        type = ["Thing"];
+    }
+
+    return type;
+}
+
+/**
+ *
+ * Mint an empty RO-Crate that conforms to the spec
+ *
+ * @returns a skeleton crate ready to be used
+ */
+export function mintNewCrate(): {} {
+    return {
+        "@context": "https://w3id.org/ro/crate/1.1/context",
+        "@graph": [
+            {
+                "@type": "CreativeWork",
+                "@id": "ro-crate-metadata.json",
+                about: { "@id": "./" },
+                conformsTo: { "@id": "https://w3id.org/ro/crate/1.1" },
+            },
+
+            {
+                "@id": "./",
+                "@type": "Dataset",
+                name: "My Research Object Crate",
+            },
+        ],
+    };
+}
+
+function isEncoded(uri: string) {
+    uri = uri || "";
+
+    return uri !== decodeURIComponent(uri);
+}