PersistentObject

PersistentObject

PersistentObject is the base class for all objects that we want to be able to persist to a JsonStore (a plain-text JSON file in which we can save, retrieve, update, and delete individual objects.)

For example, if you pass 'AppSetting' as the type param, the object you create will be stored in the AppSetting.json file in the application's data directory. (See the link to JsonStore below.)

If the underlying data store for your class does not yet exist, it will be created the first time you call save(), find(), or any other function that accesses the underlying datastore.

Constructor

new PersistentObject(opts)

Creates a new PersistentObject.

Parameters:
Name Type Description
opts object

Object containing properties to set.

Properties
Name Type Description
id string

A UUID in hex-string format. This is the object's unique identifier.
userCanDelete boolean

Indicates whether user is allowed to delete this record.

This constructor is meant to be called by the constructors in subclasses, which pass their class name as the type param.
Source:
See:
  • JsonStore for more about the JsonStore object.
  • Context#dataStores for info about how DART keeps track of different datastores.

Members

errors :Object.<string, string>

The errors property contains information about why this object is not valid. This property will be empty when an object is created, and is populated by the validate() method. If there are validation errors, the keys in the error object will be the names of invalid properties. The values will be error messages describing why the property is invalid. If validate() determines that the object is valid, errors will be empty.

Source:

id :string

id is this object's unique identifier, and the best handle to use when retrieving it from storage. This is a version 4 UUID in hex string format. It is set by the constructor when you create a new PersistentObject. You should not change it.

Source:

required :Array.<string>

This is a list of required properties. The DART UI won't let you save an instance of this object unless the required attributes have a value.

Source:

userCanDelete :string

userCanDelete indicates whether or not the user can delete this object from storage. The defaults to false, but you may want to set it to true for select items that are required for your plugin to work. For example, your plugin depends on the presence of a pre-installed BagIt profile or an AppSetting called 'Account Number' (or whatever), you can set this property to false and the user will not be able to delete the property.

Default Value:
  • true
Source:

Methods

(static) find(id) → {PersistentObject}

find finds the object with the specified id in the datastore and returns it. Returns undefined if the object is not in the datastore. Some more complex objects may have to override this method to correctly reconstruct the object from the hash representation.

Parameters:
Name Type Description
id string

The id (UUID) of the object you want to find.
Source:

(static) findMatching(property, value, opts) → {Array.<Object>}

findMatching returns an array of items matching the specified criteria.

Parameters:
Name Type Description
property string

The name of the property to match.
value string

The value of the property to match.
opts Object

Optional additional params.

Properties
Name Type Description
limit number

Limit to this many results.
offset number

Start results from this offset.
orderBy string

Sort the list on this property.
sortDirection string

Sort the list 'asc' (ascending) or 'desc'. Default is asc.
Source:
Examples
// Get all objects where obj.name === 'Homer'
let results = persistentObject.findMatching('name', 'Homer');
// Get the first ten objects where obj.name === 'Homer', sorted
// by createdAt, with newest first
let opts = {limit: 10, offset: 0, orderBy: 'createdAt', sortDir: 'desc'};
let results = persistentObject.findMatching('name', 'Homer', opts);

(static) first(filterFunction, opts) → {Object}

first returns the first item matching that passes the filterFunction. You can combine orderBy, sortDirection, and offset to get the second, third, etc. match for the given criteria, but note that this function only returns a single item at most (or null if there are no matches).

Parameters:
Name Type Description
filterFunction filterFunction

The name of the property to match.
opts Object

Optional additional params.

Properties
Name Type Description
orderBy string

Sort the list on this property.
sortDirection string

Sort the list 'asc' (ascending) or 'desc'. Default is asc.
offset number

Skip this many items before choosing a result.
Source:
Example
// Define a filter function
function nameAndAge(obj) {
   return obj.name === 'Homer' && obj.age > 30;
}

// Get the first matching object
let obj = persistentObject.first(nameAndAge);

// Get the newest matching object
let obj = persistentObject.first(nameAndAge,
{orderBy: 'createdAt', sortDirection: 'desc'});

// Get the second newest matching object
let obj = persistentObject.first(nameAndAge,
{orderBy: 'createdAt', sortDirection: 'desc', offset: 1});

// Get the oldest matching object
let obj = persistentObject.first(nameAndAge,
{orderBy: 'createdAt', sortDirection: 'asc'});

(static) firstMatching(property, value, opts) → {Object}

firstMatching returns the first item matching the specified criteria, or null if no item matches.

Parameters:
Name Type Description
property string

The name of the property to match.
value string

The value of the property to match.
opts Object

Optional additional params.

Properties
Name Type Description
orderBy string

Sort the list on this property.
sortDirection string

Sort the list 'asc' (ascending) or 'desc'. Default is asc.
Source:
Examples
// Get the first object where obj.name == 'Homer'
let obj = persistentObject.findMatching('name', 'Homer');
// Get the newest object where obj.name == 'Homer'
let obj = persistentObject.findMatching('name', 'Homer',
{orderBy: 'createdAt', sortDirection: 'desc'});
// Get the second newest object where obj.name == 'Homer'
let obj = persistentObject.first('name', 'Homer',
{orderBy: 'createdAt', sortDirection: 'desc', offset: 1});
// Get the oldest object where obj.name == 'Homer'
let obj = persistentObject.findMatching('name', 'Homer',
{orderBy: 'createdAt', sortDirection: 'asc'});

(static) list(filterFunction, opts) → {Array.<Object>}

list returns an array of items matched by the filter function.

Parameters:
Name Type Description
filterFunction filterFunction

The name of the property to match.
opts Object

Optional additional params.

Properties
Name Type Description
limit number

Limit to this many results.
offset number

Start results from this offset.
orderBy string

Sort the list on this property.
sortDirection string

Sort the list 'asc' (ascending) or 'desc'. Default is asc.
Source:
Examples
function nameAndAge(obj) {
   return obj.name === 'Homer' && obj.age > 30;
}
let results = persistentObject.list(nameAndAge);
// Get the first ten objects that match the filter, sorted
// by createdAt, with newest first
let opts = {limit: 10, offset: 0, orderBy: 'createdAt', sortDir: 'desc'};
let results = persistentObject.findMatching(nameAndAge, opts);

(static) mergeDefaultOpts(opts) → {Object}

mergeDefaultOpts sets missing option values to their default values. This function is meant for internal use.

Parameters:
Name Type Description
opts Object

A potentially null hash of options.
Source:

(static) sort(property, direction) → {Array.<Object>}

sort sorts all of the items in the Conf datastore (JSON text file) on the specified property in either 'asc' (ascending) or 'desc' (descending) order. This does not affect the order of the records in the file, but it returns a sorted list of objects.

Parameters:
Name Type Description
property string

The property to sort on.
direction string

Sort direction: 'asc' or 'desc'
Source:

delete() → {Object}

Delete this object from persistent storage. Returns a copy of the deleted object.

Source:

getValue(propertyName) → {string}

This returns the value of propertyName as read from the property itself or from the process's environment. This will return undefined if it tries to read an undefined environment variable.

This is used primarily by the subclasses StorageService and RemoteRepository, both of which use credentials that a user may want to store in the environment.

For most values, you'll simply want to access the property itself.

Parameters:
Name Type Description
propertyName string

The name of the property whose value you want to get.
Source:
Example
storageService.login = "user@example.com";
storageService.getValue("login");  // returns "user@example.com"

storageService.login = "env:USER";
storageService.getValue("login");  // returns the value of process.env.USER

save() → {PersistentObject}

Save this object to persistent storage. Returns the object after saving.

Source:

validate() → {boolean}

validate returns true if this object is valid, false if not. If the object is not valid, this populates the errors property with info describing what is not valid. Classes that derive from PersistentObject should have their own custom implementation of this method.

Source: