Collection mixins Component

A lot of Collection methods take an options parameter. The options available are:

Not all options are supported by all methods. For example, findOne() uses a limit of 1 and Tyr.byUid() does not support the query option.

A population projection definition can take one of the following three forms:

• string -- the name of a field to populate.
• string[] -- an array of names of fields to populate.
• object -- object population syntax (Advanced Population syntax).

This returns 'collection'.

This is a method used by Tyranid internally to make its AJAX calls but which is also available as part of Tyranid's public API.

The API is essentially the same as jQuery's $.ajax() method which is currently used for the underlying implementation.

If the csrf option is enabled in Tyr.config(), then CSRF will be applied to all Tyr.ajax calls automatically.

This method can be used to add new auxiliary fields to an existing collection. The syntax is the same as the values provided to fields when defining a collection. For example:

User.aux({
  someClientValue: { is: 'string' }
});

This retrieves a document by its id.

This retrieves a list of documents by their ids.

The returned array is parallel to the given ids array if the parallel option is passed as in options. If the same id shows up multiple times in the input query, then the returned array will also have multiple instances, but the instances will be shared. If a given id does not exist in the database, then the corresponding entry will still be present, but it will contain null.

This retrieves the first document it finds matching the given label using a case-insensitive search.

This method can be used to manually cache a document into the local Tyranid offline cache.

This can be useful for when a document comes back from a non-Tyranid server API call and you want to inform Tyranid about the updated document.

If Tyranid already had a local copy of the document then the existing document will be updated with the new information and the existing document will be returned.

If silent is set then local events will not be fired.

If a Secure component is registered with Tyranid, this method will be used to determine if a document can be inserted into a collection relative to the authObject (usually an instance of a user document).

Most Tyranid insert and save use canInsert() internally when an auth option is used and end-users will not normally need to directly use this method.

This returns a count of the documents that match the given opts.query.

See also Counting and also exists().

This contains a reference to the underlying native MongoDB Collection instance.

This defines the structure of a collection and is the argument that is passed into the Collection constructor.

This returns true if any documents that match the given opts.query (and permission checks).

See also count().

This creates n fake documents (default is 1) for fields matching schemaOpts using the given seed.

This is a parallel hash to def.fields that contains the generated Field objects.

This method fires off an event that is bound to this collection.

MyCollection.fire({ ... });

is shorthand for:

Tyr.Event.fire({ collection: MyCollection, ... });

See Event.fire() for more information.

This returns an array of Fields that match the given filter.

For example, following returns a list of all of the fields in the User collection that are of type string.

User.fieldsBy(field => field.def.is.def.name === 'string')

This is similar to def.fields except that it returns dynamic fields defined in Dynamic Schemas.

Only one of match and query should be provided.

If

• match is given, then it should be a document that will be matched against the schema match values.
• query is given, then it should be a mongo-style query that will be executed against the schema match values for a match.

If static is specified, then all statically defined fields will also be returned -- by default only dynamic fields are returned.

If custom is specified, then only dynamic fields which have custom: true set on them will be returned.

This behaves like the native MongoDB driver's find() method with the addition that results are wrapped in this collection's document type.

This behaves like find() except that it returns an array of Documents instead of a cursor.

findAll() also supports the count option.

This behaves like native MongoDB's findOne() method except that the results are wrapped in this collection's document type. You can also just pass in a single options object and specify the query on the options object directory.

This behaves like native MongoDB's findAndModify() method except the options are passed in a single options object and the results are wrapped in this collection's document type.

This finds all the documents that link to the given id(s) in the database. This will also find any UID references.

This creates a new document instance out of a POJO. Values are copied by reference (not deep-cloned!).

If this collection has a fromClient hook registered it will be invoked. If Tyranid is itself calling fromClient() (for example, via automatically-generated client calls), it will pass in the express request object in the options objects available as options.req.

This converts a MongoDB-style query created on the client into one suitable to be used on the server. For example:

{
  isbn: {
    $in: [
      '5614c2f00000000000000000',
      '5614c2f00000000000000001'
    ]
  }
}

{
  isbn: {
    $in: [
      ObjectId('5614c2f00000000000000000'),
      ObjectId('5614c2f00000000000000001')
    ]
  }
}

This contains the 3-character ID for the collection.

IDs that start with _ are reserved for Tyranid collections and IDs that start with ~ are reserved for auxiliary collections.

This returns the label for the specified id.

This method will return an empty string if it is given a non-truthy id (i.e. if the id is not defined).

This generates a UID from an id.

This behaves like native MongoDB's insert() method but also does things like timestamps, denormalization, and so on.

If you pass in an array, then the array of documents/objects will be inserted in bulk.

This returns true if the collection's data is auxiliary (i.e. not presisted in the database). This is the opposite of isDb().

This returns true if the collection's data is stored in the database. This is the opposite of isAux().

This returns true if the collection is a singleton collection.

This returns true if the collection's data is defined statically in its def.values field. Enumerations are a common example of static collections.

This returns true if the given UID refers to a document in this collection.

This returns a label, or display name, for the collection itself.

If this collection has a field that is marked with labelField this returns the that field.

This returns the label for the specified document. If doc is a Document, then this is equivalent to doc.$label. This method is mostly useful for when you have a raw object that you want to get the label for.

If the labelField option is specified then the given field will be used as the label.

This generates a list of label objects that can be used to populate a typeahead dropdown.

Generally prefer to use Field.labels() over this as it can take advantage of the where property on link fields.

If the labelField option is specified then the given field will be used as the label.

This returns the projection needed to properly display the given label field. This includes any labelImageField value, dependent fields of the label is a computed field, and so on.

If no labelField name is provided then the default label for the projection is used.

This generates a list of links between this collection and other collections. By default this will find both outgoing links and incoming links from other collections to this one.

opts are:

• relate:

  Value	Notes
  'associate'	Only look at "associate" links.
  'owns'	Only look at "owns" links.
  'ownedBy'	Only look at "ownedBy" links.

• direction:

  Value	Notes
  'incoming'	Only look at incoming links.
  'outgoing'	Only look at outgoing links.

This function will migrate a collection with patch-format historical data to one with document-format historical data.

The progress parameter is a callback that will be called periodically with the number of documents that have been converted. For example:

Widget.migratePatchToDocument(count => console.log(`converted ${count} documents`))

This allows you to mixin additional metadata (like additional fields) to an existing collection. This is useful for adding additional metadata to built-in Tyranid or third-party collections. See Mixins for more information.

Lets you add an event handler on this collection. See on() for more information on this method.

This parses a path into a Path object.

See also Document.parsePath.

This is a hash of all the fields inside a collection by their path names. Paths are often more convenient to work with than recursively walking the def.fields.* structure.

Note that unlike Collection.fields which just has the top-level fields, paths contains nested fields as well.

If documents is not provided, this function will return a curried version of this function that takes a single array of documents. This allows populate to be fed into a promise chain.

See Population for more information and examples.

This method assumes that path points to an array inside the document. This method will remove all elements of the array that match the predicate function.

For example:

User.pull(myId, 'name.suffices', suffix => suffix === 'Sr');

This method will also retain historical information for historical documents.

This is a shortcut for:

However, this method will also atomically retain historical information for historical documents.

This behaves like native MongoDB's remove() method.

This finds all references in documents that link to the given id(s) in the database and removes them. This will also remove any UID references.

This method will either update or insert the object based on whether it has an _id.

When updating, the entire document is replaced. Use updateDoc() to only modify updated fields.

If a Secure component is registered with Tyranid, this method will update the query with security restrictions the secure component mandates relative to the authObject (usually an instance of a user document).

Warning: This method will return false if the query is categorically rejected so it is important that the results of this are not immediately passed into a subsequent query. You need to look at the result and if it is false short-circuit the query. See secureFindQuery().

Most Tyranid methods use secureQuery internally when an auth option is used and end-users will not normally need to directly use this method.

This method behaves like secureQuery() except that this method will not ever return a boolean. If the security component detects that a query is categorically rejected, this method will return a valid MongoDB query object that is guaranteed to fail-fast (something like { _id: null }).

This subscribes the current client to the given query. When changes that match the given query are made the client objects will be updated automatically on the client with the changes.

If the cancel parameter is passed in as true, then the given subscription will be canceled.

If cancel is true and query is undefined, then all subscriptions will be canceled.

This creates a new POJO out of a document instance. Values are copied by reference (not deep-cloned!).

opts can contain the following:

Any toClient function defined for a collection in its Collection.def will also be invoked during toClient processing. This provides a standard place where fields can be removed for security and other reasons. As with post(), this is bound to the current document inside a collection's toClient() post-processing function.

$toClient() will also invoke the Document.$redact() method on documents.

This behaves like native MongoDB's update() method. It also will update timestamps if this collection is configured to use them.

This updates the server document with the values in this object.

Note that the document is not replaced. See Collection.save() if you want to do a full replace.

If the document is new (it does not have an _id) then an exception will be thrown unless the upsert option is set to true.

This contains a list of all documents that are cached locally on a client for off-line use.

This method returns all of the unique values that appear for the given fields in the collection.