@arpproject/recrate 0.1.2

package/dist/crate-builder/CrateManager/crate-manager.d.ts

@@ -0,0 +1,641 @@
+import { UnverifiedContext, NormalisedContext, UnverifiedCrate, NormalisedCrate, ProfileManagerType, UnverifiedEntityDefinition, NormalisedEntityDefinition, EntityReference, PrimitiveType, NormalisedProfile } from '../types.js';
+interface errorsInterface {
+    hasError: Boolean;
+    init: {
+        description: string;
+        messages: string[];
+    };
+    missingIdentifier: {
+        description: string;
+        entity: UnverifiedEntityDefinition[];
+    };
+    missingTypeDefinition: {
+        description: string;
+        entity: UnverifiedEntityDefinition[];
+    };
+    invalidIdentifier: {
+        description: string;
+        entity: UnverifiedEntityDefinition[];
+    };
+    clash: {
+        description: string;
+        messages: string[];
+    };
+}
+interface warningsInterface {
+    hasWarning: Boolean;
+    init: {
+        description: string;
+        messages: string[];
+    };
+    invalidIdentifier: {
+        description: string;
+        entity: UnverifiedEntityDefinition[];
+    };
+    clash: {
+        description: string;
+        messages: string[];
+    };
+}
+/**
+ * @class
+ *
+ * CrateManager
+ *
+ * A class to work with RO-Crates
+ *
+ * @param {crate} - an RO Crate to handle
+ */
+export declare class CrateManager {
+    crate: {
+        "@context": NormalisedContext;
+        "@graph": Array<NormalisedEntityDefinition | undefined>;
+    };
+    pm: ProfileManagerType;
+    reverse: {
+        [key: string]: any;
+    };
+    graphLength: number;
+    rootDescriptor?: number;
+    rootDataset?: number;
+    entityIdIndex: {
+        [key: string]: number;
+    };
+    providedContext: UnverifiedContext;
+    contextDefinitions: {
+        [key: string]: boolean;
+    };
+    localContext: {
+        [key: string]: string;
+    };
+    entityTypes: {
+        [key: string]: number;
+    };
+    entityTimestamps: Boolean;
+    blankNodes: string[];
+    coreProperties: string[];
+    errors: errorsInterface;
+    warnings: warningsInterface;
+    constructor({ crate, pm, context, entityTimestamps, }: {
+        crate: UnverifiedCrate;
+        pm?: ProfileManagerType;
+        context?: UnverifiedContext;
+        entityTimestamps?: Boolean;
+    });
+    /** Get the context
+     * @returns the crate context
+     */
+    getContext(): NormalisedContext;
+    /**
+     * Set the context
+     *
+     * This is equivalent to a profile author setting a context. It gets
+     *   used as is and data updates going forward do not get dealth with.
+     * @param {*} context
+     */
+    setContext(context: NormalisedContext): void;
+    /**
+     * Set a profile
+     *
+     * CrateManager can set reverse associations if defined in a profile.
+     *
+     * */
+    setProfileManager(pm: ProfileManagerType): void;
+    /**
+     * Get the root dataset
+     *
+     * @returns the root dataset entity
+     * @example
+
+const cm = new CrateManager({ crate })
+let rd = cm.getRootDataset()
+
+     */
+    getRootDataset(): NormalisedEntityDefinition;
+    getRootDescriptor(): NormalisedEntityDefinition;
+    /**
+     * Get an entity
+     *
+     * @param {Object} options
+     * @param {string} options.id - the id of the entity to get
+     * @param {boolean} options.stub - if true, only the `@id, @type and name` prop's will be returned. That is,
+     *                   you get a stub entry not the complete entity data.
+     * @param {boolean} options.link - if true, all the associated entities are filled out as stubs
+     * @param {boolean} options.materialise - if true, the entity will be created if it doesn't exist (consider
+     *                  when URL's point outside the crate, in this case, they will be created as entities inside it)
+     * @returns the entity
+     *
+     * @example
+
+const cm = new CrateManager({ crate })
+
+// get the full entity
+let rd = cm.getEntity({ id: './' })
+
+// return a stub entry
+rd = cm.getEntity({ id: './', stub: true })
+
+     */
+    getEntity({ id, stub, link, materialise, }: {
+        id: string;
+        stub?: boolean;
+        link?: boolean;
+        materialise?: boolean;
+    }): NormalisedEntityDefinition | undefined;
+    /**
+     *  Get Entity Types
+     *
+     * @returns an array of entity types, sorted, found in the crate
+     */
+    getEntityTypes(): string[];
+    /**
+     * @generator
+     *
+     * @param {Object} params
+     * @param {Number} params.limit - how many entities to return
+     * @param {string} params.query - a string to match against @id, @type and name
+     * @param {string} params.type -  a string to match against @type
+     * @yields {entity}
+     * @example
+
+const cm = new CrateManager({crate})
+let entities = cm.getEntities()
+
+for (let entity of entities) {
+    ...
+}
+
+To get an array just spread the return
+let entities = [ ...cm.getEntities() ]
+
+// query @id, @type and name
+entities = cm.getEntities({ query: 'person' })
+
+// query @id, @type and name for entites of type Person
+entities = cm.getEntities({ query: 'person', type: 'Person' })
+
+// query @id, @type and name for entites of type Person - limit 10 matches
+entities = cm.getEntities({ query: 'person', type: 'Person', limit: 10 })
+
+     */
+    getEntities(params?: {
+        limit?: number;
+        query?: string;
+        type?: string;
+    }): Generator<NormalisedEntityDefinition>;
+    /**
+     *
+     * locateEntity
+     *
+     * Given a set of id's, find the entity or entities that link to all of them.
+     *  This is really for finding grouping type entities like Relationships and Actions so that
+     *  you can augment their description.
+     *  @param { object } params
+     *  @param { array } params.entityIds - an array of entity id's that are linked to from another entity
+     *  @param { boolean } params.strict - if true return entities that have exactly entityIds linked. If false,
+     *                          return entities that have at least entityIds linked
+     *  @returns [] entities matching or undefined
+     */
+    locateEntity({ entityIds, strict, }: {
+        entityIds: string[];
+        strict?: boolean;
+    }): NormalisedEntityDefinition[] | undefined;
+    /**
+     * resolveLinkedEntities
+     *
+     * Given an entity and a profile, if the entity matches a resolve configuration
+     *   this method will populate the entities linked from the resolve properties
+     *   defined in the profile.
+     *
+     * @param {Object} entity
+     * @param {Object} profile
+     *
+     * @returns an array of associations
+     * @example
+
+// given an entity
+let entity = {
+    "@id": "#createAction1",
+    "@type": ["CreateAction"],
+    name: "A very long named create action to demonstrate what happens with display of long names",
+    object: { "@id": "#person2" },
+    participant: { "@id": "#participant1" },
+    agent: { "@id": "#agent1" },
+};
+
+// and a profile with a resolve configuration
+let profile = {
+    ...
+    resolve: [
+        {
+            types: [ 'Relationship', 'Related' ],
+            properties: [ 'source', 'target' ]
+        },
+        {
+            types: [ 'CreateAction', 'EditAction' ],
+            properties: [ 'object', 'participant', 'agent' ]
+        }
+    ]
+    ...
+}
+
+// get a list of the associated entities
+console.log(cm.resolveLinkedEntityAssociations({ entity, profile }))
+
+
+associations === [
+  {
+    property: 'object',
+    '@id': '#person2',
+    '@type': [ 'Thing' ],
+    name: '#person2'
+  },
+  {
+    property: 'participant',
+    '@id': '#participant1',
+    '@type': [ 'Thing' ],
+    name: '#participant1'
+  },
+  {
+    property: 'agent',
+    '@id': '#agent1',
+    '@type': [ 'Thing' ],
+    name: '#agent1'
+  }
+]
+
+     */
+    resolveLinkedEntityAssociations({ entity, profile, }: {
+        entity: NormalisedEntityDefinition;
+        profile: NormalisedProfile;
+    }): {
+        property: string;
+        "@id": string;
+        "@type": string[];
+        name: string;
+    }[] | [];
+    /**
+     * Add an entity to the graph
+     *
+     *  The entity must have '@id' and '@type' defined.
+     *
+     * @param {Object} entity - an entity definition to add to the crate
+     * @returns the entity
+     * @example
+
+const cm = new CrateManager({ crate })
+let entity = {
+    "@id": '#e1',
+    "@type": "Person",
+    name: 'person1',
+};
+let r = cm.addEntity(entity);
+
+     */
+    addEntity(entity: UnverifiedEntityDefinition): NormalisedEntityDefinition;
+    /**
+     * Add an entity with a blank node id ('_:...') to the graph.
+     *
+     * Use this when you want to add a non contextual entity to the graph. In thoses
+     *   cases providing an `@id` and name don't really make sense even though those properties are still required
+     *   therefore this method simplifies the process of adding those entity types. For example,
+     *   Actions (e.g. CreateAction), Relationships, GeoShape, GeoCoordinates etc
+     *
+     * @param {string} type - the entity type to configure for the new entity
+     * @returns the entity
+     * @example
+
+const cm = new CrateManager({ crate })
+let r = cm.addBlankNode('Relationship);
+
+r === {
+    '@id': '_:Relationship1',
+    '@type': [ 'Relationship' ],
+    name: '_:Relationship1'
+}
+
+     */
+    addBlankNode(type: string): NormalisedEntityDefinition;
+    /**
+     * Add files or folders - use addFile or addFolder in preference to this
+     *
+     * This is a helper method specifically for adding files and folders in the crate. This method
+     *   will add the intermediate paths as 'Datasets' (as per the spec) and link everything via the hasPart
+     *   property as required. It is assumed that the path is relative to the root of the folder.
+     *
+     * @param {object} params
+     * @param {string} params.path - a file or folder path
+     * @param {string} params.type - the type of thing being added - File or Dataset
+     * @returns the entity
+     * @example
+
+const cm = new CrateManager({ crate })
+let r = cm.addFileOrFolder('/a/b/c/file.txt);
+     */
+    addFileOrFolder({ path, type, }: {
+        path: string;
+        type: string;
+    }): NormalisedEntityDefinition;
+    /**
+     * Add file
+     *
+     * This is a helper method specifically for adding files to the crate. This method
+     *   will add the intermediate paths as 'Datasets' (as per the spec) and link everything via the hasPart
+     *   property as required. It is assumed that the path is relative to the root of the folder.
+     *
+     * @param {string} path - a file path to add - ensure the file path is relative to the folder root
+     * @returns the entity
+     * @example
+
+const cm = new CrateManager({ crate })
+let r = cm.addFile('/a/b/c/file.txt);
+     */
+    addFile(path: string): NormalisedEntityDefinition;
+    /**
+     * Add folder
+     *
+     * This is a helper method specifically for adding folders to the crate. This method
+     *   will add the intermediate paths as 'Datasets' (as per the spec) and link everything via the hasPart
+     *   property as required. It is assumed that the path is relative to the root of the folder.
+     *
+     * @param {string} path - a folder path to add - ensure the folder path is relative to the folder root
+     * @returns the entity
+     * @example
+
+const cm = new CrateManager({ crate })
+let r = cm.addFolder('/a/b/c);
+     */
+    addFolder(path: string): NormalisedEntityDefinition;
+    /**
+     * Delete an entity
+     *
+     * @param {Object} options
+     * @param {string} options.id - the id of the entity to delete from the crate
+     *
+     * @returns true if successful
+     * @example
+
+const cm = new CrateManager({ crate })
+cm.deleteEntity({ id: '#e1' })
+
+     */
+    deleteEntity({ id }: {
+        id: string;
+    }): true | undefined;
+    /**
+     * Set a property on an entity
+     *
+     * @param {Object} options
+     * @param {options.id} options.id - the id of the entity to add the property to
+     * @param {options.property } options.property - the property to add
+     * @param {options.value} options.value - the data to add to that property. Can be string or object with '@id'
+     * @returns true if successful
+     * @example
+
+const cm = new CrateManager({ crate })
+const authorId = chance.url();
+
+//  setting an object reference
+cm.setProperty({ id: "./", property: "author", value: { "@id": authorId } });
+
+//  setting a text string
+cm.setProperty({ id: "./", property: "author", value: "text" });
+
+//  setting a number
+cm.setProperty({ id: "./", property: "author", value: 3 });
+
+     */
+    setProperty({ id, property, propertyId, value, }: {
+        id: string;
+        property: string;
+        propertyId?: string;
+        value: PrimitiveType | EntityReference;
+    }): boolean | undefined;
+    /**
+     * Update a property on an entity
+     *
+     * @param {Object} options
+     * @param {string} options.id - the id of the entity to add the property to
+     * @param {string} options.property - the property to add
+     * @param {string} options.idx - the idx of the property array to update
+     * @param {string} options.value - the data to add to that property, string or object with '@id'
+     * @example
+
+const cm = new CrateManager({ crate })
+cm.updateProperty({ id: "./", property: "@id", value: "something else" });
+cm.updateProperty({ id: "./", property: "author", idx: 1, value: "new" });
+
+     */
+    updateProperty({ id, property, idx, value, }: {
+        id: string;
+        property: string;
+        idx?: number;
+        value: PrimitiveType | PrimitiveType[] | EntityReference;
+    }): NormalisedEntityDefinition | undefined | string;
+    /**
+     * Delete a specific property from the entity. That is, an instance of a property.
+     *
+     * @param {Object}
+     * @param {string} options.id - the id of the entity to remove the property value from
+     * @param {string} options.property - the property
+     * @param {string} options.idx - the idx of the property array to delete
+     * @example
+
+const cm = new CrateManager({ crate })
+cm.deleteProperty({ id: "./", property: "author", idx: 1 });
+
+     */
+    deleteProperty({ id, property, idx }: {
+        id: string;
+        property: string;
+        idx?: number;
+    }): void;
+    /**
+     * Ingest and link a nested json object
+     *
+     * @param {Object} options
+     * @param {string} options.id - the id of the entity to join the data into
+     * @param {string} options.property - the property to join the data into
+     * @param {string} options.propertyId - the propertyId of the property - ie the url to the definition
+     * @param {json} options.json - the data object to join in
+     * @example
+
+const cm = new CrateManager({ crate })
+let json = {
+    ...,
+}
+cm.ingestAndLink({
+    id: "./",
+    property: "language",
+    json,
+});
+
+     */
+    ingestAndLink({ id, property, propertyId, json, }: {
+        id: string | undefined;
+        property: string | undefined;
+        propertyId: string | undefined;
+        json: UnverifiedEntityDefinition;
+    }): void;
+    /**
+     * Flatten a nested json object to an array
+     *
+     * @param {Object} json - a potentially nested data blob to flatten into array
+     * @returns an array of objects
+     * @example
+
+const cm = new CrateManager({ crate })
+let json = {
+    ...,
+}
+let arrayOfObjects = cm.flatten(json)
+
+     */
+    flatten(json: UnverifiedEntityDefinition): NormalisedEntityDefinition[];
+    /**
+     * Link two entities
+     *
+     * Link two entities via a property. If there is a profile defined
+     *      and it has reverse associations, then they will be added.
+     *
+     * @param {Object} options
+     * @param {string} options.id - the id of the entity to add the association to
+     * @param {string} options.property - the property to add the association to
+     * @param {string} options.propertyId - the propertyId of the property - ie the url to the definition
+     * @param {object} options.value - an object with '@id' defining the association to create
+     * @example
+
+const cm = new CrateManager({ crate })
+cm.linkEntity({ id: './', property: 'author', value: { '@id': '#e1' }})
+
+     **/
+    linkEntity({ id, property, propertyId, value, }: {
+        id: string;
+        property: string;
+        propertyId?: string;
+        value: {
+            "@id": string;
+        };
+    }): void;
+    /**
+     * Unlink two entities
+     *
+     * Remove an association between two entities. If there is a profile defined
+     *      and it has reverse associations, then they will be removed as well.
+     *
+     * @param {Object} options
+     * @param {string} options.id - the id of the entity to remove the association from
+     * @param {string} options.property - the property containing the association
+     * @param {object} options.value - an object with '@id' defining the association to remove
+     * @example
+
+const cm = new CrateManager({ crate })
+const cm = new CrateManager({ crate })
+cm.unlinkEntity({ id: './', property: 'author', value: { '@id': '#e1' }})
+
+     **/
+    unlinkEntity({ id, property, value, stop, }: {
+        id: string | undefined;
+        property: string | undefined;
+        value: {
+            "@id": string;
+        } | undefined;
+        stop?: boolean;
+    }): void;
+    /**
+     * Purge unlinked entities from the crate
+     *
+     * Clean up the graph and purge any unlinked entities including disconnected subtrees.
+     * @example
+
+const cm = new CrateManager({ crate })
+cm.purgeUnlinkedEntities()
+
+     */
+    purgeUnlinkedEntities(): void;
+    /**
+     * Export the RO-Crate
+     * @returns the complete ro-crate
+     * @example
+
+const cm = new CrateManager({ crate })
+let crate = cm.exportCrate()
+
+     */
+    exportCrate(): NormalisedCrate;
+    /**
+     * exportEntityTemplate
+     *
+     * Export an entity as a template to be reused.
+     *  1. If resolveDepth = 0 then the entity is returned with all associations removed
+     *  2. If resolveDepth = 1 then the entity is returned with one level of associations populated but
+     *    all of their associations will be removed.
+     *
+     * @param {Object} options
+     * @param {String} options.id - the id of the entity to export as a template
+     * @param {String} options.resolveDepth - 0 or 1. If 1, linked entities will be joined in
+     *
+     * @returns entity
+     * @example
+
+const cm = new CrateManager({ crate })
+let entity = cm.exportEntityTemplate({ id: '#person' })
+let entity = cm.exportEntityTemplate({ id: '#person', resolveDepth: 1 })
+
+     */
+    exportEntityTemplate({ id, resolveDepth, }: {
+        id: string;
+        resolveDepth?: number;
+    }): NormalisedEntityDefinition;
+    /**
+     * getErrors
+     *
+     * @returns { errors }
+     *
+     */
+    getErrors(): errorsInterface;
+    /**
+     * getWarnings
+     *
+     * @returns { warnings }
+     */
+    getWarnings(): warningsInterface;
+    __updateContext({ name, id }: {
+        name: string;
+        id?: string;
+    }): void;
+    /**
+     * Normalise context
+     *
+     * Collapse all objects into a single object
+     *
+     * @param {*} context
+     * @returns context
+     */
+    __normaliseContext(context: UnverifiedContext): NormalisedContext;
+    __storeEntityType(entity: NormalisedEntityDefinition): void;
+    __removeEntityType(entity: NormalisedEntityDefinition): void;
+    __collectAllDefinitions(context: NormalisedContext): {
+        [key: string]: boolean;
+    };
+    __setError(error: keyof typeof this.errors, entity: string | UnverifiedEntityDefinition): void;
+    __setWarning(warning: keyof typeof this.warnings, entity: string | UnverifiedEntityDefinition): void;
+    __materialiseEntity({ id }: {
+        id: string;
+    }): NormalisedEntityDefinition;
+    __confirmNoClash({ entity, mintNewId, }: {
+        entity: NormalisedEntityDefinition;
+        mintNewId?: boolean;
+    }): NormalisedEntityDefinition | boolean;
+    __updateEntityId({ oldId, newId }: {
+        oldId: string;
+        newId: string;
+    }): NormalisedEntityDefinition | undefined;
+    __addReverse({ id, property, value, }: {
+        id: string;
+        property: string;
+        value: EntityReference;
+    }): void;
+    __removeAssociations(entity: NormalisedEntityDefinition): NormalisedEntityDefinition;
+}
+export {};

package/dist/crate-builder/CrateManager/crate-manager.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/crate-builder/CrateManager/lib.d.ts

@@ -0,0 +1,26 @@
+import { UnverifiedEntityDefinition, NormalisedEntityDefinition } from '../types.js';
+export declare const urlProtocols: string[];
+/**
+ *
+ * @param {string} value - string to check as a URL: checks 'http','https','ftp', 'arcp'
+ */
+export declare function isURL(value: string | number | boolean | undefined | null): boolean;
+/**
+ *  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 declare function normalise(entity: UnverifiedEntityDefinition, i: number): NormalisedEntityDefinition;
+export declare function normaliseEntityType({ entity }: {
+    entity: UnverifiedEntityDefinition;
+}): string[];
+/**
+ *
+ * Mint an empty RO-Crate that conforms to the spec
+ *
+ * @returns a skeleton crate ready to be used
+ */
+export declare function mintNewCrate(): {};

package/dist/crate-builder/CrateManager/lib.spec.d.ts

@@ -0,0 +1 @@
+export {};