Entity Querying

The real power behind Nymph is the entity querying system.

The Entity class' factory method can take a GUID as an argument. You can provide other factory functions that can take things as well. For example, the User class in Tilmeld has a factoryUsername method that takes a username. The method will return a new entity if the queried entity is not found. You can determine if it was found by checking that its GUID is not null.

const baz = await FoobarBaz.factory(guid);
if (baz.guid == null) {
  console.error("Can't find the Foobar Baz!");
}

// Tilmeld's User class has a username factory function.
const cronUser = await User.factoryUsername('cron');
if (cronUser.guid == null) {
  console.error("Can't find the cron user!");
}

The powerful way of querying entities is Nymph's getEntities and getEntity methods. The first argument is an Options object.

Every argument following the Options is a Selector object. They contain clauses and a type. An entity must match each selector to be returned. There are four selector types, and they are defined on the type property.

The other properties of the Selector are clauses. Clauses use the form name: value, or name: [value1, value2, ...]. They can be negated by prepending a bang (!) to the name, like '!name': value. A clause that has multiple values is considered as multiple clauses in terms of matching for "or" selectors.

The clauses "equal", "contain", "gt", "gte", "lt", and "lte" 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 the 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']
}

So putting it all together, you can specify the options and selectors to find the exact entities you want.

Get the first FoobarBaz entity.

const entity = await nymph.getEntity({ class: FoobarBaz });

Get the latest FoobarBaz entity.

const entity = await nymph.getEntity({
  class: FoobarBaz,
  reverse: true
});

Get all baz tagged entities, using the FoobarBaz class.

const entities = await nymph.getEntities(
  {
    class: FoobarBaz
  },
  {
    type: '&',
    tag: 'baz'
  }
);

Get the five last created bar and baz tagged entities.

const entities = await nymph.getEntities(
  {
    class: FoobarBaz,
    reverse: true,
    limit: 5
  },
  {
    type: '&',
    tag: ['bar', 'baz']
  }
);

Get the five last modified bar and baz tagged entities.

const entities = await nymph.getEntities(
  {
    class: FoobarBaz,
    reverse: true,
    limit: 5,
    sort: 'mdate'
  },
  {
    type: '&',
    tag: ['bar', 'baz']
  }
);

Get the third page of sorted by name, baz tagged entities (if pages are 5 entities long).

const entities = await nymph.getEntities(
  {
    class: FoobarBaz,
    limit: 5,
    offset: 10,
    sort: 'name'
  },
  {
    type: '&',
    tag: ['baz']
  }
);

Get baz tagged entities with names.

const entities = await nymph.getEntities(
  {
    class: FoobarBaz
  },
  {
    type: '&',
    tag: 'baz',
    defined: 'name'
  }
);

Get baz tagged entities without names.

const entities = await nymph.getEntities(
  {
    class: FoobarBaz
  },
  {
    type: '&',
    tag: 'baz',
    '!defined': 'name'
  }
);

Get baz tagged entities without names or bar tagged entities with names.

const entities = await nymph.getEntities(
  {
    class: FoobarBaz
  },
  {
    type: '|',
    selector: [
      {
        type: '&',
        tag: 'baz',
        '!defined': 'name'
      },
      {
        type: '&',
        tag: 'bar',
        defined: 'name'
      }
    ]
  }
);

Get baz tagged entities with either first names or last names.

const entities = await nymph.getEntities(
  {
    class: FoobarBaz
  },
  {
    type: '&',
    tag: 'baz'
  },
  {
    type: '|',
    defined: ['firstName', 'lastName']
  }
);

Get baz tagged entities created in the last day.

const entities = await nymph.getEntities(
  {
    class: FoobarBaz
  },
  {
    type: '&',
    tag: 'baz',
    gt: ['cdate', null, '-1 day']
  }
);

Get baz tagged entities with names, who either make only up to 8 dollars pay or are under 22.

const entities = await nymph.getEntities(
  {
    class: FoobarBaz
  },
  { type: '&', tag: 'baz', defined: 'name' },
  {
    type: '!|', // at least one must be false
    gte: ['age', 22],
    gt: ['pay', 8]
  }
);

Get baz tagged entities named Clark, James, Chris, Christopher, Jake, or Jacob.

const entities = await nymph.getEntities(
  { class: FoobarBaz },
  { type: '&', tag: 'baz' },
  {
    type: '|',
    equal: [
      ['firstName', 'Clark'],
      ['firstName', 'James']
    ],
    match: [
      ['firstName', '^Chris(topher)?$'],
      ['firstName', '^Ja(ke|cob)$']
    ]
  }
);

Get baz tagged entities that belong to any user named "John" or "James".

const entities = await nymph.getEntities(
  { class: FoobarBaz },
  {
    type: '&',
    tag: 'baz',
    qref: [
      'user',
      [
        { class: User },
        {
          type: '|',
          like: [
            ['name', 'John %'],
            ['name', 'James %']
          ]
        }
      ]
    ]
  }
);