Initialize Nymph.
The Nymph configuration.
The Nymph database driver.
Optionaltilmeld: TilmeldInterfaceThe Tilmeld user/group manager instance, if you want to use it.
Optionalparent: NymphUsed internally by Nymph. Don't set this.
The Nymph config.
The Nymph database driver.
The entity class for this instance of Nymph.
The Nymph instance that this one was cloned from, or null if it's not a clone.
OptionaltilmeldAn optional Tilmeld user/group manager instance.
Add your class to this instance.
This will create a class that extends your class within this instance of Nymph and return it. You can then use this class's constructor and methods, which will use this instance of Nymph.
Because this creates a subclass, don't use the class
returned from getEntityClass to check with instanceof.
Add an index on a specific property to an etype.
Nymph adds general indexes on etypes, but they span across all properties, so they can only speed up a query so much. You can add indexes that are specific to a property with this function, which will speed up queries for that property. If an etype only has one or two properties, you may not need a specific index, but if your etypes include many properties or properties that generally contain large amounts of data, adding a specific index can drastically improve the performance of your queries.
The scope of the index will affect which queries it will speed up:
The name must be unique within the etype and scope or the existing index will be overwritten.
You do not need to add reference indexes for the "user" and "group" properties, because these are already specifically indexed by Nymph.
The etype to add the index on.
The definition of the index.
Get a clone of this instance with cloned classes and event listeners.
A clone of this instance.
Commit the named transaction.
After this is called, the transaction instance should be discarded.
True on success, false on failure.
Connect to the database.
Whether the instance is connected to the database.
Delete an entity from the database.
The entity.
True on success, false on failure.
Delete an entity from the database by its GUID.
The entity's GUID.
OptionalclassName: stringThe entity's class name.
True on success, false on failure.
Delete an index from an etype.
The etype to delete the index on.
The scope of the index.
The name of the index to delete.
Delete a unique ID.
The UID's name.
True on success, false on failure.
Disconnect from the database.
Whether the instance is connected to the database.
Export entities to a local file.
This is the file format:
#nex2
# The above line must be the first thing in the file.
# Comments begin with #
# And can have white space before them.
# This defines a UID.
<name/of/uid>[5]
<another uid>[8000]
# For UIDs, the name is in angle brackets (<>) and the value follows
# in square brackets ([]).
# This starts a new entity.
{1234abcd}<etype>[tag,list,with,commas]
# For entities, the GUID is in curly brackets ({}), then the etype in
# angle brackets, then the comma separated tag list follows in square
# brackets ([]).
# Properties are stored like this:
# propname=JSON.stringify(value)
abilities=["system/admin"]
groups=[]
inheritAbilities=false
name="admin"
# White space before/after "=" and at beginning/end of line is ignored.
username = "admin"
{2}<etype>[tag,list]
another="This is another entity."
newline="\n"
The file to export to.
True on success, false on failure.
Export entities to the console.
True on success, false on failure.
Get an array of entities.
options is an object, which contains any of the following settings:
If a class is specified, it must have a factory() static method that returns a new instance.
Selectors are objects. Any amount of selectors can be provided. Empty
selectors will be ignored. The type property of a selector is required
and can be one of the following strings:
The rest of the properties in the selectors are called selector clauses, which can be any of the following (in the form selector.name = value, or selector.name = [value1, value2,...]):
These clauses can all be negated, by prefixing them with an exclamation point, such as "!truthy" to mean falsy (or undefined).
Any clause that accepts an array of name and value can also accept a third element. If value is null and the third element is a string, the third element will be used with Locutus' strtotime function to set value to a relative timestamp. For example, the following selector will look for all entities that were created in the last day:
{
type: '&',
gte: ['cdate', null, '-1 day']
}
Locutus' implementation: https://locutus.io/php/datetime/strtotime/ PHP's documentation: https://www.php.net/manual/en/function.strtotime.php
This example will retrieve the last two entities where:
const entities = Nymph.getEntities(
{ class: Entity, reverse: true, limit: 2 },
{
type: '&', // all must be true
tag: 'person',
defined: 'spouse',
equal: [
['gender', 'male'],
['lname', 'Smith']
],
'!equal': ['warnings', 0]
},
{
type: '|', // at least one of the selectors in this must match
selector: [
{
type: '&',
tag: ['level1', 'level2']
},
{
type: '&',
tag: ['access1', 'access2']
}
]
},
{
type: '|', // at least one must be true
tag: ['employee', 'manager']
},
{
type: '|',
equal: [
['name', 'Clark'],
['name', 'James']
],
match: [
['name', 'Chris(topher)?'],
['name', 'Ja(ke|cob)']
]
},
{
type: '!|', // at least one must be false
gte: ['age', 22],
gt: ['pay', 8]
}
);
An array of entities or guids, or a count.
Get an array of entities.
options is an object, which contains any of the following settings:
If a class is specified, it must have a factory() static method that returns a new instance.
Selectors are objects. Any amount of selectors can be provided. Empty
selectors will be ignored. The type property of a selector is required
and can be one of the following strings:
The rest of the properties in the selectors are called selector clauses, which can be any of the following (in the form selector.name = value, or selector.name = [value1, value2,...]):
These clauses can all be negated, by prefixing them with an exclamation point, such as "!truthy" to mean falsy (or undefined).
Any clause that accepts an array of name and value can also accept a third element. If value is null and the third element is a string, the third element will be used with Locutus' strtotime function to set value to a relative timestamp. For example, the following selector will look for all entities that were created in the last day:
{
type: '&',
gte: ['cdate', null, '-1 day']
}
Locutus' implementation: https://locutus.io/php/datetime/strtotime/ PHP's documentation: https://www.php.net/manual/en/function.strtotime.php
This example will retrieve the last two entities where:
const entities = Nymph.getEntities(
{ class: Entity, reverse: true, limit: 2 },
{
type: '&', // all must be true
tag: 'person',
defined: 'spouse',
equal: [
['gender', 'male'],
['lname', 'Smith']
],
'!equal': ['warnings', 0]
},
{
type: '|', // at least one of the selectors in this must match
selector: [
{
type: '&',
tag: ['level1', 'level2']
},
{
type: '&',
tag: ['access1', 'access2']
}
]
},
{
type: '|', // at least one must be true
tag: ['employee', 'manager']
},
{
type: '|',
equal: [
['name', 'Clark'],
['name', 'James']
],
match: [
['name', 'Chris(topher)?'],
['name', 'Ja(ke|cob)']
]
},
{
type: '!|', // at least one must be false
gte: ['age', 22],
gt: ['pay', 8]
}
);
An array of entities or guids, or a count.
Get an array of entities.
options is an object, which contains any of the following settings:
If a class is specified, it must have a factory() static method that returns a new instance.
Selectors are objects. Any amount of selectors can be provided. Empty
selectors will be ignored. The type property of a selector is required
and can be one of the following strings:
The rest of the properties in the selectors are called selector clauses, which can be any of the following (in the form selector.name = value, or selector.name = [value1, value2,...]):
These clauses can all be negated, by prefixing them with an exclamation point, such as "!truthy" to mean falsy (or undefined).
Any clause that accepts an array of name and value can also accept a third element. If value is null and the third element is a string, the third element will be used with Locutus' strtotime function to set value to a relative timestamp. For example, the following selector will look for all entities that were created in the last day:
{
type: '&',
gte: ['cdate', null, '-1 day']
}
Locutus' implementation: https://locutus.io/php/datetime/strtotime/ PHP's documentation: https://www.php.net/manual/en/function.strtotime.php
This example will retrieve the last two entities where:
const entities = Nymph.getEntities(
{ class: Entity, reverse: true, limit: 2 },
{
type: '&', // all must be true
tag: 'person',
defined: 'spouse',
equal: [
['gender', 'male'],
['lname', 'Smith']
],
'!equal': ['warnings', 0]
},
{
type: '|', // at least one of the selectors in this must match
selector: [
{
type: '&',
tag: ['level1', 'level2']
},
{
type: '&',
tag: ['access1', 'access2']
}
]
},
{
type: '|', // at least one must be true
tag: ['employee', 'manager']
},
{
type: '|',
equal: [
['name', 'Clark'],
['name', 'James']
],
match: [
['name', 'Chris(topher)?'],
['name', 'Ja(ke|cob)']
]
},
{
type: '!|', // at least one must be false
gte: ['age', 22],
gt: ['pay', 8]
}
);
An array of entities or guids, or a count.
Get an array of entities.
options is an object, which contains any of the following settings:
If a class is specified, it must have a factory() static method that returns a new instance.
Selectors are objects. Any amount of selectors can be provided. Empty
selectors will be ignored. The type property of a selector is required
and can be one of the following strings:
The rest of the properties in the selectors are called selector clauses, which can be any of the following (in the form selector.name = value, or selector.name = [value1, value2,...]):
These clauses can all be negated, by prefixing them with an exclamation point, such as "!truthy" to mean falsy (or undefined).
Any clause that accepts an array of name and value can also accept a third element. If value is null and the third element is a string, the third element will be used with Locutus' strtotime function to set value to a relative timestamp. For example, the following selector will look for all entities that were created in the last day:
{
type: '&',
gte: ['cdate', null, '-1 day']
}
Locutus' implementation: https://locutus.io/php/datetime/strtotime/ PHP's documentation: https://www.php.net/manual/en/function.strtotime.php
This example will retrieve the last two entities where:
const entities = Nymph.getEntities(
{ class: Entity, reverse: true, limit: 2 },
{
type: '&', // all must be true
tag: 'person',
defined: 'spouse',
equal: [
['gender', 'male'],
['lname', 'Smith']
],
'!equal': ['warnings', 0]
},
{
type: '|', // at least one of the selectors in this must match
selector: [
{
type: '&',
tag: ['level1', 'level2']
},
{
type: '&',
tag: ['access1', 'access2']
}
]
},
{
type: '|', // at least one must be true
tag: ['employee', 'manager']
},
{
type: '|',
equal: [
['name', 'Clark'],
['name', 'James']
],
match: [
['name', 'Chris(topher)?'],
['name', 'Ja(ke|cob)']
]
},
{
type: '!|', // at least one must be false
gte: ['age', 22],
gt: ['pay', 8]
}
);
An array of entities or guids, or a count.
Get the first entity to match all options/selectors.
options and selectors are the same as in getEntities().
This function is equivalent to setting options.limit to 1 for getEntities(), except that it will return null if no entity is found. getEntities() would return an empty array.
An entity or guid, or null on failure or nothing found, or a number.
Get the first entity to match all options/selectors.
options and selectors are the same as in getEntities().
This function is equivalent to setting options.limit to 1 for getEntities(), except that it will return null if no entity is found. getEntities() would return an empty array.
An entity or guid, or null on failure or nothing found, or a number.
Get the first entity to match all options/selectors.
options and selectors are the same as in getEntities().
This function is equivalent to setting options.limit to 1 for getEntities(), except that it will return null if no entity is found. getEntities() would return an empty array.
An entity or guid, or null on failure or nothing found, or a number.
Get the first entity to match all options/selectors.
options and selectors are the same as in getEntities().
This function is equivalent to setting options.limit to 1 for getEntities(), except that it will return null if no entity is found. getEntities() would return an empty array.
An entity or guid, or null on failure or nothing found, or a number.
Get the first entity to match all options/selectors.
options and selectors are the same as in getEntities().
This function is equivalent to setting options.limit to 1 for getEntities(), except that it will return null if no entity is found. getEntities() would return an empty array.
An entity or guid, or null on failure or nothing found, or a number.
Get the first entity to match all options/selectors.
options and selectors are the same as in getEntities().
This function is equivalent to setting options.limit to 1 for getEntities(), except that it will return null if no entity is found. getEntities() would return an empty array.
An entity or guid, or null on failure or nothing found, or a number.
Get the first entity to match all options/selectors.
options and selectors are the same as in getEntities().
This function is equivalent to setting options.limit to 1 for getEntities(), except that it will return null if no entity is found. getEntities() would return an empty array.
An entity or guid, or null on failure or nothing found, or a number.
Get the class that uses the specified class name.
Get the class that uses the specified class name.
Get the class that uses the specified etype.
Note that it is fine, though unusual, for two classes to use the same etype. However, this can lead to very hard to diagnose bugs, so is generally discouraged.
Returns a list of the etypes stored in the DB.
Get all the indexes defined for a specific etype.
The etype to get indexes for.
Get the current value of a unique ID.
The UID's name.
The UID's value, or null on failure and if it doesn't exist.
Import entities from a file.
The file to import from.
True on success, false on failure.
Import a single entity.
The entity data to import.
Import a single entity's Tilmeld access control properties.
This does not update any of the other data, only the access control columns.
The entity data to import.
Import a single entity's tokens.
This does not update any of the actual data, only the tokens used for full text search.
Be careful with this function, since you can overwrite existing tokens with data that is out of sync. The DB should prevent you from inserting tokens for an entity that doesn't exist, but it won't prevent you from inserting tokens for properties that don't exist on an entity.
The entity data to import.
Check if there is any open transaction.
True if there is a transaction.
Perform a live migration on the DB.
A 'tokenTables' migration will simply add the missing token tables. It will
not fill them. You must use importEntityTokens on each entity after
running this to fill the token tables and enable full text search matching
on existing entities.
A 'tilmeldColumns' migration will simply add the missing Tilmeld columns
and indexes to each entity table. It will not fill them, and you must
fill them before updating to the latest version of Nymph, or everyone will
be able to access every entity! You must use importEntityTilmeldAC on
each entity after running this.
A 'tilmeldRemoveOldRows' migration will remove all of the old access
control rows in the data tables that are no longer used as of
1.0.0-beta.110. MAKE SURE YOU HAVE RUN importEntityTilmeldAC ON ALL
ENTITIES BEFORE RUNNING THIS, OR THE DATA WILL BE IRRETRIEVABLY LOST!
Detect whether the database needs to be migrated.
If not false (so, one of the string values), the database should be exported with an old version of Nymph, then imported into a fresh database with this version. Sometimes, a live migration can be done instead, which will require no downtime. You should still export the database beforehand, in case anything goes wrong.
'json' means the data tables are missing the JSON field, and the DB must be exported and imported to fix it.
'tokens' means the FTS token tables are missing, and you can get away with
a live migration with liveMigration('tokenTables') and doing
importEntityTokens(entity) for each entity.
'tilmeldColumns' means the entity columns for "user", "group", and access
controls are missing, and you can get away with a live migration with
liveMigration('tilmeldColumns') and doing
importEntityTilmeldAC(entity) for each entity. DO NOT update to any
version later than 1.0.0-beta.109 before this is done, or access controls
WILL NOT work, and everyone will have access to every entity!
Increment or create a unique ID and return the new value.
Unique IDs, or UIDs are similar to GUIDs, but numeric and sequential.
A UID can be used to identify an object when the GUID doesn't suffice. On a system where a new entity is created many times per second, referring to something by its GUID may be unintuitive. However, the component designer is responsible for assigning UIDs to the component's entities. Beware that if a UID is incremented for an entity, and the entity cannot be saved, there is no safe, and therefore, no recommended way to decrement the UID back to its previous value.
If newUID() is passed the name of a UID which does not exist yet, one will be created with that name, and assigned the value 1. If the UID already exists, its value will be incremented. The new value will be returned.
The UID's name.
The UID's new value, or null on failure.
Rename a unique ID.
The old name.
The new name.
True on success, false on failure.
Rollback the named transaction.
After this is called, the transaction instance should be discarded.
True on success, false on failure.
Run all the query callbacks on a query.
Save an entity to the database.
If the entity has never been saved (has no GUID), a variable "cdate" is set on it with the current Unix timestamp.
The variable "mdate" is set to the current Unix timestamp.
The entity.
True on success, false on failure.
Set the value of a UID.
The UID's name.
The value.
True on success, false on failure.
Start an atomic transaction and returns a new instance of Nymph.
All proceeding changes using this new instance will wait to be written to the database's permanent storage until commit() is called. You can also undo all the changes since this function ran with rollback().
Transactions will nest as long as every name is unique. Internally, Nymph uses names prefixed with "nymph-".
A new instance of Nymph that should be used for the transaction.
An object relational mapper for Node.js.
Written by Hunter Perrin for SciActive.
Author
Hunter Perrin [email protected]
Copyright
SciActive Inc
See
http://nymph.io/