mythix-orm 1.8.2 → 1.10.2

package/lib/types/virtual/models-type.js

@@ -125,7 +125,7 @@ const TYPE_OPERATIONS = {
   'get': function({ field, type }, userQuery, options, ...args) {
     const doGet = async function*() {
       let query                       = await type.prepareQuery({ connection: null, self: this, field, options }, [ userQuery ].concat(args));
-      let results                     = query.all(Object.assign({}, options, { stream: true }));
+      let results                     = query.cursor(options);
       let primaryModelRelationalArray = [];
 
       this[field.fieldName] = primaryModelRelationalArray;
@@ -239,6 +239,124 @@ const TYPE_OPERATIONS = {
   },
 };
 
+/// A "virtual" field `type` that defines a one to many,
+/// or many to many relationship with other model(s).
+///
+/// Many to many relationships interact with "sets", which in
+/// Mythix ORM is the term used to define an "array of models",
+/// in our N to many relationship.
+///
+/// Relationships (also known as "associations") in Mythix ORM
+/// are defined by virtual fields that return a "relationship query"
+/// from a method known as a "query generator" that is defined along
+/// with the type definition.
+/// This "relationship query" itself defines the model relationship, no matter
+/// how complicated. Other ORMs require that you define relationships
+/// via their "through table", matching foreign key, type, etc...
+/// In Mythix ORM, everything is simply defined as a query for the
+/// relationship.
+///
+/// This field `type` can be used to define a virtual field
+/// that defines a relationship to other models. When your
+/// model is instantiated into an instance, then this type will
+/// inject the following methods into your model instance to
+/// assist you in interacting with the relationship set. The "injected methods"
+/// listed below are "prefixes". The full names of these methods are
+/// always postfixed with the actual name of your field that defines
+/// the relationship. For example, if you had a `roles` field
+/// that defined this type of relationship, then the methods injected
+/// would be `model.getRoles`, `model.destroyRoles`, `model.pluckRoles`, etc...
+/// | Injected Method Prefix | Full Method Name | Signature | Description |
+/// | ---------------------- | ---------------- | ----------- | --------- |
+/// | `addTo` | `addTo${fieldName}` | `addTo(models: Array<Model \| object>, options?: object): Promise<Array<Model>>` | Create the models defined by the relationship, and add them to the set. Returns the newly created models. |
+/// | `count` | `count${fieldName}` | `count(userQuery?: QueryEngine, options?: object, ...args: Array<any>): Promise<number>` | Count the number of models in the set. |
+/// | `destroy` | `destroy${fieldName}` | `destroy(options?: object, ...args: Array<any>): Promise<number>` | Destroy the models defined by the relationship set. Returns the number of models destroyed. Note that this not only destroys the target models, but also any through-table relationships involved. |
+/// | `get` | `get${fieldName}` | `get(userQuery?: QueryEngine, options?: object, ...args: Array<any>): Promise<Array<Model>>` | Get the models specified by the relationship set. Return the entire model set. |
+/// | `has` | `has${fieldName}` | `has(userQuery?: QueryEngine, options?: object, ...args: Array<any>): Promise<boolean>` | Check if the relationship set contains any models. |
+/// | `pluck` | `pluck${fieldName}` | `pluck(userQuery?: QueryEngine, fields: Field \| string \| Array<Field \| string>, options?: object, ...args: Array<any>): Promise<Array<any>>` | Pluck specific fields from the related models (set). |
+/// | `queryFor` | `queryFor${fieldName}` | `queryFor(userQuery?: QueryEngine, options?: object, ...args: Array<any>): Promise<QueryEngine>` | Get the raw relationship query defined by this field type (returned by the "query generator"). |
+/// | `removeFrom` | `removeFrom${fieldName}` | `removeFrom(models: Array<Model>, options?: object): Promise<number>` | Remove the specified models from the relationship set without destroying the target models (destroy only the through-table linking models). Returns the number of models remaining in the set after the operation. |
+/// | `set` | `set${fieldName}` | `set(models: Array<Model \| object>, options?: object): Promise<Array<Model>>` | Overwrite the model set with the models specified, destroying models outside the specified set of models. Returns the new models. |
+///
+/// The `...args` provided for each injected method are pass-through args for the user, that allow
+/// the user to pass any arguments they desire to the "relational query generator" method defined
+/// by the field (the `...userArgs` as seen in the example below). One minor exception to this is
+/// any method that has a `userQuery` argument. The `userQuery` argument will always also be passed as the
+/// first argument to the `...userArgs` of the "query generator" method. The `userQuery` argument
+/// is to allow the user to define an extra query to merge into the primary/root query of the relationship.
+/// For example, in the example provided below, we could call `await user.getRoles(Role.where.name.EQ('admin'))`
+/// to only get the related roles where each role also has a `name` attribute with the value `'admin'`.
+///
+/// This type also injects duplicates of each of these relational methods with an underscore prefix, i.e.
+/// `_getRoles`. These are known as "root methods". They are provided so the user can overload the
+/// default implementations. For example, you could define a `getRoles` method on your model class,
+/// and from that call the "super" method simply by calling `this._getRoles`. This is required because
+/// with method injection `super` doesn't actually exist, because the method was injected, instead of being
+/// defined on the model class's prototype.
+///
+/// Example:
+///   class User extends Model {
+///     static fields = {
+///       ...,
+///       // Add a virtual relationship field, which creates a
+///       // one to many relationship with the Role model.
+///       //
+///       // Notice how a "type" can always be used directly as
+///       // the field definition, instead of defining an object
+///       // with a "type" property.
+///       roles: Types.Models(
+///         // Specify the target/root model.
+///         'Role',
+///         // Define our "query generator" method that
+///         // will return our "relationship query".
+///         (context, connectionModels, ...userArgs) => {
+///           // Get the model we need from the connection,
+///           // which is conveniently passed to us as the
+///           // `connectionModels` argument here.
+///           let { Role } = connectionModels;
+///
+///           // Get the "self", which is the model instance
+///           // calling this method
+///           // (i.e. with `model.getRoles()`, "self" would be "model")
+///           let { self } = context;
+///
+///           // Now return a relationship query
+///           return Role.where
+///             .userID
+///               .EQ(self.id)
+///             .AND
+///             .MERGE(userArgs[0]); // Apply the `userQuery` (will do nothing if nullish)
+///          },
+///        ),
+///      };
+///    }
+///
+///    // ... later on
+///    // get the "roles" for the first user in the database
+///    let user = await User.first();
+///    // Call relationship method injected by the `Types.Models` type.
+///    let allUserRoles = await user.getRoles();
+///
+/// Note:
+///   See the [Associations](./Associations) article for a more in-depth discussion
+///   of Mythix ORM model relationship/associations.
+///
+/// Note:
+///   The "query generator" method defined with the type can be an asynchronous method.
+///
+/// Note:
+///   Relational methods **will not** be injected into the model instance if a method of
+///   the same name already exists on the model instance. For example, if you define a
+///   `getRoles` method on your model class, then the default `get` relational method
+///   (`getRoles` in our example) won't be injected. However, the "root method" `_getRoles`
+///   will still be injected, allowing you to call that as the `super` method instead.
+///
+/// Note:
+///   This field type will not be "exposed" to models. This means that your model will not
+///   have an attribute with the name provided by the field defining this type. The only
+///   thing that will exist on your model will be the relational methods injected by this type.
+///   Said another way, and using the examples provided, there will be no "roles" attribute
+///   on your `User` model.
 class ModelsType extends RelationalTypeBase {
   static exposeToModel() {
     return false;
@@ -248,6 +366,23 @@ class ModelsType extends RelationalTypeBase {
     return true;
   }
 
+  /// Internal method used to generate injected method names.
+  ///
+  /// This method likely should never be called by the user.
+  /// It is used to generate the injected method names.
+  ///
+  /// Return: string
+  ///   The method name to inject into the model instance.
+  ///
+  /// Arguments:
+  ///   field: <see>Field</see>
+  ///     The parent field defining this relationship.
+  ///   operation: string
+  ///     The operation being injected into the model instance, which is one of
+  ///     the prefixes listed above, i.e. `addTo`, `get`, `destroy`, etc...
+  ///   rootMethod: boolean
+  ///     If `true`, then return a generated "root method" name, instead of a "user method".
+  ///     The only difference is that the "root method" name is prefixed with an underscore `_`.
   fieldNameToOperationName(field, operation, rootMethod) {
     let fieldName = field.pluralName;
     if (!fieldName)
@@ -259,6 +394,18 @@ class ModelsType extends RelationalTypeBase {
       return `${operation}${fieldName}`;
   }
 
+  /// Inject type methods into the model instance.
+  ///
+  /// The <see>Type.initialize</see> method is always called
+  /// for each model that is instantiated. For this type, this
+  /// is used to inject the relational methods into the model
+  /// instance.
+  ///
+  /// Arguments:
+  ///   connection: <see>Connection</see>
+  ///     The connection for the model being instantiated.
+  ///   self: <see>Model</see>
+  ///     The model instance the type is being initialized for.
   initialize(connection, self) {
     return super.initialize(connection, self, TYPE_OPERATIONS);
   }

package/lib/types/virtual/relational-type-base.js

@@ -17,16 +17,6 @@ class RelationalTypeBase extends Type {
     return true;
   }
 
-  // Model types work by specifying a "target"
-  // and a "value provider" (source).
-  // These are fully qualified names, meaning
-  // they also point to the model as well as the field.
-  // If no model is specified, then it always defaults to
-  // "this" model. If no field is specified, then it always
-  // defaults to "this PK" of the model.
-  // Mythix ORM will recursively walk all models and fields
-  // defined until it has the full relationships between
-  // all fields.
   constructor(_targetModelName, queryFactory, _options) {
     let options = _options || {};
 
@@ -180,7 +170,7 @@ class RelationalTypeBase extends Type {
     let PrimaryModel      = (context.self && context.self.getModel());
     let primaryModelName  = PrimaryModel.getModelName();
     let query             = await this.prepareQuery(Object.assign({ connection }, context), args);
-    let queryParts        = query._getRawQuery();
+    let queryParts        = query.getOperationStack();
     let queryContext      = (queryParts[queryParts.length - 1] || {});
     let TargetModel       = queryContext.rootModel;
     let TargetField       = queryContext.rootField;
@@ -196,7 +186,7 @@ class RelationalTypeBase extends Type {
       let rightQueryContext = null;
 
       if (QueryEngine.isQuery(conditionValue)) {
-        rightQueryContext = conditionValue._getRawQueryContext();
+        rightQueryContext = conditionValue.getOperationContext();
         if (rightQueryContext.condition)
           continue;
       } else {

package/lib/utils/model-utils.js

@@ -1,3 +1,5 @@
+///! DocScope: ModelUtils
+
 'use strict';
 
 const Nife  = require('nife');
@@ -7,10 +9,53 @@ function isUUID(value) {
   return UUID.validate(value);
 }
 
-function sanitizeFieldString(str) {
-  return ('' + str).replace(/[^\w:.]+/g, '').replace(/([:.])+/g, '$1');
+function sanitizeFieldString(_str) {
+  let str = (typeof _str === 'symbol') ? (_str.toString()) : (_str + '');
+  return str.replace(/[^\w:.]+/g, '').replace(/([:.])+/g, '$1');
 }
 
+/// Parse a fully qualified field name.
+///
+/// A fully qualified field name is a field name that
+/// is prefixed by its parent model. For example,
+/// `'User:email'` is a fully qualified field name,
+/// whereas just `'email'` is not.
+///
+/// This method will actually parse both formats however.
+/// It will parse fully qualified field names, and short-hand
+/// field names (just the field name). If just a field name
+/// is provided with no model name prefix, then the resulting
+/// `modelName` property of the returned object will be `undefined`.
+///
+/// Field names themselves can be deeply nested. For example,
+/// `'User:metadata.ipAddress'`. Field nesting was designed into
+/// the Mythix ORM framework, and is partially supported in some
+/// areas of the framework. However, field nesting likely won't work
+/// in many places without further support being added. This feature
+/// was left in-place for now, because it will likely be expanded upon
+/// in the future.
+/// Because of this "field nesting", instead of just one field name being
+/// returned, an array of field names is *always* returned. Generally,
+/// to get the field name you are looking for you would just get the first
+/// index (`fieldNames[0]`) on the returned object.
+///
+/// This method can and will also parse just a model name, so long as the provided
+/// name starts with an upper-case letter. If no colon is found (meaning no model
+/// prefix is present), then the provided value will be assumed to be a model name
+/// only if it starts with an upper-case letter. Otherwise, it is treated as a field
+/// name, and returned in the `fieldNames` array.
+///
+/// Arguments:
+///   fieldName: string
+///     A model name, field name, or fully qualified field name to parse.
+///
+/// Return: object
+///   An object with the shape `{ modelName: string | undefined; fieldNames: Array<string> }`.
+///   The `modelName` property will contain the name of the model for the field, if it is known,
+///   which will only be the case for a fully qualified name (i.e. `'User:email'`), or a
+///   model name alone (i.e. `'User'`). `fieldNames` will always be an array of field names
+///   parsed, which will generally only be one. It can be empty if no field name was provided,
+///   for example if only a model name was provided (i.e. `'User'`).
 function parseQualifiedName(str) {
   let fieldNames = [];
   let modelName;

package/lib/utils/query-utils.js

@@ -62,11 +62,11 @@ const FILTER_OPERATORS = {
   },
   // Like
   '*':  (Model, fieldName, query, value) => {
-    return query.LIKE(value);
+    return query.AND[fieldName].LIKE(value);
   },
   // NOT Like
   '!*': (Model, fieldName, query, value) => {
-    return query.NOT_LIKE(value);
+    return query.AND[fieldName].NOT_LIKE(value);
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mythix-orm",
-  "version": "1.8.2",
+  "version": "1.10.2",
   "description": "ORM for Mythix framework",
   "main": "lib/index",
   "type": "commonjs",